switchy-sdk 0.1.0__tar.gz

switchy_sdk-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.pyo
+dist/
+build/
+*.egg-info/
+.venv/
+.claude-flow/

switchy_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: switchy-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Switchy AI memory and chat API
+Project-URL: Homepage, https://switchy.build
+Project-URL: Documentation, https://switchy.build/api-dashboard
+Project-URL: Repository, https://github.com/Switchy-AI/switchy
+Project-URL: Bug Tracker, https://github.com/Switchy-AI/switchy/issues
+Author-email: Switchy AI <contact@switchy.build>
+License: MIT
+Keywords: ai,knowledge-graph,memory,openrouter,sdk,switchy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# switchy-sdk
+
+Official Python SDK for the [Switchy AI](https://switchy.build) memory, knowledge-graph, and multi-model chat API.
+
+## Install
+
+```bash
+pip install switchy-sdk
+```
+
+## Quick start
+
+```python
+from switchy import Switchy
+
+client = Switchy(api_key="switchy_...")
+
+response = client.chat.complete(
+    model="anthropic/claude-sonnet-4",
+    message="Summarise my recent project notes",
+    memory={"enabled": True, "extractMemories": True},
+)
+
+print(response["message"]["content"])
+```
+
+## Streaming
+
+```python
+for chunk in client.chat.stream(
+    model="openai/gpt-5",
+    message="Write a haiku about memory",
+):
+    if chunk.get("type") == "token":
+        print(chunk.get("content", ""), end="", flush=True)
+```
+
+## Async
+
+```python
+import asyncio
+from switchy import AsyncSwitchy
+
+async def main():
+    async with AsyncSwitchy(api_key="switchy_...") as client:
+        res = await client.chat.complete(
+            model="anthropic/claude-sonnet-4",
+            message="Hello",
+        )
+        print(res["message"]["content"])
+
+asyncio.run(main())
+```
+
+## Memory
+
+```python
+# Create a namespace
+client.namespaces.create(name="my-project")
+
+# Store a memory frame
+client.memory.create_frame(
+    "my-project",
+    content="User prefers dark mode and TypeScript",
+    metadata={"source": "onboarding"},
+)
+
+# Contextual retrieval
+relevant = client.memory.context("my-project", query="user preferences", limit=5)
+```
+
+## Knowledge graph
+
+```python
+client.knowledge_graph.create_entity(
+    "my-project", name="AuthService", type="service"
+)
+
+client.knowledge_graph.create_relation(
+    "my-project", source="AuthService", target="User", type="authenticates"
+)
+```
+
+## Error handling
+
+```python
+from switchy import Switchy, SwitchyError, RateLimitError
+
+try:
+    client.chat.complete(model="openai/gpt-5", message="hi")
+except RateLimitError as e:
+    print(f"Rate limited, retry in {e.retry_after}s (limit={e.limit})")
+except SwitchyError as e:
+    print(f"API error: {e.code} — {e}")
+```
+
+## API reference
+
+- `chat.complete(...)` — single-turn completion
+- `chat.stream(...)` — SSE streaming iterator
+- `models.list(featured=True)` — list available models (350+)
+- `namespaces.{create,list,get,update,delete}` — memory namespace management
+- `memory.{create_frame,list_frames,context,semantic,search,bridge,consolidate}` — memory operations
+- `knowledge_graph.{create_entity,create_relation,query}` — graph operations
+- `sessions.{create,list,get}` — session management
+
+Full OpenAPI spec: https://switchy.build/api/v1/openapi.json
+
+## License
+
+MIT

switchy_sdk-0.1.0/README.md

@@ -0,0 +1,111 @@
+# switchy-sdk
+
+Official Python SDK for the [Switchy AI](https://switchy.build) memory, knowledge-graph, and multi-model chat API.
+
+## Install
+
+```bash
+pip install switchy-sdk
+```
+
+## Quick start
+
+```python
+from switchy import Switchy
+
+client = Switchy(api_key="switchy_...")
+
+response = client.chat.complete(
+    model="anthropic/claude-sonnet-4",
+    message="Summarise my recent project notes",
+    memory={"enabled": True, "extractMemories": True},
+)
+
+print(response["message"]["content"])
+```
+
+## Streaming
+
+```python
+for chunk in client.chat.stream(
+    model="openai/gpt-5",
+    message="Write a haiku about memory",
+):
+    if chunk.get("type") == "token":
+        print(chunk.get("content", ""), end="", flush=True)
+```
+
+## Async
+
+```python
+import asyncio
+from switchy import AsyncSwitchy
+
+async def main():
+    async with AsyncSwitchy(api_key="switchy_...") as client:
+        res = await client.chat.complete(
+            model="anthropic/claude-sonnet-4",
+            message="Hello",
+        )
+        print(res["message"]["content"])
+
+asyncio.run(main())
+```
+
+## Memory
+
+```python
+# Create a namespace
+client.namespaces.create(name="my-project")
+
+# Store a memory frame
+client.memory.create_frame(
+    "my-project",
+    content="User prefers dark mode and TypeScript",
+    metadata={"source": "onboarding"},
+)
+
+# Contextual retrieval
+relevant = client.memory.context("my-project", query="user preferences", limit=5)
+```
+
+## Knowledge graph
+
+```python
+client.knowledge_graph.create_entity(
+    "my-project", name="AuthService", type="service"
+)
+
+client.knowledge_graph.create_relation(
+    "my-project", source="AuthService", target="User", type="authenticates"
+)
+```
+
+## Error handling
+
+```python
+from switchy import Switchy, SwitchyError, RateLimitError
+
+try:
+    client.chat.complete(model="openai/gpt-5", message="hi")
+except RateLimitError as e:
+    print(f"Rate limited, retry in {e.retry_after}s (limit={e.limit})")
+except SwitchyError as e:
+    print(f"API error: {e.code} — {e}")
+```
+
+## API reference
+
+- `chat.complete(...)` — single-turn completion
+- `chat.stream(...)` — SSE streaming iterator
+- `models.list(featured=True)` — list available models (350+)
+- `namespaces.{create,list,get,update,delete}` — memory namespace management
+- `memory.{create_frame,list_frames,context,semantic,search,bridge,consolidate}` — memory operations
+- `knowledge_graph.{create_entity,create_relation,query}` — graph operations
+- `sessions.{create,list,get}` — session management
+
+Full OpenAPI spec: https://switchy.build/api/v1/openapi.json
+
+## License
+
+MIT

switchy_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "switchy-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Switchy AI memory and chat API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Switchy AI", email = "contact@switchy.build" }]
+keywords = ["switchy", "ai", "memory", "knowledge-graph", "openrouter", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "ruff>=0.1.0"]
+
+[project.urls]
+Homepage = "https://switchy.build"
+Documentation = "https://switchy.build/api-dashboard"
+Repository = "https://github.com/Switchy-AI/switchy"
+"Bug Tracker" = "https://github.com/Switchy-AI/switchy/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["switchy"]

