contextstore-sdk 0.1.0__tar.gz

contextstore_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: contextstore-sdk
+Version: 0.1.0
+Summary: Client SDK for the ContextStore company brain — compiled memory and agent team, accessed via a typed Python API.
+Author: ContextStore
+License: MIT
+Project-URL: Homepage, https://contextstore.oritm.tech
+Keywords: memory,mcp,second-brain,agents,knowledge-base
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ContextStore Python SDK
+
+Talk to your ContextStore **company brain** — compiled memory + agent team — from
+Python. The SDK is a typed client over your backend's MCP JSON-RPC layer.
+
+## Install
+
+```bash
+pip install contextstore-sdk
+```
+
+## Quickstart
+
+```python
+import os
+from contextstore import ContextStore
+
+client = ContextStore(api_key=os.environ["CONTEXTSTORE_KEY"])
+
+# Remember something
+client.memory.add(
+    content="Board approved usage-based pricing on Sep 12",
+    metadata={"project": "pricing", "owner": "maya"},
+)
+
+# Ask the company brain — with sources
+res = client.memory.query("What did we decide about pricing?")
+print(res.answer)
+print(res.sources)
+```
+
+## Local / self-hosted
+
+Point at your own backend (default is the hosted one):
+
+```python
+client = ContextStore(
+    api_key=os.environ["CONTEXTSTORE_KEY"],
+    base_url="https://contextstore.onrender.com",
+)
+```
+
+For local development you can pass a JWT instead of an api_key:
+
+```python
+client = ContextStore(token="<jwt>")
+```
+
+## Namespaces / methods
+
+| Python | Backend MCP tool |
+|---|---|
+| `client.memory.add(...)` | `memory_store` |
+| `client.memory.query(...)` | `memory_recall` |
+| `client.memory.log_turn(...)` | `log_conversation_turn` |
+| `client.context.snapshot()` | `get_context_snapshot` |
+| `client.context.checkin(...)` | `smart_checkin` |
+| `client.company.learn(...)` | `company_learn` |
+| `client.company.map()` / `.set_map(...)` | `company_map` |
+| `client.company.review(run=True)` | `company_review` |
+| `client.company.approve(...)` / `.reject(...)` | `review_propagation` |
+| `client.company.pending(...)` | `list_propagation_queue` |
+| `client.permissions.grant/revoke/list(...)` | permission admin tools |
+| `client.permissions.check_authority(...)` | `check_action_authority` |
+
+## Errors
+
+- `AuthenticationError` — bad/expired/scoped-out API key
+- `ApiError` — the MCP tool returned an error
+- `ContextStoreError` — network / transport issues
+
+No external dependencies — uses only the Python standard library.

contextstore_sdk-0.1.0/README.md

@@ -0,0 +1,72 @@
+# ContextStore Python SDK
+
+Talk to your ContextStore **company brain** — compiled memory + agent team — from
+Python. The SDK is a typed client over your backend's MCP JSON-RPC layer.
+
+## Install
+
+```bash
+pip install contextstore-sdk
+```
+
+## Quickstart
+
+```python
+import os
+from contextstore import ContextStore
+
+client = ContextStore(api_key=os.environ["CONTEXTSTORE_KEY"])
+
+# Remember something
+client.memory.add(
+    content="Board approved usage-based pricing on Sep 12",
+    metadata={"project": "pricing", "owner": "maya"},
+)
+
+# Ask the company brain — with sources
+res = client.memory.query("What did we decide about pricing?")
+print(res.answer)
+print(res.sources)
+```
+
+## Local / self-hosted
+
+Point at your own backend (default is the hosted one):
+
+```python
+client = ContextStore(
+    api_key=os.environ["CONTEXTSTORE_KEY"],
+    base_url="https://contextstore.onrender.com",
+)
+```
+
+For local development you can pass a JWT instead of an api_key:
+
+```python
+client = ContextStore(token="<jwt>")
+```
+
+## Namespaces / methods
+
+| Python | Backend MCP tool |
+|---|---|
+| `client.memory.add(...)` | `memory_store` |
+| `client.memory.query(...)` | `memory_recall` |
+| `client.memory.log_turn(...)` | `log_conversation_turn` |
+| `client.context.snapshot()` | `get_context_snapshot` |
+| `client.context.checkin(...)` | `smart_checkin` |
+| `client.company.learn(...)` | `company_learn` |
+| `client.company.map()` / `.set_map(...)` | `company_map` |
+| `client.company.review(run=True)` | `company_review` |
+| `client.company.approve(...)` / `.reject(...)` | `review_propagation` |
+| `client.company.pending(...)` | `list_propagation_queue` |
+| `client.permissions.grant/revoke/list(...)` | permission admin tools |
+| `client.permissions.check_authority(...)` | `check_action_authority` |
+
+## Errors
+
+- `AuthenticationError` — bad/expired/scoped-out API key
+- `ApiError` — the MCP tool returned an error
+- `ContextStoreError` — network / transport issues
+
+No external dependencies — uses only the Python standard library.

