sapixdb 0.1.0__tar.gz

sapixdb-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+/target
+.DS_Store
+*.env
+*.env.*
+!*.env.example

sapixdb-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: sapixdb
+Version: 0.1.0
+Summary: Official Python SDK for SapixDB — the agent-native living database
+Project-URL: Homepage, https://sapixdb.com
+Project-URL: Docs, https://sapixdb.com/docs/sdk/python
+Project-URL: Repository, https://github.com/sensart/sapixdb
+Author: Sensart Technologies LLC
+License: MIT
+Keywords: agent-native,ai,database,sapixdb,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SapixDB Python SDK
+
+Official Python SDK for [SapixDB](https://sapixdb.com) — the agent-native living database.
+
+Supports both **sync** and **async** (asyncio / FastAPI / Django Async). Python 3.9+.
+
+## Installation
+
+```bash
+pip install sapixdb
+# or
+uv add sapixdb
+# or
+poetry add sapixdb
+```
+
+## Quick Start
+
+```python
+from sapixdb import SapixClient
+
+db = SapixClient(url="http://localhost:7475", agent="my-app")
+
+# Write a record
+record = db.collection("products").write({
+    "name": "Classic T-Shirt",
+    "price": 29.99,
+    "stock": 100,
+})
+print(record.id)    # "nuc_abc123"
+print(record.hash)  # "sha3:e7f2a1..."
+
+# Read latest records
+products = db.collection("products").latest()
+
+# Filter
+shirts = db.collection("products").find({"category": "apparel"})
+
+# Time travel — what did the DB look like yesterday?
+from datetime import datetime, timedelta, timezone
+yesterday = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+snapshot = db.collection("orders").as_of(yesterday).latest()
+```
+
+## Async Usage
+
+```python
+import asyncio
+from sapixdb import AsyncSapixClient
+
+async def main():
+    db = AsyncSapixClient(url="http://localhost:7475", agent="my-app")
+    record = await db.collection("products").write({"name": "T-Shirt", "price": 29.99})
+    products = await db.collection("products").latest()
+
+# Or as a context manager
+async def main():
+    async with AsyncSapixClient(url="http://localhost:7475", agent="my-app") as db:
+        record = await db.collection("products").write({"name": "T-Shirt"})
+
+asyncio.run(main())
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from sapixdb import AsyncSapixClient
+
+app = FastAPI()
+db = AsyncSapixClient(url="http://localhost:7475", agent="store")
+
+@app.post("/products")
+async def create_product(name: str, price: float):
+    record = await db.collection("products").write({"name": name, "price": price})
+    return {"id": record.id, "hash": record.hash}
+
+@app.get("/products")
+async def list_products():
+    items = await db.collection("products").latest()
+    return [{"id": r.id, **r.data} for r in items]
+```
+
+## API Reference
+
+### `SapixClient` / `AsyncSapixClient`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | — | SapixDB agent URL |
+| `agent` | `str` | — | Agent ID (matches `SAPIX_AGENT_ID`) |
+| `headers` | `dict` | `{}` | Extra HTTP headers |
+| `timeout` | `float` | `10.0` | Request timeout in seconds |
+
+---
+
+### `db.collection(name)`
+
+Returns a `CollectionClient` (or `AsyncCollectionClient`).
+
+#### `.write(data)` → `WriteResult`
+Append a new record. Nothing is ever overwritten.
+
+#### `.write_batch(records)` → `list[WriteResult]`
+Write multiple records. Async version runs them concurrently.
+
+#### `.get(record_id)` → `NucleotideRecord`
+Fetch a record by ID. Raises `SapixNotFoundError` if missing.
+
+#### `.latest(*, filter?, limit?)` → `list[NucleotideRecord]`
+Current version of every record.
+
+#### `.history(*, filter?, limit?)` → `list[NucleotideRecord]`
+Full append-only history — every version ever written.
+
+#### `.find(filter, *, limit?)` → `list[NucleotideRecord]`
+Filter records (latest version only).
+
+#### `.find_one(filter)` → `NucleotideRecord | None`
+First match, or `None`.
+
+#### `.as_of(timestamp)` → `CollectionQuery`
+Scope reads to a point in time. Returns a query object with `.latest()`, `.find()`, `.find_one()`, `.all()`.
+
+---
+
+### `db.graph`
+
+#### `.relate(src, dst, edge_type, weight=1.0)`
+Create a typed directed edge between two records.
+
+#### `.add_edge(src, dst, edge_type, weight=1.0)`
+Full edge creation.
+
+#### `.remove_edge(src, dst, edge_type)`
+Delete an edge.
+
+#### `.traverse(from_id, *, depth=1, direction="outbound")` → `TraverseResult`
+Walk the graph. `direction`: `"outbound"` | `"inbound"` | `"both"`.
+
+#### `.neighbors(node_id, direction="outbound")` → `list[NucleotideRecord]`
+Direct neighbours (depth=1 shortcut).
+
+#### `.edges(node_id)` → `list[GraphEdge]`
+All outbound edges from a node.
+
+---
+
+### `db.ingest(collection, data)` → `WriteResult`
+Write via the ingest endpoint — for AI agents, webhooks, and pipelines.
+
+```python
+db.ingest("ai_decisions", {
+    "model": "gpt-4o",
+    "action": "approve_loan",
+    "confidence": 0.94,
+    "reasoning": "Credit score 780, DTI 28%",
+})
+```
+
+---
+
+## Error Handling
+
+```python
+from sapixdb import SapixError, SapixNetworkError, SapixNotFoundError
+
+try:
+    record = db.collection("orders").get("nuc_missing")
+except SapixNotFoundError as e:
+    print(f"Not found: {e.record_id}")
+except SapixNetworkError:
+    print("SapixDB is unreachable — is it running?")
+except SapixError as e:
+    print(f"Error {e.status}: {e}")
+```
+
+---
+
+## Full Example: Online Store
+
+```python
+from sapixdb import SapixClient
+
+db = SapixClient(url="http://localhost:7475", agent="store")
+
+# 1. Add a product
+shirt = db.collection("products").write({
+    "sku": "SHIRT-001", "name": "Classic T-Shirt",
+    "price": 29.99, "stock": 200, "category": "apparel",
+})
+
+# 2. Register customer
+customer = db.collection("customers").write({
+    "name": "Alice Johnson", "email": "alice@example.com",
+})
+
+# 3. Place order
+order = db.collection("orders").write({
+    "customer_id": customer.id,
+    "items": [{"product_id": shirt.id, "qty": 2, "unit_price": 29.99}],
+    "total": 59.98,
+    "status": "placed",
+})
+
+# 4. Link in graph
+db.graph.relate(order.id, customer.id, "placed_by")
+db.graph.relate(order.id, shirt.id, "contains")
+
+# 5. Ship (appends — "placed" version is preserved forever)
+db.collection("orders").write({
+    "customer_id": customer.id,
+    "status": "shipped",
+    "tracking": "UPS-1Z999AA10123456784",
+})
+
+# 6. Audit: what was the order status when it was placed?
+original = db.collection("orders").as_of(order.timestamp).find_one(
+    {"customer_id": customer.id}
+)
+print(original.data["status"])  # "placed", not "shipped"
+```

sapixdb-0.1.0/README.md

@@ -0,0 +1,222 @@
+# SapixDB Python SDK
+
+Official Python SDK for [SapixDB](https://sapixdb.com) — the agent-native living database.
+
+Supports both **sync** and **async** (asyncio / FastAPI / Django Async). Python 3.9+.
+
+## Installation
+
+```bash
+pip install sapixdb
+# or
+uv add sapixdb
+# or
+poetry add sapixdb
+```
+
+## Quick Start
+
+```python
+from sapixdb import SapixClient
+
+db = SapixClient(url="http://localhost:7475", agent="my-app")
+
+# Write a record
+record = db.collection("products").write({
+    "name": "Classic T-Shirt",
+    "price": 29.99,
+    "stock": 100,
+})
+print(record.id)    # "nuc_abc123"
+print(record.hash)  # "sha3:e7f2a1..."
+
+# Read latest records
+products = db.collection("products").latest()
+
+# Filter
+shirts = db.collection("products").find({"category": "apparel"})
+
+# Time travel — what did the DB look like yesterday?
+from datetime import datetime, timedelta, timezone
+yesterday = (datetime.now(timezone.utc) - timedelta(days=1)).isoformat()
+snapshot = db.collection("orders").as_of(yesterday).latest()
+```
+
+## Async Usage
+
+```python
+import asyncio
+from sapixdb import AsyncSapixClient
+
+async def main():
+    db = AsyncSapixClient(url="http://localhost:7475", agent="my-app")
+    record = await db.collection("products").write({"name": "T-Shirt", "price": 29.99})
+    products = await db.collection("products").latest()
+
+# Or as a context manager
+async def main():
+    async with AsyncSapixClient(url="http://localhost:7475", agent="my-app") as db:
+        record = await db.collection("products").write({"name": "T-Shirt"})
+
+asyncio.run(main())
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from sapixdb import AsyncSapixClient
+
+app = FastAPI()
+db = AsyncSapixClient(url="http://localhost:7475", agent="store")
+
+@app.post("/products")
+async def create_product(name: str, price: float):
+    record = await db.collection("products").write({"name": name, "price": price})
+    return {"id": record.id, "hash": record.hash}
+
+@app.get("/products")
+async def list_products():
+    items = await db.collection("products").latest()
+    return [{"id": r.id, **r.data} for r in items]
+```
+
+## API Reference
+
+### `SapixClient` / `AsyncSapixClient`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `url` | `str` | — | SapixDB agent URL |
+| `agent` | `str` | — | Agent ID (matches `SAPIX_AGENT_ID`) |
+| `headers` | `dict` | `{}` | Extra HTTP headers |
+| `timeout` | `float` | `10.0` | Request timeout in seconds |
+
+---
+
+### `db.collection(name)`
+
+Returns a `CollectionClient` (or `AsyncCollectionClient`).
+
+#### `.write(data)` → `WriteResult`
+Append a new record. Nothing is ever overwritten.
+
+#### `.write_batch(records)` → `list[WriteResult]`
+Write multiple records. Async version runs them concurrently.
+
+#### `.get(record_id)` → `NucleotideRecord`
+Fetch a record by ID. Raises `SapixNotFoundError` if missing.
+
+#### `.latest(*, filter?, limit?)` → `list[NucleotideRecord]`
+Current version of every record.
+
+#### `.history(*, filter?, limit?)` → `list[NucleotideRecord]`
+Full append-only history — every version ever written.
+
+#### `.find(filter, *, limit?)` → `list[NucleotideRecord]`
+Filter records (latest version only).
+
+#### `.find_one(filter)` → `NucleotideRecord | None`
+First match, or `None`.
+
+#### `.as_of(timestamp)` → `CollectionQuery`
+Scope reads to a point in time. Returns a query object with `.latest()`, `.find()`, `.find_one()`, `.all()`.
+
+---
+
+### `db.graph`
+
+#### `.relate(src, dst, edge_type, weight=1.0)`
+Create a typed directed edge between two records.
+
+#### `.add_edge(src, dst, edge_type, weight=1.0)`
+Full edge creation.
+
+#### `.remove_edge(src, dst, edge_type)`
+Delete an edge.
+
+#### `.traverse(from_id, *, depth=1, direction="outbound")` → `TraverseResult`
+Walk the graph. `direction`: `"outbound"` | `"inbound"` | `"both"`.
+
+#### `.neighbors(node_id, direction="outbound")` → `list[NucleotideRecord]`
+Direct neighbours (depth=1 shortcut).
+
+#### `.edges(node_id)` → `list[GraphEdge]`
+All outbound edges from a node.
+
+---
+
+### `db.ingest(collection, data)` → `WriteResult`
+Write via the ingest endpoint — for AI agents, webhooks, and pipelines.
+
+```python
+db.ingest("ai_decisions", {
+    "model": "gpt-4o",
+    "action": "approve_loan",
+    "confidence": 0.94,
+    "reasoning": "Credit score 780, DTI 28%",
+})
+```
+
+---
+
+## Error Handling
+
+```python
+from sapixdb import SapixError, SapixNetworkError, SapixNotFoundError
+
+try:
+    record = db.collection("orders").get("nuc_missing")
+except SapixNotFoundError as e:
+    print(f"Not found: {e.record_id}")
+except SapixNetworkError:
+    print("SapixDB is unreachable — is it running?")
+except SapixError as e:
+    print(f"Error {e.status}: {e}")
+```
+
+---
+
+## Full Example: Online Store
+
+```python
+from sapixdb import SapixClient
+
+db = SapixClient(url="http://localhost:7475", agent="store")
+
+# 1. Add a product
+shirt = db.collection("products").write({
+    "sku": "SHIRT-001", "name": "Classic T-Shirt",
+    "price": 29.99, "stock": 200, "category": "apparel",
+})
+
+# 2. Register customer
+customer = db.collection("customers").write({
+    "name": "Alice Johnson", "email": "alice@example.com",
+})
+
+# 3. Place order
+order = db.collection("orders").write({
+    "customer_id": customer.id,
+    "items": [{"product_id": shirt.id, "qty": 2, "unit_price": 29.99}],
+    "total": 59.98,
+    "status": "placed",
+})
+
+# 4. Link in graph
+db.graph.relate(order.id, customer.id, "placed_by")
+db.graph.relate(order.id, shirt.id, "contains")
+
+# 5. Ship (appends — "placed" version is preserved forever)
+db.collection("orders").write({
+    "customer_id": customer.id,
+    "status": "shipped",
+    "tracking": "UPS-1Z999AA10123456784",
+})
+
+# 6. Audit: what was the order status when it was placed?
+original = db.collection("orders").as_of(order.timestamp).find_one(
+    {"customer_id": customer.id}
+)
+print(original.data["status"])  # "placed", not "shipped"
+```

sapixdb-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sapixdb"
+version = "0.1.0"
+description = "Official Python SDK for SapixDB — the agent-native living database"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Sensart Technologies LLC" }]
+requires-python = ">=3.9"
+keywords = ["sapixdb", "database", "ai", "agent-native", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Database",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "hatch"]
+
+[project.urls]
+Homepage    = "https://sapixdb.com"
+Docs        = "https://sapixdb.com/docs/sdk/python"
+Repository  = "https://github.com/sensart/sapixdb"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sapixdb"]

sapixdb-0.1.0/sapixdb/__init__.py

@@ -0,0 +1,25 @@
+from .client import SapixClient, AsyncSapixClient
+from .collection import CollectionClient, AsyncCollectionClient, CollectionQuery, AsyncCollectionQuery
+from .graph import GraphClient, AsyncGraphClient
+from ._types import WriteResult, NucleotideRecord, GraphEdge, TraverseResult, HealthResponse
+from ._errors import SapixError, SapixNetworkError, SapixNotFoundError
+
+__version__ = "0.1.0"
+__all__ = [
+    "SapixClient",
+    "AsyncSapixClient",
+    "CollectionClient",
+    "AsyncCollectionClient",
+    "CollectionQuery",
+    "AsyncCollectionQuery",
+    "GraphClient",
+    "AsyncGraphClient",
+    "WriteResult",
+    "NucleotideRecord",
+    "GraphEdge",
+    "TraverseResult",
+    "HealthResponse",
+    "SapixError",
+    "SapixNetworkError",
+    "SapixNotFoundError",
+]

sapixdb-0.1.0/sapixdb/_errors.py

@@ -0,0 +1,20 @@
+class SapixError(Exception):
+    """Base error for all SapixDB SDK errors."""
+    def __init__(self, message: str, status: int | None = None, code: str | None = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class SapixNetworkError(SapixError):
+    """Raised when the SapixDB agent cannot be reached."""
+    def __init__(self, cause: Exception):
+        super().__init__(f"Network error: {cause}")
+        self.cause = cause
+
+
+class SapixNotFoundError(SapixError):
+    """Raised when a requested record does not exist."""
+    def __init__(self, record_id: str):
+        super().__init__(f"Record not found: {record_id}", status=404, code="NOT_FOUND")
+        self.record_id = record_id

sapixdb-0.1.0/sapixdb/_http.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+from typing import Any
+import httpx
+from ._errors import SapixError, SapixNetworkError
+
+
+def request(
+    base_url: str,
+    agent: str,
+    method: str,
+    path: str,
+    body: dict[str, Any] | None = None,
+    extra_headers: dict[str, str] | None = None,
+    timeout: float = 10.0,
+) -> Any:
+    url = f"{base_url}{path}"
+    headers = {"Content-Type": "application/json", **(extra_headers or {})}
+    try:
+        resp = httpx.request(
+            method,
+            url,
+            json=body,
+            headers=headers,
+            timeout=timeout,
+        )
+    except httpx.RequestError as exc:
+        raise SapixNetworkError(exc) from exc
+
+    if not resp.is_success:
+        message = f"HTTP {resp.status_code}"
+        code: str | None = None
+        try:
+            data = resp.json()
+            message = data.get("error", message)
+            code = data.get("code")
+        except Exception:
+            pass
+        raise SapixError(message, status=resp.status_code, code=code)
+
+    return resp.json()
+
+
+async def async_request(
+    base_url: str,
+    agent: str,
+    method: str,
+    path: str,
+    body: dict[str, Any] | None = None,
+    extra_headers: dict[str, str] | None = None,
+    timeout: float = 10.0,
+) -> Any:
+    url = f"{base_url}{path}"
+    headers = {"Content-Type": "application/json", **(extra_headers or {})}
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.request(method, url, json=body, headers=headers)
+    except httpx.RequestError as exc:
+        raise SapixNetworkError(exc) from exc
+
+    if not resp.is_success:
+        message = f"HTTP {resp.status_code}"
+        code: str | None = None
+        try:
+            data = resp.json()
+            message = data.get("error", message)
+            code = data.get("code")
+        except Exception:
+            pass
+        raise SapixError(message, status=resp.status_code, code=code)
+
+    return resp.json()

sapixdb-0.1.0/sapixdb/_types.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class WriteResult:
+    id: str
+    hash: str
+    prev_hash: str | None
+    timestamp: str
+    collection: str
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Any]) -> "WriteResult":
+        return cls(
+            id=d["id"],
+            hash=d["hash"],
+            prev_hash=d.get("prev_hash"),
+            timestamp=d["timestamp"],
+            collection=d["collection"],
+        )
+
+
+@dataclass
+class NucleotideRecord(Generic[T]):
+    id: str
+    data: T
+    timestamp: str
+    hash: str
+    prev_hash: str | None
+    collection: str
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Any]) -> "NucleotideRecord[Any]":
+        return cls(
+            id=d["id"],
+            data=d["data"],
+            timestamp=d["timestamp"],
+            hash=d["hash"],
+            prev_hash=d.get("prev_hash"),
+            collection=d["collection"],
+        )
+
+
+@dataclass
+class GraphEdge:
+    src: str
+    dst: str
+    edge_type: str
+    weight: float
+    timestamp_hlc: int | None = None
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Any]) -> "GraphEdge":
+        return cls(
+            src=d["src"],
+            dst=d["dst"],
+            edge_type=d["edge_type"],
+            weight=d.get("weight", 1.0),
+            timestamp_hlc=d.get("timestamp_hlc"),
+        )
+
+
+@dataclass
+class TraverseResult:
+    nodes: list[NucleotideRecord[Any]]
+    edges: list[GraphEdge]
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Any]) -> "TraverseResult":
+        return cls(
+            nodes=[NucleotideRecord._from_dict(n) for n in d.get("nodes", [])],
+            edges=[GraphEdge._from_dict(e) for e in d.get("edges", [])],
+        )
+
+
+@dataclass
+class HealthResponse:
+    status: str
+    agent: str
+
+    @classmethod
+    def _from_dict(cls, d: dict[str, Any]) -> "HealthResponse":
+        return cls(status=d["status"], agent=d["agent"])

