Phase-specific, budget-aware context compilation for tool-using AI agents.

500+ tests passing · zero runtime dependencies · deterministic output · Python ≥ 3.10

Imagine a tool-using agent with a 100-tool catalog and a 50-turn conversation history. At each step the agent must answer four questions:

1. Route — which tool should I call?
2. Call — what arguments?
3. Interpret — what did it return?
4. Answer — how do I respond to the user?

Naive approach A — concatenate everything:

100 tool schemas (≈50k tokens) + 50 turns (≈30k tokens) = 80k tokens
Token limit: 8k → 10× overflow

Naive approach B — cherry-pick manually:

Pick 10 tools, last 5 turns → lose dependency chains
Agent hallucinates tool calls, repeats questions, forgets context

contextweaver approach — phase-specific budgeted compilation:

Route phase:  5 tool cards (≈500 tokens), no full schemas
Answer phase: 3 relevant turns + dependency closure (≈2k tokens)
Result:       2.5k tokens, complete context, deterministic

See examples/before_after.py for a runnable side-by-side comparison.

contextweaver provides two cooperating engines:

                ┌────────────────────────────┐
  Events ──────>│      Context Engine         │──> ContextPack (prompt)
                │  candidates → closure →     │
                │  sensitivity → firewall →   │
                │  score → dedup → select →   │
                │  render                     │
                └────────────────────────────┘
                           ▲ facts / episodes
                ┌──────────┴─────────────────┐
  Tools ───────>│      Routing Engine         │──> ChoiceCards
                │  Catalog → TreeBuilder →    │
                │  ChoiceGraph → Router       │
                └────────────────────────────┘

Context Engine — eight-stage pipeline:

1. generate_candidates — pull phase-relevant events from the log for this request.
2. dependency_closure — if a selected item has a parent_id, include the parent automatically.
3. sensitivity_filter — drop or redact items at or above the configured sensitivity floor.
4. apply_firewall — tool results are stored out-of-band; large outputs are summarized/truncated before prompt assembly.
5. score_candidates — rank by recency, tag match, kind priority, and token cost.
6. deduplicate_candidates — remove near-duplicates using Jaccard similarity.
7. select_and_pack — greedily pack highest-scoring items into the phase token budget.
8. render_context — assemble final prompt string with BuildStats metadata.

Routing Engine — four-stage pipeline:

1. Catalog — register and manage SelectableItem objects.
2. TreeBuilder — convert a flat catalog into a bounded ChoiceGraph DAG.
3. Router — beam-search over the graph; deterministic tie-breaking by ID.
4. ChoiceCards — compact, LLM-friendly cards (never includes full schemas).

pip install contextweaver

Or from source:

git clone https://github.com/dgenio/contextweaver.git
cd contextweaver
pip install -e ".[dev]"

from contextweaver.context.manager import ContextManager
from contextweaver.types import ContextItem, ItemKind, Phase

mgr = ContextManager()
mgr.ingest(ContextItem(id="u1", kind=ItemKind.user_turn, text="How many users?"))
mgr.ingest(ContextItem(id="tc1", kind=ItemKind.tool_call,
                       text="db_query('SELECT COUNT(*) FROM users')", parent_id="u1"))
mgr.ingest(ContextItem(id="tr1", kind=ItemKind.tool_result,
                       text="count: 1042", parent_id="tc1"))

pack = mgr.build_sync(phase=Phase.answer, query="user count")
print(pack.prompt)   # budget-aware compiled context
print(pack.stats)    # what was kept, dropped, deduplicated

from contextweaver.routing.catalog import Catalog, load_catalog_json
from contextweaver.routing.tree import TreeBuilder
from contextweaver.routing.router import Router

catalog = Catalog()
for item in load_catalog_json("catalog.json"):
    catalog.register(item)

graph = TreeBuilder(max_children=10).build(catalog.all())
router = Router(graph, items=catalog.all(), beam_width=3, top_k=5)
result = router.route("send a reminder email about unpaid invoices")
print(result.candidate_ids)

See docs/concepts.md for the full glossary and docs/architecture.md for pipeline detail and design rationale.

contextweaver ships with a CLI for quick experimentation:

contextweaver demo                                    # end-to-end demonstration
contextweaver init                                    # scaffold config + sample catalog
contextweaver build --catalog c.json --out g.json    # build routing graph
contextweaver route --graph g.json --query "send email"
contextweaver print-tree --graph g.json
contextweaver ingest --events session.jsonl --out session.json
contextweaver replay --session session.json --phase answer

make example   # run all examples

make fmt      # format (ruff)
make lint     # lint (ruff)
make type     # type-check (mypy)
make test     # run tests (pytest)
make example  # run all examples
make demo     # run the built-in demo
make ci       # all of the above

See CONTRIBUTING.md for setup instructions.

See CHANGELOG.md for the detailed release history.

Apache-2.0