syntarus 0.2.0__tar.gz

syntarus-0.2.0/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.

syntarus-0.2.0/PKG-INFO

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

@@ -0,0 +1,95 @@
+# 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/examples/crewai_agent.py

@@ -0,0 +1,44 @@
+"""
+Example 3 — CrewAI agent with MemoryOS memory tool.
+Exposes memory search as a CrewAI Tool so the agent decides when to query.
+"""
+
+from crewai import Agent, Task, Crew
+from crewai.tools import tool
+from memoryos_client import MemoryOS
+
+mem = MemoryOS(api_key="mk_crewai", auto_approve=True)
+
+
+@tool("Search user memory")
+def search_memory(query: str) -> str:
+    """
+    Search the user's long-term memory for facts relevant to the query.
+    Use this before answering personal questions about the user.
+    Returns a context string with relevant facts.
+    """
+    results = mem.search(query, top_k=5)
+    if not results:
+        return "No relevant memories found."
+    return "\n".join(f"- {r.text}" for r in results)
+
+
+personal_assistant = Agent(
+    role="Personal Assistant",
+    goal="Help the user based on their preferences and history",
+    backstory="You have access to the user's long-term memory.",
+    tools=[search_memory],
+    verbose=True,
+)
+
+task = Task(
+    description="Answer: What kind of projects does the user work on?",
+    agent=personal_assistant,
+    expected_output="A personalized answer based on memory.",
+)
+
+crew = Crew(agents=[personal_assistant], tasks=[task])
+
+if __name__ == "__main__":
+    result = crew.kickoff()
+    print(result)

syntarus-0.2.0/examples/custom_agent.py

@@ -0,0 +1,42 @@
+"""
+Example 1 — Custom agent with MemoryOS memory layer.
+Works with any LLM — Groq, OpenAI, Anthropic, Ollama.
+"""
+
+from groq import Groq
+from memoryos_client import MemoryOS
+
+# Your MemoryOS API key (set in backend/.env MEMORYOS_API_KEYS)
+mem = MemoryOS(api_key="mk_myagent", auto_approve=False)
+client = Groq()  # uses GROQ_API_KEY env var
+
+
+def chat(user_message: str, conversation_id: str = "default") -> str:
+    # 1. Retrieve relevant memories BEFORE calling LLM
+    memory_context = mem.get_context(user_message)
+
+    # 2. Build system prompt with memory injected
+    system = "You are a helpful personal assistant."
+    if memory_context:
+        system += f"\n\nWhat you know about this user:\n{memory_context}"
+
+    # 3. Call LLM
+    response = client.chat.completions.create(
+        model="openai/gpt-oss-120b",
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user", "content": user_message},
+        ],
+        max_tokens=1024,
+    )
+    assistant_message = response.choices[0].message.content or ""
+
+    # 4. Ingest the turn AFTER responding
+    mem.ingest(user_message, assistant_message, conversation_id=conversation_id)
+
+    return assistant_message
+
+
+if __name__ == "__main__":
+    print(chat("My name is Sujal and I prefer dark mode in all tools."))
+    print(chat("What do you know about me?"))

syntarus-0.2.0/examples/enterprise_load.py

