smart_rag 0.1.0 → 0.2.1

data/docs/retrieval_plan.md

@@ -0,0 +1,251 @@
+## 1. 目的
+
+RetrievalPlan 用于把“本轮需要检索什么、怎么检索、取多少、如何控制噪声”表达为结构化对象，避免：
+- 调用方隐式依赖 SmartRAG 内部策略（不可控）
+- 多模式检索无法复现与调试（不可观测）
+- 上下文装配缺少预算与多样性约束（易被噪声淹没）
+
+---
+
+## 2. 顶层结构
+
+RetrievalPlan 是一个 JSON/Ruby Hash 对象（可序列化入日志）。
+
+```json
+{
+  "version": "0.1",
+  "request_id": "uuid",
+  "purpose": "qa|continue_task|debug|summarize|research|other",
+  "queries": [],
+  "global_filters": {},
+  "budget": {},
+  "ranking": {},
+  "output": {},
+  "debug": {}
+}
+```
+
+字段说明：
+
+* `version`：协议版本（必填）
+* `request_id`：调用方生成，用于贯穿日志与可追溯（建议必填）
+* `purpose`：检索目的，用于策略默认值（可选）
+* `queries`：检索 query 列表（必填，至少 1 条）
+* `global_filters`：对所有 queries 生效的过滤（可选）
+* `budget`：数量预算与多样性约束（可选但强烈建议）
+* `ranking`：融合与重排设置（可选）
+* `output`：返回内容控制（可选）
+* `debug`：调试信息（可选）
+
+---
+
+## 3. queries（必填）
+
+### 3.1 Query 对象
+
+```json
+{
+  "text": "string",
+  "mode": "exact|semantic|hybrid|relational|associative",
+  "weight": 1.0,
+  "filters": { },
+  "hints": { }
+}
+```
+
+字段说明：
+
+* `text`：查询文本（必填）
+* `mode`：
+
+  * `exact`：关键词/短语精确查找（FTS/BM25）
+  * `semantic`：语义召回（embedding）
+  * `hybrid`：exact + semantic（由执行方融合）
+  * `relational`：关联检索（实体/链接/任务链）
+  * `associative`：联想检索（通常表示“扩展 query”，执行方应按策略调用 exact/semantic 再融合）
+* `weight`：该 query 的相对权重（默认 1.0）
+* `filters`：只对该 query 生效的过滤（覆盖/补充 global_filters）
+* `hints`：提示执行策略的附加信息（可选）
+
+> 建议：SmartBrain 的“联想”实现为生成多个 `associative` 或多条 `semantic/exact` 扩展 queries，而不是让执行方自由发挥。
+
+### 3.2 queries 最小示例
+
+```json
+{
+  "version": "0.1",
+  "request_id": "c2b2f7d6-7c3b-4d53-8f8b-6f1f3a8c2a10",
+  "purpose": "qa",
+  "queries": [
+    { "text": "OpenViking retrieval design", "mode": "hybrid", "weight": 1.0 }
+  ]
+}
+```
+
+### 3.3 queries（扩展/联想）示例
+
+```json
+{
+  "version": "0.1",
+  "request_id": "b7b1b1ce-2330-4f72-9f7b-92a6a1a2e12a",
+  "purpose": "research",
+  "queries": [
+    { "text": "RAG memory runtime design", "mode": "hybrid", "weight": 1.0 },
+    { "text": "MemGPT hierarchical memory", "mode": "semantic", "weight": 0.7 },
+    { "text": "Letta archival memory blocks", "mode": "semantic", "weight": 0.7 },
+    { "text": "context composer token budget diversity", "mode": "exact", "weight": 0.5 }
+  ]
+}
+```
+
+---
+
+## 4. global_filters（可选）
+
+对所有 queries 生效。执行方必须支持“只过滤不改变语义”的行为。
+
+```json
+{
+  "document_ids": ["..."],
+  "tag_ids": ["..."],
+  "topic_ids": ["..."],
+  "source_type": ["url","file","manual","memory_snapshot"],
+  "source_uri_prefix": ["https://...", "file://..."],
+  "language": ["zh","en"],
+  "time_range": { "from": "2026-01-01T00:00:00Z", "to": "2026-02-20T00:00:00Z" }
+}
+```
+
+说明：
+
+* `document_ids/tag_ids/topic_ids`：知识库内过滤
+* `source_type`：资源类型过滤（建议 SmartRAG 支持）
+* `source_uri_prefix`：按 URI 前缀过滤（适合域名/路径范围）
+* `language`：语言过滤（可选）
+* `time_range`：时间过滤（可按 documents.created_at 或 sections.created_at 实现）
+
+---
+
+## 5. budget（可选但强烈建议）
+
+```json
+{
+  "top_k": 30,
+  "per_mode_k": { "exact": 10, "semantic": 10, "hybrid": 10, "relational": 10, "associative": 10 },
+  "candidate_k": 200,
+  "diversity": {
+    "by_document": 3,
+    "by_source": 10,
+    "by_section": 1
+  }
+}
+```
+
+说明：
+
+* `top_k`：最终返回条数
+* `per_mode_k`：各模式配额（执行方可按存在的模式取 min）
+* `candidate_k`：召回候选池规模（用于 rerank）
+* `diversity`：多样性约束（避免单文档/单来源垄断）
+
+> 实施建议：如果执行方不支持某一 diversity 维度，应忽略并在 explain 中声明。
+
+---
+
+## 6. ranking（可选）
+
+用于约束融合与重排。
+
+```json
+{
+  "fusion": { "method": "rrf|weighted_sum|none", "rrf_k": 60, "weights": { "exact": 1.0, "semantic": 1.0 } },
+  "rerank": { "enabled": true, "model": "qwen3-reranker", "top_n": 50 },
+  "tie_breaker": "recency|source_priority|none",
+  "source_priority": { "url": 0.9, "file": 1.0, "manual": 0.8, "memory_snapshot": 0.7 }
+}
+```
+
+说明：
+
+* `fusion.method`：默认建议 `rrf`
+* `rerank.enabled`：是否启用 reranker
+* `tie_breaker`：分数相近时的决策
+* `source_priority`：来源优先级（可选）
+
+---
+
+## 7. output（可选）
+
+控制返回内容形态，便于 token 控制与调试。
+
+```json
+{
+  "include_snippets": true,
+  "snippet_policy": "l2|l1|l0|auto",
+  "include_signals": true,
+  "include_provenance": true,
+  "include_raw": false,
+  "max_snippet_chars": 800
+}
+```
+
+说明：
+
+* `snippet_policy`：建议未来支持 L0/L1/L2（如 OpenViking 分层）
+* `max_snippet_chars`：用于截断（执行方应保证不超）
+
+---
+
+## 8. debug（可选）
+
+```json
+{
+  "trace": true,
+  "notes": "free text",
+  "caller": { "app": "smart_bot", "session_id": "..." }
+}
+```
+
+---
+
+## 9. 执行方最低合规要求（SmartRAG/SmartBrain）
+
+执行方至少要做到：
+
+1. 支持 `queries.text + mode` 的基本执行（exact/semantic/hybrid 至少两种）
+2. 支持 `top_k` 与基本 filters（document_ids/tag_ids/topic_ids）
+3. 返回结果时能提供最少的 explain（见下）
+
+建议执行方在返回 EvidencePack 时包含：
+
+* `plan_id/request_id`
+* `stats`（候选数、耗时、返回数）
+* `explain`（融合方式、是否 rerank、忽略了哪些字段）
+
+---
+
+## 10. 变更策略
+
+* v0.1：新增字段只能“可选”，不得破坏现有字段含义
+* v0.x：执行方必须忽略未知字段并在 explain 中声明（可选）
+* v1.0：如需破坏性变更，另起 major 版本并提供迁移说明
+
+---
+
+## 11. 当前实现状态（SmartRAG）
+
+已支持：
+
+* `queries.text + mode`：`exact/semantic/hybrid`
+* `global_filters.document_ids/tag_ids/topic_ids/time_range/source_type/source_uri_prefix`
+* `budget.top_k/candidate_k/per_mode_k`
+* `budget.diversity.by_document/by_source`
+* `output.include_snippets/include_signals/include_provenance/include_raw/max_snippet_chars`
+
+部分支持：
+
+* `queries.mode=relational/associative`：当前降级为 `hybrid`
+
+未支持（会进入 `explain.ignored_fields`）：
+
+* `budget.diversity.by_section`

