Skip to main content

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)

Source distribution for mbs-python 0.2.4
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)

Table of built distributions (wheels) for mbs-python 0.2.4
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.2.4 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page