@@ -0,0 +1,64 @@
+"""Rate-limit-aware enterprise ingestion load test.
+
+This intentionally counts HTTP 429 separately from accepted events. A 429 is
+not treated as a data-integrity failure; the request is retried with bounded
+exponential backoff when ``--retry-429`` is enabled.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import time
+import uuid
+
+import httpx
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--events", type=int, default=100)
+    parser.add_argument("--retry-429", action="store_true")
+    parser.add_argument("--max-retries", type=int, default=5)
+    args = parser.parse_args()
+    key = os.environ.get("SYNTARUS_PROJECT_A_KEY")
+    if not key:
+        raise SystemExit("Set SYNTARUS_PROJECT_A_KEY first.")
+    base = os.environ.get("SYNTARUS_BASE_URL", "https://ai.syntarus.com/v1")
+    accepted = rate_limited = other = 0
+    started = time.perf_counter()
+
+    with httpx.Client(base_url=base, headers={"Authorization": f"Bearer {key}"}, timeout=30) as client:
+        for index in range(args.events):
+            payload = {
+                "user_id": f"load_{uuid.uuid4().hex[:12]}",
+                "messages": [{
+                    "role": "user",
+                    "content": f"My durable enterprise load fact {index} is stable; remember this.",
+                }],
+            }
+            for attempt in range(args.max_retries + 1):
+                response = client.post("/memories", json=payload)
+                if response.status_code != 429 or not args.retry_429:
+                    break
+                retry_after = response.headers.get("Retry-After")
+                delay = float(retry_after) if retry_after and retry_after.isdigit() else min(2 ** attempt, 30)
+                time.sleep(delay)
+            if response.status_code == 202:
+                accepted += 1
+            elif response.status_code == 429:
+                rate_limited += 1
+            else:
+                other += 1
+
+    print({
+        "events": args.events,
+        "accepted": accepted,
+        "rate_limited": rate_limited,
+        "other": other,
+        "elapsed_seconds": round(time.perf_counter() - started, 2),
+    })
+
+
+if __name__ == "__main__":
+    main()

syntarus-0.2.0/examples/enterprise_smoke.py

@@ -0,0 +1,78 @@
+"""Live two-project isolation smoke test for a staging Syntarus deployment.
+
+Required environment variables:
+  SYNTARUS_PROJECT_A_KEY
+  SYNTARUS_PROJECT_B_KEY
+
+Optional:
+  SYNTARUS_BASE_URL (defaults to https://ai.syntarus.com/v1)
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+
+from syntarus import MemoryClient, SyntarusError
+
+
+def required(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise SystemExit(f"Missing required environment variable: {name}")
+    return value
+
+
+def main() -> None:
+    base_url = os.environ.get("SYNTARUS_BASE_URL", "https://ai.syntarus.com/v1")
+    key_a = required("SYNTARUS_PROJECT_A_KEY")
+    key_b = required("SYNTARUS_PROJECT_B_KEY")
+    marker = uuid.uuid4().hex
+    user_id = f"smoke_{marker[:12]}"
+    fact = (
+        f"My permanent enterprise isolation preference is marker {marker}. "
+        "Please remember this fact for future conversations."
+    )
+
+    with (
+        MemoryClient(key_a, base_url=base_url) as project_a,
+        MemoryClient(key_b, base_url=base_url) as project_b,
+    ):
+        accepted = project_a.add(
+            user_id=user_id,
+            agent_id="smoke_agent",
+            run_id=f"run_{marker[:12]}",
+            messages=[{"role": "user", "content": fact}],
+            metadata={"test": "enterprise-smoke"},
+            idempotency_key=f"smoke-{marker}",
+        )
+        project_a.wait_for_event(accepted["event_id"], timeout=120)
+
+        own = project_a.search(
+            "What is the enterprise isolation marker?",
+            user_id=user_id,
+            agent_id="smoke_agent",
+        )
+        if marker not in own.get("context", ""):
+            raise SystemExit("FAIL: Project A could not retrieve its own marker.")
+
+        other = project_b.search(
+            "What is the enterprise isolation marker?",
+            user_id=user_id,
+            agent_id="smoke_agent",
+        )
+        if marker in other.get("context", ""):
+            raise SystemExit("FAIL: Project B retrieved Project A memory.")
+
+        try:
+            project_b.event(accepted["event_id"])
+        except SyntarusError:
+            pass
+        else:
+            raise SystemExit("FAIL: Project B inspected Project A event.")
+
+    print("PASS: ingestion, polling, retrieval, and cross-project isolation")
+
+
+if __name__ == "__main__":
+    main()

syntarus-0.2.0/examples/langchain_agent.py

@@ -0,0 +1,38 @@
+"""
+Example 2 — LangChain agent with MemoryOS as external memory.
+Replaces LangChain's built-in ConversationBufferMemory.
+"""
+
+from langchain_groq import ChatGroq
+from langchain.schema import HumanMessage, SystemMessage
+from memoryos_client import MemoryOS
+
+mem = MemoryOS(api_key="mk_langchain", auto_approve=True)
+llm = ChatGroq(model="openai/gpt-oss-120b")
+
+
+def run_agent(user_message: str, conversation_id: str = "lc_session") -> str:
+    # Pull memory context
+    memory_context = mem.get_context(user_message)
+
+    system_content = "You are a helpful LangChain agent with long-term memory."
+    if memory_context:
+        system_content += f"\n\nUser memory:\n{memory_context}"
+
+    messages = [
+        SystemMessage(content=system_content),
+        HumanMessage(content=user_message),
+    ]
+
+    response = llm.invoke(messages)
+    assistant_text = response.content
+
+    # Write to memory (auto_approve=True so no UI review needed for bots)
+    mem.ingest(user_message, assistant_text, conversation_id=conversation_id)
+
+    return assistant_text
+
+
+if __name__ == "__main__":
+    print(run_agent("I'm building a SaaS product targeting developers"))
+    print(run_agent("What should I focus on for my product?"))

syntarus-0.2.0/examples/webhook_verify.py

@@ -0,0 +1,23 @@
+"""Verify Syntarus webhook signatures from a raw body.
+
+Receivers must pass the exact bytes received over the network. This helper is
+deliberately framework-neutral so it can be used by Flask, FastAPI, Django,
+or a serverless handler without forwarding customer payloads elsewhere.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_signature(*, secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
+    expected = "sha256=" + hmac.new(
+        secret.encode("utf-8"),
+        timestamp.encode("ascii") + b"." + raw_body,
+        hashlib.sha256,
+    ).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+
+__all__ = ["verify_signature"]

syntarus-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "syntarus"
+version = "0.2.0"
+description = "Project-scoped memory client for Syntarus"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Syntarus" }]
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["ai", "agents", "memory", "llm"]
+classifiers = ["License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13"]
+
+[project.optional-dependencies]
+test = ["pytest>=8,<9", "pytest-asyncio>=0.24,<1", "build>=1.2,<2", "twine>=5,<7"]
+
+[project.urls]
+Documentation = "https://www.syntarus.com/pages/developers.html"
+Homepage = "https://www.syntarus.com"
+Source = "https://github.com/sujalkherawat25-stack/memoryos/tree/main/sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/syntarus"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/syntarus",
+    "tests",
+    "examples",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+exclude = ["mcp/**", "memoryos_client.py", "**/__pycache__/**"]

syntarus-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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/tests/test_client.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from syntarus import AsyncMemoryClient, EventFailedError, MemoryClient, RateLimitError
+
+
+def _sync_client(handler) -> MemoryClient:
+    client = MemoryClient("sk_mem_test", base_url="https://api.test/v1")
+    client._client.close()
+    client._client = httpx.Client(
+        base_url="https://api.test/v1",
+        headers=client._headers,
+        transport=httpx.MockTransport(handler),
+    )
+    return client
+
+
+def _async_client(handler) -> AsyncMemoryClient:
+    client = AsyncMemoryClient("sk_mem_test", base_url="https://api.test/v1")
+    client._client = httpx.AsyncClient(
+        base_url="https://api.test/v1",
+        headers=client._headers,
+        transport=httpx.MockTransport(handler),
+    )
+    return client
+
+
+def test_add_sends_scope_metadata_and_idempotency_key():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/memories"
+        assert request.headers["authorization"] == "Bearer sk_mem_test"
+        assert request.headers["idempotency-key"] == "call-1"
+        body = json.loads(request.content)
+        assert body["agent_id"] == "support"
+        assert body["run_id"] == "ticket-1"
+        assert body["metadata"] == {"channel": "voice"}
+        return httpx.Response(202, json={"event_id": "evt_1", "status": "pending"})
+
+    with _sync_client(handler) as client:
+        response = client.add(
+            user_id="customer_1",
+            agent_id="support",
+            run_id="ticket-1",
+            metadata={"channel": "voice"},
+            messages=[{"role": "user", "content": "hello"}],
+            idempotency_key="call-1",
+        )
+    assert response["event_id"] == "evt_1"
+
+
+def test_wait_for_event_returns_success_without_extra_sleep():
+    statuses = iter(["processing", "succeeded"])
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        status = next(statuses)
+        return httpx.Response(200, json={"id": "evt_1", "status": status})
+
+    with _sync_client(handler) as client:
+        event = client.wait_for_event("evt_1", timeout=1, poll_interval=0.001)
+    assert event["status"] == "succeeded"
+
+
+def test_wait_for_event_raises_terminal_error():
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"id": "evt_1", "status": "dead_letter", "last_error": "extractor failed"})
+
+    with _sync_client(handler) as client, pytest.raises(EventFailedError, match="extractor failed") as exc:
+        client.wait_for_event("evt_1", timeout=1, poll_interval=0.001)
+    assert exc.value.event["id"] == "evt_1"
+
+
+def test_rate_limit_exposes_retry_after():
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(429, headers={"Retry-After": "7"}, json={"detail": "slow down"})
+
+    with _sync_client(handler) as client, pytest.raises(RateLimitError) as exc:
+        client.search("hello", user_id="customer_1")
+    assert exc.value.retry_after == 7
+
+
+def test_webhook_management_surface():
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.method == "POST":
+            return httpx.Response(201, json={"webhook": {"id": "wh_1"}, "signing_secret": "secret"})
+        if request.method == "GET" and request.url.path.endswith("/deliveries"):
+            return httpx.Response(200, json={"deliveries": []})
+        if request.method == "GET":
+            return httpx.Response(200, json={"webhooks": []})
+        return httpx.Response(204)
+
+    with _sync_client(handler) as client:
+        created = client.create_webhook("https://example.com/events")
+        client.list_webhooks()
+        client.webhook_deliveries(webhook_id="wh_1", limit=25)
+        client.delete_webhook("wh_1")
+
+    assert created["signing_secret"] == "secret"
+    assert requests[2].url.params["webhook_id"] == "wh_1"
+    assert requests[2].url.params["limit"] == "25"
+
+
+def test_optional_query_parameters_are_omitted_not_sent_empty():
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.method == "GET" and request.url.path.endswith("/export"):
+            return httpx.Response(200, json={"memories": []})
+        if request.method == "GET":
+            return httpx.Response(200, json={"deliveries": []})
+        return httpx.Response(204)
+
+    with _sync_client(handler) as client:
+        client.export(user_id="customer_1")
+        client.delete_user(user_id="customer_1")
+        client.webhook_deliveries()
+
+    assert "agent_id" not in requests[0].url.params
+    assert "agent_id" not in requests[1].url.params
+    assert "webhook_id" not in requests[2].url.params
+
+
+@pytest.mark.asyncio
+async def test_async_search_and_delete_are_agent_scoped():
+    requests: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.method == "POST":
+            assert json.loads(request.content)["agent_id"] == "sales"
+            return httpx.Response(200, json={"results": [], "context": "", "latency_ms": 1})
+        return httpx.Response(204)
+
+    async with _async_client(handler) as client:
+        await client.search("preferences", user_id="customer_1", agent_id="sales")
+        await client.delete_user(user_id="customer_1", agent_id="sales")
+
+    assert requests[1].url.params["agent_id"] == "sales"

syntarus-0.2.0/tests/test_webhook_verify.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+from examples.webhook_verify import verify_signature
+
+
+def test_webhook_verifier_uses_raw_body_and_timestamp():
+    secret = "test-secret"
+    timestamp = "1700000000"
+    body = b'{"z":1,"a":2}'
+    signature = "sha256=" + hmac.new(
+        secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256
+    ).hexdigest()
+
+    assert verify_signature(secret=secret, timestamp=timestamp, raw_body=body, signature=signature)
+    assert not verify_signature(secret=secret, timestamp=timestamp, raw_body=b'{"a":2,"z":1}', signature=signature)
+    assert not verify_signature(secret=secret, timestamp="1700000001", raw_body=body, signature=signature)