data/docs/smartrag_improvement_plan.md

@@ -0,0 +1,201 @@
+# SmartRAG 改进计划（1-2 天冲刺版）
+
+## 1. 目标与范围
+
+本计划目标是在 **1-2 天内**完成 SmartRAG 与 SmartBrain 的契约化集成最小闭环，并同步补齐关键可观测与索引治理能力。
+
+本次改进聚焦：
+
+- 新增统一入口：`retrieve(plan)`（`RetrievalPlan -> EvidencePack`）
+- 统一输出：`EvidencePack v0.1`（含 signals/stats/explain）
+- 兼容现有 `search(...)`（不破坏旧调用）
+- 补齐核心可观测：`search_logs` 记录 `plan_json + stats + explain`
+- 落地最小索引治理：幂等导入与重建入口
+
+不在本次范围：
+
+- 对话事件管理、记忆抽取、上下文编排、Agent loop（归属 SmartBrain/SmartBot/SmartAgent）
+- 大规模 schema 重构
+- L0/L1/L2 全量能力落地（仅预留字段与策略）
+
+---
+
+## 2. 交付物
+
+- `smart_rag/docs/retrieval_plan.md`（对齐实现，必要时补充“已支持/未支持”）
+- `smart_rag/docs/evidence_pack.md`（对齐实现，必要时补充“最低合规字段”）
+- `smart_rag/docs/smartrag_improvement_plan.md`（本文档）
+- `lib/smart_rag/retrieve.rb`（或等价入口模块）
+- `spec/retrieve_spec.rb`（关键路径测试）
+- `CHANGELOG.md`（新增接口、兼容策略、已知限制）
+
+---
+
+## 3. 执行节奏（非按周，按里程碑）
+
+### M1：契约主链路打通（Day 1，上半天）
+
+目标：让 SmartBrain 可稳定调用 `retrieve(plan)` 并拿到结构化结果。
+
+任务：
+
+1. 新增 `retrieve(plan)` 入口，接收 `RetrievalPlan v0.1`。
+2. 支持最小 `queries` 执行：`exact/semantic/hybrid`（至少两种模式可用）。
+3. 结果统一封装为 `EvidencePack v0.1` 顶层结构：
+   - `version`
+   - `plan_id`
+   - `request_id`
+   - `generated_at`
+   - `evidences`
+   - `stats`
+   - `explain`
+   - `warnings`（可选）
+4. 保留 `search(...)`，内部逐步复用新执行路径。
+
+验收标准：
+
+- 可用 `RetrievalPlan` 直接调用 `retrieve(plan)`。
+- 响应结构符合 `EvidencePack` 最低要求。
+- 不影响现有 `search(...)` 调用。
+
+---
+
+### M2：可解释与可观测补齐（Day 1，下半天）
+
+目标：结果可复现、可解释、可调试。
+
+任务：
+
+1. 为每条 evidence 增加 `signals` 最小集合：
+   - `vector_score/vector_rank`
+   - `fts_score/fts_rank`
+   - `rrf_score`
+   - `rerank_score`（模型未启用时可空或置默认）
+2. 输出 `provenance`：
+   - `mode`
+   - `query_text`
+   - `query_index`
+   - `retrieved_at`
+3. 完成 `stats` 与 `explain`：
+   - `candidates/returned/took_ms`
+   - `fusion`、`rerank`、`filters_applied`
+   - `ignored_fields`（未支持字段必须明示）
+4. 将 `plan_json + stats/explain` 写入 `search_logs`。
+
+验收标准：
+
+- 任一结果都可追溯“来自哪个 query、以何模式命中、融合信号是什么”。
+- 日志可用于离线复盘同一次检索过程。
+
+---
+
+### M3：过滤、预算、多样性与稳定性（Day 2，上半天）
+
+目标：把噪声控制能力落到执行层，不依赖调用方隐式技巧。
+
+任务：
+
+1. 支持 `global_filters` 最小集：
+   - `document_ids`
+   - `tag_ids`
+   - `topic_ids`
+   - `source_type`
+   - `time_range`（若暂不支持，显式写入 `ignored_fields`）
+2. 支持 `budget` 最小集：
+   - `top_k`
+   - `candidate_k`
+   - `per_mode_k`（按已启用模式截断）
+3. 支持最小多样性约束：
+   - `diversity.by_document`
+4. `output` 最小支持：
+   - `include_snippets`
+   - `include_signals`
+   - `max_snippet_chars`
+
+验收标准：
+
+- 同一 query 在设置预算与多样性后，结果集中度明显降低（避免单文档垄断）。
+- 不支持字段会被显式告知，不出现“静默忽略”。
+
+---
+
+### M4：索引治理与收口发布（Day 2，下半天）
+
+目标：避免长期运行后的索引漂移和重复污染，并完成发布闭环。
+
+任务：
+
+1. 幂等导入最小策略：
+   - 引入/启用 `content_hash`
+   - 同源同内容避免重复写入（`source_uri + content_hash`）
+2. 提供重建入口：
+   - `rebuild_fts(document_id=nil)`
+   - `rebuild_embeddings(document_id=nil)`
+   - `reindex(document_id=nil)`
+3. 文档与变更收口：
+   - 更新 `CHANGELOG.md`
+   - 在文档中标注已实现与待实现项（如 `tag_score/topic_score` 参与排序）
+
+验收标准：
+
+- 重复导入不会持续膨胀索引。
+- 可对单文档或全量执行重建。
+- 变更说明清晰，可被 SmartBrain 团队直接消费。
+
+当前进展补充（已落地）：
+
+- 已新增 `source_documents.source_type/source_uri/content_hash` 与索引
+- 已提供 `rake db:backfill_source_fields` 回填任务
+- 已提供轻量单测入口（不依赖测试库连接）用于 `retrieve/reindex` 核心行为验证
+
+---
+
+## 4. 最小实现清单（MVP Done Definition）
+
+满足以下条件即判定本轮完成：
+
+1. `retrieve(plan)` 可用，`search(...)` 保持兼容。
+2. `EvidencePack` 输出包含最低必需字段与 signals。
+3. `exact/semantic/hybrid` 至少两种模式稳定可用（推荐三种都可用）。
+4. `search_logs` 可记录 `request_id + plan_json + stats + explain`。
+5. 至少一组集成测试覆盖：
+   - 单 query hybrid
+   - 多 query 融合
+   - filters + budget + diversity
+   - unknown/unsupported 字段处理（`ignored_fields`）
+
+---
+
+## 5. 风险与缓解
+
+风险 1：`time_range/language/source_uri_prefix` 等字段短期无法完全支持  
+缓解：严格走 `ignored_fields` 与 `warnings`，不做静默降级。
+
+风险 2：reranker 模型不可用导致结果波动  
+缓解：`rerank.enabled=false` 自动降级，`explain` 明确记录。
+
+风险 3：多 query 融合后结果重复或单源聚集  
+缓解：先做稳定去重（按 `document_id/section_id`）+ `diversity.by_document`。
+
+风险 4：1-2 天冲刺导致文档与实现偏差  
+缓解：以测试快照校验 `RetrievalPlan` 输入与 `EvidencePack` 输出结构。
+
+---
+
+## 6. 执行顺序（建议）
+
+1. 先打通 `retrieve(plan)` 与 `EvidencePack` 骨架（M1）。
+2. 再补 signals/explain/logging（M2）。
+3. 接着补 filters/budget/diversity（M3）。
+4. 最后完成索引治理与文档收口（M4）。
+
+这个顺序能确保即使 Day 2 出现意外，Day 1 结束时仍有可集成、可调试的主链路成果。
+
+---
+
+## 7. 后续增量（不阻塞本轮）
+
+- `tag_score/topic_score` 从“占位字段”升级为真实排序特征
+- `source_priority/tie_breaker` 精细策略
+- L0/L1/L2 分层 snippet 策略（`snippet_policy` 全实现）
+- 更完善的离线评测集与回归基线（NDCG/Recall/Latency）

