Pipelex: Declarative AI Methods in .mthds Files

The problem Pipelex solves: LLM steps that nobody can reproduce

A multi-step LLM feature usually starts as a Python function that calls a model, parses the string it gets back, feeds that into a second call, and so on. Six weeks later nobody can say which step produced which field, and swapping the model means rewriting the parsing. Pipelex's answer is to move the procedure out of Python and into a .mthds file, which the README describes as "a reusable, typed AI procedure" that Pipelex executes.

The audience is narrower than the tagline suggests. The README frames the project as a "Devtool for agents and mere humans", and the primary quick start is not a terminal at all: it is a prompt you paste into Claude Code, followed by /mthds-build and /mthds-run. That tells you who the maintainers expect to arrive first, someone using a coding agent who wants the agent to produce a pipeline rather than a pile of glue code. The secondary audience is the engineer who wants the same artifact checked into a repository and run from a terminal.

The pain it targets is real: the orchestration logic is the part of an LLM feature that is hardest to review, because it is usually expressed as imperative code with implicit contracts between steps. Whether a DSL fixes that depends on whether your team will actually read .mthds files.

How a method is structured: pipes, concepts and typed inputs

The unit of work is a pipe, declared as a TOML table. The README's first example is a single PipeLLM that takes an article and an audience and returns text:

[pipe.summarize_article]
type    = "PipeLLM"
inputs  = { article = "Text", audience = "Text" }
output  = "Text"
prompt  = "Summarize $article in three bullet points for $audience."

Inputs and outputs are named and typed, and the prompt references them with a $ prefix. That is the whole contract for a leaf step: what goes in, what comes out, and the instruction that connects them. Model routing, structured output parsing and orchestration are handled by Pipelex rather than by the method author, according to the README.

Composition happens through a different pipe type. The CV screening example uses a PipeSequence with an inputs map, an output type of CandidateMatch[], and a steps list in which one step is a plain call and the next is a batch over the CV documents:

[pipe.batch_analyze_cvs_for_job_offer]
type = "PipeSequence"
inputs = { cvs = "Document[]", job_offer_pdf = "Document" }
output = "CandidateMatch[]"
steps = [
  { pipe = "prepare_job_offer", result = "job_requirements" },
  { pipe = "process_cv", batch_over = "cvs", batch_as = "cv_pdf", result = "match_analyses" },
]

The batch_over and batch_as keys are the interesting part: iteration over a collection is declared rather than written as a loop, and each step names the variable its result lands in. The custom types come from concept blocks, which carry a description plus a structure with per-field types, descriptions and a required flag. The CandidateProfile concept in the README declares skills, experience, education and achievements, with the first three marked required. Those concept descriptions are not decoration; they are what the model is told to produce.

The dependency list confirms the shape of the runtime: networkx for graph work, pydantic for the typed models, instructor for structured extraction, portkey-ai alongside openai for provider routing, and OpenTelemetry packages for tracing.

Installing Pipelex and building a first method

There are three documented install paths, and they are not equivalent. The agent path installs a Node package globally and wires a plugin into Claude Code. The terminal path does the same npm install, then bootstraps the agent and initialises Pipelex. The standalone path skips Node entirely and installs the CLI as a Python tool with uv.

For a plain terminal setup, the README gives this sequence:

npm install -g mthds
mthds-agent bootstrap
pipelex init

If you only want the CLI and have no interest in the agent integration, the README offers the uv route instead:

uv tool install pipelex
pipelex init

After either route, the README says to verify the setup with pipelex doctor. That command is the one to run before you write any method, because it is the only documented way to confirm that the install, the configuration and your provider credentials line up.

Configuration is where most first runs will stall. The README lists three options. Pipelex Gateway is the recommended one: you get a key from app.pipelex.com, put PIPELEX_GATEWAY_API_KEY in ~/.pipelex/.env, and run pipelex init again. The bring-your-own-keys option expects provider keys such as OPENAI_API_KEY or ANTHROPIC_API_KEY in the same file, mirroring the names in .env.example. The local option covers Ollama, vLLM, LM Studio and llama.cpp, and the README states that no API keys are required for those.

One caveat worth knowing before you paste a key: .env.example describes the Pipelex Manifold variables as a service "currently in private beta", and says the backend ships disabled in backends.toml. Filling in PIPELEX_MANIFOLD_ENDPOINT and PIPELEX_MANIFOLD_API_KEY without enabling the backend there does nothing. The repository layout also shows a .pipelex/ directory in the project root, so there is project-level configuration beyond the home-directory .env.

