Skip to content

docs(rfc): add recall sufficiency gate proposal - #1560

Open
AlexStocks wants to merge 3 commits into
oceanbase:masterfrom
AlexStocks:rfc/recall-sufficiency-gate
Open

docs(rfc): add recall sufficiency gate proposal#1560
AlexStocks wants to merge 3 commits into
oceanbase:masterfrom
AlexStocks:rfc/recall-sufficiency-gate

Conversation

@AlexStocks

Copy link
Copy Markdown
Contributor

Closes #1556

Rationale for this change

prepare_context is single-pass by construction: one search per participating family, then fit to max_bytes, then
render. When that one search under-retrieves, the operation still returns normally — it just delivers fewer items, or a
normal empty result. RFC 1489 gave callers control over which families participate, their order, and a per-family item
limit, but did not address what the Runtime should do when the participating families together return too little to be
useful.

This PR adds the RFC proposing an internal recall sufficiency gate with bounded expansion. It is a documentation-only
change; no runtime behaviour changes here.

What changes are included in this PR?

  • docs/en/rfcs/0000-recall-sufficiency-gate.md — new RFC.
  • docs/zh/rfcs/0000-recall-sufficiency-gate.md — the Chinese counterpart.

The proposal is deliberately narrow:

  • a model-free gate that assesses whether the candidate set is sufficient for the query;
  • at most two expansion rounds, each strictly more expensive than the last (raise the per-family search limit
    toward the existing Builder ceilings; switch SearchMemoryRequest.mode from the hard-coded auto to hybrid);
  • expansion may only change which candidates compete — never the caller's max_bytes, never the trust wrapper, never
    the citation form;
  • expansion never adds a family, because RFC 1489 makes family participation a caller decision and states that an
    unselected family is neither searched nor given output budget;
  • the effort is reported in a new in-process RecallEffort trace, following the RFC 0080 rerank trace precedent, and
    stays out of the HTTP v1 response;
  • every error path degrades to today's behaviour.

Two small observability counters (truncated_items, dropped_items) are proposed because neither is counted anywhere
today (prepared_context.py:462-463, prepared_text.py:103-104), and without them an expansion that changed nothing
cannot be interpreted honestly.

The RFC also records what it cannot do: there is no time-window or as-of parameter on either PrepareContextRequest or
SearchMemoryRequest, so "relax the time window" — the most common host-side expansion action — is not available in v1
and would need its own contract change.

Are there any user-facing changes?

None. This PR adds a design document only. The proposed feature is off by default, keeps
PreparedContext(schema, status, content, content_bytes) unchanged, and requires no OpenAPI change
(make api-generate is not needed).

How was this change tested?

Documentation only. Every code reference in the RFC was verified against master while writing it:

  • PreparedContextBuilder candidate ceilings: src/powercontext/builtin/runtime/prepared_context.py:103-110; the
    invariant raises at :165-169.
  • Prepare entry point and the hard-coded search mode: src/powercontext/builtin/runtime/application.py:727
    (_prepare), :814 (_recall_scope), :849 (mode="auto").
  • Budget-driven drop and truncation: prepared_context.py:461-463 and
    src/powercontext/builtin/runtime/prepared_text.py:103-104.
  • PreparedContextStatus values: src/powercontext/builtin/runtime/models.py:58.
  • Existing test homes referenced by the RFC exist: tests/builtin/runtime/test_prepared_context.py,
    tests/e2e/test_builtin_runtime.py, tests/e2e/test_context_text_assembly.py.

No build or test command was run for this PR, since it changes no code.

AI usage statement

AI assistance (WorkBuddy, agent mode) was used to draft both RFC documents and to cross-check the code references
above. Design decisions, scope boundaries, and all file/line citations were reviewed and verified against master by
the author.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(context): add a recall sufficiency gate with bounded expansion to prepare_context

1 participant