ContractGuard

Анализ рисков японских договоров, созданный в качестве учебного проекта по разработке ИИ — рабочий процесс 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)]

Технологический стек

Быстрый старт (локально)

Для локального запуска требуется только ключ API OpenAI.

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

Затем откройте http://localhost:5173 и загрузите docs/samples/sample-contract-ja.txt.

В этом минимальном режиме:

• ✅ Договоры в виде обычного текста и текстовые PDF-файлы (с возможностью выделения текста) работают от начала до конца.

• ❌ OCR для изображений / сканированных PDF отключен. Чтобы включить его, добавьте 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 — пользовательский интерфейс восстановления прогресса анализа.

• frontend/src/pages/ReportPage.tsx — пользовательский интерфейс отчета с фильтрами рисков и экспортом в PDF.

• tests/ — наборы тестов pytest для бэкенда.

• scripts/smoke_local_flow.sh — сквозной локальный дымовой тест.