theaios-context-router 0.2.1

Intelligent context routing engine for AI agents

Intelligent context routing for AI agents — YAML configs, multi-source retrieval, any platform.

[!NOTE] Part of the theaios ecosystem. Install with pip install theaios-context-router.

What It Does

Define how AI agents discover and receive context in YAML. The engine routes each query to the right sources, enforces agent permissions, fetches content in parallel, scores relevance, and trims to a token budget. No manual prompt-stuffing. Deterministic, fast, auditable.

• YAML configuration — declare sources, routes, permissions, and budgets in a single file
• Multi-source retrieval — inline content, local directories, git repos, REST APIs
• Expression-based routing — route queries to sources using a safe expression language (text contains "policy", boolean logic, variables)
• Agent permissions — per-agent allow/deny lists for sources and file paths
• Token budget management — relevance ranking, configurable truncation strategies (drop, truncate_end, truncate_middle)
• Optional embedding scoring — switch to ranking: embedding for +10% retrieval accuracy via OpenAI embeddings (benchmarks)
• Automatic markdown splitting — splits .md files by H2 headings for fine-grained retrieval
• Disk cache with TTL — cache source results and embeddings to avoid redundant fetches
• Extensible sources — add custom sources via @register_source plugin system
• Security hardened — SSRF protection, path traversal defense, command injection prevention, atomic writes
• CLI tools — validate configs, inspect routers, run queries from the terminal

Quick Start

pip install theaios-context-router

1. Write a config:

# context-router.yaml
version: "1.0"

sources:
  system_prompt:
    type: inline
    content: "You are a helpful assistant. Be concise."
    priority: 10

  docs:
    type: directory
    path: "./data"
    patterns: ["**/*.md", "**/*.txt"]

routes:
  - name: default
    when: ""
    sources: [system_prompt, docs]

  - name: policy-questions
    when: 'text contains "policy"'
    sources: [docs]

budget:
  max_tokens: 4000
  ranking: relevance
  truncation: drop

2. Use it:

from theaios.context_router import Router, load_config, Query

config = load_config("context-router.yaml")
router = Router(config)

response = router.query(Query(text="What is the remote work policy?"))

print(response.matched_routes)  # ["policy-questions", "default"]
print(len(response.chunks))     # 3
print(response.total_tokens)    # 847

Queries tell the engine what context to find. Each query has a text (what to search for), an agent (who is asking), and optional tags and metadata:

# Basic query
router.query(Query(text="How do expenses work?"))

# Agent-specific query (permissions apply)
router.query(Query(text="Show me project docs", agent="eng-assistant"))

# Query with metadata (accessible in route expressions)
router.query(Query(
    text="Find onboarding guide",
    agent="hr-bot",
    tags=["onboarding"],
    metadata={"department": "engineering"},
))

The engine evaluates route conditions against the query, filters by permissions, fetches from allowed sources in parallel, scores relevance, and trims to the token budget. The ContextResponse contains the ranked chunks, metadata, and timing information.

Or one-liner:

from theaios.context_router import query

response = query("context-router.yaml", text="What is the PTO policy?")

3. CLI:

context-router validate --config context-router.yaml
context-router inspect --config context-router.yaml
context-router query --config context-router.yaml --text "What is the remote work policy?"
context-router query --config context-router.yaml --text "expenses" --output json
context-router cache stats --config context-router.yaml
context-router cache clear --config context-router.yaml

Why This Library?

Every AI agent needs context. The options today:

Approach	Problem
Manual prompt-stuffing	Hardcoded, doesn't scale, no permissions
RAG frameworks (LlamaIndex, LangChain)	Heavy dependencies, vector DB required, complex setup
Vendor context windows (Gemini, Claude)	Locked to one provider, no access control
Build your own	Weeks of engineering, no standard format

theaios-context-router is lightweight (pure Python, no vector DB), declarative (YAML configs that teams can review), permission-aware (per-agent access control), and deterministic (same query = same context, every time).

Source Types

Source	Description	Config Key
inline	Static content embedded in config	content
directory	Read files from a local directory	path, patterns
git_repo	Read files from a git ref	path, ref, patterns
http_api	Query a REST API endpoint	url, method, body_template

Custom sources: implement the Source base class and register with @register_source("my_source").

Embedding Scoring (Optional)

The default scoring is keyword overlap — free, 0.6ms, deterministic. For +10% retrieval accuracy on semantic queries, switch to embedding-based scoring:

budget:
  ranking: embedding
  embedding:
    model: text-embedding-3-small
    api_key_env: OPENAI_API_KEY

pip install theaios-context-router[embeddings]

Embeddings are cached on disk — first query indexes all documents, subsequent queries need only 1 API call. See the benchmark results for an honest comparison (keyword: 85% P@1, embedding: 95% P@1, 300x slower, ~$0.0002/query).

Generate Configs with AI

Don't want to write YAML by hand? Use any LLM to generate a config. Copy-paste one of our ready-made prompts and get a production-ready YAML file in seconds. Prompts are included for:

• Generating a full config from scratch (the AI asks about your sources and agents)
• Extending an existing config with new sources or routes
• Converting plain-English routing rules to YAML
• Security-auditing an existing config for permission gaps

Then validate: context-router validate --config generated-config.yaml

Documentation

Full documentation at cohorte-ai.github.io/context-router — including the configuration reference, source types, expression language, permissions, and budget management.

Security

The library is hardened against common attack vectors:

Threat	Protection
SSRF (Server-Side Request Forgery)	HTTP API source blocks private IPs, loopback, link-local, non-HTTP schemes
Command injection (git source)	Git refs and file paths validated against whitelist regex ^[a-zA-Z0-9._/-]+$
Path traversal (directory source)	Resolved paths verified against base directory; symlink escapes blocked
Cache corruption	Atomic writes via tempfile + rename; JSON structure validated on load
ReDoS	Expression parser uses a safe recursive descent parser — no eval(), no regex on user input
YAML deserialization	yaml.safe_load() only — no arbitrary object instantiation
Env var leakage	Config structure validated before environment variable interpolation

See the Security documentation for details.

Part of the theaios Ecosystem

theaios-context-router is one of the theaios platform components. It works standalone or alongside:

• theaios-guardrails — declarative guardrails for AI agent governance
• theaios-trustgate — formal AI reliability certification

License

Apache 2.0 — see LICENSE.