📜 Diia Hakaton - AI Contract Bot

Інтелектуальний асистент для автоматизованого створення юридичних договорів. Система дозволяє користувачам створювати договори через зручний веб-інтерфейс або у режимі діалогу з AI-асистентом, який допомагає заповнити необхідні дані.

✨ Основні можливості

• 🤖 AI-асистент: Допомога у заповненні договорів через чат-інтерфейс (NLP).
• 📄 Генерація документів: Автоматичне створення .docx файлів на основі шаблонів.
• 👥 Багатокористувацький режим: Спільне редагування договору різними сторонами (Орендар/Орендодавець тощо).
• 🔄 Синхронізація в реальному часі: Оновлення полів договору для всіх учасників через SSE (Server-Sent Events).
• 🔗 Запрошення контрагента: Копіювання лінку виду /?session_id=...&role=lessee для підключення іншої сторони до конкретної ролі.
• 📱 Адаптивний інтерфейс: Зручне використання на мобільних та десктопних пристроях.
• 👁️ Попередній перегляд: Перегляд згенерованого договору перед фіналізацією.

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

Backend

• Python 3.10+
• FastAPI: REST API + SSE для стрімінгу подій.
• Pydantic: Валідація даних.
• python-docx / mammoth: Робота з документами Word.
• LiteLLM: Інтеграція з AI моделями (OpenAI, Anthropic тощо).
• Redis (опціонально): Зберігання сесій.

Frontend

• React: SPA додаток.
• Vite: Збірка проекту.
• Axios: Взаємодія з API.

🚀 Встановлення та запуск

Попередні вимоги

• Python 3.10+
• Node.js 18+
• Docker (опціонально)

1. Налаштування оточення

Скопіюйте .env.example → .env і відредагуйте значення під ваше оточення. Основні змінні:

• ENV=dev|prod — профіль. Dev працює зі SQLite/пам’яттю, prod очікує Redis + MySQL.
• SESSION_BACKEND=redis|memory|fs, REDIS_URL=redis://...
• DRAFT_TTL_HOURS, FILLED_TTL_HOURS, SIGNED_TTL_DAYS — TTL для чернеток/заповнених/підписаних сесій.
• CONTRACTS_DB_URL — DSN MySQL через pymysql; якщо порожньо, використовується SQLite.
• CONTRACTS_FS_FALLBACK — тимчасовий читання старих JSON, за замовчуванням false.
• AUTH_MODE=auto|jwt|header + AUTH_JWT_SECRET — ввімкнути перевірку Bearer JWT; у dev можна залишити X-User-ID.
• LLM_MODEL / LLM_API_KEY — якщо використовуєте AI-чат.

Рекомендації за профілями

• Dev: залиште CONTRACTS_DB_URL порожнім (SQLite), SESSION_BACKEND=redis без REDIS_URL працюватиме в in-memory режимі для швидкого старту.
• Prod: можна взяти приклад із .env.prod.example — ENV=prod, AUTH_MODE=jwt, AUTH_JWT_SECRET, REDIS_URL, CONTRACTS_DB_URL=mysql+pymysql://..., CONTRACTS_FS_FALLBACK=false.

Структура Session (коротко)

• creator_user_id: хто створив сесію (не робить його автоматично учасником).
• role_owners: мапа роль → user_id (єдине джерело прав).
• party_types, party_fields, contract_fields: статуси полів (без значень).
• all_data: значення полів (role.field або field для контрактних).
• history: глобальний масив подій:
  • field_update: {ts, type, key, user_id, role, value, normalized, valid, source}
  • sign: {ts, type, user_id, roles, state}
• signatures, state, filling_mode, progress, updated_at.
• TTL за стейтом: чернетки — draft_ttl_hours, заповнені — filled_ttl_hours, підписані — signed_ttl_days.
• Контракти: основне сховище через репозиторій (CONTRACTS_DB_URL для MySQL, інакше SQLite). Файловий JSON залишено лише як опційний fallback через CONTRACTS_FS_FALLBACK.

🔑 ACL та ролі