data/docs/smartrag_refactor.md

@@ -0,0 +1,216 @@
+## 1. 目标与边界
+
+### 1.1 目标
+SmartRAG 的职责应当被明确为：
+
+- **资源导入与索引**：文档/URL 导入、分块、embedding、FTS（Postgres tsvector/pg_jieba）、元数据管理
+- **多模式检索**：exact / semantic / hybrid（向量 + FTS + 融合）
+- **统一证据输出**：输出结构化 `EvidencePack` 供 SmartBrain 做上下文装配
+- **可观测**：记录检索计划、融合信号、结果解释，便于调试与评估
+- **可重建**：索引可重建（embedding/FTS），内容是真相
+
+### 1.2 边界（SmartRAG 不做什么）
+SmartRAG **不负责**：
+
+- 对话事件（turn/tool call）存储与管理
+- 记忆抽取（profile/preferences/entities/events/tasks/decisions）
+- 上下文编排（token 预算、摘要、历史选择）
+- Agent loop / 工具编排 / MCP
+
+上述能力属于 SmartBrain / SmartBot / SmartAgent。
+
+---
+
+## 2. 现状与集成痛点
+
+> 你现有 SmartRAG 已具备：pgvector + FTS + RRF 融合、标签/主题、日志等。但为了与 SmartBrain 形成「契约式」集成，需要补齐：
+
+1. **检索入口表达能力不足**  
+   目前 `search_type: vector/fulltext/hybrid` 能选模式，但 SmartBrain 需要表达：多 query、每路预算、过滤、去重/多样性、是否 rerank、返回信号等。
+
+2. **输出缺乏“检索信号（signals）”**  
+   SmartBrain 要做跨源融合（memory + resources）、上下文预算装配、结果解释，需要看到每条 evidence 的来源与分数构成（vector/fts/rrf/rerank/tag/topic）。
+
+3. **索引维护与幂等导入不足**  
+   SmartBrain 会不断把“记忆快照/摘要/会议纪要/网页快照”写入资源库；缺少幂等与重建会导致噪声膨胀与索引漂移。
+
+---
+
+## 3. 改造范围（MVP -> 完整版）
+
+### 3.1 MVP（建议优先完成：1~2 个迭代）
+
+#### A) 新增结构化检索入口：`retrieve(plan)`
+新增统一入口（内部可复用现有 search/hybrid 逻辑）：
+
+```ruby
+SmartRAG.retrieve(plan: RetrievalPlan) => EvidencePack
+````
+
+**RetrievalPlan（Ruby Hash / JSON）**
+
+```json
+{
+  "queries": [
+    {
+      "text": "…",
+      "mode": "exact|semantic|hybrid",
+      "weight": 1.0,
+      "filters": { "tag_ids": [], "topic_ids": [] }
+    }
+  ],
+  "global_filters": {
+    "tag_ids": [],
+    "topic_ids": [],
+    "document_ids": [],
+    "source_type": ["url", "file", "manual", "memory_snapshot"],
+    "time_range": { "from": "2026-01-01T00:00:00Z", "to": "2026-02-19T00:00:00Z" }
+  },
+  "budget": {
+    "top_k": 30,
+    "per_mode_k": { "exact": 10, "semantic": 10, "hybrid": 10 },
+    "diversity": { "by_document": 3, "by_source": 10 }
+  },
+  "rerank": { "enabled": true, "model": "qwen3-reranker", "top_n": 30 },
+  "return": { "include_signals": true, "include_snippets": true }
+}
+```
+
+> 说明：`queries` 用于表达 **联想/扩展 query**（由 SmartBrain 生成），SmartRAG 不需要知道“为什么扩展”，只执行计划。
+
+#### B) 统一输出结构：`EvidencePack`
+
+SmartRAG 的输出应当满足：可复用、可观测、可再融合。
+
+**EvidencePack（JSON 形态）**
+
+```json
+{
+  "plan_id": "uuid",
+  "evidences": [
+    {
+      "document_id": "…",
+      "section_id": "…",
+      "snippet": "…",
+      "metadata": { "title": "…", "source_uri": "…" },
+      "signals": {
+        "vector_score": 0.12,
+        "vector_rank": 3,
+        "fts_score": 0.41,
+        "fts_rank": 1,
+        "rrf_score": 0.032,
+        "rerank_score": 0.88,
+        "tag_score": 0.2,
+        "topic_score": 0.0
+      },
+      "provenance": { "mode": "hybrid", "query_text": "…", "retrieved_at": "…" },
+      "raw": { "content_ref": "section:l2" }
+    }
+  ],
+  "stats": { "candidates": 200, "returned": 30, "took_ms": 128 },
+  "explain": { "fusion": "RRF", "rerank": true }
+}
+```
+
+#### C) 结果信号可观测（signals）
+
+MVP 至少提供：
+
+* `vector_rank/vector_score`
+* `fts_rank/fts_score`
+* `rrf_score`
+* `rerank_score`（可选）
+* `tag_score/topic_score`（先保留字段，MVP 可为 0）
+
+#### D) 兼容现有 API
+
+* 现有 `search(...)` 保留为简化接口；
+* 新增 `retrieve(plan)` 面向 SmartBrain；
+* `search` 内部可调用 `retrieve`（或相反），逐步统一实现。
+
+---
+
+### 3.2 完整版（SmartBrain 上线后逐步演进）
+
+#### E) 标签/主题第三路融合（不是仅过滤）
+
+让 tags/topics 参与排序信号：
+
+* `tag_score/topic_score` 进入融合加权或 rerank features（如果 reranker 支持 feature 拼接则更好）
+
+#### F) 索引维护能力
+
+新增维护命令/接口：
+
+* `rebuild_fts(document_id=nil)`
+* `rebuild_embeddings(document_id=nil)`
+* `reindex(document_id=nil)`（组合）
+* `dedupe_by_content_hash`（幂等导入）
+
+#### G) L0/L1/L2 层（与 OpenViking 思路兼容，可选）
+
+* L2：原始 section 内容
+* L1：overview（中等摘要+导航）
+* L0：abstract（极短摘要，召回友好）
+
+SmartRAG 可先只存 L2，后续逐步补齐 L0/L1（可由 SmartBrain 或 SmartRAG 生成）。
+
+---
+
+## 4. 数据结构调整建议（最小破坏）
+
+> 在不大改既有 schema 的前提下，建议增补：
+
+### 4.1 documents
+
+* `source_type`：url/file/manual/memory_snapshot
+* `source_uri`：统一 URI（用于 provenance 与去重）
+* `content_hash`：幂等导入（URL 内容 hash / 文件 hash）
+* `updated_at`：用于判断增量重建
+
+### 4.2 sections
+
+* `layer`：L0/L1/L2（可选）
+* `summary`：用于 snippet 输出（可选）
+* `metadata(jsonb)`：标题、页码、语言、代码语言、chunker 参数等
+
+### 4.3 search_logs
+
+* `plan_json`：保存 RetrievalPlan
+* `signals_json`：保存统计与融合信号摘要（便于回归对比）
+
+---
+
+## 5. 与 SmartBrain 的契约（强约束）
+
+* SmartBrain **只**通过 `retrieve(plan)` 调用 SmartRAG（避免隐式策略）
+* SmartRAG **只**返回 `EvidencePack`（不返回最终 prompt）
+* SmartBrain 负责：跨源融合（memory vs resource）、最终 rerank（可选）、上下文装配（token 预算）
+
+---
+
+## 6. 交付物清单（SmartRAG）
+
+* `docs/retrieval_plan.md`：RetrievalPlan schema 与示例
+* `docs/evidence_pack.md`：EvidencePack schema 与字段说明
+* `lib/smart_rag/retrieve.rb`：新入口（或模块）
+* `spec/retrieve_spec.rb`：关键路径测试
+* `CHANGELOG.md`：新增接口与兼容策略说明
+
+---
+
+## 7. 里程碑与验收标准
+
+### MVP 验收
+
+* 能以 RetrievalPlan 调用 `retrieve(plan)`
+* 返回 EvidencePack（含 signals）
+* Hybrid/Exact/Semantic 三模式可用（至少 two modes）
+* search_logs 记录 plan + stats + explain
+
+### 完整版验收
+
+* 幂等导入生效（相同 hash 不重复污染库）
+* 索引重建命令可用
+* tags/topics 对排序有显式贡献
+* L0/L1/L2 支持（可选）