фиксирую состояние
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user