AlfaFuture Hack — Помощник для малого бизнеса

Описание | Возможности | Стек | Как устроен агент | Запуск

---

Описание проекта

Веб-приложение — ИИ-ассистент, который помогает владельцам малого бизнеса решать повседневные задачи с использованием LLM.

Приложение предоставляет рекомендации и автоматизирует рутинные операции в таких сферах, как:

• Юридические вопросы
• Финансы и бухгалтерия
• Маркетинг и продвижение
• Операционные процессы и управление персоналом

Цель — сэкономить время владельца бизнеса и повысить качество ежедневных решений за счёт контекстных подсказок и проактивной аналитики.

---

Ключевые возможности

• Агент с инструментами — сам решает, когда что-то посчитать или составить: финансовые расчёты (маржа, наценка, НДС, платёж по кредиту), черновики счёта / письма / договора, актуальная дата.
• RAG-база знаний — ответы по налогам, финансам и маркетингу заземлены в документах с указанием источников.
• Загрузка PDF в чат — пользователь прикрепляет договор / счёт PDF, документ чанкуется и индексируется, и агент отвечает на вопросы по нему (заземление на загруженный файл, scoped по чату), показывая его в источниках.
• Экспорт документов — сгенерированный счёт / письмо / договор можно скачать в DOCX или PDF (рендер на сервере, корректная кириллица) или скопировать в один клик.
• Стриминг в реальном времени — ответ и шаги инструментов появляются по мере выполнения.
• Guardrails — защита от prompt-инъекций и попыток обойти инструкции.
• Observability — трейсинг каждого запроса: модель, токены, оценка стоимости, латентность.
• Eval-оценка качества агента (LLM-as-judge) и набор автотестов.

---

Стек технологий

• Backend: Python + FastAPI
• Frontend: React / Vite
• База данных: PostgreSQL + pgvector (RAG)
• Контейнеризация: Docker + Docker Compose
• LLM: OpenRouter / OpenAI SDK с function calling (модель по умолчанию: openrouter/free)

---

Как устроен агент

Ассистент — это не один вызов LLM, а агент с инструментами и явным циклом рассуждение → действие → наблюдение:

сообщение пользователя
   │
   ▼
сборка контекста с ролями (system + история, обрезка по бюджету токенов через tiktoken)
   │
   ▼
┌──────────────────────────────────────────────┐
│  ответ LLM (со схемами инструментов)          │
│    • нет вызовов     → финальный ответ        │
│    • есть вызовы     → выполнить → вернуть     │◄── повтор до MAX_AGENT_STEPS
└──────────────────────────────────────────────┘
   │
   ▼
финальный ответ + список выполненных шагов-инструментов

Инструменты (детерминированные функции, описанные схемой OpenAI function calling):

Инструмент	Назначение
financial_calculator	Маржа, наценка, НДС, аннуитетный платёж по кредиту
generate_document	Черновик счёта / делового письма / договора
get_current_datetime	Актуальные дата и время для модели

Эндпоинты:

• POST /api/v1/messages/send — возвращает ответ и список шагов (steps), которые сделал агент.
• POST /api/v1/messages/stream — Server-Sent Events: события step по мере вызова инструментов и события token с дельтами ответа напрямую от модели (stream=True), по мере генерации. UI наполняет ответ токен за токеном и рисует каждый вызов сворачиваемым шагом.
• POST /api/v1/documents/export — рендерит переданный текст в DOCX или PDF ({format, content, title}) и отдаёт файл на скачивание. PDF использует встроенный Unicode-шрифт, поэтому кириллица отображается корректно.
• POST /api/v1/documents/upload — загрузка PDF (multipart: chat_id + file): извлекает текст, чанкует, считает эмбеддинги и индексирует для RAG в рамках чата.
• GET /api/v1/documents?chat_id= — список загруженных в чат документов (имя + число фрагментов).

База знаний (RAG)

Ответы заземлены в небольшой базе знаний (налоги, финансы, маркетинг) через pgvector:

• make seed чанкует markdown-документы, считает эмбеддинги и сохраняет векторы в Postgres.
• На каждый запрос сервис достаёт top-k релевантных фрагментов по косинусной близости и инжектит их в контекст агента; ответ ссылается на них, а UI показывает источники.
• Эмбеддинги подключаемые: local (по умолчанию, оффлайн, без API) или api (OpenAI-совместимый /embeddings).

Инженерная зрелость и безопасность

• Eval — датасет сценариев, оценённый двумя сигналами: детерминированной проверкой выбора инструмента и LLM-as-judge по рубрике. make eval формирует Markdown-скоркард (pass rate, точность выбора инструмента, средний балл).

• Observability — каждый прогон агента пишет структурный JSON-трейс: запрошенная и реально выбранная модель, число вызовов LLM/инструментов, токены, оценка стоимости и латентность. Sentry подключён и гейтится на APP_CONFIG__SENTRY__DSN.

  {"event": "agent_run", "model": "openrouter/free",
   "resolved_model": "nvidia/nemotron-nano-12b-v2-vl:free",
   "num_tool_calls": 1, "tools": ["financial_calculator"],
   "total_tokens": 1500, "estimated_cost_usd": 0.0, "finish_reason": "completed"}

• Guardrails — попытки prompt-инъекций / джейлбрейка отлавливаются до обращения к модели, отвечаются безопасным отказом и логируются как security-событие. Вывод проверяется на утечку системного промпта.

Агентный цикл, инструменты, трейсинг, guardrails и eval-пайплайн покрыты юнит-тестами (make test).

---

Локальный запуск

Требования: запущенный Docker Desktop и GNU Make.

1. Создайте файлы окружения

cp src/backend/.env.example          src/backend/.env
cp src/backend/.env.app_config.example src/backend/.env.app_config
cp src/frontend/.env.example         src/frontend/.env   # опционально

Откройте src/backend/.env.app_config и впишите свой APP_CONFIG__LLM__API_KEY (ключ OpenRouter). Модель по умолчанию openrouter/free сама выбирает бесплатную модель с поддержкой инструментов.

2. Поднимите всё

make up

Команда соберёт образы, запустит сервисы, сгенерирует JWT-ключи (если их нет) и применит миграции.

Опционально загрузите базу знаний, чтобы ответы были с цитированием источников:

make seed

3. Проверьте сервисы

• Backend (Swagger): http://localhost:8000/docs
• Frontend: http://localhost

Полезные команды

Команда	Описание
make help	Список всех целей
make up / make down	Запуск / остановка стека
make build / make rebuild	Сборка / пересборка образов
make logs	Логи всех сервисов (включая JSON-трейсы агента)
make migrate	Применить миграции БД
make seed	Загрузить базу знаний в pgvector
make test	Запустить тесты бэкенда
make eval	Прогнать eval-набор агента (LLM-as-judge)
make lint / make fmt	Проверка / автоформатирование бэкенда
make keys	Сгенерировать новую пару RS256 JWT-ключей
make clean	Остановить и удалить volume'ы (удаляет БД)