contextstore_sdk-0.1.0/contextstore/__init__.py

@@ -0,0 +1,26 @@
+"""ContextStore — Python SDK for the ContextStore company brain.
+
+Talk to your compiled memory and agent team over a clean, typed API.
+See the ContextStore class for usage.
+"""
+
+from .client import ContextStore
+from ._transport import (
+    ApiError,
+    AuthenticationError,
+    ContextStoreError,
+)
+from ._models import ActionResult, QueryResult, SnapshotResult, Source
+
+__all__ = [
+    "ContextStore",
+    "ActionResult",
+    "QueryResult",
+    "SnapshotResult",
+    "Source",
+    "ContextStoreError",
+    "AuthenticationError",
+    "ApiError",
+]
+
+__version__ = "0.1.0"

contextstore_sdk-0.1.0/contextstore/_models.py

@@ -0,0 +1,117 @@
+"""ContextStore SDK — typed result models for MCP tool responses."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+def _load_text(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract the JSON payload the server returns inside content[].text."""
+    for block in result.get("content", []):
+        if isinstance(block, dict) and block.get("type") == "text":
+            text = str(block.get("text", ""))
+            try:
+                parsed = json.loads(text)
+                if isinstance(parsed, dict):
+                    return parsed
+            except (ValueError, TypeError):
+                return {"text": text}
+    return {}
+
+
+@dataclass
+class Source:
+    """A single source returned by the memory recall."""
+
+    text: str
+    source: Optional[str] = None
+    memory_type: Optional[str] = None
+    confidence: Optional[float] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class QueryResult:
+    """Typed result of `client.memory.query(...)`."""
+
+    answer: str = ""
+    sources: List[Source] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_result(cls, result: Dict[str, Any]) -> "QueryResult":
+        data = _load_text(result)
+        answer = data.get("answer") or data.get("summary") or _raw_text(result)
+        if isinstance(answer, list):
+            answer = "\n".join(str(a) for a in answer)
+        sources_raw = data.get("sources") or data.get("results") or []
+        sources: List[Source] = []
+        if isinstance(sources_raw, list):
+            for s in sources_raw:
+                if isinstance(s, dict):
+                    sources.append(
+                        Source(
+                            text=str(s.get("content") or s.get("text") or s.get("summary") or s),
+                            source=s.get("source") or s.get("memory_type") or None,
+                            memory_type=s.get("memory_type") or s.get("type") or None,
+                            confidence=s.get("confidence") or s.get("score") or None,
+                            extra=s,
+                        )
+                    )
+                else:
+                    sources.append(Source(text=str(s)))
+        elif isinstance(sources_raw, dict):
+            for key, val in sources_raw.items():
+                sources.append(
+                    Source(
+                        text=str(val.get("content") or val if isinstance(val, dict) else val),
+                        source=key,
+                        extra=val if isinstance(val, dict) else {},
+                    )
+                )
+        return cls(answer=str(answer), sources=sources, raw=data)
+
+
+@dataclass
+class ActionResult:
+    """Generic result of a tool that returns a JSON-ish payload."""
+
+    data: Dict[str, Any] = field(default_factory=dict)
+    text: str = ""
+
+    @classmethod
+    def from_result(cls, result: Dict[str, Any]) -> "ActionResult":
+        return cls(data=_load_text(result), text=_raw_text(result))
+
+
+def _raw_text(result: Dict[str, Any]) -> str:
+    parts = []
+    for block in result.get("content", []):
+        if isinstance(block, dict) and block.get("type") == "text":
+            parts.append(str(block.get("text", "")))
+    return "\n".join(p for p in parts if p)
+
+
+@dataclass
+class SnapshotResult:
+    """Typed result of `client.snapshot()`."""
+
+    data: Dict[str, Any] = field(default_factory=dict)
+    matched_playbooks: List[str] = field(default_factory=list)
+    has_profile: bool = False
+    text: str = ""
+
+    @classmethod
+    def from_result(cls, result: Dict[str, Any]) -> "SnapshotResult":
+        data = _load_text(result)
+        playbooks = data.get("matched_playbooks") or []
+        if isinstance(playbooks, str):
+            playbooks = [playbooks]
+        return cls(
+            data=data,
+            matched_playbooks=list(playbooks),
+            has_profile=bool(data.get("has_profile") or data.get("user_profile")),
+            text=_raw_text(result),
+        )

