sber/agent
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: sber/agent:5d77ab1a882160d811967e64fae70d8ec5d6e412
Branches Tags
sber/agent:codex/orchestrator-v1 sber/agent:main
...
compare: sber/agent:8fb76bb33175a9d8703d9ad44381271c6535f418
Branches Tags
sber/agent:main sber/agent:codex/orchestrator-v1

3 Commits
5d77ab1a88 ... 8fb76bb331

Author SHA1 Message Date
alex 8fb76bb331 фиксирую состояние 2026-04-07 21:41:27 +03:00
alex bc29d51a29 удалил тестовые данные 2026-04-07 21:41:20 +03:00
alex 6b74d410cd Роутер работает нормально в process v2 2026-04-07 14:09:51 +03:00
712 changed files with 16498 additions and 96577 deletions
Expand all files Collapse all files
.gitignore
+6
View File
@@ -1,3 +1,9 @@
.env
.venv
__pycache__
# Pipeline harness: per-run artifacts (md/json from tests.pipeline_setup_v3/v4)
tests/**/test_runs/**/*.md
tests/**/test_runs/**/*.json
tests/**/test_results/**/*.md
tests/**/test_results/**/*.json
README.md
+5 -5
View File
@@ -915,15 +915,15 @@ flowchart TD
### 4.1.3. Канонический MVP runtime (CODE-first)
Единая точка входа исполнения — пакет `app.modules.agent.runtime`:
Единая точка входа исполнения — пакет `app.core.agent.runtime`:
- **Роутер:** `app.modules.agent.intent_router_v2`; он отвечает и за routing, и за retrieval planning.
- **LLM-слой:** `app.modules.agent.llm`; здесь живут `AgentLlmService`, `PromptLoader` и системные prompt assets.
- **Runtime:** `app.modules.agent.runtime`; внутри него stages разложены по подпакетам `retrieval`, `context`, `gates`, `answer_policy`, `generation`, `finalization`.
- **Роутер:** `app.core.agent.intent_router`; он отвечает и за routing, и за retrieval planning.
- **LLM-слой:** `app.core.agent.llm`; здесь живут `AgentLlmService`, `PromptLoader` и системные prompt assets.
- **Runtime:** `app.core.agent.runtime`; внутри него stages разложены по подпакетам `retrieval`, `context`, `gates`, `answer_policy`, `generation`, `finalization`.
- **Цепочка:** запрос → `IntentRouterV2` → retrieval planning → runtime retrieval adapter → нормализованный context/evidence → evidence gate 1 → answer policy → LLM generation → evidence gate 2 → finalization → diagnostics.
- **Evidence gates:** pre/post проверки достаточности evidence и качества ответа по сценарию.
- **Диагностика:** runtime возвращает machine-readable diagnostics и trace по стадиям.
- **RAG:** `app.modules.rag` больше не содержит agent use-case слоев; он остается инфраструктурой indexing/retrieval/storage.
- **RAG:** `app.core.rag` больше не содержит agent use-case слоев; он остается инфраструктурой indexing/retrieval/storage.
Тесты: `pipeline_setup_v3` и связанные suite-ы проверяют канонический runtime и его stage-based execution.
_plan.md
+4
View File
@@ -0,0 +1,4 @@
# Запросы
1. Какие методы апи есть в проекте
2. Какие методы апи есть для healthcheck
3. Где документация на healthcheck
_process.zip
BIN
View File
Binary file not shown.
_process/03. Intents.md
+59
View File
@@ -0,0 +1,59 @@
# Intents
## Domains
- `DOCS`
- `GENERAL`
- `CODE` - временно отключен
## GENERAL
### Intent `GENERAL_QA`
Общий интент для вопросов без точного маршрута.
В дальнейшем может использоваться как fallback.
Subintents:
- `SUMMARY` - ответы на общие вопросы по SUMMARY
## DOCS
### Intent `ARCHITECTURE`
Обработка вопросов по архитектуре.
Subintents пока отсутствуют.
Интент запланирован, без реализации.
### Intent `DOC_EXPLAIN`
Объяснение по документации.
Subintents:
- `SUMMARY` - краткое объяснение темы по SUMMARY-блокам документации
- `FIND_FILES` - поиск файлов с релевантной информацией
- `EXPLAIN_API` - объяснение работы метода
- `COMPONENT_INTEGRATIONS` - перечень интеграций компонента, API, UI, сущности, внешних систем
- `ENTITY_INTEGRATIONS` - перечень интеграций сущности
В текущем узком MVP реально реализованы только:
- `SUMMARY`
- `FIND_FILES`
Для запросов по интеграциям целевым retrieval-слоем является `D6_INTEGRATION_INDEX`.
### Intent `OPENAPI_GENERATION`
Генерация OpenAPI-спеки.
Subintents:
- `FULL_SPEC` - создание полной спецификации
### Intent `DOC_GENERATION`
Редактирование документации.
Subintents:
- `FROM_FEATURE` - создание документации из системной аналитики на фичу
_process/03. RAG.md
+356
View File
@@ -0,0 +1,356 @@
# RAG
## Состояние as is
RAG сейчас используется как общее ядро индексации и retrieval по коду и документации.
Основной storage - `rag_session` и многослойный индекс в БД.
## Основные части
- `RagService` - фасад индексации и retrieval
- `DocsIndexingPipeline` - индексация документации
- `CodeIndexingPipeline` - индексация кода
- `RagRepository` - persistence и retrieval
- `IntentRouterV2` - планирование retrieval: слои, фильтры, ограничения
- `RuntimeRetrievalAdapter` - выполнение retrieval в runtime
## Индексация
Индексация идет по двум направлениям:
- `DOCS`
- `CODE`
На вход подается snapshot или changes.
Для каждого файла выбирается подходящий pipeline.
На выходе формируются документы по слоям и сохраняются в RAG-хранилище.
## Структура БД
Все слои сохраняются в общую таблицу `rag_chunks`.
### Общие поля по слоям
| Поле БД | Назначение |
|---|---|
| `rag_session_id` | идентификатор сессии индексации |
| `path` | путь исходного файла |
| `content` | основной текст записи для retrieval |
| `layer` | идентификатор слоя |
| `title` | короткий заголовок записи |
| `lang` | язык исходного содержимого, в основном для code-слоев |
| `repo_id` | идентификатор репозитория или проекта |
| `commit_sha` | версия кода или документов на момент индексации |
| `span_start`, `span_end` | диапазон строк в исходном файле, если он есть |
| `embedding` | векторное представление записи |
| `metadata_json` | структурированные атрибуты конкретного слоя |
### Поля со смыслом слоя
Смысл конкретного слоя хранится в `metadata_json`.
Именно эти атрибуты определяют, какой объект был извлечен и как его интерпретировать в retrieval.
Домены и поддомены должны храниться в `metadata_json` явно.
## Слои DOCS
### `D0_DOC_CHUNKS`
Задача:
Хранит текстовые фрагменты документации для retrieval по содержимому разделов.
Формирование:
Документ сначала разбирается на frontmatter и body, затем body режется на секции через markdown chunker.
Для каждой секции создается отдельная запись слоя.
Нарезка идет по разделам документа.
Только в fallback-сценарии, когда markdown-структура не найдена, используется нарезка по фиксированным текстовым чанкам.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
| `type` | тип документа из frontmatter | `frontmatter.type` |
| `module` | модуль документа | `frontmatter.module` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `tags` | теги документа | `frontmatter.tags` |
| `section_path` | полный путь секции в иерархии заголовков | результат `MarkdownDocChunker` |
| `section_title` | заголовок текущей секции | результат `MarkdownDocChunker` |
| `order` | порядок секции внутри документа | результат `MarkdownDocChunker` |
| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
| `source_path` | исходный путь документа | путь файла |
| `artifact_type` | тип артефакта, здесь `DOCS` | константа builder |
Связанные классы:
`DocsIndexingPipeline`, `DocsContentParser`, `MarkdownDocChunker`, `DocsDocumentBuilder`
### `D1_DOCUMENT_CATALOG`
Задача:
Хранит карточку документа как точку входа в документ и его краткое описание.
Формирование:
Источник данных - frontmatter, fallback title, summary и doc kind, вычисленный классификатором документации.
Данные извлекаются структурированно по атрибутам.
В `content` попадает summary документа, а не склейка всех частей документа в сплошной текст.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `document_id` | идентификатор документа | `frontmatter.id`, иначе путь файла |
| `type` | тип документа из frontmatter | `frontmatter.type` |
| `name` | системное имя документа | `frontmatter.name` |
| `title` | человекочитаемый заголовок документа | `frontmatter.title`, иначе fallback title |
| `module` | модуль документа | `frontmatter.module` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `layer` | логический слой, указанный в frontmatter документа | `frontmatter.layer` |
| `status` | статус документа | `frontmatter.status` |
| `updated_at` | дата или отметка последнего обновления | `frontmatter.updated_at` |
| `tags` | теги документа | `frontmatter.tags` |
| `entities` | сущности, связанные с документом | `frontmatter.entities` |
| `parent` | родительский документ | `frontmatter.parent` |
| `children` | дочерние документы | `frontmatter.children` |
| `links` | ссылки на связанные материалы | `frontmatter.links` |
| `source_path` | исходный путь документа | путь файла |
| `summary_text` | краткое содержание документа | секция `# Summary` |
| `doc_kind` | классификация документа, например `readme`, `spec`, `runbook` | `DocsClassifier.classify(path)` |
Связанные классы:
`DocsIndexingPipeline`, `DocsFrontmatterParser`, `DocsClassifier`, `DocsContentParser`, `DocsDocumentBuilder`
### `D2_FACT_INDEX`
Задача:
Хранит атомарные факты в форме `subject-predicate-object` для точного retrieval по утверждениям.
Формирование:
Факты извлекаются из frontmatter и секций документа, после чего каждая найденная тройка превращается в отдельную запись.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `fact_id` | идентификатор факта | вычисляется builder из содержимого факта и пути |
| `subject_id` | субъект факта | `DocsFactExtractor` |
| `predicate` | предикат или тип связи | `DocsFactExtractor` |
| `object` | значение или объект факта | `DocsFactExtractor` |
| `object_ref` | ссылка на объект, если она выделена отдельно | `DocsFactExtractor` |
| `anchor` | место в документе, откуда взят факт | `DocsFactExtractor` |
| `tags` | теги факта | `DocsFactExtractor` |
| `source_path` | исходный путь документа | путь файла |
Связанные классы:
`DocsIndexingPipeline`, `DocsFactExtractor`, `DocsDocumentBuilder`
### `D3_ENTITY_CATALOG`
Задача:
Хранит сущности, найденные в документации, чтобы искать документы и связи вокруг конкретной сущности.
Формирование:
Сущности извлекаются из frontmatter документа, после чего каждая сущность сохраняется отдельной записью.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `entity_name` | имя сущности | `DocsEntityExtractor` |
| `document_id` | идентификатор документа, где найдена сущность | `frontmatter.id`, иначе путь файла |
| `document_type` | тип документа-источника | `frontmatter.type` |
| `module` | модуль документа | `frontmatter.module` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `tags` | теги документа или сущности | `frontmatter.tags` |
| `source_path` | исходный путь документа | путь файла |
Связанные классы:
`DocsIndexingPipeline`, `DocsEntityExtractor`, `DocsDocumentBuilder`
### `D4_WORKFLOW_INDEX`
Задача:
Хранит workflow и сценарии из документации для ответов про flow, шаги и жизненный цикл процесса.
Формирование:
Workflow извлекаются из detail sections документа и сохраняются как отдельные сценарии.
Извлечение идет из структуры `Details -> ## Сценарий`.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `workflow_id` | идентификатор сценария | вычисляется builder из названия, anchor и документа |
| `document_id` | идентификатор документа-источника | `frontmatter.id`, иначе путь файла |
| `workflow_name` | название сценария | блок `Details -> ## Сценарий -> **Название**` |
| `preconditions` | предусловия сценария | блок `Details -> ## Сценарий -> **Предусловия**` |
| `trigger` | триггер или событие запуска | блок `Details -> ## Сценарий -> **Триггер**` |
| `main_flow` | основной сценарий | блок `Details -> ## Сценарий -> **Основной сценарий**` |
| `alternative_flow` | альтернативные ветки | блок `Details -> ## Сценарий -> **Альтернативный сценарий**` |
| `error_handling` | обработка ошибок | блок `Details -> ## Сценарий -> **Обработка ошибок**` |
| `postconditions` | постусловия | блок `Details -> ## Сценарий -> **Постусловие**` |
| `source_path` | исходный путь документа | путь файла |
Связанные классы:
`DocsIndexingPipeline`, `DocsWorkflowExtractor`, `DocsDocumentBuilder`
### `D5_RELATION_GRAPH`
Задача:
Хранит связи между документами и сущностями документации для navigation и related docs retrieval.
Формирование:
Связи извлекаются из frontmatter и сохраняются как отдельные relation edges.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `relation_id` | идентификатор связи | вычисляется builder из source, target, relation type и anchor |
| `source_id` | источник связи | `frontmatter.id` или source документа в extractor |
| `relation_type` | тип связи | `DocsRelationExtractor` |
| `target_id` | целевой объект связи | `DocsRelationExtractor` |
| `anchor` | место в документе, где обнаружена связь | `DocsRelationExtractor` |
| `source_path` | исходный путь документа | путь файла |
Связанные классы:
`DocsIndexingPipeline`, `DocsRelationExtractor`, `DocsDocumentBuilder`
### `D6_INTEGRATION_INDEX`
Задача:
Хранит прикладные интеграции компонента, API, UI, сущности или внешней системы.
Используется для ответов на вопросы вида "какие интеграции есть у компонента".
Формирование:
Интеграции извлекаются из блока `## Integrations` документа.
Одна интеграция должна превращаться в отдельную запись слоя.
Описание интеграции может быть развернутым, а структурированные атрибуты должны выделяться в словарь.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `integration_id` | идентификатор интеграции | вычисляется builder из source, target и anchor |
| `source_id` | идентификатор объекта, для которого описана интеграция | `frontmatter.id` документа-источника |
| `source_type` | тип исходного объекта | `frontmatter.doc_type` |
| `target` | целевой объект интеграции | блок `## Integrations` |
| `target_type` | тип целевого объекта, например `api`, `ui`, `entity`, `service`, `external_system` | блок `## Integrations` |
| `direction` | направление интеграции | блок `## Integrations` |
| `interaction` | тип взаимодействия | блок `## Integrations` |
| `via` | технический канал интеграции | блок `## Integrations` |
| `purpose` | назначение интеграции | блок `## Integrations` |
| `details` | дополнительные атрибуты интеграции в виде словаря | блок `## Integrations` |
| `domain` | домен документа | `frontmatter.domain` |
| `subdomain` | поддомен документа | `frontmatter.subdomain` |
| `source_path` | исходный путь документа | путь файла |
| `anchor` | место в документе, где описана интеграция | блок `## Integrations` |
Связанные классы:
`DocsIndexingPipeline`, `DocsIntegrationExtractor`, `DocsDocumentBuilder`
## Слои CODE
### `C0_SOURCE_CHUNKS`
Задача:
Хранит фрагменты исходного кода как базовый слой для цитирования, explain и точечной догрузки кода.
Формирование:
Исходный файл режется на кодовые чанки, и для каждого чанка создается отдельная запись.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `chunk_index` | порядковый номер чанка в файле | индекс чанка при нарезке |
| `chunk_type` | тип чанка, например функция, класс или текстовый блок | `CodeTextChunker` |
| `module_or_unit` | модуль, к которому относится chunk | вычисляется из пути файла |
| `is_test` | признак тестового файла | `is_test_path(path)` |
Связанные классы:
`CodeIndexingPipeline`, `CodeTextChunker`, `CodeTextDocumentBuilder`
### `C1_SYMBOL_CATALOG`
Задача:
Хранит символы кода: классы, функции и методы. Используется для поиска по именам и структуре кода.
Формирование:
Символы извлекаются `SymbolExtractor`, и каждый символ сохраняется как отдельная запись.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `symbol_id` | идентификатор символа | `SymbolExtractor` |
| `qname` | полное квалифицированное имя | `SymbolExtractor` |
| `kind` | тип символа: класс, функция, метод | `SymbolExtractor` |
| `signature` | сигнатура символа | `SymbolExtractor` |
| `parent_symbol_id` | родительский символ | `SymbolExtractor` |
| `package_or_module` | модуль или пакет символа | вычисляется из пути файла |
| `is_test` | признак тестового файла | `is_test_path(path)` |
Связанные классы:
`CodeIndexingPipeline`, `PythonAstParser`, `SymbolExtractor`, `SymbolDocumentBuilder`
### `C2_DEPENDENCY_GRAPH`
Задача:
Хранит связи между символами кода: вызовы, импорты, наследование. Используется для анализа зависимостей и flow.
Формирование:
Связи строятся `EdgeExtractor` по AST и списку символов, после чего каждая связь сохраняется отдельной записью.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `edge_id` | идентификатор связи | `EdgeExtractor` |
| `edge_type` | тип связи: вызов, импорт, наследование | `EdgeExtractor` |
| `src_symbol_id` | исходный символ | `EdgeExtractor` |
| `src_qname` | полное имя исходного символа | `EdgeExtractor` |
| `dst_symbol_id` | целевой символ, если он разрешен | `EdgeExtractor` |
| `dst_ref` | текстовая ссылка на целевой символ | `EdgeExtractor` |
| `resolution` | статус разрешения связи | `EdgeExtractor` |
| `is_test` | признак тестового файла | `is_test_path(path)` |
Связанные классы:
`CodeIndexingPipeline`, `EdgeExtractor`, `EdgeDocumentBuilder`
### `C3_ENTRYPOINTS`
Задача:
Хранит точки входа приложения: HTTP routes, CLI commands и другие entrypoints.
Формирование:
Детекторы ищут HTTP и CLI точки входа по символам файла, после чего каждый найденный entrypoint сохраняется отдельной записью.
Фиксация в БД:
| Атрибут в `metadata_json` | Описание | Источник |
|---|---|---|
| `entry_id` | идентификатор точки входа | detector entrypoint model |
| `entry_type` | тип точки входа | detector entrypoint model |
| `framework` | framework, в котором найдена точка входа | detector entrypoint model |
| `route_or_command` | route или команда | detector entrypoint model |
| `handler_symbol_id` | идентификатор обработчика | detector entrypoint model |
| `handler_symbol` | имя обработчика | detector entrypoint model |
| `declaring_symbol` | символ, в котором объявлен entrypoint | detector entrypoint model |
| `entrypoint_kind` | вид точки входа | detector entrypoint model |
| `http_method` | HTTP-метод | detector entrypoint model |
| `route_path` | путь маршрута | detector entrypoint model |
| `decorator_text` | текст декоратора или объявления | detector entrypoint model |
| `summary_text` | краткое описание точки входа | detector entrypoint model |
| `is_test` | признак тестового файла | `is_test_path(path)` |
| `lang_payload` | дополнительные данные детектора | detector metadata |
| `artifact_type` | тип артефакта, здесь `CODE` | константа builder |
Связанные классы:
`CodeIndexingPipeline`, `EntrypointDetectorRegistry`, `FastApiEntrypointDetector`, `FlaskEntrypointDetector`, `TyperClickEntrypointDetector`, `EntrypointDocumentBuilder`
### `C4_SEMANTIC_ROLES`
Задача:
Слой объявлен в enum и retrieval-планах как слой семантических ролей кода.
Формирование:
Слой формируется на основе символов, связей, dataflow slices и execution traces.
В текущем runtime этот слой не используется как активный маршрут, так как домен `CODE` отключен.
Фиксация в БД:
Смысловые атрибуты слоя сохраняются в `rag_chunks.metadata_json`.
Точное краткое описание состава этих атрибутов в текущем документе пока не зафиксировано.
Связанные классы:
`CodeIndexingPipeline`, `SemanticRoleBuilder`, `SemanticRoleDocumentBuilder`
_process/04. Analitycs artefacts.md
+62
View File
@@ -314,11 +314,71 @@ LLM не должна каждый раз тонуть в полном доку
- функциональные требования;
- UI;
- API;
- integrations;
- ошибки;
- НФТ;
- связи;
- кодовые привязки.
### Блок `## Integrations`
Если у объекта есть интеграции, они должны быть выделены в отдельный блок `## Integrations`.
Интеграции не нужно дублировать во frontmatter.
Основное описание хранится в body документа.
Ожидаемый принцип:
- одна интеграция = одна отдельная запись внутри блока;
- у интеграции есть краткое имя;
- у интеграции есть структурированные атрибуты;
- дополнительные детали допускаются в свободной форме через вложенный словарь.
Рекомендуемые атрибуты интеграции:
- `target`
- `target_type`
- `direction`
- `interaction`
- `via`
- `purpose`
- `details`
Где:
- `target` - идентификатор или имя целевого объекта;
- `target_type` - тип цели: `api`, `ui`, `entity`, `service`, `queue`, `db`, `external_system`;
- `direction` - направление: `inbound`, `outbound`, `bidirectional`;
- `interaction` - тип взаимодействия: `calls`, `reads`, `writes`, `emits`, `consumes`, `depends_on`;
- `via` - технический канал интеграции;
- `purpose` - зачем нужна интеграция;
- `details` - словарь с гибкой структурой под дополнительные параметры.
Пример:
```md
## Integrations
### Orders API
- target: api.orders.create
- target_type: api
- direction: outbound
- interaction: calls
- via: POST /api/orders
- purpose: создание заказа
- details:
- auth: service-token
- retry: true
### Order Entity
- target: domain.order
- target_type: entity
- direction: outbound
- interaction: writes
- via: repository
- purpose: сохранение состояния заказа
- details:
- transaction: required
```
Этот блок должен быть пригоден и для чтения человеком, и для последующего извлечения в отдельный RAG-слой интеграций.
## 1.10. Общие требования к markdown body
1. В документе должен быть один `H1`, совпадающий с `title`.
@@ -428,6 +488,7 @@ UI-элементы должны храниться в **табличном** и
## Технический use case
## Функциональные требования
## Contract
## Integrations
## Errors
## Нефункциональные требования
## Связанные блоки логики
@@ -454,6 +515,7 @@ UI-элементы должны храниться в **табличном** и
## Контекст
## Технический use case
## Функциональные требования
## Integrations
## Ограничения и условия вызова
## Нефункциональные требования
## Связанные API / UI / integration points
_process/05. MVP - process_v1.md
+100
View File
@@ -0,0 +1,100 @@
# MVP: процесс v1
## 1. Общее описание
Запрос пользователя обрабатывается цепочкой API → рантайм агента → зарегистрированный процесс версии `v1` → один workflow из трёх последовательных шагов. Процесс **не** обращается к RAG и **не** маршрутизирует интенты: текст сообщения передаётся в LLM по фиксированному промпту. Ответ агента — результат генерации с лёгкой постобработкой (trim).
```mermaid
flowchart LR
subgraph api [API]
RS[RequestService]
end
subgraph runtime [Agent runtime]
AR[AgentRuntime]
PR[ProcessRunner]
end
subgraph v1 [Процесс v1]
P1[V1Process]
WG[V1FlowMainGraph]
end
subgraph wf [Workflow v1.flow_main]
S1[PrepareUserMessageStep]
S2[GenerateAnswerStep]
S3[FinalizeAnswerStep]
end
LLM[AgentLlmService]
RS --> AR
AR --> PR
PR --> P1
P1 --> WG
WG --> S1 --> S2 --> S3
S2 --> LLM
```
Клиент создаёт запрос с `process_version: v1`. `AgentRuntime` поднимает `RuntimeExecutionContext` (запрос, сессия, publisher, trace), выбирает `V1Process` из реестра и вызывает `run`. `V1Process` собирает `V1FlowContext` и прогоняет линейный граф: подготовка текста, один вызов LLM, финализация строки ответа. Итог попадает в `ProcessResult.answer` и дальше в ответ пользователю.
---
## 2. Шаги и контракты
### 2.1. Вход в процесс: `V1Process.run`
| | |
|--|--|
| **Название** | Запуск процесса v1 |
| **Задача** | Собрать контекст workflow и выполнить граф до готового ответа. |
| **Вход** | `RuntimeExecutionContext`: `request` (в т.ч. `message`), `session`, `publisher`, `trace`. |
| **Выход** | `ProcessResult` с полем `answer: str`. |
| **Как работает** | Создаётся `V1FlowContext` с `prompt_name` по умолчанию `v1_flow_main.answer`. Вызывается `V1FlowMainGraph.run`. Возвращается ответ из контекста workflow. |
Код: `src/app/core/agent/processes/v1/process.py`.
---
### 2.2. Шаг workflow: `PrepareUserMessageStep`
| | |
|--|--|
| **Название** | Подготовка сообщения пользователя |
| **Задача** | Сформировать строку, которая уйдёт в LLM как пользовательский ввод. |
| **Вход** | `V1FlowContext` с заполненным `runtime` и `prompt_name`. |
| **Выход** | Тот же контекст с `prepared_message: str`. |
| **Как работает** | Берётся `context.runtime.request.message` и обрезаются пробелы по краям (`strip`). Результат пишется в `prepared_message`. Других преобразований нет. |
Код: `src/app/core/agent/processes/v1/workflow/flow_main/steps/prepare_user_message_step.py`.
---
### 2.3. Шаг workflow: `GenerateAnswerStep`
| | |
|--|--|
| **Название** | Вызов LLM |
| **Задача** | Сгенерировать ответ по выбранному промпту и подготовленному сообщению. |
| **Вход** | `V1FlowContext` с `prepared_message`, `prompt_name`, `runtime.trace` для модуля LLM. |
| **Выход** | Контекст с `answer: str` (сырой ответ модели). |
| **Как работает** | Асинхронно в пуле потоков вызывается `AgentLlmService.generate(prompt_name, prepared_message, ...)`. В trace подключается модуль `workflow.v1.llm`. Идентификатор запроса передаётся в `log_context` для логов. |
Код: `src/app/core/agent/processes/v1/workflow/flow_main/steps/generate_answer_step.py`.
---
### 2.4. Шаг workflow: `FinalizeAnswerStep`
| | |
|--|--|
| **Название** | Финализация ответа |
| **Задача** | Нормализовать строку ответа перед выдачей пользователю. |
| **Вход** | `V1FlowContext` с заполненным `answer` после LLM. |
| **Выход** | Контекст с обновлённым `answer`. |
| **Как работает** | К ответу применяется `strip()` по краям. Другой логики нет. |
Код: `src/app/core/agent/processes/v1/workflow/flow_main/steps/finalize_answer_step.py`.
---
### 2.5. Транспорт: `WorkflowGraph` (v1)
Граф для v1 использует стандартный `WorkflowGraph`: на каждом шаге пишутся события `workflow_started`, `step_started`, `step_completed`, `workflow_completed` в `runtime_traces` через `context.runtime.trace`.
Код: `src/app/core/agent/utils/workflow/graph.py`, обёртка `V1FlowMainGraph` в `src/app/core/agent/processes/v1/workflow/flow_main/graph.py`.
_process/05. MVP - process_v2.md
+220
View File
@@ -0,0 +1,220 @@
# MVP: процесс v2
## 1. Общее описание
Процесс v2 в текущем MVP ориентирован в первую очередь на **документацию проекта**, но роутер также поддерживает `GENERAL / GENERAL_QA / SUMMARY` для общих обзорных вопросов. Для документных веток нужна активная RAG-сессия с проиндексированными документами.
Это **узкий MVP**, а не полная target architecture. Поддерживаются три маршрута:
- `GENERAL`
- `GENERAL_QA`
- `SUMMARY`
- `DOCS`
- `DOC_EXPLAIN`
- `SUMMARY`
- `FIND_FILES`
Запрос проходит следующие смысловые этапы:
1. проверка готовности сессии;
2. intent routing;
3. формирование retrieval-параметров;
4. retrieval из `DOCS RAG`;
5. минимальная сборка evidence;
6. запуск task-focused workflow нужной ветки;
7. формирование ответа.
```mermaid
flowchart TB
subgraph api [API]
RS[RequestService]
end
subgraph runtime [Agent runtime]
AR[AgentRuntime]
PR[ProcessRunner]
end
subgraph v2 [Процесс v2]
P2[V2Process]
IR[V2IntentRouter]
POL[V2RetrievalPolicyResolver]
AD[V2RagRetrievalAdapter]
RSR[RagSessionRetriever]
ASM[DocsEvidenceAssembler]
end
subgraph rag [Пакет rag]
RR[RagRepository]
end
subgraph wf [Workflow]
SUM[DocsExplainSummaryGraph]
FF[DocsExplainFindFilesGraph]
end
LLM[AgentLlmService]
RS --> AR --> PR --> P2
P2 --> IR --> POL --> AD --> RSR --> RR
AD --> ASM
ASM --> SUM
ASM --> FF
SUM --> LLM
```
Клиент указывает `process_version: v2`. Без `active_rag_session_id` в сессии процесс возвращает сообщение об ошибке. Иначе выполняется цепочка:
маршрутизация → `RetrievalPlan` → retrieval строк из `DOCS RAG` → минимальная сборка evidence → ветвление по `subintent` → запуск workflow.
### Реализованные домены, интенты и сабинтенты
В коде заданы константы `V2Domain`, `V2Intent`, `V2Subintent`. Сейчас процесс intentionally ограничен одной рабочей областью.
| Уровень | Значение (строка) | Реализация |
|--------|-------------------|------------|
| **Домен (routing_domain)** | `DOCS` | Единственный поддерживаемый домен: документация проекта. |
| **Интент** | `DOC_EXPLAIN` | Единственный интент: объяснение по документации. |
| **Сабинтент** | `SUMMARY` | Объяснение темы по SUMMARY-блокам документации. |
| **Сабинтент** | `FIND_FILES` | Поиск путей к документам, где описана нужная сущность или тема. |
Итого в текущем MVP реализована **одна** рабочая тройка домен×интент: `DOCS` + `DOC_EXPLAIN`, с **двумя** ветками по сабинтенту.
---
## 2. Этапы вне workflow (внутри `V2Process.run`)
### 2.1. `V2IntentRouter.route`
| | |
|--|--|
| **Название** | Маршрутизация запроса (v2) |
| **Задача** | Определить домен, интент, subintent и извлечь якоря из текста. |
| **Вход** | `user_query: str` (текст сообщения пользователя). |
| **Выход** | `V2RouteResult`: `routing_domain`, `intent`, `subintent`, `user_query`, `normalized_query`, `target_terms`, `anchors` (`V2RouteAnchors`), `confidence`. |
| **Как работает** | Router реализован по схеме **LLM-first**: `normalization` → `target_terms`/`anchors extraction` → `LLM router` → `deterministic validator` → `fallback`. LLM является **основным селектором маршрута**. Deterministic-слой больше не выбирает маршрут по умолчанию: он отвечает только за extraction, валидацию enum/комбинаций и fallback при сломанном или невалидном ответе LLM. В trace пишется событие `intent_routed`. |
Код: `src/app/core/agent/processes/v2/intent_router/router.py`, `modules/normalizer.py`, `modules/target_terms.py`, `modules/anchors.py`, `routers/llm.py`, `routers/validator.py`, `routers/fallback.py`.
---
### 2.2. `V2RetrievalPolicyResolver.resolve`
| | |
|--|--|
| **Название** | Политика retrieval для v2 |
| **Задача** | По результату роутинга выбрать профиль, список слоёв RAG и лимит строк выдачи. |
| **Вход** | `V2RouteResult`. |
| **Выход** | `RetrievalPlan`: `profile`, `layers`, `limit`, опционально `filters`. |
| **Как работает** | Это отдельный смысловой шаг между routing и retrieval. Он не ходит в БД и не извлекает данные, а только подготавливает параметры поиска. Для `FIND_FILES` выбирается один профиль слоёв и лимит, для `SUMMARY` — другой. Лог: `retrieval_plan_resolved`. |
Код: `src/app/core/agent/processes/v2/retrieval/policy_resolver.py`.
---
### 2.3. `V2RagRetrievalAdapter` → `RagSessionRetriever.retrieve`
| | |
|--|--|
| **Название** | Загрузка сырых строк из RAG по плану |
| **Задача** | Делегировать поиск в единственную реализацию retrieval в пакете `rag`. |
| **Вход** | `rag_session_id`, `query_text` (нормализованный запрос), `RetrievalPlan`. |
| **Выход** | `list[dict]` — строки чанков в формате `RagRepository.retrieve` (поля `path`, `layer`, `metadata`, и т.д.). |
| **Как работает** | Выполняется retrieval по уже сформированному плану: профиль, список слоёв и лимит. На этом шаге происходит только извлечение сырых строк из `DOCS RAG`. Лог: `rag_rows_fetched`. |
Код адаптера: `src/app/core/agent/processes/v2/retrieval/v2_rag_adapter.py`.
Код API: `src/app/core/rag/retrieval/session_retriever.py`.
---
### 2.4. `DocsEvidenceAssembler`
| | |
|--|--|
| **Название** | Сборка evidence для задачи |
| **Задача** | Превратить сырые строки retrieval в списки summary или кандидатов файлов с дедупом и скорингом. |
| **Вход** | Список строк `rows`, `V2RouteResult` (для `target_terms`). |
| **Выход** | `list[RetrievedSummary]` или `list[RetrievedFile]`. |
| **Как работает** | Это **минимальная evidence-проверка**, достаточная для MVP. Для `SUMMARY` отбрасываются записи без summary-текста и summary-like секции, затем применяется дедуп и простой скоринг по терминам. Для `FIND_FILES` остаются только релевантные пути документов, также с дедупом и простым скорингом. Здесь нет сложной многоступенчатой валидации: задача шага — отфильтровать очевидный шум и передать в workflow компактное evidence. Лог: `evidence_assembled`. |
Код: `src/app/core/agent/processes/v2/evidence/assembler.py`.
---
## 3. Шаги workflow
Текущие workflow являются **task-focused**: каждая ветка решает одну узкую прикладную задачу и не содержит общей универсальной логики для всех типов вопросов.
### 3.1. Ветка `SUMMARY`: `GenerateSummaryAnswerStep`
| | |
|--|--|
| **Название** | Сборка ответа по summary |
| **Задача** | Сформировать ответ пользователю по найденным SUMMARY-блокам или сообщить об отсутствии. |
| **Вход** | `DocsExplainSummaryContext`: `runtime`, `route`, `rag_session_id`, `prompt_name`, `documents` (список `RetrievedSummary`). |
| **Выход** | Контекст с `answer: str`, `prompt_input` при успешном вызове LLM. |
| **Как работает** | Workflow получает уже отобранные summary-документы. Если документов нет — возвращает честный fallback-ответ. Иначе собирает prompt input из запроса пользователя и найденных summary-блоков и вызывает LLM. Workflow не занимается retrieval и не строит retrieval-план: он решает только задачу генерации ответа по уже подготовленному evidence. |
Код: `src/app/core/agent/processes/v2/workflows/docs_explain_summary/steps/generate_summary_answer_step.py`.
Граф: `DocsExplainSummaryGraph` (`V2WorkflowGraph`).
---
### 3.2. Ветка `FIND_FILES`: `FinalizeFindFilesAnswerStep`
| | |
|--|--|
| **Название** | Сборка списка файлов |
| **Задача** | Вывести пользователю markdown-список путей к файлам документации. |
| **Вход** | `DocsExplainFindFilesContext`: `runtime`, `route`, `rag_session_id`, `files` (`RetrievedFile`). |
| **Выход** | Контекст с `answer: str`. |
| **Как работает** | Workflow получает уже собранный список файлов и формирует финальный ответ. Если файлов нет — возвращает fallback. Если файлы есть — отдает детерминированный список путей. Эта ветка intentionally не использует LLM, потому что задача сводится к выдаче путей, а не к генерации объяснения. |
Код: `src/app/core/agent/processes/v2/workflows/docs_explain_find_files/steps/finalize_find_files_answer_step.py`.
Граф: `DocsExplainFindFilesGraph` (`V2WorkflowGraph`).
---
### 3.3. Транспорт: `V2WorkflowGraph`
| | |
|--|--|
| **Название** | Workflow v2 с буфером trace |
| **Задача** | Выполнить шаги без пошаговых `step_started`/`step_completed` в trace; один раз сбросить сводку. |
| **Вход** | Контекст workflow (`DocsExplainSummaryContext` или `DocsExplainFindFilesContext`). |
| **Выход** | Обновлённый контекст. |
| **Как работает** | Для каждого шага: `trace_input` до `run`, затем `run`, затем `trace_output`; записи копятся в список. В trace уходят `workflow_started`, затем `workflow_trace_flushed` с массивом шагов, затем `workflow_completed`. Статусы пользователю публикуются через `publisher` как и раньше. |
Код: `src/app/core/agent/processes/v2/workflows/v2_workflow_graph.py`.
---
## 4. Сборка в приложении
В `ModularApplication` создаются `RagSessionRetriever`, `V2RagRetrievalAdapter`, `V2RetrievalPolicyResolver`, `DocsEvidenceAssembler` и передаются в `V2Process` (см. `src/app/core/application.py`).
---
## 5. Итоговая концептуальная схема текущего MVP
В концептуальном виде текущий `v2` работает так:
1. **Session check**
Проверка, что есть активная RAG-сессия проекта.
2. **LLM-first intent routing**
Нормализация, extraction (`target_terms`, `anchors`), затем основной выбор маршрута через LLM.
3. **Deterministic validation + fallback**
Проверка enum/комбинации маршрута и fallback только если LLM не ответил или вернул невалидный маршрут.
4. **Retrieval parameter planning**
Формирование профиля поиска, слоёв и лимитов.
5. **RAG retrieval**
Загрузка сырых строк из `DOCS RAG`.
6. **Minimal evidence assembly**
Дедуп, базовый скоринг, отбор полезных summary или файлов.
7. **Task-focused workflow**
Узкая ветка `SUMMARY` или `FIND_FILES`.
8. **Final response**
Либо explanation через LLM, либо детерминированный список файлов.
Это и есть актуальная архитектура **узкого MVP**, синхронизированная с текущей реализацией.
_process/components/v2_intent_router_architecture.md
+346
View File
@@ -0,0 +1,346 @@
# V2IntentRouter Architecture
## 1. Архитектура
Текущий `V2IntentRouter` реализован как **LLM-first router**.
Deterministic-слой не выбирает маршрут по умолчанию и используется только для:
- preprocessing
- validation ответа LLM
- fallback, если LLM не ответил или вернул невалидный маршрут
Актуальные компоненты:
- `router.py`
Главная точка входа и оркестратор пайплайна.
- `modules/normalizer.py`
Нормализация текста запроса в `normalized_query`.
- `modules/target_terms.py`
Извлечение retrieval-oriented `target_terms`, `endpoint_paths`, `matched_aliases`, `alias_docs`.
- `modules/anchors.py`
Извлечение `anchors` и marker-сигналов для fallback и downstream retrieval.
- `routers/route_catalog.py`
Каталог допустимых маршрутов (`allowed_routes`).
- `routers/llm.py`
Основной LLM-router. Получает нормализованный запрос, `target_terms`, `anchors` и список допустимых маршрутов.
- `routers/validator.py`
Deterministic validator для enum-значений, комбинации маршрута и базовой нормализации `confidence`.
- `routers/confidence.py`
Пост-обработка confidence после ответа LLM.
- `routers/fallback.py`
Fallback-маршрутизация, если LLM не ответил или ответ не прошёл validator.
- `routers/prompts.yml`
Prompt-контракт для LLM-router.
## 2. Контракт
### Вход
- `user_query: str`
### Выход
`V2RouteResult`:
- `routing_domain: str`
- `intent: str`
- `subintent: str`
- `user_query: str`
- `normalized_query: str`
- `target_terms: list[str]`
- `anchors: V2RouteAnchors`
- `confidence: float`
- `routing_mode: str`
- `llm_router_used: bool`
- `reason_short: str`
`V2RouteAnchors`:
- `entity_names: list[str]`
- `file_names: list[str]`
- `endpoint_paths: list[str]`
- `target_doc_hints: list[str]`
- `matched_aliases: list[str]`
- `process_domain: str | None`
- `process_subdomain: str | None`
## 3. Поддерживаемые домены, интенты и сабинтенты
### Домены
- `DOCS`
- `GENERAL`
### Интенты
- `DOC_EXPLAIN`
- `GENERAL_QA`
### Сабинтенты
- `SUMMARY`
- `FIND_FILES`
### Допустимые маршруты
- `GENERAL / GENERAL_QA / SUMMARY`
- `DOCS / DOC_EXPLAIN / SUMMARY`
- `DOCS / DOC_EXPLAIN / FIND_FILES`
Эти маршруты централизованно заданы в `routers/route_catalog.py`.
## 4. Актуальный флоу
Пайплайн обработки запроса:
1. `router.py` принимает `user_query`.
2. `modules/normalizer.py` строит `normalized_query`.
3. `modules/target_terms.py` извлекает:
- `target_terms`
- `endpoint_paths`
- `matched_aliases`
- `alias_docs`
4. `modules/anchors.py` строит:
- `anchors`
- `file_markers`
- `architecture_markers`
- `logic_markers`
- `domain_markers`
- `endpoint_markers`
5. `router.py` собирает `QueryFeatures`.
6. `routers/llm.py` вызывается как **основной селектор маршрута**.
7. `routers/validator.py` проверяет:
- что значения входят в допустимые enum
- что комбинация маршрута разрешена
- что `confidence` можно привести к `float`
8. `routers/confidence.py` корректирует confidence на основе силы сигналов.
9. Если ответ LLM валиден, возвращается `V2RouteResult` с `routing_mode="llm_default"`.
10. Если LLM не ответил, вернул сломанный JSON или невалидный маршрут, `routers/fallback.py` строит fallback route:
- `FIND_FILES`, если есть `file_markers`
- `DOCS / DOC_EXPLAIN / SUMMARY`, если есть docs-oriented anchors
- иначе `GENERAL / GENERAL_QA / SUMMARY`
## 5. Компоненты по флоу
### `router.py`
- Задача
Оркестрировать полный routing pipeline.
- Как решает
Последовательно вызывает:
- normalizer
- target terms extractor
- anchor extractor
- LLM router
- validator
- confidence adjuster
- fallback router
- Вход
`user_query: str`
- Выход
`V2RouteResult`
### `modules/normalizer.py`
- Задача
Привести запрос к стабильной форме для анализа.
- Как решает
Схлопывает лишние пробелы через `" ".join(...split())`.
- Вход
`user_query: str`
- Выход
`normalized_query: str`
### `modules/target_terms.py`
- Задача
Построить **чистое retrieval-поле** `target_terms`.
- Как решает
Использует позитивную модель отбора и включает в `target_terms` только:
- endpoint paths
- identifier-like tokens
- alias canonical terms
- domain terms
Исключаются:
- question words
- intent words
- filler/noisy words
- marker words
- короткие токены `< 3`, если это не endpoint или alias
- битые path-like токены
Дополнительно:
- lowercase
- trim punctuation по краям
- dedupe
- ограничение до `7` элементов
- приоритет: endpoints → identifiers → aliases → domain terms
- Вход
`normalized_query: str`
- Выход
`TargetTermsAnalysis`:
- `target_terms`
- `endpoint_paths`
- `matched_aliases`
- `alias_docs`
### `modules/anchors.py`
- Задача
Построить `anchors` и marker-сигналы, не смешивая их с `target_terms`.
- Как решает
Извлекает:
- `entity_names` из PascalCase-like токенов
- `file_names` только по жёстким правилам:
- `*.md`, `*.yaml`, `*.yml`, `*.json`
- `docs/...`, `doc/...`, `documentation/...`
- `endpoint_paths` из `TargetTermsAnalysis`
- `target_doc_hints` из alias docs, endpoint map и marker-сигналов
Marker-сигналы живут отдельно:
- `file_markers`
- `architecture_markers`
- `logic_markers`
- `domain_markers`
- `endpoint_markers`
- Вход
- `normalized_query: str`
- `TargetTermsAnalysis`
- Выход
`AnchorAnalysis`
### `routers/route_catalog.py`
- Задача
Держать один источник истины для допустимых маршрутов.
- Как решает
Возвращает:
- список `allowed_routes` для payload LLM
- проверку допустимости комбинации `routing_domain + intent + subintent`
### `routers/llm.py`
- Задача
Выбрать маршрут через LLM как основной селектор.
- Как решает
Формирует JSON payload из:
- `normalized_query`
- `target_terms`
- `anchors`
- `allowed_routes`
Затем:
- вызывает LLM
- парсит JSON
- возвращает сырой candidate route без deterministic business-routing
- Вход
- `normalized_query: str`
- `target_terms: list[str]`
- `anchors: dict`
- Выход
`dict | None`
### `routers/validator.py`
- Задача
Deterministic validation ответа LLM.
- Как решает
Проверяет:
- что `routing_domain`, `intent`, `subintent` заполнены
- что комбинация маршрута входит в `route_catalog`
- что `confidence` можно привести к числу
- Вход
`dict | None`
- Выход
Валидированный `dict | None`
### `routers/confidence.py`
- Задача
Сделать confidence осмысленным после ответа LLM.
- Как решает
Корректирует confidence:
- `-0.1`, если нет strong anchors
- `-0.1`, если запрос короткий или vague
- `+0.05`, если есть явный signal (`file_markers`, `endpoint_paths`, `endpoint_markers`)
- затем clamp в диапазон `0.0..1.0`
- Вход
- `confidence: float`
- `QueryFeatures`
- Выход
`confidence: float`
### `routers/fallback.py`
- Задача
Построить deterministic fallback, если LLM невалиден.
- Как решает
Правила:
- есть `file_markers` → `DOCS / DOC_EXPLAIN / FIND_FILES`
- есть docs-signals (`endpoint_paths`, `target_doc_hints`, `matched_aliases`, marker groups) → `DOCS / DOC_EXPLAIN / SUMMARY`
- иначе → `GENERAL / GENERAL_QA / SUMMARY`
- Вход
- `user_query: str`
- `QueryFeatures`
- `anchors: V2RouteAnchors`
- `llm_attempted: bool`
- Выход
`V2RouteResult`
### `routers/prompts.yml`
- Задача
Задать LLM-router контракт ответа и guidance по confidence.
- Как решает
Ограничивает модель только `allowed_routes` и требует JSON с полями:
- `routing_domain`
- `intent`
- `subintent`
- `confidence`
- `reason_short`
## 6. Ключевые инварианты
- LLM является default router.
- Deterministic-слой не принимает основной routing decision.
- `target_terms` содержат только retrieval-useful terms.
- `anchors` не содержат `terms`.
- `/health` и другие endpoint paths не должны попадать в `file_names`, если это не файл с расширением.
- `file_names` содержат только реальные file/doc paths.
- Fallback используется только если LLM недоступен или вернул невалидный маршрут.
_process/components/v2_retrieval_policy_resolver_architecture.md
+316
View File
@@ -0,0 +1,316 @@
# V2RetrievalPolicyResolver Architecture
## 1. Роль компонента
`V2RetrievalPolicyResolver` это deterministic bridge между `V2IntentRouter` и docs-RAG retrieval.
Компонент работает поверх уже готового `V2RouteResult` и не делает повторную интерпретацию пользовательского текста:
- не вызывает LLM;
- не меняет `intent` и `subintent`;
- не ранжирует документы;
- не собирает evidence.
Его задача: собрать один `RetrievalPlan` с полями:
- `profile`
- `layers`
- `limit`
- `filters`
## 2. Зависимости
Актуальная реализация опирается на:
- `src/app/core/agent/processes/v2/retrieval/policy_resolver.py`
- `src/app/core/agent/processes/v2/anchor_signals.py`
- `src/app/core/agent/processes/v2/models.py`
- `src/app/core/rag/contracts/enums.py`
- `src/app/core/agent/processes/v2/retrieval/v2_rag_adapter.py`
- `src/app/core/rag/retrieval/session_retriever.py`
- `src/app/core/rag/persistence/repository.py`
- `src/app/core/rag/persistence/query_repository.py`
- `src/app/core/rag/persistence/retrieval_statement_builder.py`
## 3. Входной контракт
Resolver использует:
- `route.intent`
- `route.subintent`
- `route.anchors.entity_names`
- `route.anchors.file_names`
- `route.anchors.endpoint_paths`
- `route.anchors.target_doc_hints`
- `route.anchors.matched_aliases`
- `route.anchors.process_domain`
- `route.anchors.process_subdomain`
`route.target_terms` в текущей реализации profile/filter branching не влияет.
## 4. Верхнеуровневый branching
`resolve(route)` имеет три ветки:
1. `GENERAL_QA` -> `general_qa_grounded_summary`
2. `FIND_FILES` -> `file_lookup`
3. иначе -> docs summary branch
Инварианты:
- `GENERAL_QA` всегда остаётся general profile;
- `FIND_FILES` всегда остаётся `file_lookup`;
- resolver всегда возвращает один валидный `RetrievalPlan`.
## 5. Внутренняя декомпозиция
Текущая реализация разбита на два helper-класса.
### `_AnchorTermCollector`
Собирает термы для `prefer_like_patterns`.
Источники:
- basename из `target_doc_hints`
- `endpoint_paths`
- `file_names`
- `entity_names`
- `matched_aliases`
- `process_domain`
- `process_subdomain`
Все значения нормализуются в lower-case и превращаются в SQL-like patterns вида `"%term%"`.
Для `FIND_FILES` действует отдельное правило:
- если есть `target_doc_hints`, `prefer_like_patterns` строится только по basename hints;
- иначе используется общий набор collected terms.
### `_RouteFilterBuilder`
Собирает `filters` для трёх веток:
- `general_filters(route)`
- `summary_filters(route)`
- `find_files_filters(route)`
Дополнительно содержит path selection:
- `_summary_prefixes(route)`
- `_find_files_prefixes(route)`
- `_find_files_prefer_prefixes(route)`
## 6. Signal detection
Summary profile и часть path preferences зависят от `anchor_signal_types(route)`.
Сигналы вычисляются так:
- `FIND_FILES`
- если `route.subintent == FIND_FILES`
- `API_ENDPOINT`
- если есть `endpoint_paths`
- или в `target_doc_hints` / `file_names` / `matched_aliases` встречаются маркеры `"/api/"`, `"api"`, `"endpoint"`
- `ARCHITECTURE`
- если в `target_doc_hints` / `file_names` / `matched_aliases` встречаются `"/architecture/"`, `"architecture"`, `"arch"`
- `LOGIC_FLOW`
- если в `target_doc_hints` / `file_names` / `matched_aliases` встречаются `"/logic/"`, `"logic"`, `"workflow"`, `"flow"`, `"process"`
- `DOMAIN_ENTITY`
- если есть `entity_names`
- или в `target_doc_hints` / `file_names` / `matched_aliases` встречаются `"/domains/"`, `"domain"`, `"entity"`, `"component"`
Важно:
- `process_domain` и `process_subdomain` сейчас **не участвуют** в signal detection;
- они влияют только на filters и `prefer_like_patterns`.
## 7. Summary profile selection
Метод `_summary_profile(route)` использует:
- `meaningful = anchor_signal_types(route) - {FIND_FILES}`
Правило:
- если meaningful signal не ровно один -> `docs_summary_generic`
- если ровно один:
- `API_ENDPOINT` -> `docs_summary_api_endpoint`
- `ARCHITECTURE` -> `docs_summary_architecture`
- `LOGIC_FLOW` -> `docs_summary_logic_flow`
- `DOMAIN_ENTITY` -> `docs_summary_domain_entity`
Следствие:
- конфликт API + architecture -> generic;
- API + entity -> generic;
- weak/no signals -> generic.
## 8. Profiles, layers, limits
### `general_qa_grounded_summary`
- condition: `route.intent == GENERAL_QA`
- layers: `[D1_DOCUMENT_CATALOG, D0_DOC_CHUNKS]`
- limit: `8`
### `file_lookup`
- condition: `route.subintent == FIND_FILES`
- layers: `[D1_DOCUMENT_CATALOG, D3_ENTITY_CATALOG]`
- limit: `12`
### `docs_summary_api_endpoint`
- layers: `[D1_DOCUMENT_CATALOG, D2_FACT_INDEX, D0_DOC_CHUNKS]`
- limit: `8`
### `docs_summary_logic_flow`
- layers: `[D4_WORKFLOW_INDEX, D1_DOCUMENT_CATALOG, D0_DOC_CHUNKS]`
- limit: `8`
### `docs_summary_domain_entity`
- layers: `[D3_ENTITY_CATALOG, D1_DOCUMENT_CATALOG, D0_DOC_CHUNKS]`
- limit: `8`
### `docs_summary_architecture`
- layers: `[D1_DOCUMENT_CATALOG, D5_RELATION_GRAPH, D0_DOC_CHUNKS]`
- limit: `8`
### `docs_summary_generic`
- layers: `[D1_DOCUMENT_CATALOG, D0_DOC_CHUNKS]`
- limit: `8`
## 9. Filters by branch
### General branch
`general_filters(route)` возвращает:
- `prefer_path_prefixes = ["docs/architecture/", "docs/"]`
- `prefer_like_patterns = ["%readme.md%", "%overview%"]`
- `target_doc_hints = list(route.anchors.target_doc_hints)`
Это обзорный, но не узкий plan: hard `path_prefixes` здесь нет.
### Summary branch
`summary_filters(route)` всегда включает:
- `target_doc_hints`
- `metadata.domain`, если есть `process_domain`
- `metadata.subdomain`, если есть `process_subdomain`
- `prefer_path_prefixes`
- `prefer_like_patterns`
Дополнительно:
- если есть `API_ENDPOINT` signal, добавляется hard `path_prefixes = ["docs/api/", "docs/"]`
`prefer_path_prefixes` для summary:
- API -> `["docs/api/", "docs/"]`
- ARCHITECTURE -> `["docs/architecture/", "docs/"]`
- LOGIC_FLOW -> `["docs/logic/", "docs/architecture/", "docs/"]`
- DOMAIN_ENTITY -> `["docs/domains/", "docs/", "docs/api/"]`
- empty signals -> `["docs/"]`
Если сигналов несколько, prefixes объединяются и dedupe-ятся с сохранением порядка.
### FIND_FILES branch
`find_files_filters(route)` всегда включает:
- `target_doc_hints`
- `metadata.domain`, если есть `process_domain`
- `metadata.subdomain`, если есть `process_subdomain`
- `path_prefixes`
- `prefer_path_prefixes`
- `prefer_like_patterns`
`path_prefixes` для `FIND_FILES` выбираются по приоритету:
1. директории из `target_doc_hints`
2. директории из `file_names`, если путь начинается с `docs/`
3. signal-based fallback:
- API -> `["docs/api/", "docs/"]`
- ARCHITECTURE -> `["docs/architecture/", "docs/"]`
- LOGIC_FLOW -> `["docs/logic/", "docs/"]`
- DOMAIN_ENTITY -> `["docs/domains/", "docs/"]`
4. default -> `["docs/"]`
`prefer_path_prefixes` для `FIND_FILES`:
- начинается с `path_prefixes`
- если есть `process_domain` или `process_subdomain`, дополнительно добавляет:
- `"docs/domains/"`
- `"docs/logic/"`
## 10. Hard и soft сигналы в текущей реализации
В терминах текущего кода:
Hard-ish / narrowing filters:
- `path_prefixes`
- `metadata.domain`
- `metadata.subdomain`
Soft preferences:
- `prefer_path_prefixes`
- `prefer_like_patterns`
Отдельно:
- `target_doc_hints` всегда сохраняются в `RetrievalPlan.filters`, но **не маппятся напрямую** в `RagRepository.retrieve(...)` как SQL hard filter.
То есть сейчас `target_doc_hints` это не прямой DB filter, а downstream anchor для других шагов пайплайна и для deterministic exact-doc seeding logic.
## 11. Интеграция с retrieval stack
Следующий слой после resolver теперь исполняет plan не напрямую в `V2Process`, а через `V2RagRetrievalAdapter`.
`V2RagRetrievalAdapter.fetch_rows(...)` использует `RetrievalPlan` так:
- читает `filters["target_doc_hints"]` из самого плана;
- делает exact-path seed через `retrieve_exact_files(...)`;
- для missing hints делает substring fallback через `retrieve_chunks_by_path_substrings(...)`;
- затем делает обычный semantic retrieve через `RagSessionRetriever.retrieve(...)`;
- объединяет exact / substring / semantic rows через dedupe merge.
Это важный сдвиг: execution strategy теперь зависит от **контракта `RetrievalPlan`**, а не от скрытой route-specific логики внутри `V2Process`.
`RagSessionRetriever._map_filters()` прокидывает в `RagRepository.retrieve(...)`:
- `path_prefixes`
- `exclude_path_prefixes`
- `exclude_like_patterns`
- `prefer_path_prefixes`
- `prefer_like_patterns`
- `prefer_non_tests`
- `metadata_domain` из `filters["metadata.domain"]`
- `metadata_subdomain` из `filters["metadata.subdomain"]`
`RetrievalStatementBuilder.build_retrieve(...)` добавляет SQL predicates:
- `lower(metadata_json->>'domain') = :metadata_domain`
- `lower(metadata_json->>'subdomain') = :metadata_subdomain`
Таким образом:
- `process_domain/process_subdomain` реально участвуют в retrieval query;
- `target_doc_hints` реально участвуют в retrieval execution strategy на уровне adapter;
- `V2RetrievalPolicyResolver` определяет plan contract, а следующий шаг исполняет этот contract более буквально.
## 12. Актуальные ограничения
- Логика полностью deterministic.
- `target_terms` сейчас не участвуют в branching resolver.
- `process_domain/process_subdomain` не влияют на summary profile selection.
- API signal добавляет `path_prefixes` даже в generic summary, если среди конфликтующих сигналов присутствует API.
- `target_doc_hints` не являются прямым SQL filter внутри обычного `retrieve`, но используются adapter-уровнем для exact-path / substring seeding до semantic retrieval.
docs/documentation/rag/architecture-overview.md
+8 -16
View File
@@ -37,11 +37,11 @@ tags:
- Scope: модуль индексации проектных файлов, хранения RAG-слоёв и выдачи retrieval-контекста.
- Purpose: построить индекс по документации и Python-коду и дать runtime доступ к релевантным фрагментам.
- Main modules: `RagModule`, `RagService`, `IndexingOrchestrator`, `RagRepository`, `RepoWebhookService`.
- Main modules: `RagModule`, `RagService`, `IndexingOrchestrator`, `RagRepository`.
- Main domains: RAG-сессии, задачи индексации, документы индекса, blob-cache, retrieval.
- Main integrations: PostgreSQL/pgvector, GigaChat embeddings, FastAPI, EventBus, story context.
- Key entrypoints: `/api/rag/sessions`, `/api/rag/sessions/{rag_session_id}/changes`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`, `/internal/rag-repo/webhook`.
- Key data flows: snapshot indexing, incremental reindex, retrieval из `rag_chunks`, webhook-нормализация коммитов.
- Key entrypoints: `/api/rag/sessions`, `/api/rag/sessions/{rag_session_id}/changes`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`, `/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events`.
- Key data flows: snapshot indexing, incremental reindex, retrieval из `rag_chunks`.
- Source of truth: код `src/app/modules/rag/*`.
## Назначение
@@ -50,7 +50,7 @@ tags:
## Контекст
Модуль используется как инфраструктурный слой для agent/runtime и смежных интеграций. На вход он принимает либо список файлов проекта, либо webhook репозитория. На выходе формирует устойчивый индекс, ассоциированный с `rag_session_id`, и статус задач индексации, пригодный для опроса и SSE-подписки.
Модуль используется как инфраструктурный слой для agent/runtime. На вход он принимает snapshot и изменения файлов проекта. На выходе формирует устойчивый индекс, ассоциированный с `rag_session_id`, и статус задач индексации, пригодный для опроса и SSE-подписки.
## Границы системы
@@ -74,7 +74,7 @@ tags:
## Архитектурная схема
`RagModule` собирает зависимости модуля и публикует HTTP endpoints. Для индексации он использует `RagSessionStore`, `IndexJobStore`, `IndexingOrchestrator` и `RagService`. `RagService` выбирает docs/code pipeline, обогащает документы метаданными файла, запрашивает embeddings и записывает результат через `RagRepository`. `RagRepository` агрегирует schema/session/job/document/cache/query репозитории. Отдельно `RagRepoModule` принимает repository webhooks и прокидывает нормализованный commit context в story storage и cache writer.
`RagModule` собирает зависимости модуля и публикует HTTP endpoints. Для индексации он использует `RagSessionStore`, `IndexJobStore`, `IndexingOrchestrator` и `RagService`. `RagService` выбирает docs/code pipeline, обогащает документы метаданными файла, запрашивает embeddings и записывает результат через `RagRepository`. `RagRepository` агрегирует schema/session/job/document/cache/query репозитории.
## Основные модули
@@ -87,7 +87,6 @@ tags:
| `DocsIndexingPipeline` | построение слоёв документации `D1-D4` | classifier, chunker, document builder | `src/app/modules/rag/indexing/docs/pipeline.py` |
| `CodeIndexingPipeline` | построение слоёв кода `C0-C4` | AST parser, symbol/edge/entrypoint/role builders | `src/app/modules/rag/indexing/code/pipeline.py` |
| `RagRepository` | единая точка persistence и retrieval | schema/session/job/document/cache/query repositories | `src/app/modules/rag/persistence/repository.py` |
| `RepoWebhookService` | нормализация webhook payload и выделение story id | story writer, cache writer | `src/app/modules/rag/webhook_service.py` |
## Основные доменные области
@@ -104,9 +103,8 @@ tags:
| ------------------------ | --------- | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| PostgreSQL + pgvector | outbound | хранение документов, jobs, sessions и vector search | SQLAlchemy / SQL / pgvector | `logic-rag-retrieval` |
| GigaChat embeddings | outbound | получение embedding для batch документов | HTTP client через `GigaChatClient` | `logic-rag-indexing` |
| FastAPI | inbound | публичный и internal API модуля | HTTP | `api-rag-session-create`, `api-rag-session-changes`, `api-rag-session-job` |
| FastAPI | inbound | публичный HTTP API модуля | HTTP | `api-rag-session-create`, `api-rag-session-changes`, `api-rag-session-job` |
| EventBus | outbound | публикация прогресса индексации и terminal events | in-process async events / SSE | `api-rag-session-job` |
| Story context repository | outbound | запись webhook-коммитов для story | Python interface | `logic-rag-indexing` |
## Основные потоки
@@ -138,7 +136,7 @@ tags:
- Code indexing поддерживает только Python-файлы.
- Docs indexing ориентирован на markdown и frontmatter YAML.
- Deprecated endpoint `/internal/rag/retrieve` не используется для рабочего retrieval.
- HTTP retrieval endpoint в модуле не публикуется.
- Реальное retrieval API доступно через repository/runtime adapters, а не через публичный HTTP endpoint модуля.
### Risks
@@ -152,7 +150,6 @@ tags:
### Security
- Публичные endpoints не содержат собственной бизнес-авторизации внутри модуля и полагаются на внешний слой приложения.
- Webhook provider определяется по headers/payload без явной проверки подписи в самом `RepoWebhookService`.
### Reliability
@@ -164,7 +161,7 @@ tags:
- Logs: `RagService` пишет предупреждения по cache hit/miss и skipped files.
- Metrics: явные метрики не выделены.
- Traces: явная трассировка не реализована.
- Audit: job status и webhook commit binding сохраняются в БД.
- Audit: job status сохраняется в БД.
### Performance
@@ -191,16 +188,13 @@ tags:
- `src/app/modules/rag/indexing_service.py`
- `src/app/modules/rag/persistence/repository.py`
- `src/app/modules/rag/persistence/schema_repository.py`
- `src/app/modules/rag/webhook_service.py`
### Symbols
- `RagModule`
- `RagRepoModule`
- `RagService`
- `IndexingOrchestrator`
- `RagRepository`
- `RepoWebhookService`
## Связанные документы
@@ -218,5 +212,3 @@ tags:
| Date | Source | Changes |
| ---------- | ------ | ------------------------------------------------------------------- |
| 2026-03-13 | code | Создан обзор архитектуры пакета `rag` на основе текущей реализации. |
docs/documentation/rag/logic-indexing-pipeline.md
-2
View File
@@ -125,8 +125,6 @@ tags:
- `POST /api/rag/sessions`
- `POST /api/rag/sessions/{rag_session_id}/changes`
- `POST /internal/rag/index/snapshot`
- `POST /internal/rag/index/changes`
## Связанные сущности
docs/documentation/rag/logic-retrieval-ranking.md
+2 -2
View File
@@ -90,7 +90,7 @@ tags:
- Retrieval работает только внутри одной `rag_session_id` и не агрегирует несколько сессий.
- Layer ranking зашит в код SQL-builder и требует явного обновления при появлении новых слоёв.
- Полноценный HTTP retrieval endpoint в модуле отсутствует: `/internal/rag/retrieve` возвращает `410 deprecated`.
- Полноценный HTTP retrieval endpoint в модуле не публикуется.
## Нефункциональные требования
@@ -115,7 +115,7 @@ tags:
- Runtime retrieval adapters в `src/app/modules/agent/runtime/steps/retrieval/adapter.py`
- Explain retrieval gateway в `src/app/modules/agent/runtime/steps/explain/layered_gateway.py`
- Deprecated endpoint `POST /internal/rag/retrieve`
- HTTP retrieval endpoint отсутствует
## Связанные сущности
docs/intent-router-mvp.md
+32
View File
@@ -0,0 +1,32 @@
# DOCS Intent Router MVP
## Supported Intents
- `DOCS_QA.API_METHOD_EXPLAIN`
- `DOCS_DISCOVERY.LIST_API_METHODS`
- `DOCS_DISCOVERY.FIND_DOCUMENTS_BY_DOMAIN`
- `DOCS_GENERATION.GENERATE_OPENAPI`
- `DOCS_FALLBACK.GENERAL_DOCS_QA`
## Routing Flow
1. `Stage A`: deterministic pre-routing нормализует запрос, извлекает anchors и scope, считает rule-based confidence.
2. `Stage B`: confidence gating пропускает high-confidence кейсы напрямую и эскалирует ambiguous/weak запросы в LLM.
3. `Stage C`: LLM classifier выбирает только один из 5 MVP саб-интентов и возвращает строгий JSON.
4. После выбора саб-интента router всегда прикрепляет декларативный `retrieval_plan`.
## Confidence And Escalation
- `>= 0.8` и без конфликтующих сигналов: `routing_mode=deterministic`.
- Ниже порога, при пересечении интентов, слабых anchors или коротком неоднозначном запросе: `routing_mode=llm_assisted`.
- Если LLM недоступен или вернул невалидный класс: `routing_mode=llm_fallback` c fallback в `GENERAL_DOCS_QA`.
## Retrieval Plan Mapping
- `API_METHOD_EXPLAIN` -> `docs_api_method_explain_v1`
- `LIST_API_METHODS` -> `docs_list_api_methods_v1`
- `FIND_DOCUMENTS_BY_DOMAIN` -> `docs_find_documents_by_domain_v1`
- `GENERATE_OPENAPI` -> `docs_generate_openapi_v1`
- `GENERAL_DOCS_QA` -> `docs_general_docs_qa_v1`
`retrieval_plan` хранится декларативно в `src/app/modules/agent/intent_router_v2/docs_mvp/retrieval_plans.py`, а legacy `retrieval_spec.filters` обогащается теми же anchors и scope для совместимости с текущим runtime.
pipeline_setup_v3.md
+105
View File
@@ -0,0 +1,105 @@
`pipeline_setup_v3` это YAML-driven test harness для проверки agent pipeline на уровне сценариев, а не unit-тестов.
Как он работает:
- Берёт один YAML-файл или директорию с YAML-кейсами.
- Каждый кейс описывает:
- `id`
- `query`
- `runner`
- `mode`
- `input`
- `expected`
- Если в `input` нет готового `rag_session_id`, harness сам получает его:
- либо берёт из `input.rag_session_id`
- либо индексирует `input.repo_path` в RAG и кеширует полученную сессию для одинакового `(repo_path, project_id)`
Какие режимы кейсов есть:
- `router_only`
Проверяется только роутинг, без retrieval и без LLM.
- `router_rag`
Проверяется роутинг плюс retrieval, но без полной генерации ответа.
- `full_chain`
Проверяется полный pipeline: router → retrieval → downstream pipeline/LLM → final answer.
Как устроен execution flow:
1. Loader читает YAML и превращает каждый кейс в `V3Case`.
2. Runner для каждого кейса резолвит `rag_session_id`.
3. `AgentRuntimeAdapter` исполняет кейс в зависимости от `mode`.
4. Возвращаются два объекта:
- `actual`
- `details`
5. Validator сравнивает `actual/details` с `expected`.
6. Writer сохраняет:
- JSON с машинными результатами
- Markdown с человекочитаемой диагностикой
- итоговый `summary.md` по всему прогону
Что обычно лежит в `actual`:
- `intent`
- `sub_intent`
- `graph_id`
- `conversation_mode`
- `rag_count`
- `answer_mode`
- `llm_answer`
- `path_scope`
- `doc_scope`
- `entity_candidates`
- `symbol_candidates`
- `layers`
- `filters`
Что лежит в `details`:
- `router_result`
- `retrieval_request`
- `retrieval_result`
- `rag_rows`
- `diagnostics`
- `llm_request`
- `pipeline_steps`
- иногда `validation`, `token_usage`, `runtime_trace`
Что умеют expectations:
- `expected.router`
Проверяет `intent`, `sub_intent`, `graph_id`, `conversation_mode`
- `expected.retrieval`
Проверяет:
- пустой/непустой retrieval
- минимум строк
- наличие нужных слоёв
- path/doc scope
- symbol/entity candidates
- фильтры
- `expected.llm`
Проверяет:
- есть ли ответ
- содержит ли ответ обязательные фразы
- не содержит ли запрещённые фразы
- `answer_mode`
- `expected.pipeline`
Проверяет в основном итоговый `answer_mode`
Что важно при формулировке нового test case для ChatGPT:
- кейс должен описывать не “как реализовать код”, а “какой пользовательский сценарий проверяем”
- у кейса должны быть:
- понятный `query`
- корректный `mode`
- вход: `rag_session_id` или `repo_path`
- минимально достаточные `expected`
- не надо переописывать весь output, лучше проверять только ключевые инварианты
Хороший шаблон задания для ChatGPT:
1. Укажи, для какого suite нужен кейс.
2. Укажи `mode`: `router_only`, `router_rag` или `full_chain`.
3. Дай пользовательский `query`.
4. Опиши, что именно должно проверяться:
- роутинг
- retrieval layers/scope
- answer mode
- ключевые фразы в ответе
5. Попроси вернуть YAML-фрагмент в формате `pipeline_setup_v3`.
Пример формулировки для ChatGPT:
“Сформируй YAML test case для `pipeline_setup_v3` в режиме `full_chain`. Нужно проверить, что запрос `Объясни по документации как работает /health` маршрутизируется в docs-intent, retrieval использует docs layers, retrieval непустой, а ответ содержит `/health` и не содержит фраз про отсутствие данных.”
Если хочешь, я могу сразу подготовить тебе готовый prompt для ChatGPT, который будет генерировать новые кейсы в нужном формате.
runtime_traces/agent_requests/20260401/req_33758fd1ed834100a23fe95871b34181.md
-171
View File
@@ -1,171 +0,0 @@
# Request Trace: req_33758fd1ed834100a23fe95871b34181
- session_id: as_0bb449183cc242efaec50afd8193dcaf
- active_rag_session_id: 292cad80-45ef-4edb-a23c-82f01732d295
- process_version: v1
- created_at: 2026-04-01T09:27:07.987130+00:00
## User Message
Ты здесь?
## orchestrator
```json
{
"event": "bootstrap",
"status": "started",
"process_version": "v1"
}
```
## client_event
```json
{
"event": "status",
"source": "orchestrator",
"text": "Запрос принят и поставлен в обработку.",
"payload": {},
"created_at": "2026-04-01T09:27:07.987920+00:00"
}
```
## client_event
```json
{
"event": "status",
"source": "orchestrator",
"text": "Запускаю процесс обработки v1.",
"payload": {
"process_version": "v1"
},
"created_at": "2026-04-01T09:27:07.988004+00:00"
}
```
## orchestrator
```json
{
"event": "bootstrap",
"status": "completed"
}
```
## client_event
```json
{
"event": "status",
"source": "task_workflow",
"text": "Запускаю workflow simple_llm.",
"payload": {},
"created_at": "2026-04-01T09:27:07.988104+00:00"
}
```
## client_event
```json
{
"event": "status",
"source": "prompt_builder",
"text": "Формирую prompt payload для LLM.",
"payload": {},
"created_at": "2026-04-01T09:27:07.988150+00:00"
}
```
## task_workflow
```json
{
"event": "started",
"workflow_id": "simple_llm"
}
```
## llm
```json
{
"event": "request",
"prompt_name": "simple_llm_answer",
"system_prompt": "Ты полезный AI-ассистент проекта.\n\nНа вход приходит JSON с полем:\n- question\n\nПравила:\n- Отвечай как персонаж мемов из дагестана\n- Если вопрос неясный, аккуратно укажи, чего не хватает\n- Не выдумывай несуществующие факты о проекте\n- Формулируй ответ как обычное сообщение пользователю",
"user_prompt": "{\n \"question\": \"Ты здесь?\"\n}",
"log_context": "agent:req_33758fd1ed834100a23fe95871b34181"
}
```
## llm
```json
{
"event": "response",
"text": "Да тут я, на месте! А то в горах связи иногда нет, но ты лови ответ от меня, как пастух ловит сигнал телефона в ауле!"
}
```
## task_workflow
```json
{
"event": "completed",
"workflow_id": "simple_llm",
"prompt_name": "simple_llm_answer",
"answer_length": 117
}
```
## client_event
```json
{
"event": "status",
"source": "llm_process",
"text": "Ответ от LLM получен.",
"payload": {
"workflow_id": "simple_llm",
"prompt_name": "simple_llm_answer",
"answer_length": 117
},
"created_at": "2026-04-01T09:27:08.991752+00:00"
}
```
## orchestrator
```json
{
"event": "finalize",
"status": "started"
}
```
## client_event
```json
{
"event": "user",
"source": "agent",
"text": "Да тут я, на месте! А то в горах связи иногда нет, но ты лови ответ от меня, как пастух ловит сигнал телефона в ауле!",
"payload": {},
"created_at": "2026-04-01T09:27:08.992387+00:00"
}
```
## client_event
```json
{
"event": "status",
"source": "orchestrator",
"text": "Обработка запроса завершена.",
"payload": {},
"created_at": "2026-04-01T09:27:08.992694+00:00"
}
```
## orchestrator
```json
{
"event": "finalize",
"status": "completed"
}
```
## result
```json
{
"status": "done",
"answer": "Да тут я, на месте! А то в горах связи иногда нет, но ты лови ответ от меня, как пастух ловит сигнал телефона в ауле!",
"completed_at": "2026-04-01T09:27:08.994005+00:00"
}
```
runtime_traces/agent_requests/20260406-153629-250147960243.md
+265
View File
@@ -0,0 +1,265 @@
# Runtime Trace: 20260406-153629-250147960243
- active_rag_session_id: fdf3ff03-81f0-4772-b68e-250147960243
## request
```json
{
"request_id": "req_64906a91cdb6487ca2737a091cdaddab",
"session_id": "as_d60e71ff542642649c81221db325cbcc",
"active_rag_session_id": "fdf3ff03-81f0-4772-b68e-250147960243",
"process_version": "v2",
"created_at": "2026-04-06T15:36:29.264730+00:00",
"message": "Объясни по документации, как работает /health"
}
```
## process.v2
```json
{
"event": "intent_routed",
"routing_domain": "DOCS",
"intent": "DOC_EXPLAIN",
"subintent": "SUMMARY",
"normalized_query": "Объясни по документации, как работает /health",
"target_terms": [
"/health",
"как",
"работает"
],
"anchors": {
"terms": [
"/health",
"как",
"работает"
],
"entity_names": [],
"file_names": [
"/health"
],
"process_domain": null,
"process_subdomain": null
},
"confidence": 1.0,
"routing_mode": "deterministic",
"llm_router_used": false,
"reason_short": "deterministic signal",
"rag_session_id": "fdf3ff03-81f0-4772-b68e-250147960243"
}
```
## process.v2.retrieval_policy
```json
{
"event": "retrieval_plan_resolved",
"profile": "docs_explain_summary",
"layers": [
"D1_DOCUMENT_CATALOG",
"D3_ENTITY_CATALOG",
"D0_DOC_CHUNKS"
],
"limit": 12
}
```
## process.v2.rag_retrieval
```json
{
"event": "rag_rows_fetched",
"profile": "docs_explain_summary",
"row_count": 12,
"rows": [
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/README.md",
"title": "Индекс технической документации test_echo_app",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: ",
"section_path": "",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "Архитектура Telegram Notify App",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.",
"section_path": "",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D3_ENTITY_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "TelegramNotifyWorker",
"document_id": "architecture.telegram_notify_app",
"entity_name": "TelegramNotifyWorker",
"summary_text": "",
"section_path": "",
"content_preview": "TelegramNotifyWorker"
},
{
"layer": "D3_ENTITY_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "TelegramNotifyModule",
"document_id": "architecture.telegram_notify_app",
"entity_name": "TelegramNotifyModule",
"summary_text": "",
"section_path": "",
"content_preview": "TelegramNotifyModule"
},
{
"layer": "D3_ENTITY_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "TelegramSendService",
"document_id": "architecture.telegram_notify_app",
"entity_name": "TelegramSendService",
"summary_text": "",
"section_path": "",
"content_preview": "TelegramSendService"
},
{
"layer": "D3_ENTITY_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "TelegramControlChannel",
"document_id": "architecture.telegram_notify_app",
"entity_name": "TelegramControlChannel",
"summary_text": "",
"section_path": "",
"content_preview": "TelegramControlChannel"
},
{
"layer": "D3_ENTITY_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "RuntimeManager",
"document_id": "architecture.telegram_notify_app",
"entity_name": "RuntimeManager",
"summary_text": "",
"section_path": "",
"content_preview": "RuntimeManager"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Связанные документы",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Связанные документы",
"content_preview": "- [API /health](../api/health-endpoint.md)\n- [API /actions/{action}](../api/control-actions-endpoint.md)\n- [API /send](../api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](../logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](../domains/runtime-health-entity.md)"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Навигация",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Details > Навигация",
"content_preview": "- [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md)\n- [API /health](./api/health-endpoint.md)\n- [API /actions/{action}](./api/control-actions-endpoint.md)\n- [API /send](./api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](./logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](./domains/runtime-health-entity.md)\n- [Каталог ошибок]("
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Операторские и мониторинговые клиенты",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграции > Операторские и мониторинговые клиенты",
"content_preview": "- target: ext.operator_and_probes\n- target_type: external_system\n- direction: inbound\n- interaction: calls\n- via: HTTP `/health`, `/actions/{action}`, `/send`\n- purpose: диагностика, lifecycle-управление и ручная отправка сообщений\n- details:\n - transport: FastAPI + UvicornThreadRunner\n - status_mapping: non-ok health -> HTTP 503"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Summary",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Summary",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Контекст",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Контекст",
"content_preview": "Архитектурный документ описывает состав runtime и связи между контейнероподобными компонентами приложения. Детали контрактов HTTP API вынесены в документы endpoint'ов, а сценарий фоновой отправки и health-модель описаны на отдельных страницах."
}
]
}
```
## process.v2.evidence
```json
{
"event": "evidence_assembled",
"mode": "summary",
"document_count": 1
}
```
## workflow.v2.summary
```json
{
"event": "workflow_started",
"workflow_id": "v2.docs_explain.summary"
}
```
## workflow.v2.summary.llm
```json
{
"event": "request",
"prompt_name": "v2_docs_explain.summary_answer",
"system_prompt": "Ты объясняешь документацию только на основе найденных SUMMARY-блоков.\nИспользуй только факты из входного контекста.\nЕсли информации мало, прямо скажи об этом.\nВ конце перечисли файлы, на которые ты опирался.",
"user_prompt": "Запрос пользователя:\nОбъясни по документации, как работает /health\n\nНайденные SUMMARY-блоки:\n\n1. path: docs/architecture/telegram-notify-app-overview.md\ntitle: Архитектура Telegram Notify App\nsummary: - Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.md), [`/actions/{action}`](../api/control-actions-endpoint.md), [`/send`](../api/send-message-endpoint.md).\n- Related logic: [цикл отправки уведомлений](../logic/telegram-notification-loop.md).\n- Related domain: [runtime health](../domains/runtime-health-entity.md).",
"log_context": "agent:req_64906a91cdb6487ca2737a091cdaddab"
}
```
## workflow.v2.summary.llm
```json
{
"event": "response",
"text": "На основе представленной информации, можно сказать следующее:\n\nСервис \"Telegram Notify App\" предоставляет HTTP-интерфейс, включая endpoint `/health`. Эта информация содержится в блоке, где упомянуты связанные API (Related API). Однако подробностей о том, как именно работает данный endpoint, его функциональность или формат ответа, в предоставленных данных нет.\n\nФайлы, на которые я опирался:\n- docs/architecture/telegram-notify-app-overview.md"
}
```
## workflow.v2.summary
```json
{
"event": "workflow_trace_flushed",
"workflow_id": "v2.docs_explain.summary",
"steps": [
{
"step_id": "generate_summary_answer",
"title": "Сборка ответа по summary",
"input": {},
"output": {
"answer_length": 444
}
}
]
}
```
## workflow.v2.summary
```json
{
"event": "workflow_completed",
"workflow_id": "v2.docs_explain.summary"
}
```
## result
```json
{
"status": "done",
"answer": "На основе представленной информации, можно сказать следующее:\n\nСервис \"Telegram Notify App\" предоставляет HTTP-интерфейс, включая endpoint `/health`. Эта информация содержится в блоке, где упомянуты связанные API (Related API). Однако подробностей о том, как именно работает данный endpoint, его функциональность или формат ответа, в предоставленных данных нет.\n\nФайлы, на которые я опирался:\n- docs/architecture/telegram-notify-app-overview.md",
"completed_at": "2026-04-06T15:36:31.411613+00:00"
}
```
runtime_traces/agent_requests/20260407-175918-b17b76678614.md
+130
View File
@@ -0,0 +1,130 @@
# Runtime Trace: 20260407-175918-b17b76678614
- active_rag_session_id: 94851e51-1514-4a77-9570-b17b76678614
## request
```json
{
"request_id": "req_d9dae665c88b476db700a3f7bd210370",
"session_id": "as_da5ddd4aacd94ec5b7078dd69e06c9c6",
"active_rag_session_id": "94851e51-1514-4a77-9570-b17b76678614",
"process_version": "v1",
"created_at": "2026-04-07T17:59:18.592170+00:00",
"message": "Ты тут?"
}
```
## workflow.v1
```json
{
"event": "workflow_started",
"workflow_id": "v1.flow_main"
}
```
## workflow.v1
```json
{
"event": "step_started",
"workflow_id": "v1.flow_main",
"step_id": "prepare_user_message",
"input": {}
}
```
## workflow.v1
```json
{
"event": "step_completed",
"workflow_id": "v1.flow_main",
"step_id": "prepare_user_message",
"output": {
"prepared_message_length": 7
}
}
```
## workflow.v1
```json
{
"event": "step_started",
"workflow_id": "v1.flow_main",
"step_id": "generate_answer",
"input": {
"prompt_name": "v1_flow_main.answer",
"prepared_message_length": 7
}
}
```
## workflow.v1.llm
```json
{
"event": "request",
"prompt_name": "v1_flow_main.answer",
"system_prompt": "Ты полезный ассистент.\nОтветь на сообщение пользователя по существу.\nНе придумывай факты, если данных недостаточно.\nЕсли пользователь пишет по-русски, отвечай по-русски.",
"user_prompt": "Ты тут?",
"log_context": "agent:req_d9dae665c88b476db700a3f7bd210370"
}
```
## workflow.v1.llm
```json
{
"event": "response",
"text": "Да, я здесь! Чем могу помочь?"
}
```
## workflow.v1
```json
{
"event": "step_completed",
"workflow_id": "v1.flow_main",
"step_id": "generate_answer",
"output": {
"answer_length": 29
}
}
```
## workflow.v1
```json
{
"event": "step_started",
"workflow_id": "v1.flow_main",
"step_id": "finalize_answer",
"input": {
"answer_length_before_strip": 29
}
}
```
## workflow.v1
```json
{
"event": "step_completed",
"workflow_id": "v1.flow_main",
"step_id": "finalize_answer",
"output": {
"answer_length": 29
}
}
```
## workflow.v1
```json
{
"event": "workflow_completed",
"workflow_id": "v1.flow_main"
}
```
## result
```json
{
"status": "done",
"answer": "Да, я здесь! Чем могу помочь?",
"completed_at": "2026-04-07T17:59:19.326182+00:00"
}
```
runtime_traces/agent_requests/20260407-175948-92e685261a86.md
+1048
View File
File diff suppressed because it is too large Load Diff
runtime_traces/agent_requests/20260407-182058-3f56c69c7290.md
+622
View File
@@ -0,0 +1,622 @@
# Runtime Trace: 20260407-182058-3f56c69c7290
- active_rag_session_id: c8b893cc-cb13-4493-a6d1-3f56c69c7290
## request
```json
{
"request_id": "req_bab9c8812ac94847bb102cba68516f10",
"session_id": "as_4fdccc9c55c549faad8f3ef379371129",
"active_rag_session_id": "c8b893cc-cb13-4493-a6d1-3f56c69c7290",
"process_version": "v2",
"created_at": "2026-04-07T18:20:58.679614+00:00",
"message": "Как работает метод health?"
}
```
## process.v2
```json
{
"event": "intent_routed",
"routing_domain": "DOCS",
"intent": "DOC_EXPLAIN",
"subintent": "SUMMARY",
"normalized_query": "Как работает метод health?",
"target_terms": [
"метод",
"health"
],
"anchors": {
"entity_names": [],
"file_names": [],
"endpoint_paths": [],
"target_doc_hints": [],
"matched_aliases": [],
"process_domain": null,
"process_subdomain": null,
"signal_types": []
},
"confidence": 0.75,
"routing_mode": "llm_default",
"llm_router_used": true,
"reason_short": "Запрос на понимание работы конкретного метода \"health\".",
"rag_session_id": "c8b893cc-cb13-4493-a6d1-3f56c69c7290"
}
```
## process.v2.pipeline
```json
{
"event": "router_resolved",
"domain": "DOCS",
"intent": "DOC_EXPLAIN",
"subintent": "SUMMARY",
"confidence": 0.75
}
```
## process.v2.pipeline
```json
{
"event": "anchors_extracted",
"signal_types": [],
"endpoint_paths": [],
"target_doc_hints": [],
"matched_aliases": [],
"target_terms": [
"метод",
"health"
]
}
```
## process.v2.pipeline
```json
{
"event": "alias_resolution",
"resolved_aliases": [],
"target_doc_hints": []
}
```
## process.v2.retrieval_policy
```json
{
"event": "retrieval_plan_resolved",
"profile": "docs_summary_generic",
"layers": [
"D1_DOCUMENT_CATALOG",
"D0_DOC_CHUNKS"
],
"limit": 8,
"filters": {
"target_doc_hints": [],
"prefer_path_prefixes": [
"docs/"
],
"prefer_like_patterns": []
}
}
```
## process.v2.pipeline
```json
{
"event": "retrieval_profile_selected",
"profile": "docs_summary_generic",
"layers": [
"D1_DOCUMENT_CATALOG",
"D0_DOC_CHUNKS"
],
"filters": {
"target_doc_hints": [],
"prefer_path_prefixes": [
"docs/"
],
"prefer_like_patterns": []
}
}
```
## process.v2.rag_retrieval
```json
{
"event": "rag_rows_fetched",
"profile": "docs_summary_generic",
"row_count": 8,
"rows": [
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "Архитектура Telegram Notify App",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.",
"section_path": "",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/README.md",
"title": "Индекс технической документации test_echo_app",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: ",
"section_path": "",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Операторские и мониторинговые клиенты",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграции > Операторские и мониторинговые клиенты",
"content_preview": "- target: ext.operator_and_probes\n- target_type: external_system\n- direction: inbound\n- interaction: calls\n- via: HTTP `/health`, `/actions/{action}`, `/send`\n- purpose: диагностика, lifecycle-управление и ручная отправка сообщений\n- details:\n - transport: FastAPI + UvicornThreadRunner\n - status_mapping: non-ok health -> HTTP 503"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Связанные документы",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Связанные документы",
"content_preview": "- [API /health](../api/health-endpoint.md)\n- [API /actions/{action}](../api/control-actions-endpoint.md)\n- [API /send](../api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](../logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](../domains/runtime-health-entity.md)"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Навигация",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Details > Навигация",
"content_preview": "- [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md)\n- [API /health](./api/health-endpoint.md)\n- [API /actions/{action}](./api/control-actions-endpoint.md)\n- [API /send](./api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](./logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](./domains/runtime-health-entity.md)\n- [Каталог ошибок]("
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Summary",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Summary",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Summary",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Summary",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Интеграционные сценарии",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграционные сценарии",
"content_preview": "1. При старте `main()` загружает YAML-конфиг, извлекает host, port и интервал отправки, затем собирает runtime.\n2. `RuntimeManager` регистрирует `TelegramControlChannel` для HTTP control plane.\n3. `TelegramNotifyModule` добавляет `TelegramNotifyWorker` и `TelegramSendService` в runtime.\n4. Внешний клиент вызывает endpoint'ы control plane для health-check, lifecycle-операций или ручной отправки.\n5."
}
]
}
```
## process.v2.pipeline
```json
{
"event": "candidate_generation",
"query": "Как работает метод health?",
"profile": "docs_summary_generic",
"details": {
"target_doc_hints": [],
"candidates_before_ranking": [
"docs/architecture/telegram-notify-app-overview.md",
"docs/README.md",
"docs/architecture/telegram-notify-app-overview.md",
"docs/architecture/telegram-notify-app-overview.md",
"docs/README.md",
"docs/architecture/telegram-notify-app-overview.md",
"docs/README.md",
"docs/architecture/telegram-notify-app-overview.md"
]
},
"resolved_aliases": [],
"target_doc_hints": [],
"candidate_docs_before_ranking": [
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "Архитектура Telegram Notify App",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.",
"section_path": "",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/README.md",
"title": "Индекс технической документации test_echo_app",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: ",
"section_path": "",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Операторские и мониторинговые клиенты",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграции > Операторские и мониторинговые клиенты",
"content_preview": "- target: ext.operator_and_probes\n- target_type: external_system\n- direction: inbound\n- interaction: calls\n- via: HTTP `/health`, `/actions/{action}`, `/send`\n- purpose: диагностика, lifecycle-управление и ручная отправка сообщений\n- details:\n - transport: FastAPI + UvicornThreadRunner\n - status_mapping: non-ok health -> HTTP 503"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Связанные документы",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Связанные документы",
"content_preview": "- [API /health](../api/health-endpoint.md)\n- [API /actions/{action}](../api/control-actions-endpoint.md)\n- [API /send](../api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](../logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](../domains/runtime-health-entity.md)"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Навигация",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Details > Навигация",
"content_preview": "- [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md)\n- [API /health](./api/health-endpoint.md)\n- [API /actions/{action}](./api/control-actions-endpoint.md)\n- [API /send](./api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](./logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](./domains/runtime-health-entity.md)\n- [Каталог ошибок]("
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Summary",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Summary",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Summary",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Summary",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Интеграционные сценарии",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграционные сценарии",
"content_preview": "1. При старте `main()` загружает YAML-конфиг, извлекает host, port и интервал отправки, затем собирает runtime.\n2. `RuntimeManager` регистрирует `TelegramControlChannel` для HTTP control plane.\n3. `TelegramNotifyModule` добавляет `TelegramNotifyWorker` и `TelegramSendService` в runtime.\n4. Внешний клиент вызывает endpoint'ы control plane для health-check, lifecycle-операций или ручной отправки.\n5."
}
],
"sources": {
"seeded": [],
"metadata_lookup": [],
"semantic": [
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "Архитектура Telegram Notify App",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.",
"section_path": "",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/README.md",
"title": "Индекс технической документации test_echo_app",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: ",
"section_path": "",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Операторские и мониторинговые клиенты",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграции > Операторские и мониторинговые клиенты",
"content_preview": "- target: ext.operator_and_probes\n- target_type: external_system\n- direction: inbound\n- interaction: calls\n- via: HTTP `/health`, `/actions/{action}`, `/send`\n- purpose: диагностика, lifecycle-управление и ручная отправка сообщений\n- details:\n - transport: FastAPI + UvicornThreadRunner\n - status_mapping: non-ok health -> HTTP 503"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Связанные документы",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Связанные документы",
"content_preview": "- [API /health](../api/health-endpoint.md)\n- [API /actions/{action}](../api/control-actions-endpoint.md)\n- [API /send](../api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](../logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](../domains/runtime-health-entity.md)"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Навигация",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Details > Навигация",
"content_preview": "- [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md)\n- [API /health](./api/health-endpoint.md)\n- [API /actions/{action}](./api/control-actions-endpoint.md)\n- [API /send](./api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](./logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](./domains/runtime-health-entity.md)\n- [Каталог ошибок]("
}
]
}
}
```
## process.v2.pipeline
```json
{
"event": "retrieval_executed",
"query": "Как работает метод health?",
"profile": "docs_summary_generic",
"row_count": 8,
"target_doc_hints": [],
"top_results": [
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "Архитектура Telegram Notify App",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.",
"section_path": "",
"content_preview": "- Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint."
},
{
"layer": "D1_DOCUMENT_CATALOG",
"path": "docs/README.md",
"title": "Индекс технической документации test_echo_app",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: ",
"section_path": "",
"content_preview": "- Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: "
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Операторские и мониторинговые клиенты",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Интеграции > Операторские и мониторинговые клиенты",
"content_preview": "- target: ext.operator_and_probes\n- target_type: external_system\n- direction: inbound\n- interaction: calls\n- via: HTTP `/health`, `/actions/{action}`, `/send`\n- purpose: диагностика, lifecycle-управление и ручная отправка сообщений\n- details:\n - transport: FastAPI + UvicornThreadRunner\n - status_mapping: non-ok health -> HTTP 503"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/architecture/telegram-notify-app-overview.md",
"title": "architecture.telegram_notify_app:Связанные документы",
"document_id": "architecture.telegram_notify_app",
"entity_name": "",
"summary_text": "",
"section_path": "Архитектура Telegram Notify App > Details > Связанные документы",
"content_preview": "- [API /health](../api/health-endpoint.md)\n- [API /actions/{action}](../api/control-actions-endpoint.md)\n- [API /send](../api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](../logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](../domains/runtime-health-entity.md)"
},
{
"layer": "D0_DOC_CHUNKS",
"path": "docs/README.md",
"title": "index.test_echo_app_docs:Навигация",
"document_id": "index.test_echo_app_docs",
"entity_name": "",
"summary_text": "",
"section_path": "Индекс технической документации test_echo_app > Details > Навигация",
"content_preview": "- [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md)\n- [API /health](./api/health-endpoint.md)\n- [API /actions/{action}](./api/control-actions-endpoint.md)\n- [API /send](./api/send-message-endpoint.md)\n- [Логика цикла отправки уведомлений](./logic/telegram-notification-loop.md)\n- [Доменная модель runtime health](./domains/runtime-health-entity.md)\n- [Каталог ошибок]("
}
]
}
```
## process.v2.evidence
```json
{
"event": "evidence_assembled",
"mode": "summary",
"document_count": 2,
"documents": [
"docs/README.md",
"docs/architecture/telegram-notify-app-overview.md"
]
}
```
## process.v2.pipeline
```json
{
"event": "evidence_assembled",
"mode": "summary",
"primary_doc": "docs/README.md",
"document_count": 2
}
```
## process.v2.pipeline
```json
{
"event": "ranking_explained",
"doc": "docs/README.md",
"score_breakdown": {
"semantic": 20,
"path_match": 0,
"filename_match": 0,
"alias_match": 0,
"anchor_boost": 0,
"target_doc_boost": 0,
"generic_penalty": 0
},
"score": 20,
"match_reason": "semantic_match"
}
```
## process.v2.pipeline
```json
{
"event": "ranking_explained",
"doc": "docs/architecture/telegram-notify-app-overview.md",
"score_breakdown": {
"semantic": 20,
"path_match": 0,
"filename_match": 0,
"alias_match": 0,
"anchor_boost": 0,
"target_doc_boost": 0,
"generic_penalty": 0
},
"score": 20,
"match_reason": "semantic_match"
}
```
## process.v2.pipeline
```json
{
"event": "ranking_explained",
"top_docs_after_ranking": [
{
"doc": "docs/README.md",
"score": 20,
"match_reason": "semantic_match"
},
{
"doc": "docs/architecture/telegram-notify-app-overview.md",
"score": 20,
"match_reason": "semantic_match"
}
],
"ranking_score_breakdown": [
{
"doc": "docs/README.md",
"score_breakdown": {
"semantic": 20,
"path_match": 0,
"filename_match": 0,
"alias_match": 0,
"anchor_boost": 0,
"target_doc_boost": 0,
"generic_penalty": 0
}
},
{
"doc": "docs/architecture/telegram-notify-app-overview.md",
"score_breakdown": {
"semantic": 20,
"path_match": 0,
"filename_match": 0,
"alias_match": 0,
"anchor_boost": 0,
"target_doc_boost": 0,
"generic_penalty": 0
}
}
]
}
```
## process.v2.pipeline
```json
{
"event": "evidence_gate_checked",
"passed": true,
"reason": "target_doc_found",
"answer_mode": "grounded_summary"
}
```
## workflow.v2.summary
```json
{
"event": "workflow_started",
"workflow_id": "v2.docs_explain.summary"
}
```
## workflow.v2.summary.llm
```json
{
"event": "request",
"prompt_name": "v2_docs_explain.summary_answer",
"system_prompt": "Ты объясняешь документацию только на основе найденных SUMMARY-блоков.\nИспользуй только факты из входного контекста.\nЕсли информации мало, прямо скажи об этом и не додумывай детали.\nВ конце перечисли файлы, на которые ты опирался.",
"user_prompt": "Запрос пользователя:\nКак работает метод health?\n\nСигналы запроса:\n{\n \"entity_names\": [],\n \"file_names\": [],\n \"endpoint_paths\": [],\n \"target_doc_hints\": [],\n \"matched_aliases\": [],\n \"process_domain\": null,\n \"process_subdomain\": null,\n \"signal_types\": []\n}\n\nНайденные SUMMARY-блоки:\n\n1. path: docs/README.md\ntitle: Индекс технической документации test_echo_app\nmatch_reason: semantic_match\nsummary: - Purpose: точка входа в техническую документацию сервиса `test_echo_app`.\n- Scope: архитектура, HTTP API control plane, цикл отправки уведомлений, health-модель и каталог ошибок.\n- Canonical structure: `docs/architecture`, `docs/api`, `docs/logic`, `docs/domains`, `docs/errors`.\n- Primary parent doc: [Архитектура Telegram Notify App](./architecture/telegram-notify-app-overview.md).\n- Navigation: документы связаны через `related_docs`, `parent`/`children` и markdown-ссылки без дублирования деталей.\n\n2. path: docs/architecture/telegram-notify-app-overview.md\ntitle: Архитектура Telegram Notify App\nmatch_reason: semantic_match\nsummary: - Purpose: сервис поднимает HTTP control plane и фоновый worker для отправки уведомлений в Telegram.\n- Entry point: `src/telegram_notify_app/main.py`.\n- Main components: `RuntimeManager`, `TelegramControlChannel`, `TelegramNotifyModule`, `TelegramNotifyWorker`, `TelegramSendService`.\n- Configuration: `config/config.yaml` или путь из `CONFIG_PATH`.\n- Related API: [`/health`](../api/health-endpoint.md), [`/actions/{action}`](../api/control-actions-endpoint.md), [`/send`](../api/send-message-endpoint.md).\n- Related logic: [цикл отправки уведомлений](../logic/telegram-notification-loop.md).\n- Related domain: [runtime health](../domains/runtime-health-entity.md).",
"log_context": "agent:req_bab9c8812ac94847bb102cba68516f10"
}
```
## workflow.v2.summary.llm
```json
{
"event": "response",
"text": "На основе представленного контекста невозможно предоставить подробное объяснение работы метода health. \n\nФайлы, на которые я опирался:\n1. docs/README.md\n2. docs/architecture/telegram-notify-app-overview.md"
}
```
## workflow.v2.summary
```json
{
"event": "workflow_trace_flushed",
"workflow_id": "v2.docs_explain.summary",
"steps": [
{
"step_id": "generate_summary_answer",
"title": "Сборка ответа по summary",
"input": {},
"output": {
"answer_length": 205
}
}
]
}
```
## workflow.v2.summary
```json
{
"event": "workflow_completed",
"workflow_id": "v2.docs_explain.summary"
}
```
## process.v2.pipeline
```json
{
"event": "answer_generated",
"answer_mode": "grounded_summary",
"answer_length": 205
}
```
## result
```json
{
"status": "done",
"answer": "На основе представленного контекста невозможно предоставить подробное объяснение работы метода health. \n\nФайлы, на которые я опирался:\n1. docs/README.md\n2. docs/architecture/telegram-notify-app-overview.md",
"completed_at": "2026-04-07T18:21:01.793612+00:00"
}
```
runtime_traces/agent_requests/20260407-183339-3284d16c6cb0.md
+1138
View File
File diff suppressed because it is too large Load Diff
src/app/core/agent/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.runtime import AgentRuntime
__all__ = ["AgentRuntime"]
src/app/core/agent/processes/__init__.py
+10
View File
@@ -0,0 +1,10 @@
from app.core.agent.processes.base import AgentProcess, ProcessResult
from app.core.agent.processes.v1.process import V1Process
from app.core.agent.processes.v2.process import V2Process
__all__ = [
"AgentProcess",
"ProcessResult",
"V1Process",
"V2Process",
]
src/app/core/agent/processes/base.py
+21
View File
@@ -0,0 +1,21 @@
from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
@dataclass(slots=True)
class ProcessResult:
answer: str = ""
class AgentProcess(ABC):
version = ""
@abstractmethod
async def run(self, context: "RuntimeExecutionContext") -> ProcessResult:
raise NotImplementedError
src/app/core/agent/processes/v1/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.processes.v1.process import V1Process
__all__ = ["V1Process"]
src/app/core/agent/processes/v1/process.py
+22
View File
@@ -0,0 +1,22 @@
from __future__ import annotations
from app.core.agent.processes.base import AgentProcess, ProcessResult
from app.core.agent.processes.v1.workflow import V1FlowMainGraph
from app.core.agent.processes.v1.workflow.flow_main import V1FlowContext
from app.core.agent.utils.llm import AgentLlmService
class V1Process(AgentProcess):
version = "v1"
def __init__(self, llm: AgentLlmService, prompt_name: str = "v1_flow_main.answer") -> None:
self._prompt_name = prompt_name
self._workflow = V1FlowMainGraph(llm)
async def run(self, context) -> ProcessResult:
flow_context = V1FlowContext(
runtime=context,
prompt_name=self._prompt_name,
)
flow_context = await self._workflow.run(flow_context)
return ProcessResult(answer=flow_context.answer)
src/app/core/agent/processes/v1/workflow/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.processes.v1.workflow.flow_main.graph import V1FlowMainGraph
__all__ = ["V1FlowMainGraph"]
src/app/core/agent/processes/v1/workflow/flow_main/__init__.py
+7
View File
@@ -0,0 +1,7 @@
from app.core.agent.processes.v1.workflow.flow_main.context import V1FlowContext
from app.core.agent.processes.v1.workflow.flow_main.graph import V1FlowMainGraph
__all__ = [
"V1FlowContext",
"V1FlowMainGraph",
]
src/app/core/agent/processes/v1/workflow/flow_main/context.py
+13
View File
@@ -0,0 +1,13 @@
from __future__ import annotations
from dataclasses import dataclass
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
@dataclass(slots=True)
class V1FlowContext:
runtime: RuntimeExecutionContext
prompt_name: str
prepared_message: str = ""
answer: str = ""
src/app/core/agent/processes/v1/workflow/flow_main/graph.py
+24
View File
@@ -0,0 +1,24 @@
from __future__ import annotations
from app.core.agent.processes.v1.workflow.flow_main.context import V1FlowContext
from app.core.agent.processes.v1.workflow.flow_main.steps.finalize_answer_step import FinalizeAnswerStep
from app.core.agent.processes.v1.workflow.flow_main.steps.generate_answer_step import GenerateAnswerStep
from app.core.agent.processes.v1.workflow.flow_main.steps.prepare_user_message_step import PrepareUserMessageStep
from app.core.agent.utils.llm import AgentLlmService
from app.core.agent.utils.workflow import WorkflowGraph
class V1FlowMainGraph:
def __init__(self, llm: AgentLlmService) -> None:
self._graph = WorkflowGraph(
workflow_id="v1.flow_main",
source="workflow.v1",
steps=(
PrepareUserMessageStep(),
GenerateAnswerStep(llm),
FinalizeAnswerStep(),
),
)
async def run(self, context: V1FlowContext) -> V1FlowContext:
return await self._graph.run(context)
src/app/core/agent/processes/v1/workflow/flow_main/prompts.yml
+8
View File
@@ -0,0 +1,8 @@
namespace: v1_flow_main
prompts:
answer: |
Ты полезный ассистент.
Ответь на сообщение пользователя по существу.
Не придумывай факты, если данных недостаточно.
Если пользователь пишет по-русски, отвечай по-русски.
src/app/core/agent/processes/v1/workflow/flow_main/steps/__init__.py
+9
View File
@@ -0,0 +1,9 @@
from app.core.agent.processes.v1.workflow.flow_main.steps.finalize_answer_step import FinalizeAnswerStep
from app.core.agent.processes.v1.workflow.flow_main.steps.generate_answer_step import GenerateAnswerStep
from app.core.agent.processes.v1.workflow.flow_main.steps.prepare_user_message_step import PrepareUserMessageStep
__all__ = [
"FinalizeAnswerStep",
"GenerateAnswerStep",
"PrepareUserMessageStep",
]
src/app/core/agent/processes/v1/workflow/flow_main/steps/finalize_answer_step.py
+19
View File
@@ -0,0 +1,19 @@
from __future__ import annotations
from app.core.agent.processes.v1.workflow.flow_main.context import V1FlowContext
from app.core.agent.utils.workflow import WorkflowStep
class FinalizeAnswerStep(WorkflowStep[V1FlowContext]):
step_id = "finalize_answer"
title = "Финализация ответа"
async def run(self, context: V1FlowContext) -> V1FlowContext:
context.answer = context.answer.strip()
return context
def trace_input(self, context: V1FlowContext) -> dict[str, object]:
return {"answer_length_before_strip": len(context.answer)}
def trace_output(self, context: V1FlowContext) -> dict[str, object]:
return {"answer_length": len(context.answer)}
src/app/core/agent/processes/v1/workflow/flow_main/steps/generate_answer_step.py
+32
View File
@@ -0,0 +1,32 @@
from __future__ import annotations
import asyncio
from app.core.agent.processes.v1.workflow.flow_main.context import V1FlowContext
from app.core.agent.utils.llm import AgentLlmService
from app.core.agent.utils.workflow import WorkflowStep
class GenerateAnswerStep(WorkflowStep[V1FlowContext]):
step_id = "generate_answer"
title = "Вызов LLM"
def __init__(self, llm: AgentLlmService) -> None:
self._llm = llm
async def run(self, context: V1FlowContext) -> V1FlowContext:
request_id = context.runtime.request.request_id
context.answer = await asyncio.to_thread(
self._llm.generate,
context.prompt_name,
context.prepared_message,
log_context=f"agent:{request_id}",
trace=context.runtime.trace.module("workflow.v1.llm"),
)
return context
def trace_input(self, context: V1FlowContext) -> dict[str, object]:
return {"prompt_name": context.prompt_name, "prepared_message_length": len(context.prepared_message)}
def trace_output(self, context: V1FlowContext) -> dict[str, object]:
return {"answer_length": len(context.answer)}
src/app/core/agent/processes/v1/workflow/flow_main/steps/prepare_user_message_step.py
+16
View File
@@ -0,0 +1,16 @@
from __future__ import annotations
from app.core.agent.processes.v1.workflow.flow_main.context import V1FlowContext
from app.core.agent.utils.workflow import WorkflowStep
class PrepareUserMessageStep(WorkflowStep[V1FlowContext]):
step_id = "prepare_user_message"
title = "Подготовка сообщения"
async def run(self, context: V1FlowContext) -> V1FlowContext:
context.prepared_message = context.runtime.request.message.strip()
return context
def trace_output(self, context: V1FlowContext) -> dict[str, object]:
return {"prepared_message_length": len(context.prepared_message)}
src/app/core/agent/processes/v2/__init__.py
+4
View File
@@ -0,0 +1,4 @@
from app.core.agent.processes.v2.process import V2Process
from app.core.agent.processes.v2.intent_router.router import V2IntentRouter
__all__ = ["V2IntentRouter", "V2Process"]
src/app/core/agent/processes/v2/anchor_signals.py
+57
View File
@@ -0,0 +1,57 @@
from __future__ import annotations
from app.core.agent.processes.v2.models import V2AnchorType, V2RouteAnchors, V2RouteResult, V2Subintent
def anchor_signal_types(route: V2RouteResult) -> set[str]:
texts = _signal_texts(route)
signals: set[str] = set()
if route.subintent == V2Subintent.FIND_FILES:
signals.add(V2AnchorType.FIND_FILES)
if route.anchors.endpoint_paths or _has_any(texts, ("/api/", "api", "endpoint")):
signals.add(V2AnchorType.API_ENDPOINT)
if _has_any(texts, ("/architecture/", "architecture", "arch")):
signals.add(V2AnchorType.ARCHITECTURE)
if _has_any(texts, ("/logic/", "logic", "workflow", "flow", "process")):
signals.add(V2AnchorType.LOGIC_FLOW)
if route.anchors.entity_names or _has_any(texts, ("/domains/", "domain", "entity", "component")):
signals.add(V2AnchorType.DOMAIN_ENTITY)
return signals
def route_anchor_summary(route: V2RouteResult) -> dict[str, object]:
return {
"entity_names": list(route.anchors.entity_names),
"file_names": list(route.anchors.file_names),
"endpoint_paths": list(route.anchors.endpoint_paths),
"target_doc_hints": list(route.anchors.target_doc_hints),
"matched_aliases": list(route.anchors.matched_aliases),
"process_domain": route.anchors.process_domain,
"process_subdomain": route.anchors.process_subdomain,
"signal_types": sorted(anchor_signal_types(route)),
}
def anchors_have_signal(anchors: V2RouteAnchors, signal: str, *, subintent: str | None = None) -> bool:
route = V2RouteResult(
routing_domain="",
intent="",
subintent=subintent or "",
user_query="",
normalized_query="",
anchors=anchors,
)
return signal in anchor_signal_types(route)
def _signal_texts(route: V2RouteResult) -> list[str]:
items = [
*route.anchors.target_doc_hints,
*route.anchors.file_names,
*route.anchors.matched_aliases,
]
return [str(item).strip().lower() for item in items if str(item or "").strip()]
def _has_any(items: list[str], markers: tuple[str, ...]) -> bool:
return any(marker in item for item in items for marker in markers)
src/app/core/agent/processes/v2/evidence/assembler.py
+308
View File
@@ -0,0 +1,308 @@
"""Anchor-aware ranking для summary и find-files evidence."""
from __future__ import annotations
import re
from app.core.agent.processes.v2.anchor_signals import anchor_signal_types
from app.core.agent.processes.v2.models import RetrievedFile, RetrievedSummary, V2AnchorType, V2RouteResult
from app.core.agent.processes.v2.retrieval.target_doc_seeding import normalize_doc_path
from app.core.rag.contracts.enums import RagLayer
class DocsEvidenceAssembler:
_API_PATH_PREFIXES = ("docs/api/", "docs/endpoints/", "docs/methods/", "api/", "endpoints/", "methods/")
_GENERIC_DOC_MARKERS = ("readme", "overview", "index", "navigation", "related docs", "catalog")
def assemble_summaries(self, rows: list[dict], route: V2RouteResult) -> list[RetrievedSummary]:
items = self._rank_rows(rows, route, mode="summary")
ranked = [
RetrievedSummary(
path=item["path"],
title=item["title"],
summary=item["summary"],
document_id=item["document_id"],
score=item["score"],
confidence=min(1.0, item["score"] / 1000.0),
match_reason=item["match_reason"],
score_breakdown=item["score_breakdown"],
)
for item in items
if item["summary"] and self._summary_row_allowed(item["row"])
]
if ranked:
ranked[0].is_primary = True
return ranked[:3]
def assemble_files(self, rows: list[dict], route: V2RouteResult) -> list[RetrievedFile]:
items = self._rank_rows(rows, route, mode="find_files")
ranked = [
RetrievedFile(
path=item["path"],
title=item["title"],
document_id=item["document_id"],
score=item["score"],
confidence=min(1.0, item["score"] / 1000.0),
match_reason=item["match_reason"],
score_breakdown=item["score_breakdown"],
)
for item in items
]
if ranked:
ranked[0].is_primary = True
return ranked[:4]
def _rank_rows(self, rows: list[dict], route: V2RouteResult, *, mode: str) -> list[dict]:
seen: set[str] = set()
ranked: list[dict] = []
for row in rows:
path = self._path(row)
if not path or path in seen:
continue
seen.add(path)
breakdown = self._score_breakdown(row, route, mode=mode)
score = sum(breakdown.values())
if score <= 0:
continue
ranked.append(
{
"row": row,
"path": path,
"title": self._title(row, path),
"summary": self._summary(row),
"document_id": self._document_id(row, path),
"score": score,
"score_breakdown": breakdown,
"match_reason": self._match_reason(breakdown),
"is_generic_doc": self._is_generic_doc(path, self._title(row, path), self._summary(row), row),
}
)
ranked.sort(key=lambda item: (-item["score"], item["path"]))
ranked = self._ensure_target_docs_in_top_k(ranked, route, k=4 if mode == "find_files" else 3)
return self._promote_specific_primary(ranked, route)
def _score_breakdown(self, row: dict, route: V2RouteResult, *, mode: str) -> dict[str, int]:
path_raw = self._path(row)
path = path_raw.lower()
filename = path.split("/")[-1]
title = self._title(row, path).lower()
summary = self._summary(row).lower()
entity = self._entity_name(row).lower()
query_tokens = self._query_tokens(route)
path_tokens = self._path_tokens(path)
compact_haystack = {self._compact(path), self._compact(filename), self._compact(title), self._compact(entity)}
breakdown = {
"semantic": 0,
"path_match": 0,
"filename_match": 0,
"alias_match": 0,
"anchor_boost": 0,
"target_doc_boost": 0,
"specificity_boost": 0,
"generic_penalty": 0,
}
if route.intent == "GENERAL_QA":
breakdown["semantic"] += 80
hint_norm_lower = {normalize_doc_path(h).lower() for h in route.anchors.target_doc_hints if str(h or "").strip()}
if normalize_doc_path(path_raw).lower() in hint_norm_lower:
breakdown["target_doc_boost"] += 1000
hint_texts = [str(hint or "").strip().lower() for hint in route.anchors.target_doc_hints if str(hint or "").strip()]
if any(alias.lower() in " ".join([path, title, summary, entity]) for alias in route.anchors.matched_aliases):
breakdown["alias_match"] += 500
for token in query_tokens:
if token in path_tokens:
breakdown["path_match"] += 60
if token and token in filename:
breakdown["filename_match"] += 200
if token and token in summary:
breakdown["semantic"] += 20
if self._compact(token) in compact_haystack:
breakdown["alias_match"] += 250
for hint in hint_texts:
compact_hint = self._compact(hint)
if compact_hint and compact_hint in compact_haystack:
breakdown["target_doc_boost"] += 180
elif hint and hint.strip("/") in " ".join([path, title, summary, entity]):
breakdown["semantic"] += 70
endpoint_text = self._summary(row).lower()
for endpoint in route.anchors.endpoint_paths:
normalized_endpoint = endpoint.strip().lower()
endpoint_slug = normalized_endpoint.strip("/")
if normalized_endpoint and normalized_endpoint in endpoint_text:
breakdown["target_doc_boost"] += 260
if endpoint_slug and endpoint_slug in filename:
breakdown["filename_match"] += 200
if any(endpoint.strip("/").lower() in filename for endpoint in route.anchors.endpoint_paths):
breakdown["filename_match"] += 200
signals = anchor_signal_types(route)
breakdown["anchor_boost"] += self._anchor_boost(path, signals)
breakdown["specificity_boost"] += self._specificity_boost(row, path, title, summary, route)
breakdown["generic_penalty"] += self._generic_penalty(path, signals)
if mode == "find_files":
breakdown["path_match"] *= 3
breakdown["filename_match"] *= 2
breakdown["alias_match"] *= 1
breakdown["semantic"] = max(0, breakdown["semantic"] // 2)
return breakdown
def _anchor_boost(self, path: str, signals: set[str]) -> int:
boost = 0
if V2AnchorType.API_ENDPOINT in signals and path.startswith(self._API_PATH_PREFIXES):
boost += 360
if V2AnchorType.LOGIC_FLOW in signals and path.startswith("docs/logic/"):
boost += 300
if V2AnchorType.DOMAIN_ENTITY in signals and path.startswith("docs/domains/"):
boost += 300
if V2AnchorType.ARCHITECTURE in signals and path.startswith("docs/architecture/"):
boost += 300
if V2AnchorType.FIND_FILES in signals and path.startswith("docs/"):
boost += 120
return boost
def _generic_penalty(self, path: str, signals: set[str]) -> int:
penalty = 0
lowered = path.lower()
if path == "docs/README.md" and V2AnchorType.ARCHITECTURE not in signals:
penalty -= 260
if any(marker in lowered for marker in ("/readme", "readme.md", "/index", "/overview", "/catalog", "/navigation")):
penalty -= 220
if "/architecture/" in path and V2AnchorType.ARCHITECTURE not in signals and signals.intersection(
{V2AnchorType.API_ENDPOINT, V2AnchorType.DOMAIN_ENTITY}
):
penalty -= 150
return penalty
def _ensure_target_docs_in_top_k(self, ranked: list[dict], route: V2RouteResult, *, k: int) -> list[dict]:
if not ranked or not route.anchors.target_doc_hints:
return ranked
top = ranked[:k]
top_paths = {item["path"] for item in top}
top_norm = {normalize_doc_path(p).lower() for p in top_paths if p}
for hint in route.anchors.target_doc_hints:
hn = normalize_doc_path(hint).lower()
if hn in top_norm:
continue
candidate = next(
(item for item in ranked if normalize_doc_path(item["path"]).lower() == hn),
None,
)
if candidate is None:
continue
if len(top) < k:
top.append(candidate)
else:
top[-1] = candidate
top_paths = {item["path"] for item in top}
top_norm = {normalize_doc_path(p).lower() for p in top_paths if p}
remaining = [item for item in ranked if item["path"] not in top_paths]
top.sort(key=lambda item: (-item["score"], item["path"]))
return top + remaining
def _promote_specific_primary(self, ranked: list[dict], route: V2RouteResult) -> list[dict]:
if len(ranked) < 2:
return ranked
first = ranked[0]
if not first.get("is_generic_doc"):
return ranked
promoted = next((item for item in ranked[1:] if not item.get("is_generic_doc") and self._is_specific_candidate(item, route)), None)
if promoted is None:
return ranked
return [promoted] + [item for item in ranked if item["path"] != promoted["path"]]
def _match_reason(self, breakdown: dict[str, int]) -> str:
if breakdown["target_doc_boost"] > 0:
return "exact_path"
if breakdown["alias_match"] > 0:
return "alias_match"
if breakdown["filename_match"] > 0:
return "exact_title"
return "semantic_match"
def _summary_row_allowed(self, row: dict) -> bool:
metadata = dict(row.get("metadata") or {})
if row.get("layer") != RagLayer.DOCS_DOC_CHUNKS:
return True
section = str(metadata.get("section_path") or "").lower()
return "summary" in section or "свод" in section or "overview" in section
def _specificity_boost(self, row: dict, path: str, title: str, summary: str, route: V2RouteResult) -> int:
boost = 0
filename = path.split("/")[-1]
lowered_title = title.lower()
lowered_summary = summary.lower()
if not self._is_generic_doc(path, title, summary, row):
boost += 90
if path.startswith(self._API_PATH_PREFIXES):
boost += 160
if "endpoint" in filename or "endpoint" in lowered_title or "method" in lowered_title:
boost += 120
if row.get("layer") == RagLayer.DOCS_DOC_CHUNKS and not self._looks_like_navigation_chunk(row):
boost += 80
for token in self._query_tokens(route):
if token and token in filename:
boost += 90
if token and token in lowered_title:
boost += 70
if token and token in lowered_summary:
boost += 40
return boost
def _is_specific_candidate(self, item: dict, route: V2RouteResult) -> bool:
breakdown = dict(item.get("score_breakdown") or {})
if breakdown.get("target_doc_boost", 0) > 0:
return True
if breakdown.get("specificity_boost", 0) >= 160:
return True
return V2AnchorType.API_ENDPOINT in anchor_signal_types(route) and item["path"].startswith(self._API_PATH_PREFIXES)
def _is_generic_doc(self, path: str, title: str, summary: str, row: dict) -> bool:
haystack = " ".join([path.lower(), title.lower(), summary.lower()])
if any(marker in haystack for marker in self._GENERIC_DOC_MARKERS):
return True
return self._looks_like_navigation_chunk(row)
def _looks_like_navigation_chunk(self, row: dict) -> bool:
text = self._summary(row).lower()
if not text:
return False
lines = [line.strip() for line in text.splitlines() if line.strip()]
bullet_lines = sum(1 for line in lines if line.startswith(("- ", "* ", "1.", "2.", "3.")))
link_lines = sum(1 for line in lines if "](" in line or line.startswith("docs/"))
if "related docs" in text or "navigation" in text:
return True
return bullet_lines >= 3 or link_lines >= 3
def _query_tokens(self, route: V2RouteResult) -> list[str]:
values = list(route.target_terms) + list(route.anchors.matched_aliases)
tokens: list[str] = []
for item in values:
for token in re.split(r"[^a-zA-Zа-яА-Я0-9]+", str(item).lower()):
if len(token) >= 3:
tokens.append(token)
return list(dict.fromkeys(tokens))
def _path_tokens(self, path: str) -> set[str]:
return {token for token in re.split(r"[^a-zA-Zа-яА-Я0-9]+", path.lower()) if len(token) >= 3}
def _compact(self, value: str) -> str:
return "".join(self._path_tokens(value))
def _path(self, row: dict) -> str:
metadata = dict(row.get("metadata") or {})
raw = str(row.get("path") or metadata.get("source_path") or "").strip()
return normalize_doc_path(raw)
def _title(self, row: dict, path: str) -> str:
metadata = dict(row.get("metadata") or {})
return str(row.get("title") or metadata.get("title") or path).strip()
def _summary(self, row: dict) -> str:
metadata = dict(row.get("metadata") or {})
return str(metadata.get("summary_text") or row.get("content") or "").strip()
def _document_id(self, row: dict, path: str) -> str:
metadata = dict(row.get("metadata") or {})
return str(metadata.get("document_id") or metadata.get("doc_id") or path).strip()
def _entity_name(self, row: dict) -> str:
metadata = dict(row.get("metadata") or {})
return str(metadata.get("entity_name") or "").strip()
src/app/core/agent/processes/v2/evidence/gate.py
+76
View File
@@ -0,0 +1,76 @@
from __future__ import annotations
from dataclasses import dataclass, field
from app.core.agent.processes.v2.anchor_signals import anchor_signal_types
from app.core.agent.processes.v2.models import RetrievedFile, RetrievedSummary, V2AnchorType, V2Intent, V2RouteResult
@dataclass(slots=True)
class EvidenceGateDecision:
passed: bool
answer_mode: str
reason: str
message: str = ""
supporting_paths: list[str] = field(default_factory=list)
class DocsEvidenceGate:
def check_summaries(self, route: V2RouteResult, documents: list[RetrievedSummary]) -> EvidenceGateDecision:
if route.intent == V2Intent.GENERAL_QA:
if documents:
return EvidenceGateDecision(True, "grounded_summary", "general_docs_found")
return EvidenceGateDecision(
False,
"insufficient_evidence",
"general_docs_missing",
"В найденной документации нет достаточной опоры для общего summary по запросу.",
)
if self._has_target_document(route, [item.path for item in documents]):
return EvidenceGateDecision(True, "grounded_summary", "target_doc_found")
return EvidenceGateDecision(
False,
"insufficient_evidence",
"target_doc_missing",
self._summary_insufficiency(route, documents),
[item.path for item in documents[:3]],
)
def check_files(self, route: V2RouteResult, files: list[RetrievedFile]) -> EvidenceGateDecision:
if not files:
return EvidenceGateDecision(
False,
"insufficient_evidence",
"no_file_candidates",
"Не нашёл файлов документации, которые уверенно соответствуют запросу.",
)
if files[0].confidence >= 0.8:
return EvidenceGateDecision(True, "deterministic", "primary_file_confident")
return EvidenceGateDecision(
False,
"deterministic",
"low_confidence_shortlist",
"Нашёл только ближайшие кандидаты по запросу.",
[item.path for item in files[:4]],
)
def _has_target_document(self, route: V2RouteResult, paths: list[str]) -> bool:
if any(path in route.anchors.target_doc_hints for path in paths):
return True
signals = anchor_signal_types(route)
if V2AnchorType.API_ENDPOINT in signals:
return any(path.startswith("docs/api/") for path in paths)
if V2AnchorType.ARCHITECTURE in signals:
return any(path.startswith("docs/architecture/") for path in paths)
if V2AnchorType.LOGIC_FLOW in signals:
return any(path.startswith("docs/logic/") for path in paths)
if V2AnchorType.DOMAIN_ENTITY in signals:
return any(path.startswith("docs/domains/") for path in paths)
return bool(paths)
def _summary_insufficiency(self, route: V2RouteResult, documents: list[RetrievedSummary]) -> str:
base = "В поднятом контексте не найден целевой документ по запросу."
if not documents:
return base
nearby = ", ".join(item.path for item in documents[:3])
return f"{base} Ближайшие документы: {nearby}."
src/app/core/agent/processes/v2/general_prompts.yml
+8
View File
@@ -0,0 +1,8 @@
namespace: v2_general
prompts:
summary_answer: |
Ты делаешь grounded summary только по найденной проектной документации.
Не используй общие знания о том, как обычно устроены системы.
Дай короткий, понятный ответ и опирайся только на входные документы.
Если опоры мало, прямо скажи об этом.
src/app/core/agent/processes/v2/intent_router/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.processes.v2.intent_router.router import V2IntentRouter
__all__ = ["V2IntentRouter"]
src/app/core/agent/processes/v2/intent_router/models.py
+18
View File
@@ -0,0 +1,18 @@
from __future__ import annotations
from dataclasses import dataclass
@dataclass(slots=True)
class QueryFeatures:
normalized_query: str
target_terms: list[str]
endpoint_paths: list[str]
file_names: list[str]
matched_aliases: list[str]
target_doc_hints: list[str]
file_markers: list[str]
architecture_markers: list[str]
logic_markers: list[str]
domain_markers: list[str]
endpoint_markers: list[str]
src/app/core/agent/processes/v2/intent_router/modules/__init__.py
+11
View File
@@ -0,0 +1,11 @@
from app.core.agent.processes.v2.intent_router.modules.anchors import AnchorAnalysis, V2AnchorExtractor
from app.core.agent.processes.v2.intent_router.modules.normalizer import V2QueryNormalizer
from app.core.agent.processes.v2.intent_router.modules.target_terms import TargetTermsAnalysis, V2TargetTermsExtractor
__all__ = [
"AnchorAnalysis",
"TargetTermsAnalysis",
"V2AnchorExtractor",
"V2QueryNormalizer",
"V2TargetTermsExtractor",
]
src/app/core/agent/processes/v2/intent_router/modules/anchors.py
+247
View File
@@ -0,0 +1,247 @@
from __future__ import annotations
import re
from dataclasses import dataclass
from app.core.agent.processes.v2.intent_router.modules.target_terms import TargetTermsAnalysis
from app.core.agent.processes.v2.models import V2RouteAnchors
@dataclass(slots=True)
class AnchorAnalysis:
anchors: V2RouteAnchors
file_markers: list[str]
architecture_markers: list[str]
logic_markers: list[str]
domain_markers: list[str]
endpoint_markers: list[str]
class _MarkerScanner:
_FILE_MARKERS = (
"в каком файле",
"в каком документе",
"в каких файлах",
"где находится",
"где описан",
"где описана",
"где описаны",
"покажи файл",
"какие файлы",
"найди файл",
"найди файлы",
"покажи документ",
"где описано",
"документ с описанием",
)
_ARCHITECTURE_MARKERS = (
"архитектура",
"архитектур",
"architecture",
"arch overview",
"как устроено приложение",
"как устроен сервис",
"основные части системы",
"из чего состоит",
)
_LOGIC_MARKERS = (
"цикл",
"loop",
"flow",
"workflow",
"process",
"worker",
"как работает отправка уведомлений",
"логика отправки",
"background job",
"runtime loop",
)
_DOMAIN_MARKERS = ("runtime health", "health model", "статусы здоровья", "сущность", "entity", "здоровье runtime")
_ENDPOINT_MARKERS = (
"endpoint",
"api",
"route",
"method",
"метод api",
"метод",
"метода",
"ручка",
"эндпоинт",
"маршрут",
"роут",
)
def scan(self, lowered_query: str) -> dict[str, list[str]]:
return {
"file_markers": self._matching(lowered_query, self._FILE_MARKERS),
"architecture_markers": self._matching(lowered_query, self._ARCHITECTURE_MARKERS),
"logic_markers": self._matching(lowered_query, self._LOGIC_MARKERS),
"domain_markers": self._matching(lowered_query, self._DOMAIN_MARKERS),
"endpoint_markers": self._matching(lowered_query, self._ENDPOINT_MARKERS),
}
def _matching(self, query: str, markers: tuple[str, ...]) -> list[str]:
return [marker for marker in markers if marker in query]
class _EntityNameExtractor:
_ENTITY_RE = re.compile(r"\b[A-Z][A-Za-z0-9_]+\b")
_IGNORE = {"arch"}
def extract(self, query: str) -> list[str]:
items: list[str] = []
for match in self._ENTITY_RE.finditer(query):
candidate = match.group(0).strip()
if candidate and candidate.lower() not in self._IGNORE and candidate not in items:
items.append(candidate)
return items
class _FileNameExtractor:
_TOKEN_RE = re.compile(r"`([^`]+)`|([A-Za-z0-9_./-]+)")
_WITH_EXTENSION_RE = re.compile(r".+\.(md|yaml|yml|json)$", re.IGNORECASE)
_DOC_PATH_RE = re.compile(r"^(docs|doc|documentation)/.+")
def extract(self, query: str) -> list[str]:
items: list[str] = []
for match in self._TOKEN_RE.finditer(query):
candidate = next((item for item in match.groups() if item), "")
normalized = str(candidate or "").strip().strip("`'\"")
if self._is_file_name(normalized):
self._append_unique(items, normalized.lower())
return items
def _is_file_name(self, token: str) -> bool:
if not token:
return False
if token.startswith("/") and "." not in token:
return False
if self._WITH_EXTENSION_RE.fullmatch(token):
return True
return self._DOC_PATH_RE.fullmatch(token) is not None
def _append_unique(self, items: list[str], value: str) -> None:
if value and value not in items:
items.append(value)
class _ProcessAnchorExtractor:
_DOMAIN_KEYWORDS = {
"billing": "billing",
"notifications": "notifications",
}
_SUBDOMAIN_KEYWORDS = {
"invoice": ("billing", "invoice"),
"invoices": ("billing", "invoice"),
"delivery_loop": ("notifications", "delivery_loop"),
"delivery": ("notifications", "delivery_loop"),
}
def extract(self, lowered_query: str) -> tuple[str | None, str | None]:
domain = next((value for token, value in self._DOMAIN_KEYWORDS.items() if token in lowered_query), None)
subdomain: str | None = None
for token, mapping in self._SUBDOMAIN_KEYWORDS.items():
if token in lowered_query:
domain = domain or mapping[0]
subdomain = mapping[1]
break
return domain, subdomain
class V2AnchorExtractor:
def __init__(
self,
marker_scanner: _MarkerScanner | None = None,
entity_extractor: _EntityNameExtractor | None = None,
file_name_extractor: _FileNameExtractor | None = None,
process_anchor_extractor: _ProcessAnchorExtractor | None = None,
) -> None:
self._marker_scanner = marker_scanner or _MarkerScanner()
self._entity_extractor = entity_extractor or _EntityNameExtractor()
self._file_name_extractor = file_name_extractor or _FileNameExtractor()
self._process_anchor_extractor = process_anchor_extractor or _ProcessAnchorExtractor()
def extract(self, normalized_query: str, terms: TargetTermsAnalysis) -> AnchorAnalysis:
lowered_query = normalized_query.lower()
markers = self._marker_scanner.scan(lowered_query)
process_domain, process_subdomain = self._process_anchor_extractor.extract(lowered_query)
anchors = V2RouteAnchors(
entity_names=self._entity_extractor.extract(normalized_query),
file_names=self._file_name_extractor.extract(normalized_query),
endpoint_paths=list(terms.endpoint_paths),
target_doc_hints=self._target_doc_hints(
endpoint_paths=terms.endpoint_paths,
api_like_terms=terms.api_like_terms,
alias_docs=terms.alias_docs,
architecture_markers=markers["architecture_markers"],
logic_markers=markers["logic_markers"],
domain_markers=markers["domain_markers"],
),
matched_aliases=list(terms.matched_aliases),
process_domain=process_domain,
process_subdomain=process_subdomain,
)
return AnchorAnalysis(
anchors=anchors,
file_markers=markers["file_markers"],
architecture_markers=markers["architecture_markers"],
logic_markers=markers["logic_markers"],
domain_markers=markers["domain_markers"],
endpoint_markers=markers["endpoint_markers"],
)
def _target_doc_hints(
self,
*,
endpoint_paths: list[str],
api_like_terms: list[str],
alias_docs: list[str],
architecture_markers: list[str],
logic_markers: list[str],
domain_markers: list[str],
) -> list[str]:
hints = list(alias_docs)
endpoint_map = {
"/health": "docs/api/health-endpoint.md",
"/send": "docs/api/send-message-endpoint.md",
"/actions/{action}": "docs/api/control-actions-endpoint.md",
}
for endpoint in endpoint_paths:
for hint in self._endpoint_hint_variants(endpoint):
self._append_unique(hints, hint)
hint = endpoint_map.get(endpoint)
self._append_unique(hints, hint)
for term in api_like_terms:
for hint in self._api_like_hint_variants(term):
self._append_unique(hints, hint)
if architecture_markers:
self._append_unique(hints, "docs/architecture/telegram-notify-app-overview.md")
if logic_markers:
self._append_unique(hints, "docs/logic/telegram-notification-loop.md")
if domain_markers:
self._append_unique(hints, "docs/domains/runtime-health-entity.md")
return hints
def _endpoint_hint_variants(self, endpoint: str) -> list[str]:
normalized = str(endpoint or "").strip().lower()
if not normalized:
return []
slug = normalized.strip("/").replace("/", "-").replace("{", "").replace("}", "")
leaf = next((part for part in reversed(slug.split("-")) if part and part != "id"), "")
hints: list[str] = [normalized]
for value in (slug, leaf):
if not value:
continue
hints.extend([value, f"{value}-endpoint", f"{value} endpoint"])
return list(dict.fromkeys(hints))
def _api_like_hint_variants(self, term: str) -> list[str]:
normalized = str(term or "").strip().lower().lstrip("/")
if not normalized:
return []
return [normalized, f"/{normalized}", f"{normalized}-endpoint", f"{normalized} endpoint"]
def _append_unique(self, items: list[str], value: str | None) -> None:
normalized = str(value or "").strip()
if normalized and normalized not in items:
items.append(normalized)
src/app/core/agent/processes/v2/intent_router/modules/normalizer.py
+6
View File
@@ -0,0 +1,6 @@
from __future__ import annotations
class V2QueryNormalizer:
def normalize(self, user_query: str) -> str:
return " ".join(str(user_query or "").strip().split())
src/app/core/agent/processes/v2/intent_router/modules/target_terms.py
+349
View File
@@ -0,0 +1,349 @@
from __future__ import annotations
import re
from dataclasses import dataclass
@dataclass(slots=True)
class TargetTermsAnalysis:
target_terms: list[str]
endpoint_paths: list[str]
api_like_terms: list[str]
matched_aliases: list[str]
alias_docs: list[str]
@dataclass(frozen=True, slots=True)
class _AliasRule:
phrases: tuple[str, ...]
canonical_term: str
target_doc_hint: str
class _AliasMatcher:
_RULES = (
_AliasRule(("ручная отправка сообщения", "отправка сообщения вручную"), "/send", "docs/api/send-message-endpoint.md"),
_AliasRule(("статус сервиса", "проверка здоровья"), "/health", "docs/api/health-endpoint.md"),
_AliasRule(("control actions", "управление runtime"), "/actions/{action}", "docs/api/control-actions-endpoint.md"),
_AliasRule(("runtime health", "здоровье runtime", "статусы здоровья"), "runtime_health", "docs/domains/runtime-health-entity.md"),
_AliasRule(("цикл отправки уведомлений", "notification loop", "worker loop"), "telegram-notify-loop", "docs/logic/telegram-notification-loop.md"),
_AliasRule(("архитектура приложения",), "architecture_overview", "docs/architecture/telegram-notify-app-overview.md"),
_AliasRule(("архитектура",), "architecture_overview", "docs/architecture/telegram-notify-app-overview.md"),
_AliasRule(("каталог ошибок", "errors catalog"), "errors_catalog", "docs/errors/catalog.yaml"),
_AliasRule(("файл-индекс документации", "docs index", "индекс документации"), "docs_index", "docs/README.md"),
)
def match(self, lowered_query: str) -> tuple[list[str], list[str], list[str]]:
terms: list[str] = []
docs: list[str] = []
aliases: list[str] = []
for rule in self._RULES:
if any(phrase in lowered_query for phrase in rule.phrases):
self._append_unique(terms, rule.canonical_term.lower())
self._append_unique(docs, rule.target_doc_hint)
self._append_unique(aliases, rule.canonical_term.lower())
return terms, docs, aliases
def _append_unique(self, items: list[str], value: str) -> None:
if value and value not in items:
items.append(value)
class _EndpointPathExtractor:
_PATH_RE = re.compile(r"`([^`]+)`|(/[A-Za-z0-9_./{}-]+)")
_VALID_ENDPOINT_RE = re.compile(r"^/[a-z0-9._/-]+(?:/\{[a-z0-9_]+\})?$")
_DOC_EXTENSIONS = (".md", ".yaml", ".yml", ".json")
def extract(self, query: str) -> list[str]:
values: list[str] = []
for match in self._PATH_RE.finditer(query):
candidate = next((item for item in match.groups() if item and item.startswith("/")), "")
normalized = self._normalize(candidate)
if self._is_endpoint(normalized):
self._append_unique(values, normalized)
return values
def _normalize(self, token: str) -> str:
trimmed = str(token or "").strip().strip("`'\"()[]!?.,:;")
if "{" in trimmed and "}" not in trimmed:
return ""
return trimmed.lower()
def _is_endpoint(self, token: str) -> bool:
if not token or not self._VALID_ENDPOINT_RE.fullmatch(token):
return False
return not token.endswith(self._DOC_EXTENSIONS)
def _append_unique(self, items: list[str], value: str) -> None:
if value and value not in items:
items.append(value)
@dataclass(slots=True)
class _ApiLikeAnchorAnalysis:
endpoint_paths: list[str]
candidate_terms: list[str]
class _ApiLikeAnchorExtractor:
_TOKEN_RE = re.compile(r"[A-Za-zА-Яа-я0-9_./{}-]+")
_ASCII_ENDPOINT_RE = re.compile(r"^[a-z0-9]+(?:[-_][a-z0-9]+)*$")
_API_MARKERS = {
"api",
"endpoint",
"route",
"method",
"метод",
"метода",
"методу",
"ручка",
"ручки",
"эндпоинт",
"эндпоинта",
"маршрут",
"роут",
}
_EXPLAIN_MARKERS = {
"как",
"что",
"делает",
"работает",
"объясни",
"объяснить",
"расскажи",
"опиши",
"смысл",
}
_NOISE_WORDS = _API_MARKERS | _EXPLAIN_MARKERS | {
"про",
"какой",
"какая",
"какие",
"какого",
"какую",
"кратко",
"нужен",
"нужно",
"у",
}
_SHORT_QUERY_TOKEN_LIMIT = 7
def extract(self, query: str, explicit_endpoint_paths: list[str]) -> _ApiLikeAnchorAnalysis:
if explicit_endpoint_paths:
return _ApiLikeAnchorAnalysis(endpoint_paths=list(explicit_endpoint_paths), candidate_terms=[])
token_entries = self._token_entries(query)
if not token_entries:
return _ApiLikeAnchorAnalysis(endpoint_paths=[], candidate_terms=[])
candidate_terms = [token for token, _start in token_entries if self._is_api_candidate(token)]
if not candidate_terms:
return _ApiLikeAnchorAnalysis(endpoint_paths=[], candidate_terms=[])
if self._has_api_marker(token_entries):
primary = self._primary_candidate(token_entries)
endpoint_paths = [self._ensure_endpoint(primary)] if primary else []
return _ApiLikeAnchorAnalysis(
endpoint_paths=[path for path in endpoint_paths if path],
candidate_terms=[primary] if primary else [],
)
if self._is_short_explain_query(token_entries) and len(candidate_terms) == 1:
return _ApiLikeAnchorAnalysis(endpoint_paths=[], candidate_terms=list(candidate_terms))
return _ApiLikeAnchorAnalysis(endpoint_paths=[], candidate_terms=[])
def _token_entries(self, query: str) -> list[tuple[str, int]]:
entries: list[tuple[str, int]] = []
for match in self._TOKEN_RE.finditer(query):
token = str(match.group(0) or "").strip().strip("`'\"()[]!?.,:;").lower()
if token:
entries.append((token, match.start()))
return entries
def _has_api_marker(self, token_entries: list[tuple[str, int]]) -> bool:
return any(token in self._API_MARKERS for token, _start in token_entries)
def _is_short_explain_query(self, token_entries: list[tuple[str, int]]) -> bool:
if len(token_entries) > self._SHORT_QUERY_TOKEN_LIMIT:
return False
return any(token in self._EXPLAIN_MARKERS for token, _start in token_entries)
def _primary_candidate(self, token_entries: list[tuple[str, int]]) -> str | None:
marker_positions = [start for token, start in token_entries if token in self._API_MARKERS]
candidates = [(token, start) for token, start in token_entries if self._is_api_candidate(token)]
if not candidates:
return None
if not marker_positions:
return candidates[-1][0]
primary = min(
candidates,
key=lambda item: min(abs(item[1] - marker_pos) for marker_pos in marker_positions),
)
return primary[0]
def _is_api_candidate(self, token: str) -> bool:
if (
not token
or token in self._NOISE_WORDS
or token.startswith("docs/")
or token.endswith((".md", ".yaml", ".yml", ".json"))
):
return False
if token.startswith("/"):
return True
return self._ASCII_ENDPOINT_RE.fullmatch(token) is not None and len(token) >= 3
def _ensure_endpoint(self, token: str) -> str:
return token if token.startswith("/") else f"/{token}"
class _TermCollector:
_TOKEN_RE = re.compile(r"[A-Za-zА-Яа-я0-9_./{}-]+")
_IDENTIFIER_RE = re.compile(
r"^(?:[a-z0-9]+(?:[_-][a-z0-9]+)+|[a-z]+[A-Z][A-Za-z0-9]+|(?:[A-Z][a-z0-9]+){2,})$"
)
_QUESTION_WORDS = {"что", "как", "где", "какой", "какие", "каком", "когда", "чего"}
_INTENT_WORDS = {"объясни", "покажи", "найди", "расскажи", "дай", "опиши", "нужен", "show"}
_FILLER_WORDS = {"про", "там", "тут", "плз", "pls", "for"}
_MARKER_WORDS = {
"файл",
"файле",
"file",
"method",
"метод",
"метода",
"методу",
"route",
"ручка",
"ручки",
"эндпоинт",
"эндпоинта",
"overview",
"architecture",
"arch",
"flow",
"process",
"workflow",
"док",
"дока",
"доках",
"документ",
"doc",
"описан",
"док-саммари",
"summary",
"саммари",
}
_SERVICE_WORDS = {
"кратко",
"краткий",
"для",
"есть",
"делает",
"работает",
"это",
"этой",
"этого",
"этот",
"документы",
"документация",
"документации",
"файлы",
"путь",
"пути",
"service",
"summary",
"endpoint",
"docs",
}
_MAX_TERMS = 7
def collect(self, query: str, alias_terms: list[str], endpoint_paths: list[str]) -> list[str]:
explicit_terms: list[str] = []
for value in endpoint_paths:
self._append_unique(explicit_terms, value)
for token in self._TOKEN_RE.findall(query):
normalized = self._normalize(token)
if not normalized:
continue
if self._is_endpoint(normalized) or self._is_identifier(normalized) or self._is_valid_term(normalized):
self._append_unique(explicit_terms, normalized)
alias_bucket = self._collect_alias_terms(alias_terms, explicit_terms)
prioritized = self._prioritize(explicit_terms, alias_bucket)
return prioritized[: self._MAX_TERMS]
def _normalize(self, token: str) -> str:
trimmed = str(token or "").strip().strip("`'\"()[]!?.,:;")
if "{" in trimmed and "}" not in trimmed:
return ""
return trimmed.lower()
def _is_endpoint(self, token: str) -> bool:
return token.startswith("/") and len(token) > 1 and "{" not in token.replace("{", "", 1)
def _is_identifier(self, token: str) -> bool:
return bool(self._IDENTIFIER_RE.fullmatch(token))
def _is_valid_term(self, token: str) -> bool:
if len(token) < 3 or "/" in token or "." in token:
return False
if (
token in self._QUESTION_WORDS
or token in self._INTENT_WORDS
or token in self._FILLER_WORDS
or token in self._MARKER_WORDS
or token in self._SERVICE_WORDS
):
return False
return True
def _collect_alias_terms(self, alias_terms: list[str], explicit_terms: list[str]) -> list[str]:
collected: list[str] = []
explicit_set = set(explicit_terms)
for term in alias_terms:
normalized = self._normalize(term)
if not normalized:
continue
if normalized in explicit_set:
continue
if self._is_identifier(normalized):
parts = [part for part in re.split(r"[_-]", normalized) if part]
if parts and all(part in explicit_set for part in parts):
continue
self._append_unique(collected, normalized)
return collected
def _prioritize(self, explicit_terms: list[str], alias_terms: list[str]) -> list[str]:
terms = explicit_terms + [term for term in alias_terms if term not in explicit_terms]
endpoints = [term for term in terms if self._is_endpoint(term)]
identifiers = [term for term in terms if term not in endpoints and self._is_identifier(term)]
aliases = [term for term in alias_terms if term not in endpoints and term not in identifiers]
other_terms = [term for term in terms if term not in endpoints and term not in identifiers and term not in aliases]
return endpoints + identifiers + aliases + other_terms
def _append_unique(self, items: list[str], value: str) -> None:
if value and value not in items:
items.append(value)
class V2TargetTermsExtractor:
def __init__(
self,
alias_matcher: _AliasMatcher | None = None,
endpoint_extractor: _EndpointPathExtractor | None = None,
api_like_extractor: _ApiLikeAnchorExtractor | None = None,
term_collector: _TermCollector | None = None,
) -> None:
self._alias_matcher = alias_matcher or _AliasMatcher()
self._endpoint_extractor = endpoint_extractor or _EndpointPathExtractor()
self._api_like_extractor = api_like_extractor or _ApiLikeAnchorExtractor()
self._term_collector = term_collector or _TermCollector()
def extract(self, normalized_query: str) -> TargetTermsAnalysis:
lowered = normalized_query.lower()
endpoint_paths = self._endpoint_extractor.extract(normalized_query)
api_like = self._api_like_extractor.extract(normalized_query, endpoint_paths)
alias_terms, alias_docs, alias_hits = self._alias_matcher.match(lowered)
return TargetTermsAnalysis(
target_terms=self._term_collector.collect(normalized_query, alias_terms, api_like.endpoint_paths),
endpoint_paths=api_like.endpoint_paths,
api_like_terms=api_like.candidate_terms,
matched_aliases=alias_hits,
alias_docs=alias_docs,
)
src/app/core/agent/processes/v2/intent_router/router.py
+118
View File
@@ -0,0 +1,118 @@
"""Маршрутизация запроса в домен/интент/subintent и якоря для v2."""
from __future__ import annotations
from app.core.agent.processes.v2.intent_router.modules.anchors import V2AnchorExtractor
from app.core.agent.processes.v2.intent_router.modules.normalizer import V2QueryNormalizer
from app.core.agent.processes.v2.intent_router.modules.target_terms import V2TargetTermsExtractor
from app.core.agent.processes.v2.intent_router.models import QueryFeatures
from app.core.agent.processes.v2.intent_router.routers.confidence import V2ConfidenceAdjuster
from app.core.agent.processes.v2.intent_router.routers.fallback import V2FallbackRouter
from app.core.agent.processes.v2.intent_router.routers.llm import V2LlmRouter
from app.core.agent.processes.v2.intent_router.routers.route_catalog import V2RouteCatalog
from app.core.agent.processes.v2.intent_router.routers.validator import V2RouteValidator
from app.core.agent.processes.v2.models import V2RouteResult
from app.core.agent.utils.llm import AgentLlmService
class V2IntentRouter:
def __init__(
self,
normalizer: V2QueryNormalizer | None = None,
target_terms_extractor: V2TargetTermsExtractor | None = None,
anchor_extractor: V2AnchorExtractor | None = None,
llm: AgentLlmService | None = None,
enable_llm_disambiguation: bool = True,
route_catalog: V2RouteCatalog | None = None,
confidence_adjuster: V2ConfidenceAdjuster | None = None,
) -> None:
self._normalizer = normalizer or V2QueryNormalizer()
self._target_terms_extractor = target_terms_extractor or V2TargetTermsExtractor()
self._anchor_extractor = anchor_extractor or V2AnchorExtractor()
self._catalog = route_catalog or V2RouteCatalog()
self._validator = V2RouteValidator(self._catalog)
self._fallback_router = V2FallbackRouter()
self._confidence_adjuster = confidence_adjuster or V2ConfidenceAdjuster()
self._enable_llm_disambiguation = enable_llm_disambiguation
self._llm_router = V2LlmRouter(llm, catalog=self._catalog) if llm is not None else None
def route(self, user_query: str) -> V2RouteResult:
normalized_query = self._normalizer.normalize(user_query)
target_terms_analysis = self._target_terms_extractor.extract(normalized_query)
anchor_analysis = self._anchor_extractor.extract(normalized_query, target_terms_analysis)
features = QueryFeatures(
normalized_query=normalized_query,
target_terms=list(target_terms_analysis.target_terms),
endpoint_paths=list(target_terms_analysis.endpoint_paths),
file_names=list(anchor_analysis.anchors.file_names),
matched_aliases=list(target_terms_analysis.matched_aliases),
target_doc_hints=list(anchor_analysis.anchors.target_doc_hints),
file_markers=list(anchor_analysis.file_markers),
architecture_markers=list(anchor_analysis.architecture_markers),
logic_markers=list(anchor_analysis.logic_markers),
domain_markers=list(anchor_analysis.domain_markers),
endpoint_markers=list(anchor_analysis.endpoint_markers),
)
llm_attempted = self._enable_llm_disambiguation and self._llm_router is not None
llm_candidate = self._route_with_llm(
features=features,
anchors=anchor_analysis.anchors,
)
llm_result = self._validator.validate(llm_candidate)
llm_result = self._apply_deterministic_corrections(llm_result, features)
if llm_result is not None:
confidence = self._confidence_adjuster.adjust(float(llm_result["confidence"]), features)
return V2RouteResult(
routing_domain=llm_result["routing_domain"],
intent=llm_result["intent"],
subintent=llm_result["subintent"],
user_query=user_query,
normalized_query=features.normalized_query,
target_terms=features.target_terms,
anchors=anchor_analysis.anchors,
confidence=confidence,
routing_mode="llm_default",
llm_router_used=True,
reason_short=str(llm_result["reason_short"]),
)
return self._fallback_router.route(
user_query=user_query,
features=features,
anchors=anchor_analysis.anchors,
llm_attempted=llm_attempted,
)
def _route_with_llm(self, *, features: QueryFeatures, anchors) -> dict | None:
if not self._enable_llm_disambiguation or self._llm_router is None:
return None
try:
return self._llm_router.classify(
normalized_query=features.normalized_query,
target_terms=features.target_terms,
anchors={
"entity_names": anchors.entity_names,
"file_names": anchors.file_names,
"endpoint_paths": anchors.endpoint_paths,
"target_doc_hints": anchors.target_doc_hints,
"matched_aliases": anchors.matched_aliases,
"process_domain": anchors.process_domain,
"process_subdomain": anchors.process_subdomain,
},
)
except Exception:
return None
def _apply_deterministic_corrections(self, candidate: dict | None, features: QueryFeatures) -> dict | None:
if candidate is None:
return None
if candidate.get("routing_domain") == "DOCS" and self._should_force_find_files(features):
corrected = dict(candidate)
corrected["subintent"] = "FIND_FILES"
return corrected
return candidate
def _should_force_find_files(self, features: QueryFeatures) -> bool:
if features.file_markers or features.file_names:
return True
query = features.normalized_query.lower()
return "show doc" in query or "show file" in query or "doc for" in query
src/app/core/agent/processes/v2/intent_router/routers/__init__.py
+5
View File
@@ -0,0 +1,5 @@
from app.core.agent.processes.v2.intent_router.routers.docs_subintent_resolver import DocsSubintentResolver
from app.core.agent.processes.v2.intent_router.routers.deterministic import V2DeterministicRouter
from app.core.agent.processes.v2.intent_router.routers.llm import V2LlmRouter
__all__ = ["DocsSubintentResolver", "V2DeterministicRouter", "V2LlmRouter"]
src/app/core/agent/processes/v2/intent_router/routers/confidence.py
+25
View File
@@ -0,0 +1,25 @@
from __future__ import annotations
from app.core.agent.processes.v2.intent_router.models import QueryFeatures
class V2ConfidenceAdjuster:
def adjust(self, confidence: float, features: QueryFeatures) -> float:
adjusted = confidence
if not self._has_strong_anchor(features):
adjusted -= 0.1
if self._is_short_or_vague(features):
adjusted -= 0.1
if self._has_explicit_signal(features):
adjusted += 0.05
return min(max(adjusted, 0.0), 1.0)
def _has_strong_anchor(self, features: QueryFeatures) -> bool:
return any((features.file_markers, features.endpoint_paths, features.target_doc_hints, features.matched_aliases))
def _is_short_or_vague(self, features: QueryFeatures) -> bool:
token_count = len([token for token in features.normalized_query.split() if token.strip()])
return token_count <= 3 or len(features.target_terms) <= 1
def _has_explicit_signal(self, features: QueryFeatures) -> bool:
return bool(features.file_markers or features.endpoint_paths or features.endpoint_markers)
src/app/core/agent/processes/v2/intent_router/routers/deterministic.py
+73
View File
@@ -0,0 +1,73 @@
from __future__ import annotations
from app.core.agent.processes.v2.intent_router.models import QueryFeatures
from app.core.agent.processes.v2.models import V2Domain, V2Intent, V2RouteResult, V2Subintent
from app.core.agent.processes.v2.intent_router.routers.docs_subintent_resolver import DocsSubintentResolver
class V2DeterministicRouter:
_GENERAL_MARKERS = (
"что это за сервис",
"для чего нужен",
"какую задачу решает",
"что входит в документацию",
"какие документы стоит читать сначала",
"дай короткое summary",
"с чего начать",
"что тут есть кроме api",
"как в целом устроено приложение",
"какие основные части есть",
"из чего состоит telegram notify app",
)
def __init__(self, subintent_resolver: DocsSubintentResolver | None = None) -> None:
self._subintent_resolver = subintent_resolver or DocsSubintentResolver()
def route(self, user_query: str, features: QueryFeatures, anchors) -> V2RouteResult | None:
subintent = self._subintent_resolver.resolve(features)
if subintent == V2Subintent.FIND_FILES:
return self._build_docs_route(user_query, features, anchors, subintent, "deterministic file anchor")
if subintent is not None and not self._has_conflicting_doc_anchors(features):
return self._build_docs_route(user_query, features, anchors, subintent, "deterministic signal")
if self._is_general_summary(features.normalized_query):
return V2RouteResult(
routing_domain=V2Domain.GENERAL,
intent=V2Intent.GENERAL_QA,
subintent=V2Subintent.SUMMARY,
user_query=user_query,
normalized_query=features.normalized_query,
target_terms=features.target_terms,
anchors=anchors,
confidence=1.0,
routing_mode="deterministic",
llm_router_used=False,
reason_short="general fallback signal",
)
return None
def _build_docs_route(self, user_query: str, features: QueryFeatures, anchors, subintent: str, reason: str) -> V2RouteResult:
return V2RouteResult(
routing_domain=V2Domain.DOCS,
intent=V2Intent.DOC_EXPLAIN,
subintent=subintent,
user_query=user_query,
normalized_query=features.normalized_query,
target_terms=features.target_terms,
anchors=anchors,
confidence=1.0,
routing_mode="deterministic",
llm_router_used=False,
reason_short=reason,
)
def _is_general_summary(self, normalized_query: str) -> bool:
query = normalized_query.lower()
return any(marker in query for marker in self._GENERAL_MARKERS)
def _has_conflicting_doc_anchors(self, features: QueryFeatures) -> bool:
signals = 0
signals += 1 if features.endpoint_paths or features.endpoint_markers else 0
signals += 1 if features.architecture_markers else 0
signals += 1 if features.logic_markers else 0
signals += 1 if features.domain_markers else 0
return signals > 1
src/app/core/agent/processes/v2/intent_router/routers/docs_subintent_resolver.py
+28
View File
@@ -0,0 +1,28 @@
from __future__ import annotations
from app.core.agent.processes.v2.intent_router.models import QueryFeatures
from app.core.agent.processes.v2.models import V2Subintent
class DocsSubintentResolver:
def resolve(self, features: QueryFeatures) -> str | None:
if features.file_markers or self._has_file_like_anchor(features):
return V2Subintent.FIND_FILES
if any(
(
features.endpoint_paths,
features.endpoint_markers,
features.architecture_markers,
features.logic_markers,
features.domain_markers,
features.target_doc_hints,
)
):
return V2Subintent.SUMMARY
return None
def _has_file_like_anchor(self, features: QueryFeatures) -> bool:
return any(
hint.endswith((".md", ".yaml", ".yml", ".json"))
for hint in features.target_doc_hints
) or any(token.endswith((".md", ".yaml", ".yml", ".json")) for token in features.file_names)
src/app/core/agent/processes/v2/intent_router/routers/fallback.py
+86
View File
@@ -0,0 +1,86 @@
from __future__ import annotations
from app.core.agent.processes.v2.intent_router.models import QueryFeatures
from app.core.agent.processes.v2.models import V2Domain, V2Intent, V2RouteResult, V2Subintent
class V2FallbackRouter:
def route(
self,
*,
user_query: str,
features: QueryFeatures,
anchors,
llm_attempted: bool,
) -> V2RouteResult:
if features.file_markers:
return self._build_docs_result(
user_query=user_query,
features=features,
anchors=anchors,
subintent=V2Subintent.FIND_FILES,
llm_attempted=llm_attempted,
reason="fallback file markers",
)
if self._has_docs_signal(features):
return self._build_docs_result(
user_query=user_query,
features=features,
anchors=anchors,
subintent=V2Subintent.SUMMARY,
llm_attempted=llm_attempted,
reason="fallback docs summary",
)
return V2RouteResult(
routing_domain=V2Domain.GENERAL,
intent=V2Intent.GENERAL_QA,
subintent=V2Subintent.SUMMARY,
user_query=user_query,
normalized_query=features.normalized_query,
target_terms=features.target_terms,
anchors=anchors,
confidence=0.0,
routing_mode=self._routing_mode(llm_attempted),
llm_router_used=llm_attempted,
reason_short="fallback general summary",
)
def _build_docs_result(
self,
*,
user_query: str,
features: QueryFeatures,
anchors,
subintent: str,
llm_attempted: bool,
reason: str,
) -> V2RouteResult:
return V2RouteResult(
routing_domain=V2Domain.DOCS,
intent=V2Intent.DOC_EXPLAIN,
subintent=subintent,
user_query=user_query,
normalized_query=features.normalized_query,
target_terms=features.target_terms,
anchors=anchors,
confidence=0.0,
routing_mode=self._routing_mode(llm_attempted),
llm_router_used=llm_attempted,
reason_short=reason,
)
def _has_docs_signal(self, features: QueryFeatures) -> bool:
return any(
(
features.endpoint_paths,
features.target_doc_hints,
features.endpoint_markers,
features.architecture_markers,
features.logic_markers,
features.domain_markers,
features.matched_aliases,
)
)
def _routing_mode(self, llm_attempted: bool) -> str:
return "llm_fallback" if llm_attempted else "deterministic_fallback"
src/app/core/agent/processes/v2/intent_router/routers/llm.py
+45
View File
@@ -0,0 +1,45 @@
from __future__ import annotations
import json
from app.core.agent.processes.v2.intent_router.routers.route_catalog import V2RouteCatalog
from app.core.agent.utils.llm import AgentLlmService
class V2LlmRouter:
def __init__(
self,
llm: AgentLlmService,
prompt_name: str = "v2_intent_router.route",
catalog: V2RouteCatalog | None = None,
) -> None:
self._llm = llm
self._prompt_name = prompt_name
self._catalog = catalog or V2RouteCatalog()
def classify(self, *, normalized_query: str, target_terms: list[str], anchors: dict) -> dict | None:
payload = {
"normalized_query": normalized_query,
"target_terms": target_terms,
"anchors": anchors,
"allowed_routes": self._catalog.allowed_routes(),
}
raw = self._llm.generate(
self._prompt_name,
json.dumps(payload, ensure_ascii=False, indent=2),
log_context="v2_intent_router",
)
return self._parse(raw)
def _parse(self, raw: str) -> dict | None:
try:
data = json.loads(str(raw or "").strip())
except json.JSONDecodeError:
return None
return {
"routing_domain": str(data.get("routing_domain") or "").strip(),
"intent": str(data.get("intent") or "").strip(),
"subintent": str(data.get("subintent") or "").strip(),
"confidence": data.get("confidence"),
"reason_short": str(data.get("reason_short") or "").strip(),
}
src/app/core/agent/processes/v2/intent_router/routers/prompts.yml
+26
View File
@@ -0,0 +1,26 @@
namespace: v2_intent_router
prompts:
route: |
Ты выбираешь маршрут для узкого процесса v2.
Основной принцип:
- DOCS / DOC_EXPLAIN / FIND_FILES: запрос просит найти файл, документ или путь.
- DOCS / DOC_EXPLAIN / SUMMARY: запрос просит объяснить документацию, endpoint, архитектуру, процесс или сущность.
- GENERAL / GENERAL_QA / SUMMARY: общий обзорный вопрос без явного запроса к документации.
Используй только маршруты из поля `allowed_routes`.
Верни confidence:
- 0.9-1.0 для явного кейса
- 0.7-0.9 для нормального кейса
- меньше 0.7 для неоднозначного кейса
Ответь только JSON-объектом вида:
{
"routing_domain": "GENERAL" | "DOCS",
"intent": "GENERAL_QA" | "DOC_EXPLAIN",
"subintent": "SUMMARY" | "FIND_FILES",
"confidence": 0.0-1.0,
"reason_short": "короткая причина"
}
Не добавляй markdown, комментарии и текст вне JSON.
src/app/core/agent/processes/v2/intent_router/routers/route_catalog.py
+20
View File
@@ -0,0 +1,20 @@
from __future__ import annotations
from app.core.agent.processes.v2.models import V2Domain, V2Intent, V2Subintent
class V2RouteCatalog:
_ALLOWED_ROUTES = (
(V2Domain.DOCS, V2Intent.DOC_EXPLAIN, V2Subintent.FIND_FILES),
(V2Domain.DOCS, V2Intent.DOC_EXPLAIN, V2Subintent.SUMMARY),
(V2Domain.GENERAL, V2Intent.GENERAL_QA, V2Subintent.SUMMARY),
)
def allowed_routes(self) -> list[dict[str, str]]:
return [
{"routing_domain": domain, "intent": intent, "subintent": subintent}
for domain, intent, subintent in self._ALLOWED_ROUTES
]
def is_allowed(self, routing_domain: str, intent: str, subintent: str) -> bool:
return (routing_domain, intent, subintent) in self._ALLOWED_ROUTES
src/app/core/agent/processes/v2/intent_router/routers/validator.py
+34
View File
@@ -0,0 +1,34 @@
from __future__ import annotations
from app.core.agent.processes.v2.intent_router.routers.route_catalog import V2RouteCatalog
class V2RouteValidator:
def __init__(self, catalog: V2RouteCatalog | None = None) -> None:
self._catalog = catalog or V2RouteCatalog()
def validate(self, candidate: dict | None) -> dict | None:
if not isinstance(candidate, dict):
return None
routing_domain = self._value(candidate, "routing_domain")
intent = self._value(candidate, "intent")
subintent = self._value(candidate, "subintent")
if not self._catalog.is_allowed(routing_domain, intent, subintent):
return None
return {
"routing_domain": routing_domain,
"intent": intent,
"subintent": subintent,
"confidence": self._coerce_confidence(candidate.get("confidence")),
"reason_short": self._value(candidate, "reason_short"),
}
def _value(self, candidate: dict, key: str) -> str:
return str(candidate.get(key) or "").strip()
def _coerce_confidence(self, value: object) -> float:
try:
confidence = float(value)
except (TypeError, ValueError):
return 0.0
return max(0.0, min(1.0, confidence))
src/app/core/agent/processes/v2/models.py
+87
View File
@@ -0,0 +1,87 @@
"""Типы маршрута и выдачи retrieval для процесса v2."""
from __future__ import annotations
from dataclasses import dataclass, field
class V2Domain:
DOCS = "DOCS"
GENERAL = "GENERAL"
class V2Intent:
DOC_EXPLAIN = "DOC_EXPLAIN"
GENERAL_QA = "GENERAL_QA"
class V2Subintent:
SUMMARY = "SUMMARY"
FIND_FILES = "FIND_FILES"
class V2AnchorType:
GENERAL_OVERVIEW = "GENERAL_OVERVIEW"
API_ENDPOINT = "API_ENDPOINT"
ARCHITECTURE = "ARCHITECTURE"
LOGIC_FLOW = "LOGIC_FLOW"
DOMAIN_ENTITY = "DOMAIN_ENTITY"
FIND_FILES = "FIND_FILES"
@dataclass(slots=True)
class V2RouteAnchors:
"""Якоря из запроса для retrieval и downstream."""
entity_names: list[str] = field(default_factory=list)
file_names: list[str] = field(default_factory=list)
endpoint_paths: list[str] = field(default_factory=list)
target_doc_hints: list[str] = field(default_factory=list)
matched_aliases: list[str] = field(default_factory=list)
process_domain: str | None = None
process_subdomain: str | None = None
@dataclass(slots=True)
class V2RouteResult:
routing_domain: str
intent: str
subintent: str
user_query: str
normalized_query: str
target_terms: list[str] = field(default_factory=list)
anchors: V2RouteAnchors = field(default_factory=V2RouteAnchors)
confidence: float = 1.0
routing_mode: str = "deterministic"
llm_router_used: bool = False
reason_short: str = ""
@property
def domain(self) -> str:
"""Совместимость с полем ``domain`` в логах и вызовах."""
return self.routing_domain
@dataclass(slots=True)
class RetrievedSummary:
path: str
title: str
summary: str
document_id: str
score: int
confidence: float = 0.0
match_reason: str = "semantic_match"
is_primary: bool = False
score_breakdown: dict[str, int] = field(default_factory=dict)
@dataclass(slots=True)
class RetrievedFile:
path: str
title: str
document_id: str
score: int
confidence: float
match_reason: str
is_primary: bool = False
score_breakdown: dict[str, int] = field(default_factory=dict)
src/app/core/agent/processes/v2/process.py
+304
View File
@@ -0,0 +1,304 @@
"""Процесс v2: роутинг, план retrieval, вызов rag API, сборка evidence и workflow."""
from __future__ import annotations
from app.core.agent.processes.v2.anchor_signals import route_anchor_summary
from app.core.agent.processes.v2.evidence.assembler import DocsEvidenceAssembler
from app.core.agent.processes.v2.evidence.gate import DocsEvidenceGate
from app.core.agent.processes.v2.intent_router import V2IntentRouter
from app.core.agent.processes.v2.models import V2Intent, V2Subintent
from app.core.agent.processes.v2.retrieval import DocsMetadataLookupIndex
from app.core.agent.processes.v2.retrieval.policy_resolver import V2RetrievalPolicyResolver
from app.core.agent.processes.v2.retrieval.target_doc_seeding import (
RagRowIndex,
merge_row_lists,
normalize_doc_path,
normalized_path_set,
row_path,
seed_candidates_from_target_hints,
)
from app.core.agent.processes.v2.retrieval.v2_rag_adapter import V2RagRetrievalAdapter
from app.core.agent.processes.v2.workflows.docs_explain_find_files.context import DocsExplainFindFilesContext
from app.core.agent.processes.v2.workflows.docs_explain_find_files.graph import DocsExplainFindFilesGraph
from app.core.agent.processes.v2.workflows.docs_explain_summary.context import DocsExplainSummaryContext
from app.core.agent.processes.v2.workflows.docs_explain_summary.graph import DocsExplainSummaryGraph
from app.core.agent.processes.v2.workflows.general_summary.context import GeneralSummaryContext
from app.core.agent.processes.v2.workflows.general_summary.graph import GeneralSummaryGraph
from app.core.agent.processes.base import AgentProcess, ProcessResult
from app.core.agent.utils.llm import AgentLlmService
class V2Process(AgentProcess):
version = "v2"
def __init__(
self,
llm: AgentLlmService,
policy_resolver: V2RetrievalPolicyResolver,
rag_adapter: V2RagRetrievalAdapter,
evidence_assembler: DocsEvidenceAssembler,
evidence_gate: DocsEvidenceGate | None = None,
router: V2IntentRouter | None = None,
docs_summary_prompt_name: str = "v2_docs_explain.summary_answer",
general_summary_prompt_name: str = "v2_general.summary_answer",
workflow_llm_enabled: bool = True,
) -> None:
self._router = router or V2IntentRouter()
self._policy_resolver = policy_resolver
self._rag_adapter = rag_adapter
self._evidence_assembler = evidence_assembler
self._evidence_gate = evidence_gate or DocsEvidenceGate()
self._docs_summary_prompt_name = docs_summary_prompt_name
self._general_summary_prompt_name = general_summary_prompt_name
self._workflow_llm_enabled = workflow_llm_enabled
self._summary_graph = DocsExplainSummaryGraph(llm)
self._find_files_graph = DocsExplainFindFilesGraph()
self._general_summary_graph = GeneralSummaryGraph(llm)
async def run(self, context) -> ProcessResult:
route = self._router.route(context.request.message)
rag_session_id = context.session.active_rag_session_id
context.trace.module("process.v2").log(
"intent_routed",
{
"routing_domain": route.routing_domain,
"intent": route.intent,
"subintent": route.subintent,
"normalized_query": route.normalized_query,
"target_terms": route.target_terms,
"anchors": route_anchor_summary(route),
"confidence": route.confidence,
"routing_mode": route.routing_mode,
"llm_router_used": route.llm_router_used,
"reason_short": route.reason_short,
"rag_session_id": rag_session_id,
},
)
self._log_step(
context,
"router_resolved",
{
"domain": route.routing_domain,
"intent": route.intent,
"subintent": route.subintent,
"confidence": route.confidence,
},
)
self._log_step(
context,
"anchors_extracted",
{
"signal_types": route_anchor_summary(route)["signal_types"],
"endpoint_paths": route.anchors.endpoint_paths,
"target_doc_hints": route.anchors.target_doc_hints,
"matched_aliases": route.anchors.matched_aliases,
"target_terms": route.target_terms,
},
)
self._log_step(
context,
"alias_resolution",
{
"resolved_aliases": route.anchors.matched_aliases,
"target_doc_hints": route.anchors.target_doc_hints,
},
)
if not rag_session_id:
if route.intent == V2Intent.GENERAL_QA:
answer = "Не могу собрать grounded summary без активной RAG-сессии с проиндексированной документацией."
self._log_step(context, "evidence_gate_checked", {"passed": False, "reason": "missing_rag_session"})
self._log_step(context, "answer_generated", {"answer_mode": "insufficient_evidence"})
return ProcessResult(answer=answer)
return ProcessResult(answer="Для процесса v2 нужна активная RAG-сессия проекта с проиндексированной документацией.")
plan = self._policy_resolver.resolve(route)
context.trace.module("process.v2.retrieval_policy").log(
"retrieval_plan_resolved",
{"profile": plan.profile, "layers": plan.layers, "limit": plan.limit, "filters": plan.filters},
)
self._log_step(
context,
"retrieval_profile_selected",
{"profile": plan.profile, "layers": plan.layers, "filters": plan.filters},
)
retrieved_rows = await self._rag_adapter.fetch_rows(rag_session_id, route.normalized_query, plan)
metadata_rows = self._metadata_lookup_candidates(retrieved_rows, route)
rows = self._merge_candidate_rows(retrieved_rows, metadata_rows)
rows = seed_candidates_from_target_hints(rows, route.anchors.target_doc_hints, RagRowIndex(rows))
self._print_missing_target_hints(route, rows)
context.trace.module("process.v2.rag_retrieval").log(
"rag_rows_fetched",
{
"profile": plan.profile,
"row_count": len(rows),
"rows": [self._trace_row(row) for row in rows],
},
)
self._log_step(
context,
"candidate_generation",
{
"query": route.user_query,
"profile": plan.profile,
"details": {
"target_doc_hints": list(route.anchors.target_doc_hints),
"candidates_before_ranking": [row_path(row) for row in rows if row_path(row)],
},
"resolved_aliases": route.anchors.matched_aliases,
"target_doc_hints": route.anchors.target_doc_hints,
"candidate_docs_before_ranking": [self._trace_row(row) for row in rows[:8]],
"sources": {
"seeded": [self._trace_row(row) for row in retrieved_rows[:5] if row_path(row) in {normalize_doc_path(h) for h in route.anchors.target_doc_hints}],
"metadata_lookup": [self._trace_row(row) for row in metadata_rows[:5]],
"semantic": [self._trace_row(row) for row in retrieved_rows[:5]],
},
},
)
self._log_step(
context,
"retrieval_executed",
{
"query": route.user_query,
"profile": plan.profile,
"row_count": len(rows),
"target_doc_hints": route.anchors.target_doc_hints,
"top_results": [self._trace_row(row) for row in rows[:5]],
},
)
if route.subintent == V2Subintent.FIND_FILES:
files = self._evidence_assembler.assemble_files(rows, route)
gate = self._evidence_gate.check_files(route, files)
context.trace.module("process.v2.evidence").log(
"evidence_assembled",
{"mode": "find_files", "file_count": len(files), "files": [file.path for file in files]},
)
self._log_step(
context,
"evidence_assembled",
{"mode": "find_files", "primary_file": files[0].path if files else None, "file_count": len(files)},
)
self._log_ranking(context, files)
self._log_step(
context,
"evidence_gate_checked",
{"passed": gate.passed, "reason": gate.reason, "answer_mode": gate.answer_mode},
)
flow_context = DocsExplainFindFilesContext(
runtime=context,
route=route,
rag_session_id=rag_session_id,
files=files,
gate_decision=gate,
)
flow_context = await self._find_files_graph.run(flow_context)
self._log_step(context, "answer_generated", {"answer_mode": gate.answer_mode, "answer_length": len(flow_context.answer)})
return ProcessResult(answer=flow_context.answer)
documents = self._evidence_assembler.assemble_summaries(rows, route)
gate = self._evidence_gate.check_summaries(route, documents)
context.trace.module("process.v2.evidence").log(
"evidence_assembled",
{"mode": "summary", "document_count": len(documents), "documents": [item.path for item in documents]},
)
self._log_step(
context,
"evidence_assembled",
{"mode": "summary", "primary_doc": documents[0].path if documents else None, "document_count": len(documents)},
)
self._log_ranking(context, documents)
self._log_step(
context,
"evidence_gate_checked",
{"passed": gate.passed, "reason": gate.reason, "answer_mode": gate.answer_mode},
)
if route.intent == V2Intent.GENERAL_QA:
flow_context = GeneralSummaryContext(
runtime=context,
route=route,
prompt_name=self._general_summary_prompt_name,
workflow_llm_enabled=self._workflow_llm_enabled,
documents=documents,
gate_decision=gate,
)
flow_context = await self._general_summary_graph.run(flow_context)
self._log_step(context, "answer_generated", {"answer_mode": gate.answer_mode, "answer_length": len(flow_context.answer)})
return ProcessResult(answer=flow_context.answer)
flow_context = DocsExplainSummaryContext(
runtime=context,
route=route,
rag_session_id=rag_session_id,
prompt_name=self._docs_summary_prompt_name,
workflow_llm_enabled=self._workflow_llm_enabled,
documents=documents,
gate_decision=gate,
)
flow_context = await self._summary_graph.run(flow_context)
self._log_step(context, "answer_generated", {"answer_mode": gate.answer_mode, "answer_length": len(flow_context.answer)})
return ProcessResult(answer=flow_context.answer)
def _trace_row(self, row: dict) -> dict[str, object]:
metadata = row.get("metadata") or {}
content = str(row.get("content") or "").strip()
return {
"layer": str(row.get("layer") or ""),
"path": str(row.get("path") or ""),
"title": str(row.get("title") or ""),
"document_id": str(metadata.get("document_id") or metadata.get("doc_id") or ""),
"entity_name": str(metadata.get("entity_name") or ""),
"summary_text": str(metadata.get("summary_text") or "")[:400],
"section_path": str(metadata.get("section_path") or ""),
"content_preview": content[:400],
}
def _log_step(self, context, step: str, payload: dict[str, object]) -> None:
context.trace.module("process.v2.pipeline").log(step, payload)
def _print_missing_target_hints(self, route, rows: list[dict]) -> None:
if not route.anchors.target_doc_hints:
return
candidate_paths = normalized_path_set(rows)
for hint in route.anchors.target_doc_hints:
if not str(hint or "").strip():
continue
normalized = normalize_doc_path(hint)
if not normalized.startswith("docs/") or "." not in normalized.rsplit("/", 1)[-1]:
continue
if normalized not in candidate_paths:
print("ERROR: target doc missing from candidates:", normalized)
def _metadata_lookup_candidates(self, rows: list[dict], route) -> list[dict]:
return DocsMetadataLookupIndex(rows).lookup(route)
def _merge_candidate_rows(self, *groups: list[dict]) -> list[dict]:
return merge_row_lists(*groups)
def _log_ranking(self, context, items: list) -> None:
top_docs: list[dict[str, object]] = []
for item in items[:4]:
top_docs.append(
{
"doc": getattr(item, "path", ""),
"score": getattr(item, "score", 0),
"match_reason": getattr(item, "match_reason", ""),
}
)
context.trace.module("process.v2.pipeline").log(
"ranking_explained",
{
"doc": getattr(item, "path", ""),
"score_breakdown": getattr(item, "score_breakdown", {}),
"score": getattr(item, "score", 0),
"match_reason": getattr(item, "match_reason", ""),
},
)
context.trace.module("process.v2.pipeline").log(
"ranking_explained",
{
"top_docs_after_ranking": top_docs,
"ranking_score_breakdown": [
{
"doc": getattr(item, "path", ""),
"score_breakdown": getattr(item, "score_breakdown", {}),
}
for item in items[:4]
],
},
)
src/app/core/agent/processes/v2/prompts.yml
+8
View File
@@ -0,0 +1,8 @@
namespace: v2_docs_explain
prompts:
summary_answer: |
Ты объясняешь документацию только на основе найденных SUMMARY-блоков.
Используй только факты из входного контекста.
Если информации мало, прямо скажи об этом и не додумывай детали.
В конце перечисли файлы, на которые ты опирался.
src/app/core/agent/processes/v2/retrieval/__init__.py
+17
View File
@@ -0,0 +1,17 @@
from app.core.agent.processes.v2.retrieval.metadata_lookup import DocsMetadataLookupIndex
from app.core.agent.processes.v2.retrieval.policy_resolver import V2RetrievalPolicyResolver
from app.core.agent.processes.v2.retrieval.target_doc_seeding import (
RagRowIndex,
normalize_doc_path,
seed_candidates_from_target_hints,
)
from app.core.agent.processes.v2.retrieval.v2_rag_adapter import V2RagRetrievalAdapter
__all__ = [
"V2RetrievalPolicyResolver",
"V2RagRetrievalAdapter",
"DocsMetadataLookupIndex",
"normalize_doc_path",
"RagRowIndex",
"seed_candidates_from_target_hints",
]
src/app/core/agent/processes/v2/retrieval/metadata_lookup.py
+66
View File
@@ -0,0 +1,66 @@
from __future__ import annotations
import re
from collections import defaultdict
from app.core.agent.processes.v2.models import V2RouteResult
class DocsMetadataLookupIndex:
def __init__(self, rows: list[dict]) -> None:
self._rows_by_path: dict[str, dict] = {}
self._rows_by_basename: dict[str, list[dict]] = defaultdict(list)
self._rows_by_slug: dict[str, list[dict]] = defaultdict(list)
self._rows_by_title_token: dict[str, list[dict]] = defaultdict(list)
self._rows_by_compact: dict[str, list[dict]] = defaultdict(list)
for row in rows:
path = str(row.get("path") or "").strip()
if not path or path in self._rows_by_path:
continue
self._rows_by_path[path] = row
basename = path.split("/")[-1].lower()
slug = basename.removesuffix(".md").removesuffix(".yaml").removesuffix(".yml")
self._rows_by_basename[basename].append(row)
self._rows_by_slug[slug].append(row)
self._rows_by_compact[self._compact(slug)].append(row)
title = str(row.get("title") or "").lower()
for token in self._tokens(title):
self._rows_by_title_token[token].append(row)
self._rows_by_compact[self._compact(title)].append(row)
entity_name = str(dict(row.get("metadata") or {}).get("entity_name") or "").lower()
if entity_name:
self._rows_by_compact[self._compact(entity_name)].append(row)
def lookup(self, route: V2RouteResult) -> list[dict]:
candidates: list[dict] = []
seen: set[str] = set()
for path in route.anchors.target_doc_hints:
self._append(candidates, seen, self._rows_by_path.get(path))
lookup_tokens = list(route.target_terms) + list(route.anchors.matched_aliases) + list(route.anchors.endpoint_paths)
for token in self._tokens(" ".join(lookup_tokens)):
for bucket in (
self._rows_by_basename.get(token, []),
self._rows_by_slug.get(token, []),
self._rows_by_title_token.get(token, []),
):
for row in bucket:
self._append(candidates, seen, row)
for compact in {self._compact(item) for item in lookup_tokens if item}:
for row in self._rows_by_compact.get(compact, []):
self._append(candidates, seen, row)
return candidates
def _append(self, items: list[dict], seen: set[str], row: dict | None) -> None:
if row is None:
return
path = str(row.get("path") or "").strip()
if not path or path in seen:
return
seen.add(path)
items.append(row)
def _tokens(self, value: str) -> list[str]:
return [token for token in re.split(r"[^a-zA-Zа-яА-Я0-9]+", str(value or "").lower()) if len(token) >= 3]
def _compact(self, value: str) -> str:
return "".join(self._tokens(value))
src/app/core/agent/processes/v2/retrieval/policy_resolver.py
+270
View File
@@ -0,0 +1,270 @@
"""Intent-aware retrieval policy resolver for process v2."""
from __future__ import annotations
from app.core.agent.processes.v2.anchor_signals import anchor_signal_types
from app.core.agent.processes.v2.models import V2AnchorType, V2Intent, V2RouteResult, V2Subintent
from app.core.rag.contracts.enums import RagLayer
from app.core.rag.retrieval.session_retriever import RetrievalPlan
class _AnchorTermCollector:
def prefer_like_patterns(self, route: V2RouteResult) -> list[str]:
terms = self._hint_basenames(route)
terms.extend(route.anchors.endpoint_paths)
terms.extend(route.target_terms)
terms.extend(route.anchors.file_names)
terms.extend(route.anchors.entity_names)
terms.extend(route.anchors.matched_aliases)
terms.extend(self._process_terms(route))
return [f"%{term.lower()}%" for term in _unique_terms(terms)]
def find_files_patterns(self, route: V2RouteResult) -> list[str]:
if route.anchors.target_doc_hints:
return [f"%{name.lower()}%" for name in self._hint_basenames(route)]
return self.prefer_like_patterns(route)
def api_method_patterns(self, route: V2RouteResult) -> list[str]:
terms = self._hint_basenames(route)
terms.extend(route.anchors.target_doc_hints)
terms.extend(route.anchors.endpoint_paths)
terms.extend(route.target_terms)
patterns: list[str] = []
for term in _unique_terms(terms):
lowered = term.lower()
stripped = lowered.strip("/")
if stripped:
patterns.append(f"%{stripped}%")
if lowered:
patterns.append(f"%{lowered}%")
return _unique_terms(patterns)
def _hint_basenames(self, route: V2RouteResult) -> list[str]:
return [hint.rsplit("/", 1)[-1] for hint in route.anchors.target_doc_hints if str(hint).strip()]
def _process_terms(self, route: V2RouteResult) -> list[str]:
terms: list[str] = []
if route.anchors.process_domain:
terms.append(route.anchors.process_domain)
if route.anchors.process_subdomain:
terms.append(route.anchors.process_subdomain)
return terms
class _RouteFilterBuilder:
_API_DOC_PREFIXES = [
"docs/api/",
"docs/endpoints/",
"docs/methods/",
"api/",
"endpoints/",
"methods/",
]
def __init__(self) -> None:
self._terms = _AnchorTermCollector()
def general_filters(self, route: V2RouteResult) -> dict[str, object]:
return {
"prefer_path_prefixes": ["docs/architecture/", "docs/"],
"prefer_like_patterns": ["%readme.md%", "%overview%"],
"target_doc_hints": list(route.anchors.target_doc_hints),
}
def summary_filters(self, route: V2RouteResult) -> dict[str, object]:
if _is_api_method_explain(route):
return self.api_method_filters(route)
filters = self._base_filters(route)
filters["prefer_path_prefixes"] = self._summary_prefixes(route)
filters["prefer_like_patterns"] = self._terms.prefer_like_patterns(route)
if V2AnchorType.API_ENDPOINT in anchor_signal_types(route):
filters["path_prefixes"] = ["docs/api/", "docs/"]
return filters
def api_method_filters(self, route: V2RouteResult) -> dict[str, object]:
filters = self._base_filters(route)
filters["path_prefixes"] = list(self._API_DOC_PREFIXES)
filters["prefer_path_prefixes"] = list(self._API_DOC_PREFIXES)
filters["prefer_like_patterns"] = self._terms.api_method_patterns(route)
return filters
def find_files_filters(self, route: V2RouteResult) -> dict[str, object]:
filters = self._base_filters(route)
prefixes = self._find_files_prefixes(route)
if prefixes:
filters["path_prefixes"] = prefixes
filters["prefer_path_prefixes"] = self._find_files_prefer_prefixes(route, prefixes)
filters["prefer_like_patterns"] = self._terms.find_files_patterns(route)
return filters
def _base_filters(self, route: V2RouteResult) -> dict[str, object]:
filters: dict[str, object] = {
"target_doc_hints": list(route.anchors.target_doc_hints),
}
if route.anchors.process_domain:
filters["metadata.domain"] = route.anchors.process_domain
if route.anchors.process_subdomain:
filters["metadata.subdomain"] = route.anchors.process_subdomain
return filters
def _find_files_prefixes(self, route: V2RouteResult) -> list[str]:
hint_prefixes = _prefixes_from_paths(route.anchors.target_doc_hints)
if hint_prefixes:
return hint_prefixes
file_prefixes = [name for name in route.anchors.file_names if str(name).strip().startswith("docs/")]
derived = _prefixes_from_paths(file_prefixes)
if derived:
return derived
signals = anchor_signal_types(route)
if V2AnchorType.API_ENDPOINT in signals:
return ["docs/api/", "docs/"]
if V2AnchorType.ARCHITECTURE in signals:
return ["docs/architecture/", "docs/"]
if V2AnchorType.LOGIC_FLOW in signals:
return ["docs/logic/", "docs/"]
if V2AnchorType.DOMAIN_ENTITY in signals:
return ["docs/domains/", "docs/"]
return ["docs/"]
def _find_files_prefer_prefixes(self, route: V2RouteResult, prefixes: list[str]) -> list[str]:
preferred = list(prefixes)
if route.anchors.process_domain or route.anchors.process_subdomain:
preferred.extend(["docs/domains/", "docs/logic/"])
return _unique_terms(preferred or ["docs/"])
def _summary_prefixes(self, route: V2RouteResult) -> list[str]:
signals = anchor_signal_types(route)
prefixes: list[str] = []
if V2AnchorType.API_ENDPOINT in signals:
prefixes.extend(["docs/api/", "docs/"])
if V2AnchorType.ARCHITECTURE in signals:
prefixes.extend(["docs/architecture/", "docs/"])
if V2AnchorType.LOGIC_FLOW in signals:
prefixes.extend(["docs/logic/", "docs/architecture/", "docs/"])
if V2AnchorType.DOMAIN_ENTITY in signals:
prefixes.extend(["docs/domains/", "docs/", "docs/api/"])
return _unique_terms(prefixes or ["docs/"])
class V2RetrievalPolicyResolver:
_GENERAL_LAYERS = [RagLayer.DOCS_DOCUMENT_CATALOG, RagLayer.DOCS_DOC_CHUNKS]
_FIND_FILES_LAYERS = [RagLayer.DOCS_DOCUMENT_CATALOG, RagLayer.DOCS_ENTITY_CATALOG]
_SUMMARY_LAYERS = {
"docs_api_method_explain": [
RagLayer.DOCS_DOCUMENT_CATALOG,
RagLayer.DOCS_FACT_INDEX,
RagLayer.DOCS_DOC_CHUNKS,
],
"docs_summary_api_endpoint": [
RagLayer.DOCS_DOCUMENT_CATALOG,
RagLayer.DOCS_FACT_INDEX,
RagLayer.DOCS_DOC_CHUNKS,
],
"docs_summary_logic_flow": [
RagLayer.DOCS_WORKFLOW_INDEX,
RagLayer.DOCS_DOCUMENT_CATALOG,
RagLayer.DOCS_DOC_CHUNKS,
],
"docs_summary_domain_entity": [
RagLayer.DOCS_ENTITY_CATALOG,
RagLayer.DOCS_DOCUMENT_CATALOG,
RagLayer.DOCS_DOC_CHUNKS,
],
"docs_summary_architecture": [
RagLayer.DOCS_DOCUMENT_CATALOG,
RagLayer.DOCS_RELATION_GRAPH,
RagLayer.DOCS_DOC_CHUNKS,
],
"docs_summary_generic": [
RagLayer.DOCS_DOCUMENT_CATALOG,
RagLayer.DOCS_DOC_CHUNKS,
],
}
def __init__(self) -> None:
self._filters = _RouteFilterBuilder()
def resolve(self, route: V2RouteResult) -> RetrievalPlan:
if route.intent == V2Intent.GENERAL_QA:
return RetrievalPlan(
profile="general_qa_grounded_summary",
layers=list(self._GENERAL_LAYERS),
limit=8,
filters=self._filters.general_filters(route),
)
if route.subintent == V2Subintent.FIND_FILES:
return RetrievalPlan(
profile="file_lookup",
layers=list(self._FIND_FILES_LAYERS),
limit=12,
filters=self._filters.find_files_filters(route),
)
profile = self._summary_profile(route)
return RetrievalPlan(
profile=profile,
layers=list(self._SUMMARY_LAYERS[profile]),
limit=10 if profile == "docs_api_method_explain" else 8,
filters=self._filters.summary_filters(route),
)
def _summary_profile(self, route: V2RouteResult) -> str:
if _is_api_method_explain(route):
return "docs_api_method_explain"
meaningful = anchor_signal_types(route) - {V2AnchorType.FIND_FILES}
if len(meaningful) != 1:
return "docs_summary_generic"
mapping = {
V2AnchorType.API_ENDPOINT: "docs_summary_api_endpoint",
V2AnchorType.ARCHITECTURE: "docs_summary_architecture",
V2AnchorType.LOGIC_FLOW: "docs_summary_logic_flow",
V2AnchorType.DOMAIN_ENTITY: "docs_summary_domain_entity",
}
return mapping.get(next(iter(meaningful)), "docs_summary_generic")
def _prefixes_from_paths(paths: list[str]) -> list[str]:
prefixes = []
for path in paths:
value = str(path).strip().strip("/")
if "/" not in value:
continue
prefix = value.rsplit("/", 1)[0] + "/"
if prefix:
prefixes.append(prefix)
return _unique_terms(prefixes)
def _unique_terms(items: list[str]) -> list[str]:
seen: set[str] = set()
unique: list[str] = []
for raw in items:
value = str(raw or "").strip()
if not value or value in seen:
continue
seen.add(value)
unique.append(value)
return unique
def _is_api_method_explain(route: V2RouteResult) -> bool:
if route.subintent != V2Subintent.SUMMARY:
return False
if route.anchors.endpoint_paths:
return True
if _has_api_like_hints(route.anchors.target_doc_hints):
return True
return V2AnchorType.API_ENDPOINT in anchor_signal_types(route)
def _has_api_like_hints(hints: list[str]) -> bool:
for hint in hints:
value = str(hint or "").strip().lower()
if not value:
continue
if value.startswith("/"):
return True
if value.startswith(("docs/api/", "docs/endpoints/", "docs/methods/")):
return True
if "endpoint" in value or "method" in value:
return True
return False
src/app/core/agent/processes/v2/retrieval/target_doc_seeding.py
+114
View File
@@ -0,0 +1,114 @@
from __future__ import annotations
def normalize_doc_path(path: str | None) -> str:
value = str(path or "").strip().replace("\\", "/")
if not value:
return ""
while "//" in value:
value = value.replace("//", "/")
while value.startswith("./"):
value = value[2:]
value = value.lstrip("/")
docs_idx = value.lower().find("docs/")
if docs_idx >= 0:
value = value[docs_idx:]
elif "/" not in value and value.lower().endswith(".md"):
value = f"docs/{value}"
return value.strip()
def row_path(row: dict) -> str:
metadata = dict(row.get("metadata") or {})
raw = row.get("path") or metadata.get("source_path") or ""
return normalize_doc_path(str(raw))
def normalized_path_set(rows: list[dict]) -> set[str]:
return {path for row in rows if (path := row_path(row))}
def path_variants_for_rag_query(path: str | None) -> list[str]:
normalized = normalize_doc_path(path)
if not normalized:
return []
variants = [normalized]
if normalized.startswith("docs/"):
variants.append(normalized.removeprefix("docs/"))
else:
variants.append(f"docs/{normalized}")
basename = normalized.split("/")[-1]
if basename and basename not in variants:
variants.append(basename)
return list(dict.fromkeys(variants))
def merge_row_lists(*groups: list[dict]) -> list[dict]:
merged: list[dict] = []
seen: set[tuple[str, str, str]] = set()
for rows in groups:
for row in rows:
metadata = dict(row.get("metadata") or {})
key = (
row_path(row),
str(row.get("layer") or ""),
str(metadata.get("section_path") or ""),
)
if key in seen:
continue
seen.add(key)
merged.append(row)
return merged
class RagRowIndex:
def __init__(self, rows: list[dict]) -> None:
self._by_path: dict[str, list[dict]] = {}
self._by_name: dict[str, list[dict]] = {}
for row in rows:
normalized = row_path(row)
if not normalized:
continue
self._by_path.setdefault(normalized.lower(), []).append(row)
basename = normalized.split("/")[-1].lower()
self._by_name.setdefault(basename, []).append(row)
def lookup(self, hint: str | None) -> list[dict]:
matches: list[dict] = []
seen_ids: set[int] = set()
for variant in path_variants_for_rag_query(hint):
key = variant.lower()
for row in self._by_path.get(key, []):
row_id = id(row)
if row_id in seen_ids:
continue
seen_ids.add(row_id)
matches.append(row)
basename = normalize_doc_path(hint).split("/")[-1].lower()
for row in self._by_name.get(basename, []):
row_id = id(row)
if row_id in seen_ids:
continue
seen_ids.add(row_id)
matches.append(row)
return matches
def seed_candidates_from_target_hints(rows: list[dict], hints: list[str], index: RagRowIndex | None = None) -> list[dict]:
hints_raw = [str(hint).strip() for hint in hints if str(hint or "").strip()]
if not hints_raw or not rows:
return rows
rag_index = index or RagRowIndex(rows)
seeded = [match for hint in hints_raw for match in rag_index.lookup(hint)]
return merge_row_lists(seeded, rows)
__all__ = [
"RagRowIndex",
"merge_row_lists",
"normalize_doc_path",
"normalized_path_set",
"path_variants_for_rag_query",
"row_path",
"seed_candidates_from_target_hints",
]
src/app/core/agent/processes/v2/retrieval/v2_rag_adapter.py
+108
View File
@@ -0,0 +1,108 @@
"""Адаптер v2 к :class:`RagSessionRetriever` с plan-driven execution strategy."""
from __future__ import annotations
from app.core.agent.processes.v2.retrieval.target_doc_seeding import (
merge_row_lists,
normalize_doc_path,
path_variants_for_rag_query,
)
from app.core.rag.retrieval.session_retriever import RagSessionRetriever, RetrievalPlan
class _PlanDrivenRetrieval:
def __init__(self, retriever: RagSessionRetriever) -> None:
self._retriever = retriever
async def fetch_rows(self, rag_session_id: str, query_text: str, plan: RetrievalPlan) -> list[dict]:
seeded_rows = await self._seed_from_target_hints(rag_session_id, plan)
semantic_rows = await self._retriever.retrieve(rag_session_id, query_text, plan)
return merge_row_lists(seeded_rows, semantic_rows)
async def fetch_exact_paths(self, rag_session_id: str, *, paths: list[str], layers: list[str] | None = None) -> list[dict]:
return await self._retriever.retrieve_exact_files(rag_session_id, paths=paths, layers=layers)
async def fetch_chunks_by_path_substrings(
self,
rag_session_id: str,
*,
path_needles: list[str],
layers: list[str] | None = None,
limit: int = 200,
) -> list[dict]:
return await self._retriever.retrieve_chunks_by_path_substrings(
rag_session_id,
path_needles=path_needles,
layers=layers,
limit=limit,
)
async def _seed_from_target_hints(self, rag_session_id: str, plan: RetrievalPlan) -> list[dict]:
hints = self._target_doc_hints(plan)
if not hints:
return []
exact_rows = await self._fetch_exact_rows(rag_session_id, hints)
missing = self._missing_hints(hints, exact_rows)
if not missing:
return exact_rows
fallback_rows = await self._fetch_substring_rows(rag_session_id, missing)
return merge_row_lists(exact_rows, fallback_rows)
async def _fetch_exact_rows(self, rag_session_id: str, hints: list[str]) -> list[dict]:
variant_paths: list[str] = []
for hint in hints:
variant_paths.extend(path_variants_for_rag_query(hint))
unique_paths = list(dict.fromkeys(path for path in variant_paths if path))
if not unique_paths:
return []
return await self._retriever.retrieve_exact_files(rag_session_id, paths=unique_paths, layers=None)
async def _fetch_substring_rows(self, rag_session_id: str, hints: list[str]) -> list[dict]:
needles = [normalize_doc_path(hint).split("/")[-1] for hint in hints]
unique_needles = list(dict.fromkeys(needle for needle in needles if needle))
if not unique_needles:
return []
return await self._retriever.retrieve_chunks_by_path_substrings(
rag_session_id,
path_needles=unique_needles,
layers=None,
limit=200,
)
def _target_doc_hints(self, plan: RetrievalPlan) -> list[str]:
raw = plan.filters.get("target_doc_hints")
if not isinstance(raw, list):
return []
return [str(item).strip() for item in raw if str(item or "").strip()]
def _missing_hints(self, hints: list[str], rows: list[dict]) -> list[str]:
pool = {normalize_doc_path(str(row.get("path") or "")) for row in rows}
return [hint for hint in hints if normalize_doc_path(hint) not in pool]
class V2RagRetrievalAdapter:
"""Обёртка над :class:`RagSessionRetriever` для plan-driven retrieval и подмены в тестах."""
def __init__(self, retriever: RagSessionRetriever) -> None:
self._retriever = _PlanDrivenRetrieval(retriever)
async def fetch_rows(self, rag_session_id: str, query_text: str, plan: RetrievalPlan) -> list[dict]:
return await self._retriever.fetch_rows(rag_session_id, query_text, plan)
async def fetch_exact_paths(self, rag_session_id: str, *, paths: list[str], layers: list[str] | None = None) -> list[dict]:
return await self._retriever.fetch_exact_paths(rag_session_id, paths=paths, layers=layers)
async def fetch_chunks_by_path_substrings(
self,
rag_session_id: str,
*,
path_needles: list[str],
layers: list[str] | None = None,
limit: int = 200,
) -> list[dict]:
return await self._retriever.fetch_chunks_by_path_substrings(
rag_session_id,
path_needles=path_needles,
layers=layers,
limit=limit,
)
src/app/modules/agent/orchestration/__init__.py → src/app/core/agent/processes/v2/workflows/__init__.py
View File
src/app/core/agent/processes/v2/workflows/docs_explain_find_files/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.processes.v2.workflows.docs_explain_find_files.graph import DocsExplainFindFilesGraph
__all__ = ["DocsExplainFindFilesGraph"]
src/app/core/agent/processes/v2/workflows/docs_explain_find_files/context.py
+17
View File
@@ -0,0 +1,17 @@
from __future__ import annotations
from dataclasses import dataclass, field
from app.core.agent.processes.v2.evidence.gate import EvidenceGateDecision
from app.core.agent.processes.v2.models import RetrievedFile, V2RouteResult
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
@dataclass(slots=True)
class DocsExplainFindFilesContext:
runtime: RuntimeExecutionContext
route: V2RouteResult
rag_session_id: str
files: list[RetrievedFile] = field(default_factory=list)
gate_decision: EvidenceGateDecision | None = None
answer: str = ""
src/app/core/agent/processes/v2/workflows/docs_explain_find_files/graph.py
+16
View File
@@ -0,0 +1,16 @@
from __future__ import annotations
from app.core.agent.processes.v2.workflows.docs_explain_find_files.context import DocsExplainFindFilesContext
from app.core.agent.processes.v2.workflows.docs_explain_find_files.steps.finalize_find_files_answer_step import (
FinalizeFindFilesAnswerStep,
)
from app.core.agent.processes.v2.workflows.v2_workflow_graph import V2WorkflowGraph
class DocsExplainFindFilesGraph(V2WorkflowGraph[DocsExplainFindFilesContext]):
def __init__(self) -> None:
super().__init__(
workflow_id="v2.docs_explain.find_files",
source="workflow.v2.find_files",
steps=[FinalizeFindFilesAnswerStep()],
)
src/app/core/agent/processes/v2/workflows/docs_explain_find_files/steps/finalize_find_files_answer_step.py
+25
View File
@@ -0,0 +1,25 @@
from __future__ import annotations
from app.core.agent.processes.v2.workflows.docs_explain_find_files.context import DocsExplainFindFilesContext
from app.core.agent.utils.workflow import WorkflowStep
class FinalizeFindFilesAnswerStep(WorkflowStep[DocsExplainFindFilesContext]):
step_id = "finalize_find_files_answer"
title = "Сборка списка файлов"
async def run(self, context: DocsExplainFindFilesContext) -> DocsExplainFindFilesContext:
if not context.files:
context.answer = "Не нашёл файлов документации, которые уверенно соответствуют запросу."
return context
if context.gate_decision is not None and context.gate_decision.reason == "low_confidence_shortlist":
context.answer = "\n".join(item.path for item in context.files[:4])
return context
if len(context.files) == 1:
context.answer = context.files[0].path
return context
context.answer = "\n".join(item.path for item in context.files[:4])
return context
def trace_output(self, context: DocsExplainFindFilesContext) -> dict[str, object]:
return {"answer_length": len(context.answer)}
src/app/core/agent/processes/v2/workflows/docs_explain_summary/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.processes.v2.workflows.docs_explain_summary.graph import DocsExplainSummaryGraph
__all__ = ["DocsExplainSummaryGraph"]
src/app/core/agent/processes/v2/workflows/docs_explain_summary/context.py
+20
View File
@@ -0,0 +1,20 @@
from __future__ import annotations
from dataclasses import dataclass, field
from app.core.agent.processes.v2.evidence.gate import EvidenceGateDecision
from app.core.agent.processes.v2.models import RetrievedSummary, V2RouteResult
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
@dataclass(slots=True)
class DocsExplainSummaryContext:
runtime: RuntimeExecutionContext
route: V2RouteResult
rag_session_id: str
prompt_name: str
workflow_llm_enabled: bool = True
documents: list[RetrievedSummary] = field(default_factory=list)
gate_decision: EvidenceGateDecision | None = None
prompt_input: str = ""
answer: str = ""
src/app/core/agent/processes/v2/workflows/docs_explain_summary/graph.py
+17
View File
@@ -0,0 +1,17 @@
from __future__ import annotations
from app.core.agent.processes.v2.workflows.docs_explain_summary.context import DocsExplainSummaryContext
from app.core.agent.processes.v2.workflows.docs_explain_summary.steps.generate_summary_answer_step import (
GenerateSummaryAnswerStep,
)
from app.core.agent.processes.v2.workflows.v2_workflow_graph import V2WorkflowGraph
from app.core.agent.utils.llm import AgentLlmService
class DocsExplainSummaryGraph(V2WorkflowGraph[DocsExplainSummaryContext]):
def __init__(self, llm: AgentLlmService) -> None:
super().__init__(
workflow_id="v2.docs_explain.summary",
source="workflow.v2.summary",
steps=[GenerateSummaryAnswerStep(llm)],
)
src/app/core/agent/processes/v2/workflows/docs_explain_summary/steps/generate_summary_answer_step.py
+68
View File
@@ -0,0 +1,68 @@
from __future__ import annotations
import asyncio
import json
from app.core.agent.processes.v2.anchor_signals import route_anchor_summary
from app.core.agent.utils.llm import AgentLlmService
from app.core.agent.processes.v2.workflows.docs_explain_summary.context import DocsExplainSummaryContext
from app.core.agent.utils.workflow import WorkflowStep
class GenerateSummaryAnswerStep(WorkflowStep[DocsExplainSummaryContext]):
step_id = "generate_summary_answer"
title = "Сборка ответа по summary"
def __init__(self, llm: AgentLlmService) -> None:
self._llm = llm
async def run(self, context: DocsExplainSummaryContext) -> DocsExplainSummaryContext:
if context.gate_decision is not None and not context.gate_decision.passed:
context.answer = context.gate_decision.message
return context
if not context.workflow_llm_enabled:
context.answer = self._build_deterministic_answer(context)
return context
if not context.documents:
context.answer = "Не нашёл подходящих SUMMARY-блоков в документации по этому запросу."
return context
context.prompt_input = self._build_prompt_input(context)
request_id = context.runtime.request.request_id
context.answer = await asyncio.to_thread(
self._llm.generate,
context.prompt_name,
context.prompt_input,
log_context=f"agent:{request_id}",
trace=context.runtime.trace.module("workflow.v2.summary.llm"),
)
return context
def _build_prompt_input(self, context: DocsExplainSummaryContext) -> str:
blocks = [
f"Запрос пользователя:\n{context.route.user_query}",
"Сигналы запроса:\n" + json.dumps(route_anchor_summary(context.route), ensure_ascii=False, indent=2),
"Найденные SUMMARY-блоки:",
]
for index, item in enumerate(context.documents, start=1):
blocks.append(
f"{index}. path: {item.path}\n"
f"title: {item.title}\n"
f"match_reason: {item.match_reason}\n"
f"summary: {item.summary}"
)
return "\n\n".join(blocks)
def _build_deterministic_answer(self, context: DocsExplainSummaryContext) -> str:
if not context.documents:
return "Не нашёл подходящих SUMMARY-блоков в документации по этому запросу."
lines = []
primary = context.documents[0]
lines.append(primary.summary)
lines.append("")
lines.append("Файлы-источники:")
for item in context.documents:
lines.append(f"- {item.path}")
return "\n".join(lines)
def trace_output(self, context: DocsExplainSummaryContext) -> dict[str, object]:
return {"answer_length": len(context.answer)}
src/app/core/agent/processes/v2/workflows/general_summary/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.processes.v2.workflows.general_summary.graph import GeneralSummaryGraph
__all__ = ["GeneralSummaryGraph"]
src/app/core/agent/processes/v2/workflows/general_summary/context.py
+19
View File
@@ -0,0 +1,19 @@
from __future__ import annotations
from dataclasses import dataclass, field
from app.core.agent.processes.v2.evidence.gate import EvidenceGateDecision
from app.core.agent.processes.v2.models import RetrievedSummary, V2RouteResult
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
@dataclass(slots=True)
class GeneralSummaryContext:
runtime: RuntimeExecutionContext
route: V2RouteResult
prompt_name: str
workflow_llm_enabled: bool = True
documents: list[RetrievedSummary] = field(default_factory=list)
gate_decision: EvidenceGateDecision | None = None
prompt_input: str = ""
answer: str = ""
src/app/core/agent/processes/v2/workflows/general_summary/graph.py
+17
View File
@@ -0,0 +1,17 @@
from __future__ import annotations
from app.core.agent.processes.v2.workflows.general_summary.context import GeneralSummaryContext
from app.core.agent.processes.v2.workflows.general_summary.steps.generate_general_summary_answer_step import (
GenerateGeneralSummaryAnswerStep,
)
from app.core.agent.processes.v2.workflows.v2_workflow_graph import V2WorkflowGraph
from app.core.agent.utils.llm import AgentLlmService
class GeneralSummaryGraph(V2WorkflowGraph[GeneralSummaryContext]):
def __init__(self, llm: AgentLlmService) -> None:
super().__init__(
workflow_id="v2.general_qa.summary",
source="workflow.v2.general_summary",
steps=[GenerateGeneralSummaryAnswerStep(llm)],
)
src/app/core/agent/processes/v2/workflows/general_summary/steps/generate_general_summary_answer_step.py
+57
View File
@@ -0,0 +1,57 @@
from __future__ import annotations
import asyncio
from app.core.agent.processes.v2.workflows.general_summary.context import GeneralSummaryContext
from app.core.agent.utils.llm import AgentLlmService
from app.core.agent.utils.workflow import WorkflowStep
class GenerateGeneralSummaryAnswerStep(WorkflowStep[GeneralSummaryContext]):
step_id = "generate_general_summary_answer"
title = "Общий ответ через LLM"
def __init__(self, llm: AgentLlmService) -> None:
self._llm = llm
async def run(self, context: GeneralSummaryContext) -> GeneralSummaryContext:
if context.gate_decision is not None and not context.gate_decision.passed:
context.answer = context.gate_decision.message
return context
if not context.workflow_llm_enabled:
context.answer = self._build_deterministic_answer(context)
return context
context.prompt_input = self._build_prompt_input(context)
request_id = context.runtime.request.request_id
context.answer = await asyncio.to_thread(
self._llm.generate,
context.prompt_name,
context.prompt_input,
log_context=f"agent:{request_id}",
trace=context.runtime.trace.module("workflow.v2.general_summary.llm"),
)
return context
def _build_prompt_input(self, context: GeneralSummaryContext) -> str:
blocks = [
f"Запрос пользователя:\n{context.route.user_query}",
"Опорные документы:",
]
for index, item in enumerate(context.documents, start=1):
blocks.append(
f"{index}. path: {item.path}\n"
f"title: {item.title}\n"
f"summary: {item.summary}"
)
return "\n\n".join(blocks)
def _build_deterministic_answer(self, context: GeneralSummaryContext) -> str:
if not context.documents:
return "В найденной документации нет достаточной опоры для общего summary по запросу."
return "\n".join(item.summary for item in context.documents[:2] if item.summary)
def trace_input(self, context: GeneralSummaryContext) -> dict[str, object]:
return {"query": context.route.normalized_query}
def trace_output(self, context: GeneralSummaryContext) -> dict[str, object]:
return {"answer_length": len(context.answer)}
src/app/core/agent/processes/v2/workflows/v2_workflow_graph.py
+39
View File
@@ -0,0 +1,39 @@
"""Workflow-граф v2: буфер шаговых логов и один сброс в trace в конце прогона."""
from __future__ import annotations
from typing import Generic, Sequence, TypeVar
from app.core.agent.utils.workflow.context import WorkflowContext
from app.core.agent.utils.workflow.graph import WorkflowGraph
from app.core.agent.utils.workflow.step import WorkflowStep
TContext = TypeVar("TContext", bound=WorkflowContext)
class V2WorkflowGraph(WorkflowGraph[TContext]):
"""Не логирует step_started/step_completed по отдельности; сбрасывает буфер в ``workflow_trace_flushed``."""
async def run(self, context: TContext) -> TContext:
trace = context.runtime.trace.module(self._source)
trace.log("workflow_started", {"workflow_id": self._workflow_id})
steps_buffer: list[dict[str, object]] = []
for step in self._steps:
inp = step.trace_input(context)
request_id = context.runtime.request.request_id
await context.runtime.publisher.publish_status(
request_id,
self._source,
f"Шаг workflow: {step.title}.",
{"workflow_id": self._workflow_id, "step_id": step.step_id},
)
context = await step.run(context)
out = step.trace_output(context)
steps_buffer.append({"step_id": step.step_id, "title": step.title, "input": inp, "output": out})
trace.log(
"workflow_trace_flushed",
{"workflow_id": self._workflow_id, "steps": steps_buffer},
)
trace.log("workflow_completed", {"workflow_id": self._workflow_id})
return context
src/app/core/agent/runtime/__init__.py
+13
View File
@@ -0,0 +1,13 @@
from app.core.agent.runtime.agent_runtime import AgentRuntime
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
from app.core.agent.runtime.process_registry import ProcessRegistry
from app.core.agent.runtime.process_runner import ProcessRunner
from app.core.agent.runtime.publisher import RuntimeEventPublisher
__all__ = [
"AgentRuntime",
"ProcessRegistry",
"ProcessRunner",
"RuntimeEventPublisher",
"RuntimeExecutionContext",
]
src/app/core/agent/runtime/agent_runtime.py
+107
View File
@@ -0,0 +1,107 @@
from __future__ import annotations
from datetime import datetime, timezone
from app.core.api.application.session_service import SessionService
from app.core.api.domain.models.agent_request import AgentRequest
from app.core.api.domain.models.agent_session import AgentSession
from app.core.api.infrastructure.stores.in_memory_request_store import InMemoryRequestStore
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
from app.core.agent.runtime.process_registry import ProcessRegistry
from app.core.agent.runtime.process_runner import ProcessRunner
from app.core.agent.runtime.publisher import RuntimeEventPublisher
from app.infra.exceptions import AppError
from app.infra.observability.module_trace import RequestTraceContext
from app.infra.observability.request_trace_logger import RequestTraceLogger
from app.schemas.common import ErrorPayload, ModuleName
from app.schemas.orchestration import RequestExecutionStatus
class AgentRuntime:
def __init__(
self,
request_store: InMemoryRequestStore,
sessions: SessionService,
process_registry: ProcessRegistry,
process_runner: ProcessRunner,
publisher: RuntimeEventPublisher,
trace_logger: RequestTraceLogger,
) -> None:
self._request_store = request_store
self._sessions = sessions
self._process_registry = process_registry
self._process_runner = process_runner
self._publisher = publisher
self._trace_logger = trace_logger
async def run(self, request: AgentRequest, session: AgentSession) -> None:
try:
process = self._resolve_process(request.process_version)
self._start_request(request, session)
context = RuntimeExecutionContext(
request=request,
session=session,
publisher=self._publisher,
trace=RequestTraceContext(request_id=request.request_id, logger=self._trace_logger),
)
await self._announce_start(request.request_id, process.version)
result = await self._process_runner.run(context, process)
request.answer = result.answer
await self._publish_result(request)
self._complete_request(request, session)
except Exception as exc:
await self._fail_request(request, exc)
def _resolve_process(self, version: str):
process = self._process_registry.get(version)
if process is None:
raise AppError("process_not_found", f"Unsupported process version: {version}", ModuleName.AGENT)
return process
def _start_request(self, request: AgentRequest, session: AgentSession) -> None:
request.status = RequestExecutionStatus.RUNNING
self._request_store.save(request)
self._trace_logger.start_request(request, session)
async def _announce_start(self, request_id: str, process_version: str) -> None:
await self._publisher.publish_status(request_id, "runtime", "Запрос принят и поставлен в обработку.")
await self._publisher.publish_status(
request_id,
"runtime",
f"Запускаю процесс {process_version}.",
{"process_version": process_version},
)
async def _publish_result(self, request: AgentRequest) -> None:
await self._publisher.publish_user(request.request_id, "agent", request.answer or "")
await self._publisher.publish_status(request.request_id, "runtime", "Обработка запроса завершена.")
def _complete_request(self, request: AgentRequest, session: AgentSession) -> None:
session.append_turn(user_message=request.message, assistant_message=request.answer or "")
self._sessions.save(session)
request.status = RequestExecutionStatus.DONE
request.completed_at = datetime.now(timezone.utc)
self._request_store.save(request)
self._trace_logger.complete_request(request)
async def _fail_request(self, request: AgentRequest, exc: Exception) -> None:
request.status = RequestExecutionStatus.ERROR
request.completed_at = datetime.now(timezone.utc)
request.error = self._build_error_payload(exc)
self._request_store.save(request)
self._trace_logger.fail_request(request)
await self._publisher.publish_status(
request.request_id,
"runtime",
"Во время обработки запроса произошла ошибка.",
{"code": request.error.code},
)
def _build_error_payload(self, exc: Exception) -> ErrorPayload:
if isinstance(exc, AppError):
return ErrorPayload(code=exc.code, desc=exc.desc, module=exc.module)
return ErrorPayload(
code="api_runtime_error",
desc="Agent request failed unexpectedly.",
module=ModuleName.AGENT,
)
src/app/core/agent/runtime/execution_context.py
+20
View File
@@ -0,0 +1,20 @@
from __future__ import annotations
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any
from app.core.api.domain.models.agent_request import AgentRequest
from app.core.api.domain.models.agent_session import AgentSession
from app.infra.observability.module_trace import RequestTraceContext
if TYPE_CHECKING:
from app.core.agent.runtime.publisher import RuntimeEventPublisher
@dataclass(slots=True)
class RuntimeExecutionContext:
request: AgentRequest
session: AgentSession
publisher: "RuntimeEventPublisher"
trace: RequestTraceContext
state: dict[str, Any] = field(default_factory=dict)
src/app/core/agent/runtime/process_registry.py
+13
View File
@@ -0,0 +1,13 @@
from __future__ import annotations
from collections.abc import Iterable
from app.core.agent.processes.base import AgentProcess
class ProcessRegistry:
def __init__(self, processes: Iterable[AgentProcess]) -> None:
self._items = {process.version: process for process in processes}
def get(self, version: str) -> AgentProcess | None:
return self._items.get(version)
src/app/core/agent/runtime/process_runner.py
+9
View File
@@ -0,0 +1,9 @@
from __future__ import annotations
from app.core.agent.processes.base import AgentProcess, ProcessResult
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
class ProcessRunner:
async def run(self, context: RuntimeExecutionContext, process: AgentProcess) -> ProcessResult:
return await process.run(context)
src/app/core/agent/runtime/publisher.py
+36
View File
@@ -0,0 +1,36 @@
from __future__ import annotations
from app.core.api.domain.events.client_event import ClientEventRecord
from app.core.api.infrastructure.streaming.sse_event_channel import SseEventChannel
from app.infra.observability.request_trace_logger import RequestTraceLogger
from app.schemas.client_events import ClientEventType
class RuntimeEventPublisher:
def __init__(self, channel: SseEventChannel, trace_logger: RequestTraceLogger) -> None:
self._channel = channel
self._trace_logger = trace_logger
async def publish_status(self, request_id: str, source: str, text: str, payload: dict | None = None) -> None:
await self._publish(request_id, ClientEventType.STATUS, source, text, payload)
async def publish_user(self, request_id: str, source: str, text: str, payload: dict | None = None) -> None:
await self._publish(request_id, ClientEventType.USER, source, text, payload)
async def _publish(
self,
request_id: str,
event_type: ClientEventType,
source: str,
text: str,
payload: dict | None = None,
) -> None:
event = ClientEventRecord(
request_id=request_id,
type=event_type,
source=source,
text=text,
payload=payload or {},
)
self._trace_logger.log_event(event)
await self._channel.publish(event)
src/app/core/agent/utils/__init__.py
+3
View File
@@ -0,0 +1,3 @@
from app.core.agent.utils.llm import AgentLlmService, PromptLoader
__all__ = ["AgentLlmService", "PromptLoader"]
src/app/core/agent/utils/llm/__init__.py
+4
View File
@@ -0,0 +1,4 @@
from app.core.agent.utils.llm.prompt_loader import PromptLoader
from app.core.agent.utils.llm.service import AgentLlmService
__all__ = ["AgentLlmService", "PromptLoader"]
src/app/core/agent/utils/llm/prompt_loader.py
+43
View File
@@ -0,0 +1,43 @@
from __future__ import annotations
import os
from collections.abc import Iterable
from pathlib import Path
import yaml
class PromptLoader:
def __init__(self, prompts_path: Path | Iterable[Path] | None = None) -> None:
self._paths = self._resolve_paths(prompts_path)
self._prompts = self._load_prompts()
def load(self, name: str) -> str:
return str(self._prompts.get(name, "") or "").strip()
def _load_prompts(self) -> dict[str, str]:
merged: dict[str, str] = {}
for path in self._paths:
if not path.is_file():
continue
payload = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
if not isinstance(payload, dict):
continue
namespace = str(payload.get("namespace") or "").strip()
prompts = payload.get("prompts", payload)
if not isinstance(prompts, dict):
continue
for key, value in prompts.items():
prompt_name = f"{namespace}.{key}" if namespace else str(key)
merged[prompt_name] = str(value or "")
return merged
def _resolve_paths(self, prompts_path: Path | Iterable[Path] | None) -> tuple[Path, ...]:
if prompts_path is None:
base = Path(__file__).resolve().parent / "prompts.yml"
env_override = os.getenv("AGENT_PROMPTS_DIR", "").strip()
raw_path = Path(env_override) if env_override else base
return (raw_path / "prompts.yml" if raw_path.is_dir() else raw_path,)
if isinstance(prompts_path, Path):
return (prompts_path,)
return tuple(Path(item) for item in prompts_path)
src/app/modules/agent/llm/service.py → src/app/core/agent/utils/llm/service.py
+5 -3
View File
@@ -1,8 +1,10 @@
from __future__ import annotations
import logging
from app.modules.agent.observability.module_trace import ModuleTrace
from app.modules.agent.llm.prompt_loader import PromptLoader
from app.modules.shared.gigachat.client import GigaChatClient
from app.core.agent.utils.llm.prompt_loader import PromptLoader
from app.core.shared.gigachat.client import GigaChatClient
from app.infra.observability.module_trace import ModuleTrace
LOGGER = logging.getLogger(__name__)
src/app/core/agent/utils/traces/__init__.py
+1
View File
@@ -0,0 +1 @@
"""Shared trace helpers will live here."""
src/app/core/agent/utils/workflow/__init__.py
+9
View File
@@ -0,0 +1,9 @@
from app.core.agent.utils.workflow.context import WorkflowContext
from app.core.agent.utils.workflow.graph import WorkflowGraph
from app.core.agent.utils.workflow.step import WorkflowStep
__all__ = [
"WorkflowContext",
"WorkflowGraph",
"WorkflowStep",
]
src/app/core/agent/utils/workflow/context.py
+9
View File
@@ -0,0 +1,9 @@
from __future__ import annotations
from typing import Protocol
from app.core.agent.runtime.execution_context import RuntimeExecutionContext
class WorkflowContext(Protocol):
runtime: RuntimeExecutionContext
src/app/core/agent/utils/workflow/graph.py
+44
View File
@@ -0,0 +1,44 @@
from __future__ import annotations
from typing import Generic, Sequence, TypeVar
from app.core.agent.utils.workflow.context import WorkflowContext
from app.core.agent.utils.workflow.step import WorkflowStep
TContext = TypeVar("TContext", bound=WorkflowContext)
class WorkflowGraph(Generic[TContext]):
def __init__(self, workflow_id: str, source: str, steps: Sequence[WorkflowStep[TContext]]) -> None:
self._workflow_id = workflow_id
self._source = source
self._steps = tuple(steps)
async def run(self, context: TContext) -> TContext:
trace = context.runtime.trace.module(self._source)
trace.log("workflow_started", {"workflow_id": self._workflow_id})
for step in self._steps:
context = await self._run_step(context, step)
trace.log("workflow_completed", {"workflow_id": self._workflow_id})
return context
async def _run_step(self, context: TContext, step: WorkflowStep[TContext]) -> TContext:
request_id = context.runtime.request.request_id
trace = context.runtime.trace.module(self._source)
trace.log(
"step_started",
{"workflow_id": self._workflow_id, "step_id": step.step_id, "input": step.trace_input(context)},
)
await context.runtime.publisher.publish_status(
request_id,
self._source,
f"Шаг workflow: {step.title}.",
{"workflow_id": self._workflow_id, "step_id": step.step_id},
)
context = await step.run(context)
trace.log(
"step_completed",
{"workflow_id": self._workflow_id, "step_id": step.step_id, "output": step.trace_output(context)},
)
return context
src/app/core/agent/utils/workflow/step.py
+22
View File
@@ -0,0 +1,22 @@
from __future__ import annotations
from abc import ABC, abstractmethod
from typing import Any, Generic, TypeVar
TContext = TypeVar("TContext")
class WorkflowStep(ABC, Generic[TContext]):
step_id = ""
title = ""
@abstractmethod
async def run(self, context: TContext) -> TContext:
raise NotImplementedError
def trace_input(self, context: TContext) -> dict[str, Any]:
return {}
def trace_output(self, context: TContext) -> dict[str, Any]:
return {}
src/app/modules/api/__init__.py → src/app/core/api/__init__.py
View File
src/app/modules/api/application/request_service.py → src/app/core/api/application/request_service.py
+8 -8
View File
@@ -2,11 +2,11 @@ from __future__ import annotations
import asyncio
from app.modules.api.domain.models.agent_request import AgentRequest
from app.modules.api.infrastructure.ids.request_id_factory import RequestIdFactory
from app.modules.api.infrastructure.stores.in_memory_request_store import InMemoryRequestStore
from app.modules.api.application.session_service import SessionService
from app.modules.agent.orchestration.facade import OrchestrationFacade
from app.core.api.domain.models.agent_request import AgentRequest
from app.core.api.infrastructure.ids.request_id_factory import RequestIdFactory
from app.core.api.infrastructure.stores.in_memory_request_store import InMemoryRequestStore
from app.core.api.application.session_service import SessionService
from app.core.agent.runtime import AgentRuntime
class RequestService:
@@ -15,12 +15,12 @@ class RequestService:
request_store: InMemoryRequestStore,
request_ids: RequestIdFactory,
sessions: SessionService,
orchestration: OrchestrationFacade,
runtime: AgentRuntime,
) -> None:
self._request_store = request_store
self._request_ids = request_ids
self._sessions = sessions
self._orchestration = orchestration
self._runtime = runtime
async def create(self, session_id: str, message: str, process_version: str) -> AgentRequest:
session = self._sessions.get(session_id)
@@ -31,7 +31,7 @@ class RequestService:
process_version=process_version,
)
self._request_store.save(request)
asyncio.create_task(self._orchestration.run(request, session))
asyncio.create_task(self._runtime.run(request, session))
return request
def get(self, request_id: str) -> AgentRequest | None:
src/app/core/api/application/session_bootstrap_service.py
+25
View File
@@ -0,0 +1,25 @@
from __future__ import annotations
from dataclasses import dataclass
from app.core.api.application.session_service import SessionService
from app.core.api.domain.models.agent_session import AgentSession
from app.core.rag.indexing import IndexJob
from app.core.rag.module import RagModule
@dataclass(slots=True)
class BootstrappedAgentSession:
session: AgentSession
index_job: IndexJob
class SessionBootstrapService:
def __init__(self, sessions: SessionService, rag: RagModule) -> None:
self._sessions = sessions
self._rag = rag
async def create(self, project_id: str, files: list[dict]) -> BootstrappedAgentSession:
rag_session, index_job = await self._rag.create_session(project_id=project_id, files=files)
session = self._sessions.create(rag_session_id=rag_session.rag_session_id)
return BootstrappedAgentSession(session=session, index_job=index_job)
src/app/core/api/application/session_service.py
+26
View File
@@ -0,0 +1,26 @@
from __future__ import annotations
from app.infra.exceptions import AppError
from app.core.api.domain.models.agent_session import AgentSession
from app.core.api.infrastructure.ids.session_id_factory import SessionIdFactory
from app.core.api.infrastructure.stores.in_memory_session_store import InMemorySessionStore
from app.schemas.common import ModuleName
class SessionService:
def __init__(self, store: InMemorySessionStore, ids: SessionIdFactory) -> None:
self._store = store
self._ids = ids
def create(self, rag_session_id: str | None = None) -> AgentSession:
session = AgentSession.create(self._ids.create(), rag_session_id=rag_session_id)
return self._store.save(session)
def get(self, session_id: str) -> AgentSession:
session = self._store.get(session_id)
if session is None:
raise AppError("session_not_found", f"Agent session not found: {session_id}", ModuleName.BACKEND)
return session
def save(self, session: AgentSession) -> AgentSession:
return self._store.save(session)
src/app/modules/api/application/stream_service.py → src/app/core/api/application/stream_service.py
+3 -3
View File
@@ -1,8 +1,8 @@
from __future__ import annotations
from app.core.exceptions import AppError
from app.modules.api.infrastructure.streaming.sse_encoder import SseEncoder
from app.modules.api.infrastructure.streaming.sse_event_channel import SseEventChannel
from app.infra.exceptions import AppError
from app.core.api.infrastructure.streaming.sse_encoder import SseEncoder
from app.core.api.infrastructure.streaming.sse_event_channel import SseEventChannel
from app.schemas.common import ModuleName
src/app/core/api/controllers/rag_public_controller.py
+33
View File
@@ -0,0 +1,33 @@
from __future__ import annotations
from app.core.api.infrastructure.streaming.sse_response_builder import build_sse_response
from app.core.rag.module import RagModule
from app.core.shared.messaging import EventBus
from app.schemas.rag_sessions import RagSessionJobResponse
class RagPublicController:
def __init__(self, rag: RagModule) -> None:
self._rag = rag
def get_job(self, rag_session_id: str, index_job_id: str) -> RagSessionJobResponse:
job = self._rag.get_session_job(rag_session_id, index_job_id)
return RagSessionJobResponse(
rag_session_id=rag_session_id,
index_job_id=job.index_job_id,
status=job.status,
indexed_files=job.indexed_files,
failed_files=job.failed_files,
cache_hit_files=job.cache_hit_files,
cache_miss_files=job.cache_miss_files,
error=job.error.model_dump(mode="json") if job.error else None,
)
async def stream_job_events(self, rag_session_id: str, index_job_id: str):
channel_id, queue = await self._rag.subscribe_session_job_events(rag_session_id, index_job_id)
return build_sse_response(
queue,
encoder=EventBus.as_sse,
unsubscribe=lambda: self._rag.unsubscribe_job_events(channel_id, queue),
stop_on_event="terminal",
)

Some files were not shown because too many files have changed in this diff Show More