lmctx

Context Kernel for LLM APIs. Standardize what happens before and after every model call, while keeping execution in your own runtime.

• Before call: adapter.plan(context, spec) builds provider-ready payloads and diagnostics
• After call: adapter.ingest(context, response, spec=...) normalizes output back into Context
• Boundary: lmctx never sends HTTP requests, executes tools, or orchestrates loops

Why lmctx

• Append-only, snapshot-friendly context model (Context) with immutable-by-default updates
• Unified part model (Part) for text, images, files, tool calls/results, thinking, compaction
• Loss-resistant round-trips for opaque provider payloads through provider_raw and blob references
• Pluggable blob storage (InMemoryBlobStore, FileBlobStore, or custom BlobStore)
• Provider adapters + auto routing via AutoAdapter on (provider, endpoint, api_version)
• Explainable planning through RequestPlan (included, excluded, warnings, errors)
• Minimal dependencies (core package has no runtime deps; provider SDKs are optional extras)

Install

pip install lmctx

# provider extras (optional)
pip install 'lmctx[openai]'
pip install 'lmctx[anthropic]'
pip install 'lmctx[google]'
pip install 'lmctx[bedrock]'
pip install 'lmctx[all]'

5-Minute Integration

from openai import OpenAI

from lmctx import AutoAdapter, Context, RunSpec
from lmctx.spec import Instructions

# 1) Build conversation state
ctx = Context().user("What is the capital of France?")

# 2) Describe runtime call settings
spec = RunSpec(
    provider="openai",
    endpoint="responses.create",
    model="gpt-4o-mini",
    instructions=Instructions(system="You are concise and accurate."),
)

# 3) Build request payload with lmctx
router = AutoAdapter()
plan = router.plan(ctx, spec)

# 4) Execute with provider SDK in your own code
client = OpenAI()
response = client.responses.create(**plan.request)

# 5) Normalize response back into Context
ctx = router.ingest(ctx, response, spec=spec)

assistant = ctx.last(role="assistant")
if assistant:
    print(assistant.parts[0].text)

Core Types

Built-in Adapters

Documentation

• docs/README.md: doc map and recommended reading paths
• docs/architecture.md: boundaries, lifecycle, extension points
• docs/data-model.md: concrete type contracts and invariants
• docs/api-reference.md: public API quick reference
• docs/adapters.md: adapter matrix and provider caveats
• docs/examples.md: runnable examples and prerequisites
• docs/logs.md: log files and regeneration workflow

Examples

Scripts are in examples/:

• Core (no API keys): quickstart.py, multimodal.py, blob_stores.py, tool_calling.py
• OpenAI: api_openai_responses.py, api_openai_compact.py, api_openai_chat.py, api_openai_images.py
• Anthropic: api_anthropic.py, api_anthropic_compact.py
• Google: api_google_genai.py, api_google_image_generation.py
• Bedrock: api_bedrock.py

Run one:

uv run python examples/quickstart.py

Recorded Logs

Example outputs can be stored locally under examples/logs/ (git-ignored by default). See docs/logs.md for mapping and regeneration commands.

Development

See CONTRIBUTING.md for full guidelines.

uv sync --all-extras --dev
make check

Requirements

• Python >=3.10,<3.15

License

Apache License 2.0. See LICENSE.