contextir 1.0.1

Local-first adaptive context compiler and privacy gateway for language models.

ContextIR

ContextIR is a local-first adaptive context compiler and privacy gateway for language models. It turns text into a compact, inspectable intermediate representation while retaining critical source fragments when a lossy summary would be unsafe.

Status: stable 1.0 API. ContextIR follows semantic versioning for the public Python surface and the contextir.v2 contract. Semantic compression and PII detection still require evaluation on each deployment's data.

Quick Start

python3 -m pip install contextir
ollama pull qwen3:0.6b
contextir run --model qwen3:0.6b --text "Reply with only READY."

from contextir import ContextPipeline, OllamaClient

pipeline = ContextPipeline(invoke=OllamaClient("qwen3:0.6b"))
result = pipeline.run(
    "If payment 42 is complete, do not send it again.",
    source_lang="en",
    target_lang="en",
)
print(result.answer)

The release wheel avoids a source checkout and Git dependency. A pinned Git install remains available for environments that prefer source builds.

For a two-minute integration and safe restoration example, see Quick start.

Why

Long agent histories and tool outputs consume model context with repeated facts, formatting, and sensitive values. ContextIR provides three explicit modes:

• raw: masked source text, without protocol overhead;
• hybrid: semantic events plus source fragments containing negation, conditions, numbers, quotes, or protected placeholders;
• semantic: compact events only, for callers that accept lossy compression.

auto first distinguishes exhaustive tasks, document retrieval, and operational history. Exhaustive tasks stay raw. Document QA uses local lexical retrieval to keep the query, formatting instructions, and evidence spans verbatim. Operational history continues to use inspectable events and critical source fragments.

ContextPipeline is the product entry point. It measures candidate prompts with a configurable target-model tokenizer, rejects compression without useful savings, verifies output safety, and performs bounded fallback from semantic to hybrid to raw context.

Install

From a checkout:

python3 -m pip install -e .

Optional Presidio integration:

python3 -m pip install -e '.[privacy]'

Advanced Compiler API

from contextir import ContextIR

gateway = ContextIR()
bundle = gateway.compile_private(
    "If payment 42 is complete, do not send it again. Email [e-mail].",
    source_lang="en",
    target_lang="en",
    mode="hybrid",
)

contract = bundle.contract
model_prompt = gateway.render_prompt(contract)

# Restore only placeholders explicitly allowed by the application.
answer = gateway.restore("Contact PII_EMAIL_1", bundle, allowed={"PII_EMAIL_1"})

compile() returns only the public contract. compile_private() additionally returns the local PII vault and source-reference map. Neither is inserted into the model prompt.

For model-facing applications, prefer ContextPipeline over calling the compiler directly. Use task="transform" for translation, rewriting, and summarization where numbers, negation, constraints, and placeholders must survive. Normal reasoning answers are not incorrectly required to echo the request.

CLI

contextir run \
  --backend ollama \
  --model qwen3:0.6b \
  --text "Summarize the current agent state."

contextir compile \
  --text "Если платеж 42 выполнен, не отправляй его повторно." \
  --source-lang ru \
  --target-lang en \
  --mode hybrid \
  --out /tmp/contextir.json

contextir render --contract /tmp/contextir.json

The source checkout also exposes python3 scripts/contextir.py.

Contract

ContextIR v2 records:

• source and target language;
• intent and confidence;
• typed entities and protected placeholders;
• events with predicate, arguments, polarity, modality, condition, and source reference;
• execution and privacy constraints;
• optional lexical concepts;
• included source fragments and unresolved source references;
• prompt-size and latency statistics.

The packaged JSON Schema is available through:

from contextir.schemas import load_contract_schema

Privacy

The default detector is deliberately small and recognizes common emails, phones, payment-card-like values, and API-key-like tokens. Presidio can be used as an optional detector and extended with project-specific recognizers.

Automated PII detection is not a security boundary by itself. Keep the vault local, avoid logging prompt bodies, use explicit restoration allowlists, and evaluate recognizers on data representative of the deployment.

Current Evidence

The checked-in compiler smoke benchmark reports:

• 9 compiler and 4 product-pipeline cases;
• 0 expectation failures;
• 0 pipeline failures;
• 0 PII leaks into public contracts or rendered prompts;
• 0.3627 prompt/source ratio on the one compression-eligible repeated-context case.

The first model-level A/B exposed a large quality loss in v0.3.0. Query-aware routing corrected that failure. On the v0.5.0 nine-case Qwen3 8B run, raw and auto both scored 0.7272, while auto reduced model input by 70.0% and mean latency from 53.8 s to 2.51 s. An external 1,500-row Presidio Research benchmark measured 0.8471 precision and 1.0000 recall for the dependency-free email/phone/card profile. These are bounded results, not universal quality or privacy claims; broader official tasks and deployment-specific PII evaluation remain required.

See the local model A/B card and benchmark roadmap.

Research Layer

The repository retains the earlier RU/EN lexical graph, graph embeddings, synthetic translator, checkpoints, and roundtrip experiments. They are not loaded by the default package path. Use the research extra and source checkout for those experiments.

The old WordNet keyword roundtrip is preserved as a baseline, not presented as the production compiler. See RESEARCH_HISTORY.md.

Development

python3 -m pip install -e '.[dev,research]'
python3 -m unittest discover -s tests -v
python3 scripts/evaluate_contextir.py
python3 -m build
python3 -m twine check dist/*

Architecture, scope, contribution, and security guidance:

• Architecture
• Quick start
• Product scope
• Benchmarks
• Contributing
• Security

License

ContextIR code is licensed under Apache-2.0. Research datasets and derived lexical artifacts retain their upstream terms. See THIRD_PARTY_NOTICES.md before redistributing them.