stablebaseline 0.1.0__py3-none-any.whl

stablebaseline/__init__.py

@@ -0,0 +1,25 @@
+"""Stable Baseline — Python SDK for the REST API.
+
+    from stablebaseline import StableBaseline
+
+    sb = StableBaseline(api_key="sta_xxx")
+    orgs = sb.tools.listOrganisations()
+    doc = sb.tools.createDocument(folder_id="...", title="X", cdmd="# Hi")
+
+The same surface is available asynchronously via :class:`AsyncStableBaseline`.
+163 MCP tools across 16 categories — see https://stablebaseline.io/docs/mcp/tools.
+"""
+
+from .client import (
+    AsyncStableBaseline,
+    StableBaseline,
+    StableBaselineToolError,
+)
+
+__all__ = [
+    "StableBaseline",
+    "AsyncStableBaseline",
+    "StableBaselineToolError",
+]
+
+__version__ = "0.1.0"

stablebaseline/client.py

@@ -0,0 +1,225 @@
+"""HTTP client for the Stable Baseline REST API.
+
+Sync and async variants share the same dispatch logic via a small base
+class. All 163 MCP tools are reachable as ``client.tools.<tool_name>(...)``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Iterator, Mapping
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.stablebaseline.io/functions/v1/cloud-serve/api/v1"
+
+
+class StableBaselineToolError(Exception):
+    """Raised when the server returns a non-2xx response."""
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        details: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(f"[{status} {code}] {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+
+def _auth_header(api_key: str | None, access_token: str | None) -> dict[str, str]:
+    token = access_token or api_key
+    if not token:
+        return {}
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _resolve_credential(
+    api_key: str | None, access_token: str | None
+) -> tuple[str | None, str | None]:
+    api_key = api_key or os.environ.get("SB_API_KEY")
+    access_token = access_token or os.environ.get("SB_ACCESS_TOKEN")
+    if not api_key and not access_token:
+        raise ValueError(
+            "No credential provided. Pass `api_key=` or `access_token=`, "
+            "or set the SB_API_KEY / SB_ACCESS_TOKEN env vars."
+        )
+    return api_key, access_token
+
+
+def _raise_for_error(response: httpx.Response) -> None:
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+    envelope = (body or {}).get("error") or {}
+    raise StableBaselineToolError(
+        status=response.status_code,
+        code=envelope.get("code") or f"http_{response.status_code}",
+        message=envelope.get("message") or response.reason_phrase,
+        details=envelope.get("details"),
+    )
+
+
+# ── Sync client ──────────────────────────────────────────────────────
+
+
+class _SyncToolDispatcher:
+    """Dynamic attribute-based tool dispatch — ``client.tools.<name>(input)``."""
+
+    def __init__(self, client: "StableBaseline") -> None:
+        self._client = client
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return lambda **kwargs: self._client.call_tool(name, kwargs)
+
+    def __call__(self, name: str, input: Mapping[str, Any] | None = None) -> Any:
+        """Escape hatch: ``client.tools("listOrganisations", {})``."""
+        return self._client.call_tool(name, dict(input or {}))
+
+
+class StableBaseline:
+    """Synchronous client. Use as a context manager for connection reuse:
+
+        with StableBaseline(api_key="sta_xxx") as sb:
+            orgs = sb.tools.listOrganisations()
+
+    Or instantiate directly; ``httpx.Client`` is created lazily and closed
+    when ``close()`` is called.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = 30.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        api_key, access_token = _resolve_credential(api_key, access_token)
+        self._base_url = base_url.rstrip("/")
+        self._headers = _auth_header(api_key, access_token)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+        self.tools = _SyncToolDispatcher(self)
+
+    # — Public surface —
+
+    def call_tool(self, name: str, params: Mapping[str, Any] | None = None) -> Any:
+        url = f"{self._base_url}/tools/{name}"
+        res = self._http.post(
+            url,
+            headers={"Content-Type": "application/json", **self._headers},
+            json=dict(params or {}),
+        )
+        if not res.is_success:
+            _raise_for_error(res)
+        return res.json()
+
+    def list_tools(self) -> dict[str, Any]:
+        res = self._http.get(f"{self._base_url}/tools")
+        res.raise_for_status()
+        return res.json()
+
+    def openapi(self) -> dict[str, Any]:
+        res = self._http.get(f"{self._base_url}/openapi.json")
+        res.raise_for_status()
+        return res.json()
+
+    # — Resource management —
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "StableBaseline":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __iter__(self) -> Iterator[Any]:
+        # Prevent surprise iteration (httpx.Client supports it).
+        raise TypeError("StableBaseline is not iterable; use sb.tools.<name>(...).")
+
+
+# ── Async client ─────────────────────────────────────────────────────
+
+
+class _AsyncToolDispatcher:
+    def __init__(self, client: "AsyncStableBaseline") -> None:
+        self._client = client
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        async def _call(**kwargs: Any) -> Any:
+            return await self._client.call_tool(name, kwargs)
+
+        return _call
+
+    def __call__(self, name: str, input: Mapping[str, Any] | None = None) -> Any:
+        return self._client.call_tool(name, dict(input or {}))
+
+
+class AsyncStableBaseline:
+    """Asynchronous client.
+
+        async with AsyncStableBaseline(api_key="sta_xxx") as sb:
+            orgs = await sb.tools.listOrganisations()
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        access_token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        api_key, access_token = _resolve_credential(api_key, access_token)
+        self._base_url = base_url.rstrip("/")
+        self._headers = _auth_header(api_key, access_token)
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._owns_http = http_client is None
+        self.tools = _AsyncToolDispatcher(self)
+
+    async def call_tool(self, name: str, params: Mapping[str, Any] | None = None) -> Any:
+        url = f"{self._base_url}/tools/{name}"
+        res = await self._http.post(
+            url,
+            headers={"Content-Type": "application/json", **self._headers},
+            json=dict(params or {}),
+        )
+        if not res.is_success:
+            _raise_for_error(res)
+        return res.json()
+
+    async def list_tools(self) -> dict[str, Any]:
+        res = await self._http.get(f"{self._base_url}/tools")
+        res.raise_for_status()
+        return res.json()
+
+    async def openapi(self) -> dict[str, Any]:
+        res = await self._http.get(f"{self._base_url}/openapi.json")
+        res.raise_for_status()
+        return res.json()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncStableBaseline":
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()

stablebaseline-0.1.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: stablebaseline
+Version: 0.1.0
+Summary: Python SDK for the Stable Baseline REST API. End-to-end agent-managed company brain — docs, diagrams, plans, and a self-learning Knowledge Graph. 163 tools across 16 categories.
+Project-URL: Homepage, https://stablebaseline.io
+Project-URL: Documentation, https://stablebaseline.io/docs/mcp
+Project-URL: Repository, https://github.com/stablebaseline/mcp
+Project-URL: Issues, https://github.com/stablebaseline/mcp/issues
+Author-email: Stable Baseline <hello@stablebaseline.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,company-brain,diagrams,documentation,knowledge-graph,mcp,model-context-protocol,plans,rest-api,sdk,stable-baseline,stablebaseline
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: typing-extensions>=4.10.0; python_version < '3.12'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stablebaseline
+
+[![PyPI](https://img.shields.io/pypi/v/stablebaseline?color=orange)](https://pypi.org/project/stablebaseline/)
+[![Tools](https://img.shields.io/badge/MCP%20tools-163-orange)](https://stablebaseline.io/docs/mcp/tools)
+
+Python SDK for the **[Stable Baseline](https://stablebaseline.io) REST API** — the simplest, most complete, end-to-end agent-managed company brain. Living docs, 40+ visual diagrams, plans, and a self-learning Knowledge Graph. 163 tools across 16 categories.
+
+## Install
+
+```bash
+pip install stablebaseline
+```
+
+## Quick start
+
+```python
+from stablebaseline import StableBaseline
+
+# Mint a key at app.stablebaseline.io/settings/mcp-keys
+with StableBaseline(api_key="sta_xxx") as sb:
+    orgs = sb.tools.listOrganisations()
+    print(orgs)
+
+    doc = sb.tools.createDocument(
+        folderId="folder-uuid",
+        title="Q4 architecture",
+        cdmd="# Architecture\n\nThis document covers...",
+    )
+    print(f"Created {doc['friendlyId']} ({doc['id']})")
+
+    search = sb.tools.kg_search(query="compliance posture", mode="global")
+    print(search["entities"])
+```
+
+Or asynchronously:
+
+```python
+import asyncio
+from stablebaseline import AsyncStableBaseline
+
+async def main() -> None:
+    async with AsyncStableBaseline(api_key="sta_xxx") as sb:
+        orgs = await sb.tools.listOrganisations()
+        print(orgs)
+
+asyncio.run(main())
+```
+
+## Auth
+
+```python
+StableBaseline(api_key="sta_...")              # API key (mint at app.stablebaseline.io/settings/mcp-keys)
+StableBaseline(access_token="...")             # OAuth 2.1 access token
+StableBaseline()                               # picks up SB_API_KEY / SB_ACCESS_TOKEN from env
+```
+
+## Tool dispatch
+
+Each method on `client.tools` corresponds to one of the [163 MCP tools](https://stablebaseline.io/docs/mcp/tools):
+
+```python
+sb.tools.listOrganisations()
+sb.tools.getProjectHierarchy(projectId="...")
+sb.tools.createDocument(folderId="...", title="X", cdmd="# ...")
+sb.tools.editDocument(documentId="...", versionTimestamp=..., patches=[...])
+sb.tools.kg_search(query="...", mode="global")
+sb.tools.previewSubscriptionChange(...)
+sb.tools.applySubscriptionChange(...)
+```
+
+For dynamic / discovered names, use the callable form:
+
+```python
+sb.tools("createDocument", {"folderId": "...", "title": "X", "cdmd": "# Hi"})
+```
+
+Or the lower-level `call_tool`:
+
+```python
+sb.call_tool("createDocument", {"folderId": "...", "title": "X", "cdmd": "# Hi"})
+```
+
+## Discover tools at runtime
+
+```python
+catalogue = sb.list_tools()
+print(f"{catalogue['count']} tools across categories:")
+cats = {t['category'] for t in catalogue['tools']}
+print(sorted(cats))
+```
+
+## Errors
+
+All non-2xx responses raise `StableBaselineToolError` with `status`, `code`, `message`, and optional `details`:
+
+```python
+from stablebaseline import StableBaseline, StableBaselineToolError
+
+with StableBaseline(api_key="sta_xxx") as sb:
+    try:
+        sb.tools.deleteDocument(documentId="missing")
+    except StableBaselineToolError as e:
+        if e.status == 404:
+            print("not found")
+        elif e.code == "permission_denied":
+            print("RBAC said no")
+        else:
+            raise
+```
+
+## Companion packages
+
+| Surface | Package | Use case |
+|---|---|---|
+| **Python SDK** (this) | `stablebaseline` | Python apps, data work |
+| **TypeScript SDK** | `@stablebaseline/sdk` | Node, browsers, Deno, Bun |
+| **CLI** | `@stablebaseline/cli` (binary `sb`) | Shells, scripts, CI/CD |
+| **MCP server** | `https://api.stablebaseline.io/functions/v1/cloud-serve/mcp` | AI agents (Claude Code, Cursor, Windsurf, ChatGPT, Gemini, …) |
+
+All four share the same auth, same handlers, same data — see [github.com/stablebaseline/mcp](https://github.com/stablebaseline/mcp).
+
+## License
+
+MIT — see [LICENSE](../../LICENSE) at the repo root. The Stable Baseline product itself is proprietary SaaS at [stablebaseline.io](https://stablebaseline.io).

stablebaseline-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+stablebaseline/__init__.py,sha256=Hug2pgQSeM-v4Ey8rwf0Yol2HNvwXDQMAFtJC2AA4f4,644
+stablebaseline/client.py,sha256=-kawSNcENVcZZCMsGYvc6KzicJSNT9gWHWYoX8cYvoQ,7384
+stablebaseline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+stablebaseline-0.1.0.dist-info/METADATA,sha256=X2Ji-cO31wHLjPwVV-CeRBqcqZMFA3y2yA7gm8YKZbs,5516
+stablebaseline-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stablebaseline-0.1.0.dist-info/licenses/LICENSE,sha256=kIfp0IYSuP2vHoYwow3tcjpi4r7lQL4Dy6yXyfTcoFg,1082
+stablebaseline-0.1.0.dist-info/RECORD,,

stablebaseline-0.1.0.dist-info/WHEEL

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

stablebaseline-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orixian Solutions Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.