kontxt 0.1.0a1

Context orchestration primitives for LLM applications.

kontxt

Context engineering for production AI systems

Most AI projects fail not because of bad models, but because of bad context. kontxt solves this.

The Problem

85% of AI projects fail to deliver on their promises (Gartner). The root cause isn't model quality—it's context engineering:

• ❌ Context overload - Passing too much irrelevant data → hallucinations, high costs
• ❌ Missing context - Omitting critical information → poor decisions
• ❌ No memory - Long conversations overflow context windows → agent amnesia
• ❌ Poor formatting - Unstructured data → model confusion
• ❌ No observability - Can't debug production failures

"Context engineering is the new skill in AI. It is about providing the right information and tools, in the right format, at the right time." — Philipp Schmid

The Solution

kontxt is a lightweight library that gives you production-grade context control:

• 🎯 Budget control - Set token limits, auto-trim intelligently
• 🧠 Memory primitives - Scratchpads, vector stores, persistence
• 🔄 Multi-phase flows - Coordinate complex agent workflows
• 📊 Token observability - Track usage, debug context issues
• 🔌 Vendor-agnostic - Works with OpenAI, Anthropic, Gemini, or any LLM
• 🔒 Type-safe - Full type hints, IDE autocomplete, zero magic

Key Features

• Context composition with ordered sections, lazy evaluation, and multiple render formats (OpenAI, Anthropic, Gemini)
• Memory primitives including scratchpads, vector stores, and configurable backends
• Phase templates for multi-stage flows with transition validation
• Token budgeting with automatic trimming and priority management
• State management for session tracking and workflow coordination
• Production-ready with comprehensive tests and typed APIs

Installation

⚠️ Alpha Release: This is an alpha version (0.1.0a1) for early testing. APIs may change before the stable 0.1.0 release.

pip install kontxt

Or install from source:

uv pip install -e .

Development tooling:

uv pip install -e '.[dev]'

Quick Start

from kontxt import Context

context = Context()
context.add("system", "You are a dental triage assistant.")
context.add("instructions", "Answer using the provided chart.")
context.add("patient", {"name": "Alex", "age": 41})
context.add("messages", {"role": "user", "content": "My tooth aches."})

prompt = context.render()
# -> XML-style prompt that preserves section boundaries

Memory Integration

from kontxt import Memory

memory = Memory()
memory.store("patient:123", {"allergy": "penicillin"}, meta={"patient_id": "123"})
memory.scratchpad.write("plan", ["Collect symptoms", "Check red flags"])

plan = memory.scratchpad.read("plan")
allergies = memory.retrieve("penicillin", filters={"patient_id": "123"})

Gemini Integration

# Recommended: Explicit imports (scales better)
from kontxt import Context, Memory
from kontxt.types import Format

# Create context with memory
memory = Memory()
ctx = Context(memory=memory)

# Add system prompt and user message
ctx.add("system", "You are a helpful AI assistant")
ctx.add("messages", {"role": "user", "content": "Explain quantum computing"})

# Render for Gemini
payload = ctx.render(
    format=Format.GEMINI,  # Type-safe enum with IDE autocomplete
    generation_config={"temperature": 0.7}
)

# Call Gemini API (you control the API call)
from google import genai
client = genai.Client(api_key="...")
response = client.models.generate_content(model="gemini-2.0-flash-exp", **payload)

# Add response back to context
ctx.add_response(response.text)

Import Patterns

kontxt supports two import styles:

# ✅ Recommended: Explicit imports (better for large projects)
from kontxt import Context, Memory, State
from kontxt.types import Format

# ✅ Also works: Convenience imports (quick scripts)
from kontxt import Context, Memory, State, Format

Both patterns work identically - choose based on your preference and project size.

Available Render Formats

from kontxt.types import Format

Format.TEXT       # Plain text with XML-like tags
Format.OPENAI     # OpenAI chat completion format
Format.ANTHROPIC  # Anthropic messages API format
Format.GEMINI     # Google Gemini API format

See examples/ for complete examples:

• simple_rag.py - Basic RAG workflow

Why kontxt vs LangChain/LlamaIndex?

Most frameworks abstract the wrong things.

They abstract the LLM (doesn't matter—all models work similarly). They don't abstract context (matters most—it's complex and error-prone).

kontxt inverts this:

• ✅ LLM is your responsibility (use any vendor, local models, whatever)
• ✅ Context is our responsibility (we make it production-grade)

Feature	kontxt	LangChain	LlamaIndex
Learning curve	5 minutes	Hours	Hours
Dependencies	2 (pydantic, tiktoken)	20+	15+
Token budgets	✅ Built-in	❌ Manual	❌ Manual
Multi-phase flows	✅ Native	⚠️ Custom	⚠️ Custom
Memory operations	✅ 4 primitives	⚠️ Complex	⚠️ Complex
Vendor lock-in	❌ None	⚠️ High	⚠️ High
Type safety	✅ Full	⚠️ Partial	⚠️ Partial

TL;DR: We do one thing (context engineering) and do it perfectly. They try to do everything, and context becomes an afterthought.

Built for Production

kontxt is built on research-backed context engineering principles:

The Four Operations (Lance Martin, 2025)

1. WRITE - Externalize context beyond the window
2. SELECT - Retrieve relevant context intelligently
3. COMPRESS - Reduce tokens while preserving signal
4. ISOLATE - Partition context for clarity

mem.scratchpad.write("plan", data)           # WRITE
notes = mem.retrieve("plan", filters={...})  # SELECT
ctx.set_budget(max_tokens=4000, priority=[]) # COMPRESS
sub = ctx.fork(include=["system"])           # ISOLATE

Why This Matters

Research shows:

• Context position matters: LLMs exhibit attention bias—details in the middle get lost
• More ≠ better: A model given 46 tools fails; given 19 tools succeeds (same context window)
• Format matters: How you structure data affects model performance as much as what data you include

kontxt handles these nuances so you don't have to.

Who This Is For

Choose kontxt if you're building:

• 🏥 Multi-phase agents (medical triage, customer support, legal analysis)
• 💬 Long conversations (therapy bots, tutoring, extended troubleshooting)
• 💰 Cost-sensitive systems (token budgets matter, can't blow $500 on one session)
• 🔍 Observable AI (need to debug why agents fail in production)
• 🔌 Vendor-agnostic apps (might switch from GPT-4 to Claude to Gemini)

If your AI needs to work in production, not just demos, use kontxt.

Documentation

Documentation scaffolding lives under docs/. We plan to publish the first version once the API stabilises. Contributions are welcome—open an issue if you spot gaps or inconsistencies.

Development

uv sync
uv run pytest
uv run ruff check .

See CONTRIBUTING for detailed guidance.

Roadmap

• Additional storage backends (Qdrant, Pinecone, etc.)
• Built-in compression helpers powered by user-supplied LLMs
• Observability hooks for prompt debugging and token telemetry
• Async APIs once ergonomics questions are resolved

License

Licensed under the Apache 2.0 License. See LICENSE for details.