ContractGuard

Análisis de riesgos de contratos japoneses construido como un caso de estudio de ingeniería de IA: flujo de trabajo de LangGraph + RAG con pgvector + ingesta multimodal + UX de streaming recuperable.

⚠️ No es un servicio legal. Este repositorio nunca ha sido operado comercialmente: el artículo 72 de la Ley de Abogados de Japón (弁護士法第72条) reserva el asesoramiento legal remunerado para abogados con licencia. El código fuente se publica únicamente como un artefacto técnico de código abierto. Los resultados no son opiniones legales.

中文文档 | 日本語 | Licencia

Estado

Implementación de referencia de código abierto lista para producción. El stack completo — frontend, backend, OCR, pagos, correo electrónico, Postgres, Redis, seguimiento de errores — está conectado con integraciones reales y listo para desplegar. Simplemente nunca se ha lanzado, por diseño (Ley de Abogados §72).

Un contrato japonés sintético se encuentra en docs/samples/ para que el flujo local pueda probarse de principio a fin inmediatamente después de clonar.

Arquitectura

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

Stack Tecnológico

Inicio Rápido (local)

La ejecución local solo requiere una clave de API de OpenAI.

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

Luego abre http://localhost:5173 y sube docs/samples/sample-contract-ja.txt.

En este modo mínimo:

• ✅ Los contratos en texto plano y PDFs basados en texto (texto seleccionable) funcionan de principio a fin.

• ❌ El OCR de imágenes / PDFs escaneados está deshabilitado. Para habilitarlo, añade GOOGLE_APPLICATION_CREDENTIALS_JSON y GOOGLE_VISION_PROJECT_ID.

• KOMOJU / Resend se omiten automáticamente en desarrollo: sin pagos reales, sin correos electrónicos reales.

Configuración de Producción

El repositorio está diseñado para desplegarse en producción configurando APP_ENV=production y proporcionando credenciales para cada servicio externo:

Cuando APP_ENV=production, la aplicación se niega a arrancar si falta alguno de los anteriores o si FRONTEND_URL sigue apuntando a localhost. La lógica de validación estricta reside en backend/config.py (validate_runtime()).

fly.toml y vercel.json describen la topología de despliegue utilizada durante el desarrollo. El servicio no está alojado actualmente.

Flujo

1. Sube un contrato (texto, PDF o imagen). La ruta de carga ejecuta la extracción de texto, comprobaciones de PII, estimación de tokens, detección de no-contratos y límites de presupuesto de OCR.

2. La ruta de referencia de pago crea un pedido. Las credenciales de KOMOJU vacías activan una omisión local en desarrollo.

3. /review/:orderId inicia o reanuda el trabajo de análisis persistente y transmite eventos de progreso que sobreviven a la actualización de la página.

4. LangGraph analiza las cláusulas, analiza cada cláusula con llamadas a herramientas basadas en RAG y genera sugerencias solo cuando el riesgo lo justifica.

5. /report/:orderId muestra el informe guardado, extractos de cláusulas, filtros de riesgo y exportación a PDF, conservados durante 72 horas.

El texto del contrato del usuario se elimina después del análisis. El almacén de vectores contiene solo estatutos públicos de e-Gov; los contratos de los usuarios nunca se incrustan.

Demo

Mapa del Repositorio

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

• backend/agent/tools.py — Llamadas a herramientas basadas en RAG.

• backend/services/analysis_executor.py — Trabajo de análisis persistente + abastecimiento de eventos.

• backend/rag/store.py — Almacenamiento y búsqueda en pgvector.

• backend/config.py — Configuración en tiempo de ejecución y validación estricta.

• frontend/src/pages/ReviewPage.tsx — UI de progreso de análisis recuperable.

• frontend/src/pages/ReportPage.tsx — UI de informe con filtros de riesgo y exportación a PDF.

• tests/ — Suites de pytest del backend.

• scripts/smoke_local_flow.sh — Prueba de humo local de principio a fin.