diff --git a/README.md b/README.md index 789a4da..521a4ea 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # FOWOCO AI

+ AI CI AI Deploy

@@ -25,6 +26,31 @@ E-9 외국인근로자를 고용한 사업장의 재계약·체류기간 연장 환경변수를 설정하지 않은 선택 기능은 Stub 또는 명시적인 `503`으로 동작합니다. 따라서 “코드가 존재함”과 “실제 Provider가 활성화됨”을 구분해 확인해야 합니다. +## 왜 이렇게 설계했나요? + +| 선택 | 프로젝트에서 필요했던 이유 | +| --- | --- | +| BERT → Guardrail → A.X | 반복적인 단일 Intent는 빠르게 처리하고, 경계·복합 발화만 더 큰 모델로 보완하기 위해서입니다. | +| PLAN → ANALYZE 분리 | AI가 DB를 직접 조회하지 않고 필요한 field key만 요청한 뒤, Server가 권한을 검사해 Context를 보충하기 위해서입니다. | +| LangGraph 상태 흐름 | 누락 정보, OCR, 근로자 안내, 문서 생성 분기를 코드와 테스트에서 명시적으로 추적하기 위해서입니다. | +| 결정론적 문서 Tool | LLM이 HWP/HWPX 구조를 임의로 수정하지 않고 승인된 템플릿과 field map만 사용하게 하기 위해서입니다. | +| Human-in-the-loop | 번역·OCR·문서 결과가 불확실하면 자동 발송하지 않고 HR 검토 상태로 되돌리기 위해서입니다. | + +## 5분 코드 투어 + +심사·리뷰 시 아래 순서로 보면 전체 구현을 가장 빠르게 확인할 수 있습니다. + +| 순서 | 확인할 내용 | 대표 코드·테스트 | +| --- | --- | --- | +| 1 | FastAPI 진입점과 API 경계 | [`app/main.py`](app/main.py), [`app/api/router.py`](app/api/router.py), [`tests/api`](tests/api) | +| 2 | PLAN·ANALYZE와 Intent 결정 재사용 | [`app/agents/pipeline.py`](app/agents/pipeline.py), [`app/agents/intent`](app/agents/intent), [`tests/agents/test_intent_hybrid.py`](tests/agents/test_intent_hybrid.py) | +| 3 | Renewal Agent 상태·분기 | [`app/agents/workflow_graph/graph.py`](app/agents/workflow_graph/graph.py), [`app/agents/workflow_graph/supervisor.py`](app/agents/workflow_graph/supervisor.py), [`tests/agents/test_workflow_graph.py`](tests/agents/test_workflow_graph.py) | +| 4 | Tool 구현과 실패 격리 | [`app/ocr`](app/ocr), [`app/agents/language`](app/agents/language), [`app/documents`](app/documents) | +| 5 | Server–AI 계약과 대표 응답 | [`docs/analyses-contract.md`](docs/analyses-contract.md), [`docs/workflows-contract.md`](docs/workflows-contract.md), [`examples`](examples) | + +설계와 코드 관계를 더 자세히 보려면 [Architecture & Code Tour](docs/architecture.md), +문서 전체 분류는 [Documentation Index](docs/README.md)를 확인합니다. + ## 저장소 경계 FOWOCO는 모델이 업무 시스템을 직접 조작하지 않도록 저장소별 책임을 분리합니다. @@ -205,6 +231,8 @@ docker compose up --build # AI + Qdrant | 찾는 내용 | 문서 | | --- | --- | +| 문서 전체 탐색 | [Documentation Index](docs/README.md) | +| 아키텍처와 코드 위치 | [Architecture & Code Tour](docs/architecture.md) | | Server 연결과 인증 | [AI Runtime Handshake](docs/ai-runtime-handshake.md) | | PLAN·ANALYZE 계약 | [Analyses Contract](docs/analyses-contract.md) | | Renewal Agent 계약 | [Workflows Contract](docs/workflows-contract.md) | diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7ebf4e8 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,55 @@ +# FOWOCO AI Documentation + +이 디렉터리는 현재 실행 계약, 운영 가이드, 구현 과정 기록을 보존합니다. +처음 저장소를 보는 심사위원과 개발자는 아래 추천 순서부터 확인하면 됩니다. + +## 추천 읽기 순서 + +1. [저장소 README](../README.md) — 프로젝트 목표와 전체 기능 +2. [Architecture & Code Tour](architecture.md) — 설계 선택과 실제 코드 위치 +3. [Analyses Contract](analyses-contract.md) — PLAN·ANALYZE 요청·응답 +4. [Workflows Contract](workflows-contract.md) — Renewal Agent 실행 계약 +5. [AI Runtime Handshake](ai-runtime-handshake.md) — Server 연결과 인증 + +## 현재 계약 + +아래 문서는 현재 Server·AI 연동의 기준입니다. + +| 범위 | 문서 | +| --- | --- | +| PLAN·ANALYZE | [analyses-contract.md](analyses-contract.md) | +| Renewal 실행 | [workflows-contract.md](workflows-contract.md) | +| Slot 재보충 | [slot-refill-contract.md](slot-refill-contract.md) | +| Language Assistant JSON Schema | [contracts](contracts) | +| 요청·응답 예시 | [`../examples/analyses`](../examples/analyses), [`../examples/workflows`](../examples/workflows) | + +## Provider·운영 가이드 + +| 범위 | 문서 | +| --- | --- | +| Server–AI 인증과 연결 | [ai-runtime-handshake.md](ai-runtime-handshake.md) | +| Language Assistant 설정·장애 처리 | [language-assistant-operations.md](language-assistant-operations.md) | +| CLOVA OCR 계약 | [clova-ocr-integration.md](clova-ocr-integration.md) | +| HWP·HWPX 변환 검증 | [document-conversion-poc.md](document-conversion-poc.md) | +| Language 품질 기준 | [evaluations/language-assistant-baseline.md](evaluations/language-assistant-baseline.md) | + +## 모듈별 상세 문서 + +| 모듈 | 문서 | +| --- | --- | +| HTTP API | [`../app/api/README.md`](../app/api/README.md) | +| Renewal Agent | [`../app/agents/workflow_graph/README.md`](../app/agents/workflow_graph/README.md) | +| Language Assistant | [`../app/agents/language/README.md`](../app/agents/language/README.md) | +| 문서 처리 | [`../app/documents/README.md`](../app/documents/README.md) | +| HWPX MCP | [`../hwp-editor/README.md`](../hwp-editor/README.md) | + +## 구현 과정 기록 + +다음 디렉터리는 설계·작업·검증 과정을 재현하기 위한 기록입니다. 현재 API 계약을 +확인할 때는 위의 **현재 계약** 문서를 우선합니다. + +- [`language-assistant/engineering`](language-assistant/engineering) — Language Assistant 설계, 작업, 검증 Evidence +- [`superpowers`](superpowers) — OCR·문서 자동화 설계와 구현 계획 + +과거 기록은 삭제하지 않습니다. 다만 현재 동작과 충돌할 경우 실행 코드, 테스트, +현재 계약 문서 순으로 판단합니다. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..9ad88c2 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,109 @@ +# Architecture & Code Tour + +FOWOCO AI는 모델이 업무 DB를 직접 조작하는 자율 실행기가 아니라, Server가 제공한 +검증된 Context 안에서 판단과 Tool 실행 결과를 반환하는 내부 Runtime입니다. + +## 전체 경계 + +```mermaid +flowchart LR + C["Client\nHR 입력·검토"] --> S["Server\n인증·tenant·업무 상태"] + S -->|"PLAN: 원문"| A["AI Runtime\nIntent·Workflow 판단"] + A -->|"requestedFieldKeys"| S + S -->|"ANALYZE: 허용된 Context"| A + A --> G["Renewal LangGraph"] + G --> O["OCR Tool"] + G --> L["Language Tool"] + G --> D["HWP/HWPX Tool"] + O --> G + L --> G + D --> G + G -->|"구조화 결과·검토 상태"| S + S -->|"HR 승인 후 반영"| C +``` + +AI가 소유하는 것은 Prompt, 모델 라우팅, Agent 분기, Tool 조합입니다. 사용자 권한, +사업장 격리, Task 전이, 공식 파일, 감사로그는 Server가 소유합니다. + +## 실행 파이프라인 + +### 1. PLAN — 업무와 필요한 Context 결정 + +- 진입: [`app/api/routes/analyses.py`](../app/api/routes/analyses.py) +- 조합: [`app/api/dependencies.py`](../app/api/dependencies.py) +- 실행: [`app/agents/pipeline.py`](../app/agents/pipeline.py) +- Intent: [`app/agents/intent`](../app/agents/intent) + +PLAN은 `detectedIntent`, canonical `workflowId`, `requestedFieldKeys`를 반환합니다. +Worker·Company 값을 직접 조회하지 않습니다. + +### 2. ANALYZE — Server Context로 질문·Candidate 생성 + +Server는 PLAN 결정을 저장하고 권한이 확인된 값만 보충합니다. ANALYZE는 +`plannedIntent`, `plannedWorkflowId`를 재사용하므로 Intent 모델을 다시 호출하지 않습니다. + +- 질문 판단: [`app/agents/ambiguity`](../app/agents/ambiguity) +- Workflow Candidate: [`app/agents/workflow`](../app/agents/workflow) +- 계약 Fixture: [`examples/analyses`](../examples/analyses) + +### 3. Renewal — 명시적 상태 기반 분기 + +- 그래프: [`app/agents/workflow_graph/graph.py`](../app/agents/workflow_graph/graph.py) +- 상태: [`app/agents/workflow_graph/state.py`](../app/agents/workflow_graph/state.py) +- Supervisor: [`app/agents/workflow_graph/supervisor.py`](../app/agents/workflow_graph/supervisor.py) +- Node 동작: [`app/agents/workflow_graph/nodes`](../app/agents/workflow_graph/nodes) + +```mermaid +stateDiagram-v2 + [*] --> LoadContext + LoadContext --> Supervisor + Supervisor --> AskHR: HR 입력 부족 + Supervisor --> Guide: 근로자 서류 부족 + Guide --> AskWorker + Supervisor --> OCR: 검토할 신분서류 + OCR --> Generate + Supervisor --> Generate: 필수정보 충족 + Supervisor --> OutOfScope: 지원 범위 아님 + AskHR --> [*] + AskWorker --> [*] + Generate --> [*] + OutOfScope --> [*] +``` + +## Tool과 Agent 판단 구분 + +| 구분 | 코드 | 특징 | +| --- | --- | --- | +| Intent Agent | [`app/agents/intent`](../app/agents/intent) | BERT·Guardrail·A.X 결과를 공통 계약으로 변환 | +| Renewal Agent | [`app/agents/workflow_graph`](../app/agents/workflow_graph) | Slot·서류 상태를 보고 다음 분기 제안 | +| OCR Tool | [`app/ocr`](../app/ocr) | CLOVA 응답을 허용된 문서 필드로 정규화 | +| Language Tool | [`app/agents/language`](../app/agents/language) | 표준·쉬운 한국어와 대상 언어 초안 생성·검증 | +| Document Tool | [`app/documents`](../app/documents) | 템플릿과 field map을 사용한 결정론적 생성·변환 | +| HWPX MCP | [`hwp-editor`](../hwp-editor) | HWPX 구조 분석, 승인 편집, 무결성·시각 검증 | + +OCR·문서 Tool은 정해진 입력을 처리합니다. 어떤 Tool을 호출할지와 추가 정보가 +필요한지는 Agent가 제안합니다. 결과를 실제 업무에 반영할지는 Server와 HR이 결정합니다. + +## 실패 시 정책 + +| 상황 | AI 응답 | Server 동작 | +| --- | --- | --- | +| Intent 모델 비활성 | Stub 또는 readiness 비가용 상태 | 데모·운영 설정을 구분 | +| Worker Context 부족 | `CONTEXT_REQUIRED` 또는 `NEEDS_INFO` | 허용된 field만 조회하거나 HR 질문 | +| 번역 실패·검토 필요 | `guideReviewRequired=true`, `workerRequestMessage=null` | 자동 발송 금지, HR 직접 검토 | +| OCR 낮은 신뢰도 | 필드별 confidence와 검토 사유 | HR 승인 전 Worker 정보 미반영 | +| 문서 Provider 실패 | 생성 실패 상태와 오류 코드 | 파일·Task 자동 완료 금지 | + +## 검증 코드 + +| 검증 관점 | 위치 | +| --- | --- | +| API·인증 계약 | [`tests/api`](../tests/api) | +| PLAN·ANALYZE Fixture | [`tests/contracts`](../tests/contracts) | +| Intent·Workflow Agent | [`tests/agents`](../tests/agents) | +| OCR 정규화·Provider 격리 | [`tests/ocr`](../tests/ocr) | +| HWP·HWPX 생성·변환 | [`tests/documents`](../tests/documents) | +| Qdrant·모델 선택 통합 | [`tests/integration`](../tests/integration) | + +기본 CI는 외부 Secret 없이 결정론적 테스트를 실행하고, Qdrant와 Windows OCR 계약을 +별도 Job으로 분리합니다. 실제 Provider 품질은 환경별 Smoke Test로 별도 확인합니다.