zizkadb-sdk 0.2.1__tar.gz

zizkadb_sdk-0.2.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: zizkadb-sdk
+Version: 0.2.1
+Summary: ZizkaDB tells you when your agent stops behaving like itself. Causal lineage, time travel and behavioral baselines for any AI agent.
+Author-email: Zizka AI <hello@zizka.ai>
+License: AGPL-3.0
+Project-URL: Homepage, https://db.zizka.ai
+Project-URL: Documentation, https://db.zizka.ai/docs
+Project-URL: Repository, https://github.com/Zizka-ai/agentdb
+Project-URL: Issues, https://github.com/Zizka-ai/agentdb/issues
+Keywords: ai,agents,database,memory,llm,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# agentdb-sdk
+
+Python SDK for [AgentDB](https://agentdb.zizka.ai) — the operational database for AI agents.
+
+## Install
+
+```bash
+pip install agentdb-sdk
+```
+
+> **Note:** There is an unrelated package called `agentdb` on PyPI. Make sure to install `agentdb-sdk` (this package). The import is still `from agentdb import AgentDB`.
+
+## Quickstart
+
+```python
+from agentdb import AgentDB
+
+# Cloud (agentdb.zizka.ai)
+db = AgentDB("agdb_live_xxxx")
+
+# Self-hosted
+db = AgentDB(host="http://localhost:8000")
+```
+
+## Log an event
+
+```python
+result = await db.log(
+    agent="my-bot",
+    event="tool_call",
+    data={"tool": "search_web", "query": "competitor pricing"},
+)
+print(result.event_id)
+```
+
+## Link events causally
+
+```python
+# Log the user message
+msg = await db.log(agent="my-bot", event="user_message",
+                   data={"text": "why is my bill $200?"})
+
+# Log the tool call that happened BECAUSE of the message
+tool = await db.log(agent="my-bot", event="tool_call",
+                    data={"tool": "get_billing"},
+                    parent_id=msg.event_id)  # <-- causal link
+
+# Log the response that happened BECAUSE of the tool call
+await db.log(agent="my-bot", event="agent_response",
+             data={"text": "I found an anomaly in your account"},
+             parent_id=tool.event_id)
+```
+
+## Why did something happen?
+
+```python
+chain = await db.why(tool.event_id)
+chain.print()
+# user_message: {'text': 'why is my bill $200?'}  [14:32:01]
+#     └── tool_call: {'tool': 'get_billing'}       [14:32:02]
+#         └── agent_response: {'text': '...'}      [14:32:03]
+```
+
+## Semantic search
+
+```python
+results = await db.search("customer angry about billing")
+for event in results:
+    print(event.event, event.data)
+```
+
+## Time travel
+
+```python
+from datetime import datetime
+
+state = await db.at("my-bot", datetime(2026, 5, 1, 15, 0))
+print(state.state)
+```
+
+## Query events
+
+```python
+events = await db.query("my-bot", limit=100, event_type="tool_call")
+```
+
+## Self-host
+
+```bash
+git clone https://github.com/Zizka-ai/agentdb
+cd agentdb && cp .env.example .env
+docker-compose -f infra/docker-compose.yml up
+```
+
+## License
+
+AGPL-3.0

zizkadb_sdk-0.2.1/README.md

@@ -0,0 +1,97 @@
+# agentdb-sdk
+
+Python SDK for [AgentDB](https://agentdb.zizka.ai) — the operational database for AI agents.
+
+## Install
+
+```bash
+pip install agentdb-sdk
+```
+
+> **Note:** There is an unrelated package called `agentdb` on PyPI. Make sure to install `agentdb-sdk` (this package). The import is still `from agentdb import AgentDB`.
+
+## Quickstart
+
+```python
+from agentdb import AgentDB
+
+# Cloud (agentdb.zizka.ai)
+db = AgentDB("agdb_live_xxxx")
+
+# Self-hosted
+db = AgentDB(host="http://localhost:8000")
+```
+
+## Log an event
+
+```python
+result = await db.log(
+    agent="my-bot",
+    event="tool_call",
+    data={"tool": "search_web", "query": "competitor pricing"},
+)
+print(result.event_id)
+```
+
+## Link events causally
+
+```python
+# Log the user message
+msg = await db.log(agent="my-bot", event="user_message",
+                   data={"text": "why is my bill $200?"})
+
+# Log the tool call that happened BECAUSE of the message
+tool = await db.log(agent="my-bot", event="tool_call",
+                    data={"tool": "get_billing"},
+                    parent_id=msg.event_id)  # <-- causal link
+
+# Log the response that happened BECAUSE of the tool call
+await db.log(agent="my-bot", event="agent_response",
+             data={"text": "I found an anomaly in your account"},
+             parent_id=tool.event_id)
+```
+
+## Why did something happen?
+
+```python
+chain = await db.why(tool.event_id)
+chain.print()
+# user_message: {'text': 'why is my bill $200?'}  [14:32:01]
+#     └── tool_call: {'tool': 'get_billing'}       [14:32:02]
+#         └── agent_response: {'text': '...'}      [14:32:03]
+```
+
+## Semantic search
+
+```python
+results = await db.search("customer angry about billing")
+for event in results:
+    print(event.event, event.data)
+```
+
+## Time travel
+
+```python
+from datetime import datetime
+
+state = await db.at("my-bot", datetime(2026, 5, 1, 15, 0))
+print(state.state)
+```
+
+## Query events
+
+```python
+events = await db.query("my-bot", limit=100, event_type="tool_call")
+```
+
+## Self-host
+
+```bash
+git clone https://github.com/Zizka-ai/agentdb
+cd agentdb && cp .env.example .env
+docker-compose -f infra/docker-compose.yml up
+```
+
+## License
+
+AGPL-3.0

zizkadb_sdk-0.2.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zizkadb-sdk"
+version = "0.2.1"
+description = "ZizkaDB tells you when your agent stops behaving like itself. Causal lineage, time travel and behavioral baselines for any AI agent."
+readme = "README.md"
+license = { text = "AGPL-3.0" }
+requires-python = ">=3.10"
+authors = [{ name = "Zizka AI", email = "hello@zizka.ai" }]
+keywords = ["ai", "agents", "database", "memory", "llm", "observability"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = ["httpx>=0.27.0"]
+
+[project.urls]
+Homepage = "https://db.zizka.ai"
+Documentation = "https://db.zizka.ai/docs"
+Repository = "https://github.com/Zizka-ai/agentdb"
+Issues = "https://github.com/Zizka-ai/agentdb/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["zizkadb*"]

zizkadb_sdk-0.2.1/setup.cfg

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

zizkadb_sdk-0.2.1/zizkadb/__init__.py

@@ -0,0 +1,5 @@
+from .client import ZizkaDB
+from .exceptions import ZizkaDBError, AuthError, NotFoundError
+
+__all__ = ["ZizkaDB", "ZizkaDBError", "AuthError", "NotFoundError"]
+__version__ = "0.2.1"

zizkadb_sdk-0.2.1/zizkadb/client.py

@@ -0,0 +1,484 @@
+"""
+ZizkaDB Python SDK
+
+Usage:
+    from zizkadb import ZizkaDB
+
+    # Managed (cloud)
+    db = ZizkaDB("agdb_live_xxxx")
+
+    # Self-hosted
+    db = ZizkaDB(host="http://localhost:8000")
+
+    # Log an event
+    await db.log(agent="my-bot", event="tool_call", data={"tool": "search"})
+
+    # Why did something happen?
+    chain = await db.why(event_id="...")
+    chain.print()
+
+    # Semantic search
+    results = await db.search("what did the agent do about billing")
+
+    # Time travel
+    state = await db.at(agent="my-bot", timestamp=datetime(2026, 5, 1))
+"""
+
+import httpx
+from datetime import datetime
+from typing import Any
+
+from .models import Event, LogResult, CausalChain, AgentState, AgentInfo
+from .exceptions import ZizkaDBError, AuthError, NotFoundError, RateLimitError
+from .telemetry import ping as _telemetry_ping
+
+CLOUD_HOST = "https://db.zizka.ai"
+
+
+class ZizkaDB:
+    """
+    ZizkaDB client.
+
+    Args:
+        api_key: Your ZizkaDB API key (starts with agdb_live_).
+                 Get one at db.zizka.ai
+        host:    URL of your self-hosted instance.
+                 Defaults to ZizkaDB Cloud if api_key is provided.
+        timeout: HTTP timeout in seconds. Default 10.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        host: str | None = None,
+        timeout: float = 10.0,
+    ):
+        if not api_key and not host:
+            raise ZizkaDBError(
+                "Provide an api_key (cloud) or host (self-hosted).\n"
+                "  Cloud:       ZizkaDB('agdb_live_...')\n"
+                "  Self-hosted: ZizkaDB(host='http://localhost:8000')"
+            )
+
+        self._api_key = api_key
+        self._base_url = host.rstrip("/") if host else CLOUD_HOST
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+        _telemetry_ping(mode="self-hosted" if host else "cloud")
+
+    # ─────────────────────────────────────────
+    # CONTEXT MANAGER
+    # ─────────────────────────────────────────
+
+    async def __aenter__(self):
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+        return self
+
+    async def __aexit__(self, *_):
+        if self._client:
+            await self._client.aclose()
+
+    # ─────────────────────────────────────────
+    # LOG — log a single event
+    # ─────────────────────────────────────────
+
+    async def log(
+        self,
+        agent: str,
+        event: str,
+        data: dict[str, Any],
+        parent_id: str | None = None,
+        session_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> LogResult:
+        """
+        Log an event.
+
+        Args:
+            agent:      Your agent's identifier (e.g. "customer-support-bot")
+            event:      Event type (e.g. "tool_call", "user_message", "error")
+            data:       Event payload — any dict
+            parent_id:  ID of the causing event (enables causal lineage)
+            session_id: Group related events into a session
+            metadata:   Optional extra metadata
+
+        Returns:
+            LogResult with event_id, timestamp, sequence_no, checksum
+        """
+        response = await self._post(
+            "/v1/events",
+            {
+                "agent": agent,
+                "event": event,
+                "data": data,
+                "parent_id": parent_id,
+                "session_id": session_id,
+                "metadata": metadata,
+            },
+        )
+        return LogResult.from_dict(response)
+
+    # ─────────────────────────────────────────
+    # QUERY — fetch events
+    # ─────────────────────────────────────────
+
+    async def query(
+        self,
+        agent: str,
+        limit: int = 50,
+        before: datetime | None = None,
+        after: datetime | None = None,
+        event_type: str | None = None,
+        session_id: str | None = None,
+    ) -> list[Event]:
+        """
+        Query events for an agent.
+
+        Args:
+            agent:      Agent identifier
+            limit:      Max events to return (default 50, max 1000)
+            before:     Only events before this time
+            after:      Only events after this time
+            event_type: Filter to a specific event type
+            session_id: Filter to a specific session
+
+        Returns:
+            List of Event objects, newest first
+        """
+        params: dict[str, Any] = {"agent": agent, "limit": limit}
+        if before:
+            params["before"] = before.isoformat()
+        if after:
+            params["after"] = after.isoformat()
+        if event_type:
+            params["event_type"] = event_type
+        if session_id:
+            params["session_id"] = session_id
+
+        response = await self._get("/v1/events", params)
+        return [Event.from_dict(e) for e in response]
+
+    # ─────────────────────────────────────────
+    # WHY — causal chain for an event
+    # ─────────────────────────────────────────
+
+    async def why(self, event_id: str, depth: int = 10) -> CausalChain:
+        """
+        Get the causal chain for an event.
+        Walks parent_id links to show WHY an event happened.
+
+        Args:
+            event_id: The event to explain
+            depth:    How many levels up to trace (default 10)
+
+        Returns:
+            CausalChain — call .print() to display as a tree
+
+        Example:
+            chain = await db.why("evt_abc123")
+            chain.print()
+            # user_message: "why is my bill high?"
+            #     └── tool_call: get_billing(user=123)
+            #         └── agent_response: "I found an anomaly"
+        """
+        response = await self._get(
+            f"/v1/events/{event_id}/why",
+            {"depth": depth},
+        )
+        return CausalChain(
+            event_id=response["event_id"],
+            chain_length=response["chain_length"],
+            chain=[Event.from_dict(e) for e in response["chain"]],
+        )
+
+    # ─────────────────────────────────────────
+    # SEARCH — semantic search
+    # ─────────────────────────────────────────
+
+    async def search(
+        self,
+        query: str,
+        agent: str | None = None,
+        limit: int = 10,
+    ) -> list[Event]:
+        """
+        Search agent history using natural language.
+
+        Args:
+            query: Natural language query
+            agent: Limit search to a specific agent (optional)
+            limit: Number of results (default 10)
+
+        Returns:
+            List of Events sorted by relevance score
+
+        Example:
+            results = await db.search("what happened with billing refunds")
+        """
+        response = await self._post(
+            "/v1/search",
+            {"query": query, "agent": agent, "limit": limit},
+        )
+        return [Event.from_dict(e) for e in response["results"]]
+
+    # ─────────────────────────────────────────
+    # AT — time travel
+    # ─────────────────────────────────────────
+
+    async def at(self, agent: str, timestamp: datetime) -> AgentState:
+        """
+        Reconstruct agent state at a specific point in time.
+
+        Args:
+            agent:     Agent identifier
+            timestamp: Point in time to reconstruct state at
+
+        Returns:
+            AgentState with the reconstructed state dict
+
+        Example:
+            from datetime import datetime
+            state = await db.at("my-bot", datetime(2026, 5, 1, 15, 0))
+            print(state.state)
+        """
+        response = await self._get(
+            "/v1/events/at",
+            {"agent": agent, "timestamp": timestamp.isoformat()},
+        )
+        return AgentState.from_dict(response)
+
+    # ─────────────────────────────────────────
+    # CONTEXT FOR — prompt-ready memory injection
+    # ─────────────────────────────────────────
+
+    async def context_for(
+        self,
+        agent: str,
+        task: str,
+        max_tokens: int = 2000,
+        session_id: str | None = None,
+    ) -> str:
+        """
+        Get a formatted memory block ready to inject into a system prompt.
+        Combines recent events + semantically relevant past events.
+
+        Args:
+            agent:      Agent identifier
+            task:       What the agent is about to do (natural language)
+            max_tokens: Token budget for the context block (default 2000)
+            session_id: Current session ID to exclude from context
+
+        Returns:
+            A formatted string — paste directly into your system prompt.
+
+        Example:
+            context = await db.context_for(
+                agent="support-bot",
+                task="user asking about their invoice"
+            )
+            messages = [
+                {"role": "system", "content": f"You are a support agent.\\n\\n{context}"},
+                {"role": "user",   "content": user_message},
+            ]
+        """
+        response = await self._post(
+            "/v1/memory/context",
+            {
+                "agent": agent,
+                "task": task,
+                "max_tokens": max_tokens,
+                "session_id": session_id,
+            },
+        )
+        return response.get("context", "")
+
+    async def context_for_full(
+        self,
+        agent: str,
+        task: str,
+        max_tokens: int = 2000,
+        session_id: str | None = None,
+    ) -> dict:
+        """
+        Same as context_for() but returns the full response including
+        source event references and token count.
+        """
+        return await self._post(
+            "/v1/memory/context",
+            {
+                "agent": agent,
+                "task": task,
+                "max_tokens": max_tokens,
+                "session_id": session_id,
+            },
+        )
+
+    # ─────────────────────────────────────────
+    # MEMORY DIFF — what changed after a session
+    # ─────────────────────────────────────────
+
+    async def memory_diff(self, session_id: str) -> dict:
+        """
+        Returns a summary of what happened in a session and what new
+        patterns emerged compared to prior sessions.
+
+        Args:
+            session_id: The session to analyse
+
+        Returns:
+            Dict with: summary, event_count, event_types, causal_depth,
+                       has_errors, new_event_types, top_events
+
+        Example:
+            diff = await db.memory_diff("sess_abc")
+            print(diff["summary"])
+            # "Session with agent 'support-bot': 12 events over 45s."
+            if diff["has_errors"]:
+                print("Errors detected:", diff["new_event_types"])
+        """
+        return await self._get(f"/v1/memory/diff/{session_id}", {})
+
+    # ─────────────────────────────────────────
+    # FORGET — GDPR compliance
+    # ─────────────────────────────────────────
+
+    async def forget(self, filter_key: str, filter_value: str) -> dict:
+        """
+        Delete all events where data[filter_key] == filter_value.
+        Also removes vectors from the search index.
+
+        Use this for GDPR right-to-erasure requests.
+
+        Args:
+            filter_key:   Field in event data to match (e.g. "user_id", "email")
+            filter_value: Value to match (e.g. "user_123")
+
+        Returns:
+            Dict with deleted_events count and confirmation message
+
+        Example:
+            result = await db.forget("user_id", "user_123")
+            print(result["deleted_events"])  # e.g. 47
+        """
+        return await self._delete(
+            "/v1/memory/forget",
+            {"filter_key": filter_key, "filter_value": filter_value},
+        )
+
+    # ─────────────────────────────────────────
+    # AGENTS — list agents
+    # ─────────────────────────────────────────
+
+    async def agents(self) -> list[AgentInfo]:
+        """List all agents in your project."""
+        response = await self._get("/v1/agents", {})
+        return [AgentInfo.from_dict(a) for a in response]
+
+    # ─────────────────────────────────────────
+    # BASELINE — behavioral baseline + drift signal
+    # ─────────────────────────────────────────
+
+    async def baseline(self, agent: str, recent_window: int = 50) -> dict:
+        """
+        Get the behavioral baseline for an agent.
+
+        Splits this agent's sessions into two windows: the most recent N
+        sessions (`recent`) and everything older (`baseline`). Returns
+        event-type distribution, parent->child transition distribution,
+        average session shape, and error rate for each window, plus a
+        drift score (0 = identical, 1 = totally different) and the
+        biggest behavioural changes between the two windows.
+
+        Use this to answer "has this agent started behaving differently
+        since I shipped v2?" before users notice.
+
+        Args:
+            agent:         Agent identifier
+            recent_window: Number of most-recent sessions in the "recent"
+                           window. Default 50.
+
+        Returns:
+            Dict with: status, sessions, recent_window, baseline, recent,
+                       drift {score, verdict, biggest_changes, ...}
+
+        Example:
+            b = await db.baseline("support-bot")
+            if b["drift"]["score"] > 0.15:
+                print("Drift detected:", b["drift"]["biggest_changes"])
+        """
+        return await self._get(
+            f"/v1/agents/{agent}/baseline",
+            {"recent_window": recent_window},
+        )
+
+    # ─────────────────────────────────────────
+    # HTTP HELPERS
+    # ─────────────────────────────────────────
+
+    def _headers(self) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        return headers
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        if self._client:
+            return self._client
+        return httpx.AsyncClient(
+            base_url=self._base_url,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+
+    async def _post(self, path: str, body: dict) -> dict:
+        client = await self._get_client()
+        try:
+            resp = await client.post(path, json=body)
+            return self._handle(resp)
+        finally:
+            if not self._client:
+                await client.aclose()
+
+    async def _get(self, path: str, params: dict) -> Any:
+        client = await self._get_client()
+        try:
+            resp = await client.get(path, params=params)
+            return self._handle(resp)
+        finally:
+            if not self._client:
+                await client.aclose()
+
+    async def _delete(self, path: str, body: dict) -> Any:
+        client = await self._get_client()
+        try:
+            resp = await client.request("DELETE", path, json=body)
+            return self._handle(resp)
+        finally:
+            if not self._client:
+                await client.aclose()
+
+    def _handle(self, resp: httpx.Response) -> Any:
+        if resp.status_code == 401:
+            raise AuthError(
+                "Invalid API key. Check your key at db.zizka.ai/settings/api-keys",
+                status_code=401,
+            )
+        if resp.status_code == 404:
+            raise NotFoundError("Resource not found", status_code=404)
+        if resp.status_code == 429:
+            raise RateLimitError("Rate limit exceeded", status_code=429)
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise ZizkaDBError(
+                f"ZizkaDB error ({resp.status_code}): {detail}",
+                status_code=resp.status_code,
+            )
+        return resp.json()

zizkadb_sdk-0.2.1/zizkadb/exceptions.py

@@ -0,0 +1,18 @@
+class ZizkaDBError(Exception):
+    """Base exception for ZizkaDB SDK."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class AuthError(ZizkaDBError):
+    """Invalid or missing API key."""
+
+
+class NotFoundError(ZizkaDBError):
+    """Event or agent not found."""
+
+
+class RateLimitError(ZizkaDBError):
+    """Too many requests."""

zizkadb_sdk-0.2.1/zizkadb/models.py

@@ -0,0 +1,118 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class Event:
+    event_id: str
+    agent: str
+    timestamp: datetime
+    event: str
+    data: dict[str, Any]
+    parent_id: str | None = None
+    session_id: str | None = None
+    sequence_no: int = 0
+    score: float | None = None  # set on search results
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Event":
+        return cls(
+            event_id=d["event_id"],
+            agent=d["agent"],
+            timestamp=datetime.fromisoformat(d["timestamp"]),
+            event=d["event"],
+            data=d["data"],
+            parent_id=d.get("parent_id"),
+            session_id=d.get("session_id"),
+            sequence_no=d.get("sequence_no", 0),
+            score=d.get("score"),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Event(id={self.event_id[:8]}... "
+            f"agent={self.agent!r} "
+            f"event={self.event!r} "
+            f"at={self.timestamp.strftime('%H:%M:%S')})"
+        )
+
+
+@dataclass
+class LogResult:
+    event_id: str
+    timestamp: datetime
+    sequence_no: int
+    checksum: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "LogResult":
+        return cls(
+            event_id=d["event_id"],
+            timestamp=datetime.fromisoformat(d["timestamp"]),
+            sequence_no=d["sequence_no"],
+            checksum=d["checksum"],
+        )
+
+
+@dataclass
+class CausalChain:
+    event_id: str
+    chain_length: int
+    chain: list[Event]
+
+    def print(self) -> None:
+        """Pretty-print the causal chain as a tree."""
+        if not self.chain:
+            print("(empty chain)")
+            return
+
+        for i, event in enumerate(self.chain):
+            indent = "    " * i
+            connector = "└── " if i > 0 else ""
+            print(
+                f"{indent}{connector}"
+                f"{event.event}: {_truncate(str(event.data), 60)}"
+                f"  [{event.timestamp.strftime('%H:%M:%S')}]"
+            )
+
+    def __repr__(self) -> str:
+        return f"CausalChain(length={self.chain_length})"
+
+
+@dataclass
+class AgentState:
+    agent: str
+    at: datetime
+    event_count: int
+    state: dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentState":
+        return cls(
+            agent=d["agent"],
+            at=datetime.fromisoformat(d["at"]),
+            event_count=d["event_count"],
+            state=d.get("state", {}),
+        )
+
+
+@dataclass
+class AgentInfo:
+    agent: str
+    first_seen: datetime
+    last_seen: datetime
+    event_count: int
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AgentInfo":
+        return cls(
+            agent=d["agent"],
+            first_seen=datetime.fromisoformat(d["first_seen"]),
+            last_seen=datetime.fromisoformat(d["last_seen"]),
+            event_count=d["event_count"],
+        )
+
+
+def _truncate(s: str, n: int) -> str:
+    return s if len(s) <= n else s[:n] + "..."

zizkadb_sdk-0.2.1/zizkadb/telemetry.py

@@ -0,0 +1,90 @@
+"""
+Anonymous usage telemetry for the ZizkaDB Python SDK.
+
+What is sent (once per install, fire-and-forget):
+  install_id  — random UUID stored in ~/.zizkadb/install_id (never changes)
+  sdk_version — e.g. "0.1.0"
+  python      — e.g. "3.12.3"
+  os          — e.g. "Linux", "Darwin", "Windows"
+  mode        — "cloud" or "self-hosted"
+
+What is NOT sent: API keys, agent names, event data, IP address, hostname.
+
+Opt out at any time:
+  export ZIZKADB_TELEMETRY=false   # shell
+  ZIZKADB_TELEMETRY=false          # .env
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import platform
+import threading
+import uuid
+from pathlib import Path
+
+_TELEMETRY_URL = "https://db.zizka.ai/v1/telemetry"
+_INSTALL_ID_PATH = Path.home() / ".zizkadb" / "install_id"
+_sent = False  # only fire once per process
+
+
+def _get_or_create_install_id() -> str:
+    try:
+        _INSTALL_ID_PATH.parent.mkdir(parents=True, exist_ok=True)
+        if _INSTALL_ID_PATH.exists():
+            iid = _INSTALL_ID_PATH.read_text().strip()
+            if iid:
+                return iid
+        iid = str(uuid.uuid4())
+        _INSTALL_ID_PATH.write_text(iid)
+        return iid
+    except Exception:
+        return str(uuid.uuid4())  # ephemeral fallback
+
+
+def _send(mode: str) -> None:
+    try:
+        import urllib.request
+        import json
+
+        payload = json.dumps({
+            "install_id":   _get_or_create_install_id(),
+            "sdk":          "python",
+            "sdk_version":  _sdk_version(),
+            "python":       f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+            "os":           platform.system(),
+            "mode":         mode,
+        }).encode()
+
+        req = urllib.request.Request(
+            _TELEMETRY_URL,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=3)
+    except Exception:
+        pass  # never surface telemetry errors
+
+
+def _sdk_version() -> str:
+    try:
+        from zizkadb import __version__
+        return __version__
+    except Exception:
+        return "unknown"
+
+
+def ping(mode: str = "cloud") -> None:
+    """Fire a single anonymous telemetry ping in a background thread."""
+    global _sent
+
+    if _sent:
+        return
+    if os.getenv("ZIZKADB_TELEMETRY", "").lower() in ("false", "0", "no", "off"):
+        return
+
+    _sent = True
+    t = threading.Thread(target=_send, args=(mode,), daemon=True)
+    t.start()

zizkadb_sdk-0.2.1/zizkadb_sdk.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: zizkadb-sdk
+Version: 0.2.1
+Summary: ZizkaDB tells you when your agent stops behaving like itself. Causal lineage, time travel and behavioral baselines for any AI agent.
+Author-email: Zizka AI <hello@zizka.ai>
+License: AGPL-3.0
+Project-URL: Homepage, https://db.zizka.ai
+Project-URL: Documentation, https://db.zizka.ai/docs
+Project-URL: Repository, https://github.com/Zizka-ai/agentdb
+Project-URL: Issues, https://github.com/Zizka-ai/agentdb/issues
+Keywords: ai,agents,database,memory,llm,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+# agentdb-sdk
+
+Python SDK for [AgentDB](https://agentdb.zizka.ai) — the operational database for AI agents.
+
+## Install
+
+```bash
+pip install agentdb-sdk
+```
+
+> **Note:** There is an unrelated package called `agentdb` on PyPI. Make sure to install `agentdb-sdk` (this package). The import is still `from agentdb import AgentDB`.
+
+## Quickstart
+
+```python
+from agentdb import AgentDB
+
+# Cloud (agentdb.zizka.ai)
+db = AgentDB("agdb_live_xxxx")
+
+# Self-hosted
+db = AgentDB(host="http://localhost:8000")
+```
+
+## Log an event
+
+```python
+result = await db.log(
+    agent="my-bot",
+    event="tool_call",
+    data={"tool": "search_web", "query": "competitor pricing"},
+)
+print(result.event_id)
+```
+
+## Link events causally
+
+```python
+# Log the user message
+msg = await db.log(agent="my-bot", event="user_message",
+                   data={"text": "why is my bill $200?"})
+
+# Log the tool call that happened BECAUSE of the message
+tool = await db.log(agent="my-bot", event="tool_call",
+                    data={"tool": "get_billing"},
+                    parent_id=msg.event_id)  # <-- causal link
+
+# Log the response that happened BECAUSE of the tool call
+await db.log(agent="my-bot", event="agent_response",
+             data={"text": "I found an anomaly in your account"},
+             parent_id=tool.event_id)
+```
+
+## Why did something happen?
+
+```python
+chain = await db.why(tool.event_id)
+chain.print()
+# user_message: {'text': 'why is my bill $200?'}  [14:32:01]
+#     └── tool_call: {'tool': 'get_billing'}       [14:32:02]
+#         └── agent_response: {'text': '...'}      [14:32:03]
+```
+
+## Semantic search
+
+```python
+results = await db.search("customer angry about billing")
+for event in results:
+    print(event.event, event.data)
+```
+
+## Time travel
+
+```python
+from datetime import datetime
+
+state = await db.at("my-bot", datetime(2026, 5, 1, 15, 0))
+print(state.state)
+```
+
+## Query events
+
+```python
+events = await db.query("my-bot", limit=100, event_type="tool_call")
+```
+
+## Self-host
+
+```bash
+git clone https://github.com/Zizka-ai/agentdb
+cd agentdb && cp .env.example .env
+docker-compose -f infra/docker-compose.yml up
+```
+
+## License
+
+AGPL-3.0

zizkadb_sdk-0.2.1/zizkadb_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+zizkadb/__init__.py
+zizkadb/client.py
+zizkadb/exceptions.py
+zizkadb/models.py
+zizkadb/telemetry.py
+zizkadb_sdk.egg-info/PKG-INFO
+zizkadb_sdk.egg-info/SOURCES.txt
+zizkadb_sdk.egg-info/dependency_links.txt
+zizkadb_sdk.egg-info/requires.txt
+zizkadb_sdk.egg-info/top_level.txt

zizkadb_sdk-0.2.1/zizkadb_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

zizkadb_sdk-0.2.1/zizkadb_sdk.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27.0

zizkadb_sdk-0.2.1/zizkadb_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+zizkadb