ContractGuard

Risikoanalyse japanischer Verträge, entwickelt als KI-Engineering-Fallstudie — LangGraph-Workflow + pgvector RAG + multimodale Aufnahme + wiederherstellbare Streaming-UX.

⚠️ Kein Rechtsdienst. Dieses Repository wurde nie kommerziell betrieben — das japanische Anwaltsgesetz §72 (弁護士法第72条) behält kostenpflichtige Rechtsberatung lizenzierten Anwälten vor. Die Codebasis wird ausschließlich als Open-Source-technisches Artefakt veröffentlicht. Die Ergebnisse stellen keine Rechtsberatung dar.

中文文档 | 日本語 | License

Status

Produktionsreife Open-Source-Referenzimplementierung. Der gesamte Stack — Frontend, Backend, OCR, Zahlung, E-Mail, Postgres, Redis, Fehlerverfolgung — ist mit echten Integrationen verbunden und bereit für die Bereitstellung. Er wurde lediglich konzeptionsbedingt nie gestartet (Anwaltsgesetz §72).

Ein synthetischer japanischer Vertrag befindet sich in docs/samples/, sodass der lokale Ablauf direkt nach dem Klonen vollständig getestet werden kann.

Architektur

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)]

Tech-Stack

Schnellstart (lokal)

Für den lokalen Betrieb ist lediglich ein OpenAI API-Schlüssel erforderlich.

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

Öffnen Sie dann http://localhost:5173 und laden Sie docs/samples/sample-contract-ja.txt hoch.

In diesem Minimalmodus:

• ✅ Klartextverträge und textbasierte PDFs (auswählbarer Text) funktionieren vollständig.

• ❌ Bild- / gescannte PDF-OCR ist deaktiviert. Um sie zu aktivieren, fügen Sie GOOGLE_APPLICATION_CREDENTIALS_JSON und GOOGLE_VISION_PROJECT_ID hinzu.

• KOMOJU / Resend werden in der Entwicklung automatisch umgangen — keine echte Zahlung, keine echte E-Mail.

Produktionseinrichtung

Das Repository ist so konzipiert, dass es durch das Setzen von APP_ENV=production und die Bereitstellung von Anmeldeinformationen für jeden externen Dienst in die Produktion überführt werden kann:

Wenn APP_ENV=production gesetzt ist, verweigert die App den Start, falls eine der oben genannten Variablen fehlt oder FRONTEND_URL noch auf localhost zeigt. Die strikte Validierungslogik befindet sich in backend/config.py (validate_runtime()).

fly.toml und vercel.json beschreiben die während der Entwicklung verwendete Bereitstellungstopologie. Der Dienst wird derzeit nicht gehostet.

Ablauf

1. Laden Sie einen Vertrag hoch (Text, PDF oder Bild). Die Upload-Route führt Textextraktion, PII-Prüfungen, Token-Schätzung, Nicht-Vertragserkennung und OCR-Budget-Schutzmaßnahmen durch.

2. Der Checkout-Referenzpfad erstellt eine Bestellung. Leere KOMOJU-Anmeldeinformationen lösen in der Entwicklung eine lokale Umgehung aus.

3. /review/:orderId startet oder setzt den persistenten Analyseauftrag fort und streamt Fortschrittsereignisse, die einen Seiten-Refresh überstehen.

4. LangGraph analysiert Klauseln, analysiert jede Klausel mit RAG-gestützten Tool-Aufrufen und generiert Vorschläge nur dort, wo das Risiko dies rechtfertigt.

5. /report/:orderId zeigt den gespeicherten Bericht, Klauselauszüge, Risikofilter und PDF-Export an — gespeichert für 72 Stunden.

Der Vertragstext des Benutzers wird nach der Analyse gelöscht. Der Vektorspeicher enthält nur öffentliche e-Gov-Gesetze; Benutzerverträge werden niemals eingebettet.

Demo

Repository-Karte

• backend/agent/graph.py — LangGraph-Pipeline.

• backend/agent/tools.py — RAG-gestützte Tool-Aufrufe.

• backend/services/analysis_executor.py — persistenter Analyseauftrag + Event-Sourcing.

• backend/rag/store.py — pgvector-Speicher und Suche.

• backend/config.py — Laufzeitkonfiguration und strikte Validierung.

• frontend/src/pages/ReviewPage.tsx — UI für wiederherstellbaren Analysefortschritt.

• frontend/src/pages/ReportPage.tsx — Bericht-UI mit Risikofiltern und PDF-Export.

• tests/ — Backend-pytest-Suiten.

• scripts/smoke_local_flow.sh — End-to-End lokaler Smoke-Test.