Skip to main content

Toolsplice for Python

Native, framework-independent SDK for checked tool handoffs, learning, typed bindings and offline maintenance. 0.0.1, Python 3.11+. No Node, Agno, model-provider or Cloudflare runtime dependency.

This release implements the JavaScript SDK's feature categories. Portable contracts, corrections, shared recordings and learning records use JS wire formats/fingerprints. Generated Python code and project adapters are language-specific. Tests establish the represented cases, not universal equivalence or production readiness.

Install

python -m pip install toolsplice==0.0.1
python -m pip install 'toolsplice[mcp]==0.0.1'       # SDK adapter and proxy transports
python -m pip install 'toolsplice[postgres]==0.0.1'  # Optional database backend
python -m pip install 'toolsplice[http]==0.0.1'      # Optional HTTPX middleware

For local development, install the absolute checkout path to packages/python. Core dependencies: jsonschema, referencing, google-re2 and rfc8785, plus transitive dependencies. RE2/rpds-py use native platform components.

Handoffs

from toolsplice import ToolContract, prepare_splice

source = ToolContract(
    "docs",
    "fetch",
    {"type": "object"},
    {
        "type": "object",
        "properties": {"markdown": {"type": "string"}},
        "required": ["markdown"],
    },
)
target = ToolContract(
    "files",
    "save",
    {
        "type": "object",
        "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
        "required": ["path", "content"],
    },
    {"type": "boolean"},
)
plan = {
    "format": "toolsplice-splice",
    "formatVersion": 1,
    "source": {"server": "docs", "tool": "fetch", "path": "/markdown"},
    "target": {"server": "files", "tool": "save"},
    "contextSchema": {
        "type": "object",
        "properties": {"path": {"type": "string"}},
        "required": ["path"],
    },
    "bindings": [
        {"to": "/content", "from": ""},
        {"to": "/path", "fromContext": "/path"},
    ],
}
handoff = prepare_splice(plan, source, target)
print(handoff.report)  # ready / review / blocked; assumptions and fingerprints

# Application supplies async source_caller(request) and target_caller(request).
# request: {"name": "...", "arguments": {...}}
# Return {"structuredContent": json_value}, or an MCP content/result envelope.


async def save_document(url: str) -> dict:
    """Fetch and save a document; register this ordinary function in any framework."""
    results = await handoff.run(
        source_caller,
        target_caller,
        {"url": url},
        context={"path": "application-owned-destination.md"},
        allow_review=True,
        timeout=30,
    )
    return {"saved": len(results)}

prepare_splice also accepts shared callshape-contract snapshots. create_contract_from_catalog(server, catalog, tools=[...]) builds them from saved catalogs; applications own pagination/identity. ToolContract.from_catalog selects one tool.

Static preflight conservatively checks required/optional/missing paths, nullability, unions, local references, mapped argument types, literals and bounds. allow_review permits review only; blocked setup and runtime guards remain enforced. Consumer source.valueSchema is an additional requirement, never an implicit replacement for the server declaration.

map_output(decoded_fixture, context=...) checks without tools. run validates source input/context before the source call, known source output, source.expect, selection/optional JSON parsing, consumer schema, fanout cap, every destination argument and target.uniqueBy before any destination dispatch. Destination calls are sequential; returned outputs and aggregate result bytes are checked afterward. Plans retain shared v1 camelCase fields; Python APIs use snake_case.

Execution and MCP

from toolsplice.mcp import mcp_caller

source_caller = mcp_caller(source_session)
target_caller = mcp_caller(target_session)

Sessions are initialized/closed by the application. Core imports do not import MCP. Helpers include create_tool_caller, invoke_tool, tool_functions, BindingCallOptions, and create_contract_caller. Guards preserve successful raw results and leave normal MCP error/unfinished-result handling to the caller. Unknown tools reject before dispatch.

run(timeout=...) bounds the awaited workflow; call_timeout defaults to 120 seconds per call. Request-scoped on_progress reaches the SDK adapter. Normalize multiple internal progress streams in the application when exposing one outer tool. Synchronous work/schema checks cannot be preempted by asyncio.

SpliceError exposes stage, completed_targets and path-only issues; explain_error adds endpoints, row/binding origins and source selection. SpliceCancelled is an asyncio cancellation with stage/count. Counts mean acknowledged/collected results, not committed writes. Effects can occur before cancellation, timeout, output or size rejection. No retry, rollback, exactly-once execution or durable resume is promised.

