mthds 0.4.1

The Python interface for methods — base structures for structured outputs and the base runner for executing methods via API.

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.

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() resolves credentials 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_API_URL	API base URL — any MTHDS Protocol server	https://api.pipelex.com

The reference server is Pipelex (https://api.pipelex.com) — get a key at app.pipelex.com, or point MTHDS_API_URL at your own MTHDS-Protocol server. You can also pass api_token / api_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.