sapixdb-0.1.0/sapixdb/client.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+from typing import Any
+from .collection import CollectionClient, AsyncCollectionClient
+from .graph import GraphClient, AsyncGraphClient
+from ._types import WriteResult, HealthResponse
+from ._http import request, async_request
+
+
+class SapixClient:
+    """
+    Synchronous SapixDB client.
+
+    Usage::
+
+        from sapixdb import SapixClient
+
+        db = SapixClient(url="http://localhost:7475", agent="my-app")
+        record = db.collection("products").write({"name": "T-Shirt", "price": 29.99})
+        products = db.collection("products").latest()
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        agent: str,
+        headers: dict[str, str] | None = None,
+        timeout: float = 10.0,
+    ):
+        self._base_url = url.rstrip("/")
+        self._agent = agent
+        self._headers = headers or {}
+        self._timeout = timeout
+        self.graph = GraphClient(self._base_url, self._agent, self._headers, self._timeout)
+
+    def collection(self, name: str) -> CollectionClient:
+        """Access a collection by name. Collections are created on first write."""
+        return CollectionClient(self._base_url, self._agent, name, self._headers, self._timeout)
+
+    def ingest(self, collection: str, data: dict[str, Any]) -> WriteResult:
+        """
+        Write via the ingest endpoint — for AI agents, webhooks, and pipelines.
+        Supports optional dual-write to Supabase if configured on the server.
+        """
+        raw = request(self._base_url, self._agent, "POST",
+                      f"/v1/{self._agent}/ingest",
+                      {"collection": collection, "data": data},
+                      self._headers, self._timeout)
+        return WriteResult._from_dict(raw)
+
+    def health(self) -> HealthResponse:
+        """Check that the SapixDB agent is reachable. Raises on failure."""
+        raw = request(self._base_url, self._agent, "GET", "/v1/health",
+                      None, self._headers, self._timeout)
+        return HealthResponse._from_dict(raw)
+
+    def ping(self) -> bool:
+        """Returns True if the agent is healthy. Never raises."""
+        try:
+            return self.health().status == "ok"
+        except Exception:
+            return False
+
+
+class AsyncSapixClient:
+    """
+    Async SapixDB client for use with asyncio / FastAPI / etc.
+
+    Usage::
+
+        from sapixdb import AsyncSapixClient
+
+        async def main():
+            db = AsyncSapixClient(url="http://localhost:7475", agent="my-app")
+            record = await db.collection("products").write({"name": "T-Shirt"})
+
+        # Or as an async context manager:
+        async with AsyncSapixClient(url="...", agent="...") as db:
+            record = await db.collection("products").write({...})
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str,
+        agent: str,
+        headers: dict[str, str] | None = None,
+        timeout: float = 10.0,
+    ):
+        self._base_url = url.rstrip("/")
+        self._agent = agent
+        self._headers = headers or {}
+        self._timeout = timeout
+        self.graph = AsyncGraphClient(self._base_url, self._agent, self._headers, self._timeout)
+
+    async def __aenter__(self) -> "AsyncSapixClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        pass
+
+    def collection(self, name: str) -> AsyncCollectionClient:
+        return AsyncCollectionClient(self._base_url, self._agent, name, self._headers, self._timeout)
+
+    async def ingest(self, collection: str, data: dict[str, Any]) -> WriteResult:
+        raw = await async_request(self._base_url, self._agent, "POST",
+                                  f"/v1/{self._agent}/ingest",
+                                  {"collection": collection, "data": data},
+                                  self._headers, self._timeout)
+        return WriteResult._from_dict(raw)
+
+    async def health(self) -> HealthResponse:
+        raw = await async_request(self._base_url, self._agent, "GET", "/v1/health",
+                                  None, self._headers, self._timeout)
+        return HealthResponse._from_dict(raw)
+
+    async def ping(self) -> bool:
+        try:
+            return (await self.health()).status == "ok"
+        except Exception:
+            return False

