stablebaseline 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- stablebaseline-0.1.0/.gitignore +43 -0
- stablebaseline-0.1.0/LICENSE +21 -0
- stablebaseline-0.1.0/PKG-INFO +156 -0
- stablebaseline-0.1.0/README.md +124 -0
- stablebaseline-0.1.0/pyproject.toml +69 -0
- stablebaseline-0.1.0/stablebaseline/__init__.py +25 -0
- stablebaseline-0.1.0/stablebaseline/client.py +225 -0
- stablebaseline-0.1.0/stablebaseline/py.typed +0 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Build outputs
|
|
2
|
+
dist/
|
|
3
|
+
build/
|
|
4
|
+
*.tsbuildinfo
|
|
5
|
+
|
|
6
|
+
# Generated types
|
|
7
|
+
packages/sdk-typescript/src/types.generated.ts
|
|
8
|
+
packages/sdk-typescript/openapi.json
|
|
9
|
+
packages/sdk-python/openapi.json
|
|
10
|
+
packages/cli/openapi.json
|
|
11
|
+
openapi.json
|
|
12
|
+
|
|
13
|
+
# Node
|
|
14
|
+
node_modules/
|
|
15
|
+
.npm
|
|
16
|
+
*.log
|
|
17
|
+
npm-debug.log*
|
|
18
|
+
|
|
19
|
+
# Python
|
|
20
|
+
__pycache__/
|
|
21
|
+
*.py[cod]
|
|
22
|
+
*$py.class
|
|
23
|
+
*.egg-info/
|
|
24
|
+
.venv/
|
|
25
|
+
.pytest_cache/
|
|
26
|
+
.mypy_cache/
|
|
27
|
+
.ruff_cache/
|
|
28
|
+
|
|
29
|
+
# OS
|
|
30
|
+
.DS_Store
|
|
31
|
+
Thumbs.db
|
|
32
|
+
|
|
33
|
+
# Editors
|
|
34
|
+
.vscode/
|
|
35
|
+
.idea/
|
|
36
|
+
*.swp
|
|
37
|
+
*~
|
|
38
|
+
|
|
39
|
+
# CLI build outputs
|
|
40
|
+
packages/cli/sb
|
|
41
|
+
packages/cli/sb.exe
|
|
42
|
+
packages/cli/sb-*.tar.gz
|
|
43
|
+
packages/cli/sb-*.zip
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Orixian Solutions Pty Ltd
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: stablebaseline
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
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.
|
|
5
|
+
Project-URL: Homepage, https://stablebaseline.io
|
|
6
|
+
Project-URL: Documentation, https://stablebaseline.io/docs/mcp
|
|
7
|
+
Project-URL: Repository, https://github.com/stablebaseline/mcp
|
|
8
|
+
Project-URL: Issues, https://github.com/stablebaseline/mcp/issues
|
|
9
|
+
Author-email: Stable Baseline <hello@stablebaseline.io>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ai-agent,company-brain,diagrams,documentation,knowledge-graph,mcp,model-context-protocol,plans,rest-api,sdk,stable-baseline,stablebaseline
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Operating System :: OS Independent
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
23
|
+
Classifier: Typing :: Typed
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Requires-Dist: httpx>=0.27.0
|
|
26
|
+
Requires-Dist: typing-extensions>=4.10.0; python_version < '3.12'
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: mypy>=1.13.0; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=8.0.0; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff>=0.7.0; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# stablebaseline
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/stablebaseline/)
|
|
36
|
+
[](https://stablebaseline.io/docs/mcp/tools)
|
|
37
|
+
|
|
38
|
+
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.
|
|
39
|
+
|
|
40
|
+
## Install
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
pip install stablebaseline
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Quick start
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
from stablebaseline import StableBaseline
|
|
50
|
+
|
|
51
|
+
# Mint a key at app.stablebaseline.io/settings/mcp-keys
|
|
52
|
+
with StableBaseline(api_key="sta_xxx") as sb:
|
|
53
|
+
orgs = sb.tools.listOrganisations()
|
|
54
|
+
print(orgs)
|
|
55
|
+
|
|
56
|
+
doc = sb.tools.createDocument(
|
|
57
|
+
folderId="folder-uuid",
|
|
58
|
+
title="Q4 architecture",
|
|
59
|
+
cdmd="# Architecture\n\nThis document covers...",
|
|
60
|
+
)
|
|
61
|
+
print(f"Created {doc['friendlyId']} ({doc['id']})")
|
|
62
|
+
|
|
63
|
+
search = sb.tools.kg_search(query="compliance posture", mode="global")
|
|
64
|
+
print(search["entities"])
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Or asynchronously:
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
import asyncio
|
|
71
|
+
from stablebaseline import AsyncStableBaseline
|
|
72
|
+
|
|
73
|
+
async def main() -> None:
|
|
74
|
+
async with AsyncStableBaseline(api_key="sta_xxx") as sb:
|
|
75
|
+
orgs = await sb.tools.listOrganisations()
|
|
76
|
+
print(orgs)
|
|
77
|
+
|
|
78
|
+
asyncio.run(main())
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Auth
|
|
82
|
+
|
|
83
|
+
```python
|
|
84
|
+
StableBaseline(api_key="sta_...") # API key (mint at app.stablebaseline.io/settings/mcp-keys)
|
|
85
|
+
StableBaseline(access_token="...") # OAuth 2.1 access token
|
|
86
|
+
StableBaseline() # picks up SB_API_KEY / SB_ACCESS_TOKEN from env
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Tool dispatch
|
|
90
|
+
|
|
91
|
+
Each method on `client.tools` corresponds to one of the [163 MCP tools](https://stablebaseline.io/docs/mcp/tools):
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
sb.tools.listOrganisations()
|
|
95
|
+
sb.tools.getProjectHierarchy(projectId="...")
|
|
96
|
+
sb.tools.createDocument(folderId="...", title="X", cdmd="# ...")
|
|
97
|
+
sb.tools.editDocument(documentId="...", versionTimestamp=..., patches=[...])
|
|
98
|
+
sb.tools.kg_search(query="...", mode="global")
|
|
99
|
+
sb.tools.previewSubscriptionChange(...)
|
|
100
|
+
sb.tools.applySubscriptionChange(...)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
For dynamic / discovered names, use the callable form:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
sb.tools("createDocument", {"folderId": "...", "title": "X", "cdmd": "# Hi"})
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Or the lower-level `call_tool`:
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
sb.call_tool("createDocument", {"folderId": "...", "title": "X", "cdmd": "# Hi"})
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Discover tools at runtime
|
|
116
|
+
|
|
117
|
+
```python
|
|
118
|
+
catalogue = sb.list_tools()
|
|
119
|
+
print(f"{catalogue['count']} tools across categories:")
|
|
120
|
+
cats = {t['category'] for t in catalogue['tools']}
|
|
121
|
+
print(sorted(cats))
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## Errors
|
|
125
|
+
|
|
126
|
+
All non-2xx responses raise `StableBaselineToolError` with `status`, `code`, `message`, and optional `details`:
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
from stablebaseline import StableBaseline, StableBaselineToolError
|
|
130
|
+
|
|
131
|
+
with StableBaseline(api_key="sta_xxx") as sb:
|
|
132
|
+
try:
|
|
133
|
+
sb.tools.deleteDocument(documentId="missing")
|
|
134
|
+
except StableBaselineToolError as e:
|
|
135
|
+
if e.status == 404:
|
|
136
|
+
print("not found")
|
|
137
|
+
elif e.code == "permission_denied":
|
|
138
|
+
print("RBAC said no")
|
|
139
|
+
else:
|
|
140
|
+
raise
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Companion packages
|
|
144
|
+
|
|
145
|
+
| Surface | Package | Use case |
|
|
146
|
+
|---|---|---|
|
|
147
|
+
| **Python SDK** (this) | `stablebaseline` | Python apps, data work |
|
|
148
|
+
| **TypeScript SDK** | `@stablebaseline/sdk` | Node, browsers, Deno, Bun |
|
|
149
|
+
| **CLI** | `@stablebaseline/cli` (binary `sb`) | Shells, scripts, CI/CD |
|
|
150
|
+
| **MCP server** | `https://api.stablebaseline.io/functions/v1/cloud-serve/mcp` | AI agents (Claude Code, Cursor, Windsurf, ChatGPT, Gemini, …) |
|
|
151
|
+
|
|
152
|
+
All four share the same auth, same handlers, same data — see [github.com/stablebaseline/mcp](https://github.com/stablebaseline/mcp).
|
|
153
|
+
|
|
154
|
+
## License
|
|
155
|
+
|
|
156
|
+
MIT — see [LICENSE](../../LICENSE) at the repo root. The Stable Baseline product itself is proprietary SaaS at [stablebaseline.io](https://stablebaseline.io).
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# stablebaseline
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/stablebaseline/)
|
|
4
|
+
[](https://stablebaseline.io/docs/mcp/tools)
|
|
5
|
+
|
|
6
|
+
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.
|
|
7
|
+
|
|
8
|
+
## Install
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
pip install stablebaseline
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Quick start
|
|
15
|
+
|
|
16
|
+
```python
|
|
17
|
+
from stablebaseline import StableBaseline
|
|
18
|
+
|
|
19
|
+
# Mint a key at app.stablebaseline.io/settings/mcp-keys
|
|
20
|
+
with StableBaseline(api_key="sta_xxx") as sb:
|
|
21
|
+
orgs = sb.tools.listOrganisations()
|
|
22
|
+
print(orgs)
|
|
23
|
+
|
|
24
|
+
doc = sb.tools.createDocument(
|
|
25
|
+
folderId="folder-uuid",
|
|
26
|
+
title="Q4 architecture",
|
|
27
|
+
cdmd="# Architecture\n\nThis document covers...",
|
|
28
|
+
)
|
|
29
|
+
print(f"Created {doc['friendlyId']} ({doc['id']})")
|
|
30
|
+
|
|
31
|
+
search = sb.tools.kg_search(query="compliance posture", mode="global")
|
|
32
|
+
print(search["entities"])
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Or asynchronously:
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
import asyncio
|
|
39
|
+
from stablebaseline import AsyncStableBaseline
|
|
40
|
+
|
|
41
|
+
async def main() -> None:
|
|
42
|
+
async with AsyncStableBaseline(api_key="sta_xxx") as sb:
|
|
43
|
+
orgs = await sb.tools.listOrganisations()
|
|
44
|
+
print(orgs)
|
|
45
|
+
|
|
46
|
+
asyncio.run(main())
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Auth
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
StableBaseline(api_key="sta_...") # API key (mint at app.stablebaseline.io/settings/mcp-keys)
|
|
53
|
+
StableBaseline(access_token="...") # OAuth 2.1 access token
|
|
54
|
+
StableBaseline() # picks up SB_API_KEY / SB_ACCESS_TOKEN from env
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Tool dispatch
|
|
58
|
+
|
|
59
|
+
Each method on `client.tools` corresponds to one of the [163 MCP tools](https://stablebaseline.io/docs/mcp/tools):
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
sb.tools.listOrganisations()
|
|
63
|
+
sb.tools.getProjectHierarchy(projectId="...")
|
|
64
|
+
sb.tools.createDocument(folderId="...", title="X", cdmd="# ...")
|
|
65
|
+
sb.tools.editDocument(documentId="...", versionTimestamp=..., patches=[...])
|
|
66
|
+
sb.tools.kg_search(query="...", mode="global")
|
|
67
|
+
sb.tools.previewSubscriptionChange(...)
|
|
68
|
+
sb.tools.applySubscriptionChange(...)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
For dynamic / discovered names, use the callable form:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
sb.tools("createDocument", {"folderId": "...", "title": "X", "cdmd": "# Hi"})
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or the lower-level `call_tool`:
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
sb.call_tool("createDocument", {"folderId": "...", "title": "X", "cdmd": "# Hi"})
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Discover tools at runtime
|
|
84
|
+
|
|
85
|
+
```python
|
|
86
|
+
catalogue = sb.list_tools()
|
|
87
|
+
print(f"{catalogue['count']} tools across categories:")
|
|
88
|
+
cats = {t['category'] for t in catalogue['tools']}
|
|
89
|
+
print(sorted(cats))
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## Errors
|
|
93
|
+
|
|
94
|
+
All non-2xx responses raise `StableBaselineToolError` with `status`, `code`, `message`, and optional `details`:
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from stablebaseline import StableBaseline, StableBaselineToolError
|
|
98
|
+
|
|
99
|
+
with StableBaseline(api_key="sta_xxx") as sb:
|
|
100
|
+
try:
|
|
101
|
+
sb.tools.deleteDocument(documentId="missing")
|
|
102
|
+
except StableBaselineToolError as e:
|
|
103
|
+
if e.status == 404:
|
|
104
|
+
print("not found")
|
|
105
|
+
elif e.code == "permission_denied":
|
|
106
|
+
print("RBAC said no")
|
|
107
|
+
else:
|
|
108
|
+
raise
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Companion packages
|
|
112
|
+
|
|
113
|
+
| Surface | Package | Use case |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| **Python SDK** (this) | `stablebaseline` | Python apps, data work |
|
|
116
|
+
| **TypeScript SDK** | `@stablebaseline/sdk` | Node, browsers, Deno, Bun |
|
|
117
|
+
| **CLI** | `@stablebaseline/cli` (binary `sb`) | Shells, scripts, CI/CD |
|
|
118
|
+
| **MCP server** | `https://api.stablebaseline.io/functions/v1/cloud-serve/mcp` | AI agents (Claude Code, Cursor, Windsurf, ChatGPT, Gemini, …) |
|
|
119
|
+
|
|
120
|
+
All four share the same auth, same handlers, same data — see [github.com/stablebaseline/mcp](https://github.com/stablebaseline/mcp).
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
MIT — see [LICENSE](../../LICENSE) at the repo root. The Stable Baseline product itself is proprietary SaaS at [stablebaseline.io](https://stablebaseline.io).
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "stablebaseline"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "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."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [{ name = "Stable Baseline", email = "hello@stablebaseline.io" }]
|
|
13
|
+
keywords = [
|
|
14
|
+
"stablebaseline",
|
|
15
|
+
"stable-baseline",
|
|
16
|
+
"mcp",
|
|
17
|
+
"model-context-protocol",
|
|
18
|
+
"knowledge-graph",
|
|
19
|
+
"company-brain",
|
|
20
|
+
"documentation",
|
|
21
|
+
"diagrams",
|
|
22
|
+
"plans",
|
|
23
|
+
"ai-agent",
|
|
24
|
+
"rest-api",
|
|
25
|
+
"sdk",
|
|
26
|
+
]
|
|
27
|
+
classifiers = [
|
|
28
|
+
"Development Status :: 4 - Beta",
|
|
29
|
+
"Intended Audience :: Developers",
|
|
30
|
+
"License :: OSI Approved :: MIT License",
|
|
31
|
+
"Operating System :: OS Independent",
|
|
32
|
+
"Programming Language :: Python :: 3",
|
|
33
|
+
"Programming Language :: Python :: 3.10",
|
|
34
|
+
"Programming Language :: Python :: 3.11",
|
|
35
|
+
"Programming Language :: Python :: 3.12",
|
|
36
|
+
"Programming Language :: Python :: 3.13",
|
|
37
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
38
|
+
"Typing :: Typed",
|
|
39
|
+
]
|
|
40
|
+
dependencies = [
|
|
41
|
+
"httpx>=0.27.0",
|
|
42
|
+
"typing-extensions>=4.10.0; python_version < '3.12'",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[project.urls]
|
|
46
|
+
Homepage = "https://stablebaseline.io"
|
|
47
|
+
Documentation = "https://stablebaseline.io/docs/mcp"
|
|
48
|
+
Repository = "https://github.com/stablebaseline/mcp"
|
|
49
|
+
Issues = "https://github.com/stablebaseline/mcp/issues"
|
|
50
|
+
|
|
51
|
+
[project.optional-dependencies]
|
|
52
|
+
dev = ["pytest>=8.0.0", "ruff>=0.7.0", "mypy>=1.13.0"]
|
|
53
|
+
|
|
54
|
+
[tool.hatch.build.targets.wheel]
|
|
55
|
+
packages = ["stablebaseline"]
|
|
56
|
+
|
|
57
|
+
[tool.hatch.build.targets.sdist]
|
|
58
|
+
include = ["stablebaseline", "README.md", "LICENSE", "openapi.json"]
|
|
59
|
+
|
|
60
|
+
[tool.ruff]
|
|
61
|
+
line-length = 100
|
|
62
|
+
target-version = "py310"
|
|
63
|
+
|
|
64
|
+
[tool.ruff.lint]
|
|
65
|
+
select = ["E", "F", "I", "B", "UP", "RUF"]
|
|
66
|
+
|
|
67
|
+
[tool.mypy]
|
|
68
|
+
strict = true
|
|
69
|
+
python_version = "3.10"
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Stable Baseline — Python SDK for the REST API.
|
|
2
|
+
|
|
3
|
+
from stablebaseline import StableBaseline
|
|
4
|
+
|
|
5
|
+
sb = StableBaseline(api_key="sta_xxx")
|
|
6
|
+
orgs = sb.tools.listOrganisations()
|
|
7
|
+
doc = sb.tools.createDocument(folder_id="...", title="X", cdmd="# Hi")
|
|
8
|
+
|
|
9
|
+
The same surface is available asynchronously via :class:`AsyncStableBaseline`.
|
|
10
|
+
163 MCP tools across 16 categories — see https://stablebaseline.io/docs/mcp/tools.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from .client import (
|
|
14
|
+
AsyncStableBaseline,
|
|
15
|
+
StableBaseline,
|
|
16
|
+
StableBaselineToolError,
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
__all__ = [
|
|
20
|
+
"StableBaseline",
|
|
21
|
+
"AsyncStableBaseline",
|
|
22
|
+
"StableBaselineToolError",
|
|
23
|
+
]
|
|
24
|
+
|
|
25
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
"""HTTP client for the Stable Baseline REST API.
|
|
2
|
+
|
|
3
|
+
Sync and async variants share the same dispatch logic via a small base
|
|
4
|
+
class. All 163 MCP tools are reachable as ``client.tools.<tool_name>(...)``.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import os
|
|
10
|
+
from typing import Any, Iterator, Mapping
|
|
11
|
+
|
|
12
|
+
import httpx
|
|
13
|
+
|
|
14
|
+
DEFAULT_BASE_URL = "https://api.stablebaseline.io/functions/v1/cloud-serve/api/v1"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class StableBaselineToolError(Exception):
|
|
18
|
+
"""Raised when the server returns a non-2xx response."""
|
|
19
|
+
|
|
20
|
+
def __init__(
|
|
21
|
+
self,
|
|
22
|
+
status: int,
|
|
23
|
+
code: str,
|
|
24
|
+
message: str,
|
|
25
|
+
details: Mapping[str, Any] | None = None,
|
|
26
|
+
) -> None:
|
|
27
|
+
super().__init__(f"[{status} {code}] {message}")
|
|
28
|
+
self.status = status
|
|
29
|
+
self.code = code
|
|
30
|
+
self.message = message
|
|
31
|
+
self.details = details or {}
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _auth_header(api_key: str | None, access_token: str | None) -> dict[str, str]:
|
|
35
|
+
token = access_token or api_key
|
|
36
|
+
if not token:
|
|
37
|
+
return {}
|
|
38
|
+
return {"Authorization": f"Bearer {token}"}
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _resolve_credential(
|
|
42
|
+
api_key: str | None, access_token: str | None
|
|
43
|
+
) -> tuple[str | None, str | None]:
|
|
44
|
+
api_key = api_key or os.environ.get("SB_API_KEY")
|
|
45
|
+
access_token = access_token or os.environ.get("SB_ACCESS_TOKEN")
|
|
46
|
+
if not api_key and not access_token:
|
|
47
|
+
raise ValueError(
|
|
48
|
+
"No credential provided. Pass `api_key=` or `access_token=`, "
|
|
49
|
+
"or set the SB_API_KEY / SB_ACCESS_TOKEN env vars."
|
|
50
|
+
)
|
|
51
|
+
return api_key, access_token
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _raise_for_error(response: httpx.Response) -> None:
|
|
55
|
+
try:
|
|
56
|
+
body = response.json()
|
|
57
|
+
except Exception:
|
|
58
|
+
body = None
|
|
59
|
+
envelope = (body or {}).get("error") or {}
|
|
60
|
+
raise StableBaselineToolError(
|
|
61
|
+
status=response.status_code,
|
|
62
|
+
code=envelope.get("code") or f"http_{response.status_code}",
|
|
63
|
+
message=envelope.get("message") or response.reason_phrase,
|
|
64
|
+
details=envelope.get("details"),
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
# ── Sync client ──────────────────────────────────────────────────────
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class _SyncToolDispatcher:
|
|
72
|
+
"""Dynamic attribute-based tool dispatch — ``client.tools.<name>(input)``."""
|
|
73
|
+
|
|
74
|
+
def __init__(self, client: "StableBaseline") -> None:
|
|
75
|
+
self._client = client
|
|
76
|
+
|
|
77
|
+
def __getattr__(self, name: str) -> Any:
|
|
78
|
+
if name.startswith("_"):
|
|
79
|
+
raise AttributeError(name)
|
|
80
|
+
return lambda **kwargs: self._client.call_tool(name, kwargs)
|
|
81
|
+
|
|
82
|
+
def __call__(self, name: str, input: Mapping[str, Any] | None = None) -> Any:
|
|
83
|
+
"""Escape hatch: ``client.tools("listOrganisations", {})``."""
|
|
84
|
+
return self._client.call_tool(name, dict(input or {}))
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class StableBaseline:
|
|
88
|
+
"""Synchronous client. Use as a context manager for connection reuse:
|
|
89
|
+
|
|
90
|
+
with StableBaseline(api_key="sta_xxx") as sb:
|
|
91
|
+
orgs = sb.tools.listOrganisations()
|
|
92
|
+
|
|
93
|
+
Or instantiate directly; ``httpx.Client`` is created lazily and closed
|
|
94
|
+
when ``close()`` is called.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
def __init__(
|
|
98
|
+
self,
|
|
99
|
+
*,
|
|
100
|
+
api_key: str | None = None,
|
|
101
|
+
access_token: str | None = None,
|
|
102
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
103
|
+
timeout: float | None = 30.0,
|
|
104
|
+
http_client: httpx.Client | None = None,
|
|
105
|
+
) -> None:
|
|
106
|
+
api_key, access_token = _resolve_credential(api_key, access_token)
|
|
107
|
+
self._base_url = base_url.rstrip("/")
|
|
108
|
+
self._headers = _auth_header(api_key, access_token)
|
|
109
|
+
self._http = http_client or httpx.Client(timeout=timeout)
|
|
110
|
+
self._owns_http = http_client is None
|
|
111
|
+
self.tools = _SyncToolDispatcher(self)
|
|
112
|
+
|
|
113
|
+
# — Public surface —
|
|
114
|
+
|
|
115
|
+
def call_tool(self, name: str, params: Mapping[str, Any] | None = None) -> Any:
|
|
116
|
+
url = f"{self._base_url}/tools/{name}"
|
|
117
|
+
res = self._http.post(
|
|
118
|
+
url,
|
|
119
|
+
headers={"Content-Type": "application/json", **self._headers},
|
|
120
|
+
json=dict(params or {}),
|
|
121
|
+
)
|
|
122
|
+
if not res.is_success:
|
|
123
|
+
_raise_for_error(res)
|
|
124
|
+
return res.json()
|
|
125
|
+
|
|
126
|
+
def list_tools(self) -> dict[str, Any]:
|
|
127
|
+
res = self._http.get(f"{self._base_url}/tools")
|
|
128
|
+
res.raise_for_status()
|
|
129
|
+
return res.json()
|
|
130
|
+
|
|
131
|
+
def openapi(self) -> dict[str, Any]:
|
|
132
|
+
res = self._http.get(f"{self._base_url}/openapi.json")
|
|
133
|
+
res.raise_for_status()
|
|
134
|
+
return res.json()
|
|
135
|
+
|
|
136
|
+
# — Resource management —
|
|
137
|
+
|
|
138
|
+
def close(self) -> None:
|
|
139
|
+
if self._owns_http:
|
|
140
|
+
self._http.close()
|
|
141
|
+
|
|
142
|
+
def __enter__(self) -> "StableBaseline":
|
|
143
|
+
return self
|
|
144
|
+
|
|
145
|
+
def __exit__(self, *_: object) -> None:
|
|
146
|
+
self.close()
|
|
147
|
+
|
|
148
|
+
def __iter__(self) -> Iterator[Any]:
|
|
149
|
+
# Prevent surprise iteration (httpx.Client supports it).
|
|
150
|
+
raise TypeError("StableBaseline is not iterable; use sb.tools.<name>(...).")
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
# ── Async client ─────────────────────────────────────────────────────
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class _AsyncToolDispatcher:
|
|
157
|
+
def __init__(self, client: "AsyncStableBaseline") -> None:
|
|
158
|
+
self._client = client
|
|
159
|
+
|
|
160
|
+
def __getattr__(self, name: str) -> Any:
|
|
161
|
+
if name.startswith("_"):
|
|
162
|
+
raise AttributeError(name)
|
|
163
|
+
|
|
164
|
+
async def _call(**kwargs: Any) -> Any:
|
|
165
|
+
return await self._client.call_tool(name, kwargs)
|
|
166
|
+
|
|
167
|
+
return _call
|
|
168
|
+
|
|
169
|
+
def __call__(self, name: str, input: Mapping[str, Any] | None = None) -> Any:
|
|
170
|
+
return self._client.call_tool(name, dict(input or {}))
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
class AsyncStableBaseline:
|
|
174
|
+
"""Asynchronous client.
|
|
175
|
+
|
|
176
|
+
async with AsyncStableBaseline(api_key="sta_xxx") as sb:
|
|
177
|
+
orgs = await sb.tools.listOrganisations()
|
|
178
|
+
"""
|
|
179
|
+
|
|
180
|
+
def __init__(
|
|
181
|
+
self,
|
|
182
|
+
*,
|
|
183
|
+
api_key: str | None = None,
|
|
184
|
+
access_token: str | None = None,
|
|
185
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
186
|
+
timeout: float | None = 30.0,
|
|
187
|
+
http_client: httpx.AsyncClient | None = None,
|
|
188
|
+
) -> None:
|
|
189
|
+
api_key, access_token = _resolve_credential(api_key, access_token)
|
|
190
|
+
self._base_url = base_url.rstrip("/")
|
|
191
|
+
self._headers = _auth_header(api_key, access_token)
|
|
192
|
+
self._http = http_client or httpx.AsyncClient(timeout=timeout)
|
|
193
|
+
self._owns_http = http_client is None
|
|
194
|
+
self.tools = _AsyncToolDispatcher(self)
|
|
195
|
+
|
|
196
|
+
async def call_tool(self, name: str, params: Mapping[str, Any] | None = None) -> Any:
|
|
197
|
+
url = f"{self._base_url}/tools/{name}"
|
|
198
|
+
res = await self._http.post(
|
|
199
|
+
url,
|
|
200
|
+
headers={"Content-Type": "application/json", **self._headers},
|
|
201
|
+
json=dict(params or {}),
|
|
202
|
+
)
|
|
203
|
+
if not res.is_success:
|
|
204
|
+
_raise_for_error(res)
|
|
205
|
+
return res.json()
|
|
206
|
+
|
|
207
|
+
async def list_tools(self) -> dict[str, Any]:
|
|
208
|
+
res = await self._http.get(f"{self._base_url}/tools")
|
|
209
|
+
res.raise_for_status()
|
|
210
|
+
return res.json()
|
|
211
|
+
|
|
212
|
+
async def openapi(self) -> dict[str, Any]:
|
|
213
|
+
res = await self._http.get(f"{self._base_url}/openapi.json")
|
|
214
|
+
res.raise_for_status()
|
|
215
|
+
return res.json()
|
|
216
|
+
|
|
217
|
+
async def aclose(self) -> None:
|
|
218
|
+
if self._owns_http:
|
|
219
|
+
await self._http.aclose()
|
|
220
|
+
|
|
221
|
+
async def __aenter__(self) -> "AsyncStableBaseline":
|
|
222
|
+
return self
|
|
223
|
+
|
|
224
|
+
async def __aexit__(self, *_: object) -> None:
|
|
225
|
+
await self.aclose()
|
|
File without changes
|