swarm-analytics 0.1.0__tar.gz

swarm_analytics-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,101 @@
+# 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/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "swarm-analytics"
+version = "0.1.0"
+description = "Typed, auto-generated client for the OpenSwarm product-analytics ingest API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Haik Decie" }]
+keywords = ["analytics", "telemetry", "openswarm", "pydantic"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+    "Intended Audience :: Developers",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+]
+
+[project.urls]
+Homepage = "https://github.com/openswarm-ai/product-analytics-v1"
+Source = "https://github.com/openswarm-ai/product-analytics-v1"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+swarm_analytics = ["py.typed"]

swarm_analytics-0.1.0/setup.cfg

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

swarm_analytics-0.1.0/src/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-0.1.0/src/swarm_analytics/_generated/__init__.py

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

swarm_analytics-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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"),
+}