sapixdb-0.1.0/sapixdb/collection.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+from typing import Any
+from ._types import NucleotideRecord, WriteResult
+from ._errors import SapixNotFoundError, SapixError
+from ._http import request, async_request
+
+
+class CollectionQuery:
+    """Time-scoped read-only view of a collection."""
+
+    def __init__(self, base_url: str, agent: str, name: str, as_of: str, headers: dict, timeout: float):
+        self._base_url = base_url
+        self._agent = agent
+        self._name = name
+        self._as_of = as_of
+        self._headers = headers
+        self._timeout = timeout
+
+    def _query(self, *, latest: bool, filter: dict[str, Any] | None = None,
+               limit: int | None = None, offset: int | None = None) -> list[NucleotideRecord]:
+        body: dict[str, Any] = {"collection": self._name, "latest": latest, "as_of": self._as_of}
+        if filter:
+            body["filter"] = filter
+        if limit is not None:
+            body["limit"] = limit
+        if offset is not None:
+            body["offset"] = offset
+        data = request(self._base_url, self._agent, "POST",
+                       f"/v1/{self._agent}/strand/query", body, self._headers, self._timeout)
+        return [NucleotideRecord._from_dict(r) for r in data.get("results", [])]
+
+    def latest(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        return self._query(latest=True, filter=filter, limit=limit)
+
+    def all(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        return self._query(latest=False, filter=filter, limit=limit)
+
+    def find(self, filter: dict[str, Any], *, limit: int | None = None) -> list[NucleotideRecord]:
+        return self._query(latest=True, filter=filter, limit=limit)
+
+    def find_one(self, filter: dict[str, Any]) -> NucleotideRecord | None:
+        results = self._query(latest=True, filter=filter, limit=1)
+        return results[0] if results else None
+
+
+class AsyncCollectionQuery:
+    """Async time-scoped read-only view of a collection."""
+
+    def __init__(self, base_url: str, agent: str, name: str, as_of: str, headers: dict, timeout: float):
+        self._base_url = base_url
+        self._agent = agent
+        self._name = name
+        self._as_of = as_of
+        self._headers = headers
+        self._timeout = timeout
+
+    async def _query(self, *, latest: bool, filter: dict[str, Any] | None = None,
+                     limit: int | None = None) -> list[NucleotideRecord]:
+        body: dict[str, Any] = {"collection": self._name, "latest": latest, "as_of": self._as_of}
+        if filter:
+            body["filter"] = filter
+        if limit is not None:
+            body["limit"] = limit
+        data = await async_request(self._base_url, self._agent, "POST",
+                                   f"/v1/{self._agent}/strand/query", body, self._headers, self._timeout)
+        return [NucleotideRecord._from_dict(r) for r in data.get("results", [])]
+
+    async def latest(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        return await self._query(latest=True, filter=filter, limit=limit)
+
+    async def all(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        return await self._query(latest=False, filter=filter, limit=limit)
+
+    async def find(self, filter: dict[str, Any], *, limit: int | None = None) -> list[NucleotideRecord]:
+        return await self._query(latest=True, filter=filter, limit=limit)
+
+    async def find_one(self, filter: dict[str, Any]) -> NucleotideRecord | None:
+        results = await self._query(latest=True, filter=filter, limit=1)
+        return results[0] if results else None
+
+
+class CollectionClient:
+    def __init__(self, base_url: str, agent: str, name: str, headers: dict, timeout: float):
+        self._base_url = base_url
+        self._agent = agent
+        self._name = name
+        self._headers = headers
+        self._timeout = timeout
+
+    def as_of(self, timestamp: str) -> CollectionQuery:
+        """Scope all reads to a specific point in time. Returns a CollectionQuery."""
+        return CollectionQuery(self._base_url, self._agent, self._name,
+                               timestamp, self._headers, self._timeout)
+
+    def write(self, data: dict[str, Any]) -> WriteResult:
+        raw = request(self._base_url, self._agent, "POST",
+                      f"/v1/{self._agent}/strand/write",
+                      {"collection": self._name, "data": data},
+                      self._headers, self._timeout)
+        return WriteResult._from_dict(raw)
+
+    def write_batch(self, records: list[dict[str, Any]]) -> list[WriteResult]:
+        return [self.write(r) for r in records]
+
+    def get(self, record_id: str) -> NucleotideRecord:
+        try:
+            raw = request(self._base_url, self._agent, "GET",
+                          f"/v1/{self._agent}/strand/{record_id}",
+                          None, self._headers, self._timeout)
+            return NucleotideRecord._from_dict(raw)
+        except SapixError as e:
+            if e.status == 404:
+                raise SapixNotFoundError(record_id) from e
+            raise
+
+    def latest(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        body: dict[str, Any] = {"collection": self._name, "latest": True}
+        if filter:
+            body["filter"] = filter
+        if limit is not None:
+            body["limit"] = limit
+        data = request(self._base_url, self._agent, "POST",
+                       f"/v1/{self._agent}/strand/query", body, self._headers, self._timeout)
+        return [NucleotideRecord._from_dict(r) for r in data.get("results", [])]
+
+    def history(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        body: dict[str, Any] = {"collection": self._name, "latest": False}
+        if filter:
+            body["filter"] = filter
+        if limit is not None:
+            body["limit"] = limit
+        data = request(self._base_url, self._agent, "POST",
+                       f"/v1/{self._agent}/strand/query", body, self._headers, self._timeout)
+        return [NucleotideRecord._from_dict(r) for r in data.get("results", [])]
+
+    def find(self, filter: dict[str, Any], *, limit: int | None = None) -> list[NucleotideRecord]:
+        return self.latest(filter=filter, limit=limit)
+
+    def find_one(self, filter: dict[str, Any]) -> NucleotideRecord | None:
+        results = self.latest(filter=filter, limit=1)
+        return results[0] if results else None
+
+
+class AsyncCollectionClient:
+    def __init__(self, base_url: str, agent: str, name: str, headers: dict, timeout: float):
+        self._base_url = base_url
+        self._agent = agent
+        self._name = name
+        self._headers = headers
+        self._timeout = timeout
+
+    def as_of(self, timestamp: str) -> AsyncCollectionQuery:
+        return AsyncCollectionQuery(self._base_url, self._agent, self._name,
+                                    timestamp, self._headers, self._timeout)
+
+    async def write(self, data: dict[str, Any]) -> WriteResult:
+        raw = await async_request(self._base_url, self._agent, "POST",
+                                  f"/v1/{self._agent}/strand/write",
+                                  {"collection": self._name, "data": data},
+                                  self._headers, self._timeout)
+        return WriteResult._from_dict(raw)
+
+    async def write_batch(self, records: list[dict[str, Any]]) -> list[WriteResult]:
+        import asyncio
+        return list(await asyncio.gather(*[self.write(r) for r in records]))
+
+    async def get(self, record_id: str) -> NucleotideRecord:
+        try:
+            raw = await async_request(self._base_url, self._agent, "GET",
+                                      f"/v1/{self._agent}/strand/{record_id}",
+                                      None, self._headers, self._timeout)
+            return NucleotideRecord._from_dict(raw)
+        except SapixError as e:
+            if e.status == 404:
+                raise SapixNotFoundError(record_id) from e
+            raise
+
+    async def latest(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        body: dict[str, Any] = {"collection": self._name, "latest": True}
+        if filter:
+            body["filter"] = filter
+        if limit is not None:
+            body["limit"] = limit
+        data = await async_request(self._base_url, self._agent, "POST",
+                                   f"/v1/{self._agent}/strand/query", body, self._headers, self._timeout)
+        return [NucleotideRecord._from_dict(r) for r in data.get("results", [])]
+
+    async def history(self, *, filter: dict[str, Any] | None = None, limit: int | None = None) -> list[NucleotideRecord]:
+        body: dict[str, Any] = {"collection": self._name, "latest": False}
+        if filter:
+            body["filter"] = filter
+        if limit is not None:
+            body["limit"] = limit
+        data = await async_request(self._base_url, self._agent, "POST",
+                                   f"/v1/{self._agent}/strand/query", body, self._headers, self._timeout)
+        return [NucleotideRecord._from_dict(r) for r in data.get("results", [])]
+
+    async def find(self, filter: dict[str, Any], *, limit: int | None = None) -> list[NucleotideRecord]:
+        return await self.latest(filter=filter, limit=limit)
+
+    async def find_one(self, filter: dict[str, Any]) -> NucleotideRecord | None:
+        results = await self.latest(filter=filter, limit=1)
+        return results[0] if results else None

sapixdb-0.1.0/sapixdb/graph.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+from typing import Any
+from ._types import GraphEdge, TraverseResult, NucleotideRecord
+from ._http import request, async_request
+
+
+class GraphClient:
+    def __init__(self, base_url: str, agent: str, headers: dict, timeout: float):
+        self._base_url = base_url
+        self._agent = agent
+        self._headers = headers
+        self._timeout = timeout
+
+    def add_edge(self, src: str, dst: str, edge_type: str, weight: float = 1.0) -> None:
+        request(self._base_url, self._agent, "POST",
+                f"/v1/{self._agent}/graph/edge",
+                {"src": src, "dst": dst, "edge_type": edge_type, "weight": weight},
+                self._headers, self._timeout)
+
+    def remove_edge(self, src: str, dst: str, edge_type: str) -> None:
+        request(self._base_url, self._agent, "DELETE",
+                f"/v1/{self._agent}/graph/edge",
+                {"src": src, "dst": dst, "edge_type": edge_type},
+                self._headers, self._timeout)
+
+    def relate(self, src: str, dst: str, edge_type: str, weight: float = 1.0) -> None:
+        """Convenience alias for add_edge with a readable name."""
+        self.add_edge(src, dst, edge_type, weight)
+
+    def traverse(self, from_id: str, *, depth: int = 1,
+                 direction: str = "outbound") -> TraverseResult:
+        data = request(self._base_url, self._agent, "GET",
+                       f"/v1/{self._agent}/graph/traverse/{from_id}"
+                       f"?depth={depth}&direction={direction}",
+                       None, self._headers, self._timeout)
+        return TraverseResult._from_dict(data)
+
+    def neighbors(self, node_id: str,
+                  direction: str = "outbound") -> list[NucleotideRecord]:
+        return self.traverse(node_id, depth=1, direction=direction).nodes
+
+    def edges(self, node_id: str) -> list[GraphEdge]:
+        return self.traverse(node_id, depth=1).edges
+
+
+class AsyncGraphClient:
+    def __init__(self, base_url: str, agent: str, headers: dict, timeout: float):
+        self._base_url = base_url
+        self._agent = agent
+        self._headers = headers
+        self._timeout = timeout
+
+    async def add_edge(self, src: str, dst: str, edge_type: str, weight: float = 1.0) -> None:
+        await async_request(self._base_url, self._agent, "POST",
+                            f"/v1/{self._agent}/graph/edge",
+                            {"src": src, "dst": dst, "edge_type": edge_type, "weight": weight},
+                            self._headers, self._timeout)
+
+    async def remove_edge(self, src: str, dst: str, edge_type: str) -> None:
+        await async_request(self._base_url, self._agent, "DELETE",
+                            f"/v1/{self._agent}/graph/edge",
+                            {"src": src, "dst": dst, "edge_type": edge_type},
+                            self._headers, self._timeout)
+
+    async def relate(self, src: str, dst: str, edge_type: str, weight: float = 1.0) -> None:
+        await self.add_edge(src, dst, edge_type, weight)
+
+    async def traverse(self, from_id: str, *, depth: int = 1,
+                       direction: str = "outbound") -> TraverseResult:
+        data = await async_request(self._base_url, self._agent, "GET",
+                                   f"/v1/{self._agent}/graph/traverse/{from_id}"
+                                   f"?depth={depth}&direction={direction}",
+                                   None, self._headers, self._timeout)
+        return TraverseResult._from_dict(data)
+
+    async def neighbors(self, node_id: str, direction: str = "outbound") -> list[NucleotideRecord]:
+        return (await self.traverse(node_id, depth=1, direction=direction)).nodes
+
+    async def edges(self, node_id: str) -> list[GraphEdge]:
+        return (await self.traverse(node_id, depth=1)).edges