diff --git a/docs/en/rfcs/1858-artifact-search.md b/docs/en/rfcs/1858-artifact-search.md new file mode 100644 index 000000000..884ada9ff --- /dev/null +++ b/docs/en/rfcs/1858-artifact-search.md @@ -0,0 +1,102 @@ +--- +title: Unified Artifact Search and Capability Contracts +--- + +- Proposal Name: `artifact_search` +- Start Date: 2026-10-07 +- RFC PR: [oceanbase/powercontext#1858](https://github.com/oceanbase/powercontext/pull/1858) + +# Summary + +Provide a common `search` endpoint for one Artifact Family within one Scope, returning an Artifact array ordered by +relevance and bounded by `limit`. The common layer defines calling conventions and baseline behavior. Each Family declares +its supported capabilities and owns the domain implementation. Existing specialized HTTP endpoints retain their request and +response contracts and default behavior; for integrated Families, they must call the new common search method internally. + +# Motivation + +`ListActiveEntries` lacks query relevance ordering, so budget truncation can discard the most relevant memories. Callers +need the top N relevant Artifacts for a query. Independent search implementations also increase integration cost; new Families +should join the common endpoint through registration. + +# Guide-level explanation + +Call `POST /v1/scopes/{scope_id}/artifacts/{family}/search`, for example with: + +```json +{ + "query": "Experience resolving database connection timeouts", + "limit": 5 +} +``` + +The response contains a relevance-ordered Artifact array in `results`, with at most five items. Each Family defines its item +content, and no matches produce an empty array. `query` must be nonempty; omitting the retrieval mode uses the Family default. + +Callers may also use modes, filters, relevance admission, fusion configuration, score thresholds, or reranking declared by +the Family. Unknown Families, unsupported search, and unsupported requested capabilities produce clear errors. Execution +failures are not returned as empty results. + +Each request searches one Family, with a final `limit` and no pagination. Multi-Family orchestration and context budget +allocation remain with `prepare`. + +# Reference-level explanation + +- **Capability dispatch:** Families register search capabilities, parameter constraints, and domain implementations. The + common entry point parses and dispatches through registration. Families own specialized parameters and default strategies; + the framework does not mandate `auto`, and adding a Family requires no new branch in the public entry point. +- **Capability scope:** Full-text, vector, hybrid retrieval, filters, admission, score thresholds, and reranking are + encouraged capabilities. Families choose support and publish available combinations. Unsupported explicit requests must + fail rather than silently ignoring parameters or switching strategies. +- **Scoring contract:** Retrieval scores must be finite values in `[0, 1]`, with higher values indicating higher scores. + When supported, `min_score` strictly filters normalized retrieval scores; reranking or filling the result count cannot + bypass it. Normalization does not imply absolute comparability across Families, algorithms, or queries. +- **Fusion responsibility:** Fusion algorithms are shared implementations independent of Artifact types. Families supply + retrieval channels, candidates, and weights. Algorithm-specific parameters belong to the selected algorithm's + configuration. Switching algorithms preserves declared relevance admission. +- **Compatibility and adoption:** Existing specialized HTTP endpoints remain available with their request and response + contracts and default behavior. For integrated Families, they must call the new common search method internally, sharing + the Family domain implementation with the new HTTP endpoint, SDK, and `prepare`. They perform only necessary parameter and + result adaptation, without independent retrieval logic. Initial coverage includes Topic Memory, + Experience, and Skill; existing Memory entry retrieval retains its current entry points. Prompt is excluded; Profile and + Handoff do not gain search solely for uniformity and return a clear error when search is unsupported. + +Family contracts follow [RFC #1549](1549_artifact_family_unification.md), database migrations follow +[RFC #1771](https://github.com/oceanbase/powercontext/pull/1771). [RFC #1803](https://github.com/oceanbase/powercontext/pull/1803) +is a related retrieval implementation proposal, not a prerequisite for the common interface. Atomic Memory integration +depends on and follows [RFC #1809](https://github.com/oceanbase/powercontext/pull/1809), joining after that proposal is adopted +and its Family is ready. This dependency does not block other Families. + +# Drawbacks + +- Family support and defaults still differ, requiring maintained capability documentation and awareness from callers. +- A common score range cannot eliminate algorithm differences; retrieval configuration changes can affect threshold + behavior. Adapting existing entry points also carries compatibility costs. + +# Rationale and alternatives + +- Adding relevance retrieval to `list` mixes browsing with query search. A separate `search` operation expresses top-N + relevant results more clearly. +- Continuing to add independently implemented specialized search endpoints repeats interface and retrieval work. The common + method keeps domain differences within Families while supporting the retained endpoints. +- Requiring every capability from every Family introduces unnecessary index or model dependencies for simple retrieval; + declared, optional support avoids this requirement. +- Searching all Families with mandatory model reranking adds cross-Family comparison and inference costs. Multi-Family + orchestration remains with `prepare`. + +# Prior art + +PowerContext already exposes specialized endpoints such as `/v1/memory/search` and `/v1/topic-memory/search`. This proposal +retains these endpoints and their request and response contracts and default behavior. For integrated Families, their +retrieval must use the new common search method internally. + +# Unresolved questions + +The initial Family capability combinations, defaults, and compatibility mappings for retained entry points need to be +specified in the design. Complete request and response schemas, parameter models, scoring formulas, and backend execution +plans belong in the subsequent design work. + +# Future possibilities + +Capability discovery and additional fusion algorithms can reduce the effort needed to understand available capabilities. +Cross-Family score calibration can be explored separately and is not a prerequisite for this proposal. diff --git a/docs/zh/rfcs/1858-artifact-search.md b/docs/zh/rfcs/1858-artifact-search.md new file mode 100644 index 000000000..792df1f8d --- /dev/null +++ b/docs/zh/rfcs/1858-artifact-search.md @@ -0,0 +1,85 @@ +--- +title: 统一制品检索与能力契约 +--- + +- Proposal Name: `artifact_search` +- Start Date: 2026-10-07 +- RFC PR: [oceanbase/powercontext#1858](https://github.com/oceanbase/powercontext/pull/1858) + +# Summary + +为同一 Scope 内的单个 Artifact Family 提供统一 `search` 接口，返回按相关性排序、受 `limit` 限制的 Artifact +数组。公共层约定调用方式和基础行为，各 Family 按需声明检索能力并负责业务实现。现有业务专用接口为兼容性 +继续保留，已接入 Family 的专用接口内部改为调用统一检索方法。 + +# Motivation + +`ListActiveEntries` 缺少针对查询的相关性排序，结果在预算不足时被截断，可能丢掉最相关的记忆。调用方需要按查询 +选取前 N 个相关制品。同时，各制品分散的检索入口增加了接入成本；新增 Family 应能通过注册接入统一接口。 + +# Guide-level explanation + +调用方使用 `POST /v1/scopes/{scope_id}/artifacts/{family}/search`，例如提交： + +```json +{ + "query": "数据库连接超时的处理经验", + "limit": 5 +} +``` + +响应的 `results` 是按相关性排序的 Artifact 数组，最多包含 5 项；每项内容由对应 Family 定义，没有匹配项时返回 +空数组。`query` 必须非空，省略检索模式时使用 Family 的默认行为。 + +调用方还可使用该 Family 声明支持的模式、过滤条件、相关性准入、融合配置、评分阈值或重排能力。未知 Family、 +不支持搜索或不支持所请求能力时，接口给出明确错误；运行失败不作为空结果返回。 + +每次请求检索一个 Family，只提供 `limit`，不提供分页。多制品编排和上下文预算分配继续使用 `prepare`。 + +# Reference-level explanation + +- **能力分派**：Family 注册检索能力、参数约束和业务实现。公共入口按注册信息解析、分派请求，Family 负责专用 + 参数及默认策略，框架不强制 `auto`，新增 Family 无需修改公共入口的分支逻辑。 +- **能力范围**：鼓励支持全文、向量、融合、过滤、准入、评分阈值和重排；Family 按需支持并公开可用组合。显式请求 + 不支持的能力必须报错，不能忽略参数或静默切换策略。 +- **评分契约**：检索评分必须为有限的 `[0, 1]` 数值，越大表示评分越高。支持 `min_score` 时严格按归一化检索分数 + 筛选，重排或补足数量不能绕过门槛。归一化不承诺跨 Family、算法或查询的绝对可比性。 +- **融合职责**：融合算法独立于制品，复用通用实现；Family 提供召回通道、候选和权重。算法专用参数随所选算法配置， + 已声明的相关性准入不因切换融合算法而改变。 +- **兼容与接入**：现有业务专用接口继续保留，保持既有请求、响应及默认行为。已接入 Family 的专用接口必须调用 + 统一检索方法，通过参数和结果适配保持兼容，与新 HTTP 入口、SDK、`prepare` 共用同一业务检索实现。 + 首批覆盖 Topic Memory、Experience 和 Skill；现有 Memory entry 检索保留原入口。Prompt 不纳入， + Profile、Handoff 不为统一接口补充搜索能力，未提供搜索时明确报错。 + +Family 契约遵循 [RFC #1549](1549_artifact_family_unification.md)，数据库迁移遵循 +[RFC #1771](https://github.com/oceanbase/powercontext/pull/1771)。 +[RFC #1803](https://github.com/oceanbase/powercontext/pull/1803) 是相关的检索实现提案，不作为统一接口的前置条件。 +Atomic Memory 接入依赖并遵循 [RFC #1809](https://github.com/oceanbase/powercontext/pull/1809)，在该提案采纳且 +对应 Family 就绪后接入，不阻塞其他 Family。 + +# Drawbacks + +- 各 Family 的支持范围和默认策略仍有差异，需要持续维护能力说明，调用方也需要了解这些差异。 +- 统一评分范围不能消除算法差异；调整检索配置可能影响阈值效果。既有入口的适配也需要处理兼容成本。 + +# Rationale and alternatives + +- 在 `list` 上加入相关性检索，会混合列表浏览与查询检索。独立 `search` 更明确地表达前 N 条相关结果。 +- 继续为各 Family 新增独立实现的专用接口，会重复接口适配和检索逻辑；统一入口与统一检索方法降低这种维护成本。 +- 要求所有 Family 实现全部能力，会给简单检索增加不必要的索引或模型依赖，因此采用能力声明与按需支持。 +- 一次搜索所有制品并强制统一模型重排，会增加跨制品比较和推理成本，多制品编排继续由 `prepare` 承担。 + +# Prior art + +PowerContext 已有 `/v1/memory/search`、`/v1/topic-memory/search` 等专用接口。这些接口为兼容性继续保留； +已接入 Family 的专用接口必须改用新的统一检索方法，适配既有请求和响应，不再维护独立的检索逻辑。 + +# Unresolved questions + +首批各 Family 开放的能力组合、默认策略和专用接口的适配映射，需在方案设计中逐项明确。完整请求与响应结构、参数模型、 +评分公式和后端执行方案留在后续方案设计中。 + +# Future possibilities + +后续可增加能力发现接口和更多融合算法，减少调用方了解能力范围的成本。跨制品评分校准可单独研究， +不作为本提案的前置条件。