Shared recording, replay and corrections

from toolsplice import create_splice_recorder, replay_splice_recording

recorder = create_splice_recorder(
    plan, source, target, capture="payloads", redact_keys=["customerEmail"]
)
await recorder.run(
    source_caller,
    target_caller,
    {"url": url},
    context={"path": path},
    allow_review=True,
)
recording = recorder.snapshot()
report = await replay_splice_recording(recording)
upgrade = await replay_splice_recording(recording, target_contract=candidate_target)

The factory creates toolsplice-recording v1, shared with JS. Replay verifies artifact/plan/contract fingerprints, exact saved call order/arguments and expected outcome. Candidate checks report passed/failed/inconclusive plus diffs/fingerprints. Failed/cancelled/transport-failed baselines cannot establish upgrade success. Replay accepts no live callers; it checks captured data, not live behavior or effects. Cancellation/timeout timing is not reproduced.

Metadata-only capture is the default; payloads are explicit and bounded. Common credential keys and configured keys/secret substrings are redacted with exact paths. Every redacted path needs a private restoration; extra paths are rejected. Redaction is not anonymization and fingerprints are not authentication. Capture failures never retry/change forwarding; snapshot/storage remain separately fallible. Applications explicitly choose where to persist recordings. Preview Recorder/replay remain for v0.1 native artifacts; use the factory above for shared artifacts. replay dispatches shared artifacts too.

parse_contract_correction/apply_contract_correction validate shared whole-schema replacements pinned to the original fingerprint, reason and positive/negative fixtures per changed tool/side. Originals remain intact, corrected metadata is fingerprinted and outputs labelled corrected. No correction automatically activates after guard failure.

Typed code and projects

emit_splice_module generates an executable Python adapter with create_splice; emit_bindings/emit_module generate callable tool methods; schema_to_python emits declarations. TypedDict inputs/outputs and required context support static checking. Untrusted names and JSON literals are quoted safely. Python typing differs from TypeScript; runtime guards remain authoritative.

initialize_splice_project creates a new private fixed-file directory from synthetic data or a successful shared recording. check_splice_project validates inputs/fixtures/mappings and adapter freshness without calls. Existing directories/files are refused. Python projects use adapter.py; JS projects use adapter.ts; generated-language files/freshness checks are not interchangeable. Restored project fixtures can contain confidential values while the retained recording remains redacted.

Learning and storage

from toolsplice import ShapeStore, record_tool_list, record_call, extract

store = ShapeStore("/application-owned-volume/toolsplice")


def update(record):
    record_tool_list(record, catalog["tools"])
    record_call(record, "fetch", extract(raw_result))


store.transact("installation-account-name", update)

File operations are synchronous; LearningStore permits sync/async backends and toolsplice.store.await_maybe supports both. New directories/files use 0700/0600. Atomic replacement, shared writer locks and stale-save checks protect updates. Synchronous mutators are never retried after entry. Existing locks are not automatically reclaimed. Refresh/remove respect another process's forget; diagnostics inspect lock/temp ownership without returned values. Close watchers when finished.

from toolsplice.postgres import PostgresShapeStore

store = PostgresShapeStore(database_url, namespace="project-tenant", migrate=False)
await store.transact("installation-account-name", update)
await store.close()

The optional async PostgreSQL backend shares JS public.mcp_shape_* tables, migration v1 and advisory-lock identities, including absent-row/delete locks. migrate=True bootstraps; use False with a restricted runtime role after migration. Namespaces partition records, not authorization. No cache/file fallback or callback retry follows a DB failure. The store owns its pool unless explicitly supplied by the application.

Learning includes bounded statistics, safe/all/none examples (default none), sensitive-key suppression, embedded JSON, maps/recursive trees, merges, drift revisions, structural declaration diagnostics, doctor reports and export freshness. Field names/counts/nonsensitive numeric bounds can persist under none; it is not anonymization. create_contract_snapshot exports learned portable contracts.

Proxy and HTTP

create_proxy(initialized_session, store=store, server_name=...) gives list_tools/call_tool methods. Description/none modes preserve results; learning failures stay fail-open. Notifications are coalesced; ordinary repeated observations do not churn descriptions. Experimental enrich="schema" can advertise lenient schemas and attach compatible structured content when explicitly requested.

