feat(wiki): batch related orphan triage into one maintainer call - #20
Merged
Conversation
The maintainer triaged one orphan per LLM call; same-subject keywords sharing a source fact each repeated the same research. With WIKI_TRIAGE_CLUSTER on (default) it now claims a few related pending triage jobs together (non-hub keywords sharing a source fact + that fact's own job) and decides every seed in ONE agent call, one decision per seed. run_cron and the per-job lifecycle are unchanged: each job still closes with its own status; a singleton (or flag off) is a 1-seed unit, as before. Validated against the one-at-a-time path on the same snapshot: identical decision split and near-identical wikis, at ~1.6 orphans/call (~37% fewer LLM calls), with multi-seed batches deciding each seed independently (no conflation).
…600s) _ASK_TIMEOUT is now read from BRAINDB_ASK_TIMEOUT (default 600s, was a hardcoded 90s) so a slow /agent/query LLM loop doesn't time out and the ceiling is tunable per deployment.
…ClusterDecision submit_maintainer now carries MaintainerClusterDecision (a `decisions` list, one entry per seed) instead of the flat MaintainerDecision, so the tool-schema assertion is updated to expect `decisions` as the only required field. The base MaintainerDecision model is unchanged, so the model-direct tests stay.
A self-hosted vLLM profile for Gemma 4 12B (QAT w4a16) served at host.docker.internal:8012, mirroring the existing vllm_workstation_* profiles. Select it with LLM_PROFILE=vllm_workstation_gemma12b to run the agent on the local Gemma model.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The wiki maintainer triaged orphan entities one at a time — one agent run (recall + graph research) per orphan, so same-subject keywords that share a source fact each repeated the same neighbourhood research. This PR lets the maintainer claim a few related orphan triage jobs together — non-hub keywords that share a source fact, plus that fact's own job — and decide them in a single agent call, one decision per seed.
run_cronand the per-job lifecycle are unchanged: every job still closes with its own status (skip→rejected,attach→done+suggestion, …); a singleton — or the flag off — is a one-seed unit identical to today. Gated byWIKI_TRIAGE_CLUSTER(default on;WIKI_TRIAGE_CLUSTER_MAX/WIKI_TRIAGE_HUB_DEGREEtune it).Why: materially fewer maintainer LLM calls for the same work — same-subject keywords no longer each re-run the same research.
Validation — A/B vs the one-at-a-time path on the same snapshot
Also exercised on a smaller self-hosted model (Gemma 4 12B): the clustered maintainer produced the same kinds of decisions and wikis, so the batched / structured-output path holds up across model sizes.
Changes
braindb/services/wiki_jobs.py—WIKI_TRIAGE_CLUSTER/WIKI_TRIAGE_CLUSTER_MAX/WIKI_TRIAGE_HUB_DEGREE+claim_related_triagebraindb/routers/wiki.py— claim-sidewiki_maintain+ extracted_apply_decision(the existing per-seed resolution, verbatim)braindb/agent/schemas.py—MaintainerClusterItem+MaintainerClusterDecision(reuseMaintainerDecision)braindb/agent/prompts/wiki_maintainer_prompt.md— SEED → SEEDS list; one decision per seed; "co-occurrence is not identity"braindb/agent/tools.py— bind the maintainerfinal_answerto the cluster schematests/test_final_answer_rename.py— track the schema rebindbraindb/config.py— add thevllm_workstation_gemma12bLLM profileintegrations/hermes/braindb/__init__.py— env-configurable Hermes ask-timeout (BRAINDB_ASK_TIMEOUT, default 600s)Tests
Pure-unit suite green (final_answer/schema, handoff hooks, config profiles, chunking).