mbs-python — Python SDK for MBS Workbench
Official async Python client for MBS Workbench.
Connects to a running mbsd daemon or any OpenAI-compatible server.
Installation
pip install mbs-python
# with NumPy support:
pip install "mbs-python[numpy]"
# with Pandas support:
pip install "mbs-python[pandas]"
# everything:
pip install "mbs-python[all]"
Quick Start
import asyncio
from mbs import MbsClient
async def main():
async with MbsClient(base_url="http://127.0.0.1:3030") as client:
# Chat completion
resp = await client.chat([
{"role": "user", "content": "Explain Rust ownership in 2 sentences."}
])
print(resp.choices[0].message.content)
# Streaming
async for delta in await client.chat_stream([
{"role": "user", "content": "Write a haiku about async."}
]):
print(delta, end="", flush=True)
print()
# Embeddings
resp = await client.embed("Hello, world!")
print(len(resp.data[0].embedding)) # vector dimension
asyncio.run(main())
API Reference
MbsClient
client = MbsClient(
base_url="http://127.0.0.1:3030", # default
api_key=None, # optional bearer token
timeout=120.0, # seconds
max_retries=3, # on 429/5xx
retry_base_delay_ms=500,
)
| Method | Description |
|---|---|
await client.models() |
List available models → ModelsResponse |
await client.load_model(req) |
Load a .gguf into VRAM → ModelLoadResponse |
await client.unload_model() |
Unload current model → ModelUnloadResponse |
await client.chat(messages, *, model, temperature, max_tokens, stop) |
Chat completion → ChatCompletionResponse |
await client.chat_stream(messages, ...) |
Async iterator yielding text deltas |
await client.complete(prompt, ...) |
Text completion → CompletionResponse |
await client.embed(input, *, model) |
Embeddings → EmbeddingResponse |
await client.embed_numpy(input, *, model) |
Embeddings as NumPy array (requires [numpy]) |
await client.generate_image(prompt, *, n, size) |
Image generation → ImageGenerationResponse |
await client.run_agent(task, *, model, max_iterations) |
ReAct agent → AgentRunResponse |
await client.list_tools() |
List MCP tools → McpToolsResponse |
await client.invoke_tool(tool_id, arguments) |
Invoke MCP tool → McpInvokeResponse |
await client.anthropic_messages(req) |
Anthropic-compatible → AnthropicMessagesResponse |
await client.batch_chat(requests, *, concurrency) |
Batch chat → BatchSummary |
await client.batch_embed(inputs, *, model, concurrency) |
Batch embeddings → BatchSummary |
await client.batch_embed_dataframe(series, ...) |
Add embedding column to Pandas Series (requires [pandas]) |
await client.ping() |
Health check → bool |
Streaming
async for delta in await client.chat_stream([
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Tell me about Python 3.12."},
]):
print(delta, end="", flush=True)
Batch Processing
from mbs import ChatCompletionRequest, ChatMessage
requests = [
ChatCompletionRequest(messages=[ChatMessage(role="user", content=f"What is {i}^2?")])
for i in range(10)
]
summary = await client.batch_chat(requests, concurrency=5)
print(f"{summary.succeeded}/{len(summary.results)} succeeded")
for item in summary.results:
if item.ok:
data = item.value # dict from ChatCompletionResponse.model_dump()
print(data["choices"][0]["message"]["content"])
else:
print(f"Error: {item.error}")
NumPy / Pandas Integration
import numpy as np
import pandas as pd
# Get embeddings as a numpy array — shape (n, dim)
vectors = await client.embed_numpy(["hello", "world", "rust"])
print(vectors.shape) # e.g. (3, 4096)
# Add embedding column to a DataFrame
df = pd.DataFrame({"text": ["foo", "bar", "baz"]})
df["embedding"] = await client.batch_embed_dataframe(
df["text"], concurrency=3
)
Error Handling
from mbs import MbsError
try:
resp = await client.chat([{"role": "user", "content": "Hi"}])
except MbsError as e:
print(f"HTTP {e.status_code}: {e}")
Transient errors (429, 500–504) are automatically retried with exponential backoff + jitter.
Context Manager
async with MbsClient() as client:
print(await client.ping())
# connection pool is closed automatically
Running Tests
cd sdk/python
pip install -e ".[dev]"
pytest tests/ -v
Metadata
Release files for mbs-python 0.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mbs_python-0.2.4.tar.gz | 14.6 kB | Without provenance | Details for mbs_python-0.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mbs_python-0.2.4-py3-none-any.whl | Python 3 | none | any | Details for mbs_python-0.2.4-py3-none-any.whl |
Total release size: 26.7 kB
Release files / mbs_python-0.2.4.tar.gz
| Download URL | mbs_python-0.2.4.tar.gz |
|---|---|
| Size | 14.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
16e8dd451ca86e8f0f4376f8a0990c34d0990acaffbaf0bd452416f6d13bb6c1
|
|
BLAKE2b-256 checksum How to use checksums |
09a2accaab82278c0c619cdfa318c2112957e23f64e474f75eb3780063f26d52
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / mbs_python-0.2.4-py3-none-any.whl
| Download URL | mbs_python-0.2.4-py3-none-any.whl |
|---|---|
| Size | 12.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4da14f5636bdc84048d5a6c95c5d4d59e53ef05031105d351973c7a8802a9afc
|
|
BLAKE2b-256 checksum How to use checksums |
5c47d90613025a65a4cea11fb63a53c37658bed9da3dfd281e321ff5c09a79ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for mbs-python 0.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.