Where Pipelex gets in the way

The licence is the first constraint, and it is easy to miss because the repository metadata reports it as NOASSERTION while the README badge and pyproject.toml both say Elastic-2.0. Elastic License 2.0 is not an OSI-approved open source licence. If your organisation has a policy against source-available licences, or if you intend to offer the pipeline itself as a hosted service, that policy question has to be settled before you write a single .mthds file. The repository also carries a CLA.md and a subject_grants.toml, which is consistent with a project that expects to manage contribution rights deliberately.

The runtime floor is Python 3.11 with an upper bound below 3.15, per pyproject.toml. That is a wide window, but it is still a constraint if you are pinned to an older interpreter.

Agent integration is the recommended path and also the most fragile one. It depends on npm, on a global install of mthds, on a plugin marketplace, and on a /reload-plugins step in Claude Code. The Codex variant is a different set of commands with a restart and a /plugins step. None of that is wrong, but it means the recommended experience has more moving parts than the uv install, and those parts move on someone else's release schedule.

The documentation is also uneven in places. The README shows the full CV screening method only partially, with the rest behind a collapsed details block, and it does not document rollback or how to pin a method to a specific model version. If you need reproducible output across model upgrades, the README does not tell you how to get it.

Pipelex against LangChain and plain Python

The obvious comparison is LangChain, and the difference is where the logic lives. In LangChain the pipeline is Python: you compose runnables, chains or graphs in code, and the structure is whatever your program does at runtime. In Pipelex the pipeline is data: a .mthds file that a separate runtime reads and executes. That makes the method diffable and reviewable by someone who does not read Python, and it makes the same file portable across the 60+ models the README claims routing support for.

The cost is expressiveness. Anything the DSL does not model has to go around it, and you have given up the ability to drop into arbitrary Python mid-pipeline. A LangChain user who needs a custom retriever, a database write between two steps, or a hand-rolled retry with backoff will find the declarative surface narrower than the code they are used to writing.

The second alternative is not a framework at all: a plain Python script with the provider SDK and pydantic. That is genuinely sufficient for a two-step summarise-then-classify job, and it has no licence question attached. Pipelex starts to pay for itself when the procedure has several steps, batch iteration, and more than one person who needs to understand it. Below that threshold it is overhead.

A third point of comparison sits inside the repository itself: the mthds package is a pinned dependency (mthds==0.14.0), and the README links to mthds.sh as a hub. The format is presented as an open standard that Pipelex executes, which means the interesting question for a long-lived project is whether other runtimes adopt it.

Maintenance, upgrades and what the release cadence implies

The last push to the repository was on 2026-09-14, and the most recent release, v0.58.0, is dated the same day. The two prior releases, v0.57.0 and v0.56.0, landed on 2026-09-07 and 2026-09-03. That is a fast cadence: three minor releases in under two weeks, and a version number that has already passed fifty-eight. The project is not archived.

That cadence is a real cost, not just a sign of health. Minor versions arriving every few days means the surface you build against can shift while you are still writing your first methods. The Makefile contains a telling comment about the TypeScript emission gates: the prettier version is pinned exactly at 3.9.6 because the emitter in pipelex/codegen/emitters/ts_zod.py emits the bytes that specific prettier leaves alone, and moving the pin is described as an emitter change rather than a dependency bump. That is the maintainers being careful, but it also tells you that some parts of this project are tightly coupled to exact tool versions, and upgrades there are not mechanical.

For an adopter, the practical implication is to pin pipelex in your own environment rather than tracking latest, and to read the changelog before bumping. The repository keeps a CHANGELOG.md and the README links to a changelog page, so the information exists. The dependency list is long, spanning OpenTelemetry, pydantic, portkey-ai, openai, instructor and networkx, so a bump of Pipelex can pull a wide transitive set.

On licence implications: Elastic-2.0 is a source-available licence with use restrictions, and the repository separately includes a CLA. Whether that combination works for your product is a question for your legal team, not for this article.

Editorial conclusion

Adopt Pipelex if you have a repeatable multi-step LLM procedure that keeps drifting between runs and you want it written down as a typed .mthds file rather than buried in Python. Do not adopt it if you need a permissive OSI licence, if your workflow is a single prompt call, or if you cannot accept a Python 3.11 to 3.14 runtime. Verify first: run pipelex doctor after pipelex init, confirm which backend your provider keys resolve to in backends.toml, and read the LICENSE file before you build anything on top of it.

Frequently asked questions

Official sources

1. Issues
2. Pipelex/pipelex on GitHub
3. Project website
4. README
5. Releases