Персональный финансовый советник с искусственным интеллектом. Анализирует ваши расходы, прогнозирует кешфлоу, подбирает кредиты и даёт конкретные советы — прямо в чате.
- О проекте
- Архитектура
- Функциональность
- Стек технологий
- Быстрый старт
- API Reference
- База данных
- Преимущества
КопиКот — полнофункциональное PWA-приложение для управления личными финансами, построенное на трёх независимых микросервисах. Пользователь проходит короткий онбординг, после чего получает персонализированный финансовый профиль, доступ к AI-чату, прогнозам кешфлоу и подборке кредитных предложений от 37 российских банков.
Ключевая идея: детерминированные калькуляторы считают цифры, LLM объясняет результаты на понятном языке.
Система состоит из трёх независимо разворачиваемых сервисов:
┌──────────────────────────────────┐
│ Frontend (React PWA) │
│ :3000 / GitHub Pages │
└──────────────┬───────────────────┘
│ HTTP / SSE
┌──────────────▼───────────────────┐
│ Backend API (FastAPI) │
│ :8000 — /api/v1 │
└──────┬───────────────┬────────────┘
│ │
┌────────────▼────┐ ┌──────▼──────────────────┐
│ MongoDB Atlas │ │ AI Service (FastAPI) │
│ │ │ :8001 (HTTPS) │
│ users │ │ │
│ messages │ │ LangGraph Pipeline │
│ ai_cache │ │ Ollama + Qwen 2.5 │
└─────────────────┘ │ Web Search │
└──────────────────────────┘
- Frontend отправляет запрос на Backend
- Backend проверяет кеш в MongoDB; при промахе — проксирует запрос к AI Service
- AI Service запускает LangGraph-пайплайн: Planner → (Search) → Analyst
- Ответ возвращается через SSE или синхронно; Backend сохраняет результат в
ai_cache
| Фаза | Вопросы |
|---|---|
| Lifestyle | Досуг, ежедневные сервисы |
| Spending Patterns | Кафе/рестораны, подписки, транспорт |
| Financial Details | Доход, обязательства, накопления, цели |
После онбординга LLM строит финансовый профиль пользователя и немедленно прогревает кеш аналитики.
Диалоговый финансовый советник с памятью (последние 10 сообщений в контексте). Работает в двух режимах:
- Синхронный — ответ за 15–60 с
- Стриминг (SSE) — прогресс в реальном времени:
queued → processing → searching → analyzing → result
Адаптирует сложность ответа под финансовую грамотность пользователя (beginner / medium / advanced).
Работают мгновенно, без LLM и очереди:
| Калькулятор | Описание |
|---|---|
| Traffic Light | PTI-коэффициент (платёж/доход): зелёный <30%, жёлтый 30–50%, красный >50% |
| Health Score | Интегральная оценка здоровья финансов (0–100): расходы, долги, подушка безопасности |
| Cashflow Forecast | Поднёвной прогноз баланса до зарплаты, флаг критических платежей |
| Savings Plan | Срок достижения финансовой цели при выделении 20% свободного дохода |
| Spending Patterns | Соотношение статей расходов, инсайты по категориям |
- 45 офферов от 37 российских банков (Т-Банк, Сбербанк, Альфа-Банк, ВТБ, Газпромбанк и др.)
- Двухкомпонентный скоринг: ставка (40 очков) + срок (60 очков)
- Возвращает топ-6 предложений, отсортированных по
score - Время ответа < 50 мс (детерминированный алгоритм, без LLM)
- Daily Action — персональная карточка-действие на день (обновляется раз в сутки)
- Spending Patterns — паттерны трат с LLM-инсайтами
- Cashflow — прогноз денежного потока с указанием «дня икс»
- Goals — трекинг финансовых целей
| Технология | Назначение |
|---|---|
| React 19 + TypeScript | UI-фреймворк |
| Vite | Сборка, HMR |
| Tailwind CSS + Radix UI | Стили и компоненты |
| Zustand | Глобальное состояние |
| Recharts | Графики и визуализация |
| Framer Motion | Анимации |
| React Router DOM 7 | Роутинг |
| idb-keyval | Локальное хранилище (IndexedDB) |
| PWA (vite-plugin-pwa) | Установка как приложение |
| Технология | Назначение |
|---|---|
| Python 3.12+ | Язык |
| FastAPI ≥ 0.115 | Веб-фреймворк, Swagger/ReDoc |
| Uvicorn ≥ 0.32 | ASGI-сервер |
| Motor ≥ 3.6 | Async-драйвер MongoDB |
| httpx ≥ 0.28 | Async HTTP-клиент для AI-сервиса |
| Pydantic Settings ≥ 2.6 | Конфигурация через .env |
| MongoDB Atlas | Облачная база данных |
| Технология | Назначение |
|---|---|
| FastAPI 0.115.5 | Веб-фреймворк |
| LangGraph 0.2.55 | Оркестрация AI-агента |
| LangChain Core 0.3 | Работа с LLM |
| Ollama 0.4.2 | Локальный инференс LLM |
| Qwen 2.5 (1.5b + 7b) | Модели планировщика и аналитика |
| DuckDuckGo / Serper / Tavily | Веб-поиск |
| Trafilatura | Извлечение контента со страниц |
| MongoDB (Motor) | Хранение сессий и профилей |
- Python 3.12+
- Node.js 20+
- MongoDB Atlas (или локальный MongoDB)
- Ollama с загруженными моделями Qwen 2.5
# Клонирование ветки back
git checkout back
# Создание venv и установка зависимостей
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
# Конфигурация
copy .env.example .env
# Заполнить: MONGODB_URI, AI_SERVICE_URL
# Запуск
uvicorn app.main:app --reload --port 8000| Интерфейс | URL |
|---|---|
| Swagger UI | http://localhost:8000/docs |
| ReDoc | http://localhost:8000/redoc |
| Базовый путь API | http://localhost:8000/api/v1 |
# Клонирование ветки ai
git checkout ai
# Установка зависимостей
pip install -r requirements.txt
# Загрузка моделей
ollama pull qwen2.5:1.5b-instruct-q4_K_M
ollama pull qwen2.5:7b-instruct-q4_K_M
# Конфигурация
cp .env.example .env
# Установить: OLLAMA_BASE_URL, TAVILY_API_KEY (опционально)
# Запуск
uvicorn main:app --port 8001 --ssl-keyfile certs/server.key --ssl-certfile certs/server.crt# Клонирование ветки front
git checkout front
npm install
# Конфигурация API URL в .env
VITE_API_URL=http://localhost:8000
npm run dev # http://localhost:3000
npm run build # Продакшн-сборка
npm run deploy # Деплой на GitHub Pages| Переменная | По умолчанию | Описание |
|---|---|---|
PROJECT_NAME |
HackathonBack |
Название в Swagger |
VERSION |
0.1.0 |
Версия API |
DEBUG |
false |
Debug-режим |
ALLOWED_ORIGINS |
["http://localhost:3000"] |
CORS |
AI_SERVICE_URL |
http://localhost:8001 |
URL AI-сервиса |
CA_CERT_PATH |
certs/ca.crt |
CA-сертификат |
AI_SSL_VERIFY |
false |
Проверка SSL (dev) |
MONGODB_URI |
mongodb://localhost:27017 |
URI MongoDB |
MONGODB_DB_NAME |
hackathon |
Имя базы данных |
| Метод | Путь | Описание |
|---|---|---|
GET |
/api/v1/health |
Статус бэкенда |
GET |
/api/v1/ai/health |
Статус AI-сервиса и Ollama |
GET |
/api/v1/ai/queue/status |
Длина очереди AI |
| Метод | Путь | Описание |
|---|---|---|
POST |
/api/v1/onboarding/step |
Следующий шаг онбординга |
POST |
/api/v1/onboarding/stream |
То же через SSE |
| Метод | Путь | Описание |
|---|---|---|
POST |
/api/v1/chat/message |
Синхронный AI-ответ |
POST |
/api/v1/chat/stream |
Стриминговый ответ (SSE) |
| Метод | Путь | Описание |
|---|---|---|
GET |
/api/v1/ai/daily-action/{login} |
Совет на сегодня |
GET |
/api/v1/ai/cashflow/{login} |
Прогноз кешфлоу |
POST |
/api/v1/ai/cashflow/calculate |
Расчёт по текущему балансу |
GET |
/api/v1/ai/patterns/{login} |
Анализ паттернов трат |
POST |
/api/v1/ai/bank-offers |
Подбор кредитных предложений |
{
"login": "user@example.com",
"profile": {
"monthly_income": 120000.0,
"monthly_expenses": 80000.0,
"monthly_debt_payments": 10000.0,
"savings": 200000.0,
"financial_goal_amount": 500000.0,
"goals": ["накопить на квартиру"],
"financial_literacy": "medium"
},
"onboarding_complete": true,
"created_at": "2026-05-30T10:00:00Z"
}Хранит историю чата; в каждый запрос к AI передаются последние 10 сообщений.
{
"user_id": "user@example.com",
"endpoint": "daily_action | patterns | cashflow | bank_offers",
"response": { "...ответ AI..." },
"cached_at": "2026-05-30T10:00:00Z"
}Уникальный индекс по (user_id, endpoint). Фоновый планировщик обновляет кеш при старте и раз в час.
Детерминированные алгоритмы дают точные цифры (PTI, Health Score, кешфлоу), а LLM переводит их на язык пользователя. Это исключает галлюцинации в расчётах и снижает нагрузку на модель.
При недоступности AI-сервиса бэкенд отдаёт последний закешированный ответ. Математический фолбэк (fallbacks.py) обеспечивает работу кешфлоу-калькулятора без LLM. Пользователь никогда не видит пустой экран.
Server-Sent Events позволяют показывать статус обработки в реальном времени (queued → searching → analyzing), что снижает ощущение ожидания при 15–60-секундных запросах.
Три независимых микросервиса позволяют масштабировать только узкое место (AI-инференс) и не тратить ресурсы на избыточный фронтенд или бэкенд.
/cashflow/calculate и /bank-offers обходят LLM-очередь и отвечают за < 50 мс — идеально для интерактивных форм без ощутимых задержек.
- Онбординг строит полный финансовый профиль за 9 вопросов
- AI адаптирует стиль ответа под уровень финансовой грамотности
- Ежедневная персональная карточка-действие меняется в зависимости от профиля
- 45 кредитных предложений от 37 банков РФ с актуальными ставками
- Все расчёты в рублях
- Обязательный русский язык для LLM-ответов (закреплено в промптах)
prompts.yaml позволяет редактировать все системные промпты без перезапуска сервиса — удобно для тонкой настройки поведения AI в продакшне.
| Ветка | Содержимое |
|---|---|
about_project |
Главная ветка, общий README |
back |
FastAPI-бэкенд |
front |
React PWA-приложение |
ai |
LangGraph AI-микросервис |
gh-pages |
Деплой фронтенда на GitHub Pages |
Проект создан в рамках финтех-хакатона командой AnywayHack.