snapstate-sdk 1.0.0__tar.gz

snapstate_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: snapstate-sdk
+Version: 1.0.0
+Summary: Python SDK for the SnapState workflow state persistence service
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+
+# snapstate-sdk (Python)
+
+Python SDK for the [Checkpoint Service](https://github.com/your-org/snapstate) — a workflow state persistence API that lets AI agents save and resume multi-step work across interruptions, crashes, and handoffs between agents.
+
+## Installation
+
+```bash
+pip install snapstate-sdk
+```
+
+Requires Python 3.9+ and `httpx>=0.25.0` (installed automatically).
+
+## Quick start (sync)
+
+```python
+from snapstate_sdk import SnapStateClient
+
+client = SnapStateClient(
+    api_key="snp_your_key_here",
+    base_url="http://localhost:3000",
+)
+
+# Save state after each step
+result = client.save(
+    workflow_id="wf_research_001",
+    step=1,
+    label="sources_gathered",
+    state={"sources": ["arxiv.org/123"], "progress": 0.25},
+)
+print(f"Saved: {result.checkpoint_id} (etag: {result.etag})")
+
+# Resume a workflow — get the latest state
+resumed = client.resume("wf_research_001")
+print(f"Resuming from step {resumed.latest_checkpoint.step}")
+state = resumed.latest_checkpoint.state
+
+# Get full checkpoint history
+history = client.replay("wf_research_001")
+for cp in history.checkpoints:
+    print(f"  Step {cp.step}: {cp.label}")
+
+client.close()
+```
+
+## Async usage
+
+Every method has an `async_` prefixed equivalent:
+
+```python
+import asyncio
+from snapstate_sdk import SnapStateClient
+
+async def main():
+    client = SnapStateClient(api_key="snp_...", base_url="http://localhost:3000")
+
+    result = await client.async_save(
+        workflow_id="wf_001",
+        step=1,
+        state={"status": "running"},
+    )
+    print(f"Saved: {result.checkpoint_id}")
+
+    resumed = await client.async_resume("wf_001")
+    print(f"Latest step: {resumed.latest_checkpoint.step}")
+
+    await client.async_close()
+
+asyncio.run(main())
+```
+
+Context managers are supported for both sync and async usage:
+
+```python
+# Sync
+with SnapStateClient(api_key="snp_...") as client:
+    client.save(workflow_id="wf_001", step=1, state={})
+
+# Async
+async with SnapStateClient(api_key="snp_...") as client:
+    await client.async_save(workflow_id="wf_001", step=1, state={})
+```
+
+## Agent identity
+
+Register your agent once at startup, then tag checkpoints with `agent_id`:
+
+```python
+client = SnapStateClient(api_key="snp_...", base_url="http://localhost:3000")
+
+# Register agent identity
+client.register_agent(
+    agent_id="research-bot",
+    name="Research Bot",
+    description="Searches and summarizes sources",
+    capabilities=["web_search", "summarization"],
+    metadata={"model": "claude-sonnet-4-6", "version": "2.0.0"},
+)
+
+# Tag checkpoints with agent identity
+client.save(
+    workflow_id="wf_collab_001",
+    step=1,
+    state={"findings": [...]},
+    agent_id="research-bot",    # identity tag
+)
+
+# Another agent picks up the workflow
+resumed = client.resume("wf_collab_001")
+prior_agent = resumed.latest_checkpoint.metadata.get("agent_id")
+print(f"Picking up from: {prior_agent}")
+```
+
+## Error handling
+
+```python
+from snapstate_sdk import SnapStateClient
+from snapstate_sdk.errors import (
+    AuthError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    PayloadTooLargeError,
+    ValidationError,
+    SnapStateError,  # base class
+)
+
+client = SnapStateClient(api_key="snp_...", base_url="http://localhost:3000")
+
+try:
+    resumed = client.resume("wf_missing")
+except NotFoundError:
+    print("No prior state — starting fresh")
+
+try:
+    client.save(
+        workflow_id="wf_001",
+        step=2,
+        state={"data": "..."},
+        if_match="old-etag",       # optimistic concurrency
+    )
+except ConflictError:
+    print("State was modified by another agent — re-read and retry")
+
+try:
+    client.save(workflow_id="wf_001", step=1, state={})
+except AuthError:
+    print("Check your API key")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except PayloadTooLargeError:
+    print("State exceeds 1 MB limit — consider compressing")
+except SnapStateError as e:
+    print(f"Unexpected error: {e} (HTTP {e.status_code}, code={e.code})")
+```
+
+## API reference
+
+### `SnapStateClient(api_key, base_url, timeout, max_retries)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | API key starting with `snp_` |
+| `base_url` | `str` | `http://localhost:3000` | Checkpoint Service base URL |
+| `timeout` | `float` | `30.0` | Request timeout in seconds |
+| `max_retries` | `int` | `3` | Retry attempts on 429 before raising `RateLimitError` |
+
+---
+
+### Checkpoint methods
+
+#### `save(workflow_id, step, state, label, metadata, agent_id, ttl_seconds, if_match) → SaveResult`
+
+Save state for a workflow step.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `workflow_id` | `str` | required | Unique workflow identifier |
+| `step` | `int` | required | Sequential step number |
+| `state` | `dict` | required | Full state to persist (max 1 MB) |
+| `label` | `str` | `None` | Human-readable step label |
+| `metadata` | `dict` | `None` | Arbitrary metadata |
+| `agent_id` | `str` | `None` | Agent identity tag |
+| `ttl_seconds` | `int` | `None` | Override default TTL |
+| `if_match` | `str` | `None` | ETag for optimistic concurrency |
+
+Returns `SaveResult(checkpoint_id, workflow_id, step, etag, created_at, diff_from_previous, size_bytes)`.
+
+#### `get(checkpoint_id) → Checkpoint`
+
+Fetch a specific checkpoint by ID.
+
+#### `resume(workflow_id) → WorkflowResume`
+
+Get the latest checkpoint for a workflow. Raises `NotFoundError` if no checkpoints exist.
+
+Returns `WorkflowResume(workflow_id, latest_checkpoint, total_checkpoints, workflow_started_at, last_activity_at)`.
+
+#### `replay(workflow_id, from_step, to_step, limit) → WorkflowReplay`
+
+Get the full ordered checkpoint history.
+
+Returns `WorkflowReplay(workflow_id, checkpoints, total, has_more)`.
+
+---
+
+### Agent methods
+
+#### `register_agent(agent_id, name, description, capabilities, metadata) → Agent`
+
+Register or update an agent (upsert). Safe to call on every startup.
+
+#### `list_agents() → list[Agent]`
+
+List all agents for this account.
+
+---
+
+### Webhook methods
+
+#### `register_webhook(url, events, secret) → dict`
+
+Register a webhook URL. `events` is a list of `checkpoint.saved`, `workflow.resumed`, `workflow.expired`.
+
+---
+
+### Lifecycle
+
+#### `close()`
+
+Close the sync HTTP client.
+
+#### `async_close()`
+
+Close the async HTTP client.
+
+---
+
+### Async equivalents
+
+Every method above has an `async_` prefixed version:
+`async_save`, `async_get`, `async_resume`, `async_replay`, `async_register_agent`, `async_list_agents`.
+
+---
+
+### Return types
+
+| Type | Fields |
+|------|--------|
+| `Checkpoint` | `checkpoint_id, workflow_id, step, label, state, metadata, etag, created_at, diff_from_previous, size_bytes, agent_id` |
+| `WorkflowResume` | `workflow_id, latest_checkpoint, total_checkpoints, workflow_started_at, last_activity_at` |
+| `WorkflowReplay` | `workflow_id, checkpoints, total, has_more` |
+| `Agent` | `agent_id, name, description, capabilities, metadata, last_seen_at, created_at` |
+| `SaveResult` | `checkpoint_id, workflow_id, step, etag, created_at, diff_from_previous, size_bytes` |
+
+### Error types
+
+| Exception | HTTP status | When raised |
+|-----------|-------------|-------------|
+| `AuthError` | 401 | Invalid or missing API key |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | ETag mismatch (optimistic concurrency) |
+| `PayloadTooLargeError` | 413 | State exceeds 1 MB |
+| `RateLimitError` | 429 | Rate limit exceeded after all retries |
+| `ValidationError` | 400 | Invalid input |
+| `SnapStateError` | any | Base class for all SDK errors |
+
+All exceptions expose `.status_code` (int) and `.code` (str, machine-readable error code).  
+`RateLimitError` additionally exposes `.retry_after` (int, seconds).
+
+## Running tests
+
+```bash
+pip install "snapstate-sdk[dev]"
+pytest tests/
+```

snapstate_sdk-1.0.0/README.md

@@ -0,0 +1,275 @@
+# snapstate-sdk (Python)
+
+Python SDK for the [Checkpoint Service](https://github.com/your-org/snapstate) — a workflow state persistence API that lets AI agents save and resume multi-step work across interruptions, crashes, and handoffs between agents.
+
+## Installation
+
+```bash
+pip install snapstate-sdk
+```
+
+Requires Python 3.9+ and `httpx>=0.25.0` (installed automatically).
+
+## Quick start (sync)
+
+```python
+from snapstate_sdk import SnapStateClient
+
+client = SnapStateClient(
+    api_key="snp_your_key_here",
+    base_url="http://localhost:3000",
+)
+
+# Save state after each step
+result = client.save(
+    workflow_id="wf_research_001",
+    step=1,
+    label="sources_gathered",
+    state={"sources": ["arxiv.org/123"], "progress": 0.25},
+)
+print(f"Saved: {result.checkpoint_id} (etag: {result.etag})")
+
+# Resume a workflow — get the latest state
+resumed = client.resume("wf_research_001")
+print(f"Resuming from step {resumed.latest_checkpoint.step}")
+state = resumed.latest_checkpoint.state
+
+# Get full checkpoint history
+history = client.replay("wf_research_001")
+for cp in history.checkpoints:
+    print(f"  Step {cp.step}: {cp.label}")
+
+client.close()
+```
+
+## Async usage
+
+Every method has an `async_` prefixed equivalent:
+
+```python
+import asyncio
+from snapstate_sdk import SnapStateClient
+
+async def main():
+    client = SnapStateClient(api_key="snp_...", base_url="http://localhost:3000")
+
+    result = await client.async_save(
+        workflow_id="wf_001",
+        step=1,
+        state={"status": "running"},
+    )
+    print(f"Saved: {result.checkpoint_id}")
+
+    resumed = await client.async_resume("wf_001")
+    print(f"Latest step: {resumed.latest_checkpoint.step}")
+
+    await client.async_close()
+
+asyncio.run(main())
+```
+
+Context managers are supported for both sync and async usage:
+
+```python
+# Sync
+with SnapStateClient(api_key="snp_...") as client:
+    client.save(workflow_id="wf_001", step=1, state={})
+
+# Async
+async with SnapStateClient(api_key="snp_...") as client:
+    await client.async_save(workflow_id="wf_001", step=1, state={})
+```
+
+## Agent identity
+
+Register your agent once at startup, then tag checkpoints with `agent_id`:
+
+```python
+client = SnapStateClient(api_key="snp_...", base_url="http://localhost:3000")
+
+# Register agent identity
+client.register_agent(
+    agent_id="research-bot",
+    name="Research Bot",
+    description="Searches and summarizes sources",
+    capabilities=["web_search", "summarization"],
+    metadata={"model": "claude-sonnet-4-6", "version": "2.0.0"},
+)
+
+# Tag checkpoints with agent identity
+client.save(
+    workflow_id="wf_collab_001",
+    step=1,
+    state={"findings": [...]},
+    agent_id="research-bot",    # identity tag
+)
+
+# Another agent picks up the workflow
+resumed = client.resume("wf_collab_001")
+prior_agent = resumed.latest_checkpoint.metadata.get("agent_id")
+print(f"Picking up from: {prior_agent}")
+```
+
+## Error handling
+
+```python
+from snapstate_sdk import SnapStateClient
+from snapstate_sdk.errors import (
+    AuthError,
+    NotFoundError,
+    ConflictError,
+    RateLimitError,
+    PayloadTooLargeError,
+    ValidationError,
+    SnapStateError,  # base class
+)
+
+client = SnapStateClient(api_key="snp_...", base_url="http://localhost:3000")
+
+try:
+    resumed = client.resume("wf_missing")
+except NotFoundError:
+    print("No prior state — starting fresh")
+
+try:
+    client.save(
+        workflow_id="wf_001",
+        step=2,
+        state={"data": "..."},
+        if_match="old-etag",       # optimistic concurrency
+    )
+except ConflictError:
+    print("State was modified by another agent — re-read and retry")
+
+try:
+    client.save(workflow_id="wf_001", step=1, state={})
+except AuthError:
+    print("Check your API key")
+except RateLimitError as e:
+    print(f"Rate limited — retry after {e.retry_after}s")
+except PayloadTooLargeError:
+    print("State exceeds 1 MB limit — consider compressing")
+except SnapStateError as e:
+    print(f"Unexpected error: {e} (HTTP {e.status_code}, code={e.code})")
+```
+
+## API reference
+
+### `SnapStateClient(api_key, base_url, timeout, max_retries)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | API key starting with `snp_` |
+| `base_url` | `str` | `http://localhost:3000` | Checkpoint Service base URL |
+| `timeout` | `float` | `30.0` | Request timeout in seconds |
+| `max_retries` | `int` | `3` | Retry attempts on 429 before raising `RateLimitError` |
+
+---
+
+### Checkpoint methods
+
+#### `save(workflow_id, step, state, label, metadata, agent_id, ttl_seconds, if_match) → SaveResult`
+
+Save state for a workflow step.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `workflow_id` | `str` | required | Unique workflow identifier |
+| `step` | `int` | required | Sequential step number |
+| `state` | `dict` | required | Full state to persist (max 1 MB) |
+| `label` | `str` | `None` | Human-readable step label |
+| `metadata` | `dict` | `None` | Arbitrary metadata |
+| `agent_id` | `str` | `None` | Agent identity tag |
+| `ttl_seconds` | `int` | `None` | Override default TTL |
+| `if_match` | `str` | `None` | ETag for optimistic concurrency |
+
+Returns `SaveResult(checkpoint_id, workflow_id, step, etag, created_at, diff_from_previous, size_bytes)`.
+
+#### `get(checkpoint_id) → Checkpoint`
+
+Fetch a specific checkpoint by ID.
+
+#### `resume(workflow_id) → WorkflowResume`
+
+Get the latest checkpoint for a workflow. Raises `NotFoundError` if no checkpoints exist.
+
+Returns `WorkflowResume(workflow_id, latest_checkpoint, total_checkpoints, workflow_started_at, last_activity_at)`.
+
+#### `replay(workflow_id, from_step, to_step, limit) → WorkflowReplay`
+
+Get the full ordered checkpoint history.
+
+Returns `WorkflowReplay(workflow_id, checkpoints, total, has_more)`.
+
+---
+
+### Agent methods
+
+#### `register_agent(agent_id, name, description, capabilities, metadata) → Agent`
+
+Register or update an agent (upsert). Safe to call on every startup.
+
+#### `list_agents() → list[Agent]`
+
+List all agents for this account.
+
+---
+
+### Webhook methods
+
+#### `register_webhook(url, events, secret) → dict`
+
+Register a webhook URL. `events` is a list of `checkpoint.saved`, `workflow.resumed`, `workflow.expired`.
+
+---
+
+### Lifecycle
+
+#### `close()`
+
+Close the sync HTTP client.
+
+#### `async_close()`
+
+Close the async HTTP client.
+
+---
+
+### Async equivalents
+
+Every method above has an `async_` prefixed version:
+`async_save`, `async_get`, `async_resume`, `async_replay`, `async_register_agent`, `async_list_agents`.
+
+---
+
+### Return types
+
+| Type | Fields |
+|------|--------|
+| `Checkpoint` | `checkpoint_id, workflow_id, step, label, state, metadata, etag, created_at, diff_from_previous, size_bytes, agent_id` |
+| `WorkflowResume` | `workflow_id, latest_checkpoint, total_checkpoints, workflow_started_at, last_activity_at` |
+| `WorkflowReplay` | `workflow_id, checkpoints, total, has_more` |
+| `Agent` | `agent_id, name, description, capabilities, metadata, last_seen_at, created_at` |
+| `SaveResult` | `checkpoint_id, workflow_id, step, etag, created_at, diff_from_previous, size_bytes` |
+
+### Error types
+
+| Exception | HTTP status | When raised |
+|-----------|-------------|-------------|
+| `AuthError` | 401 | Invalid or missing API key |
+| `NotFoundError` | 404 | Resource not found |
+| `ConflictError` | 409 | ETag mismatch (optimistic concurrency) |
+| `PayloadTooLargeError` | 413 | State exceeds 1 MB |
+| `RateLimitError` | 429 | Rate limit exceeded after all retries |
+| `ValidationError` | 400 | Invalid input |
+| `SnapStateError` | any | Base class for all SDK errors |
+
+All exceptions expose `.status_code` (int) and `.code` (str, machine-readable error code).  
+`RateLimitError` additionally exposes `.retry_after` (int, seconds).
+
+## Running tests
+
+```bash
+pip install "snapstate-sdk[dev]"
+pytest tests/
+```

snapstate_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "snapstate-sdk"
+version = "1.0.0"
+description = "Python SDK for the SnapState workflow state persistence service"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.25.0"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21.0"]
+
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

snapstate_sdk-1.0.0/setup.cfg

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

snapstate_sdk-1.0.0/src/checkpoint_sdk/__init__.py

@@ -0,0 +1,45 @@
+"""
+checkpoint-sdk — Python SDK for the Checkpoint workflow state persistence service.
+
+Quick start::
+
+    from checkpoint_sdk import CheckpointClient
+
+    client = CheckpointClient(api_key="cpk_...", base_url="http://localhost:3000")
+
+    result = client.save(workflow_id="wf_001", step=1, state={"progress": 0})
+    resumed = client.resume("wf_001")
+    client.close()
+"""
+
+from .client import CheckpointClient
+from .errors import (
+    AuthError,
+    CheckpointError,
+    ConflictError,
+    NotFoundError,
+    PayloadTooLargeError,
+    RateLimitError,
+    ValidationError,
+)
+from .types import Agent, Checkpoint, SaveResult, WorkflowResume, WorkflowReplay
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "CheckpointClient",
+    # Types
+    "Checkpoint",
+    "WorkflowResume",
+    "WorkflowReplay",
+    "Agent",
+    "SaveResult",
+    # Errors
+    "CheckpointError",
+    "AuthError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ValidationError",
+    "PayloadTooLargeError",
+]