Skip to main content

mthds

The Python implementation of the MTHDS Protocol — a typed client for any MTHDS runner, plus the base structures that methods are defined in.

Learn more at mthds.ai and browse the Hub at mthds.sh.

Looking for the command line? The mthds CLI ships as the npm package (mthds-js). This Python package is a library — it has no CLI.

Installation

pip install mthds

What's in the box

  • The protocol (mthds.protocol) — MTHDSProtocol, the interface of the required routes every runner implements (execute, start, validate, models, version); the wire models (RunResult, ModelDeck, ValidationReport, VersionInfo); the domain shapes methods are built from (concept, stuff, working_memory, pipe_output, pipeline_inputs); and the catalog serialization of a stored method's source (method_files).
  • Runners (mthds.runners) — MthdsAPIClient (mthds.runners.api.client), the HTTP client for any MTHDS-Protocol server plus the hosted run-lifecycle (polling) extension; and PipelexRunner (mthds.runners.pipelex.runner), which shells out to a locally installed pipelex CLI.
  • Package management (mthds.package) — read, lock, and resolve METHODS.toml manifests.

See docs/runners.md for the protocol + runners reference. See docs/inputs-template.md for the inputs-template projection. See docs/versioning.md for the MTHDS standard and protocol versions this package carries. See docs/method-tree.md for listing a method tree, its digest, file entries and file references.

Quick start

Run a method against any MTHDS-Protocol server with the API runner, MthdsAPIClient:

import asyncio

from mthds.runners.api.client import MthdsAPIClient


async def main() -> None:
    async with MthdsAPIClient() as client:
        # Discovery handshake
        version = await client.version()
        print(version.protocol_version)

        # Run a method and wait for the result — start → poll → result in one call
        result = await client.start_and_wait(pipe_code="my_pipe", inputs={"topic": "owls"})
        print(result.main_stuff)


asyncio.run(main())

execute runs synchronously; start returns immediately with a pipeline_run_id; start_and_wait does the whole async lifecycle in one call. validate, models, and version round out the protocol surface.

Need local execution instead of an API? PipelexRunner (mthds.runners.pipelex.runner) implements the same MTHDSProtocol by shelling out to an installed pipelex CLI — no API key.

Configuration

MthdsAPIClient() reads its config from ~/.mthds/config — the same file the mthds CLI (npm) reads and writes, so configuring either configures both. Environment variables take precedence:

Variable Description Default
MTHDS_API_KEY API authentication key (empty)
MTHDS_BASE_URL API base URL — any MTHDS Protocol server http://localhost:8081

This client targets the open-source pipelex-api runner, so it defaults to a local instance (http://localhost:8081, pipelex-api's default port). Point MTHDS_BASE_URL at any other MTHDS-Protocol server to use it instead. You can also pass api_key / base_url straight to MthdsAPIClient(...).

To set the config from a terminal, use the npm CLI (mthds config set api-key …) or edit ~/.mthds/config directly.

  • mthds (npm) — the mthds CLI (install methods, run, configure) + TypeScript client.
  • Pipelex — the reference full-featured runner.

Metadata

Release files for mthds 0.23.0

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

Source distribution (sdist)

Source distribution for mthds 0.23.0
File Size Uploaded Provenance Actions
mthds-0.23.0.tar.gz 394.4 kB With provenance Details for mthds-0.23.0.tar.gz

Built distribution (wheel)

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

Total release size: 553.9 kB

Release files / mthds-0.23.0.tar.gz

Download URL mthds-0.23.0.tar.gz
Size 394.4 kB
Tags Source
SHA-256 checksum
How to use checksums
a683c9cee742b2e2164c9abac0c934886adf72e48fff4953fb65e5c34ccdfeb2
BLAKE2b-256 checksum
How to use checksums
51c22d70bc3f90c8f3dac25a416992a6e68f8efd7c2af05871c9ab091661ab22
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Release files / mthds-0.23.0-py3-none-any.whl

Download URL mthds-0.23.0-py3-none-any.whl
Size 159.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1f0212d3d673829341b30ca16b0038b67f65aa41b979f30539f8d664c9673ec4
BLAKE2b-256 checksum
How to use checksums
e933d2eb995332b68e256298a3278c20b4460e2e1f2289fa487bd3839a958311
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

Security for mthds 0.23.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mthds-0.23.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 16, 2026.

Transparency log

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.23.0 This release

2 release files Full 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