swarm-analytics 0.1.0__py3-none-any.whl

swarm_analytics/__init__.py

@@ -0,0 +1,32 @@
+"""swarm_analytics — typed client for the OpenSwarm product-analytics ingest API.
+
+The event payload models under ``swarm_analytics`` are vendored verbatim from the
+analytics service and re-exported here, so callers validate against the exact
+schema the server enforces.
+"""
+
+from __future__ import annotations
+
+from ._generated.models import *  # noqa: F401,F403
+from ._generated.models import __all__ as _model_all
+from .client import AnalyticsClient
+from .errors import (
+    AnalyticsError,
+    AuthError,
+    RateLimited,
+    TransportError,
+    ValidationRejected,
+)
+from .spool import SqliteSpool, Spool
+
+__all__ = [
+    "AnalyticsClient",
+    "AnalyticsError",
+    "AuthError",
+    "RateLimited",
+    "TransportError",
+    "ValidationRejected",
+    "SqliteSpool",
+    "Spool",
+    *_model_all,
+]

swarm_analytics/_generated/__init__.py

@@ -0,0 +1 @@
+"""Generated SDK surface (do not edit)."""

swarm_analytics/_generated/endpoints.py

@@ -0,0 +1,71 @@
+"""Typed endpoint namespaces (generated — do not edit)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from ..transport import Transport
+from .models.agent import AgentMessage
+
+class AgentNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+
+    def create(self, *, id: str, name: str | None = None, dashboard_id: str | None = None) -> None:
+        self.t.send("events.agent.create", {"id": id, "name": name, "dashboard_id": dashboard_id})
+
+
+    def message(self, *, agent_id: str, seq: int, message: AgentMessage) -> None:
+        self.t.send("events.agent.message", {"agent_id": agent_id, "seq": seq, "message": message})
+
+
+class AppLifecycleNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+
+    def closed(self) -> None:
+        self.t.send("events.app_lifecycle.closed", {})
+
+
+    def opened(self, *, os: str, os_version: str, timezone: str | None = None, locale: str | None = None, app_version: str) -> None:
+        self.t.send("events.app_lifecycle.opened", {"os": os, "os_version": os_version, "timezone": timezone, "locale": locale, "app_version": app_version})
+
+
+class DashboardNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+
+    def event(self, *, dashboard_id: str, action: Literal['open', 'close', 'create', 'delete']) -> None:
+        self.t.send("events.dashboard.event", {"dashboard_id": dashboard_id, "action": action})
+
+
+class OnboardingNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+
+    def step(self, *, step_id: str, status: Literal['started', 'completed', 'abandoned']) -> None:
+        self.t.send("events.onboarding.step", {"step_id": step_id, "status": status})
+
+
+class EventsNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+        self.agent: AgentNS = AgentNS(t)
+        self.app_lifecycle: AppLifecycleNS = AppLifecycleNS(t)
+        self.dashboard: DashboardNS = DashboardNS(t)
+        self.onboarding: OnboardingNS = OnboardingNS(t)
+
+
+class IdentifyNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+
+    def link_email(self, *, email: str) -> None:
+        self.t.send("identify.link_email", {"email": email})
+
+
+class LogsNS:
+    def __init__(self, t: Transport) -> None:
+        self.t = t
+
+    def write(self, *, tag: str, subtag: str | None = None, data: Any = None) -> None:
+        self.t.send("logs.write", {"tag": tag, "subtag": subtag, "data": data})

swarm_analytics/_generated/models/__init__.py

@@ -0,0 +1,23 @@
+"""Vendored payload models (generated — do not edit)."""
+
+from ._shared import DeviceContext, IngestMeta
+from .agent import AgentCreated, AgentMessage, AgentMessageEvent
+from .app_lifecycle import AppOpened
+from .dashboard import DashboardEvent
+from .identify import IdentifyRequest, RegisterRequest
+from .logs import LogWrite
+from .onboarding import OnboardingStep
+
+__all__ = [
+    "AgentCreated",
+    "AgentMessage",
+    "AgentMessageEvent",
+    "AppOpened",
+    "DashboardEvent",
+    "DeviceContext",
+    "IdentifyRequest",
+    "IngestMeta",
+    "LogWrite",
+    "OnboardingStep",
+    "RegisterRequest",
+]

swarm_analytics/_generated/models/_shared.py

@@ -0,0 +1,31 @@
+"""Base payload models shared by every event subapp.
+
+Identity (install_id / user_id) is NEVER part of a payload — it is resolved
+server-side from the Authorization header by the auth dependency. Every payload
+carries only the per-request fields (ts, submission_id) via IngestMeta.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class IngestMeta(BaseModel):
+    """Minimal per-request metadata shared by every event payload.
+
+    Doubles as the payload type for events that carry no extra args.
+    """
+
+    ts: float = Field(..., description="Client-side unix timestamp (seconds)")
+    submission_id: str = Field(..., description="UUID for idempotency dedup")
+
+
+class DeviceContext(BaseModel):
+    """The four attributes whose combination defines a device_context row.
+
+    app_version and geo are NOT here — app_version lives on the spine (carried by
+    app.opened), geo is derived from edge headers per event.
+    """
+
+    os: str
+    os_version: str
+    timezone: str | None = None
+    locale: str | None = None