contextstore_sdk-0.1.0/contextstore/_transport.py

@@ -0,0 +1,150 @@
+"""ContextStore SDK — MCP JSON-RPC transport over Streamable HTTP."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Optional
+
+DEFAULT_BASE_URL = "https://contextstore.onrender.com"
+DEFAULT_MCP_PATH = "/mcp"
+DEFAULT_TIMEOUT = 60.0
+
+
+class ContextStoreError(Exception):
+    """Base error for ContextStore SDK."""
+
+
+class AuthenticationError(ContextStoreError):
+    """Raised when the API key / token is invalid, expired, or lacks scope."""
+
+
+class ApiError(ContextStoreError):
+    """Raised when the MCP call returns an error or an isError result."""
+
+
+class Transport:
+    """Minimal MCP Streamable HTTP (JSON-RPC) client with no external deps."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not api_key and not token:
+            raise ValueError("Either api_key or token (JWT) must be provided")
+        self._api_key = api_key
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._headers_cache: Optional[Dict[str, str]] = None
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+        }
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+        elif self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        return headers
+
+    def call_tool(self, name: str, arguments: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Send a JSON-RPC tools/call and return the result payload (dict)."""
+        request_id = int(time.time() * 1000) % (2 ** 31)
+        payload = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": "tools/call",
+            "params": {"name": name, "arguments": arguments or {}},
+        }
+        url = f"{self._base_url}{DEFAULT_MCP_PATH}"
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=self._headers(), method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            body = ""
+            try:
+                body = e.read().decode("utf-8")
+            except Exception:
+                pass
+            if e.code in (401, 403):
+                raise AuthenticationError(
+                    f"Authentication failed ({e.code}): {body or e.reason}"
+                )
+            raise ApiError(f"HTTP {e.code}: {body or e.reason}")
+        except urllib.error.URLError as e:
+            raise ContextStoreError(f"Network error: {e.reason}")
+
+        # The response may be either a single JSON object or an SSE stream.
+        obj = self._parse_response(raw)
+        if "error" in obj:
+            err = obj["error"]
+            raise ApiError(str(err.get("message", err)))
+        result = obj.get("result", {})
+        if result.get("isError"):
+            text = self._text_of(result)
+            raise ApiError(text or "MCP tool returned an error")
+        return result
+
+    def list_tools(self) -> list:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": int(time.time() * 1000) % (2 ** 31),
+            "method": "tools/list",
+            "params": {},
+        }
+        url = f"{self._base_url}{DEFAULT_MCP_PATH}"
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers=self._headers(),
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as e:
+            if e.code in (401, 403):
+                raise AuthenticationError(f"Authentication failed ({e.code})")
+            raise ApiError(f"HTTP {e.code}")
+        except urllib.error.URLError as e:
+            raise ContextStoreError(f"Network error: {e.reason}")
+        obj = self._parse_response(raw)
+        if "error" in obj:
+            raise ApiError(str(obj["error"]))
+        return obj.get("result", {}).get("tools", [])
+
+    @staticmethod
+    def _parse_response(raw: str) -> Dict[str, Any]:
+        raw = raw.strip()
+        if not raw:
+            raise ApiError("Empty response from server")
+        if raw.startswith("event:"):
+            # SSE stream: take the last data: line.
+            for line in raw.splitlines():
+                line = line.strip()
+                if line.startswith("data:") and line[5:].strip():
+                    raw = line[5:].strip()
+        if not raw.startswith("{"):
+            raise ApiError(f"Unexpected response format: {raw[:200]}")
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise ApiError(f"Invalid JSON response: {e}")
+
+    @staticmethod
+    def _text_of(result: Dict[str, Any]) -> str:
+        texts = []
+        for block in result.get("content", []):
+            if isinstance(block, dict) and block.get("type") == "text":
+                texts.append(str(block.get("text", "")))
+        return "\n".join(t for t in texts if t)

contextstore_sdk-0.1.0/contextstore/client.py

@@ -0,0 +1,54 @@
+"""ContextStore SDK — the public client.
+
+Usage:
+    import os
+    from contextstore import ContextStore
+
+    client = ContextStore(api_key=os.environ["CONTEXTSTORE_KEY"])
+
+    client.memory.add("Board approved usage-based pricing on Sep 12",
+                      metadata={"project": "pricing", "owner": "maya"})
+    res = client.memory.query("What did we decide about pricing?")
+    print(res.answer, res.sources)
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ._transport import Transport
+from .company import CompanyBrainNamespace
+from .context import ContextNamespace
+from .memory import MemoryNamespace
+from .permissions import PermissionsNamespace
+
+__all__ = ["ContextStore"]
+
+
+class ContextStore:
+    """Root client. Points at the ContextStore backend and exposes namespaced,
+    typed access to the MCP tool catalog over JSON-RPC."""
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        base_url: str = "https://contextstore.onrender.com",
+        timeout: float = 60.0,
+    ) -> None:
+        transport = Transport(
+            api_key=api_key,
+            token=token,
+            base_url=base_url,
+            timeout=timeout,
+        )
+        self._transport = transport
+        self.memory = MemoryNamespace(transport)
+        self.company = CompanyBrainNamespace(transport)
+        self.context = ContextNamespace(transport)
+        self.permissions = PermissionsNamespace(transport)
+
+    def ping(self) -> bool:
+        """Quick connectivity/auth check: list the available MCP tools."""
+        return self._transport.list_tools() is not None

