Soma Python provider helper

Soma embeds this dependency-free module into the Python provider bridge. A drop-in provider can import the decorator without installing a package. The same module is packaged as the soma-provider distribution for IDEs, tests, and Python projects that want an explicit dependency:

uv pip install ./packages/python

Provider files use the same import in both modes:

from soma_provider import Context, provider, tool

PROVIDER = provider(name="example", kind="python")

@tool(
    name="greet",
    title="Greet",
    input_schema={
        "type": "object",
        "additionalProperties": False,
        "properties": {"name": {"type": "string"}},
        "required": ["name"],
    },
)
def greet(name: str, ctx: Context) -> dict:
    """Return a greeting with runner request identity."""
    return {
        "message": f"Hello, {name}!",
        "surface": ctx.request.surface,
    }

The decorator returns the original function unchanged and records only JSON-compatible metadata. Omitted fields keep the adapter's existing defaults: function name and docstring discovery, annotation-based input-schema inference, and generated CLI exposure. Dependency-free inference covers Annotated descriptions and constraints, TypedDict required and optional keys, dataclasses, literals, unions/nullability, fixed and variadic tuples, and typed mapping values. Parameters annotated as Context are excluded from the public input schema and injected by the runner. The one-shot compatibility runner supplies request identity and explicit unavailable capability handles. Persistent brokered workers provide live HTTP, secrets, namespaced state, logging, metrics, progress, and cancellation handles under the provider declaration, deployment policy, actor scopes, and host availability intersection.

Broker capability calls are async so they do not block the provider event loop:

response = await ctx.http.request("GET", "https://api.example.com/data")
secret = await ctx.secrets.get("example-key")
current = await ctx.state.get("counter")
await ctx.state.set("counter", (current or 0) + 1)
await ctx.log.emit("info", "updated", counter=current)
await ctx.metrics.increment("updates")
await ctx.progress.update(1, total=1, message="done")

HTTP request and response bodies are lossless bytes (body_bytes) with base64-encoded transport. Broker policy denials remain typed CapabilityUnavailableError failures instead of being reported as worker crashes.

The experimental componentize preflight statically inspects source and explicit wheel evidence without importing or executing provider code:

from soma_provider import scan_componentize_compatibility

report = scan_componentize_compatibility(
    source,
    filename="provider.py",
    wheel_files=["dependency-1.0.0-py3-none-any.whl"],
)

It fails closed on native extensions, non-pure wheels, dynamic imports, process, thread, socket, native-FFI, and other ambient-authority assumptions. A compatible report means only that the provider is eligible for later isolated build and Wasmtime validation. It does not transpile Python or claim runtime compatibility.

Rust's provider-core manifest and adapter validation remain authoritative. The tests/soma_runner_protocol.py module is also internal: it implements the bounded length-prefixed JSON codec, version negotiation, and feature intersection used by persistent-runner contract fixtures. One-shot remains the default runtime. SOMA_PYTHON_RUNNER_MODE=persistent activates supervised installed-wheel workers for catalog and invocation. Set SOMA_PYTHON_EXECUTION_PROFILE=brokered with explicit broker policy to activate the fail-closed capability and containment boundary.

pyproject.toml defines the soma-provider 0.2.x maturin mixed package for Python 3.11 and newer. The pure-Python facade remains usable without a native extension; built wheels include the private soma_provider._soma_native abi3 module for provider-core manifest validation and an SDK/native version check. uv.lock pins development/build resolution, and the package smoke test builds and installs the wheel in isolation. The repository now enforces an independent soma-provider-v* tag and version parity across Python and Cargo metadata; trusted PyPI publication, signing, provenance, and release execution remain separate milestones. Replacing a Python implementation with WASM should preserve the provider contract rather than attempt to transpile arbitrary Python code. The canonical delivery status and remaining milestones live in docs/specs/python-provider-platform.md.

Project links

Data verified by PyPI on Aug 2, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for jmagar from gravatar.com jmagar

Credits

Author: Dinglebear AI

GitHub Statistics

Data verified by PyPI on Aug 2, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

soma providers mcp tools

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

soma_provider-0.2.0-cp311-abi3-win_amd64.whl (2.4 MB view details)

Uploaded CPython 3.11+Windows x86-64

soma_provider-0.2.0-cp311-abi3-musllinux_1_2_x86_64.whl (2.9 MB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ x86-64

soma_provider-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl (2.8 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.28+ x86-64

soma_provider-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl (2.5 MB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file soma_provider-0.2.0-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for soma_provider-0.2.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 059f37d43e8f798c1f9a27a417bb5077d147c3ecd29bb527869e4eee567e9a5e
MD5 78a749ebf362948539be4d061f9bf8c2
BLAKE2b-256 0b07f5252bc7a6cda5abd9af49c584793c775c6e80835912c7fcafa9aaacfed6

See more details on using hashes here.

Provenance

The following attestation bundles were made for soma_provider-0.2.0-cp311-abi3-win_amd64.whl:

Publisher: python-wheels.yml on dinglebear-ai/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file soma_provider-0.2.0-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for soma_provider-0.2.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 230b94b69637e49eda8b0e3dacc64b8d4facdf23b43cfdd8332c4bc007cb3387
MD5 82bddd48697cb47e458db961fd17cc8d
BLAKE2b-256 4779ae3df9218cd87fa465b504af40ffa6a3c3beceb510fb344d90b29dffb76a

See more details on using hashes here.

Provenance

The following attestation bundles were made for soma_provider-0.2.0-cp311-abi3-musllinux_1_2_x86_64.whl:

Publisher: python-wheels.yml on dinglebear-ai/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file soma_provider-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for soma_provider-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 0da79e3d58e4bfad0e7a01e7c7989275b355d210331f0f53bb2b1d13b18fd32e
MD5 a29254ae01e9694ef31ebf769182d39f
BLAKE2b-256 2781961d098f8ef90135baed0f1d81bc36321a6348492995fd08ad73c3582047

See more details on using hashes here.

Provenance

The following attestation bundles were made for soma_provider-0.2.0-cp311-abi3-manylinux_2_28_x86_64.whl:

Publisher: python-wheels.yml on dinglebear-ai/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file soma_provider-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for soma_provider-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b0608bb0d09f22a70b4a502285185f713a6acb1928b2726d7f88c00c807e311e
MD5 947333099d730ca968350996732bf3d8
BLAKE2b-256 061f1063ade6190540d89d59c3d57faaeab9094cfde8309493b85f73f36e9b13

See more details on using hashes here.

Provenance

The following attestation bundles were made for soma_provider-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: python-wheels.yml on dinglebear-ai/soma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page