codegraff 0.1.1__cp313-cp313-win_amd64.whl

codegraff/__init__.py

@@ -0,0 +1,270 @@
+"""Python SDK for the codegraff agent."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Optional
+
+from codegraff._native import GraffApi, ChatStreamHandle, version as _native_version
+from codegraff._validation import validate
+
+__all__ = ["Graff", "GraffSession", "Sandbox", "version"]
+
+
+def version() -> str:
+    return _native_version()
+
+
+@dataclass
+class AgentEvent:
+    type: str
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def __repr__(self) -> str:
+        return f"AgentEvent({self.type!r}, {self.data})"
+
+
+def _parse_event(raw: str) -> AgentEvent:
+    d = json.loads(raw)
+    t = d.pop("type", "unknown")
+    return AgentEvent(type=t, data=d)
+
+
+class Graff:
+    """Long-lived codegraff instance. Mirrors the TS SDK's Graff class."""
+
+    def __init__(
+        self,
+        *,
+        cwd: Optional[str] = None,
+        provider: Optional[str] = None,
+        api_key: Optional[str] = None,
+        model: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+    ):
+        validate("init", {"cwd": cwd, "provider": provider, "api_key": api_key, "model": model, "max_tokens": max_tokens})
+        if api_key and not provider:
+            raise ValueError("provider is required when api_key is supplied")
+
+        if provider:
+            os.environ["FORGE_SESSION__PROVIDER_ID"] = provider
+        if model:
+            os.environ["FORGE_SESSION__MODEL_ID"] = model
+        if max_tokens is not None:
+            os.environ["FORGE_MAX_TOKENS"] = str(max_tokens)
+
+        self._api = GraffApi.init(cwd or os.getcwd())
+
+        if api_key and provider:
+            # extra_params is a required positional in the native binding
+            # (Option without a #[pyo3(signature)] default), so pass None.
+            self._api.upsert_credential(provider, api_key, None)
+
+    def chat(
+        self,
+        prompt: str,
+        *,
+        conversation_id: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> Iterator[AgentEvent]:
+        """Run a chat turn. Yields AgentEvent objects."""
+        validate("chat", {"prompt": prompt, "conversation_id": conversation_id, "model": model})
+        handle = self._api.chat(prompt, conversation_id, model)
+        yield AgentEvent(type="ConversationStarted", data={"conversationId": handle.conversation_id})
+        while True:
+            raw = handle.next_event()
+            if raw is None:
+                break
+            yield _parse_event(raw)
+
+    def session(
+        self,
+        *,
+        conversation_id: Optional[str] = None,
+        model: Optional[str] = None,
+    ) -> "GraffSession":
+        return GraffSession(self, conversation_id=conversation_id, model=model)
+
+    # -- Conversation management --
+
+    def list_conversations(self, limit: Optional[int] = None) -> list[dict]:
+        return json.loads(self._api.list_conversations(limit))
+
+    def get_conversation(self, id: str) -> Optional[dict]:
+        raw = self._api.get_conversation(id)
+        return json.loads(raw) if raw else None
+
+    def last_conversation(self) -> Optional[dict]:
+        raw = self._api.last_conversation()
+        return json.loads(raw) if raw else None
+
+    def delete_conversation(self, id: str) -> None:
+        self._api.delete_conversation(id)
+
+    def compact_conversation(self, id: str) -> dict:
+        return json.loads(self._api.compact_conversation(id))
+
+    # -- Agents --
+
+    def get_agent_infos(self) -> list[dict]:
+        return json.loads(self._api.get_agent_infos())
+
+    # -- Auth --
+
+    def upsert_credential(
+        self,
+        provider_id: str,
+        api_key: str,
+        extra_params: Optional[list[list[str]]] = None,
+    ) -> None:
+        self._api.upsert_credential(provider_id, api_key, extra_params)
+
+    def remove_credential(self, provider_id: str) -> None:
+        self._api.remove_credential(provider_id)
+
+    # -- Sandboxes (gateway HTTP) --
+
+    def create_sandbox(self, **kwargs) -> "Sandbox":
+        return Sandbox.create(self, **kwargs)
+
+    def get_sandbox(self, id: str) -> "Sandbox":
+        return Sandbox.get(self, id)
+
+    def list_sandboxes(self) -> list[dict]:
+        return Sandbox.list(self)
+
+    def version(self) -> str:
+        return self._api.version()
+
+
+class GraffSession:
+    """Multi-turn session that preserves conversation_id across sends."""
+
+    def __init__(
+        self,
+        graff: Graff,
+        *,
+        conversation_id: Optional[str] = None,
+        model: Optional[str] = None,
+    ):
+        self._graff = graff
+        self._conversation_id = conversation_id
+        self._model = model
+
+    @property
+    def conversation_id(self) -> Optional[str]:
+        return self._conversation_id
+
+    def send(self, prompt: str) -> Iterator[AgentEvent]:
+        for event in self._graff.chat(prompt, conversation_id=self._conversation_id, model=self._model):
+            if event.type == "ConversationStarted" and not self._conversation_id:
+                self._conversation_id = event.data.get("conversationId")
+            yield event
+
+
+# -- Sandbox (thin HTTP client hitting the gateway) --
+
+import urllib.request
+import urllib.error
+
+_GATEWAY_URL = os.environ.get("CODEGRAFF_GATEWAY_URL", "https://gateway.codegraff.com")
+
+
+def _gateway_fetch(api_key: str, method: str, path: str, body: Optional[dict] = None) -> Any:
+    url = f"{_GATEWAY_URL}{path}"
+    data = json.dumps(body).encode() if body is not None else None
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method=method,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": "codegraff-python-sdk/0.1.0",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            ct = resp.headers.get("Content-Type", "")
+            raw = resp.read()
+            if "application/json" in ct:
+                return json.loads(raw)
+            return raw.decode()
+    except urllib.error.HTTPError as e:
+        body_text = e.read().decode()[:300] if e.fp else ""
+        raise RuntimeError(f"Gateway {method} {path} failed ({e.code}): {body_text}") from e
+
+
+def _resolve_api_key() -> str:
+    for var in ("CODEGRAFF_API_KEY", "CG_API_KEY"):
+        val = os.environ.get(var, "")
+        if val:
+            return val
+    return ""
+
+
+class Sandbox:
+    """Cloud sandbox managed through the codegraff gateway."""
+
+    def __init__(self, graff: Graff, id: str):
+        self._graff = graff
+        self._api_key = _resolve_api_key()
+        self.id = id
+
+    @staticmethod
+    def create(
+        graff: Graff,
+        *,
+        language: str = "javascript",
+        auto_stop_minutes: int = 30,
+        labels: Optional[dict[str, str]] = None,
+    ) -> "Sandbox":
+        api_key = _resolve_api_key()
+        data = _gateway_fetch(api_key, "POST", "/v1/sandboxes", {
+            "language": language,
+            "autoStopMinutes": auto_stop_minutes,
+            "labels": labels or {},
+        })
+        return Sandbox(graff, data["id"])
+
+    @staticmethod
+    def get(graff: Graff, id: str) -> "Sandbox":
+        api_key = _resolve_api_key()
+        _gateway_fetch(api_key, "GET", f"/v1/sandboxes/{id}")
+        return Sandbox(graff, id)
+
+    @staticmethod
+    def list(graff: Graff) -> list[dict]:
+        api_key = _resolve_api_key()
+        return _gateway_fetch(api_key, "GET", "/v1/sandboxes")
+
+    def info(self) -> dict:
+        return _gateway_fetch(self._api_key, "GET", f"/v1/sandboxes/{self.id}")
+
+    def exec(self, command: str, *, cwd: Optional[str] = None, env: Optional[dict] = None, timeout_seconds: int = 300) -> dict:
+        return _gateway_fetch(self._api_key, "POST", f"/v1/sandboxes/{self.id}/exec", {
+            "command": command, "cwd": cwd, "env": env, "timeoutSeconds": timeout_seconds,
+        })
+
+    def upload(self, content: bytes | str, dest_path: str) -> None:
+        import base64
+        b = content if isinstance(content, bytes) else content.encode()
+        _gateway_fetch(self._api_key, "POST", f"/v1/sandboxes/{self.id}/upload", {
+            "path": dest_path, "contentBase64": base64.b64encode(b).decode(),
+        })
+
+    def download(self, path: str) -> bytes:
+        import base64
+        data = _gateway_fetch(self._api_key, "POST", f"/v1/sandboxes/{self.id}/download", {"path": path})
+        return base64.b64decode(data["contentBase64"])
+
+    def stop(self) -> dict:
+        return _gateway_fetch(self._api_key, "POST", f"/v1/sandboxes/{self.id}/stop")
+
+    def start(self) -> dict:
+        return _gateway_fetch(self._api_key, "POST", f"/v1/sandboxes/{self.id}/start")
+
+    def destroy(self) -> None:
+        _gateway_fetch(self._api_key, "DELETE", f"/v1/sandboxes/{self.id}")

codegraff/_validation.py

@@ -0,0 +1,81 @@
+"""dhi-backed input validation for the codegraff Python SDK.
+
+Mirrors the TS SDK's ``validation.js``. dhi (https://github.com/justrach/dhi) is
+a Pydantic-compatible validator. Validation is **advisory**: if dhi can't be
+imported, we fall back to a minimal check so validation never becomes a *new*
+hard failure. We only read the pass/fail result — the original option values
+reach the native layer unchanged (no coercion, no mutation).
+
+dhi ships native wheels for cp39-cp314 (incl. free-threaded cp313t/cp314t). The
+native build (>=1.3.3) matches Pydantic on the type checks we use and, on a
+free-threaded interpreter, no longer re-enables the GIL. A pure-Python fallback
+is only used where no native wheel exists (e.g. Windows) and is looser on
+``Optional[...]`` fields.
+"""
+
+# Keep these annotations as real objects (no `from __future__ import annotations`).
+# dhi's old pure-Python fallback silently skipped validation when annotations were
+# stringized; native dhi (>=1.3.2) resolves them, but there's no reason to add the
+# future import here.
+import warnings
+from typing import Optional
+
+_models = None
+_warned = False
+
+
+def _build():
+    from dhi import BaseModel  # lazy: SDK still imports if dhi is absent
+
+    class InitOptions(BaseModel):
+        cwd: Optional[str] = None
+        provider: Optional[str] = None
+        api_key: Optional[str] = None
+        model: Optional[str] = None
+        max_tokens: Optional[int] = None
+
+    class ChatOptions(BaseModel):
+        prompt: str
+        conversation_id: Optional[str] = None
+        model: Optional[str] = None
+
+    return {"init": InitOptions, "chat": ChatOptions}
+
+
+def _get():
+    global _models
+    if _models is None:
+        _models = _build()
+    return _models
+
+
+def _fallback(kind: str, opts: dict) -> None:
+    if kind == "chat" and not isinstance(opts.get("prompt"), str):
+        raise TypeError("codegraff chat: `prompt` must be a string")
+    if kind == "init":
+        ak = opts.get("api_key")
+        if ak is not None and not isinstance(ak, str):
+            raise TypeError("codegraff init: `api_key` must be a string")
+
+
+def validate(kind: str, opts: dict) -> None:
+    """Validate public options for `kind` in ('init', 'chat').
+
+    Raises ValueError on invalid input; returns None on success. Never mutates
+    `opts`.
+    """
+    global _warned
+    try:
+        models = _get()
+    except Exception as e:  # dhi missing / failed to import
+        if not _warned:
+            _warned = True
+            warnings.warn(f"codegraff: dhi validation unavailable ({e}); using basic checks")
+        return _fallback(kind, opts)
+    model = models.get(kind)
+    if model is None:
+        return
+    try:
+        model(**opts)
+    except Exception as e:
+        raise ValueError(f"codegraff {kind}: invalid options — {e}") from None

codegraff-0.1.1.dist-info/METADATA

@@ -0,0 +1,88 @@
+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.
+

codegraff-0.1.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+codegraff/__init__.py,sha256=Nm0dtzrb5Qt-T91dA0Nbx4hNGuQpExotRvKBk2EUAYQ,9055
+codegraff/_native.cp313-win_amd64.pyd,sha256=WymNF3K2YNDBeNUqQIZ2TKV6loux4o-SUxIJeJaESTc,40040960
+codegraff/_validation.py,sha256=uWyK5LBeiNJ4eyOWZr8y2iNRJzWWp2IgsA7Twfb-wTM,2896
+codegraff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codegraff-0.1.1.dist-info/METADATA,sha256=3AYzPFm_cvgfo74s7EiNZecgXdItGaQdwU1QJ3301fk,3298
+codegraff-0.1.1.dist-info/WHEEL,sha256=SOvIh6ndLyztvkrMKsamHag5pxo6YUrIipqSIMTC7-I,97
+codegraff-0.1.1.dist-info/sboms/forge_sdk_python.cyclonedx.json,sha256=7_7xuVtJ9lEEO5yP8ckec-Sp7bOCT0V-OUi_OoOPVVs,758081
+codegraff-0.1.1.dist-info/RECORD,,

codegraff-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.13.3)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win_amd64