keel-agent 0.3.0

In-process agent sessions: task contracts, transcript merge, compression, and YAML policy

Keel

Python library for long-running LLM agents: task contracts, transcript merge, tiered context compression, and YAML policy (tools and outbound text). Runs in-process beside your provider SDK.

PyPI distribution: keel-agent. Import name: keel (import keel).

Optional CloudClient syncs audit-style events when KEEL_API_KEY is set; the hosted dashboard is a separate product.

Install

pip install keel-agent
pip install 'keel-agent[cloud]'   # httpx for CloudClient

From a checkout:

pip install -e .
pip install -e ".[dev]"    # tests + ruff

Example

import asyncio
from keel import AgentSession, TaskContract

async def main():
    contract = TaskContract(
        objective="Ship the fix",
        hard_constraints="No secrets in logs.",
        done_criteria="Tests pass.",
        version=1,
        created_at="2026-01-01T00:00:00Z",
        updated_by="app",
    )
    session = AgentSession(contract=contract, transcript=[])
    prep = await session.prepare_turn([{"role": "user", "content": "Next step?"}])
    # prep.messages_for_model -> your LLM API
    # await session.check_tool_or_raise(name, args) before each tool call
    # session.finish_turn(prep.merged_transcript_base, assistant_dict)

asyncio.run(main())

Cloud sync

from keel import CloudClient

client = CloudClient()  # KEEL_API_KEY, KEEL_CLOUD_BASE_URL from env
info = client.verify_subscription()
if info.active:
    client.push_audit_batch([{"type": "compression", "tokens_saved": 42}])

See docs/CLOUD.md in the repository for behavior and endpoints. Base URL is env-driven.

Configuration

Environment variables use the KEEL_ prefix (e.g. KEEL_VERBATIM_USER_TURNS, KEEL_POLICY_FILE). Defaults and types are in keel/config.py.

Tests

pip install -e ".[dev]"
pytest -q tests/

Documentation

Guides and OpenAPI for the cloud API live under docs/ in the source tree. On PyPI, open the project’s repository and browse that folder (the published sdist is code-only).

Modules

Module	Role
keel.runtime	AgentSession, PreparedTurn
keel.context_assembly	merge + assemble_messages
keel.compressor	tiered compression
keel.policy_yaml	YAML policy loading
keel.cloud	optional authenticated sync
keel.grading	deterministic rubrics for tests / evals