🎯 ODRA-Outcome-Driven RAG Auditor

🚀 Повнофункціональна система аудиту документів з AI-аналізом у реальному часі

📖 Документація • 🚀 Швидкий старт • 🏗️ Архітектура • 📝 API • 🤝 Контрибьют

✨ Ключові можливості

📤 Завантаження документів Групова обробка файлів Підтримка PDF, TXT, JSON Асинхронна обробка Прогрес у реальному часі	🔍 Семантичний пошук Векторні вбудовування (embeddings) Пошук по змісту Кешування результатів AI-аналіз документів
🏛️ Audit Jobs Створення та управління аудитами Відстеження прогресу в реальному часі Детальні метрики якості Автоматичні звіти з рекомендаціями	💬 Human Feedback Loop Зворотний зв'язок від користувачів Поліпшення моделі на льоту Статистика зворотного зв'язку Навчання з людської взаємодії
📊 Аналітика & Звіти Детальні звіти аудиту Метрики точності та повноти Експорт результатів Візуалізація прогресу	🔐 Безпека API Key аутентифікація CORS захист SQL-injection перевірка Валідація Pydantic

🏗️ Архітектура

┌─────────────────────────────────────────────────────────────┐
│          🎨 Frontend (React + TypeScript)                   │
│        📍 http://localhost:5173                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ 📤 Upload │ 📋 Jobs │ 📊 Reports │ 💬 Feedback      │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│         ⚙️ Backend API (FastAPI)                            │
│        📍 http://localhost:8000                             │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Health │ Ingest │ Audit │ Feedback │ Reports        │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
        ↓                        ↓                        ↓
  ┌──────────┐           ┌──────────────┐         ┌──────────┐
  │ 🗄️ SQLite │           │ 🎯 Services  │         │ 🚀 Workers │
  │ Database  │           │              │         │            │
  └──────────┘           │ - Embeddings  │         │ Processing │
                          │ - Ingest      │         │ Pool       │
                          │ - Auditor     │         │            │
                          │ - Task Queue  │         │ (Async)    │
                          └──────────────┘         └──────────┘

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

Компонент	Технологія	Версія
Backend Framework	FastAPI	Latest
Database	SQLite / PostgreSQL	3.11+
ORM	SQLAlchemy	2.0+
Frontend	React + TypeScript	18
Build Tool	Vite	Latest
Styling	Tailwind CSS	3+
Embeddings	Mock (для тестів)	-
LLM	Anthropic Claude / Mock	3-haiku
PDF Parser	PyPDF2	3.0.1
Async	AsyncIO + Semaphore	Python 3.11+
Task Queue	Redis/Celery	Optional

🚀 Швидкий старт

📋 Вимоги

Docker та Docker Compose (рекомендовано)
Або Python 3.11+ та Node.js 18+ для локального запуску

⚡ Встановлення

🐳 Варіант А: Docker (Рекомендовано)

1. Клонування репозиторію

git clone https://github.com/Nazickj2023/ODRA
cd ODRA

2. Налаштування змінних оточення (опційно)

cp .env.example .env
# Відредагуйте .env для налаштування API ключів

3. Запуск системи

docker-compose up -d

4. Доступ до системи

🌐 Web UI: http://localhost:5173
📚 API Docs: http://localhost:8000/docs
📖 ReDoc: http://localhost:8000/redoc

Корисні команди Docker:

# Перегляд логів
docker-compose logs -f

# Зупинка системи
docker-compose down

# Перезбірка після змін
docker-compose build
docker-compose up -d

# Очистка БД
docker-compose exec backend python -c "from app.db import SessionLocal, Document, AuditJob; db = SessionLocal(); db.query(Document).delete(); db.query(AuditJob).delete(); db.commit(); print('Cleaned')"

💻 Варіант Б: Локальний запуск

1. Клонування та налаштування

git clone https://github.com/Nazickj2023/ODRA
cd ODRA

# Активація віртуального оточення
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# або для Windows:
# .venv\Scripts\activate

# Встановлення залежностей
pip install -r backend/requirements.txt
cd frontend && npm install && cd ..

2. Ініціалізація БД

python init_db.py

3. Запуск компонентів

Terminal 1 - Backend:

