Metadata-Version: 2.4
Name: keel-agent
Version: 0.3.0
Summary: In-process agent sessions: task contracts, transcript merge, compression, and YAML policy
Requires-Python: >=3.11
Requires-Dist: pydantic-settings>=2.6.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.0
Provides-Extra: cloud
Requires-Dist: httpx>=0.27.0; extra == 'cloud'
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

From a checkout:

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

## Example

```python
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

```python
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

```bash
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 |