swarm_analytics/_generated/models/agent.py

@@ -0,0 +1,68 @@
+"""Typed payloads for the agent event subapp.
+
+A agent is captured incrementally over two endpoints, mirroring the agent's
+real lifecycle:
+
+  - agent.created — emitted once when the agent is created. Carries only the
+    scalar agent fields (id/name/dashboard_id); no transcript yet.
+  - agent.message — emitted once per transcript message as it happens. Carries
+    a single message plus a agent-scoped `seq` for ordering.
+
+The one genuinely dynamic leaf — message `content` — is typed as `JsonValue`
+(Pydantic's recursive JSON type), never `Any`. Unmodeled fields from the desktop
+dump are ignored (the client may still ship a richer object); we persist only the
+trimmed columns
+"""
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, JsonValue, ConfigDict
+
+from ._shared import IngestMeta
+
+
+class AgentMessage(BaseModel):
+    """One transcript message. `content` is polymorphic (text, content blocks, or
+    a tool payload) so it's typed as JsonValue. `error` is a terminal role used to
+    infer agent outcome at query time."""
+
+    model_config = ConfigDict(validate_assignment=True) # Ensures you can't reassign new types to variables
+
+    id: str
+    role: Literal[
+        "user", "assistant", "tool_call", "tool_result", "system", "thinking", "error"
+    ]
+    content: JsonValue = None # NOTE: JsonValue is a descriminated union so it can be None
+    parent_id: Optional[str] = None
+    provider: Optional[str] = None
+    model: Optional[str] = None
+    thinking_level: Optional[Literal["off", "low", "medium", "high", "auto"]] = None
+
+    model_config = {"populate_by_name": True}
+
+
+class AgentCreated(IngestMeta):
+    """POST /created — the scalar agent record, sent when the agent is
+    created. No transcript: messages arrive separately via POST /message."""
+
+    model_config = ConfigDict(validate_assignment=True) # Ensures you can't reassign new types to variables
+
+    agent_id: str = Field(..., alias="id")
+    name: Optional[str] = None
+    dashboard_id: Optional[str] = None
+
+    model_config = {"populate_by_name": True}
+
+
+class AgentMessageEvent(IngestMeta):
+    """POST /message — one transcript message appended to an existing agent.
+
+    `seq` is a agent-scoped, client-supplied ordinal; it is the durable
+    ordering key (do not rely on server receive time, since messages can be
+    streamed/retried out of order)."""
+
+    model_config = ConfigDict(validate_assignment=True) # Ensures you can't reassign new types to variables
+
+    agent_id: str
+    seq: int
+    message: AgentMessage

swarm_analytics/_generated/models/app_lifecycle.py

@@ -0,0 +1,15 @@
+"""Typed payloads for the app_lifecycle event subapp.
+
+Only open/close survive. app.opened carries the four device-context attributes
+(via DeviceContext) plus app_version, which is stamped on the spine. app.closed
+is a bare meta event.
+"""
+
+from ._shared import DeviceContext, IngestMeta
+
+
+class AppOpened(IngestMeta, DeviceContext):
+    """POST /opened — sent once per launch. Carries the device fields that define
+    the device_context row, plus app_version (stamped on the spine)."""
+
+    app_version: str