cd backend
python -m uvicorn app.main:app --reload --port 8000

Terminal 2 - Frontend:

cd frontend
npm run dev

Terminal 3 - Worker (опційно):

python workers/processor.py

4. Доступ до системи

🌐 Web UI: http://localhost:5173
📚 API Docs: http://localhost:8000/docs

📝 API Посилання

🏥 Health & Status

GET /health
# Повертає: {status, database, embeddings, task_queue, timestamp}

📤 Document Ingestion

POST /ingest/batch
Headers: X-API-Key: dev-key-change-in-production
Body: form-data з файлами
Response: {total_files, queued, results[]}

GET /ingest/status/{task_id}
Response: {task_id, status, progress, error}

🏛️ Audit Operations

POST /audit/run
Headers: X-API-Key: dev-key-change-in-production
Body: {"goal": "...", "scope": "...", "priority": 9}
Response: {job_id, status, created_at}

GET /audit/status/{job_id}
Response: {job_id, status, progress_percent, metrics}

GET /audit/report/{job_id}
Response: {job_id, goal, evidence[], summary, recommendations}

POST /audit/feedback/{job_id}
Headers: X-API-Key: dev-key-change-in-production
Body: {"doc_id": "...", "feedback": "relevant", "comment": "..."}
Response: {status, updated_at}

📚 Все API методи

Метод	Endpoint	Опис
`GET`	`/health`	Перевірка здоров'я системи
`POST`	`/ingest/batch`	Загрузка документів
`GET`	`/ingest/status/{task_id}`	Статус завантаження
`POST`	`/audit/run`	Запуск аудиту
`GET`	`/audit/status/{job_id}`	Статус аудиту
`GET`	`/audit/report/{job_id}`	Отримання звіту
`POST`	`/audit/feedback/{job_id}`	Надання зворотного зв'язку

🧪 Тестування

Запуск інтеграційних тестів

python test_integration.py

Запуск тестів компонентів

python test_all_components.py

Запуск тестів worker'а

python test_worker_local.py

Перевірка статусу системи

./CHECK_SYSTEM.sh

curl приклади

1. Health Check:

curl http://localhost:8000/health | jq .

2. Загрузка документа:

echo "Financial Report Q1 2024
Total Revenue: 5000000
Total Expenses: 3000000" > test_doc.txt

curl -X POST http://localhost:8000/ingest/batch \
  -H "X-API-Key: dev-key-change-in-production" \
  -F "files=@test_doc.txt"

3. Запуск аудиту:

curl -X POST http://localhost:8000/audit/run \
  -H "X-API-Key: dev-key-change-in-production" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Перевірити точність фінансових даних",
    "scope": "finance",
    "priority": 9
  }'

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

ODRA/
├── 📦 backend/
│   ├── app/
│   │   ├── main.py              # FastAPI додаток
│   │   ├── config.py            # Налаштування
│   │   ├── db.py                # Конфігурація БД
│   │   ├── models.py            # Pydantic моделі
│   │   ├── security.py          # Аутентифікація
│   │   ├── api/                 # API маршрути
│   │   └── services/            # Бізнес-логіка
│   ├── tests/                   # Тести
│   └── requirements.txt
│
├── 🎨 frontend/
│   ├── src/
│   │   ├── pages/               # Сторінки
│   │   ├── components/          # React компоненти
│   │   ├── api/                 # API клієнт
│   │   └── App.tsx
│   ├── package.json
│   └── vite.config.ts
│
├── 🚀 workers/
│   └── processor.py             # Фоновий обробник
│
├── 📊 clickhouse/               # ClickHouse схема
├── 📝 scripts/                  # Утиліти
├── 🧪 тести
├── 🐳 docker-compose.yml
└── 📄 README.md

⚙️ Конфігурація

Змінні оточення

Створіть .env файл у кореневій папці:

# API
API_KEY=your-secure-key-here
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Database
DATABASE_URL=sqlite:///./odra.db
# Для продакшену використовуйте PostgreSQL:
# DATABASE_URL=postgresql://user:pass@localhost/odra

# Redis/Celery
REDIS_URL=redis://localhost:6379/0
USE_CELERY=false

# Embeddings
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDING_DIMENSION=384

