Handbook

Knowledge Assistant recipe router

Canonical operator reference for the forge-knowledge-assistant Copilot recipe plane. Library concepts: LMeta v4 execution, v5-alpha authoring, routing ladders.

Updated

Entry point

copilot_ask_routed() — matches recipes when enabled, dispatches active fast path via recipe_dispatch, emits route telemetry.

Flags (defaults safe)

Env Default Effect
KA_COPILOT_RECIPES_ENABLED false Enable matcher
KA_COPILOT_RECIPES_SHADOW true Log matches; keep slow-path response
KA_COPILOT_PHRASE_FTS_ENABLED true Phrase FTS second layer
KA_COPILOT_LMETA_ENABLED false Run lmeta_flow_id instead of Python handler
KA_COPILOT_V4_ROUTER_FLOW_ENABLED false Dispatch via generated static router flow
KA_COPILOT_COMPILED_V5_ENABLED false Prefer flows/copilot/generated/compiled-v5/
KA_COPILOT_LLM_TIEBREAK_ENABLED false Experimental margin tiebreak (recipe must opt in)
KA_COPILOT_PROMOTION_ENABLED false Offline promotion tooling only

Active dispatch guards

  • Recipe status must be shadow or active (not draft).
  • Handler must be wired (five recipes in phase 1: find slides, summarize, locate/export, topic facets, compare).
  • Fast path uses FastPathBudgetLedger (≤1 LLM call); budget exhaustion does not fall back to slow path after a call.

Soak before production

  1. Parity tests green (Python handler vs LMeta) for adopted recipes.
  2. Shadow routing precision ≥88% on golden asks (monitor toward 95%).
  3. Seven-day shadow with stable calls_per_ask telemetry.
  4. Enable RECIPES_ENABLED=1, then RECIPES_SHADOW=0 per environment.

Maintainer workflows

Task Command / path
Compile GoalSpecs python3 scripts/compile-lmeta-v5.py (--check in CI)
Regenerate static router python3 scripts/generate-copilot-static-router.py
Golden routing fixture tests/fixtures/copilot-golden-asks.v1.yaml
v5-alpha source flows/copilot/v5-alpha/

Set LMETA_V5_LAB_ROOT to workbench/lmeta-v5-lab when regenerating the router via the IntentProgram compiler.

Rollback

  • RECIPES_SHADOW=1 or RECIPES_ENABLED=0 — immediate slow-path only.
  • COMPILED_V5_ENABLED=0 — hand-authored v4 flows.

Tests (representative)

cd forge-knowledge-assistant
PYTHONPATH=src:../forge-lcdl/src pytest tests/test_copilot_active_routing.py tests/test_copilot_lmeta_parity.py -q