swarm_analytics/_generated/models/dashboard.py

@@ -0,0 +1,16 @@
+"""Typed payload for the dashboard event subapp.
+
+One consolidated route carries the lifecycle action in the body; the
+event_dashboard.event_type CHECK constraint already allows these four values.
+"""
+
+from typing import Literal
+
+from ._shared import IngestMeta
+
+
+class DashboardEvent(IngestMeta):
+    """POST "" — one dashboard lifecycle action (open/close/create/delete)."""
+
+    dashboard_id: str
+    action: Literal["open", "close", "create", "delete"]

swarm_analytics/_generated/models/identify.py

@@ -0,0 +1,22 @@
+"""Request/response models for the identify SubApp.
+
+Kept in a dedicated models.py (like every other domain) so the generated SDK can
+vendor them verbatim. These are NOT events: they carry no IngestMeta (ts /
+submission_id). Identity for authed routes is resolved from the bearer token, so
+only the email travels in the link body.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class RegisterRequest(BaseModel):
+    install_id: str = Field(..., min_length=1, max_length=128)
+
+
+class RegisterResponse(BaseModel):
+    token: str
+    install_id: str
+
+
+class IdentifyRequest(BaseModel):
+    email: str = Field(..., min_length=1, max_length=320)

swarm_analytics/_generated/models/logs.py

@@ -0,0 +1,17 @@
+"""Payload model for the logs SubApp.
+
+Reuses the shared IngestMeta (ts + submission_id); identity is resolved
+server-side from the Authorization header, never from the body. `data` is any
+JSON-serializable value — it is serialized with to_json() and stored as opaque
+JSON text (DB-enforced via json_valid()).
+"""
+
+from typing import Any
+
+from ._shared import IngestMeta
+
+
+class LogWrite(IngestMeta):
+    tag: str
+    subtag: str | None = None
+    data: Any = None

swarm_analytics/_generated/models/onboarding.py

@@ -0,0 +1,16 @@
+"""Typed payload for the onboarding event subapp.
+
+The whole funnel collapses to one event: a step transition carrying which step
+and its funnel status.
+"""
+
+from typing import Literal
+
+from ._shared import IngestMeta
+
+
+class OnboardingStep(IngestMeta):
+    """POST /step — one onboarding step transition."""
+
+    step_id: str
+    status: Literal["started", "completed", "abandoned"]

swarm_analytics/_generated/routes.py

@@ -0,0 +1,22 @@
+"""Route table (generated — do not edit)."""
+
+from ..transport import Route
+from .models._shared import IngestMeta
+from .models.agent import AgentCreated, AgentMessageEvent
+from .models.app_lifecycle import AppOpened
+from .models.dashboard import DashboardEvent
+from .models.identify import IdentifyRequest, RegisterRequest
+from .models.logs import LogWrite
+from .models.onboarding import OnboardingStep
+
+ROUTES: dict[str, Route] = {
+    "events.agent.create": Route("POST", "/public/events/agent/create", AgentCreated, True, "product"),
+    "events.agent.message": Route("POST", "/public/events/agent/message", AgentMessageEvent, True, "product"),
+    "events.app_lifecycle.closed": Route("POST", "/public/events/app_lifecycle/closed", IngestMeta, True, "product"),
+    "events.app_lifecycle.opened": Route("POST", "/public/events/app_lifecycle/opened", AppOpened, True, "product"),
+    "events.dashboard.event": Route("POST", "/public/events/dashboard/event", DashboardEvent, True, "product"),
+    "events.onboarding.step": Route("POST", "/public/events/onboarding/step", OnboardingStep, True, "product"),
+    "identify.link_email": Route("POST", "/public/identify/link_email_to_install", IdentifyRequest, True, "identity"),
+    "identify.register": Route("POST", "/public/identify/create_install_token", RegisterRequest, False, "bootstrap"),
+    "logs.write": Route("POST", "/public/logs", LogWrite, True, "diagnostic"),
+}

swarm_analytics/client.py

@@ -0,0 +1,83 @@
+"""The public client.
+
+``AnalyticsClient`` ties the background transport to the generated, typed
+endpoint namespaces. Identity is the bearer token; no method ever takes an
+install_id/user_id. ``ts``/``submission_id`` are auto-filled by the transport, so
+they are absent from every signature.
+
+Bootstrap (``register``) is the one unauthenticated, *blocking* call: a fresh
+install has no token, so this is how it mints one.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ._generated.endpoints import EventsNS, IdentifyNS, LogsNS
+from ._generated.routes import ROUTES
+from .errors import AuthError, TransportError
+from .spool import Spool
+from .transport import DropCallback, Transport
+
+
+class AnalyticsClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str,
+        mode: str = "full",
+        spool: Optional[Spool] = None,
+        http_client: Optional[httpx.Client] = None,
+        max_attempts: int = 8,
+        on_drop: Optional[DropCallback] = None,
+    ) -> None:
+        self.transport = Transport(
+            base_url=base_url,
+            token=token,
+            routes=ROUTES,
+            mode=mode,
+            spool=spool,
+            http_client=http_client,
+            max_attempts=max_attempts,
+            on_drop=on_drop,
+        )
+        self.events: EventsNS = EventsNS(self.transport)
+        self.logs: LogsNS = LogsNS(self.transport)
+        self.identify: IdentifyNS = IdentifyNS(self.transport)
+
+    @classmethod
+    def register(cls, *, base_url: str, install_id: str, timeout: float = 10.0) -> str:
+        """Mint and return an install token (unauthenticated, blocking).
+
+        Call once on first launch, persist the returned token, and pass it to the
+        constructor on every subsequent run.
+        """
+        route = ROUTES["identify.register"]
+        url = base_url.rstrip("/") + route.path
+        body = route.model(install_id=install_id).model_dump(by_alias=True, mode="json")
+        with httpx.Client(timeout=timeout) as client:
+            resp = client.post(url, json=body)
+        if resp.status_code == 401:
+            raise AuthError("register rejected")
+        if resp.status_code >= 400:
+            raise TransportError(f"register failed: {resp.status_code} {resp.text}")
+        return resp.json()["token"]
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        """Block until pending events are delivered (or timeout). Call before exit."""
+        return self.transport.flush(timeout)
+
+    def close(self) -> None:
+        self.transport.close()
+
+    def __enter__(self) -> "AnalyticsClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        try:
+            self.flush(timeout=2.0)
+        finally:
+            self.close()