# LLM Provider
LLM_PROVIDER=anthropic  # mock, anthropic, openai, google
ANTHROPIC_API_KEY=your-api-key-here
OPENAI_API_KEY=
GOOGLE_API_KEY=

# Processing
MAX_WORKERS=4
CHUNK_SIZE=1000
OVERLAP=100

# Audit
TARGET_PRECISION=0.85
MAX_ITERATIONS=5

🐳 Docker розгортання

Запуск з Docker Compose

# Клонування репозиторію
git clone https://github.com/Nazickj2023/ODRA
cd ODRA

# Запуск системи
docker-compose up -d

# Перегляд логів
docker-compose logs -f

Доступ:

Корисні команди

# Зупинка
docker-compose down

# Перезбірка
docker-compose build
docker-compose up -d

# Перезапуск конкретного сервісу
docker-compose restart backend
docker-compose restart frontend
docker-compose restart worker

# Очистка бази даних
docker-compose exec backend python -c "from app.db import SessionLocal, Document, AuditJob; db = SessionLocal(); db.query(Document).delete(); db.query(AuditJob).delete(); db.commit(); print('Database cleaned')"

📊 Характеристики продуктивності

Метрика	Значення
Пропускна здатність	~100 документів/хвилину
Одночасних worker'ів	До 5 процесів
Середня затримка API	<100ms
Розмір БД (порожня)	~28KB
На один документ	~3-5KB

🔐 Безпека

✅ Реалізовані функції безпеки

✔️ API Key Validation на захищених endpoints'ах
✔️ CORS Protection з налаштованими origin'ами
✔️ SQL Injection Prevention через SQLAlchemy ORM
✔️ Pydantic Validation для всіх вхідних даних
✔️ Error Handling без витоку інформації
✔️ Retry Logic для надійності

📋 Чек-лист продакшену

🚀 Робочий цикл розробки

Додавання нового API endpoint'у