contextstore_sdk-0.1.0/contextstore/company.py

@@ -0,0 +1,75 @@
+"""ContextStore SDK — Company Brain namespace (learn, map, review, approve)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ._models import ActionResult
+from ._transport import Transport
+
+
+class CompanyBrainNamespace:
+    """Access to the Company Brain: corrections, the live map, and the review
+    ritual that gates what propagates company-wide."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def learn(
+        self,
+        correction: str,
+        *,
+        correction_type: str = "fact",
+        reviewer: Optional[str] = None,
+        reason: Optional[str] = None,
+        playbook_name: Optional[str] = None,
+        when_to_use: Optional[str] = None,
+    ) -> ActionResult:
+        """Record a correction/lesson. It is stored as pending_review and must pass
+        human sign-off (via review()) before it spreads company-wide."""
+        arguments: Dict[str, Any] = {"correction": correction, "correction_type": correction_type}
+        if reviewer:
+            arguments["reviewer"] = reviewer
+        if reason:
+            arguments["reason"] = reason
+        if playbook_name:
+            arguments["playbook_name"] = playbook_name
+        if when_to_use:
+            arguments["when_to_use"] = when_to_use
+        result = self._transport.call_tool("company_learn", arguments)
+        return ActionResult.from_result(result)
+
+    def map(self, *, playbooks: bool = True) -> ActionResult:
+        """Read the current company map (front door: priorities, source order, nav)."""
+        result = self._transport.call_tool("company_map", {"playbooks": playbooks})
+        return ActionResult.from_result(result)
+
+    def set_map(self, map_text: str) -> ActionResult:
+        """Upsert a new company map. Map is stored as a tagged, recallable memory."""
+        result = self._transport.call_tool("company_map", {"set_map": True, "map_text": map_text})
+        return ActionResult.from_result(result)
+
+    def review(self, run: bool = True) -> ActionResult:
+        """List pending learnings awaiting human sign-off. run=True lists them."""
+        result = self._transport.call_tool("company_review", {"run": run})
+        return ActionResult.from_result(result)
+
+    def approve(self, queue_id: str) -> ActionResult:
+        """Approve a pending propagation request so it spreads company-wide."""
+        result = self._transport.call_tool("review_propagation", {"queue_id": queue_id, "action": "approve"})
+        return ActionResult.from_result(result)
+
+    def reject(self, queue_id: str) -> ActionResult:
+        """Reject a pending propagation request (stays restricted)."""
+        result = self._transport.call_tool("review_propagation", {"queue_id": queue_id, "action": "reject"})
+        return ActionResult.from_result(result)
+
+    def pending(self, org_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        """List the raw pending propagation queue entries."""
+        arguments: Dict[str, Any] = {}
+        if org_id:
+            arguments["org_id"] = org_id
+        result = self._transport.call_tool("list_propagation_queue", arguments)
+        data = ActionResult.from_result(result).data
+        items = data.get("pending_requests") or []
+        return items if isinstance(items, list) else []

contextstore_sdk-0.1.0/contextstore/context.py

@@ -0,0 +1,28 @@
+"""ContextStore SDK — context namespace (snapshot, checkin)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._models import ActionResult, SnapshotResult
+from ._transport import Transport
+
+
+class ContextNamespace:
+    """Startup + session context (get_context_snapshot / smart_checkin)."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def snapshot(self) -> SnapshotResult:
+        """Load user profile, project conventions, and recent history. Call first."""
+        result = self._transport.call_tool("get_context_snapshot", {})
+        return SnapshotResult.from_result(result)
+
+    def checkin(self, user_intent: Optional[str] = None) -> ActionResult:
+        """Optional richer startup loader: active_thread, asks, suggestions."""
+        arguments: Dict[str, Any] = {}
+        if user_intent:
+            arguments["user_intent"] = user_intent
+        result = self._transport.call_tool("smart_checkin", arguments)
+        return ActionResult.from_result(result)

contextstore_sdk-0.1.0/contextstore/memory.py

@@ -0,0 +1,86 @@
+"""ContextStore SDK — memory namespace (store, recall, log, list)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ._models import ActionResult, QueryResult
+from ._transport import Transport
+
+
+class MemoryNamespace:
+    """Typesafe access to the brain's memory layer (memory_store / memory_recall)."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def add(
+        self,
+        content: str,
+        *,
+        memory_type: str = "general",
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        project: Optional[str] = None,
+        source: Optional[str] = "sdk",
+        team_id: Optional[str] = None,
+        confidence_score: Optional[float] = None,
+    ) -> ActionResult:
+        """Remember a durable fact. Maps to the server's memory_store tool.
+
+        `metadata` is a convenience map merged into `tags`/`source`; keys other
+        than the tool's known params are passed through as tags so nothing is lost.
+        """
+        arguments: Dict[str, Any] = {
+            "content": content,
+            "memory_type": memory_type,
+            "tags": tags or [],
+            "source": source or "sdk",
+        }
+        if project:
+            arguments["project"] = project
+        if team_id:
+            arguments["team_id"] = team_id
+        if confidence_score is not None:
+            arguments["confidence_score"] = confidence_score
+        if metadata:
+            for key, value in metadata.items():
+                if key in arguments:
+                    arguments[key] = value
+                elif isinstance(value, str):
+                    arguments.setdefault("tags", []).append(f"{key}:{value}")
+        result = self._transport.call_tool("memory_store", arguments)
+        return ActionResult.from_result(result)
+
+    def query(
+        self,
+        query: str,
+        *,
+        top_k: int = 5,
+        memory_type: Optional[str] = None,
+        project: Optional[str] = None,
+        user_intent: Optional[str] = None,
+        include_scratchpad: bool = False,
+    ) -> QueryResult:
+        """Ask the company brain a question; returns `answer` + `sources`."""
+        arguments: Dict[str, Any] = {"query": query, "top_k": top_k}
+        if memory_type:
+            arguments["memory_type"] = memory_type
+        if project:
+            arguments["project"] = project
+        if user_intent:
+            arguments["user_intent"] = user_intent
+        if include_scratchpad:
+            arguments["include_scratchpad"] = True
+        result = self._transport.call_tool("memory_recall", arguments)
+        return QueryResult.from_result(result)
+
+    def log_turn(self, role: str, content: str, *, thread_id: Optional[str] = None, thread_label: Optional[str] = None) -> ActionResult:
+        """Log a conversation turn (role='user' or 'assistant')."""
+        arguments: Dict[str, Any] = {"role": role, "content": content}
+        if thread_id:
+            arguments["thread_id"] = thread_id
+        if thread_label:
+            arguments["thread_label"] = thread_label
+        result = self._transport.call_tool("log_conversation_turn", arguments)
+        return ActionResult.from_result(result)

