cogspace 0.1.0__tar.gz

cogspace-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+venv/
+ENV/
+env/
+.venv
+
+# Node
+node_modules/
+npm-debug.log
+yarn-error.log
+.next/
+out/
+.turbo/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Data
+*.db
+*.sqlite
+*.sqlite3
+data/
+.cogspace/
+examples/*/memory.db
+examples/*/bm25_index/
+examples/*/lancedb/
+
+# Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Logs
+*.log
+logs/

cogspace-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: cogspace
+Version: 0.1.0
+Summary: Official Cogspace SDK — add a knowledge layer to any AI agent
+Project-URL: Homepage, https://cogspace.ai
+Project-URL: Documentation, https://docs.cogspace.ai
+Project-URL: Repository, https://github.com/Jack-Pision/cogspace-ai
+Project-URL: Issues, https://github.com/Jack-Pision/cogspace-ai/issues
+Author-email: Cogspace <sdk@cogspace.ai>
+License: MIT
+Keywords: agents,ai,knowledge,memory,rag,sdk
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cogspace
+
+Official Python SDK for [Cogspace](https://cogspace.ai) — add a persistent knowledge layer to any AI agent.
+
+## Install
+
+```bash
+pip install cogspace
+```
+
+## Quickstart
+
+```python
+from cogspace import Cogspace
+
+cog = Cogspace(api_key="cs-...")
+
+# Get a space-scoped client
+space = cog.space("my-agent")
+
+# Search
+results = space.search("retry logic with backoff")
+for r in results.results:
+    print(r.file_path, r.score)
+
+# Write knowledge
+space.write("expertise/retry.md", """
+# Retry patterns
+Always use exponential backoff with jitter.
+""")
+
+# Read the hot layer (always-injected context)
+context = space.hot_layer()
+
+# Memory
+space.write_memory("Currently working on the payment service refactor.")
+memory = space.read_memory()
+```
+
+## Async
+
+```python
+from cogspace import AsyncCogspace
+
+async def main():
+    cog = AsyncCogspace(api_key="cs-...")
+    space = await cog.space("my-agent")
+    results = await space.search("retry logic")
+    await cog.aclose()
+```
+
+Or use as a context manager:
+
+```python
+async with AsyncCogspace(api_key="cs-...") as cog:
+    space = await cog.space("my-agent")
+    await space.write("expertise/notes.md", "...")
+```
+
+## API Reference
+
+### `Cogspace(api_key, base_url, timeout, max_retries)`
+
+| Method | Description |
+|---|---|
+| `cog.space(name_or_id)` | Get a space client |
+| `cog.list_spaces()` | List all your spaces |
+| `cog.create_space(name)` | Create a new space |
+
+### `SpaceClient`
+
+| Method | Description |
+|---|---|
+| `space.search(query, mode, top_k, layer)` | Hybrid / vector / keyword search |
+| `space.read(path)` | Read a file by path |
+| `space.write(path, content, metadata)` | Write or update a file |
+| `space.list(folder)` | List files in a folder |
+| `space.read_memory()` | Read `memory.md` |
+| `space.write_memory(content, confidence)` | Update `memory.md` |
+| `space.read_context()` | Read `memory/user/` context files |
+| `space.hot_layer()` | Get full hot layer injection string |
+| `space.graph_traverse(path, depth, rel_type)` | Traverse knowledge graph |
+| `space.health()` | Space health and storage stats |
+
+## Errors
+
+All exceptions inherit from `CogspaceError`:
+
+```python
+from cogspace.exceptions import AuthError, NotFoundError, RateLimitError
+
+try:
+    space.search("query")
+except AuthError:
+    print("Invalid API key")
+except NotFoundError:
+    print("Space not found")
+```
+
+## Get an API key
+
+Sign in at [platform.cogspace.ai](https://platform.cogspace.ai), go to **Settings → API keys**, and create a key.

cogspace-0.1.0/README.md

@@ -0,0 +1,102 @@
+# cogspace
+
+Official Python SDK for [Cogspace](https://cogspace.ai) — add a persistent knowledge layer to any AI agent.
+
+## Install
+
+```bash
+pip install cogspace
+```
+
+## Quickstart
+
+```python
+from cogspace import Cogspace
+
+cog = Cogspace(api_key="cs-...")
+
+# Get a space-scoped client
+space = cog.space("my-agent")
+
+# Search
+results = space.search("retry logic with backoff")
+for r in results.results:
+    print(r.file_path, r.score)
+
+# Write knowledge
+space.write("expertise/retry.md", """
+# Retry patterns
+Always use exponential backoff with jitter.
+""")
+
+# Read the hot layer (always-injected context)
+context = space.hot_layer()
+
+# Memory
+space.write_memory("Currently working on the payment service refactor.")
+memory = space.read_memory()
+```
+
+## Async
+
+```python
+from cogspace import AsyncCogspace
+
+async def main():
+    cog = AsyncCogspace(api_key="cs-...")
+    space = await cog.space("my-agent")
+    results = await space.search("retry logic")
+    await cog.aclose()
+```
+
+Or use as a context manager:
+
+```python
+async with AsyncCogspace(api_key="cs-...") as cog:
+    space = await cog.space("my-agent")
+    await space.write("expertise/notes.md", "...")
+```
+
+## API Reference
+
+### `Cogspace(api_key, base_url, timeout, max_retries)`
+
+| Method | Description |
+|---|---|
+| `cog.space(name_or_id)` | Get a space client |
+| `cog.list_spaces()` | List all your spaces |
+| `cog.create_space(name)` | Create a new space |
+
+### `SpaceClient`
+
+| Method | Description |
+|---|---|
+| `space.search(query, mode, top_k, layer)` | Hybrid / vector / keyword search |
+| `space.read(path)` | Read a file by path |
+| `space.write(path, content, metadata)` | Write or update a file |
+| `space.list(folder)` | List files in a folder |
+| `space.read_memory()` | Read `memory.md` |
+| `space.write_memory(content, confidence)` | Update `memory.md` |
+| `space.read_context()` | Read `memory/user/` context files |
+| `space.hot_layer()` | Get full hot layer injection string |
+| `space.graph_traverse(path, depth, rel_type)` | Traverse knowledge graph |
+| `space.health()` | Space health and storage stats |
+
+## Errors
+
+All exceptions inherit from `CogspaceError`:
+
+```python
+from cogspace.exceptions import AuthError, NotFoundError, RateLimitError
+
+try:
+    space.search("query")
+except AuthError:
+    print("Invalid API key")
+except NotFoundError:
+    print("Space not found")
+```
+
+## Get an API key
+
+Sign in at [platform.cogspace.ai](https://platform.cogspace.ai), go to **Settings → API keys**, and create a key.

cogspace-0.1.0/cogspace/__init__.py

@@ -0,0 +1,203 @@
+"""
+Cogspace SDK — add a knowledge layer to any AI agent.
+
+Quickstart (sync):
+    from cogspace import Cogspace
+
+    cog = Cogspace(api_key="cs-...")
+    space = cog.space("my-agent")
+    results = space.search("retry logic with backoff")
+    space.write("expertise/retry.md", "# Retry patterns\\n...")
+    context = space.hot_layer()
+
+Quickstart (async):
+    from cogspace import AsyncCogspace
+
+    cog = AsyncCogspace(api_key="cs-...")
+    space = cog.space("my-agent")
+    results = await space.search("retry logic with backoff")
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from cogspace._async_client import AsyncClient
+from cogspace._async_space import AsyncSpaceClient
+from cogspace._client import SyncClient
+from cogspace._space import SpaceClient
+from cogspace.exceptions import (
+    AuthError,
+    CogspaceError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+)
+from cogspace.types import (
+    ContextFile,
+    GraphEdge,
+    GraphNode,
+    GraphTraverseResponse,
+    HealthResponse,
+    ListResponse,
+    ReadContextResponse,
+    ReadResponse,
+    SearchItem,
+    SearchResponse,
+    Space,
+    WriteResponse,
+)
+
+DEFAULT_BASE_URL = "https://platform.cogspace.ai"
+
+
+class Cogspace:
+    """
+    Sync Cogspace client.
+
+    Args:
+        api_key: Your Cogspace API key (starts with 'cs-').
+        base_url: Platform URL. Defaults to https://platform.cogspace.ai.
+        timeout: Request timeout in seconds. Default 30.
+        max_retries: Number of retries on 429/5xx. Default 3.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._client = SyncClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._space_cache: dict[str, str] = {}  # name -> id
+
+    def _resolve_space_id(self, space_name_or_id: str) -> str:
+        """Resolve a space name to its ID, caching the result."""
+        if space_name_or_id in self._space_cache:
+            return self._space_cache[space_name_or_id]
+        spaces = self._client.get("/spaces")
+        for s in spaces:
+            if s["name"] == space_name_or_id or s["id"] == space_name_or_id:
+                self._space_cache[s["name"]] = s["id"]
+                self._space_cache[s["id"]] = s["id"]
+                return s["id"]
+        raise NotFoundError(f"Space not found: {space_name_or_id!r}")
+
+    def space(self, name_or_id: str) -> SpaceClient:
+        """Get a space-scoped client by space name or ID."""
+        space_id = self._resolve_space_id(name_or_id)
+        return SpaceClient(self._client, space_id)
+
+    def list_spaces(self) -> list[Space]:
+        """List all your spaces."""
+        data = self._client.get("/spaces")
+        return [Space.model_validate(s) for s in data]
+
+    def create_space(self, name: str) -> Space:
+        """Create a new space."""
+        data = self._client.post("/spaces", json={"name": name})
+        return Space.model_validate(data)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "Cogspace":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+
+class AsyncCogspace:
+    """
+    Async Cogspace client.
+
+    Args:
+        api_key: Your Cogspace API key (starts with 'cs-').
+        base_url: Platform URL. Defaults to https://platform.cogspace.ai.
+        timeout: Request timeout in seconds. Default 30.
+        max_retries: Number of retries on 429/5xx. Default 3.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._client = AsyncClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._space_cache: dict[str, str] = {}
+
+    async def _resolve_space_id(self, space_name_or_id: str) -> str:
+        if space_name_or_id in self._space_cache:
+            return self._space_cache[space_name_or_id]
+        spaces = await self._client.get("/spaces")
+        for s in spaces:
+            if s["name"] == space_name_or_id or s["id"] == space_name_or_id:
+                self._space_cache[s["name"]] = s["id"]
+                self._space_cache[s["id"]] = s["id"]
+                return s["id"]
+        raise NotFoundError(f"Space not found: {space_name_or_id!r}")
+
+    async def space(self, name_or_id: str) -> AsyncSpaceClient:
+        """Get a space-scoped async client by space name or ID."""
+        space_id = await self._resolve_space_id(name_or_id)
+        return AsyncSpaceClient(self._client, space_id)
+
+    async def list_spaces(self) -> list[Space]:
+        data = await self._client.get("/spaces")
+        return [Space.model_validate(s) for s in data]
+
+    async def create_space(self, name: str) -> Space:
+        data = await self._client.post("/spaces", json={"name": name})
+        return Space.model_validate(data)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncCogspace":
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.aclose()
+
+
+__all__ = [
+    "Cogspace",
+    "AsyncCogspace",
+    "SpaceClient",
+    "AsyncSpaceClient",
+    "CogspaceError",
+    "AuthError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "TimeoutError",
+    "SearchResponse",
+    "SearchItem",
+    "ReadResponse",
+    "WriteResponse",
+    "ListResponse",
+    "ReadContextResponse",
+    "ContextFile",
+    "GraphTraverseResponse",
+    "GraphNode",
+    "GraphEdge",
+    "HealthResponse",
+    "Space",
+]
+
+__version__ = "0.1.0"

cogspace-0.1.0/cogspace/_async_client.py

@@ -0,0 +1,93 @@
+"""Async HTTP client for the Cogspace SDK."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from cogspace.exceptions import RateLimitError, TimeoutError, _raise_for_status
+
+DEFAULT_BASE_URL = "https://platform.cogspace.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+_RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._http = httpx.AsyncClient(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": "cogspace-python/0.1.0"},
+            timeout=timeout,
+        )
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> dict:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries):
+            try:
+                response = await self._http.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(f"Request timed out: {path}") from exc
+
+            if response.status_code not in _RETRY_STATUSES:
+                if response.status_code >= 400:
+                    try:
+                        body = response.json()
+                    except Exception:
+                        body = {}
+                    _raise_for_status(response.status_code, body)
+                return response.json() if response.content else {}
+
+            if attempt < self._max_retries - 1:
+                wait = 2 ** attempt
+                if response.status_code == 429:
+                    retry_after = response.headers.get("Retry-After")
+                    if retry_after:
+                        wait = float(retry_after)
+                await asyncio.sleep(wait)
+                try:
+                    body = response.json()
+                except Exception:
+                    body = {}
+                last_exc = RateLimitError(
+                    body.get("detail", f"HTTP {response.status_code}"),
+                    status=response.status_code,
+                )
+            else:
+                try:
+                    body = response.json()
+                except Exception:
+                    body = {}
+                _raise_for_status(response.status_code, body)
+
+        raise last_exc or RateLimitError("Max retries exceeded")
+
+    async def get(self, path: str, params: dict | None = None) -> dict:
+        return await self._request("GET", path, params=params)
+
+    async def post(self, path: str, json: dict | None = None) -> dict:
+        return await self._request("POST", path, json=json)
+
+    async def delete(self, path: str) -> dict:
+        return await self._request("DELETE", path)

cogspace-0.1.0/cogspace/_async_space.py

@@ -0,0 +1,105 @@
+"""AsyncSpaceClient — async space-scoped operations."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from cogspace._async_client import AsyncClient
+from cogspace.types import (
+    GraphTraverseResponse,
+    HealthResponse,
+    ListResponse,
+    ReadContextResponse,
+    ReadResponse,
+    SearchResponse,
+    WriteResponse,
+)
+
+
+class AsyncSpaceClient:
+    """Async client scoped to a single Cogspace space."""
+
+    def __init__(self, client: AsyncClient, space_id: str) -> None:
+        self._c = client
+        self._space_id = space_id
+
+    def _path(self, endpoint: str) -> str:
+        return f"/spaces/{self._space_id}/{endpoint}"
+
+    async def search(
+        self,
+        query: str,
+        mode: Literal["hybrid", "vector", "bm25"] = "hybrid",
+        top_k: int = 5,
+        layer: Optional[str] = None,
+        min_score: float = 0.0,
+    ) -> SearchResponse:
+        endpoint = {
+            "hybrid": "search/semantic",
+            "vector": "search/semantic",
+            "bm25": "search/keyword",
+        }[mode]
+        data = await self._c.post(self._path(endpoint), json={
+            "query": query,
+            "top_k": top_k,
+            "layer": layer,
+            "min_score": min_score,
+            "mode": mode,
+        })
+        return SearchResponse.model_validate(data)
+
+    async def read(self, path: str) -> ReadResponse:
+        data = await self._c.get(self._path("read"), params={"path": path})
+        return ReadResponse.model_validate(data)
+
+    async def write(
+        self,
+        path: str,
+        content: str,
+        metadata: Optional[dict] = None,
+        agent_id: str = "default",
+    ) -> WriteResponse:
+        data = await self._c.post(self._path("write"), json={
+            "path": path,
+            "content": content,
+            "metadata": metadata,
+            "agent_id": agent_id,
+        })
+        return WriteResponse.model_validate(data)
+
+    async def list(self, folder: str = "") -> ListResponse:
+        data = await self._c.get(self._path("list"), params={"folder": folder})
+        return ListResponse.model_validate(data)
+
+    async def read_memory(self) -> ReadResponse:
+        data = await self._c.get(self._path("memory"))
+        return ReadResponse.model_validate(data)
+
+    async def write_memory(self, content: str, confidence: float = 0.9) -> WriteResponse:
+        data = await self._c.post(self._path("memory"), json={"content": content, "confidence": confidence})
+        return WriteResponse.model_validate(data)
+
+    async def read_context(self) -> ReadContextResponse:
+        data = await self._c.get(self._path("memory/context"))
+        return ReadContextResponse.model_validate(data)
+
+    async def graph_traverse(
+        self,
+        path: str,
+        depth: int = 2,
+        rel_type: Optional[str] = None,
+    ) -> GraphTraverseResponse:
+        data = await self._c.post(self._path("graph/traverse"), json={
+            "path": path,
+            "depth": depth,
+            "rel_type": rel_type,
+        })
+        return GraphTraverseResponse.model_validate(data)
+
+    async def hot_layer(self) -> str:
+        data = await self._c.get(self._path("hot-layer"))
+        return data["hot_layer"]
+
+    async def health(self) -> HealthResponse:
+        data = await self._c.get(self._path("health"))
+        return HealthResponse.model_validate(data)

cogspace-0.1.0/cogspace/_client.py

@@ -0,0 +1,96 @@
+"""Sync HTTP client for the Cogspace SDK."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, TypeVar
+
+import httpx
+
+from cogspace.exceptions import RateLimitError, TimeoutError, _raise_for_status
+
+T = TypeVar("T")
+
+DEFAULT_BASE_URL = "https://platform.cogspace.ai"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+_RETRY_STATUSES = {429, 500, 502, 503, 504}
+
+
+class SyncClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {api_key}", "User-Agent": "cogspace-python/0.1.0"},
+            timeout=timeout,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "SyncClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries):
+            try:
+                response = self._http.request(method, path, **kwargs)
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(f"Request timed out: {path}") from exc
+
+            if response.status_code not in _RETRY_STATUSES:
+                if response.status_code >= 400:
+                    try:
+                        body = response.json()
+                    except Exception:
+                        body = {}
+                    _raise_for_status(response.status_code, body)
+                return response.json() if response.content else {}
+
+            # Retryable status
+            if attempt < self._max_retries - 1:
+                wait = 2 ** attempt
+                if response.status_code == 429:
+                    retry_after = response.headers.get("Retry-After")
+                    if retry_after:
+                        wait = float(retry_after)
+                time.sleep(wait)
+                try:
+                    body = response.json()
+                except Exception:
+                    body = {}
+                last_exc = RateLimitError(
+                    body.get("detail", f"HTTP {response.status_code}"),
+                    status=response.status_code,
+                )
+            else:
+                try:
+                    body = response.json()
+                except Exception:
+                    body = {}
+                _raise_for_status(response.status_code, body)
+
+        raise last_exc or RateLimitError("Max retries exceeded")
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: dict | None = None) -> dict:
+        return self._request("POST", path, json=json)
+
+    def delete(self, path: str) -> dict:
+        return self._request("DELETE", path)

cogspace-0.1.0/cogspace/_space.py

@@ -0,0 +1,127 @@
+"""SpaceClient — sync space-scoped operations."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from cogspace._client import SyncClient
+from cogspace.types import (
+    GraphTraverseResponse,
+    HealthResponse,
+    ListResponse,
+    ReadContextResponse,
+    ReadResponse,
+    SearchResponse,
+    WriteResponse,
+)
+
+
+class SpaceClient:
+    """Sync client scoped to a single Cogspace space."""
+
+    def __init__(self, client: SyncClient, space_id: str) -> None:
+        self._c = client
+        self._space_id = space_id
+
+    def _path(self, endpoint: str) -> str:
+        return f"/spaces/{self._space_id}/{endpoint}"
+
+    # ── Search ────────────────────────────────────────────────────────────────
+
+    def search(
+        self,
+        query: str,
+        mode: Literal["hybrid", "vector", "bm25"] = "hybrid",
+        top_k: int = 5,
+        layer: Optional[str] = None,
+        min_score: float = 0.0,
+    ) -> SearchResponse:
+        """Search the knowledge space."""
+        endpoint = {
+            "hybrid": "search/semantic",
+            "vector": "search/semantic",
+            "bm25": "search/keyword",
+        }[mode]
+        data = self._c.post(self._path(endpoint), json={
+            "query": query,
+            "top_k": top_k,
+            "layer": layer,
+            "min_score": min_score,
+            "mode": mode,
+        })
+        return SearchResponse.model_validate(data)
+
+    # ── Core ──────────────────────────────────────────────────────────────────
+
+    def read(self, path: str) -> ReadResponse:
+        """Read a file by path."""
+        data = self._c.get(self._path("read"), params={"path": path})
+        return ReadResponse.model_validate(data)
+
+    def write(
+        self,
+        path: str,
+        content: str,
+        metadata: Optional[dict] = None,
+        agent_id: str = "default",
+    ) -> WriteResponse:
+        """Write (create or update) a file."""
+        data = self._c.post(self._path("write"), json={
+            "path": path,
+            "content": content,
+            "metadata": metadata,
+            "agent_id": agent_id,
+        })
+        return WriteResponse.model_validate(data)
+
+    def list(self, folder: str = "") -> ListResponse:
+        """List files in a folder."""
+        data = self._c.get(self._path("list"), params={"folder": folder})
+        return ListResponse.model_validate(data)
+
+    # ── Memory ────────────────────────────────────────────────────────────────
+
+    def read_memory(self) -> ReadResponse:
+        """Read the agent's memory.md."""
+        data = self._c.get(self._path("memory"))
+        return ReadResponse.model_validate(data)
+
+    def write_memory(self, content: str, confidence: float = 0.9) -> WriteResponse:
+        """Update the agent's memory."""
+        data = self._c.post(self._path("memory"), json={"content": content, "confidence": confidence})
+        return WriteResponse.model_validate(data)
+
+    def read_context(self) -> ReadContextResponse:
+        """Read user context files (memory/user/)."""
+        data = self._c.get(self._path("memory/context"))
+        return ReadContextResponse.model_validate(data)
+
+    # ── Graph ─────────────────────────────────────────────────────────────────
+
+    def graph_traverse(
+        self,
+        path: str,
+        depth: int = 2,
+        rel_type: Optional[str] = None,
+    ) -> GraphTraverseResponse:
+        """Traverse the knowledge graph from a file."""
+        data = self._c.post(self._path("graph/traverse"), json={
+            "path": path,
+            "depth": depth,
+            "rel_type": rel_type,
+        })
+        return GraphTraverseResponse.model_validate(data)
+
+    # ── Hot layer ─────────────────────────────────────────────────────────────
+
+    def hot_layer(self) -> str:
+        """Get the full hot layer injection string (always-injected context)."""
+        data = self._c.get(self._path("hot-layer"))
+        return data["hot_layer"]
+
+    # ── Health ────────────────────────────────────────────────────────────────
+
+    def health(self) -> HealthResponse:
+        """Get space health and storage layer stats."""
+        data = self._c.get(self._path("health"))
+        return HealthResponse.model_validate(data)

cogspace-0.1.0/cogspace/exceptions.py

@@ -0,0 +1,46 @@
+"""Cogspace SDK exception hierarchy."""
+
+from __future__ import annotations
+
+
+class CogspaceError(Exception):
+    """Base exception for all Cogspace SDK errors."""
+
+    def __init__(self, message: str, status: int | None = None, code: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class AuthError(CogspaceError):
+    """Invalid or revoked API key."""
+
+
+class NotFoundError(CogspaceError):
+    """Requested resource does not exist."""
+
+
+class RateLimitError(CogspaceError):
+    """Rate limit exceeded. The SDK will retry automatically."""
+
+
+class ServerError(CogspaceError):
+    """Unexpected server-side error (5xx)."""
+
+
+class TimeoutError(CogspaceError):
+    """Request timed out."""
+
+
+def _raise_for_status(status: int, body: dict) -> None:
+    message = body.get("detail") or body.get("message") or f"HTTP {status}"
+    code = body.get("error")
+    if status == 401:
+        raise AuthError(message, status=status, code=code)
+    if status == 404:
+        raise NotFoundError(message, status=status, code=code)
+    if status == 429:
+        raise RateLimitError(message, status=status, code=code)
+    if status >= 500:
+        raise ServerError(message, status=status, code=code)
+    raise CogspaceError(message, status=status, code=code)

cogspace-0.1.0/cogspace/types.py

@@ -0,0 +1,113 @@
+"""Response types for the Cogspace SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel
+
+
+class SearchItem(BaseModel):
+    file_path: str
+    content: str
+    score: float
+    layer: str
+    file_type: str
+    topic: str
+    confidence: float
+
+
+class SearchResponse(BaseModel):
+    results: list[SearchItem]
+    total: int
+    query: str
+    mode: str
+
+
+class ReadResponse(BaseModel):
+    path: str
+    frontmatter: dict[str, Any]
+    content: str
+    layer: str
+    size_bytes: int
+
+
+class WriteResponse(BaseModel):
+    path: str
+    status: Literal["created", "updated"]
+    reindex_queued: bool
+
+
+class FileTreeNode(BaseModel):
+    model_config = {"extra": "allow"}
+
+
+class ListResponse(BaseModel):
+    tree: dict[str, Any]
+    file_count: int
+    folder: str
+
+
+class ContextFile(BaseModel):
+    path: str
+    content: str
+    frontmatter: dict[str, Any]
+    confidence: float
+
+
+class ReadContextResponse(BaseModel):
+    files: list[ContextFile]
+    count: int
+    folder: str
+
+
+class GraphNode(BaseModel):
+    path: str
+    file_type: str
+    topic: str
+    summary: Optional[str] = None
+
+
+class GraphEdge(BaseModel):
+    from_: str
+    to: str
+    rel_type: str
+
+    class Config:
+        populate_by_name = True
+        fields = {"from_": "from"}
+
+
+class GraphTraverseResponse(BaseModel):
+    source: str
+    depth: int
+    rel_type: Optional[str] = None
+    nodes: list[GraphNode]
+    edges: list[GraphEdge]
+    graph_available: bool
+
+
+class HealthResponse(BaseModel):
+    status: str
+    space_id: str
+    vector_count: int
+    bm25_doc_count: int
+    graph_available: bool
+    graph_node_count: int = 0
+    graph_edge_count: int = 0
+    hot_layer_files: dict[str, bool] = {}
+
+
+class Space(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    created_at: str
+
+
+class ApiKey(BaseModel):
+    id: str
+    name: str
+    key_prefix: str
+    created_at: str
+    last_used: Optional[str] = None

cogspace-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cogspace"
+version = "0.1.0"
+description = "Official Cogspace SDK — add a knowledge layer to any AI agent"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Cogspace", email = "sdk@cogspace.ai" }]
+requires-python = ">=3.10"
+keywords = ["ai", "agents", "knowledge", "memory", "rag", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://cogspace.ai"
+Documentation = "https://docs.cogspace.ai"
+Repository = "https://github.com/Jack-Pision/cogspace-ai"
+Issues = "https://github.com/Jack-Pision/cogspace-ai/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["cogspace"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100

cogspace-0.1.0/tests/conftest.py

@@ -0,0 +1,54 @@
+"""Shared pytest fixtures for Cogspace SDK tests."""
+
+import pytest
+import respx
+import httpx
+
+BASE_URL = "http://test.cogspace.local"
+API_KEY = "cs-testkey1234567890abcdef1234567890abcdef12"
+
+MOCK_SPACES = [
+    {"id": "space-001", "user_id": "user-1", "name": "code-patterns", "created_at": "2026-01-01T00:00:00"}
+]
+
+MOCK_SEARCH = {
+    "results": [
+        {
+            "file_path": "expertise/retry.md",
+            "content": "Retry with exponential backoff...",
+            "score": 0.91,
+            "layer": "expertise",
+            "file_type": "knowledge",
+            "topic": "retry",
+            "confidence": 0.9,
+        }
+    ],
+    "total": 1,
+    "query": "retry logic",
+    "mode": "hybrid",
+}
+
+MOCK_READ = {
+    "path": "expertise/retry.md",
+    "frontmatter": {"type": "knowledge", "topic": "retry"},
+    "content": "# Retry patterns\n...",
+    "layer": "expertise",
+    "size_bytes": 42,
+}
+
+MOCK_WRITE = {
+    "path": "expertise/retry.md",
+    "status": "created",
+    "reindex_queued": True,
+}
+
+MOCK_HEALTH = {
+    "status": "ok",
+    "space_id": "space-001",
+    "vector_count": 10,
+    "bm25_doc_count": 5,
+    "graph_available": False,
+    "graph_node_count": 0,
+    "graph_edge_count": 0,
+    "hot_layer_files": {"cogspace_md": True, "memory_md": False},
+}

cogspace-0.1.0/tests/test_async.py

@@ -0,0 +1,65 @@
+"""Tests for the async Cogspace SDK client."""
+
+import pytest
+import respx
+import httpx
+
+from tests.conftest import BASE_URL, API_KEY, MOCK_SPACES, MOCK_SEARCH, MOCK_WRITE, MOCK_HEALTH
+from cogspace import AsyncCogspace
+from cogspace.exceptions import AuthError, NotFoundError
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_search():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.post(f"{BASE_URL}/spaces/space-001/search/semantic").mock(
+        return_value=httpx.Response(200, json=MOCK_SEARCH)
+    )
+    cog = AsyncCogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = await cog.space("code-patterns")
+    results = await space.search("retry logic")
+    assert results.total == 1
+    await cog.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_write():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.post(f"{BASE_URL}/spaces/space-001/write").mock(return_value=httpx.Response(200, json=MOCK_WRITE))
+    async with AsyncCogspace(api_key=API_KEY, base_url=BASE_URL) as cog:
+        space = await cog.space("code-patterns")
+        result = await space.write("expertise/retry.md", "# Retry\n...")
+    assert result.status == "created"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_space_not_found():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    cog = AsyncCogspace(api_key=API_KEY, base_url=BASE_URL)
+    with pytest.raises(NotFoundError):
+        await cog.space("nonexistent")
+    await cog.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_auth_error():
+    respx.get(f"{BASE_URL}/spaces").mock(
+        return_value=httpx.Response(401, json={"detail": "Invalid or revoked API key"})
+    )
+    cog = AsyncCogspace(api_key="cs-badkey", base_url=BASE_URL)
+    with pytest.raises(AuthError):
+        await cog.list_spaces()
+    await cog.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_async_context_manager():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    async with AsyncCogspace(api_key=API_KEY, base_url=BASE_URL) as cog:
+        spaces = await cog.list_spaces()
+    assert len(spaces) == 1

cogspace-0.1.0/tests/test_sync.py

@@ -0,0 +1,111 @@
+"""Tests for the sync Cogspace SDK client."""
+
+import pytest
+import respx
+import httpx
+
+from tests.conftest import BASE_URL, API_KEY, MOCK_SPACES, MOCK_SEARCH, MOCK_READ, MOCK_WRITE, MOCK_HEALTH
+from cogspace import Cogspace
+from cogspace.exceptions import AuthError, NotFoundError
+
+
+@respx.mock
+def test_space_by_name_resolves():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.post(f"{BASE_URL}/spaces/space-001/search/semantic").mock(
+        return_value=httpx.Response(200, json=MOCK_SEARCH)
+    )
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = cog.space("code-patterns")
+    results = space.search("retry logic")
+    assert results.total == 1
+    assert results.results[0].file_path == "expertise/retry.md"
+
+
+@respx.mock
+def test_space_by_id_resolves():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = cog.space("space-001")
+    assert space._space_id == "space-001"
+
+
+@respx.mock
+def test_space_name_cached():
+    route = respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    cog.space("code-patterns")
+    cog.space("code-patterns")
+    assert route.call_count == 1  # only resolved once
+
+
+@respx.mock
+def test_space_not_found():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    with pytest.raises(NotFoundError):
+        cog.space("nonexistent-space")
+
+
+@respx.mock
+def test_search():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.post(f"{BASE_URL}/spaces/space-001/search/semantic").mock(
+        return_value=httpx.Response(200, json=MOCK_SEARCH)
+    )
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = cog.space("code-patterns")
+    results = space.search("retry logic")
+    assert len(results.results) == 1
+    assert results.results[0].score == 0.91
+
+
+@respx.mock
+def test_read():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.get(f"{BASE_URL}/spaces/space-001/read").mock(return_value=httpx.Response(200, json=MOCK_READ))
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = cog.space("code-patterns")
+    result = space.read("expertise/retry.md")
+    assert result.path == "expertise/retry.md"
+    assert result.layer == "expertise"
+
+
+@respx.mock
+def test_write():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.post(f"{BASE_URL}/spaces/space-001/write").mock(return_value=httpx.Response(200, json=MOCK_WRITE))
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = cog.space("code-patterns")
+    result = space.write("expertise/retry.md", "# Retry patterns\n...")
+    assert result.status == "created"
+    assert result.reindex_queued is True
+
+
+@respx.mock
+def test_health():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    respx.get(f"{BASE_URL}/spaces/space-001/health").mock(return_value=httpx.Response(200, json=MOCK_HEALTH))
+    cog = Cogspace(api_key=API_KEY, base_url=BASE_URL)
+    space = cog.space("code-patterns")
+    h = space.health()
+    assert h.status == "ok"
+    assert h.vector_count == 10
+
+
+@respx.mock
+def test_auth_error():
+    respx.get(f"{BASE_URL}/spaces").mock(
+        return_value=httpx.Response(401, json={"detail": "Invalid or revoked API key"})
+    )
+    cog = Cogspace(api_key="cs-badkey", base_url=BASE_URL)
+    with pytest.raises(AuthError):
+        cog.list_spaces()
+
+
+@respx.mock
+def test_context_manager():
+    respx.get(f"{BASE_URL}/spaces").mock(return_value=httpx.Response(200, json=MOCK_SPACES))
+    with Cogspace(api_key=API_KEY, base_url=BASE_URL) as cog:
+        spaces = cog.list_spaces()
+    assert len(spaces) == 1