• Роль закріплюється тільки через POST /sessions/{id}/party-context з автентифікованим user_id (Bearer JWT або X-User-ID у dev).
• 1 user_id → максимум 1 роль у сесії. Повторний claim іншої ролі блокується.
• У режимі full ініціатор може префілити сторони, доки ролі вільні; після claim редагувати може лише власник ролі.
• Умови договору редагують учасники з роллю; якщо ролі ще не зайняті — може редагувати creator_user_id.
• history одна глобальна (події field_update/sign) зі штампами user_id/role.

🔌 Інтеграція з Дією / JWT

• AUTH_MODE=jwt — prod-режим: user_id береться лише з Bearer токена, X-User-ID ігнорується.
• Валідація токена: алгоритм AUTH_JWT_ALGO, опційно AUTH_JWT_ISSUER/AUTH_JWT_AUDIENCE.
• Внутрішній user_id будується як AUTH_USER_PREFIX + <sub> (префікс за замовчуванням diia:). Усі ACL/історія/контракти прив'язані до цього ID.
• Ендпоінт /me/profile повертає user_id + розібрані клейми профілю (якщо токен надано).
• Див. docs/diia_integration.md для деталей (клейми, мапінг, як підшивати токен у фронт/SSE).

2. Запуск Backend

# Встановлення залежностей
pip install -r requirements.txt

# Запуск сервера
python launcher.py
# Або через uvicorn напряму:
# uvicorn backend.api.http.server:app --reload

Сервер буде доступний за адресою: http://localhost:8000 Документація API: http://localhost:8000/docs

MySQL для контрактів

• Docker Compose містить сервіс contracts-db (MySQL 8). Для локальної розробки достатньо docker-compose up — БД підніметься автоматично.
• URL підключення можна одразу прописати в .env:
  CONTRACTS_DB_URL=mysql+pymysql://contracts:contracts@contracts-db:3306/contracts_db
• Якщо раніше контракти зберігались у JSON (assets/meta_data/meta_data_users/documents/*.json), виконайте міграцію в репозиторій:

  python tools/migrate_contracts_to_db.py
  # або переглянути список без запису:
  python tools/migrate_contracts_to_db.py --dry-run

• Файловий fallback вимкнено за замовчуванням. Якщо потрібен тимчасовий режим читання зі старих JSON, виставіть CONTRACTS_FS_FALLBACK=true і планово вимкніть після міграції.

3. Запуск Frontend

cd frontend

# Встановлення залежностей
npm install

# Запуск у режимі розробки
npm run dev

Фронтенд буде доступний за адресою: http://localhost:5173

🐳 Запуск через Docker

docker-compose up --build

📁 Структура проєкту

.
├── assets/                 # Шаблони документів та метадані
│   ├── documents_files/    # DOCX шаблони
│   └── meta_data/          # JSON конфігурації категорій та ролей
├── backend/                # Backend Source Code
│   ├── api/http            # FastAPI додаток та роути
│   ├── api/tool_adapter    # Адаптер для LLM tools
│   ├── agent/              # Логіка AI агента та інструменти
│   ├── domain/             # Бізнес-логіка (sessions, documents, templates, categories, validation)
│   ├── infra/              # Зберігання/конфіг (fs, redis, settings, persistence)
│   └── shared/             # Спільні утиліти/enum/логування
├── frontend/               # React Frontend додаток
├── scripts/                # Міграції/демо
├── tools/                  # CLI та перевірки (manage_content.py, verify_*.py)
├── tests/                  # Pytest
└── launcher.py             # Скрипт запуску

🔧 CLI Інструменти

Проєкт має вбудовані CLI інструменти для розробників:

Чат у терміналі (для тестування AI):

python launcher.py --test

Управління контентом (додавання категорій/шаблонів):

# Додати нову категорію
python tools/manage_content.py add-category --id auto_lease --label "Оренда авто"

# Додати шаблон
python tools/manage_content.py add-template --category auto_lease --id std_auto --name "Стандартний договір"

🔒 Безпека

• PII Sanitization: Персональні дані (паспорт, ІПН тощо) маскуються перед відправкою в LLM.
• Session Access: У проді використовуйте Bearer JWT (AUTH_MODE=jwt + AUTH_JWT_SECRET), у dev дозволений X-User-ID як fallback.
• Аудит: усі 401/403 логуються, історія сесії містить user_id/role для підписів і змін полів.

---

Розроблено для Diia Hakaton 🇺🇦