waypoint-sdk 0.1.0__py3-none-any.whl

sdk/__init__.py

@@ -0,0 +1,46 @@
+from .client import WaypointClient
+from .exceptions import (
+    CheckpointError,
+    CheckpointNotFoundError,
+    ExecutionNotFoundError,
+    GatewayError,
+    WaypointClientError,
+    WaypointConnectionError,
+    WaypointError,
+    WaypointTimeoutError,
+)
+from .gateway import Waypoint, checkpoint
+from .models import (
+    CheckpointResponse,
+    ExecutionHistory,
+    ExecutionInfo,
+    ExecutionResult,
+    ExecutionStep,
+    ReplayState,
+    ResumeState,
+    StepStatus,
+)
+from .session import WaypointSession
+
+__all__ = [
+    "Waypoint",
+    "WaypointClient",
+    "WaypointSession",
+    "checkpoint",
+    "ExecutionInfo",
+    "WaypointError",
+    "GatewayError",
+    "CheckpointError",
+    "WaypointClientError",
+    "WaypointConnectionError",
+    "WaypointTimeoutError",
+    "ExecutionNotFoundError",
+    "CheckpointNotFoundError",
+    "ExecutionResult",
+    "CheckpointResponse",
+    "ExecutionHistory",
+    "ExecutionStep",
+    "ResumeState",
+    "ReplayState",
+    "StepStatus",
+]

sdk/client.py

