Metadata-Version: 2.4
Name: chronos-gateway
Version: 0.3.0
Summary: Client for Chronos Gateway: AI agents change your Postgres only through checked, approved merges
License-Expression: BUSL-1.1
Project-URL: Homepage, https://chronos.2090.tech
Keywords: postgres,ai-agents,mcp,chronos,approvals
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Pytest
Classifier: Topic :: Database
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# chronos-gateway

The Python client for Chronos Gateway: AI agents change your Postgres only through checked, approved merges. Each
agent task is a run for one tenant, working in its own copy of your data; its merge lands when your rules allow it,
or waits for a person to approve it. Standard library only, Python 3.9+.

```bash
pip install chronos-gateway
```

```python
from chronos_gateway import Gateway

gw = Gateway("https://gateway.example.com", key=os.environ["CHRONOS_GATEWAY_KEY"])
with gw.run(tenant=user.org_id, intent="clean up duplicate leads", end_user=user.id) as run:
    agent.tools = run.openai_tools()          # or run.mcp_server() for MCP clients
    agent.invoke(task)
    result = run.propose()
if result.held:
    link = gw.approval(run.id, end_user=user.id)   # show link.html (the <chronos-approve> widget) to the user
```

- `AsyncGateway` runs the same calls for asyncio code.
- A person approves a part (`gw.approve(run.id, only_keys=["leads/7"])`), or a link only one person, signed in, can
  use (`gw.approval(run.id, approver="bo@acme.com")`).
- A held run whose reads changed since it began raises `GatewayError` with code `reads_changed` (its `body` says what
  changed); a person who decides to merge it anyway: `gw.approve(run.id, skip_read_check=True)`.
- The rules, keys and masks: `policy` / `set_policy`, `keys` / `create_key` / `revoke_key`, `masks` / `set_masks`;
  `events(last=20)` for what happened lately.
- `run.undo(preview=True)` shows what undoing a merged run would put back; `run.undo()` puts it back.
- `run.child(intent, may_change="leads.stage")` delegates part of the work to a sub-agent: a run of its own, its world
  forked from this one's, merging into it; `run.children()` lists them. The parent proposes once they are done.
- `run.propose(evidence=[{"kind": "ticket", "uri": "...", "sha256": "...", "note": "..."}])` keeps what the change
  rests on with the run, for whoever approves it. `gw.effects()` lists effects the gateway delivered.
- `chronos_gateway.adapters`: the run's tools for LangChain and LangGraph, the Claude Agent SDK, the OpenAI Agents
  SDK, CrewAI (`crewai_tools(run)`: query, changes, propose) and Pydantic AI (`pydantic_ai_toolset()` with
  `deps=pydantic_ai_deps(run)`); and `ChronosCheckpointSaver(MemorySaver(), run)`, a LangGraph checkpointer that
  records each checkpoint on the run (a checkpoint of its world, `lg-<id>`, where the engine lets the run's agent
  make one, and always in the run's metadata). Each needs its framework installed; none is imported until asked.
- A pytest fixture, `chronos_run`: a run discarded after the test (set `CHRONOS_GATEWAY_URL`, `CHRONOS_GATEWAY_KEY`
  and `CHRONOS_GATEWAY_TENANT`).
- `verify_signature` checks a webhook delivery's `Chronos-Signature`.

The gateway itself is chronos-gateway, which you run beside your Postgres (or link to Chronos Cloud).
