usegradient 1.3.1__py3-none-any.whl

gradient_sdk/client.py

@@ -0,0 +1,1059 @@
+from __future__ import annotations
+
+from dataclasses import asdict, is_dataclass
+from typing import Any, Callable, Mapping
+from urllib.error import HTTPError, URLError
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+from urllib.parse import quote
+from urllib.request import Request, urlopen
+import json
+import re
+import time
+
+from .credentials import Credentials, load_credentials
+from .errors import GradientAPIError, GradientAuthError, GradientError
+from .models import (
+    AppSecret,
+    CreateMachineResponse,
+    ExecMachineResponse,
+    Guest,
+    MachineCreateRequest,
+    MachineListItem,
+    MachineSpec,
+    Restart,
+    ServiceConfig,
+    CreateTraceRunResponse,
+    ReplayTraceRunResponse,
+    TraceEvent,
+    TraceRun,
+    TraceSpan,
+    WhoamiResponse,
+    to_payload,
+)
+
+Transport = Callable[[Request, float], Any]
+
+
+class GradientClient:
+    """Synchronous client for the Gradient console API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        api_url: str = "https://console.usegradient.dev",
+        proxy_url: str = "",
+        slug: str = "",
+        timeout: float = 90.0,
+        transport: Transport | None = None,
+    ) -> None:
+        if not api_key:
+            raise GradientAuthError(
+                "missing API key. Set GRADIENT_API_KEY or run `gradient login --api-key grad_live_...`."
+            )
+        self.api_key = api_key
+        self.api_url = api_url.rstrip("/")
+        self.proxy_url_base = proxy_url.rstrip("/")
+        self.slug = slug
+        self.timeout = timeout
+        self.last_server_timing = ""
+        self._transport = transport
+
+    @classmethod
+    def from_credentials(
+        cls,
+        *,
+        path: str | None = None,
+        timeout: float = 90.0,
+        transport: Transport | None = None,
+    ) -> "GradientClient":
+        credentials = load_credentials(path=path, require_api_key=True)
+        return cls.from_loaded_credentials(credentials, timeout=timeout, transport=transport)
+
+    @classmethod
+    def from_loaded_credentials(
+        cls,
+        credentials: Credentials,
+        *,
+        timeout: float = 90.0,
+        transport: Transport | None = None,
+    ) -> "GradientClient":
+        return cls(
+            credentials.api_key,
+            api_url=credentials.api_url,
+            proxy_url=credentials.proxy_url,
+            slug=credentials.slug,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def whoami(self) -> WhoamiResponse:
+        data = self._call("GET", "/api/v1/whoami")
+        who = WhoamiResponse.from_dict(data)
+        if who.proxy_url:
+            self.proxy_url_base = who.proxy_url.rstrip("/")
+        if who.slug:
+            self.slug = who.slug
+        return who
+
+    def ensure_routable(self) -> None:
+        self._call("POST", "/api/v1/apps/ensure-routable", {})
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        return list(self._call("GET", "/api/v1/projects"))
+
+    def ensure_project(self, name: str, *, display_name: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name}
+        if display_name is not None:
+            body["display_name"] = display_name
+        return dict(self._call("POST", "/api/v1/projects", body))
+
+    def resolve_environment(
+        self,
+        *,
+        project: str,
+        environment: Mapping[str, Any] | None = None,
+        source: Mapping[str, Any] | None = None,
+        display_name: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "project": project,
+            "environment": dict(environment or {}),
+            "source": dict(source or {}),
+        }
+        if display_name is not None:
+            body["display_name"] = display_name
+        return dict(self._call("POST", "/api/v1/environments", body))
+
+    def list_environment_versions(self, *, project: str | None = None) -> list[dict[str, Any]]:
+        suffix = f"?project={quote(project, safe='')}" if project else ""
+        return list(self._call("GET", f"/api/v1/environments{suffix}"))
+
+    def list_deployments(self) -> list[dict[str, Any]]:
+        return list(self._call("GET", "/api/v1/deployments"))
+
+    def create_deployment(
+        self,
+        *,
+        name: str,
+        project: str,
+        template: Mapping[str, Any],
+        environment_version_id: str | None = None,
+        trace_mode: str = "full",
+        capture_policy: Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        min_machines: int = 1,
+        max_machines: int = 1,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "name": name,
+            "project": project,
+            "environment_version_id": environment_version_id,
+            "template": dict(template),
+            "trace_mode": trace_mode,
+            "metadata": dict(metadata or {}),
+            "scaling": {
+                "min_machines": min_machines,
+                "max_machines": max_machines,
+            },
+        }
+        if capture_policy is not None:
+            body["capture_policy"] = dict(capture_policy)
+        return dict(
+            self._call(
+                "POST",
+                "/api/v1/deployments",
+                body,
+            )
+        )
+
+    def get_deployment(self, name: str) -> dict[str, Any]:
+        return dict(self._call("GET", f"/api/v1/deployments/{quote(name, safe='')}"))
+
+    def start_deployment(self, name: str) -> dict[str, Any]:
+        return dict(
+            self._call("PATCH", f"/api/v1/deployments/{quote(name, safe='')}", {"action": "start"})
+        )
+
+    def stop_deployment(self, name: str) -> dict[str, Any]:
+        return dict(
+            self._call("PATCH", f"/api/v1/deployments/{quote(name, safe='')}", {"action": "stop"})
+        )
+
+    def scale_deployment(self, name: str, machines: int) -> dict[str, Any]:
+        return dict(
+            self._call(
+                "PATCH",
+                f"/api/v1/deployments/{quote(name, safe='')}",
+                {"action": "scale", "machines": machines},
+            )
+        )
+
+    def delete_deployment(self, name: str) -> dict[str, Any]:
+        return dict(self._call("DELETE", f"/api/v1/deployments/{quote(name, safe='')}"))
+
+    def create_machine(self, template: MachineCreateRequest | Mapping[str, Any]) -> CreateMachineResponse:
+        data = self._call("POST", "/api/v1/machines", _payload(template))
+        return CreateMachineResponse.from_dict(data)
+
+    def create_traced_machine(
+        self,
+        template: MachineCreateRequest | Mapping[str, Any],
+        *,
+        machine_template: MachineCreateRequest | Mapping[str, Any] | None = None,
+        trace_mode: str = "full",
+        capture_policy: Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        wait: bool = False,
+        wait_timeout_seconds: int = 30,
+    ) -> dict[str, Any]:
+        """Create a trace run, inject trace env vars, cold-create a machine, and attach the run."""
+
+        trace = self.create_trace_run(
+            trace_mode=trace_mode,
+            template=template,
+            metadata=metadata,
+            capture_policy=capture_policy,
+        )
+        traced_template = self.trace_template(machine_template or template, trace)
+        machine = self.create_machine(traced_template)
+        if wait:
+            self.wait_machine_state(machine.id, timeout_seconds=wait_timeout_seconds)
+        full_proxy_url = self.proxy_url(
+            machine.id,
+            slug=machine.slug,
+            proxy_base=machine.proxy_url,
+            proxy_session_token=machine.proxy_session_token,
+        )
+        attached = self.attach_trace_run(
+            trace.id,
+            machine_id=machine.id,
+            proxy_url=full_proxy_url,
+            status="active",
+        )
+        return {
+            "machine": asdict(machine),
+            "trace_run": asdict(attached),
+            "ingest_token": trace.ingest_token,
+            "ingest_url": trace.ingest_url,
+            "full_proxy_url": full_proxy_url,
+        }
+
+    def replay_machine(
+        self,
+        parent_run_id: str,
+        *,
+        trace_mode: str | None = None,
+        replay_config: Mapping[str, Any] | None = None,
+        capture_policy: Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        wait: bool = False,
+        wait_timeout_seconds: int = 30,
+    ) -> dict[str, Any]:
+        """Fork a prior trace run into a fresh sandbox and re-run it.
+
+        Re-creates the parent run's machine template, injects trace and
+        GRADIENT_REPLAY_* env vars (seed, frozen clock, dataset, egress mode),
+        cold-creates a machine, and attaches the linked child run.
+        """
+
+        replay = self.replay_trace_run(
+            parent_run_id,
+            trace_mode=trace_mode,
+            replay_config=replay_config,
+            capture_policy=capture_policy,
+            metadata=metadata,
+        )
+        if not replay.template:
+            raise GradientError(
+                "parent run has no machine template to replay; only runs created "
+                "with `gradient up --trace` can be forked."
+            )
+        template = self.trace_template(replay.template, replay)
+        template = _with_replay_env(template, replay.replay_config)
+        machine = self.create_machine(template)
+        if wait:
+            self.wait_machine_state(machine.id, timeout_seconds=wait_timeout_seconds)
+        full_proxy_url = self.proxy_url(
+            machine.id,
+            slug=machine.slug,
+            proxy_base=machine.proxy_url,
+            proxy_session_token=machine.proxy_session_token,
+        )
+        attached = self.attach_trace_run(
+            replay.id,
+            machine_id=machine.id,
+            proxy_url=full_proxy_url,
+            status="active",
+        )
+        return {
+            "machine": asdict(machine),
+            "trace_run": asdict(attached),
+            "parent_run_id": parent_run_id,
+            "replay_config": replay.replay_config,
+            "ingest_token": replay.ingest_token,
+            "ingest_url": replay.ingest_url,
+            "full_proxy_url": full_proxy_url,
+        }
+
+    def list_machines(self) -> list[MachineListItem]:
+        data = self._call("GET", "/api/v1/machines")
+        return [MachineListItem.from_dict(item) for item in data]
+
+    def delete_machine(self, machine_id: str) -> None:
+        if not machine_id:
+            raise ValueError("machine_id is required")
+        self._call("DELETE", f"/api/v1/machines/{machine_id}")
+
+    def exec_machine(
+        self,
+        machine_id: str,
+        command: list[str],
+        *,
+        stdin: str | None = None,
+        timeout_seconds: int = 60,
+        trace: bool = True,
+        watch: list[str] | None = None,
+    ) -> ExecMachineResponse:
+        if not machine_id:
+            raise ValueError("machine_id is required")
+        if not command:
+            raise ValueError("command is required")
+        body = {
+            "command": command,
+            "timeout": timeout_seconds,
+            "trace": trace,
+            "watch": watch or [],
+        }
+        if stdin is not None:
+            body["stdin"] = stdin
+        data = self._call("POST", f"/api/v1/machines/{machine_id}/exec", body)
+        return ExecMachineResponse.from_dict(data)
+
+    def list_secrets(self) -> list[AppSecret]:
+        data = self._call("GET", "/api/v1/secrets")
+        return [AppSecret.from_dict(item) for item in data]
+
+    def update_secrets(self, values: Mapping[str, str | None]) -> list[AppSecret]:
+        if not values:
+            raise ValueError("values must not be empty")
+        data = self._call("POST", "/api/v1/secrets", {"values": dict(values)})
+        return [AppSecret.from_dict(item) for item in data]
+
+    def set_secret(self, name: str, value: str) -> list[AppSecret]:
+        return self.update_secrets({name: value})
+
+    def unset_secret(self, name: str) -> list[AppSecret]:
+        return self.update_secrets({name: None})
+
+    def wait_machine_state(
+        self,
+        machine_id: str,
+        *,
+        state: str = "started",
+        timeout_seconds: int = 30,
+    ) -> None:
+        if state not in {"started", "stopped", "destroyed", "suspended"}:
+            raise ValueError("state must be started, stopped, destroyed, or suspended")
+        deadline = time.monotonic() + timeout_seconds
+        last_error: GradientAPIError | None = None
+        while time.monotonic() < deadline:
+            remaining = max(1, min(60, int(deadline - time.monotonic())))
+            query = urlencode({"state": state, "timeout": remaining})
+            try:
+                self._call("GET", f"/api/v1/machines/{machine_id}/wait?{query}")
+                return
+            except GradientAPIError as exc:
+                last_error = exc
+                if exc.status != 408:
+                    raise
+        if last_error is not None:
+            raise last_error
+        raise GradientError(f"timed out waiting for {machine_id} to reach {state}")
+
+    def create_trace_run(
+        self,
+        *,
+        trace_mode: str = "proxy",
+        template: MachineCreateRequest | Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        capture_policy: Mapping[str, Any] | None = None,
+    ) -> CreateTraceRunResponse:
+        body: dict[str, Any] = {"trace_mode": trace_mode}
+        if template is not None:
+            body["template"] = _payload(template)
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        if capture_policy is not None:
+            body["capture_policy"] = dict(capture_policy)
+        data = self._call("POST", "/api/v1/runs", body)
+        return CreateTraceRunResponse.from_dict(data)
+
+    def replay_trace_run(
+        self,
+        parent_run_id: str,
+        *,
+        trace_mode: str | None = None,
+        replay_config: Mapping[str, Any] | None = None,
+        capture_policy: Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> ReplayTraceRunResponse:
+        if not parent_run_id:
+            raise ValueError("parent_run_id is required")
+        body: dict[str, Any] = {}
+        if trace_mode is not None:
+            body["trace_mode"] = trace_mode
+        if replay_config is not None:
+            body["replay_config"] = dict(replay_config)
+        if capture_policy is not None:
+            body["capture_policy"] = dict(capture_policy)
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        data = self._call("POST", f"/api/v1/runs/{parent_run_id}/replay", body)
+        return ReplayTraceRunResponse.from_dict(data)
+
+    def attach_trace_run(
+        self,
+        run_id: str,
+        *,
+        machine_id: str,
+        proxy_url: str | None = None,
+        status: str = "active",
+    ) -> TraceRun:
+        body = {
+            "action": "attach",
+            "machine_id": machine_id,
+            "proxy_url": proxy_url,
+            "status": status,
+        }
+        data = self._call("PATCH", f"/api/v1/runs/{run_id}", body)
+        return TraceRun.from_dict(data)
+
+    def finish_trace_run(self, run_id: str) -> TraceRun:
+        data = self._call("PATCH", f"/api/v1/runs/{run_id}", {"action": "finish"})
+        return TraceRun.from_dict(data)
+
+    def update_trace_policy(
+        self,
+        run_id: str,
+        capture_policy: Mapping[str, Any],
+    ) -> TraceRun:
+        data = self._call(
+            "PATCH",
+            f"/api/v1/runs/{run_id}",
+            {"action": "policy", "capture_policy": dict(capture_policy)},
+        )
+        return TraceRun.from_dict(data)
+
+    def delete_trace_run(self, run_id: str) -> None:
+        self._call("DELETE", f"/api/v1/runs/{run_id}")
+
+    def get_trace_run(self, run_id: str) -> TraceRun:
+        data = self._call("GET", f"/api/v1/runs/{run_id}")
+        return TraceRun.from_dict(data)
+
+    def list_trace_runs(self, *, limit: int = 50) -> list[TraceRun]:
+        data = self._call("GET", f"/api/v1/runs?limit={limit}")
+        return [TraceRun.from_dict(item) for item in data]
+
+    def list_trace_events(self, run_id: str, *, limit: int = 1000) -> list[TraceEvent]:
+        data = self._call("GET", f"/api/v1/runs/{run_id}/events?limit={limit}")
+        return [TraceEvent.from_dict(item) for item in data]
+
+    def list_trace_spans(
+        self,
+        run_id: str,
+        *,
+        kind: str | None = None,
+        status: str | None = None,
+        project: str | None = None,
+        session_id: str | None = None,
+        query: str | None = None,
+        limit: int | None = None,
+    ) -> list[TraceSpan]:
+        params = {
+            key: value
+            for key, value in {
+                "kind": kind,
+                "status": status,
+                "project": project,
+                "session_id": session_id,
+                "q": query,
+                "limit": limit,
+            }.items()
+            if value is not None
+        }
+        suffix = f"?{urlencode(params)}" if params else ""
+        data = self._call("GET", f"/api/v1/runs/{run_id}/spans{suffix}")
+        return [TraceSpan.from_dict(item) for item in data]
+
+    def list_trace_sessions(
+        self,
+        *,
+        limit: int = 100,
+        query: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"limit": limit}
+        if query:
+            params["q"] = query
+        return list(self._call("GET", f"/api/v1/sessions?{urlencode(params)}"))
+
+    def list_session_spans(self, session_id: str) -> list[TraceSpan]:
+        data = self._call(
+            "GET",
+            f"/api/v1/sessions/{quote(session_id, safe='')}/spans",
+        )
+        return [TraceSpan.from_dict(item) for item in data]
+
+    def trace_metrics(self, *, days: int = 30) -> dict[str, Any]:
+        return dict(self._call("GET", f"/api/v1/metrics?days={days}"))
+
+    def query_traces(self, sql: str, *, limit: int = 100) -> dict[str, Any]:
+        if not sql or not sql.strip():
+            raise ValueError("sql is required")
+        return dict(
+            self._call(
+                "POST",
+                "/api/v1/traces/query",
+                {"sql": sql, "limit": limit},
+            )
+        )
+
+    def create_trace_annotation(
+        self,
+        *,
+        name: str,
+        value: Any,
+        run_id: str | None = None,
+        span_id: str | None = None,
+        trace_id: str | None = None,
+        source: str | None = None,
+        annotator: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name, "value": value}
+        for key, item in {
+            "run_id": run_id,
+            "span_id": span_id,
+            "trace_id": trace_id,
+            "source": source,
+            "annotator": annotator,
+        }.items():
+            if item is not None:
+                body[key] = item
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        return dict(self._call("POST", "/api/v1/annotations", body))
+
+    def list_trace_annotations(
+        self,
+        *,
+        run_id: str | None = None,
+        span_id: str | None = None,
+        trace_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params = {
+            key: value
+            for key, value in {
+                "run_id": run_id,
+                "span_id": span_id,
+                "trace_id": trace_id,
+            }.items()
+            if value is not None
+        }
+        suffix = f"?{urlencode(params)}" if params else ""
+        return list(self._call("GET", f"/api/v1/annotations{suffix}"))
+
+    def delete_trace_annotation(self, annotation_id: str) -> None:
+        self._call("DELETE", f"/api/v1/annotations/{annotation_id}")
+
+    def create_dataset(
+        self,
+        name: str,
+        *,
+        description: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name}
+        if description is not None:
+            body["description"] = description
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        return dict(self._call("POST", "/api/v1/datasets", body))
+
+    def list_datasets(self) -> list[dict[str, Any]]:
+        return list(self._call("GET", "/api/v1/datasets"))
+
+    def get_dataset(self, dataset_id: str) -> dict[str, Any]:
+        return dict(self._call("GET", f"/api/v1/datasets/{dataset_id}"))
+
+    def delete_dataset(self, dataset_id: str) -> None:
+        self._call("DELETE", f"/api/v1/datasets/{dataset_id}")
+
+    def add_dataset_example(
+        self,
+        dataset_id: str,
+        *,
+        input: Any | None = None,
+        expected_output: Any | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        split: str | None = None,
+        source_span_id: str | None = None,
+        source_trace_id: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        for key, item in {
+            "input": input,
+            "expected_output": expected_output,
+            "split": split,
+            "source_span_id": source_span_id,
+            "source_trace_id": source_trace_id,
+        }.items():
+            if item is not None:
+                body[key] = item
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        return dict(
+            self._call(
+                "POST",
+                f"/api/v1/datasets/{dataset_id}/examples",
+                body,
+            )
+        )
+
+    def list_dataset_examples(self, dataset_id: str) -> list[dict[str, Any]]:
+        return list(
+            self._call("GET", f"/api/v1/datasets/{dataset_id}/examples")
+        )
+
+    def delete_dataset_example(self, dataset_id: str, example_id: str) -> None:
+        self._call(
+            "DELETE",
+            f"/api/v1/datasets/{dataset_id}/examples/{example_id}",
+        )
+
+    def create_experiment(
+        self,
+        *,
+        dataset_id: str,
+        name: str,
+        description: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"dataset_id": dataset_id, "name": name}
+        if description is not None:
+            body["description"] = description
+        if metadata is not None:
+            body["metadata"] = dict(metadata)
+        return dict(self._call("POST", "/api/v1/experiments", body))
+
+    def list_experiments(self) -> list[dict[str, Any]]:
+        return list(self._call("GET", "/api/v1/experiments"))
+
+    def get_experiment(self, experiment_id: str) -> dict[str, Any]:
+        return dict(self._call("GET", f"/api/v1/experiments/{experiment_id}"))
+
+    def update_experiment_status(self, experiment_id: str, status: str) -> None:
+        self._call(
+            "PATCH",
+            f"/api/v1/experiments/{experiment_id}",
+            {"status": status},
+        )
+
+    def create_experiment_run(
+        self,
+        experiment_id: str,
+        *,
+        name: str,
+        config: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return dict(
+            self._call(
+                "POST",
+                f"/api/v1/experiments/{experiment_id}/runs",
+                {"name": name, "config": dict(config or {})},
+            )
+        )
+
+    def record_experiment_results(
+        self,
+        experiment_id: str,
+        run_id: str,
+        results: list[Mapping[str, Any]],
+    ) -> int:
+        data = self._call(
+            "POST",
+            f"/api/v1/experiments/{experiment_id}/runs/{run_id}/results",
+            {"results": [dict(result) for result in results]},
+        )
+        return int(data.get("inserted", 0))
+
+    def update_experiment_run_status(
+        self,
+        experiment_id: str,
+        run_id: str,
+        status: str,
+    ) -> dict[str, Any]:
+        return dict(
+            self._call(
+                "PATCH",
+                f"/api/v1/experiments/{experiment_id}/runs/{run_id}",
+                {"status": status},
+            )
+        )
+
+    def run_experiment(
+        self,
+        dataset_id: str,
+        *,
+        task: Callable[[Any, Mapping[str, Any]], Any],
+        evaluators: Mapping[str, Callable[[Mapping[str, Any]], Any]] | None = None,
+        experiment_id: str | None = None,
+        name: str = "Experiment",
+        variant: str = "candidate",
+        config: Mapping[str, Any] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        batch_size: int = 50,
+    ) -> dict[str, Any]:
+        dataset = self.get_dataset(dataset_id)
+        experiment = (
+            {"id": experiment_id}
+            if experiment_id
+            else self.create_experiment(
+                dataset_id=dataset_id,
+                name=name,
+                metadata=metadata,
+            )
+        )
+        run = self.create_experiment_run(
+            str(experiment["id"]),
+            name=variant,
+            config=config,
+        )
+        pending: list[dict[str, Any]] = []
+        try:
+            for example in dataset.get("examples", []):
+                started = time.perf_counter()
+                try:
+                    raw = task(example.get("input"), example)
+                    envelope = (
+                        raw
+                        if isinstance(raw, Mapping) and "output" in raw
+                        else {"output": raw}
+                    )
+                    scores: dict[str, Any] = {}
+                    for evaluator_name, evaluator in (evaluators or {}).items():
+                        scores[evaluator_name] = evaluator(
+                            {
+                                "input": example.get("input"),
+                                "output": envelope.get("output"),
+                                "expected_output": example.get("expected_output"),
+                                "metadata": example.get("metadata"),
+                                "example": example,
+                            }
+                        )
+                    result = {
+                        "dataset_example_id": example["id"],
+                        "output": envelope.get("output"),
+                        "scores": scores,
+                        "latency_ms": (time.perf_counter() - started) * 1000,
+                    }
+                    for wire_key, envelope_key in {
+                        "prompt_tokens": "prompt_tokens",
+                        "completion_tokens": "completion_tokens",
+                        "total_tokens": "total_tokens",
+                        "total_cost": "total_cost",
+                        "trace_id": "trace_id",
+                        "span_id": "span_id",
+                        "metadata": "metadata",
+                    }.items():
+                        if envelope.get(envelope_key) is not None:
+                            result[wire_key] = envelope[envelope_key]
+                    pending.append(result)
+                except Exception as error:
+                    pending.append(
+                        {
+                            "dataset_example_id": example["id"],
+                            "error": str(error),
+                            "latency_ms": (time.perf_counter() - started) * 1000,
+                        }
+                    )
+                if len(pending) >= batch_size:
+                    self.record_experiment_results(
+                        str(experiment["id"]),
+                        str(run["id"]),
+                        pending,
+                    )
+                    pending = []
+            if pending:
+                self.record_experiment_results(
+                    str(experiment["id"]),
+                    str(run["id"]),
+                    pending,
+                )
+            self.update_experiment_run_status(
+                str(experiment["id"]),
+                str(run["id"]),
+                "completed",
+            )
+            self.update_experiment_status(str(experiment["id"]), "completed")
+        except Exception:
+            self.update_experiment_run_status(
+                str(experiment["id"]),
+                str(run["id"]),
+                "failed",
+            )
+            self.update_experiment_status(str(experiment["id"]), "failed")
+            raise
+        return self.get_experiment(str(experiment["id"]))
+
+    def ingest_trace_events(
+        self,
+        run_id: str,
+        ingest_token: str,
+        events: list[Mapping[str, Any]],
+    ) -> int:
+        data = self._call(
+            "POST",
+            "/api/v1/runs/ingest",
+            {"run_id": run_id, "events": [dict(event) for event in events]},
+            auth_token=ingest_token,
+        )
+        return int(data.get("inserted", 0))
+
+    def ingest_trace_event(
+        self,
+        run_id: str,
+        ingest_token: str,
+        *,
+        event_type: str,
+        source: str = "sdk",
+        data: Mapping[str, Any] | None = None,
+        ts: str | None = None,
+        machine_id: str | None = None,
+    ) -> int:
+        event: dict[str, Any] = {
+            "source": source,
+            "type": event_type,
+            "data": dict(data or {}),
+        }
+        if ts is not None:
+            event["ts"] = ts
+        if machine_id is not None:
+            event["machineId"] = machine_id
+        return self.ingest_trace_events(run_id, ingest_token, [event])
+
+    def trace_template(
+        self,
+        template: MachineCreateRequest | Mapping[str, Any],
+        trace: CreateTraceRunResponse,
+    ) -> dict[str, Any]:
+        return _with_trace_env(template, trace, self.api_url)
+
+    def proxy_url(
+        self,
+        machine_id: str,
+        *,
+        slug: str | None = None,
+        proxy_base: str | None = None,
+        proxy_session_token: str | None = None,
+    ) -> str:
+        resolved_slug = slug or self.slug
+        resolved_proxy = (proxy_base or self.proxy_url_base).rstrip("/")
+        if not resolved_proxy or not resolved_slug:
+            raise GradientError("missing proxy URL or Gradient slug; call whoami() first")
+        raw = f"{resolved_proxy}/{resolved_slug}/{machine_id}/"
+        if not proxy_session_token:
+            return raw
+        parsed = urlparse(raw)
+        query = dict(parse_qsl(parsed.query, keep_blank_values=True))
+        query["gradient_proxy_token"] = proxy_session_token
+        return urlunparse(parsed._replace(query=urlencode(query)))
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        body: Any | None = None,
+        *,
+        auth_token: str | None = None,
+    ) -> Any:
+        raw_body: bytes | None = None
+        if body is not None:
+            raw_body = json.dumps(body).encode("utf-8")
+
+        req = Request(
+            self.api_url + path,
+            data=raw_body,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {auth_token or self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": "gradient-sdk-python/0.2.0",
+            },
+        )
+
+        status, headers, raw = self._send(req)
+        self.last_server_timing = headers.get("Server-Timing", "")
+
+        if status == 401:
+            raise GradientAuthError(
+                "unauthorized. Your API key is invalid or revoked; run `gradient login` again."
+            )
+        if status < 200 or status >= 300:
+            message = raw.decode("utf-8", errors="replace")
+            fly_request_id = None
+            try:
+                err_data = json.loads(message)
+                message = str(err_data.get("error") or message)
+                fly_request_id = err_data.get("fly_request_id")
+            except json.JSONDecodeError:
+                pass
+            raise GradientAPIError(
+                status,
+                method,
+                path,
+                message,
+                fly_request_id=fly_request_id,
+                response_body=raw.decode("utf-8", errors="replace"),
+            )
+
+        if not raw:
+            return None
+        decoded = json.loads(raw.decode("utf-8"))
+        if isinstance(decoded, Mapping) and "data" in decoded:
+            return decoded["data"]
+        return decoded
+
+    def _send(self, req: Request) -> tuple[int, Mapping[str, str], bytes]:
+        try:
+            res = self._transport(req, self.timeout) if self._transport else urlopen(req, timeout=self.timeout)
+            with res:
+                status = int(getattr(res, "status", getattr(res, "code", 0)))
+                headers = dict(res.headers.items())
+                raw = res.read()
+                return status, headers, raw
+        except HTTPError as exc:
+            headers = dict(exc.headers.items())
+            return int(exc.code), headers, exc.read()
+        except URLError as exc:
+            raise GradientError(f"failed to reach Gradient API: {exc.reason}") from exc
+
+
+def default_machine_template(
+    image: str,
+    *,
+    region: str = "sjc",
+    size: str = "shared-cpu-2x",
+    memory_mb: int = 1024,
+    env: Mapping[str, str] | None = None,
+    services: list[ServiceConfig] | list[dict[str, Any]] | None = None,
+    metadata: Mapping[str, str] | None = None,
+    project: str | None = None,
+) -> MachineCreateRequest:
+    """Create a machine template matching the Gradient CLI defaults."""
+
+    cpu_kind = "performance" if size.startswith("performance") else "shared"
+    cpus = 2
+    match = re.search(r"-(\d+)x$", size)
+    if match:
+        cpus = int(match.group(1))
+    resolved_metadata = dict(metadata or {})
+    if project:
+        resolved_metadata["project"] = project
+    return MachineCreateRequest(
+        region=region,
+        config=MachineSpec(
+            image=image,
+            guest=Guest(cpu_kind=cpu_kind, cpus=cpus, memory_mb=memory_mb),
+            env=dict(env or {}),
+            services=services or [ServiceConfig.default_https()],
+            restart=Restart(policy="no"),
+            metadata=resolved_metadata or None,
+        ),
+    )
+
+
+def _payload(value: Any) -> Any:
+    if is_dataclass(value):
+        return to_payload(asdict(value))
+    return to_payload(value)
+
+
+def _with_trace_env(
+    template: MachineCreateRequest | Mapping[str, Any],
+    trace: CreateTraceRunResponse,
+    api_url: str,
+) -> dict[str, Any]:
+    payload = _payload(template)
+    config = dict(payload.get("config", {}))
+    env = dict(config.get("env") or {})
+    env.update(
+        {
+            "GRADIENT_TRACE_RUN_ID": trace.id,
+            "GRADIENT_TRACE_TOKEN": trace.ingest_token,
+            "GRADIENT_TRACE_ENDPOINT": trace.ingest_url or api_url.rstrip("/") + "/api/v1/runs/ingest",
+            "GRADIENT_TRACE_MODE": trace.trace_mode,
+        }
+    )
+    env.setdefault(
+        "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+        api_url.rstrip("/") + "/v1/traces",
+    )
+    env.setdefault("OTEL_EXPORTER_OTLP_PROTOCOL", "http/json")
+    env["OTEL_EXPORTER_OTLP_HEADERS"] = _append_env_list(
+        env.get("OTEL_EXPORTER_OTLP_HEADERS", ""),
+        f"authorization={quote('Bearer ' + trace.ingest_token, safe='')}",
+    )
+    env["OTEL_RESOURCE_ATTRIBUTES"] = _append_env_list(
+        env.get("OTEL_RESOURCE_ATTRIBUTES", ""),
+        f"gradient.run.id={trace.id}",
+        f"gradient.trace.mode={trace.trace_mode}",
+    )
+    metadata = dict(config.get("metadata") or {})
+    metadata.update({"trace_run_id": trace.id, "trace_mode": trace.trace_mode})
+    config["env"] = env
+    config["metadata"] = metadata
+    payload["config"] = config
+    return payload
+
+
+def _with_replay_env(
+    template: Mapping[str, Any],
+    replay_config: Mapping[str, Any],
+) -> dict[str, Any]:
+    payload = _payload(template)
+    config = dict(payload.get("config", {}))
+    env = dict(config.get("env") or {})
+
+    def _stringify(value: Any) -> str:
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, float) and value.is_integer():
+            return str(int(value))
+        return str(value)
+
+    egress = replay_config.get("egress") or "live"
+    env["GRADIENT_REPLAY_EGRESS"] = _stringify(egress)
+    mapping = {
+        "parentRunId": "GRADIENT_REPLAY_PARENT_RUN_ID",
+        "seed": "GRADIENT_REPLAY_SEED",
+        "freezeTime": "GRADIENT_REPLAY_FREEZE_TIME",
+        "datasetId": "GRADIENT_REPLAY_DATASET_ID",
+    }
+    for key, env_key in mapping.items():
+        value = replay_config.get(key)
+        if value not in (None, ""):
+            env[env_key] = _stringify(value)
+    config["env"] = env
+    payload["config"] = config
+    return payload
+
+
+def _append_env_list(current: str, *values: str) -> str:
+    items = [item for item in current.split(",") if item]
+    for value in values:
+        if value and value not in items:
+            items.append(value)
+    return ",".join(items)