Створіть маршрут у backend/app/api/*.py
Визначте моделі у backend/app/models.py
Реалізуйте логіку у backend/app/services/*.py
Напишіть тести у backend/tests/test_*.py
Оновіть документацію docstring'ів
Протестуйте: python test_integration.py

Додавання фронтенд-сторінки

Створіть компонент у frontend/src/pages/*.tsx
Додайте маршрут у frontend/src/App.tsx
Використовуйте API клієнт з frontend/src/api/client.ts
Стилізуйте Tailwind CSS
Протестуйте у браузері

🧰 Утиліти та команди

# Перевірка статусу системи
./CHECK_SYSTEM.sh

# Запуск всієї системи
./START_SYSTEM.sh

# Швидкий тест інтеграції
python test_integration.py

# Всі тести компонентів
python test_all_components.py

# Тести worker'а
python test_worker_local.py

# Покриття тестами
pytest --cov=backend/app --cov-report=html

📈 Масштабування

Вертикальне масштабування

# backend/app/config.py
MAX_WORKERS = 8  # Збільшіть для більшої пропускної здатності

Горизонтальне масштабування

Запустіть декілька worker інстансів
Використовуйте Redis для розподіленого task queue
Розгорніть Celery для обробки на кількох машинах

Оптимізація БД

Перейдіть на PostgreSQL для продакшену
Налаштуйте індекси для часто використовуваних полів
Використовуйте ClickHouse для аналітики (опційно)

🎯 Roadmap

🚀 Version 1.0 (Поточна версія)

Конвеєр загрузки документів
Створення та управління аудитами
Відстеження прогресу в реальному часі
Цикли зворотного зв'язку від людей
Комплексне тестування

📅 Version 1.1 (Планується)

Інтеграція ClickHouse для аналітики
Redis task queue реалізація
Celery worker масштабування
Розширений фільтрування та пошук
Експорт звітів (PDF, Excel)

🎪 Version 2.0 (Майбутнє)

Співпраця між користувачами
Role-Based Access Control (RBAC)
Продвинута аналітика панель
Custom rule engine
API webhooks та інтеграції

🤝 Контрибьют

Ми приймаємо pull requests! Для великих змін, будь ласка, спочатку відкрийте issue для обговорення.

Зробіть fork репозиторію
Створіть feature branch (git checkout -b feature/amazing-feature)
Commit ваші зміни (git commit -m 'Додав крутий функціонал')
Push на branch (git push origin feature/amazing-feature)
Відкрийте Pull Request

📝 Contribution Guidelines

Додайте тести для нового коду
Оновіть документацію
Дотримуйтесь стилю коду проекту
Переконайтесь, що всі тести проходять

📞 Підтримка та документація

📚 API Документація: http://localhost:8000/docs (коли система запущена)
📖 Швидкий старт: QUICKSTART.md
🧪 Гайд тестування: TESTING_GUIDE.md
📊 Статус системи: SYSTEM_STATUS.md
❓ Issues: GitHub Issues

📄 Ліцензія

Проект ліцензований під MIT License - дивіться файл LICENSE для деталей.

🙏 Подяки

Побудовано з допомогою:

FastAPI - Сучасний Python web framework
React - UI бібліотека
SQLAlchemy - ORM
Sentence Transformers - Embeddings
Tailwind CSS - Utility CSS
Vite - Next generation frontend tooling

🌟 Якщо вам подобається проект, дайте йому ⭐ на GitHub!

Готові аудитувати документи? Почніть з docker-compose up -d 🚀

⬆ Повернутися до верхньої частини

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.venv		.venv
backend		backend
clickhouse		clickhouse
frontend		frontend
scripts		scripts
workers		workers
.env.example		.env.example
.gitignore		.gitignore
.pylintrc		.pylintrc
BUGFIXES.md		BUGFIXES.md
CHANGES_OVERVIEW.txt		CHANGES_OVERVIEW.txt
CHECK_SYSTEM.sh		CHECK_SYSTEM.sh
FIXES_QUICK_START.md		FIXES_QUICK_START.md
FIXES_SUMMARY.txt		FIXES_SUMMARY.txt
IMPORT_FIX.md		IMPORT_FIX.md
Makefile		Makefile
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
START_SYSTEM.sh		START_SYSTEM.sh
SYSTEM_STATUS.md		SYSTEM_STATUS.md
TESTING_GUIDE.md		TESTING_GUIDE.md
docker-compose.yml		docker-compose.yml
init_db.py		init_db.py
package-lock.json		package-lock.json
pyrightconfig.json		pyrightconfig.json
pytest.ini		pytest.ini
run_tests.sh		run_tests.sh
setup.cfg		setup.cfg
test_all_components.py		test_all_components.py
test_integration.py		test_integration.py
test_worker_local.py		test_worker_local.py
verify_fixes.sh		verify_fixes.sh

Latest commit

History

Folders and files

Repository files navigation

🎯 ODRA-Outcome-Driven RAG Auditor

✨ Ключові можливості

📤 Завантаження документів

🔍 Семантичний пошук

🏛️ Audit Jobs

💬 Human Feedback Loop

📊 Аналітика & Звіти

🔐 Безпека

🏗️ Архітектура

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

🚀 Швидкий старт

📋 Вимоги

⚡ Встановлення

🐳 Варіант А: Docker (Рекомендовано)

💻 Варіант Б: Локальний запуск

📝 API Посилання

🏥 Health & Status

📤 Document Ingestion

🏛️ Audit Operations

📚 Все API методи

🧪 Тестування

Запуск інтеграційних тестів

Запуск тестів компонентів

Запуск тестів worker'а

Перевірка статусу системи

curl приклади

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

⚙️ Конфігурація

Змінні оточення

🐳 Docker розгортання

Запуск з Docker Compose

Корисні команди

📊 Характеристики продуктивності

🔐 Безпека

✅ Реалізовані функції безпеки

📋 Чек-лист продакшену

🚀 Робочий цикл розробки

Додавання нового API endpoint'у

Додавання фронтенд-сторінки

🧰 Утиліти та команди

📈 Масштабування

Вертикальне масштабування

Горизонтальне масштабування

Оптимізація БД

🎯 Roadmap

🚀 Version 1.0 (Поточна версія)

📅 Version 1.1 (Планується)

🎪 Version 2.0 (Майбутнє)

🤝 Контрибьют

📝 Contribution Guidelines

📞 Підтримка та документація

📄 Ліцензія

🙏 Подяки

🌟 Якщо вам подобається проект, дайте йому ⭐ на GitHub!

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages