syntarus 0.2.0__py3-none-any.whl

syntarus/__init__.py

@@ -0,0 +1,18 @@
+"""Official Syntarus project-scoped memory clients."""
+
+from .client import AsyncMemoryClient, MemoryClient
+from .exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    EventFailedError,
+    PermissionDenied,
+    RateLimitError,
+    SyntarusError,
+)
+
+__all__ = [
+    "AsyncMemoryClient", "MemoryClient", "SyntarusError", "AuthenticationError",
+    "PermissionDenied", "RateLimitError", "APIConnectionError", "APITimeoutError",
+    "EventFailedError",
+]

syntarus/client.py

@@ -0,0 +1,219 @@
+"""Synchronous and asynchronous clients for the Syntarus v1 memory API."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    EventFailedError,
+    PermissionDenied,
+    RateLimitError,
+    SyntarusError,
+)
+
+DEFAULT_BASE_URL = "https://ai.syntarus.com/v1"
+
+
+def _raise_for_response(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        detail = response.json().get("detail", "Request failed.")
+    except Exception:
+        detail = "Request failed."
+    if response.status_code == 401:
+        raise AuthenticationError("Project API key was rejected.")
+    if response.status_code == 403:
+        raise PermissionDenied(str(detail))
+    if response.status_code == 429:
+        raw_retry = response.headers.get("Retry-After")
+        try:
+            retry_after = float(raw_retry) if raw_retry is not None else None
+        except ValueError:
+            retry_after = None
+        raise RateLimitError("Project API rate limit exceeded.", retry_after=retry_after)
+    raise SyntarusError(f"Syntarus API error ({response.status_code}): {detail}")
+
+
+class _BaseClient:
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 20.0):
+        if not api_key.startswith("sk_mem_"):
+            raise ValueError("api_key must be a Syntarus project API key")
+        self._base_url = base_url.rstrip("/")
+        self._headers = {"Authorization": f"Bearer {api_key}", "User-Agent": "syntarus-python/0.2.0"}
+        self._timeout = timeout
+
+    @staticmethod
+    def _payload(user_id: str, messages: list[dict[str, str]], agent_id: str | None, run_id: str | None, metadata: dict[str, Any] | None) -> dict[str, Any]:
+        return {"user_id": user_id, "messages": messages, "agent_id": agent_id, "run_id": run_id, "metadata": metadata or {}}
+
+
+class MemoryClient(_BaseClient):
+    """Blocking client. Use ``AsyncMemoryClient`` inside async applications."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 20.0):
+        super().__init__(api_key, base_url=base_url, timeout=timeout)
+        self._client = httpx.Client(base_url=self._base_url, headers=self._headers, timeout=self._timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "MemoryClient":
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError("Syntarus API request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise APIConnectionError("Could not connect to the Syntarus API.") from exc
+        _raise_for_response(response)
+        return response
+
+    def add(self, *, user_id: str, messages: list[dict[str, str]], agent_id: str | None = None, run_id: str | None = None, metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> dict[str, Any]:
+        response = self._request("POST", "/memories", json=self._payload(user_id, messages, agent_id, run_id, metadata), headers={"Idempotency-Key": idempotency_key or uuid.uuid4().hex})
+        return response.json()
+
+    def event(self, event_id: str) -> dict[str, Any]:
+        response = self._request("GET", f"/events/{event_id}")
+        return response.json()
+
+    def wait_for_event(self, event_id: str, *, timeout: float = 60.0, poll_interval: float = 0.5) -> dict[str, Any]:
+        if timeout <= 0 or poll_interval <= 0:
+            raise ValueError("timeout and poll_interval must be positive")
+        deadline = time.monotonic() + timeout
+        while True:
+            event = self.event(event_id)
+            if event.get("status") == "succeeded":
+                return event
+            if event.get("status") in {"dead_letter", "cancelled"}:
+                raise EventFailedError(event)
+            if time.monotonic() >= deadline:
+                raise APITimeoutError(f"Timed out waiting for event {event_id}.")
+            time.sleep(min(poll_interval, max(0.0, deadline - time.monotonic())))
+
+    def search(self, query: str, *, user_id: str, top_k: int = 10, agent_id: str | None = None) -> dict[str, Any]:
+        response = self._request("POST", "/memories/search", json={"user_id": user_id, "query": query, "top_k": top_k, "agent_id": agent_id})
+        return response.json()
+
+    def export(self, *, user_id: str, agent_id: str | None = None) -> dict[str, Any]:
+        params = {"user_id": user_id, **({"agent_id": agent_id} if agent_id else {})}
+        response = self._request("GET", "/memories/export", params=params)
+        return response.json()
+
+    def delete(self, memory_id: str) -> None:
+        self._request("DELETE", f"/memories/{memory_id}")
+
+    def delete_user(self, *, user_id: str, agent_id: str | None = None) -> None:
+        params = {"user_id": user_id, **({"agent_id": agent_id} if agent_id else {})}
+        self._request("DELETE", "/memories", params=params)
+
+    def create_webhook(self, url: str, *, event_types: list[str] | None = None) -> dict[str, Any]:
+        response = self._request("POST", "/webhooks", json={"url": url, "event_types": event_types or ["memory.ingest.succeeded"]})
+        return response.json()
+
+    def list_webhooks(self) -> dict[str, Any]:
+        return self._request("GET", "/webhooks").json()
+
+    def webhook_deliveries(self, *, webhook_id: str | None = None, limit: int = 100) -> dict[str, Any]:
+        params: dict[str, Any] = {"limit": limit}
+        if webhook_id:
+            params["webhook_id"] = webhook_id
+        return self._request("GET", "/webhooks/deliveries", params=params).json()
+
+    def delete_webhook(self, webhook_id: str) -> None:
+        self._request("DELETE", f"/webhooks/{webhook_id}")
+
+
+class AsyncMemoryClient(_BaseClient):
+    """Async client for FastAPI, LangGraph and other async agent runtimes."""
+
+    def __init__(self, api_key: str, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 20.0):
+        super().__init__(api_key, base_url=base_url, timeout=timeout)
+        self._client = httpx.AsyncClient(base_url=self._base_url, headers=self._headers, timeout=self._timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncMemoryClient":
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = await self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException as exc:
+            raise APITimeoutError("Syntarus API request timed out.") from exc
+        except httpx.RequestError as exc:
+            raise APIConnectionError("Could not connect to the Syntarus API.") from exc
+        _raise_for_response(response)
+        return response
+
+    async def add(self, *, user_id: str, messages: list[dict[str, str]], agent_id: str | None = None, run_id: str | None = None, metadata: dict[str, Any] | None = None, idempotency_key: str | None = None) -> dict[str, Any]:
+        response = await self._request("POST", "/memories", json=self._payload(user_id, messages, agent_id, run_id, metadata), headers={"Idempotency-Key": idempotency_key or uuid.uuid4().hex})
+        return response.json()
+
+    async def event(self, event_id: str) -> dict[str, Any]:
+        response = await self._request("GET", f"/events/{event_id}")
+        return response.json()
+
+    async def wait_for_event(self, event_id: str, *, timeout: float = 60.0, poll_interval: float = 0.5) -> dict[str, Any]:
+        if timeout <= 0 or poll_interval <= 0:
+            raise ValueError("timeout and poll_interval must be positive")
+        deadline = time.monotonic() + timeout
+        while True:
+            event = await self.event(event_id)
+            if event.get("status") == "succeeded":
+                return event
+            if event.get("status") in {"dead_letter", "cancelled"}:
+                raise EventFailedError(event)
+            if time.monotonic() >= deadline:
+                raise APITimeoutError(f"Timed out waiting for event {event_id}.")
+            await asyncio.sleep(min(poll_interval, max(0.0, deadline - time.monotonic())))
+
+    async def search(self, query: str, *, user_id: str, top_k: int = 10, agent_id: str | None = None) -> dict[str, Any]:
+        response = await self._request("POST", "/memories/search", json={"user_id": user_id, "query": query, "top_k": top_k, "agent_id": agent_id})
+        return response.json()
+
+    async def export(self, *, user_id: str, agent_id: str | None = None) -> dict[str, Any]:
+        params = {"user_id": user_id, **({"agent_id": agent_id} if agent_id else {})}
+        response = await self._request("GET", "/memories/export", params=params)
+        return response.json()
+
+    async def delete(self, memory_id: str) -> None:
+        await self._request("DELETE", f"/memories/{memory_id}")
+
+    async def delete_user(self, *, user_id: str, agent_id: str | None = None) -> None:
+        params = {"user_id": user_id, **({"agent_id": agent_id} if agent_id else {})}
+        await self._request("DELETE", "/memories", params=params)
+
+    async def create_webhook(self, url: str, *, event_types: list[str] | None = None) -> dict[str, Any]:
+        response = await self._request("POST", "/webhooks", json={"url": url, "event_types": event_types or ["memory.ingest.succeeded"]})
+        return response.json()
+
+    async def list_webhooks(self) -> dict[str, Any]:
+        return (await self._request("GET", "/webhooks")).json()
+
+    async def webhook_deliveries(self, *, webhook_id: str | None = None, limit: int = 100) -> dict[str, Any]:
+        params: dict[str, Any] = {"limit": limit}
+        if webhook_id:
+            params["webhook_id"] = webhook_id
+        response = await self._request("GET", "/webhooks/deliveries", params=params)
+        return response.json()
+
+    async def delete_webhook(self, webhook_id: str) -> None:
+        await self._request("DELETE", f"/webhooks/{webhook_id}")

syntarus/exceptions.py

@@ -0,0 +1,38 @@
+"""Typed API errors. Exception messages intentionally omit request secrets."""
+
+
+class SyntarusError(Exception):
+    """Base exception raised for an unsuccessful Syntarus API response."""
+
+
+class AuthenticationError(SyntarusError):
+    """The project API key is invalid, expired, or revoked."""
+
+
+class PermissionDenied(SyntarusError):
+    """The project API key does not have the required scope."""
+
+
+class RateLimitError(SyntarusError):
+    """The project API key has exceeded its request budget."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class APIConnectionError(SyntarusError):
+    """The Syntarus API could not be reached."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The Syntarus API did not respond before the configured timeout."""
+
+
+class EventFailedError(SyntarusError):
+    """An accepted asynchronous memory event reached a terminal failure."""
+
+    def __init__(self, event: dict):
+        self.event = event
+        detail = event.get("last_error") or f"event ended with status {event.get('status')}"
+        super().__init__(str(detail))

syntarus-0.2.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: syntarus
+Version: 0.2.0
+Summary: Project-scoped memory client for Syntarus
+Project-URL: Documentation, https://www.syntarus.com/pages/developers.html
+Project-URL: Homepage, https://www.syntarus.com
+Project-URL: Source, https://github.com/sujalkherawat25-stack/memoryos/tree/main/sdk
+Author: Syntarus
+License: MIT License
+        
+        Copyright (c) 2026 Syntarus
+        
+        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.
+License-File: LICENSE
+Keywords: agents,ai,llm,memory
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: test
+Requires-Dist: build<2,>=1.2; extra == 'test'
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'test'
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Requires-Dist: twine<7,>=5; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Syntarus Python SDK
+
+The official Python client for the project-scoped Syntarus memory API.
+
+## Install
+
+```bash
+pip install syntarus
+```
+
+Python 3.10 or newer is required. Keep project API keys in a server-side
+secret manager; never ship them in browser or mobile applications.
+
+## Add and search memory
+
+```python
+from syntarus import MemoryClient
+
+with MemoryClient(api_key="sk_mem_...") as memory:
+    accepted = memory.add(
+        user_id="customer_123",
+        agent_id="support_agent",
+        run_id="ticket_456",
+        messages=[
+            {"role": "user", "content": "I prefer vegetarian food."},
+            {"role": "assistant", "content": "I will remember that."},
+        ],
+        metadata={"channel": "voice"},
+        idempotency_key="call-456-final",
+    )
+    memory.wait_for_event(accepted["event_id"])
+    result = memory.search(
+        "What food does the customer prefer?",
+        user_id="customer_123",
+        agent_id="support_agent",
+    )
+    print(result["context"])
+```
+
+`agent_id` creates an isolated memory namespace. Omit it for a user profile
+shared by every agent in the project. `run_id` groups the conversation history
+used during ingestion. `metadata` is event metadata and is returned by event
+status and webhook payloads; it is not currently a memory-search filter.
+
+## Async client
+
+```python
+from syntarus import AsyncMemoryClient
+
+async with AsyncMemoryClient(api_key="sk_mem_...") as memory:
+    accepted = await memory.add(
+        user_id="customer_123",
+        messages=[{"role": "user", "content": "Call me after 5 PM."}],
+    )
+    await memory.wait_for_event(accepted["event_id"])
+```
+
+## Lifecycle operations
+
+```python
+memory.export(user_id="customer_123", agent_id="support_agent")
+memory.delete("memory-uuid")
+memory.delete_user(user_id="customer_123", agent_id="support_agent")
+```
+
+Deleting a user without `agent_id` deletes only the shared user namespace.
+Delete each agent namespace separately when an application uses agent-scoped
+memory.
+
+## Webhooks
+
+```python
+created = memory.create_webhook("https://example.com/syntarus/events")
+signing_secret = created["signing_secret"]  # returned once
+memory.list_webhooks()
+memory.webhook_deliveries(webhook_id=created["webhook"]["id"])
+memory.delete_webhook(created["webhook"]["id"])
+```
+
+Deliveries include `X-Syntarus-Timestamp`, `X-Syntarus-Delivery`, and
+`X-Syntarus-Signature-256`. Verify the signature as HMAC-SHA256 over
+`<timestamp>.<raw_request_body>` and reject timestamps outside a five-minute
+window. A non-2xx response is retried durably and eventually becomes a
+dead-letter delivery visible through `webhook_deliveries`.
+
+## Errors
+
+The SDK raises typed exceptions derived from `SyntarusError`:
+
+- `AuthenticationError`
+- `PermissionDenied`
+- `RateLimitError` (`retry_after` is available when the API sends it)
+- `APIConnectionError`
+- `APITimeoutError`
+- `EventFailedError` (`event` contains the terminal event record)

syntarus-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+syntarus/__init__.py,sha256=e3EKF7l7_kp1NpQ4ODO30zi00EhdpgWgisF_zVvLbXc,492
+syntarus/client.py,sha256=_Em0uDOZfhB_ex_cEOveq_NuIRebD1D4rOkfSTtMRzE,10380
+syntarus/exceptions.py,sha256=MZd6DpODf8kTBZGwJTSviIWLo-ajWLZykPylw3ryHZU,1175
+syntarus-0.2.0.dist-info/METADATA,sha256=jZB6YrXiCoNc4aIev9lHaMBGz4mpPGfbM-MbYIpRGq0,5231
+syntarus-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+syntarus-0.2.0.dist-info/licenses/LICENSE,sha256=g-up2h6UU5Af0pIbAAu214vBiACCwqocsK3gvD6BbkA,1065
+syntarus-0.2.0.dist-info/RECORD,,

syntarus-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

syntarus-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Syntarus
+
+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.