contextstore_sdk-0.1.0/contextstore/permissions.py

@@ -0,0 +1,47 @@
+"""ContextStore SDK — permissions & action-authority namespace (admin tools)."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._models import ActionResult
+from ._transport import Transport
+
+
+class PermissionsNamespace:
+    """Admin controls: grant/revoke tool permissions and check action authority.
+    These require an API key with the 'admin' scope."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def grant(self, *, agent_id: str, tool_name: str, allowed: bool = True) -> ActionResult:
+        result = self._transport.call_tool(
+            "grant_permission",
+            {"agent_id": agent_id, "tool_name": tool_name, "allowed": allowed},
+        )
+        return ActionResult.from_result(result)
+
+    def revoke(self, *, agent_id: str, tool_name: str) -> ActionResult:
+        result = self._transport.call_tool(
+            "revoke_permission",
+            {"agent_id": agent_id, "tool_name": tool_name},
+        )
+        return ActionResult.from_result(result)
+
+    def list(self, agent_id: Optional[str] = None) -> ActionResult:
+        arguments: Dict[str, Any] = {}
+        if agent_id:
+            arguments["agent_id"] = agent_id
+        result = self._transport.call_tool("list_permissions", arguments)
+        return ActionResult.from_result(result)
+
+    def check_authority(self, memory_id: str, requested_action: str) -> ActionResult:
+        """Verify whether a memory's stored action_authority allows an action
+        (e.g. 'act:auto_email', 'act:deploy', 'act:refund'). Queues for human
+        sign-off if unauthorized."""
+        result = self._transport.call_tool(
+            "check_action_authority",
+            {"memory_id": memory_id, "requested_action": requested_action},
+        )
+        return ActionResult.from_result(result)

