python

codegraff

The Python SDK for the 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.

pip install codegraff

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

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.

What you get

• Streaming chat — for ev in graff.chat(prompt) yields AgentEvents (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):

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
• turboAPI HTTP example: example/
• TypeScript SDK: @codegraff/sdk · guide

Requires Python >= 3.9. MIT licensed.