Обзор API

Архитектура API

Думатель использует API Gateway паттерн: все клиентские запросы проходят через Sprut, который маршрутизирует их к специализированным микросервисам. Межсервисное взаимодействие происходит через HTTP/REST (синхронное) и NATS JetStream (асинхронное).

OpenAPI-спецификация

Параметр	Значение
URL	https://sprut-api-dev01.monsterscorp.ru/openapi.json
Генерация типов	pnpm generate-api-types → shared/api/openapi/types.generated.ts
Swagger UI	/docs (на каждом FastAPI-сервисе)
ReDoc	/redoc (на каждом FastAPI-сервисе)

Sprut — API Gateway

Центральная точка входа. Python 3.14, FastAPI с автоматической OpenAPI-документацией.

Endpoints

Группа	Путь	Назначение
Auth	/auth/*	Аутентификация через Keycloak (SSO/OIDC)
Chat	/chat/*	Управление чатами: создание, список, удаление
Message	/message/*	Отправка и получение сообщений в чате
Document	/document/*	Загрузка, метаданные, управление документами
Attachment	/attachment/*	Управление вложениями к документам
Directory	/directory/*	Справочники и каталоги
Project	/project/*	Управление проектами (пространствами)
Organization	/organization/*	Управление организациями
Profile	/profile/*	Профили пользователей
Billing	/billing/*	Платежи, баланс, тарифы
Notification	/notification/*	Уведомления пользователей
Onboarding	/onboarding/*	Онбординг новых пользователей
Legal Document	/legal_document/*	Юридические документы и соглашения
Tree	/tree/*	Древовидные структуры данных (карты знаний)
Yandex	/yandex/*	Интеграция с Yandex API

Аутентификация

• Метод: Bearer token через Keycloak OIDC
• SSO: Single Sign-On через Keycloak realm
• Межсервисная: SERVICE_AUTH_TOKEN для внутренних вызовов

Протоколы коммуникации

Направление	Протокол	Описание
Browser → Seadragon	HTTPS	SPA
Seadragon → Sprut	REST (HTTPS)	CRUD operations, OpenAPI
Seadragon ← NATS	SSE (через Next.js API Route)	AI-стриминг ответов
Sprut → PostgreSQL	asyncpg	Основные данные
Sprut → Milvus	pymilvus	Векторный поиск RAG
Sprut → Keycloak	HTTP	Верификация токенов
Sprut → NATS	Producer	Публикация задач воркерам
Sprut → Doubloon	HTTP	Биллинговые операции
Workers ← NATS	Consumer (orker)	Получение задач
Workers → NATS	FrontProducer	Результаты → фронтенд
Amigofish → LLM	HTTPS	OpenAI/Claude API
Anglerfish → Milvus	pymilvus	Запись embeddings
Doubloon → Tinkoff	HTTP	Платежи
Gull → Bitrix	HTTP	CRM события
Chronograf → NATS	Producer	Scheduling задач

Doubloon — Billing API

Сервис обработки платежей и управления подписками.

Endpoints

Путь	Метод	Назначение
/billing	GET/POST	Основные операции биллинга
/health	GET	Health check

Схемы данных

Сущность	Описание
balance	Баланс пользователя
card	Привязанные платёжные карты
transaction	История транзакций
subscription	Активные подписки
tariff	Доступные тарифы
charge_off	Списания
freeze	Заморозка подписки
hold	Холдирование средств
sbp	Оплата через СБП
period	Периоды тарификации

Kraken — Math Evaluation API

Stateless сервис для математических вычислений.

Endpoints

Путь	Метод	Назначение
POST /evaluate	POST	Вычисление математического выражения
GET /health	GET	Health check

Пример запроса

POST /evaluate
{
  "expression": "integrate(x^2, x, 0, 1)"
}

Sealayers — ML Classification API

Классификация пользовательских запросов через нейросеть.

Endpoints

Путь	Метод	Назначение
POST /classify	POST	Классификация запроса (тип, сложность)
GET /health	GET	Health check

Асинхронные API (NATS JetStream)

Сервисы, работающие через очереди сообщений:

Сервис	Stream/Subject	Назначение
Amigofish	complete_tasks / completion.{chat_id}	Обработка AI-запросов, стриминг результатов
Anglerfish	index, attachment_index, unindex	Индексирование документов
Gull	Email task stream	Отправка email-уведомлений
Chronograf	Scheduled tasks stream	Выполнение задач по расписанию
Anchor	Notification events	Обработка платёжных событий
Bilge	Billing tasks	Управление подписками
Shark	Shark tasks	Scheduled worker
ConvictFish	ConvictFish tasks	Daily Bitrix CRM sync

Формат событий NATS (AI-стриминг)

{ "type": "text-delta", "data": "..." }
{ "type": "reasoning-delta", "data": "..." }
{ "type": "tool", "data": { "name": "web_search", "result": "..." } }
{ "type": "finish" }

Паттерн обработки (Orker Worker)

Producer → NATS JetStream → Durable Consumer → Orker Worker → Result
                                                    │
                                                    ├── Success → ack
                                                    ├── Retry → redeliver (до 3 попыток)
                                                    └── Fail → on_fail handler + Sentry

Streaming Event Contract (Amigofish)

Все события генерации стримятся как JSON-объекты в NATS subject completion.{chat_id} (stream COMPLETIONS, max_age=24h). Фронтенд (Seadragon) подписывается через SSE и обрабатывает события в реальном времени.

Типы событий

Тип	Ключевые поля	Описание
reasoning-start	id	Открытие блока reasoning
reasoning-delta	id, delta, [tool, meta]	Фрагмент «размышления» (на русском, user-facing)
reasoning-end	id, [duration]	Закрытие блока reasoning
text-start	id	Начало текстового блока ответа
text-delta	id, delta	Инкрементальная часть текста
text-end	id	Завершение текстового блока
citation-marker	textId, markerId, sourceId, index, length, unit	Инлайн-маркер цитаты в тексте
citation-source	id, kind (document/web), documentId/url, ...	Источник цитаты (документ или веб-ссылка)
citations-finalize	order, unused	Финальный порядок цитат (после завершения стрима)
tool-input-start	toolCallId, toolName, input	Начало вызова инструмента
tool-call	toolCallId, toolName, input	Вызов инструмента (MindMap / file artifact)
tool-result	toolCallId, toolName, result	Результат инструмента
clarification-request	chat_id, thread_id, questions, timeout_seconds, round, max_rounds	Запрос уточнения (при LangGraph interrupt)
finish	—	Всегда последнее событие

Соседние text-delta с одинаковым id объединяются (сжатие) при сохранении в БД.

NATS-конфигурация

Параметр	Значение
Input stream	complete_tasks
Output stream	COMPLETIONS
Output subject	completion.{chat_id}
max_age	24 часа
Clarification subject	clarification_answer.{complete_id} (ephemeral, не JetStream)

Устаревшие сообщения NATS subject очищаются при старте каждой задачи, чтобы избежать воспроизведения предыдущего ответа.

LLM Tools (каталог инструментов Amigofish)

Все определения инструментов хранятся в schemas/function.py как OpenAI-shaped function specs (strict=True). Реализации — в tools/.

Инструмент	Агент-владелец	Вход / Выход
RAG (query, document_ids)	rag_agent	Milvus hybrid dense+sparse search -> list[Chunk]
Tree ()	rag_agent	Sprut tree endpoint -> вложенный dict директорий/файлов
GetDocumentContent (document_id)	rag_agent	Sprut document full-text -> строка
WebSearch (query)	web_agent	Tavily search (search_depth="advanced") -> list[WebSearchResponse]
WebExtract (link_ids)	web_agent	Tavily extract -> list[WebExtractResponse]
GenerateDocument (query, raw_data)	document_agent	Stonefish /api/document/generate -> ArtifactItem + DB row
GetArtifact ()	document_agent	Список артефактов чата (до 10, по created_at desc)
EditDocument (artifact_id, instructions)	document_agent	Stonefish /api/document/edit с сохранённым base_code

| Answer (chunks) | synthesis_agent | Финальный ответ: text / citation / link чанки | | MindMap (nodes, edges) | synthesis_agent | Визуализация дерева; макс. один вызов; BFS-фильтрация циклов/orphans |

Каждый инструмент имеет опциональные reasoning formatters (*_input_reasoning_formatter, *_reasoning_formatter), которые превращают вызов в человекочитаемую мысль на русском (напр. «Ищу в сети "..."», «Изучаю документ "..."»). Они формируют поток reasoning-delta на фронтенде.

Stonefish — Document Generation API

FastAPI-сервис генерации бинарных документов. README в репозитории отсутствует; информация получена из структуры репозитория (stonefish-tree.md) и CI-конфига.

Назначение

Параметр	Значение
Фреймворк	FastAPI (Python)
Ветка	master
Helm chart	tools/charts/stonefish/
Окружения	dev, pro (отдельные ConfigMap и Ingress на каждое)
Масштабирование	HPA (задан в templates/hpa.yaml)

Endpoints

Путь	Назначение
POST /api/document/generate	Генерация нового документа (PDF, DOCX, XLSX, PPTX)
POST /api/document/edit	Редактирование существующего документа по artifact_id + instructions
GET /health	Health check

Роутеры расположены в source/src/api/router/document.py и health.py. Схемы данных — в source/src/schemas/document.py.

Интеграция с Claude

Сервис использует Claude API через модуль source/src/services/claude.py. Dockerfile устанавливает Claude Code CLI (npm install -g @anthropic-ai/claude-code) поверх базового образа cr.monsterscorp.ru:5000/python:latest, что указывает на programmatic использование Claude для синтеза содержимого документов.

Аутентификация

Модуль source/src/api/auth.py реализует авторизацию для входящих запросов от Amigofish (межсервисный SERVICE_AUTH_TOKEN).

CI/CD

Stonefish использует стандартный набор workflow-шаблонов (dot.mind/devops/workflows): version → test (SAST + linters + pytest) → build_docker → build_chart → push_chart → update_umbrella_chart → deploy_env → verify → test_env. Интеграция с Sentry: проект stonefish. Registry: cr.monsterscorp.ru:5000.

Межсервисное взаимодействие

┌──────────┐   HTTP    ┌──────────┐
│  Sprut   │─────────▶│ Doubloon │  Синхронные запросы на биллинг
└──────────┘          └──────────┘

┌──────────┐   HTTP    ┌──────────┐
│  Anchor  │─────────▶│ Doubloon │  Обработка платёжных событий
└──────────┘          └──────────┘

┌──────────┐   HTTP    ┌──────────┐
│  Bilge   │─────────▶│ Doubloon │  Управление подписками
└──────────┘          └──────────┘

┌──────────┐   HTTP    ┌──────────┐
│  Descent │─────────▶│  Sprut   │  Справочные данные
└──────────┘          └──────────┘

┌──────────┐   NATS    ┌──────────┐
│  All     │─────────▶│  All     │  Асинхронные события
│ producers│          │ consumers│
└──────────┘          └──────────┘

Связанные страницы

• Потоки данных — полная схема движения данных
• C4: Containers — карта сервисов платформы
• Стек технологий
• Деплой и инфраструктура