@@ -0,0 +1,255 @@
+import asyncio
+import logging
+from typing import Any
+from uuid import UUID
+
+import httpx
+
+from .exceptions import (
+    CheckpointNotFoundError,
+    ExecutionNotFoundError,
+    GatewayError,
+    WaypointClientError,
+)
+from .models import (
+    CheckpointResponse,
+    ExecutionHistory,
+    ExecutionInfo,
+    ExecutionStep,
+    ReplayState,
+    ResumeState,
+)
+
+log = logging.getLogger(f"sdk.{__name__}")
+
+
+class WaypointClient:
+    """
+    Low-level HTTP client for the Waypoint API.
+
+    Manages reusable httpx clients (sync and async) with lazy initialisation,
+    thread-safety locks, and explicit close/aclose lifecycle.
+
+    Every public method maps to exactly one API endpoint.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        agent_id: str,
+        timeout: float = 30.0,
+        api_key: str | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+        self.timeout = timeout
+        self.api_key = api_key
+
+        self._sync_client: httpx.Client | None = None
+        self._async_client: httpx.AsyncClient | None = None
+
+        self._sync_lock = asyncio.Lock()
+        self._async_lock = asyncio.Lock()
+
+    # ── low-level HTTP helpers ──────────────────────────────────────────────────
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self.api_key:
+            return {"X-WAYPOINT-API-KEY": f"{self.api_key}"}
+        return {}
+
+    def _http(self) -> httpx.Client:
+        if self._sync_client is None or self._sync_client.is_closed:
+            self._sync_client = httpx.Client(
+                base_url=self.base_url,
+                headers=self._auth_headers(),
+                timeout=self.timeout,
+                trust_env=False,
+            )
+        return self._sync_client
+
+    async def _ahttp(self) -> httpx.AsyncClient:
+        if self._async_client is None or self._async_client.is_closed:
+            self._async_client = httpx.AsyncClient(
+                base_url=self.base_url,
+                headers=self._auth_headers(),
+                timeout=self.timeout,
+                trust_env=False,
+            )
+        return self._async_client
+
+    def close(self) -> None:
+        if self._sync_client:
+            self._sync_client.close()
+
+    async def aclose(self) -> None:
+        if self._async_client:
+            await self._async_client.aclose()
+
+    # ── request dispatch ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _build_path(
+        execution_id: UUID,
+        resource: str,
+        *,
+        include_load: bool = False,
+    ) -> str:
+        if resource == "create_execution":
+            return "/executions/"
+        if resource == "checkpoint":
+            return "/checkpoints/"
+        if resource == "checkpoint_load":
+            return "/checkpoints/load"
+        if resource == "history":
+            return f"/executions/{execution_id}/history"
+        if resource == "resume":
+            return f"/executions/{execution_id}/resume"
+        if resource == "replay":
+            return f"/executions/{execution_id}/replay"
+        msg = f"Unknown resource: {resource}"
+        raise ValueError(msg)
+
+    async def _arequest(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, str | int] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            http = await self._ahttp()
+            resp = await http.request(
+                method,
+                path,
+                json=json_body,
+                params=params,
+            )
+            body: dict[str, Any] = resp.json()
+            if not resp.is_success:
+                detail = body.get("detail", str(resp.reason_phrase))
+                if resp.status_code == 404:
+                    msg = detail if isinstance(detail, str) else str(detail)
+                    if "checkpoint" in msg.lower():
+                        raise CheckpointNotFoundError(msg)
+                    raise ExecutionNotFoundError(msg)
+                raise WaypointClientError(resp.status_code, detail)
+            return body
+        except httpx.ConnectError as exc:
+            raise GatewayError(self.base_url, exc) from exc
+        except httpx.TimeoutException as exc:
+            raise GatewayError(self.base_url, exc) from exc
+
+    # ── API methods ─────────────────────────────────────────────────────────────
+
+    async def create_execution(
+        self,
+        agent_id: str,
+        initial_input: dict[str, Any] | None = None,
+    ) -> ExecutionInfo:
+        body = await self._arequest(
+            "POST",
+            "/executions/",
+            json_body={
+                "agent_id": agent_id,
+                "initial_input": initial_input,
+            },
+        )
+        return ExecutionInfo(
+            id=UUID(body["id"]) if isinstance(body["id"], str) else body["id"],
+            agent_id=body["agent_id"],
+            status=body["status"],
+            started_at=body["started_at"],
+            initial_input=body.get("initial_input"),
+            created_at=body.get("created_at"),
+        )
+
+    async def create_checkpoint(
+        self,
+        execution_id: UUID,
+        step_number: int,
+        step_name: str,
+        state: dict[str, Any],
+        *,
+        input_data: dict[str, Any] | None = None,
+        output_data: dict[str, Any] | None = None,
+        status: str = "completed",
+        duration_ms: int | None = None,
+        error: dict[str, Any] | None = None,
+        cached: bool = False,
+    ) -> CheckpointResponse:
+        body = await self._arequest(
+            "POST",
+            "/checkpoints/",
+            json_body={
+                "execution_id": str(execution_id),
+                "step_number": step_number,
+                "step_name": step_name,
+                "state": state,
+                "input_data": input_data or {},
+                "output_data": output_data,
+                "status": status,
+                "duration_ms": duration_ms,
+                "error": error,
+                "cached": cached,
+            },
+        )
+        return CheckpointResponse(
+            id=UUID(body["id"]) if isinstance(body["id"], str) else body["id"],
+            execution_id=UUID(body["execution_id"])
+            if isinstance(body["execution_id"], str)
+            else body["execution_id"],
+            step_number=body["step_number"],
+            completed_at=body["completed_at"],
+            state_hash=body.get("state_hash"),
+            created_at=body.get("created_at"),
+        )
+
+    async def resume_execution(self, execution_id: UUID) -> ResumeState:
+        body = await self._arequest(
+            "POST",
+            f"/executions/{execution_id}/resume",
+        )
+        return ResumeState(
+            execution_id=UUID(body["execution_id"])
+            if isinstance(body["execution_id"], str)
+            else body["execution_id"],
+            checkpoint_step=body.get("checkpoint_step", 0),
+            reconstructed_state=body.get("reconstructed_state", {}),
+            state_hash=body.get("state_hash"),
+            ready_to_resume=body.get("ready_to_resume", True),
+        )
+
+    async def replay_from_step(
+        self,
+        execution_id: UUID,
+        step_number: int,
+    ) -> ReplayState:
+        body = await self._arequest(
+            "POST",
+            f"/executions/{execution_id}/replay",
+            json_body={"step_number": step_number},
+        )
+        return ReplayState(
+            execution_id=UUID(body["execution_id"])
+            if isinstance(body["execution_id"], str)
+            else body["execution_id"],
+            replay_from_step=body.get("replay_from_step", step_number),
+            reconstructed_state=body.get("reconstructed_state", {}),
+            ready_to_resume=body.get("ready_to_resume", True),
+        )
+
+    async def get_execution_history(self, execution_id: UUID) -> ExecutionHistory:
+        body = await self._arequest("GET", f"/executions/{execution_id}/history")
+        steps = [ExecutionStep(**s) for s in body.get("steps", [])]
+        return ExecutionHistory(
+            execution_id=UUID(body["execution_id"])
+            if isinstance(body["execution_id"], str)
+            else body["execution_id"],
+            agent_id=body["agent_id"],
+            status=body["status"],
+            started_at=body["started_at"],
+            completed_at=body.get("completed_at"),
+            steps=steps,
+        )

sdk/examples/agent_with_llm_mock.py

@@ -0,0 +1,115 @@
+"""
+Agent workflow with mocked LLM calls, demonstrating crash recovery.
+
+Prerequisites:
+    - Waypoint API running at http://localhost:9654
+
+Usage:
+    uv run python -m sdk.examples.agent_with_llm_mock
+
+This simulates:
+    1. Create a new execution
+    2. Normal execution with an LLM call
+    3. Resume after a simulated crash: the LLM response is served from cache
+"""
+
+import asyncio
+
+from sdk import Waypoint, checkpoint
+
+AGENT_ID = "llm_agent"
+API_BASE_URL = "http://localhost:9654/api/v1/"
+
+waypoint = Waypoint(
+    base_url=API_BASE_URL,
+    agent_id=AGENT_ID,
+).use()
+
+
+@checkpoint("load_context", cache=True)
+async def load_context(user_query: str):
+    return {
+        "query": user_query,
+        "context": {"user_id": "abc123", "session": "test"},
+    }
+
+
+async def mock_llm_call(prompt: str) -> dict:
+    """Simulate an expensive LLM API call."""
+    await asyncio.sleep(0.05)
+    return {
+        "response": f"Analysis of: {prompt[:50]}...",
+        "tokens_used": 150,
+        "model": "gpt-4",
+    }
+
+
+@checkpoint("call_llm", cache=True)
+async def call_llm(context: dict):
+    print("  Calling LLM (this is expensive)...")
+    return await mock_llm_call(context["query"])
+
+
+@checkpoint("format_output")
+async def format_output(data: dict):
+    response = data["llm"]["response"]
+    return {"formatted": f"<result>{response}</result>", "meta": data["llm"]}
+
+
+async def first_run():
+    """First execution: create, run steps, return execution_id for recovery demo."""
+    execution_id = await waypoint.create()
+    print(f"Created execution: {execution_id}")
+
+    context = await load_context(user_query="What is event sourcing?")
+    print("Step 1 (load_context): context loaded")
+
+    llm_result = await call_llm(context=context)
+    print("Step 2 (call_llm): LLM responded")
+
+    output = await format_output(data={"llm": llm_result, "context": context})
+    print(f"Step 3 (format_output): {output['formatted'][:100]}...")
+
+    print(f"\nExecution completed! Total steps: {waypoint.get_step_number()}")
+    return execution_id
+
+
+async def crash_recovery_demo(execution_id):
+    """
+    Simulate a crash and recovery.
+    A new Waypoint instance resumes the execution; the cached LLM response
+    is returned without re-invoking the LLM call.
+    """
+    print("\n--- CRASH RECOVERY ---")
+    print(f"Resuming execution {execution_id}...")
+
+    waypoint2 = Waypoint(
+        base_url=API_BASE_URL,
+        agent_id=AGENT_ID,
+    ).use()
+
+    resume = await waypoint2.resume(execution_id)
+    print(f"Resumed from step {resume.checkpoint_step}")
+    print(f"Recovered state keys: {list(waypoint2.get_state().keys())}")
+
+    context = await load_context(user_query="What is event sourcing?")
+    print("Step 1 (load_context, cached): context loaded (from cache)")
+
+    llm_result = await call_llm(context=context)
+    print("Step 2 (call_llm, cached): LLM responded (from cache, no re-execution)")
+
+    output = await format_output(data={"llm": llm_result, "context": context})
+    print(f"Step 3 (format_output, fresh): {output['formatted'][:100]}...")
+
+    print(f"\nRecovery complete! Total steps: {waypoint2.get_step_number()}")
+    await waypoint2.aclose()
+
+
+async def main():
+    execution_id = await first_run()
+    await crash_recovery_demo(execution_id)
+    await waypoint.aclose()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/examples/simple_agent.py

@@ -0,0 +1,69 @@
+"""
+Simple 3-step agent workflow using the Waypoint SDK.
+
+Prerequisites:
+    - Waypoint API running at http://localhost:9654
+
+Usage:
+    uv run python -m sdk.examples.simple_agent
+"""
+
+import asyncio
+
+from sdk import Waypoint, checkpoint
+
+AGENT_ID = "simple_agent"
+API_BASE_URL = "http://localhost:9654/api/v1/"
+
+waypoint = Waypoint(
+    base_url=API_BASE_URL,
+    agent_id=AGENT_ID,
+).use()
+
+
+@checkpoint("load_query")
+async def load_query(query: str):
+    return {"query": query, "normalized": query.lower()}
+
+
+@checkpoint("search")
+async def search(data: dict):
+    results = [
+        "Waypoint provides agent execution recovery",
+        "Event sourcing enables deterministic replay",
+    ]
+    return {**data, "results": results}
+
+
+@checkpoint("summarize", cache=True)
+async def summarize(data: dict):
+    summary = "Waypoint is a fault-tolerant execution recovery system."
+    return {**data, "summary": summary}
+
+
+async def main():
+    execution_id = await waypoint.create()
+    print(f"Created execution: {execution_id}")
+
+    try:
+        step1 = await load_query(query="What is Waypoint?")
+        print(f"Step 1 (load_query): {step1}")
+
+        step2 = await search(data=step1)
+        print(f"Step 2 (search): {step2}")
+
+        step3 = await summarize(data=step2)
+        print(f"Step 3 (summarize): {step3}")
+
+        print(f"\nExecution completed! Total steps: {waypoint.get_step_number()}")
+        print(f"Final state: {waypoint.get_state()}")
+
+    except Exception as e:
+        print(f"Execution failed: {e}")
+        raise
+
+    await waypoint.aclose()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sdk/exceptions.py

@@ -0,0 +1,52 @@
+class WaypointError(Exception):
+    """Base exception for all Waypoint SDK errors."""
+
+    pass
+
+
+class GatewayError(WaypointError):
+    """Raised when the Waypoint API is unreachable and no fail-open policy applies."""
+
+    def __init__(self, gateway_url: str, original: Exception) -> None:
+        self.gateway_url = gateway_url
+        self.original = original
+        super().__init__(f"Waypoint API at {gateway_url!r} unreachable: {original}")
+
+
+class CheckpointError(WaypointError):
+    """Raised when a checkpoint operation fails."""
+
+    pass
+
+
+class ExecutionNotFoundError(WaypointError):
+    """Raised when the execution does not exist on the server."""
+
+    pass
+
+
+class CheckpointNotFoundError(WaypointError):
+    """Raised when no checkpoint exists for an execution."""
+
+    pass
+
+
+class WaypointClientError(WaypointError):
+    """Raised when the API returns an unexpected error status."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"API error {status_code}: {detail}")
+
+
+class WaypointConnectionError(WaypointError):
+    """Raised when the SDK cannot connect to the Waypoint API."""
+
+    pass
+
+
+class WaypointTimeoutError(WaypointError):
+    """Raised when a request to the Waypoint API times out."""
+
+    pass