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).
