graphe-sdk 0.1.0__tar.gz

graphe_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: graphe-sdk
+Version: 0.1.0
+Summary: Python SDK for the Graphe Layer 1 world-state API
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+
+# graphe-sdk
+
+Python client for the [Graphe](https://github.com/) Layer 1 API.
+
+```bash
+pip install graphe-sdk
+```
+
+```python
+from graphe_sdk import GrapheClient, GrapheConfig
+
+config = GrapheConfig.from_env()
+client = GrapheClient(config.base_url, config.api_key)
+print(client.get_health())
+```
+
+See the monorepo `API.md` for endpoint contracts.

graphe_sdk-0.1.0/README.md

@@ -0,0 +1,17 @@
+# graphe-sdk
+
+Python client for the [Graphe](https://github.com/) Layer 1 API.
+
+```bash
+pip install graphe-sdk
+```
+
+```python
+from graphe_sdk import GrapheClient, GrapheConfig
+
+config = GrapheConfig.from_env()
+client = GrapheClient(config.base_url, config.api_key)
+print(client.get_health())
+```
+
+See the monorepo `API.md` for endpoint contracts.

graphe_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "graphe-sdk"
+version = "0.1.0"
+description = "Python SDK for the Graphe Layer 1 world-state API"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0", "respx>=0.21.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

graphe_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

graphe_sdk-0.1.0/src/graphe_sdk/__init__.py

@@ -0,0 +1,14 @@
+from graphe_sdk.client import AuthError, ConflictError, GrapheClient, GrapheError, NotFoundError
+from graphe_sdk.config import GrapheConfig
+from graphe_sdk.instrument import GrapheRun, start_run
+
+__all__ = [
+    "AuthError",
+    "ConflictError",
+    "GrapheClient",
+    "GrapheConfig",
+    "GrapheError",
+    "GrapheRun",
+    "NotFoundError",
+    "start_run",
+]

graphe_sdk-0.1.0/src/graphe_sdk/client.py

@@ -0,0 +1,117 @@
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+class GrapheError(Exception):
+    def __init__(self, status_code: int, detail: Any):
+        super().__init__(f"Graphe API error {status_code}: {detail}")
+        self.status_code = status_code
+        self.detail = detail
+
+
+class ConflictError(GrapheError):
+    pass
+
+
+class AuthError(GrapheError):
+    pass
+
+
+class NotFoundError(GrapheError):
+    pass
+
+
+@dataclass
+class GrapheClient:
+    base_url: str
+    api_key: str
+    timeout: float = 10
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        headers = kwargs.pop("headers", {})
+        headers["x-api-key"] = self.api_key
+        response = httpx.request(method, f"{self.base_url.rstrip('/')}{path}", headers=headers, timeout=self.timeout, **kwargs)
+        if response.status_code >= 400:
+            detail = response.json().get("detail") if response.headers.get("content-type", "").startswith("application/json") else response.text
+            if response.status_code in {401, 403}:
+                raise AuthError(response.status_code, detail)
+            if response.status_code == 404:
+                raise NotFoundError(response.status_code, detail)
+            if response.status_code == 409:
+                raise ConflictError(response.status_code, detail)
+            raise GrapheError(response.status_code, detail)
+        return response.json()
+
+    def log_event(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/api/v1/events", json=payload)
+
+    def create_run(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/api/v1/runs", json=payload)
+
+    def list_runs(self, **params: Any) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/runs", params=params)
+
+    def get_run(self, run_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/runs/{run_id}")
+
+    def get_trace(self, run_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/runs/{run_id}/trace")
+
+    def get_run_issues(self, run_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/runs/{run_id}/issues")
+
+    def explain_run(self, run_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/runs/{run_id}/explain")
+
+    def suggest_next(self, run_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/runs/{run_id}/suggest")
+
+    def get_current_state(self, **params: Any) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/state/current", params=params)
+
+    def get_history(self, **params: Any) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/state/history", params=params)
+
+    def get_health(self) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/health")
+
+    def hybrid_search(self, payload: dict[str, Any], *, mode: str | None = None) -> dict[str, Any]:
+        path = "/api/v1/search/hybrid"
+        if mode:
+            path = f"{path}?mode={mode}"
+        return self._request("POST", path, json=payload)
+
+    def propose_claim(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/api/v1/claims/propose", json=payload)
+
+    def confirm_claim(self, claim_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/api/v1/claims/{claim_id}/confirm")
+
+    def invalidate_claim(self, claim_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/api/v1/claims/{claim_id}/invalidate")
+
+    def supersede_claim(self, claim_id: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", f"/api/v1/claims/{claim_id}/supersede", json=payload)
+
+    def list_claims(self, **params: Any) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/claims", params=params)
+
+    def get_claim(self, claim_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/claims/{claim_id}")
+
+    def create_annotation(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/api/v1/annotations", json=payload)
+
+    def get_observation(self, observation_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/observations/{observation_id}")
+
+    def list_entities(self, **params: Any) -> dict[str, Any]:
+        return self._request("GET", "/api/v1/entities", params=params)
+
+    def get_entity(self, entity_type: str, entity_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/entities/{entity_type}/{entity_id}")
+
+    def get_entity_subgraph(self, entity_type: str, entity_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/entities/{entity_type}/{entity_id}/subgraph")

graphe_sdk-0.1.0/src/graphe_sdk/config.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+@dataclass
+class GrapheConfig:
+    base_url: str
+    api_key: str
+    workspace_id: str | None = None
+    project_id: str | None = None
+    actor_id: str | None = None
+
+    @classmethod
+    def from_env(cls, *, config_path: str | Path | None = None) -> GrapheConfig:
+        file_values = _load_config_file(config_path) if config_path else _load_default_config_file()
+        return cls(
+            base_url=_env_or_file("GRAPHE_API_BASE", file_values, "base_url", "http://localhost:8000"),
+            api_key=_env_or_file("GRAPHE_API_KEY", file_values, "api_key", ""),
+            workspace_id=_env_or_file("GRAPHE_WORKSPACE_ID", file_values, "workspace_id"),
+            project_id=_env_or_file("GRAPHE_PROJECT_ID", file_values, "project_id"),
+            actor_id=_env_or_file("GRAPHE_ACTOR_ID", file_values, "actor_id"),
+        )
+
+    def require_scope(self) -> tuple[str, str]:
+        if not self.workspace_id or not self.project_id:
+            raise ValueError(
+                "workspace_id and project_id are required. Set GRAPHE_WORKSPACE_ID and "
+                "GRAPHE_PROJECT_ID or pass --workspace / --project."
+            )
+        return self.workspace_id, self.project_id
+
+
+def _load_default_config_file() -> dict[str, Any]:
+    for path in (Path.home() / ".config" / "graphe" / "config.toml", Path.cwd() / "graphe.toml"):
+        if path.is_file():
+            return _load_config_file(path)
+    return {}
+
+
+def _load_config_file(path: str | Path) -> dict[str, Any]:
+    data = tomllib.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        return {}
+    return data
+
+
+def _env_or_file(
+    env_name: str,
+    file_values: dict[str, Any],
+    key: str,
+    default: str | None = None,
+) -> str | None:
+    env_value = os.environ.get(env_name)
+    if env_value:
+        return env_value
+    file_value = file_values.get(key)
+    if file_value is not None:
+        return str(file_value)
+    return default

graphe_sdk-0.1.0/src/graphe_sdk/instrument.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from contextlib import AbstractContextManager
+from datetime import datetime, timezone
+from typing import Any, Callable, TypeVar
+from uuid import UUID
+
+from graphe_sdk.client import GrapheClient
+
+T = TypeVar("T")
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _args_hash(args: tuple[Any, ...], kwargs: dict[str, Any]) -> str:
+    blob = json.dumps({"args": args, "kwargs": kwargs}, default=str, sort_keys=True)
+    return hashlib.sha256(blob.encode()).hexdigest()[:16]
+
+
+class GrapheRun(AbstractContextManager["GrapheRun"]):
+    """Context manager that creates a run and logs lifecycle events."""
+
+    def __init__(
+        self,
+        client: GrapheClient,
+        *,
+        workspace_id: str,
+        project_id: str,
+        actor_id: str,
+        goal: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.client = client
+        self.workspace_id = workspace_id
+        self.project_id = project_id
+        self.actor_id = actor_id
+        self.goal = goal
+        self.metadata = metadata or {}
+        self.run_id: str | None = None
+        self._terminal_logged = False
+
+    def __enter__(self) -> GrapheRun:
+        response = self.client.create_run(
+            {
+                "workspace_id": self.workspace_id,
+                "project_id": self.project_id,
+                "actor_id": self.actor_id,
+                "goal": self.goal,
+                "started_at": _utc_now(),
+                "status": "started",
+                "metadata": self.metadata,
+            }
+        )
+        self.run_id = str(response["run_id"])
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._terminal_logged or not self.run_id:
+            return
+        if exc_type is not None:
+            self.end_failed(summary=str(exc), error_type=exc_type.__name__ if exc_type else "Error")
+        else:
+            self.end_completed(summary=f"Run completed: {self.goal}")
+
+    def _base_event(self, event_type: str, payload: dict[str, Any], *, idempotency_key: str | None = None) -> dict[str, Any]:
+        if not self.run_id:
+            raise RuntimeError("GrapheRun is not active; use as context manager.")
+        body: dict[str, Any] = {
+            "workspace_id": self.workspace_id,
+            "project_id": self.project_id,
+            "actor_id": self.actor_id,
+            "run_id": self.run_id,
+            "event_type": event_type,
+            "occurred_at": _utc_now(),
+            "payload": payload,
+        }
+        if idempotency_key:
+            body["idempotency_key"] = idempotency_key
+        return body
+
+    def log_event(self, event_type: str, payload: dict[str, Any], *, idempotency_key: str | None = None) -> dict[str, Any]:
+        return self.client.log_event(self._base_event(event_type, payload, idempotency_key=idempotency_key))
+
+    def log_tool(
+        self,
+        tool_name: str,
+        fn: Callable[[], T],
+        *,
+        summary: str | None = None,
+    ) -> T:
+        key = f"{self.run_id}:tool:{tool_name}"
+        try:
+            result = fn()
+            self.log_event(
+                "tool.invoked",
+                {
+                    "summary": summary or f"{tool_name} succeeded",
+                    "tool_name": tool_name,
+                    "args_hash": key,
+                },
+                idempotency_key=f"{key}:ok",
+            )
+            return result
+        except Exception as exc:
+            self.log_event(
+                "tool.failed",
+                {
+                    "summary": summary or f"{tool_name} failed",
+                    "tool_name": tool_name,
+                    "error_type": type(exc).__name__,
+                    "args_hash": key,
+                },
+                idempotency_key=f"{key}:fail",
+            )
+            raise
+
+    def log_api(
+        self,
+        service: str,
+        method: str,
+        endpoint: str,
+        *,
+        status_code: int,
+        latency_ms: float | None = None,
+        summary: str | None = None,
+        error_code: str | None = None,
+    ) -> dict[str, Any]:
+        failed = status_code >= 400
+        event_type = "api.request.failed" if failed else "api.request.completed"
+        payload = {
+            "summary": summary or f"{method} {endpoint} -> {status_code}",
+            "service": service,
+            "method": method,
+            "endpoint": endpoint,
+            "status_code": status_code,
+        }
+        if latency_ms is not None:
+            payload["latency_ms"] = latency_ms
+        if error_code:
+            payload["error_code"] = error_code
+        key = f"{self.run_id}:api:{service}:{method}:{endpoint}:{status_code}"
+        return self.log_event(event_type, payload, idempotency_key=key)
+
+    def with_context_used(self, query: str, items: list[dict[str, Any]]) -> dict[str, Any]:
+        return {"query": query, "items": items}
+
+    def end_completed(self, summary: str) -> dict[str, Any]:
+        self._terminal_logged = True
+        return self.log_event("run.completed", {"summary": summary, "status": "completed"}, idempotency_key=f"{self.run_id}:completed")
+
+    def end_failed(self, summary: str, *, error_type: str = "RunFailed") -> dict[str, Any]:
+        self._terminal_logged = True
+        return self.log_event(
+            "run.failed",
+            {"summary": summary, "status": "failed", "error_type": error_type},
+            idempotency_key=f"{self.run_id}:failed",
+        )
+
+
+def start_run(
+    client: GrapheClient,
+    *,
+    workspace_id: str,
+    project_id: str,
+    actor_id: str,
+    goal: str,
+    metadata: dict[str, Any] | None = None,
+) -> GrapheRun:
+    return GrapheRun(
+        client,
+        workspace_id=workspace_id,
+        project_id=project_id,
+        actor_id=actor_id,
+        goal=goal,
+        metadata=metadata,
+    )

graphe_sdk-0.1.0/src/graphe_sdk/output.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Iterable, Mapping, Sequence
+
+
+def emit(data: Any, *, output: str = "json", stream: Any = None) -> None:
+    target = stream or sys.stdout
+    if output == "json":
+        json.dump(data, target, indent=2, default=str)
+        target.write("\n")
+        return
+    if isinstance(data, Mapping):
+        for key, value in data.items():
+            target.write(f"{key}: {value}\n")
+        return
+    if isinstance(data, Sequence) and not isinstance(data, (str, bytes)):
+        for row in data:
+            if isinstance(row, Mapping):
+                target.write("  ".join(f"{k}={v}" for k, v in row.items()) + "\n")
+            else:
+                target.write(f"{row}\n")
+        return
+    target.write(f"{data}\n")
+
+
+def print_table(
+    rows: Iterable[Mapping[str, Any]],
+    columns: Sequence[str],
+    *,
+    stream: Any = None,
+) -> None:
+    target = stream or sys.stdout
+    materialized = list(rows)
+    if not materialized:
+        target.write("(no rows)\n")
+        return
+    widths = {column: len(column) for column in columns}
+    for row in materialized:
+        for column in columns:
+            widths[column] = max(widths[column], len(str(row.get(column, ""))))
+    header = "  ".join(column.ljust(widths[column]) for column in columns)
+    target.write(header + "\n")
+    target.write("  ".join("-" * widths[column] for column in columns) + "\n")
+    for row in materialized:
+        target.write("  ".join(str(row.get(column, "")).ljust(widths[column]) for column in columns) + "\n")

graphe_sdk-0.1.0/src/graphe_sdk.egg-info/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: graphe-sdk
+Version: 0.1.0
+Summary: Python SDK for the Graphe Layer 1 world-state API
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: respx>=0.21.0; extra == "dev"
+
+# graphe-sdk
+
+Python client for the [Graphe](https://github.com/) Layer 1 API.
+
+```bash
+pip install graphe-sdk
+```
+
+```python
+from graphe_sdk import GrapheClient, GrapheConfig
+
+config = GrapheConfig.from_env()
+client = GrapheClient(config.base_url, config.api_key)
+print(client.get_health())
+```
+
+See the monorepo `API.md` for endpoint contracts.

graphe_sdk-0.1.0/src/graphe_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/graphe_sdk/__init__.py
+src/graphe_sdk/client.py
+src/graphe_sdk/config.py
+src/graphe_sdk/instrument.py
+src/graphe_sdk/output.py
+src/graphe_sdk.egg-info/PKG-INFO
+src/graphe_sdk.egg-info/SOURCES.txt
+src/graphe_sdk.egg-info/dependency_links.txt
+src/graphe_sdk.egg-info/requires.txt
+src/graphe_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_config.py
+tests/test_health.py
+tests/test_instrument.py

graphe_sdk-0.1.0/src/graphe_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

graphe_sdk-0.1.0/src/graphe_sdk.egg-info/requires.txt

@@ -0,0 +1,5 @@
+httpx>=0.27.0
+
+[dev]
+pytest>=8.0.0
+respx>=0.21.0

graphe_sdk-0.1.0/src/graphe_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+graphe_sdk

graphe_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,50 @@
+import httpx
+
+from graphe_sdk import AuthError, ConflictError, GrapheClient, NotFoundError
+
+
+class MockTransport:
+    def __init__(self, status_code=200, payload=None):
+        self.status_code = status_code
+        self.payload = payload or {"ok": True}
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        assert request.headers["x-api-key"] == "key"
+        return httpx.Response(self.status_code, json=self.payload, request=request)
+
+
+def test_log_event_sends_api_key(monkeypatch) -> None:
+    transport = httpx.MockTransport(MockTransport(payload={"event_id": "1", "status": "accepted"}))
+    monkeypatch.setattr(httpx, "request", httpx.Client(transport=transport).request)
+    client = GrapheClient("http://test", "key")
+    assert client.log_event({"payload": {}})["status"] == "accepted"
+
+
+def test_list_runs_builds_query(monkeypatch) -> None:
+    observed: dict[str, object] = {}
+
+    def capture_request(method, url, **kwargs):
+        observed["method"] = method
+        observed["url"] = url
+        observed["params"] = kwargs.get("params")
+        return httpx.Response(200, json={"runs": []}, request=httpx.Request(method, url))
+
+    monkeypatch.setattr(httpx, "request", capture_request)
+    client = GrapheClient("http://test", "key")
+    client.list_runs(workspace_id="w", project_id="p", limit=5)
+    assert observed["method"] == "GET"
+    assert observed["url"] == "http://test/api/v1/runs"
+    assert observed["params"] == {"workspace_id": "w", "project_id": "p", "limit": 5}
+
+
+def test_typed_errors(monkeypatch) -> None:
+    for status, error_type in [(401, AuthError), (404, NotFoundError), (409, ConflictError)]:
+        transport = httpx.MockTransport(MockTransport(status_code=status, payload={"detail": "bad"}))
+        monkeypatch.setattr(httpx, "request", httpx.Client(transport=transport).request)
+        client = GrapheClient("http://test", "key")
+        try:
+            client.get_run("missing")
+        except error_type:
+            pass
+        else:
+            raise AssertionError(f"expected {error_type.__name__}")

graphe_sdk-0.1.0/tests/test_config.py

@@ -0,0 +1,29 @@
+import os
+
+from graphe_sdk.config import GrapheConfig
+
+
+def test_from_env_reads_graphe_variables(monkeypatch) -> None:
+    monkeypatch.setenv("GRAPHE_API_BASE", "http://api.test")
+    monkeypatch.setenv("GRAPHE_API_KEY", "secret")
+    monkeypatch.setenv("GRAPHE_WORKSPACE_ID", "ws-1")
+    monkeypatch.setenv("GRAPHE_PROJECT_ID", "proj-1")
+    monkeypatch.setenv("GRAPHE_ACTOR_ID", "actor-1")
+    config = GrapheConfig.from_env()
+    assert config.base_url == "http://api.test"
+    assert config.api_key == "secret"
+    assert config.workspace_id == "ws-1"
+    assert config.project_id == "proj-1"
+    assert config.actor_id == "actor-1"
+
+
+def test_require_scope_raises_when_missing(monkeypatch) -> None:
+    monkeypatch.delenv("GRAPHE_WORKSPACE_ID", raising=False)
+    monkeypatch.delenv("GRAPHE_PROJECT_ID", raising=False)
+    config = GrapheConfig.from_env()
+    try:
+        config.require_scope()
+    except ValueError as exc:
+        assert "workspace_id" in str(exc)
+    else:
+        raise AssertionError("expected ValueError")

graphe_sdk-0.1.0/tests/test_health.py

@@ -0,0 +1,27 @@
+import httpx
+
+from graphe_sdk import GrapheClient
+
+
+def test_get_health(monkeypatch) -> None:
+    def capture_request(method, url, **kwargs):
+        assert method == "GET"
+        assert url == "http://test/api/v1/health"
+        return httpx.Response(200, json={"status": "ok"}, request=httpx.Request(method, url))
+
+    monkeypatch.setattr(httpx, "request", capture_request)
+    client = GrapheClient("http://test", "key")
+    assert client.get_health()["status"] == "ok"
+
+
+def test_hybrid_search_mode_query(monkeypatch) -> None:
+    observed: dict[str, object] = {}
+
+    def capture_request(method, url, **kwargs):
+        observed["url"] = url
+        return httpx.Response(200, json={"results": []}, request=httpx.Request(method, url))
+
+    monkeypatch.setattr(httpx, "request", capture_request)
+    client = GrapheClient("http://test", "key")
+    client.hybrid_search({"query": "auth"}, mode="graph_first")
+    assert observed["url"] == "http://test/api/v1/search/hybrid?mode=graph_first"

graphe_sdk-0.1.0/tests/test_instrument.py

@@ -0,0 +1,29 @@
+import httpx
+
+from graphe_sdk import GrapheClient
+from graphe_sdk.instrument import GrapheRun
+
+
+class Recorder:
+    def __init__(self):
+        self.calls: list[tuple[str, dict]] = []
+
+    def create_run(self, payload):
+        self.calls.append(("create_run", payload))
+        return {"run_id": "run-1", "status": "started"}
+
+    def log_event(self, payload):
+        self.calls.append(("log_event", payload))
+        return {"event_id": f"e-{len(self.calls)}", "status": "accepted"}
+
+
+def test_graphe_run_logs_tool_and_terminal() -> None:
+    recorder = Recorder()
+    client = GrapheClient("http://test", "key")
+    client.create_run = recorder.create_run  # type: ignore[method-assign]
+    client.log_event = recorder.log_event  # type: ignore[method-assign]
+    with GrapheRun(client, workspace_id="w", project_id="p", actor_id="a", goal="demo") as run:
+        run.log_tool("fetch", lambda: "ok", summary="fetched")
+    event_types = [call[1]["event_type"] for call in recorder.calls if call[0] == "log_event"]
+    assert "tool.invoked" in event_types
+    assert "run.completed" in event_types