contextstore_sdk-0.1.0/contextstore/py.typed

@@ -0,0 +1,2 @@
+# Marker file for PEP 561: this package ships inline type hints.
+

contextstore_sdk-0.1.0/contextstore_sdk.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: contextstore-sdk
+Version: 0.1.0
+Summary: Client SDK for the ContextStore company brain — compiled memory and agent team, accessed via a typed Python API.
+Author: ContextStore
+License: MIT
+Project-URL: Homepage, https://contextstore.oritm.tech
+Keywords: memory,mcp,second-brain,agents,knowledge-base
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ContextStore Python SDK
+
+Talk to your ContextStore **company brain** — compiled memory + agent team — from
+Python. The SDK is a typed client over your backend's MCP JSON-RPC layer.
+
+## Install
+
+```bash
+pip install contextstore-sdk
+```
+
+## Quickstart
+
+```python
+import os
+from contextstore import ContextStore
+
+client = ContextStore(api_key=os.environ["CONTEXTSTORE_KEY"])
+
+# Remember something
+client.memory.add(
+    content="Board approved usage-based pricing on Sep 12",
+    metadata={"project": "pricing", "owner": "maya"},
+)
+
+# Ask the company brain — with sources
+res = client.memory.query("What did we decide about pricing?")
+print(res.answer)
+print(res.sources)
+```
+
+## Local / self-hosted
+
+Point at your own backend (default is the hosted one):
+
+```python
+client = ContextStore(
+    api_key=os.environ["CONTEXTSTORE_KEY"],
+    base_url="https://contextstore.onrender.com",
+)
+```
+
+For local development you can pass a JWT instead of an api_key:
+
+```python
+client = ContextStore(token="<jwt>")
+```
+
+## Namespaces / methods
+
+| Python | Backend MCP tool |
+|---|---|
+| `client.memory.add(...)` | `memory_store` |
+| `client.memory.query(...)` | `memory_recall` |
+| `client.memory.log_turn(...)` | `log_conversation_turn` |
+| `client.context.snapshot()` | `get_context_snapshot` |
+| `client.context.checkin(...)` | `smart_checkin` |
+| `client.company.learn(...)` | `company_learn` |
+| `client.company.map()` / `.set_map(...)` | `company_map` |
+| `client.company.review(run=True)` | `company_review` |
+| `client.company.approve(...)` / `.reject(...)` | `review_propagation` |
+| `client.company.pending(...)` | `list_propagation_queue` |
+| `client.permissions.grant/revoke/list(...)` | permission admin tools |
+| `client.permissions.check_authority(...)` | `check_action_authority` |
+
+## Errors
+
+- `AuthenticationError` — bad/expired/scoped-out API key
+- `ApiError` — the MCP tool returned an error
+- `ContextStoreError` — network / transport issues
+
+No external dependencies — uses only the Python standard library.

contextstore_sdk-0.1.0/contextstore_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+contextstore/__init__.py
+contextstore/_models.py
+contextstore/_transport.py
+contextstore/client.py
+contextstore/company.py
+contextstore/context.py
+contextstore/memory.py
+contextstore/permissions.py
+contextstore/py.typed
+contextstore_sdk.egg-info/PKG-INFO
+contextstore_sdk.egg-info/SOURCES.txt
+contextstore_sdk.egg-info/dependency_links.txt
+contextstore_sdk.egg-info/top_level.txt

contextstore_sdk-0.1.0/contextstore_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

contextstore_sdk-0.1.0/contextstore_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+contextstore

contextstore_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contextstore-sdk"
+version = "0.1.0"
+description = "Client SDK for the ContextStore company brain — compiled memory and agent team, accessed via a typed Python API."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "ContextStore" }]
+keywords = ["memory", "mcp", "second-brain", "agents", "knowledge-base"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://contextstore.oritm.tech"
+
+[tool.setuptools]
+packages = ["contextstore"]
+
+[tool.setuptools.package-data]
+contextstore = ["py.typed"]

contextstore_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+