zin 0.0.1__tar.gz

zin-0.0.1/.gitignore

@@ -0,0 +1,5 @@
+data/
+__pycache__/
+*.pyc
+.env
+.venv/

zin-0.0.1/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: zin
+Version: 0.0.1
+Summary: Zin AI — long-term memory for AI agents
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28

zin-0.0.1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zin"
+version = "0.0.1"
+description = "Zin AI — long-term memory for AI agents"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.28",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["zin"]

zin-0.0.1/zin/__init__.py

@@ -0,0 +1,4 @@
+from zin.client import ZinMemory
+from zin.models import Memory, SearchResult
+
+__all__ = ["ZinMemory", "Memory", "SearchResult"]

zin-0.0.1/zin/client.py

@@ -0,0 +1,157 @@
+"""Zin Memory SDK — async client for the Zin memory server."""
+
+from __future__ import annotations
+
+import httpx
+
+from zin.models import (
+    ConversationMessage,
+    Memory,
+    SearchResult,
+)
+
+
+class ZinMemory:
+    """Async client for the Zin memory API.
+
+    Can be used as a singleton — user_id and namespaces are passed per-call,
+    not at init time.
+
+    Usage::
+
+        client = ZinMemory("http://localhost:8000")
+
+        # Add a memory
+        mem_id = await client.add("Likes dark mode", user_id="u1")
+
+        # Search
+        results = await client.search("preferences", user_id="u1")
+
+        # Process a conversation (fire-and-forget on server side)
+        await client.process_memory(
+            messages=[("user", "I love hiking"), ("assistant", "Nice!")],
+            user_id="u1",
+        )
+
+        # Cleanup
+        await client.close()
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8000", timeout: float = 10.0):
+        self._http = httpx.AsyncClient(base_url=base_url, timeout=timeout)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> ZinMemory:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+    # ── Add ───────────────────────────────────────────────────────────────
+
+    async def add(
+        self,
+        text: str,
+        *,
+        user_id: str | None = None,
+        namespace: str = "personal",
+        metadata: dict | None = None,
+    ) -> str:
+        """Add a memory. Returns the memory ID."""
+        payload: dict = {"text": text, "namespace": namespace, "metadata": metadata or {}}
+        if user_id:
+            payload["user_id"] = user_id
+        resp = await self._http.post("/add", json=payload)
+        resp.raise_for_status()
+        return resp.json()["id"]
+
+    # ── Search ────────────────────────────────────────────────────────────
+
+    async def search(
+        self,
+        query: str,
+        *,
+        user_id: str | None = None,
+        namespace: str | None = None,
+        top_k: int = 5,
+    ) -> list[SearchResult]:
+        """Search for memories by semantic similarity."""
+        payload: dict = {"query": query, "top_k": top_k}
+        if user_id:
+            payload["user_id"] = user_id
+        if namespace:
+            payload["namespace"] = namespace
+        resp = await self._http.post("/search", json=payload)
+        resp.raise_for_status()
+        return [
+            SearchResult(
+                id=r["id"],
+                text=r["text"],
+                metadata=r["metadata"],
+                namespace=r["namespace"],
+                distance=r["distance"],
+            )
+            for r in resp.json()
+        ]
+
+    # ── Process memory ────────────────────────────────────────────────────
+
+    async def process_memory(
+        self,
+        messages: list[tuple[str, str] | ConversationMessage],
+        *,
+        user_id: str | None = None,
+        namespaces: dict[str, str] | None = None,
+        store_personal: bool = True,
+    ) -> None:
+        """Send a conversation window to the memory agent for processing.
+
+        Args:
+            messages: List of (role, content) tuples or ConversationMessage objects.
+            user_id: User ID for personal namespace scoping.
+            namespaces: Shared namespace dict (e.g. {"company": "Company knowledge"}).
+            store_personal: Whether the agent can store personal memories.
+        """
+        msg_dicts = []
+        for m in messages:
+            if isinstance(m, ConversationMessage):
+                msg_dicts.append({"role": m.role, "content": m.content})
+            else:
+                msg_dicts.append({"role": m[0], "content": m[1]})
+
+        payload: dict = {"messages": msg_dicts, "store_personal": store_personal}
+        if user_id:
+            payload["user_id"] = user_id
+        if namespaces:
+            payload["namespaces"] = namespaces
+        resp = await self._http.post("/process-memory", json=payload)
+        resp.raise_for_status()
+
+    # ── Delete all memories ─────────────────────────────────────────────────
+
+    async def delete_all_memories(self) -> int:
+        """Delete all memories. Returns the number deleted."""
+        resp = await self._http.delete("/memories")
+        resp.raise_for_status()
+        return resp.json()["deleted"]
+
+    # ── List memories ─────────────────────────────────────────────────────
+
+    async def list_memories(
+        self,
+        *,
+        namespace: str | None = None,
+        limit: int = 100,
+    ) -> list[Memory]:
+        """List stored memories (no vector search). For dev/debugging."""
+        params: dict = {"limit": limit}
+        if namespace:
+            params["namespace"] = namespace
+        resp = await self._http.get("/memories", params=params)
+        resp.raise_for_status()
+        return [
+            Memory(id=r["id"], text=r["text"], metadata=r["metadata"], namespace=r["namespace"])
+            for r in resp.json()
+        ]

zin-0.0.1/zin/models.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Memory:
+    id: str
+    text: str
+    metadata: dict
+    namespace: str
+
+
+@dataclass
+class SearchResult(Memory):
+    distance: float = 0.0
+
+
+@dataclass
+class ConversationMessage:
+    role: str
+    content: str