cogspace 0.1.0__py3-none-any.whl

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/_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/_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/_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/_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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+cogspace/__init__.py,sha256=CebMSK2BU5iCT2wYDFXmjrgWPgcXxvwMnftjJONFcD4,5843
+cogspace/_async_client.py,sha256=g01gz6hV74OUdFYR6saKjbubojq6sry3VTQnAc-SRGs,3217
+cogspace/_async_space.py,sha256=ERhvMlKvO5Rzl3JqebdqDkmj9jJJ4RrBBgYtZpPbKEI,3380
+cogspace/_client.py,sha256=c99BFCE8ZxZPvG-0wwg6vPG4S31p6A7-6Y_yqYzsOGQ,3172
+cogspace/_space.py,sha256=NOgWW53aOL25lOH2sUEX_0SW23hcXOa9ce8RX1g4X_o,5016
+cogspace/exceptions.py,sha256=wv03Dn6WouEhViucQnW3YRQIqRDrnWZu-69I1F16_8k,1315
+cogspace/types.py,sha256=l9J612EqUoXe_PA35h913w1-8bKMgy-DeeLbk9HngC4,1968
+cogspace-0.1.0.dist-info/METADATA,sha256=97wFXYhup6cPSbMhGfxOIKBseoZFjJA7qLbe9TpiX24,3679
+cogspace-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cogspace-0.1.0.dist-info/RECORD,,

cogspace-0.1.0.dist-info/WHEEL

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