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 five-route interface every runner implements (execute, start, validate, models, version); the wire models (RunResult, ModelDeck, ValidationReport, VersionInfo); and the domain shapes methods are built from (concept, stuff, working_memory, pipe_output, pipeline_inputs).
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.

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.

Related packages

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

Release files for mthds 0.14.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.14.0
File	Size	Uploaded
mthds-0.14.0.tar.gz	221.2 kB	Sep 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mthds 0.14.0
File	Interpreter	ABI	Platform	Reset
mthds-0.14.0-py3-none-any.whl 87.2 kB Sep 6, 2026	Python 3	none	any	Details

Total release size: 308.4 kB

Release files / mthds-0.14.0.tar.gz

Download URL	mthds-0.14.0.tar.gz
Size	221.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`d2b4a9cd064004dfd5b802bb71c9894601fba9e598426f96e4bede16d52c3900`
BLAKE2b-256 checksum How to use checksums	`92594ca9539571a2030f9427aeddb01bc334910953ebdfa4ab7db2051a6b8ae7`
Upload date	Sep 6, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mthds-ai/mthds-python
Publishing commit: github.com/mthds-ai/mthds-python/tree/8da87c60902a99820a13720f9532fd4b4b1841d9

Workflow

Publishing configuration: github.com/mthds-ai/mthds-python/blob/8da87c60902a99820a13720f9532fd4b4b1841d9/.github/workflows/publish.yml
Publishing logs: github.com/mthds-ai/mthds-python/actions/runs/34061965842/attempts/1

Artifact

Subject: mthds-0.14.0.tar.gz
SHA-256 checksum: d2b4a9cd064004dfd5b802bb71c9894601fba9e598426f96e4bede16d52c3900 Verifying attestations

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

Download URL	mthds-0.14.0-py3-none-any.whl
Size	87.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`59a706205b6e6df47345caac01038588d21ab9e9c246afc765ee50b5f27f05a8`
BLAKE2b-256 checksum How to use checksums	`280b32908eeed33396c5aafd4bcb2a1adc38d0ab8d85c2fde3af0bf4c2f73745`
Upload date	Sep 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/mthds-ai/mthds-python
Publishing commit: github.com/mthds-ai/mthds-python/tree/8da87c60902a99820a13720f9532fd4b4b1841d9

Workflow

Publishing configuration: github.com/mthds-ai/mthds-python/blob/8da87c60902a99820a13720f9532fd4b4b1841d9/.github/workflows/publish.yml
Publishing logs: github.com/mthds-ai/mthds-python/actions/runs/34061965842/attempts/1

Artifact

Subject: mthds-0.14.0-py3-none-any.whl
SHA-256 checksum: 59a706205b6e6df47345caac01038588d21ab9e9c246afc765ee50b5f27f05a8 Verifying attestations