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 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; 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. 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.
Related packages
Metadata
Release files for mthds 0.26.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 | Provenance | Actions |
|---|---|---|---|---|
| mthds-0.26.0.tar.gz | 525.2 kB | With provenance | Details for mthds-0.26.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mthds-0.26.0-py3-none-any.whl | Python 3 | none | any | Details for mthds-0.26.0-py3-none-any.whl |
Total release size: 735.9 kB
Release files / mthds-0.26.0.tar.gz
| Download URL | mthds-0.26.0.tar.gz |
|---|---|
| Size | 525.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bf7e0c7e6570b10a681800c626aefffd0b47617d9516f84716d192d66100204e
|
|
BLAKE2b-256 checksum How to use checksums |
2f260173b04ac75c4ac1fb10d795a705a3d992ff98890883ba1ba17003b7cfa4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 29, 2026.
Transparency logRelease files / mthds-0.26.0-py3-none-any.whl
| Download URL | mthds-0.26.0-py3-none-any.whl |
|---|---|
| Size | 210.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63963aebc2a4dd8705a0ff0aa4f91c1f9ed621112b4b5d5c880e2e6531decee5
|
|
BLAKE2b-256 checksum How to use checksums |
bd0916beda6f93ed401dc70745bd1ae0c4eba396d04c04ea476f8c6297b9d36c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 29, 2026.
Transparency logSecurity for mthds 0.26.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.
Attestation for mthds-0.26.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 29, 2026.
Transparency logA 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.