Metadata-Version: 2.4
Name: mthds
Version: 0.4.0
Summary: The Python interface for methods — base structures for structured outputs and the base runner for executing methods via API.
Project-URL: Homepage, https://mthds.ai
Project-URL: Repository, https://github.com/mthds-ai/mthds
Project-URL: Documentation, https://docs.mthds.ai/
Project-URL: Changelog, https://github.com/mthds-ai/mthds/releases
Author-email: "Evotis S.A.S." <oss@pipelex.com>
Maintainer-email: Pipelex staff <oss@pipelex.com>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: backports-strenum>=1.3.0; python_version < '3.11'
Requires-Dist: httpx<1.0.0,>=0.23.0
Requires-Dist: pydantic<3.0.0,>=2.10.6
Requires-Dist: semantic-version<3.0.0,>=2.10.0
Requires-Dist: tomli<3.0.0,>=2.0.0; python_version < '3.11'
Requires-Dist: tomlkit>=0.12.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy==1.19.1; extra == 'dev'
Requires-Dist: pylint==4.0.4; extra == 'dev'
Requires-Dist: pyright==1.1.408; extra == 'dev'
Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == 'dev'
Requires-Dist: pytest-sugar>=1.0.0; extra == 'dev'
Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
Requires-Dist: ruff==0.14.13; extra == 'dev'
Description-Content-Type: text/markdown

# mthds

The Python implementation of the [MTHDS Protocol](https://mthds.ai) — a typed client for any MTHDS runner, plus the base structures that methods are defined in.

Learn more at [mthds.ai](https://mthds.ai) and browse the Hub at [mthds.sh](https://mthds.sh).

> Looking for the command line? The `mthds` **CLI** ships as the [npm package](https://www.npmjs.com/package/mthds) (mthds-js). This Python package is a **library** — it has no CLI.

## Installation

```bash
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](./docs/runners.md) for the protocol + runners reference.

## Quick start

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

```python
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](https://mthds.ai) server | `https://api.pipelex.com` |

The reference server is **Pipelex** (`https://api.pipelex.com`) — get a key at [app.pipelex.com](https://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`](https://www.npmjs.com/package/mthds) (npm) — the `mthds` CLI (install methods, run, configure) + TypeScript client.
- [Pipelex](https://github.com/Pipelex/pipelex) — the reference full-featured runner.
