govon 1.0.5__tar.gz

govon-1.0.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 umyunsang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

govon-1.0.5/PKG-INFO

@@ -0,0 +1,422 @@
+Metadata-Version: 2.4
+Name: govon
+Version: 1.0.5
+Summary: Agentic CLI shell for Korean public-sector civil complaint workflows
+Author-email: umyunsang <dbstkd5865@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/GovOn-org/GovOn
+Project-URL: Documentation, https://github.com/GovOn-org/GovOn#readme
+Project-URL: Repository, https://github.com/GovOn-org/GovOn.git
+Project-URL: Issues, https://github.com/GovOn-org/GovOn/issues
+Keywords: agentic-shell,cli,civil-complaint,korean-nlp,public-sector
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: prompt-toolkit>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.4.0; extra == "dev"
+Requires-Dist: bandit>=1.7.5; extra == "dev"
+Requires-Dist: safety>=2.3.5; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-cov>=4.1.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Provides-Extra: server
+Requires-Dist: torch>=2.8.0; extra == "server"
+Requires-Dist: transformers>=4.53.0; extra == "server"
+Requires-Dist: accelerate>=1.0.0; extra == "server"
+Requires-Dist: datasets>=2.14.0; extra == "server"
+Requires-Dist: bitsandbytes>=0.44.0; extra == "server"
+Requires-Dist: optimum>=1.13.0; extra == "server"
+Requires-Dist: autoawq>=0.2.8; extra == "server"
+Requires-Dist: peft>=0.16.0; extra == "server"
+Requires-Dist: trl>=0.15.0; extra == "server"
+Requires-Dist: vllm>=0.14.1; extra == "server"
+Requires-Dist: fastapi>=0.100.0; extra == "server"
+Requires-Dist: uvicorn>=0.23.0; extra == "server"
+Requires-Dist: pydantic>=2.0.0; extra == "server"
+Requires-Dist: rank-bm25>=0.2.2; extra == "server"
+Requires-Dist: sentence-transformers>=3.0.0; extra == "server"
+Requires-Dist: faiss-cpu>=1.7.4; extra == "server"
+Requires-Dist: langgraph==1.1.6; extra == "server"
+Requires-Dist: langgraph-checkpoint==4.0.1; extra == "server"
+Requires-Dist: langgraph-checkpoint-sqlite==3.0.3; extra == "server"
+Requires-Dist: langchain-core<2.0.0,>=1.2.0; extra == "server"
+Requires-Dist: langchain-openai>=0.3.0; extra == "server"
+Requires-Dist: pandas>=2.0.0; extra == "server"
+Requires-Dist: numpy>=1.24.0; extra == "server"
+Requires-Dist: scikit-learn>=1.3.0; extra == "server"
+Requires-Dist: tqdm>=4.66.0; extra == "server"
+Requires-Dist: python-dotenv>=1.0.0; extra == "server"
+Requires-Dist: pyyaml>=6.0.0; extra == "server"
+Provides-Extra: korean-nlp
+Requires-Dist: konlpy>=0.6.0; extra == "korean-nlp"
+Requires-Dist: mecab-python3>=1.0.6; extra == "korean-nlp"
+Provides-Extra: database
+Requires-Dist: sqlalchemy>=2.0.0; extra == "database"
+Requires-Dist: alembic>=1.12.0; extra == "database"
+Requires-Dist: psycopg2-binary>=2.9.0; extra == "database"
+Provides-Extra: all
+Requires-Dist: govon[database,dev,korean-nlp,server]; extra == "all"
+Dynamic: license-file
+
+# GovOn — Agentic CLI Shell for Korean Public Sector
+
+> **"도로 파손 민원에 대한 답변 초안을 작성해줘"** — 한마디면 AI가 법령을 찾고, 유사 사례를 조회하고, 공문서 형식의 초안을 생성합니다.
+
+GovOn은 **동아대학교 컴퓨터공학과** 현장미러형 산학연계 프로젝트로 개발된 에이전틱 CLI 셸입니다.
+지방자치단체 공무원의 민원 답변 업무를 AI 에이전트가 보조합니다.
+
+[![PyPI version](https://img.shields.io/pypi/v/govon?logo=pypi&logoColor=white)](https://pypi.org/project/govon/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/govon)](https://pypi.org/project/govon/)
+[![Docs Portal](https://img.shields.io/badge/Docs-Portal-blue?logo=readthedocs)](https://govon-org.github.io/GovOn/)
+[![Public Roadmap](https://img.shields.io/badge/Public_Roadmap-Workstreams-7C3AED)](https://github.com/GovOn-Org/GovOn/issues/402)
+[![HF Space](https://img.shields.io/badge/HF_Space-Runtime-yellow?logo=huggingface)](https://huggingface.co/spaces/umyunsang/govon-runtime)
+[![Discussion](https://img.shields.io/badge/Discussion-Community-green?logo=github)](https://github.com/GovOn-Org/GovOn/discussions/606)
+
+<!-- DORA-BADGES:START -->
+![DORA Grade](https://img.shields.io/badge/DORA-Elite-brightgreen)
+![Deploy Freq](https://img.shields.io/badge/Deploy_Freq-30%2Fweek-blue)
+![Lead Time](https://img.shields.io/badge/Lead_Time-0.4h-brightgreen)
+![CFR](https://img.shields.io/badge/CFR-29.0%2525-yellow)
+![MTTR](https://img.shields.io/badge/MTTR-0.0h-brightgreen)
+<!-- DORA-BADGES:END -->
+
+---
+
+## 핵심 특징
+
+### 1. ReAct 자율 에이전트
+
+LLM이 사용자의 의도를 이해하고 **7개 도구 중 어떤 것을 호출할지 자율적으로 판단**합니다.
+키워드 매칭이 아니라, 맥락 기반 추론으로 도구를 선택합니다.
+
+| 도구 | 역할 |
+|------|------|
+| `api_lookup` | 민원 데이터 API 조회 |
+| `issue_detector` | 주요 이슈 탐지 |
+| `stats_lookup` | 통계 데이터 조회 |
+| `keyword_analyzer` | 핵심 키워드 분석 |
+| `demographics_lookup` | 인구통계 조회 |
+| `public_admin_adapter` | 공공행정 민원 답변 생성 (civil LoRA) |
+| `legal_adapter` | 법률 해석 및 법령 인용 답변 생성 (legal LoRA) |
+
+### 2. 도메인 특화 Multi-LoRA
+
+단일 EXAONE 4.0-32B-AWQ 베이스 모델 위에 요청별로 LoRA 어댑터를 동적 전환합니다.
+
+| 어댑터 | 학습 데이터 | 용도 |
+|--------|-----------|------|
+| [**civil-adapter**](https://huggingface.co/umyunsang/govon-civil-adapter) (r16) | 74K 민원-답변 쌍 | `public_admin_adapter` tool_call 시 attach |
+| [**legal-adapter**](https://huggingface.co/siwo/govon-legal-adapter) (r16) | 270K 법률 문서 | `legal_adapter` tool_call 시 attach |
+
+### 3. Human-in-the-loop 승인 흐름
+
+AI가 도구를 실행하기 전에 사용자에게 승인을 요청합니다.
+완전 자동화가 아닌, **사람의 판단을 존중하는 반자동화**입니다.
+
+```bash
+$ govon
+GovOn Shell v1.0 — 무엇을 도와드릴까요?
+
+> 도로 파손 민원에 대한 답변 초안을 작성해줘
+
+┌─ 작업 승인 요청 ─────────────────┐
+│  유형: 답변 초안 작성              │
+│  목표: 도로 파손 민원 답변 생성     │
+│  작업:                            │
+│   • 민원 처리 근거 확인            │
+│   • 유사 사례 및 담당 부서 조회     │
+│                                   │
+│  ● 승인  ○ 거절                   │
+└───────────────────────────────────┘
+```
+
+---
+
+## 아키텍처
+
+```mermaid
+graph LR
+    subgraph Client ["사용자 터미널"]
+        CLI["govon CLI"]
+    end
+
+    subgraph HFSpace ["HF Space — A100 80GB"]
+        subgraph FastAPI ["FastAPI :7860"]
+            V4["v4 Agent\n(approval flow)"]
+            V3["v3 Agent\n(auto-execute)"]
+            CTX["6-Layer\nContext Mgmt"]
+        end
+        subgraph VLLM ["vLLM :8000"]
+            BASE["EXAONE-4.0\n32B-AWQ"]
+            LORA1["civil LoRA"]
+            LORA2["legal LoRA"]
+        end
+    end
+
+    CLI -- "HTTP/SSE" --> V4
+    CLI -- "HTTP/SSE" --> V3
+    V4 --> CTX
+    V3 --> CTX
+    V4 -- "httpx" --> BASE
+    V3 -- "httpx" --> BASE
+    BASE --- LORA1
+    BASE --- LORA2
+
+    style Client fill:#e0f2fe,stroke:#0284c7
+    style HFSpace fill:#fef3c7,stroke:#d97706
+    style FastAPI fill:#dcfce7,stroke:#16a34a
+    style VLLM fill:#fce7f3,stroke:#db2777
+```
+
+### ReAct 루프 흐름
+
+```mermaid
+graph TD
+    START([START]) --> SL[session_load\n컨텍스트 복원]
+    SL --> AGENT[agent\nLLM 자율 도구 선택]
+    AGENT -->|tool_calls 없음| END_NODE[persist + END]
+    AGENT -->|Tier 0 도구| TOOLS[tools\nToolNode 실행]
+    AGENT -->|승인 필요| APPROVAL[approval_wait\nHuman-in-the-loop]
+    APPROVAL -->|승인| TOOLS
+    APPROVAL -->|거절| AGENT
+    TOOLS --> AGENT
+
+    style SL fill:#dbeafe
+    style AGENT fill:#fef9c3
+    style TOOLS fill:#dcfce7
+    style END_NODE fill:#f3e8ff
+    style APPROVAL fill:#fee2e2
+```
+
+### 6-Layer 컨텍스트 관리
+
+장기 대화에서 토큰 오버플로를 방지하는 6단계 파이프라인:
+
+| Layer | 단계 | 메커니즘 |
+|-------|------|---------|
+| L1 | 도구 실행 | 도구 출력 3000자 head+tail 절단 |
+| L2 | LLM 호출 | 오래된 도구 결과 placeholder 교체 |
+| L3 | LLM 호출 | 역순 토큰 예산 trim (4500 토큰) |
+| L4 | LLM 호출 | 예산 초과 시 강제 제거 |
+| L5 | 세션 복원 | 룰 기반 대화 요약 |
+| L6 | 세션 복원 | 토큰 예산 영구 삭제 |
+
+---
+
+## 데이터 파이프라인
+
+```mermaid
+flowchart LR
+    subgraph Sources["공공 데이터 소스"]
+        A1["AI Hub 71852\n민원 QA 29K"]
+        A2["AI Hub 71847\n행정법 QA 37K"]
+        A3["AI Hub 71841/43/48\n민사/지재/형사 200K"]
+        A4["HF 판례\n법원 판결 85K"]
+    end
+
+    subgraph Civil["Civil Adapter"]
+        B1["parsers.py"] --> B2["train 74K"]
+        B2 --> B3["HF Hub"]
+    end
+
+    subgraph Legal["Legal Adapter"]
+        C1["build_dataset.py"] --> C2["train 270K"]
+        C2 --> C3["HF Hub"]
+    end
+
+    subgraph Training["Unsloth QLoRA"]
+        D1["EXAONE 4.0-32B\n4-bit NF4"] --> D2["LoRA r16"]
+        D2 --> D3["HF Spaces\nA100 80GB"]
+    end
+
+    A1 --> B1
+    A2 --> B1
+    A3 --> C1
+    A4 --> C1
+    B3 --> D1
+    C3 --> D1
+
+    style Sources fill:#e0f2fe,stroke:#0284c7
+    style Civil fill:#dcfce7,stroke:#16a34a
+    style Legal fill:#fce7f3,stroke:#db2777
+    style Training fill:#fef9c3,stroke:#ca8a04
+```
+
+| 데이터셋 | 건수 | HuggingFace Hub |
+|---------|------|-----------------|
+| Civil Response | 74K | [umyunsang/govon-civil-response-data](https://huggingface.co/datasets/umyunsang/govon-civil-response-data) |
+| Legal Citation | 270K | [umyunsang/govon-legal-response-data](https://huggingface.co/datasets/umyunsang/govon-legal-response-data) |
+
+---
+
+## 설치
+
+```bash
+# PyPI에서 CLI 클라이언트 설치
+pip install govon
+
+# 서버 런타임 전체 설치 (GPU 환경)
+pip install govon[server]
+```
+
+## 빠른 시작
+
+```bash
+# 1. HF Space 런타임에 직접 요청
+export GOVON_RUNTIME_URL=https://umyunsang-govon-runtime.hf.space
+
+# 2. v3 자동 실행 모드
+curl -X POST $GOVON_RUNTIME_URL/v3/agent/run \
+  -H "Content-Type: application/json" \
+  -d '{"query": "도로 파손 민원 현황 알려줘", "session_id": "demo-1", "max_iterations": 10}'
+
+# 3. v4 승인 흐름 (CLI 권장)
+pip install govon
+export GOVON_RUNTIME_URL=https://umyunsang-govon-runtime.hf.space
+govon
+```
+
+상세한 사용법은 [사용자 가이드](docs/guide/user-guide.md)를 참고하세요.
+
+---
+
+## 검증 지표
+
+### E2E 테스트: 27/27 통과
+
+| Phase | 시나리오 | 검증 대상 |
+|-------|---------|---------|
+| 1. Infrastructure | 3 | 헬스체크, 베이스 모델, vLLM 연결 |
+| 2. v2 Pipeline | 6 | 승인 흐름, 거절, 멀티턴, 동시성 |
+| 3. v3 ReAct | 10 | 직접 응답, 도구 실행, SSE 스트리밍 |
+| 4. Cross-version | 2 | v2↔v3 일관성 |
+| 5. Multi-turn | 3 | 컨텍스트 유지, 세션 격리, 3턴 워크플로우 |
+| 6. Context Mgmt | 3 | 도구 클리어링, 5턴 요약 |
+
+### DORA Elite
+
+| 지표 | 값 | 수집 방식 |
+|------|---|----------|
+| Deployment Frequency | 30/주 | main 머지 PR 수 |
+| Lead Time | 0.9h | PR 첫 커밋 → 머지 |
+| Change Failure Rate | 28.6% | hotfix/revert 비율 |
+| MTTR | 0.0h | bug 이슈 open → close |
+
+- **실시간 대시보드**: [Grafana Cloud](https://umyunsang.grafana.net/d/govon-dora/)
+- **주간 보고서**: [`metrics/reports/`](metrics/reports/)
+
+---
+
+## 문서
+
+| 문서 | 설명 |
+|------|------|
+| [사용자 가이드](docs/guide/user-guide.md) | 설치, CLI 사용법, 도구 설명 |
+| [운영 가이드](docs/guide/ops-guide.md) | 배포, 환경변수, 모니터링, 트러블슈팅 |
+| [데모 패키지](docs/demo/README.md) | 시연 시나리오 3종 + curl 재현 |
+| [프로젝트 회고](docs/retrospective.md) | v1→v4 진화, 기술적 도전, KPT |
+| [ADR](docs/adr/README.md) | Architecture Decision Records |
+| [PRD](docs/prd.md) | Product Requirements Document |
+| [WBS](docs/wbs.md) | Work Breakdown Structure |
+| [Docs Portal](https://govon-org.github.io/GovOn/) | GitHub Pages 통합 문서 |
+
+---
+
+## 프로젝트 구조
+
+```
+src/
+├── cli/                    # CLI 인터페이스
+│   ├── shell.py            # 인터랙티브 REPL
+│   ├── approval_ui.py      # Rich Panel 승인 UI
+│   ├── daemon.py           # 백그라운드 데몬
+│   └── renderer.py         # 출력 렌더러
+└── inference/              # 추론 엔진
+    ├── api_server.py       # FastAPI 서버
+    ├── session_context.py  # SQLite 세션 저장소
+    └── graph/              # LangGraph 코어
+        ├── builder.py      # v4/v3 그래프 빌더
+        ├── nodes.py        # 노드 팩토리 (5개 노드)
+        ├── state.py        # GovOnGraphState
+        ├── capabilities/   # 도구 Capability 클래스
+        └── tools/          # StructuredTool 팩토리
+```
+
+---
+
+## API 엔드포인트
+
+| 메서드 | 엔드포인트 | 용도 |
+|--------|-----------|------|
+| GET | `/health` | 헬스체크 (인증 불필요) |
+| POST | `/v2/agent/stream` | v4 에이전트 스트리밍 (승인 흐름) |
+| POST | `/v2/agent/run` | v4 에이전트 동기 실행 |
+| POST | `/v2/agent/approve` | 도구 실행 승인/거절 |
+| POST | `/v2/agent/cancel` | 실행 취소 |
+| POST | `/v3/agent/stream` | v3 에이전트 SSE 스트리밍 |
+| POST | `/v3/agent/run` | v3 에이전트 동기 실행 |
+
+---
+
+## 리소스
+
+| 자원 | 링크 |
+|------|------|
+| HF Space (Runtime) | [umyunsang/govon-runtime](https://huggingface.co/spaces/umyunsang/govon-runtime) |
+| Civil Adapter | [umyunsang/govon-civil-adapter](https://huggingface.co/umyunsang/govon-civil-adapter) |
+| Legal Adapter | [siwo/govon-legal-adapter](https://huggingface.co/siwo/govon-legal-adapter) |
+| Civil Dataset | [umyunsang/govon-civil-response-data](https://huggingface.co/datasets/umyunsang/govon-civil-response-data) |
+| Legal Dataset | [umyunsang/govon-legal-response-data](https://huggingface.co/datasets/umyunsang/govon-legal-response-data) |
+| DORA Dashboard | [Grafana Cloud](https://umyunsang.grafana.net/d/govon-dora/) |
+| Public Roadmap | [#402](https://github.com/GovOn-Org/GovOn/issues/402) |
+
+---
+
+## 개발 규칙
+
+- 브랜치 전략: GitHub Flow (`main` 단일 브랜치)
+- 모든 변경은 PR을 통해 진행
+- CI: lint(Black+isort+flake8) + test(pytest 3.10/3.11/3.12) + security + runtime-contract
+- 기여 가이드: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+---
+
+## GitHub 이슈 구조
+
+```
+#402 Public Roadmap (root)
+ ├── Workstream (🧭 라벨)
+ │    └── Task ([Task X.Y] 접두사)
+ └── Workstream
+      └── Task
+```
+
+---
+
+## 라이선스
+
+이 프로젝트는 동아대학교 현장미러형 산학연계 프로젝트의 산출물입니다.