feat(knowledge): global budget, rate limit, source cap, and configurable extraction model

[iamwhatever]

Problem

Per-source chunk budgets (auto_ingest_chunk_budget=150, folder_ingest_chunk_budget=300)
bound cost per folder per sweep. When many directories are registered — via
auto_register_project_docs on a multi-project workspace, or a user adding many
folders — the total extraction work per sweep = N × per-source budget:

• 10 project-doc sources → 1,500 chunks/sweep
• 20 hand-added folders → 6,000 chunks/sweep

Each chunk costs one LLM extraction call on the worker pool. This burst saturates the
LLM pool (default 3 workers), generates a massive embedding backlog, starves
chat-session inference, and can stall/respawn-loop the gateway (#2175, #2336, #2448).

Additionally, the extraction model was hardcoded to claude-haiku-4.5 with no user
override — users couldn't choose their own model for knowledge extraction.

Why it matters

A user who adds a few project folders or opens a multi-project workspace silently
triggers thousands of billed extraction calls per 5-minute sweep with no global cap.
The existing per-source budgets are necessary but insufficient — they're additive
across sources with no ceiling.

Fix (symptoms → root cause → change)

Symptom: gateway stalls under heavy knowledge ingestion load.
Root cause: no global cap on total extraction work per sweep; extraction model not
configurable; no embedding rate limit; no source count cap.
Change: five new KnowledgeConfig fields that bound the overall cost envelope:

Field	Default	Range	Effect
sweep_chunk_budget	500	0–50000	Hard cap on total chunks across all folder sources per sweep. 0 = unbounded.
max_sources	50	0–1000	Cap on registered source count. Auto-discovery stops at limit. 0 = unbounded.
embed_rate_limit	120/min	0–10000	Token-bucket throttle on embedding generation. 0 = unlimited.
extraction_model	"" (= agent.model)	any model id	Extraction LLM. Empty inherits user's default chat model.
extraction_pool_size	3	1–10	Concurrent extraction workers. Requires restart.

Cost consequence of the model default change: extraction previously used hardcoded
claude-haiku-4.5. Now it inherits agent.model — a user chatting on an Opus-class
model will pay chat-model rates per extraction chunk unless they explicitly set
extraction_model: claude-haiku-4.5. The sweep_chunk_budget (500, down from
unbounded) bounds total cost regardless of model choice.

All numeric fields: 0 = unbounded (preserves old behavior for power users).
sweep_chunk_budget, max_sources, and embed_rate_limit are live-reloaded (take
effect on the next watcher sweep, no restart). extraction_model and
extraction_pool_size require a gateway restart.

Tests

• test/test_knowledge_budget.py — 24 new tests:

  • TestKnowledgeConfigBudgetDefaults (7): all fields have correct defaults, zero-is-unbounded
  • TestEmbedRateLimiter (4): zero-rate noop, high-rate no-block, setter reset, config integration
  • TestMaxSourcesCap (4): under-cap allows, at-cap blocks, zero unbounded, existing URI ignores cap
  • TestSweepChunkBudget (2): reads from config, zero means unbounded
  • TestPoolSizeConfig (4): default, configured, clamped max, clamped min
  • TestExtractionModelResolution (2): empty uses agent.model, explicit overrides

• Pre-existing tests fixed to work with new behavior:

  • test_knowledge_folder_cost_guards.py: mock sets sweep_chunk_budget=0 (unbounded)
  • test_knowledge_project_docs.py: max_sources handled via safe int() conversion
  • test_llm_pool.py: pool size only overridden when config explicitly sets the key

Manual verification

N/A — backend infrastructure, no UI surface in this PR. All five config knobs are
accessible via kirocrew config set knowledge.<key> <value> and the Settings PATCH
API (/api/config with knowledge.sweep_chunk_budget, etc.).

Screenshots

N/A — no user-visible UI change in this PR. Frontend Settings UI card is a follow-up
PR (requires i18n key additions across 12 locales + screenshot capture).

Follow-up (not included)

• Frontend Settings card — ChatPanel.tsx additions with i18n for the 5 new fields
• extraction_model live-reload (rebuild agent config + recycle workers on PATCH)
• max_sources enforcement on the manual POST /api/knowledge/sources endpoint
• Round-robin fairness across sources when global budget is scarce

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed a2c47382257981a61a4728089470388ac9ffe55f — this comment is updated in place on each push.

Review details

No blocking findings.

FINDING — src/kiro_crew/knowledge/llm_pool.py:511-516 — the pool-size override applies to every LLMPool, so setting knowledge.extraction_pool_size (e.g. 10) also resizes auto_research's deliberately-isolated LLMPool(pool_size=1) up to 10, contradicting the code comment's claim that "callers that pass a specific pool_size to the constructor are not overridden" → Fix: gate the override on self._pool_size == DEFAULT_POOL_SIZE so only the default-constructed Knowledge pool is resized.

[OPUS-REVIEWED] a2c4738

Verdict parsed from the review's SHA-scoped output markers for commit a2c47382257981a61a4728089470388ac9ffe55f.

False positive or not applicable? A repository writer can comment:
/ai-review override fable a2c47382257981a61a4728089470388ac9ffe55f: <one-sentence reason>

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of a2c47382257981a61a4728089470388ac9ffe55f and found no blocking issues.

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/knowledge/ingestion.py:95 -- concurrent waiters all execute self._tokens = 0.0 after one delay, exceeding the configured rate -> Fix: loop under the lock until each waiter reserves a token.
FINDING -- src/kiro_crew/knowledge/llm_pool.py:514 -- "explicit" overrides Auto Research’s intentional pool_size=1, spawning extra workers -> Fix: override only when the constructor retained DEFAULT_POOL_SIZE.
FINDING -- src/kiro_crew/agent.py:2944 -- function-local from kiro_crew.config.loader import KiroCrewConfig violates the top-level-imports rule -> Fix: move the import to module scope.
FINDING -- src/kiro_crew/knowledge/ingestion.py:107 -- function-local from kiro_crew.config.loader import KiroCrewConfig violates the top-level-imports rule without a circular-import explanation -> Fix: move it to module scope or document the genuine cycle.
[GPT-REVIEWED] a2c4738

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a2c47382257981a61a4728089470388ac9ffe55f: <one-sentence reason>

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

Advisory design-level review of a2c47382257981a61a4728089470388ac9ffe55f — updated in place on each push; does not block merge.

Design-Verdict: CONCERNS

Right shape (global caps over per-source caps), but the "hard cap across ALL sources" isn't, and extraction_model duplicates the existing role_models seam.

Watch

• The global budget doesn't cover all ingestion paths. sweep_chunk_budget gates only the folder-source loop; the local_file loop right after it calls pipeline.ingest_file with no accounting against sweep_chunks_used, so the description's "hard cap on total chunks across ALL sources" is false for file sources — a burst of changed files still bypasses the cap the PR exists to add.
• Phantom claim on max_sources. The field metadata says manual registrations past the cap are "rejected", but only create_auto_source_unless_dismissed takes max_sources; add_source is untouched, so manual adds are uncapped. Also the cap counts all source rows (uploads, single files) against a limit meant to bound watched folders — 45 uploads silently stops project-doc auto-discovery with no user-visible signal.
• knowledge.extraction_model is a second, divergent model-pinning surface. AGENTS.md's doctrine is "pin a cheaper model only via agent.role_models.<role> → resolve_model(role)"; this adds a parallel key, writes the id verbatim into the agent file with no resolve_usable_model/entitlement check (an unentitled explicit pick fails silently at first extraction), and flips the default from the cheapest model to the user's chat model — raising cost-per-chunk inside a cost-control PR.
• Fixed-order break is starvation, not deferral. Sources iterate in DB row order every sweep; a large early source that keeps churning consumes the budget indefinitely and later sources never ingest. The PR defers "round-robin fairness" but ships the failure mode now.

Suggestions

• Fold extraction_model into agent.role_models (e.g. a knowledge role) instead of a new knowledge-section key; you get resolution and validation for free.
• Charge the local_file loop against sweep_chunks_used, and count only folder/auto sources toward max_sources.
• Rotate the sweep's starting offset (e.g. by last-scanned timestamp) — one line of fairness that removes the starvation mode without the deferred priority queue.

[DESIGN-REVIEWED] a2c4738

[github-actions]

UX Review (Fable 5) — ⏭️ skipped

Revision a2c47382257981a61a4728089470388ac9ffe55f touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.