ExecutionKit sits between a raw chat-completions call and a workflow runtime. It provides bounded functions for common call patterns, plus small helpers for cost tracking, retries, approvals, routing, checkpoints, tracing, and evaluation.

Use it when your application already owns the surrounding service and needs a few well-defined LLM execution functions. Do not use it as a retrieval system, long-running scheduler, provider gateway, or multi-agent runtime. See Scope for the boundary.

The base install supports Python 3.11 through 3.13 and has no required third-party runtime dependencies.

Release status

python -m pip install executionkit currently installs 0.4.0 (released 2026-09-23), which includes the Claude Agent SDK transport and the two RetryConfig/react_loop() behavior changes described below. The full, commit-traceable list is the [0.4.0] section of CHANGELOG.md.

Install

python -m pip install executionkit

Optional extras add only the feature you request:

python -m pip install "executionkit[httpx]"       # pooled HTTP connections
python -m pip install "executionkit[jsonschema]"  # full tool-argument validation
python -m pip install "executionkit[otel]"        # OpenTelemetry API integration
python -m pip install "executionkit[claude]"      # Claude Agent SDK transport

First call

import asyncio
import os

from executionkit import Provider, consensus


async def main() -> None:
    async with Provider(
        base_url="https://api.openai.com/v1",
        api_key=os.environ["OPENAI_API_KEY"],
        model=os.environ["OPENAI_MODEL"],
    ) as provider:
        result = await consensus(
            provider,
            "Return only the ISO country code for France.",
            num_samples=3,
        )
        print(result.value)
        print(result.metadata["agreement_ratio"])
        print(result.cost)


asyncio.run(main())

Expected output (token counts depend on the endpoint; the shape does not):

FR
1.0
TokenUsage(input_tokens=..., output_tokens=..., llm_calls=3)

result.cost.llm_calls counts dispatched HTTP attempts, including retries. For example, three samples cost three calls only when none of the samples is retried.

See the quick start for local-provider setup, synchronous wrappers, and the other patterns.

Patterns

Async functions are the primary API. Matching _sync wrappers are available for all six patterns in code that does not already run an event loop.

Every pattern returns PatternResult:

result.value       # pattern output
result.score       # optional pattern-specific score
result.cost        # TokenUsage(input_tokens, output_tokens, llm_calls)
result.metadata    # read-only pattern-specific metadata

Execution helpers

These helpers run inside one process. They do not provide durable scheduling, distributed coordination, or multi-agent handoff.

Versioned retry guidance. RetryConfig.max_retries means something different depending on which version you run:

The 0.4.0 behavior also makes RetryConfig agree with structured()'s own max_retries, which has always run 1 + max_retries attempts, and it rejects a negative max_retries with ValueError instead of silently making zero attempts. To keep 0.3.0's call count exactly when you upgrade, decrement existing max_retries values by one (max_retries=N → max_retries=N-1); max_retries=0 is unchanged either way — always a single attempt, no retries. See the [0.4.0] section of CHANGELOG.md for the full migration note, including a max_cost budget edge case.

Provider contract

Provider sends bearer-authenticated requests to an OpenAI-compatible /chat/completions endpoint. Set base_url, api_key, and model for the endpoint you use:

provider = Provider(
    base_url="http://localhost:11434/v1",
    model="your-local-model",
)

You can also pass any object that implements the LLMProvider protocol. A custom adapter does not need to inherit from an ExecutionKit class.

Provider compatibility varies by endpoint and model. In particular, tool calling and streaming work only when the endpoint returns the corresponding OpenAI-format fields. The provider guide lists the exact contract and current endpoint examples.

Tool execution boundary

react_loop() executes only the Tool objects registered by the caller. The loop applies these controls before and around each tool call:

• tool names must be unique — enforced with a ValueError before the first provider call (0.4.0+; on 0.3.0 and earlier a duplicate name silently shadows the earlier tool instead of raising);
• arguments are checked against a dependency-free JSON Schema subset;
• schemas outside that subset fail closed unless the jsonschema extra is installed;
• each tool has a timeout;
• calls per round, rounds per run, and observation length are bounded;
• an optional ApprovalGate can reject a call before its body runs; and
• tool exceptions become bounded observations containing the exception type, not the exception message or traceback.

This protects the model-to-tool boundary. It does not isolate the Python code inside a tool. Run untrusted tool implementations in a separate process or container owned by your application.

MCP and batch integrations

python -m executionkit.mcp starts a standard-library-only MCP server over stdio. It exposes consensus and a react_loop limited to the package's fixed demo tools. It does not expose arbitrary caller-defined Python functions.

AnthropicBatchClient, consensus_batch(), and map_batch() use Anthropic's Message Batches API for offline fan-out jobs. This integration is Anthropic-specific and separate from the OpenAI-compatible Provider.

Read the MCP guide and Message Batches guide before using either integration.

Scope

ExecutionKit intentionally does not provide:

• retrieval, embeddings, or vector storage;
• persistent or distributed workflow scheduling;
• dashboards or spend-management services;
• native adapters for every model provider; or
• multi-agent coordination.

The companion agentic-runtime-platform owns the higher-level runtime concerns. ExecutionKit remains usable on its own.

Documentation

• Installation
• Provider setup
• Pattern selection
• Execution controls
• Evaluation
• API index
• Architecture
• Changelog

Development

python -m pip install -e ".[dev,docs]" pip-audit
python -m ruff check executionkit tests scripts
python -m ruff format --check executionkit tests scripts
python -m mypy --strict executionkit
python scripts/check_doc_facts.py
python scripts/check_lock_parity.py
python -m pytest -q
python -m mkdocs build --strict

See CONTRIBUTING.md for platform-specific setup and the optional security checks.

License

MIT. See LICENSE.