context-budget — context allocation under a token budget

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Commands, APIs and runtime behavior described below are conditional examples for a compatible upstream installation; they are not evidence of execution in this package.

When NOT to use

• You want to measure the always-on cost, not allocate it — use context_profiler.
• One large body of context must serve several agents or task types — use context_slicer.
• You only need a ranked shortlist and have no budget constraint — use skill_finder.

The OR-Tools principle applied to the agent's always-on cost: choosing which skills/docs to load is a 0/1 knapsack — maximize total relevance while the summed token cost stays under a budget. The upstream design uses dynamic programming for this 0/1 model. Verify the installed solver, relevance inputs, token estimates and any scaling before interpreting the result as optimal for the original inputs.

python -m skills.context_budget.cli "optimize slow postgres queries and add tests" --budget 3000
python -m skills.context_budget.cli "<task>" --budget 4000 --json

How it selects

1. Rank — score every skill against the task lexically ([[skill-finder]], matching), with each skill's token cost.
2. Knapsack — knapsack(items, budget) finds the subset that maximizes summed relevance subject to Σ tokens ≤ budget (exact DP, token costs scaled to bound the table). Inspect how scaling affects the original budget and objective.
3. Frame — report the chosen set, tokens used, relevance captured, and the saving vs loading the whole catalog.

No typical subset size or savings is established by this catalog. Report the actual chosen inventory, budget and measured or estimated costs from the compatible installed runtime.

The knapsack(items, budget) engine is generic (takes Item(name, kind, tokens, relevance)), so docs ([[docs-steward]]) or any context source plug in the same way. Exposed via [[llm-mcp]] as context_budget. Related: [[skill-finder]] (ranking), [[metrics]] (measures the always-on cost this cuts).

First of the deterministic "solver" hybridizations (OR-Tools-inspired): exact combinatorial optimization replacing LLM reasoning for structured decisions.