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
mthdsCLI 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); 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; andPipelexRunner(mthds.runners.pipelex.runner), which shells out to a locally installedpipelexCLI. - Package management (
mthds.package) — read, lock, and resolveMETHODS.tomlmanifests.
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
1 maintainer
Release files for mthds 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mthds-0.16.0.tar.gz | 259.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mthds-0.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 363.2 kB
Release files / mthds-0.16.0.tar.gz
| Download URL | mthds-0.16.0.tar.gz |
|---|---|
| Size | 259.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc8f54bc76c9ed13273e7cd2e1c66767e5478fc3640a26481bf099451d56aa29
|
|
BLAKE2b-256 checksum How to use checksums |
25034aca733536f741f741d0cba3ae3d23dfd56f691c53a0d7e3e7baea371585
|
| 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 Sep 23, 2026.
Transparency logRelease files / mthds-0.16.0-py3-none-any.whl
| Download URL | mthds-0.16.0-py3-none-any.whl |
|---|---|
| Size | 103.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
67468669451278e8c17409c5fed60eafab8453fd5cd92f333d788b21f7500ebe
|
|
BLAKE2b-256 checksum How to use checksums |
d000a80f90f0ed7ddff9886f925fbb8dd0061ec0b0e1af49901971664f1a3e12
|
| 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 Sep 23, 2026.
Transparency log