switchy_sdk-0.1.0/switchy/__init__.py

@@ -0,0 +1,17 @@
+"""Switchy AI Python SDK.
+
+Install:
+    pip install switchy-sdk
+
+Usage:
+    from switchy import Switchy
+    client = Switchy(api_key="switchy_...")
+    res = client.chat.complete(model="anthropic/claude-sonnet-4", message="Hello")
+    print(res["message"]["content"])
+"""
+
+from .client import Switchy, AsyncSwitchy
+from .errors import SwitchyError, RateLimitError
+
+__version__ = "0.1.0"
+__all__ = ["Switchy", "AsyncSwitchy", "SwitchyError", "RateLimitError"]

switchy_sdk-0.1.0/switchy/client.py

@@ -0,0 +1,372 @@
+"""Synchronous and asynchronous Switchy API clients."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional
+
+import httpx
+
+from .errors import RateLimitError, SwitchyError
+
+
+DEFAULT_BASE_URL = "https://switchy.build/api/v1"
+DEFAULT_TIMEOUT = 60.0
+USER_AGENT = "switchy-sdk-python/0.1.0"
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+def _unwrap(resp: httpx.Response) -> Any:
+    """Parse a Switchy API envelope and return `data`, raising on error."""
+    if resp.status_code == 429:
+        try:
+            body = resp.json()
+        except Exception:
+            body = {}
+        err = body.get("error") or {}
+        raise RateLimitError(err.get("message") or "Rate limit exceeded", err.get("details"))
+    if resp.status_code >= 400:
+        try:
+            body = resp.json()
+        except Exception:
+            raise SwitchyError(f"HTTP {resp.status_code}", "HTTP_ERROR", resp.status_code)
+        err = body.get("error") or {}
+        raise SwitchyError(
+            err.get("message") or f"HTTP {resp.status_code}",
+            err.get("code") or "HTTP_ERROR",
+            resp.status_code,
+            err.get("details"),
+        )
+    body = resp.json()
+    if not body.get("success"):
+        err = body.get("error") or {}
+        raise SwitchyError(
+            err.get("message") or "Unknown error",
+            err.get("code") or "UNKNOWN",
+            resp.status_code,
+            err.get("details"),
+        )
+    return body.get("data")
+
+
+def _clean_params(params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    if not params:
+        return {}
+    return {k: v for k, v in params.items() if v is not None}
+
+
+# ---------------------------------------------------------------------------
+# Sync client
+# ---------------------------------------------------------------------------
+
+class Switchy:
+    """Synchronous Switchy API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.Client(
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+        )
+        self.chat = _Chat(self)
+        self.models = _Models(self)
+        self.memory = _Memory(self)
+        self.namespaces = _Namespaces(self)
+        self.sessions = _Sessions(self)
+        self.knowledge_graph = _KnowledgeGraph(self)
+
+    # ── internal ───────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Any] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        resp = self._client.request(
+            method,
+            self.base_url + path,
+            json=json_body,
+            params=_clean_params(params),
+        )
+        return _unwrap(resp)
+
+    def _stream(self, path: str, json_body: Any) -> Iterator[Dict[str, Any]]:
+        with self._client.stream(
+            "POST",
+            self.base_url + path,
+            json=json_body,
+            headers={"Accept": "text/event-stream"},
+        ) as resp:
+            if resp.status_code != 200:
+                resp.read()
+                _unwrap(resp)
+            for line in resp.iter_lines():
+                if not line or not line.startswith("data:"):
+                    continue
+                data = line[5:].strip()
+                if not data or data == "[DONE]":
+                    continue
+                try:
+                    yield json.loads(data)
+                except json.JSONDecodeError:
+                    continue
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Switchy":
+        return self
+
+    def __exit__(self, *a: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+class AsyncSwitchy:
+    """Asynchronous Switchy API client (asyncio)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.AsyncClient(
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+            },
+        )
+        self.chat = _AsyncChat(self)
+        self.models = _AsyncModels(self)
+        self.memory = _AsyncMemory(self)
+        self.namespaces = _AsyncNamespaces(self)
+        self.sessions = _AsyncSessions(self)
+        self.knowledge_graph = _AsyncKnowledgeGraph(self)
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Any] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        resp = await self._client.request(
+            method,
+            self.base_url + path,
+            json=json_body,
+            params=_clean_params(params),
+        )
+        return _unwrap(resp)
+
+    async def _stream(self, path: str, json_body: Any) -> AsyncIterator[Dict[str, Any]]:
+        async with self._client.stream(
+            "POST",
+            self.base_url + path,
+            json=json_body,
+            headers={"Accept": "text/event-stream"},
+        ) as resp:
+            if resp.status_code != 200:
+                await resp.aread()
+                _unwrap(resp)
+            async for line in resp.aiter_lines():
+                if not line or not line.startswith("data:"):
+                    continue
+                data = line[5:].strip()
+                if not data or data == "[DONE]":
+                    continue
+                try:
+                    yield json.loads(data)
+                except json.JSONDecodeError:
+                    continue
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncSwitchy":
+        return self
+
+    async def __aexit__(self, *a: Any) -> None:
+        await self.close()
+
+
+# ---------------------------------------------------------------------------
+# Resources (sync)
+# ---------------------------------------------------------------------------
+
+class _Chat:
+    def __init__(self, c: Switchy) -> None: self._c = c
+    def complete(self, *, model: str, message: str, **kwargs: Any) -> Dict[str, Any]:
+        body = {"model": model, "message": message, "stream": False, **kwargs}
+        return self._c._request("POST", "/chat", body)
+    def stream(self, *, model: str, message: str, **kwargs: Any) -> Iterator[Dict[str, Any]]:
+        body = {"model": model, "message": message, "stream": True, **kwargs}
+        return self._c._stream("/chat", body)
+
+class _Models:
+    def __init__(self, c: Switchy) -> None: self._c = c
+    def list(self, *, category: Optional[str] = None, q: Optional[str] = None, featured: Optional[bool] = None) -> Dict[str, Any]:
+        return self._c._request("GET", "/models", params={"category": category, "q": q, "featured": featured})
+
+class _Namespaces:
+    def __init__(self, c: Switchy) -> None: self._c = c
+    def create(self, *, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        return self._c._request("POST", "/namespaces", {"name": name, "description": description})
+    def list(self) -> List[Dict[str, Any]]:
+        return self._c._request("GET", "/namespaces")
+    def get(self, id: str) -> Dict[str, Any]:
+        return self._c._request("GET", f"/namespaces/{id}")
+    def update(self, id: str, **data: Any) -> Dict[str, Any]:
+        return self._c._request("PATCH", f"/namespaces/{id}", data)
+    def delete(self, id: str) -> None:
+        self._c._request("DELETE", f"/namespaces/{id}")
+
+class _Memory:
+    def __init__(self, c: Switchy) -> None: self._c = c
+    def create_frame(self, namespace: str, *, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/frames", {"content": content, "metadata": metadata})
+    def list_frames(self, namespace: str, *, limit: Optional[int] = None, offset: Optional[int] = None, status: Optional[str] = None) -> List[Dict[str, Any]]:
+        return self._c._request("GET", f"/memory/{namespace}/frames", params={"limit": limit, "offset": offset, "status": status})
+    def get_frame(self, namespace: str, id: str) -> Dict[str, Any]:
+        return self._c._request("GET", f"/memory/{namespace}/frames/{id}")
+    def update_frame(self, namespace: str, id: str, **data: Any) -> Dict[str, Any]:
+        return self._c._request("PATCH", f"/memory/{namespace}/frames/{id}", data)
+    def close_frame(self, namespace: str, id: str) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/frames/{id}/close")
+    def context(self, namespace: str, *, query: str, limit: Optional[int] = None) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/context", {"query": query, "limit": limit})
+    def semantic(self, namespace: str, *, query: str, limit: Optional[int] = None, threshold: Optional[float] = None) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/semantic", {"query": query, "limit": limit, "threshold": threshold})
+    def search(self, *, query: str, namespaces: Optional[List[str]] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        return self._c._request("POST", "/memory/search", {"query": query, "namespaces": namespaces, "limit": limit})
+    def bridge(self, namespace: str, *, source_namespace: str, frame_ids: Optional[List[str]] = None, mode: str = "link") -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/bridge", {"sourceNamespace": source_namespace, "frameIds": frame_ids, "mode": mode})
+    def consolidate(self, namespace: str) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/consolidate")
+
+class _KnowledgeGraph:
+    def __init__(self, c: Switchy) -> None: self._c = c
+    def list_entities(self, namespace: str) -> List[Dict[str, Any]]:
+        return self._c._request("GET", f"/memory/{namespace}/graph/entities")
+    def create_entity(self, namespace: str, *, name: str, type: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/graph/entities", {"name": name, "type": type, "metadata": metadata})
+    def list_relations(self, namespace: str) -> List[Dict[str, Any]]:
+        return self._c._request("GET", f"/memory/{namespace}/graph/relations")
+    def create_relation(self, namespace: str, *, source: str, target: str, type: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._c._request("POST", f"/memory/{namespace}/graph/relations", {"source": source, "target": target, "type": type, "metadata": metadata})
+    def query(self, *, query: str, depth: Optional[int] = None, namespace: Optional[str] = None) -> Dict[str, Any]:
+        return self._c._request("POST", "/knowledge-graph", {"query": query, "depth": depth, "namespace": namespace})
+
+class _Sessions:
+    def __init__(self, c: Switchy) -> None: self._c = c
+    def create(self, **data: Any) -> Dict[str, Any]:
+        return self._c._request("POST", "/sessions", data)
+    def list(self) -> List[Dict[str, Any]]:
+        return self._c._request("GET", "/sessions")
+    def get(self, id: str) -> Dict[str, Any]:
+        return self._c._request("GET", f"/sessions/{id}")
+
+
+# ---------------------------------------------------------------------------
+# Resources (async) — mirrors the sync ones
+# ---------------------------------------------------------------------------
+
+class _AsyncChat:
+    def __init__(self, c: AsyncSwitchy) -> None: self._c = c
+    async def complete(self, *, model: str, message: str, **kwargs: Any) -> Dict[str, Any]:
+        body = {"model": model, "message": message, "stream": False, **kwargs}
+        return await self._c._request("POST", "/chat", body)
+    def stream(self, *, model: str, message: str, **kwargs: Any) -> AsyncIterator[Dict[str, Any]]:
+        body = {"model": model, "message": message, "stream": True, **kwargs}
+        return self._c._stream("/chat", body)
+
+class _AsyncModels:
+    def __init__(self, c: AsyncSwitchy) -> None: self._c = c
+    async def list(self, *, category: Optional[str] = None, q: Optional[str] = None, featured: Optional[bool] = None) -> Dict[str, Any]:
+        return await self._c._request("GET", "/models", params={"category": category, "q": q, "featured": featured})
+
+class _AsyncNamespaces:
+    def __init__(self, c: AsyncSwitchy) -> None: self._c = c
+    async def create(self, *, name: str, description: Optional[str] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", "/namespaces", {"name": name, "description": description})
+    async def list(self) -> List[Dict[str, Any]]:
+        return await self._c._request("GET", "/namespaces")
+    async def get(self, id: str) -> Dict[str, Any]:
+        return await self._c._request("GET", f"/namespaces/{id}")
+    async def update(self, id: str, **data: Any) -> Dict[str, Any]:
+        return await self._c._request("PATCH", f"/namespaces/{id}", data)
+    async def delete(self, id: str) -> None:
+        await self._c._request("DELETE", f"/namespaces/{id}")
+
+class _AsyncMemory:
+    def __init__(self, c: AsyncSwitchy) -> None: self._c = c
+    async def create_frame(self, namespace: str, *, content: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/frames", {"content": content, "metadata": metadata})
+    async def list_frames(self, namespace: str, *, limit: Optional[int] = None, offset: Optional[int] = None, status: Optional[str] = None) -> List[Dict[str, Any]]:
+        return await self._c._request("GET", f"/memory/{namespace}/frames", params={"limit": limit, "offset": offset, "status": status})
+    async def get_frame(self, namespace: str, id: str) -> Dict[str, Any]:
+        return await self._c._request("GET", f"/memory/{namespace}/frames/{id}")
+    async def update_frame(self, namespace: str, id: str, **data: Any) -> Dict[str, Any]:
+        return await self._c._request("PATCH", f"/memory/{namespace}/frames/{id}", data)
+    async def close_frame(self, namespace: str, id: str) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/frames/{id}/close")
+    async def context(self, namespace: str, *, query: str, limit: Optional[int] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/context", {"query": query, "limit": limit})
+    async def semantic(self, namespace: str, *, query: str, limit: Optional[int] = None, threshold: Optional[float] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/semantic", {"query": query, "limit": limit, "threshold": threshold})
+    async def search(self, *, query: str, namespaces: Optional[List[str]] = None, limit: Optional[int] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", "/memory/search", {"query": query, "namespaces": namespaces, "limit": limit})
+    async def bridge(self, namespace: str, *, source_namespace: str, frame_ids: Optional[List[str]] = None, mode: str = "link") -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/bridge", {"sourceNamespace": source_namespace, "frameIds": frame_ids, "mode": mode})
+    async def consolidate(self, namespace: str) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/consolidate")
+
+class _AsyncKnowledgeGraph:
+    def __init__(self, c: AsyncSwitchy) -> None: self._c = c
+    async def list_entities(self, namespace: str) -> List[Dict[str, Any]]:
+        return await self._c._request("GET", f"/memory/{namespace}/graph/entities")
+    async def create_entity(self, namespace: str, *, name: str, type: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/graph/entities", {"name": name, "type": type, "metadata": metadata})
+    async def list_relations(self, namespace: str) -> List[Dict[str, Any]]:
+        return await self._c._request("GET", f"/memory/{namespace}/graph/relations")
+    async def create_relation(self, namespace: str, *, source: str, target: str, type: str, metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", f"/memory/{namespace}/graph/relations", {"source": source, "target": target, "type": type, "metadata": metadata})
+    async def query(self, *, query: str, depth: Optional[int] = None, namespace: Optional[str] = None) -> Dict[str, Any]:
+        return await self._c._request("POST", "/knowledge-graph", {"query": query, "depth": depth, "namespace": namespace})
+
+class _AsyncSessions:
+    def __init__(self, c: AsyncSwitchy) -> None: self._c = c
+    async def create(self, **data: Any) -> Dict[str, Any]:
+        return await self._c._request("POST", "/sessions", data)
+    async def list(self) -> List[Dict[str, Any]]:
+        return await self._c._request("GET", "/sessions")
+    async def get(self, id: str) -> Dict[str, Any]:
+        return await self._c._request("GET", f"/sessions/{id}")

switchy_sdk-0.1.0/switchy/errors.py

@@ -0,0 +1,39 @@
+"""Exception types raised by the Switchy SDK."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Optional
+
+
+class SwitchyError(Exception):
+    """Base error for all SDK failures."""
+
+    def __init__(
+        self,
+        message: str,
+        code: str = "UNKNOWN",
+        status: int = 0,
+        details: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"SwitchyError(code={self.code!r}, status={self.status}, message={self.args[0]!r})"
+
+
+class RateLimitError(SwitchyError):
+    """Raised when the API returns 429 Too Many Requests."""
+
+    def __init__(self, message: str, details: Optional[dict] = None) -> None:
+        super().__init__(message, "RATE_LIMIT_EXCEEDED", 429, details)
+        details = details or {}
+        self.retry_after: int = int(details.get("retryAfter") or 60)
+        self.limit: Optional[int] = details.get("limit")
+        reset_at = details.get("resetAt")
+        self.reset_at: Optional[datetime] = (
+            datetime.fromisoformat(reset_at.replace("Z", "+00:00")) if reset_at else None
+        )