Metadata-Version: 2.4
Name: codegraff
Version: 0.1.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: dhi>=1.3.3
Summary: Python SDK for the codegraff agent (PyO3 bindings).
Keywords: ai,agent,sandbox,codegraff
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://codegraff.com
Project-URL: Repository, https://github.com/justrach/codegraff

# codegraff

The Python SDK for the [CodeGraff](https://github.com/justrach/codegraff) coding
agent. Run the agent **in-process** (PyO3 native bindings) — streaming events,
multi-turn sessions, BYOK auth, and cloud sandboxes — with synchronous
generators that fit straight into any Python app or web framework.

```bash
pip install codegraff
```

```python
from codegraff import Graff

graff = Graff()  # reads ~/.forge/forge.toml, like the graff CLI

for ev in graff.chat("explain monads in 3 sentences"):
    if ev.type == "TaskMessage" and ev.data.get("content", {}).get("kind") == "Markdown":
        print(ev.data["content"]["text"], end="", flush=True)
```

## BYOK

```python
import os
from codegraff import Graff

graff = Graff(
    provider="codegraff",                  # or "openai" / "anthropic" / "open_router" / "xai" / ...
    api_key=os.environ["CODEGRAFF_API_KEY"],
    model="deepseek-v4-pro",
)
```

`Graff(...)` is a synchronous constructor; `chat()` is a blocking generator that
releases the GIL while it waits on the agent, so it drives async servers without
starving the loop. Inputs are validated at the boundary with
[dhi](https://github.com/justrach/dhi).

## What you get

- **Streaming chat** — `for ev in graff.chat(prompt)` yields `AgentEvent`s
  (`TaskMessage`, `ToolCallStart`/`End`, `TaskReasoning`, `TaskComplete`, …).
- **Multi-turn** — pass `conversation_id`, or use `graff.session()`.
- **Conversation management** — `list_conversations`, `get_conversation`,
  `last_conversation`, `compact_conversation`, `delete_conversation`.
- **Agents & auth** — `get_agent_infos`, `upsert_credential`, `remove_credential`.
- **Cloud sandboxes** — `graff.create_sandbox()` → `exec` / `upload` / `download` /
  `stop` / `start` / `destroy` (via the CodeGraff gateway).

## Install notes

**Platform support (0.1.0):** prebuilt wheels are published **only for macOS
arm64** on Python **3.12 / 3.13 / 3.14t**, and there is **no sdist** — so
`pip install codegraff` fails on Linux, Windows, Intel macOS, or Python
3.9–3.11 until the CI wheel matrix lands. To run elsewhere today, build from the
full repo (not `pip install` — the crate has workspace path deps):

```bash
git clone https://github.com/justrach/codegraff
cd codegraff/sdk/python
pip install maturin && maturin develop --release
```

## Docs & examples

- **In-depth guide:** [docs/sdk/python.md](../../docs/sdk/python.md)
- **turboAPI HTTP example:** [`example/`](./example)
- **TypeScript SDK:** [`@codegraff/sdk`](../typescript) · [guide](../../docs/sdk/typescript.md)

Requires Python >= 3.9. MIT licensed.