For transparent wire forwarding, pass (upstream_read, upstream_write) and call proxy.run(downstream_read, downstream_write). Non-tool MCP requests, resources and prompts pass through too. The CLI supports stdio/Streamable HTTP upstreams. Cancellation is forwarded; deadline failure reports uncertainty and suppresses late duplicate results. proxy.close() does not close application-owned stores/sessions.

toolsplice.http.LearningTransport wraps HTTPX with explicit client/endpoint/principal identity. It observes JSON/SSE without a second fetch; bounded finite JSON catalogs can be enriched. Late/oversized bodies pass through, SSE bytes remain unchanged, and on_changed is a local cache-refresh signal. SDKs retain authentication and protocol negotiation. This supplies the JS v2 fetch-adapter role without requiring a Python SDK 2.x.

CLI

python -m toolsplice init ./new-handoff
python -m toolsplice project ./new-handoff --allow-review --json
python -m toolsplice replay recording.json --target-contract next.json --json
python -m toolsplice proxy --store ./private-learning --name installation -- python server.py

Installed binaries: toolsplice, callshape, mcp-shape. Commands: splice, replay, correct, init/project, proxy, config wrapping, explicit/read-only-hint probe, doctor, show/list, schema, snapshot/check, forget, storage diagnostics and emit-py. Artifact outputs refuse existing files. Exit 2 denotes blocked/unaccepted review, regression or candidate incompatibility; invalid configuration/artifacts exit 1. MCP stdout stays protocol-only in proxy mode.

--store selects a directory (default .mcp-shape relative to cwd). --database-env NAME, --namespace, --no-migrate, --database-timeout select/control PostgreSQL. Artifact commands supplied explicit contracts/catalogs do not initialize a store or contact providers. --source-contract, --target-contract, catalog equivalents, --fixture, --context, --summary, --allow-review and --out support offline handoff checks/generation.

Bounds and validation

Runtime guards support Draft 7 and 2020-12 (default), local references/recursive types, restricted ASCII RE2 patterns, unions/conditionals/tuples/dependencies and supported unevaluated assertions. External/dynamic refs, nested resources/dialects, patternProperties, ambiguous Draft 7 ref siblings and unknown assertions reject setup. Root $id is an annotation; formats/content annotations are not assertions. uniqueItems requires maxItems<=1000, matching JS. No schema is downloaded.

Shared JSON is finite, UTF-8 encodable, string-keyed and uses safe integers. Budgets reject cycles/oversized/deep data. Python integers are not silently rounded into JS numbers. No semantic matching, factual correctness, token savings, production availability, independent adoption or universal schema equivalence follows from passing tests.

python -m pip install -e './packages/python[mcp,http,postgres,test]'
python -m pytest packages/python/tests
python packages/python/examples/composite.py
python -m build packages/python

DB tests require TOOLSPLICE_PG_BIN and create only a disposable private loopback cluster. Cross-language conformance needs this built checkout and Node for testing only. Core tests/demo need no provider account or model call.

Metadata

Release files for toolsplice 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for toolsplice 0.0.1
File Size Uploaded Provenance Actions
toolsplice-0.0.1.tar.gz 94.0 kB Without provenance Details for toolsplice-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for toolsplice 0.0.1
File Interpreter ABI Platform Actions
toolsplice-0.0.1-py3-none-any.whl Python 3 none any Details for toolsplice-0.0.1-py3-none-any.whl

Total release size: 173.2 kB

Release files / toolsplice-0.0.1.tar.gz

Download URL toolsplice-0.0.1.tar.gz
Size 94.0 kB
Tags Source
SHA-256 checksum
How to use checksums
3b61381e3452fa4ae0a0ff3b137a8dc313f38afb613f22554ab3024fd40e3a97
BLAKE2b-256 checksum
How to use checksums
24b84b677e88c55adef87dd8c7b7382dd365a2cd4b9fe271042b723150a57e13
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Release files / toolsplice-0.0.1-py3-none-any.whl

Download URL toolsplice-0.0.1-py3-none-any.whl
Size 79.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c3f041eb961ebe1ebc89bdd4311350ac30eb8ca2a504448014b42761f29eeb61
BLAKE2b-256 checksum
How to use checksums
95166abe2428852edbaa72a5518793604bf8e345dfcedb9c6c9833455143ea48
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.6

Security for toolsplice 0.0.1

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