ContractGuard

AI 엔지니어링 사례 연구로 구축된 일본 계약 위험 분석 시스템 — LangGraph 워크플로우 + pgvector RAG + 멀티모달 수집 + 복구 가능한 스트리밍 UX.

⚠️ 법률 서비스가 아닙니다. 이 저장소는 상업적으로 운영된 적이 없으며, 일본 변호사법 제72조(弁護士法第72条)는 유료 법률 자문을 변호사 자격이 있는 사람에게만 허용합니다. 이 코드베이스는 오픈 소스 기술 아티팩트로서만 공개되었습니다. 출력물은 법률적 의견이 아닙니다.

中文文档 | 日本語 | License

상태

프로덕션 준비가 완료된 오픈 소스 참조 구현입니다. 프론트엔드, 백엔드, OCR, 결제, 이메일, Postgres, Redis, 오류 추적 등 전체 스택이 실제 통합으로 연결되어 배포 준비가 되어 있습니다. 다만, 설계상(변호사법 제72조) 실제로 출시된 적은 없습니다.

docs/samples/에 합성 일본 계약서가 포함되어 있어, 클론 직후 로컬 흐름을 처음부터 끝까지 테스트할 수 있습니다.

아키텍처

flowchart LR
  U[React/Vite UI<br/>text, PDF, image upload] --> API[FastAPI routers]
  API --> Q[Quote + PII + OCR budget guards]
  Q --> PAY[KOMOJU checkout<br/>reference implementation]
  PAY --> JOB[Persistent analysis job]
  JOB --> SSE[Recoverable SSE stream<br/>status + events + after_seq]
  JOB --> LG[LangGraph pipeline]
  LG --> P[parse_contract]
  P --> A[clause-by-clause risk analysis]
  A --> T[tool call: analyze_clause_risk]
  T --> RAG[(PostgreSQL pgvector<br/>331 Japanese legal articles)]
  A --> S[tool call: generate_suggestion<br/>medium/high risks only]
  S --> REP[report generation + translation]
  REP --> CACHE[(Redis 72h report cache)]
  REP --> DB[(PostgreSQL orders/reports/costs)]

기술 스택

빠른 시작 (로컬)

로컬 실행에는 OpenAI API 키만 있으면 됩니다.

cp .env.example .env
# Edit .env: set OPENAI_API_KEY
docker compose up --build

그 후 http://localhost:5173을 열고 docs/samples/sample-contract-ja.txt를 업로드하세요.

이 최소 모드에서:

• ✅ 일반 텍스트 계약서 및 텍스트 기반 PDF(선택 가능한 텍스트)는 처음부터 끝까지 작동합니다.

• ❌ 이미지 / 스캔된 PDF OCR은 비활성화되어 있습니다. 활성화하려면 GOOGLE_APPLICATION_CREDENTIALS_JSON 및 GOOGLE_VISION_PROJECT_ID를 추가하세요.

• 개발 환경에서는 KOMOJU / Resend가 자동 우회되므로 실제 결제나 이메일 발송은 이루어지지 않습니다.

프로덕션 설정

이 저장소는 APP_ENV=production을 설정하고 각 외부 서비스에 대한 자격 증명을 제공하여 프로덕션에 배포할 수 있도록 구성되어 있습니다:

APP_ENV=production일 때, 위 항목 중 하나라도 누락되었거나 FRONTEND_URL이 여전히 localhost를 가리키고 있으면 앱이 부팅을 거부합니다. 엄격한 유효성 검사 로직은 backend/config.py (validate_runtime())에 있습니다.

fly.toml 및 vercel.json은 개발 중에 사용된 배포 토폴로지를 설명합니다. 현재 서비스는 호스팅되고 있지 않습니다.

흐름

1. 계약서(텍스트, PDF 또는 이미지)를 업로드합니다. 업로드 경로는 텍스트 추출, PII 검사, 토큰 추정, 계약서 여부 감지 및 OCR 예산 제한을 실행합니다.

2. 체크아웃 참조 경로가 주문을 생성합니다. KOMOJU 자격 증명이 비어 있으면 개발 환경에서 로컬 우회가 트리거됩니다.

3. /review/:orderId는 지속적인 분석 작업을 시작하거나 재개하며, 페이지 새로고침 후에도 유지되는 진행 상황 이벤트를 스트리밍합니다.

4. LangGraph는 조항을 파싱하고, RAG 기반 도구 호출을 통해 각 조항을 분석하며, 위험이 있는 경우에만 제안을 생성합니다.

5. /report/:orderId는 저장된 보고서, 조항 발췌문, 위험 필터 및 PDF 내보내기를 보여주며, 72시간 동안 보관됩니다.

사용자 계약 텍스트는 분석 후 삭제됩니다. 벡터 저장소에는 공개 e-Gov 법령만 포함되어 있으며, 사용자 계약은 절대 임베딩되지 않습니다.

데모

저장소 맵

• backend/agent/graph.py — LangGraph 파이프라인.

• backend/agent/tools.py — RAG 기반 도구 호출.

• backend/services/analysis_executor.py — 지속적인 분석 작업 + 이벤트 소싱.

• backend/rag/store.py — pgvector 스토리지 및 검색.

• backend/config.py — 런타임 구성 및 엄격한 유효성 검사.

• frontend/src/pages/ReviewPage.tsx — 복구 가능한 분석 진행 상황 UI.

• frontend/src/pages/ReportPage.tsx — 위험 필터 및 PDF 내보내기가 포함된 보고서 UI.

• tests/ — 백엔드 pytest 제품군.

• scripts/smoke_local_flow.sh — 엔드 투 엔드 로컬 스모크 테스트.