swarm_analytics/errors.py

@@ -0,0 +1,32 @@
+"""Typed exception hierarchy for the SDK.
+
+Mirrors the server's retryable/non-retryable split so callers (and the transport
+worker) can branch on category rather than raw status codes.
+"""
+
+from __future__ import annotations
+
+
+class AnalyticsError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class AuthError(AnalyticsError):
+    """401 — the bearer token is missing, malformed, or expired."""
+
+
+class RateLimited(AnalyticsError):
+    """429 — retryable; the worker backs off and retries."""
+
+
+class TransportError(AnalyticsError):
+    """5xx / timeout / network failure — retryable."""
+
+
+class ValidationRejected(AnalyticsError):
+    """422 — the server rejected the payload as malformed.
+
+    Should never happen in practice: the SDK validates against the same pydantic
+    models the server enforces, so a bad call raises pydantic's ``ValidationError``
+    locally, before anything is sent. Surfaced for completeness only.
+    """

swarm_analytics/spool.py

@@ -0,0 +1,92 @@
+"""Optional durable outbox.
+
+A spool persists not-yet-delivered events to disk so they survive a crash or an
+offline-then-quit. It is OFF by default: the transport uses an in-memory queue
+unless a spool is supplied, in which case undelivered events are lost on exit.
+
+The contract is intentionally tiny (add / remove / load). The default
+``SqliteSpool`` stores one row per record keyed by ``spool_key`` (the event's
+``submission_id`` when it has one), so a replay after restart reuses the same id
+and the server dedups any event that actually went out before the crash.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Spool(Protocol):
+    """Durable store for pending records. Implementations must be thread-safe."""
+
+    def add(self, spool_key: str, record: dict) -> None:
+        """Insert or replace the pending record under ``spool_key``."""
+
+    def remove(self, spool_key: str) -> None:
+        """Delete the record once it is delivered or permanently dropped."""
+
+    def load(self) -> list[tuple[str, dict]]:
+        """Return all pending ``(spool_key, record)`` pairs (called at startup)."""
+
+
+class SqliteSpool:
+    """A bounded, file-backed spool. Past ``max_bytes`` the oldest rows are pruned."""
+
+    def __init__(self, path: str, max_bytes: int = 50_000_000) -> None:
+        self.path = path
+        self.max_bytes = max_bytes
+        self.lock = threading.Lock()
+        self.conn = sqlite3.connect(path, check_same_thread=False)
+        self.conn.execute(
+            "CREATE TABLE IF NOT EXISTS spool ("
+            " spool_key TEXT PRIMARY KEY,"
+            " record TEXT NOT NULL,"
+            " created_at REAL NOT NULL DEFAULT (julianday('now')))"
+        )
+        self.conn.commit()
+
+    def add(self, spool_key: str, record: dict) -> None:
+        blob = json.dumps(record, separators=(",", ":"))
+        with self.lock:
+            self.conn.execute(
+                "INSERT OR REPLACE INTO spool (spool_key, record) VALUES (?, ?)",
+                (spool_key, blob),
+            )
+            self.conn.commit()
+            self.prune()
+
+    def remove(self, spool_key: str) -> None:
+        with self.lock:
+            self.conn.execute("DELETE FROM spool WHERE spool_key = ?", (spool_key,))
+            self.conn.commit()
+
+    def load(self) -> list[tuple[str, dict]]:
+        with self.lock:
+            rows = self.conn.execute(
+                "SELECT spool_key, record FROM spool ORDER BY rowid ASC"
+            ).fetchall()
+        return [(key, json.loads(blob)) for key, blob in rows]
+
+    def prune(self) -> None:
+        """Drop oldest rows while the DB file exceeds the byte cap. Caller holds the lock."""
+        page = self.conn.execute("PRAGMA page_size").fetchone()[0]
+        while True:
+            count = self.conn.execute("PRAGMA page_count").fetchone()[0]
+            if count * page <= self.max_bytes:
+                return
+            victims = self.conn.execute(
+                "SELECT spool_key FROM spool ORDER BY rowid ASC LIMIT 64"
+            ).fetchall()
+            if not victims:
+                return
+            self.conn.executemany(
+                "DELETE FROM spool WHERE spool_key = ?", victims
+            )
+            self.conn.commit()
+
+    def close(self) -> None:
+        with self.lock:
+            self.conn.close()

swarm_analytics/transport.py

@@ -0,0 +1,216 @@
+"""Sync surface, async delivery.
+
+The public client is fully synchronous and fire-and-forget: a call validates the
+payload on the *calling thread* (so a bad call raises immediately, in the
+caller's stack) and then hands a serialized record to a background worker thread
+that does the actual HTTP, with retry and optional durable spooling.
+
+Idempotency: ``submission_id`` is minted once, at enqueue time, and reused on
+every retry — including a replay loaded from the spool after a restart — so the
+server's ``(install_id, submission_id)`` dedup turns retries into no-ops.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+import httpx
+from pydantic import BaseModel
+
+from .spool import Spool
+
+# Delivery mode → which event categories are allowed through. "minimal" mutes
+# product telemetry while still letting identity/diagnostic/bootstrap flow.
+MUTED_IN_MINIMAL = frozenset({"product"})
+
+
+@dataclass(frozen=True)
+class Route:
+    """One ingest endpoint. Emitted into the generated route table."""
+
+    method: str
+    path: str
+    model: type[BaseModel]
+    auth: bool
+    category: str
+
+
+@dataclass
+class Record:
+    """A validated, serialized event in flight."""
+
+    route_key: str
+    body: dict
+    submission_id: Optional[str]
+    spool_key: str
+    attempts: int = 0
+
+
+DropCallback = Callable[[Record, Optional[int]], None]
+
+
+class Transport:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: Optional[str],
+        routes: dict[str, Route],
+        mode: str = "full",
+        spool: Optional[Spool] = None,
+        http_client: Optional[httpx.Client] = None,
+        max_attempts: int = 8,
+        backoff_base: float = 0.5,
+        backoff_cap: float = 30.0,
+        on_drop: Optional[DropCallback] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.routes = routes
+        self.mode = mode
+        self.spool = spool
+        self.client = http_client or httpx.Client(timeout=10.0)
+        self.owns_client = http_client is None
+        self.max_attempts = max_attempts
+        self.backoff_base = backoff_base
+        self.backoff_cap = backoff_cap
+        self.on_drop = on_drop
+
+        self.queue: "queue.Queue[Record]" = queue.Queue()
+        self.stopping = threading.Event()
+
+        # Resume anything left in the spool from a previous run (same submission_id).
+        if self.spool is not None:
+            for spool_key, rec in self.spool.load():
+                self.queue.put(
+                    Record(
+                        route_key=rec["route_key"],
+                        body=rec["body"],
+                        submission_id=rec.get("submission_id"),
+                        spool_key=spool_key,
+                        attempts=int(rec.get("attempts", 0)),
+                    )
+                )
+
+        self.worker = threading.Thread(
+            target=self.run, name="swarm-analytics", daemon=True
+        )
+        self.worker.start()
+
+    # --- enqueue path (caller thread) --------------------------------------
+
+    def enabled_for(self, category: str) -> bool:
+        if self.mode == "full":
+            return True
+        return category not in MUTED_IN_MINIMAL
+
+    def build_model(self, route: Route, fields: dict) -> BaseModel:
+        """Validate on the caller's thread, auto-filling per-request meta."""
+        data = dict(fields)
+        model_fields = route.model.model_fields
+        if "ts" in model_fields:
+            data.setdefault("ts", time.time())
+        if "submission_id" in model_fields:
+            data.setdefault("submission_id", str(uuid.uuid4()))
+        return route.model(**data)  # raises pydantic.ValidationError on bad input
+
+    def send(self, route_key: str, fields: dict) -> None:
+        route = self.routes[route_key]
+        if not self.enabled_for(route.category):
+            return
+        model = self.build_model(route, fields)
+        submission_id = getattr(model, "submission_id", None)
+        body = model.model_dump(by_alias=True, mode="json")
+        spool_key = submission_id or str(uuid.uuid4())
+        if self.spool is not None:
+            self.spool.add(spool_key, self.as_spool_record(route_key, body, submission_id, 0))
+        self.queue.put(
+            Record(route_key=route_key, body=body, submission_id=submission_id, spool_key=spool_key)
+        )
+
+    @staticmethod
+    def as_spool_record(route_key: str, body: dict, submission_id: Optional[str], attempts: int) -> dict:
+        return {"route_key": route_key, "body": body, "submission_id": submission_id, "attempts": attempts}
+
+    # --- delivery path (worker thread) -------------------------------------
+
+    def run(self) -> None:
+        while not self.stopping.is_set():
+            try:
+                rec = self.queue.get(timeout=0.2)
+            except queue.Empty:
+                continue
+            try:
+                self.deliver(rec)
+            finally:
+                self.queue.task_done()
+
+    def deliver(self, rec: Record) -> None:
+        route = self.routes[rec.route_key]
+        url = self.base_url + route.path
+        headers = {"Content-Type": "application/json"}
+        if route.auth and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        while True:
+            status = self.attempt(route.method, url, rec.body, headers)
+            if status is not None and 200 <= status < 300:
+                self.finish(rec)
+                return
+            if status is not None and status != 429 and not (500 <= status < 600):
+                # Permanent (4xx other than 429): bad data, not worth retrying.
+                self.drop(rec, status)
+                return
+            rec.attempts += 1
+            if rec.attempts >= self.max_attempts:
+                self.drop(rec, status)
+                return
+            if self.spool is not None:
+                self.spool.add(
+                    rec.spool_key,
+                    self.as_spool_record(rec.route_key, rec.body, rec.submission_id, rec.attempts),
+                )
+            delay = min(self.backoff_cap, self.backoff_base * (2 ** (rec.attempts - 1)))
+            # Wake early on shutdown; leave the record in the spool for next run.
+            if self.stopping.wait(delay):
+                return
+
+    def attempt(self, method: str, url: str, body: dict, headers: dict) -> Optional[int]:
+        """Return the HTTP status, or None for a network-level failure (retryable)."""
+        try:
+            resp = self.client.request(method, url, json=body, headers=headers)
+            return resp.status_code
+        except (httpx.TimeoutException, httpx.TransportError):
+            return None
+
+    def finish(self, rec: Record) -> None:
+        if self.spool is not None:
+            self.spool.remove(rec.spool_key)
+
+    def drop(self, rec: Record, status: Optional[int]) -> None:
+        if self.spool is not None:
+            self.spool.remove(rec.spool_key)
+        if self.on_drop is not None:
+            self.on_drop(rec, status)
+
+    # --- lifecycle ---------------------------------------------------------
+
+    def flush(self, timeout: Optional[float] = None) -> bool:
+        """Block until the queue drains (or timeout). Returns True if fully drained."""
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while self.queue.unfinished_tasks > 0:
+            if deadline is not None and time.monotonic() >= deadline:
+                return False
+            time.sleep(0.02)
+        return True
+
+    def close(self) -> None:
+        self.stopping.set()
+        self.worker.join(timeout=2.0)
+        if self.owns_client:
+            self.client.close()

swarm_analytics-0.1.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: swarm-analytics
+Version: 0.1.0
+Summary: Typed, auto-generated client for the OpenSwarm product-analytics ingest API.
+Author: Haik Decie
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/openswarm-ai/product-analytics-v1
+Project-URL: Source, https://github.com/openswarm-ai/product-analytics-v1
+Keywords: analytics,telemetry,openswarm,pydantic
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# swarm_analytics
+
+A typed, **auto-generated** Python client for the OpenSwarm product-analytics
+ingest API. It is the single network egress the desktop FastAPI backend imports to
+send analytics — identity comes from a bearer token, payloads are validated
+against the *exact* pydantic models the server enforces, and delivery is
+fire-and-forget with background retry.
+
+## Why it's hard to call wrong
+
+- **Identity is impossible to pass.** No method takes `install_id`/`user_id`; the
+  server resolves them from the token.
+- **Per-request meta is auto-filled.** `ts` and `submission_id` never appear in a
+  signature — the transport stamps them (and reuses `submission_id` on every
+  retry for idempotency).
+- **Enums stay enums.** `status`, `action`, `role`, etc. are `Literal`s. A bad
+  value raises `pydantic.ValidationError` synchronously, in your stack, before any
+  network I/O.
+- **Models are vendored verbatim** from the service, so the client validates with
+  the same schema the server uses.
+
+## Install
+
+```bash
+pip install ./sdk          # from the repo root
+```
+
+## Usage
+
+```python
+from swarm_analytics import AnalyticsClient, AgentMessage
+
+# One-time bootstrap on first launch (unauthenticated, blocking)
+token = AnalyticsClient.register(base_url="https://analytics.openswarm.ai", install_id=install_id)
+# persist `token` in settings; reuse forever
+
+client = AnalyticsClient(base_url="https://analytics.openswarm.ai", token=token)
+
+client.events.app_lifecycle.opened(os="darwin", os_version="25.3.0", app_version="1.2.0")
+client.events.agent.create(id="sess_123", name="Refactor auth", dashboard_id="dash_1")
+client.events.agent.message(agent_id="sess_123", seq=0,
+                            message=AgentMessage(id="m1", role="user", content="hello"))
+client.events.onboarding.step(step_id="connect_provider", status="completed")
+client.events.dashboard.event(dashboard_id="dash_1", action="create")
+client.logs.write(tag="agent", subtag="tool", data={"name": "shell"})
+client.identify.link_email(email="user@example.com")
+
+# On shutdown
+client.events.app_lifecycle.closed()
+client.flush(timeout=2.0)
+client.close()
+```
+
+### Durability (optional)
+
+By default events live in an in-memory queue and are lost if the process dies
+with deliveries pending. Pass a spool for crash/offline durability:
+
+```python
+from swarm_analytics import SqliteSpool
+client = AnalyticsClient(base_url=..., token=..., spool=SqliteSpool("service_spool.db"))
+```
+
+### Opt-out
+
+```python
+client = AnalyticsClient(base_url=..., token=..., mode="minimal")  # mutes product events; diagnostics still flow
+```
+
+## Regenerating (auto-generated — do not hand-edit `_generated/`)
+
+The models, route table, and namespaces under `src/swarm_analytics/_generated/`
+are produced from the live service. Regenerate whenever the backend's ingest
+models or routes change:
+
+```bash
+PYTHONPATH=<repo_root> python sdk/generate.py
+```
+
+`ROUTE_SPECS` in `generate.py` (nice method name + category per endpoint) is the
+only human input; it is cross-checked against the live app, so a new or removed
+endpoint fails generation rather than drifting silently.
+
+### Drift check (CI)
+
+```bash
+PYTHONPATH=<repo_root> python sdk/generate.py --check
+```
+
+Exits non-zero if the committed `_generated/` output is stale. The same guard runs
+as `tests/test_drift.py`.
+
+## Tests
+
+```bash
+cd sdk && PYTHONPATH=<repo_root> python -m pytest tests -q
+```
+
+Covers synchronous validation, meta auto-fill, identity-from-token, idempotent
+`submission_id` reuse across retries, opt-out gating, the drift check, and an
+end-to-end pass through the real FastAPI app.

swarm_analytics-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+swarm_analytics/__init__.py,sha256=6qtDc8zHH1mDtEIigXaNcusoJKmkgFZtOPglpHGwGOM,806
+swarm_analytics/client.py,sha256=Dma3axRB1rHEWrOXHy6L15SkHmj3L_hEUXhiliy02b8,2806
+swarm_analytics/errors.py,sha256=rdH8br9yzraWTmfx60JblWrgDDpTGt5wxGFvjD7EtZs,967
+swarm_analytics/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swarm_analytics/spool.py,sha256=ZnpFLmkt36Z19LdODtQh2aUiCF2Aw0khoDiMZW74caA,3407
+swarm_analytics/transport.py,sha256=l3aX2cDaYr3qp7aAcXdTNUrGoGsnsWbuBex8FBcyy3c,7806
+swarm_analytics/_generated/__init__.py,sha256=EuktMkT_XXZmiOXyXhQnVAtqEbEKpRRjqMiBRsEQOag,43
+swarm_analytics/_generated/endpoints.py,sha256=MgRzxgzY_g-RtiXhcsHGu1tEvUfVLGNFP1X3JtdjoUg,2437
+swarm_analytics/_generated/routes.py,sha256=uSaRbljGKrQ_z_QY_aT4ITrPM_NvKDr3Gft4lFZUUHM,1428
+swarm_analytics/_generated/models/__init__.py,sha256=lBL8104cb1CYeTTbe5KihlZOqBFi-GyAtAmaZ67_iKg,610
+swarm_analytics/_generated/models/_shared.py,sha256=zo04aZ0J4vdRAAV5dAInsj0bpeMv-9YfeqpdTx43OB4,1019
+swarm_analytics/_generated/models/agent.py,sha256=rTHBo_zT4lZcZIUXbqq6PFNoZS5dWkb4iL5MoprC0Mo,2553
+swarm_analytics/_generated/models/app_lifecycle.py,sha256=MqVT812KJw3WlYPkz3U2isuE8lwuk7hyg1V3q1jfeoA,512
+swarm_analytics/_generated/models/dashboard.py,sha256=Zsg_EKuLkp-bU5dfa2HUcN8y_iIKmMfXMTsJ3hp2RLs,459
+swarm_analytics/_generated/models/identify.py,sha256=FFCn6vpWylAoBAzw6Ay7hr8EIJTjdurVfG5FpR6R9jY,639
+swarm_analytics/_generated/models/logs.py,sha256=2LfYzU3VD8X4DlrOQtdXVnaGU2tNqGRBrGoiDwtUAK0,467
+swarm_analytics/_generated/models/onboarding.py,sha256=aCIwI_pCOgGwc-SypWhcTO0xFns2_vg7CT-UeEM23JY,386
+swarm_analytics-0.1.0.dist-info/licenses/LICENSE,sha256=6eKzD82yvZAYnQ2RgZoM-3nnkSqIP9Sq1fF8zm0O6QU,1067
+swarm_analytics-0.1.0.dist-info/METADATA,sha256=YWteQLJrysGsZmhTon1-Yduh40yFbTq0RmDNorLQoSk,4345
+swarm_analytics-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+swarm_analytics-0.1.0.dist-info/top_level.txt,sha256=_GZt1gb77qObV_e2nb7vWf-LMxDdDC124dr_Xc1taDI,16
+swarm_analytics-0.1.0.dist-info/RECORD,,

swarm_analytics-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

swarm_analytics-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haik Decie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

swarm_analytics-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+swarm_analytics