Skip to content

docs(config): document the recall-gate Runtime keys - #1689

Merged
Teingi merged 2 commits into
masterfrom
docs/recall-gate-config-keys
Sep 21, 2026
Merged

Teingi merged 2 commits into
masterfrom
docs/recall-gate-config-keys

Conversation

@AlexStocks

Copy link
Copy Markdown
Contributor

Which issue or RFC does this PR close?

Closes #1688.

Rationale for this change

RuntimeConfig.recall_gate_* drives the optional recall-sufficiency gate shipped in v1.1.0, but docs/{en,zh}/docs/operate/configuration.md listed none of those keys. The upgrade notes tell operators to enable the gate when needed, so the canonical reference left readers with no documented way to set or tune it: the keys were reachable only by reading the source.

What changes are included in this PR?

  • Add the nine POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_* keys to the Runtime table in both locales, with the defaults and bounds from src/powercontext/builtin/runtime/config.py.
  • Add a paragraph describing what the gate measures, what an expansion round reuses, the load-time ordering rule between the two similarity floors, and the added latency.
  • The environment variable names follow the existing POWERCONTEXT_SERVER_ prefix plus nested _ delimiter convention.

Two notes on the issue text:

  • The issue says "eight keys"; there are nine. recall_gate_allow_with_rerank is not a threshold and was easy to miss, but it does gate expansion, so it is documented here too.
  • I did not touch the powercontext config init template in src/powercontext/cli/config.py. That file emits a curated sample of settings rather than every Runtime key, and adding to it changes generated output, which belongs in a separate change rather than this documentation fix.

Are there any user-facing changes?

Documentation only. No behaviour, API, or persisted-format change.

How was this change tested?

  • Verified the derived variable works against a real settings object in the repository virtual environment:

    $ POWERCONTEXT_SERVER_RUNTIME_RECALL_GATE_ENABLED=true python -c "from powercontext.server.settings import ServerSettings; print(ServerSettings().runtime.recall_gate_enabled)"
    True
    $ python -c "from powercontext.server.settings import ServerSettings; print(ServerSettings().runtime.recall_gate_enabled)"
    False
    
  • Re-read every default and bound from src/powercontext/builtin/runtime/config.py and the ordering validator next to it.

  • Confirmed the assessment logic the new paragraph describes against RecallSufficiencyGate.assess and RecallSufficiencyPolicy.from_runtime_config.

  • Cross-checked the two locale tables row by row.

AI usage statement

Built with an AI assistant (WorkBuddy), which read the runtime configuration source, drafted both locale tables, and ran the environment-variable check above. Every documented default, bound, and route was verified against the source before writing.

`RuntimeConfig.recall_gate_*` drives the optional recall-sufficiency gate added in
v1.1.0, but the configuration reference listed none of the nine keys, so readers had
no documented way to enable or tune the gate.

Add the keys to the Runtime table in both locales with their defaults and bounds, and
describe the gate's behaviour, its latency cost, and the ordering rule that the
round-one and round-two similarity floors must keep.
Comment thread docs/en/docs/operate/configuration.md Outdated
@AlexStocks

Copy link
Copy Markdown
Contributor Author

@Teingi I have completed all works which related to your comment. Please review again.

@Teingi Teingi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Teingi
Teingi merged commit b7498f5 into master Sep 21, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: recall-gate Runtime config keys missing from the configuration reference

2 participants