pipelex - Moses Yebei

The Problem

Teams building AI workflows face a gap between ad-hoc scripting and heavyweight orchestration frameworks. Prompt logic gets buried in Python, model calls are hard to swap, and outputs lack structure. Pipelex addresses this with a declarative .mthds file format where a pipeline step is a typed TOML block, not imperative code.

What This Does

Pipelex is a Python package (1288 files) that executes declarative AI workflows. A method file declares typed pipes—PipeLLM, PipeExtract, PipeSearch—that route to 60+ models via configured backends in .pipelex/inference/backends/*.toml. The system handles structured output parsing, pipeline orchestration, and validation.

The project splits into a core runtime (pipelex/core/, pipelex/pipeline/) and a CLI (pipelex/cli/). It includes 709 test files and extensive docs (145 files) covering cookbooks, configuration, and advanced injection patterns.

How It Is Wired

Execution starts at the CLI entry points: pipelex/cli/commands/build/app.py for compilation, pipelex/cli/agent_cli/commands/run/app.py for execution. The import graph shows 1259 internal modules with 5521 edges. The hub is pipelex/hub (174 modules import it, 31 it imports) and pipelex/__init__.py (187 dependents). These are the highest-blast-radius files—changes ripple across the entire codebase.

The runtime routes through pipelex/core/concepts/ for type definitions and pipelex/core/pipes/pipe_abstract.py (647 lines) for pipe behavior. The pipelex/hub module is the central registry that everything depends on, making it the bottleneck for any architectural change. Two modules sit in a circular import cycle involving pipelex/core/stuffs/stuff.py.

The system touches external services through inference backends (OpenAI, Anthropic, etc.), file I/O for documents, and optional telemetry via pipelex/telemetry.toml. Network calls happen through the configured model providers.

How To Use It

# Clone and install
git clone https://github.com/moses-y/pipelex
cd pipelex
pip install -e .  # or use uv

# Configure providers in .pipelex/inference/backends/*.toml
# Set API keys per the .env.example file

# Run a method
pipelex run path/to/method.mthds

The README documents a Claude Code setup: npm install -g mthds && mthds-agent bootstrap. Configuration lives in .pipelex/pipelex.toml and backend-specific TOML files under .pipelex/inference/backends/.

Real-World Use

A content team builds a blog pipeline: PipeLLM for drafting, PipeExtract for metadata, PipeSearch for research. Each step is a typed block in a .mthds file, swapable between OpenAI and Anthropic by changing one config line. The docs/cookbook/blog-article-generator.md shows this exact pattern.

Code Health & Issues

Static analysis found 311 findings (68 high, 240 medium, 3 low). Key issues:

High - Deep nesting in pipelex/core/stuffs/stuff_factory.py, pipelex/core/memory/working_memory.py, pipelex/core/concepts/concept_factory.py (max depth 8) - hard to follow control flow
High - Hub modules in pipelex/__init__.py, pipelex/hub.py, pipelex/types.py - 187 modules depend on pipelex/__init__.py; high churn risk
High - Import cycle in pipelex/core/stuffs/stuff.py - circular dependency
Medium - Broad exception handling in pipelex/tools/misc/string_utils.py, json_utils.py
Medium - Oversized file in pipelex/core/pipes/pipe_abstract.py (647 lines)

SDLC gaps: no lockfile (non-reproducible builds), 8 dependencies behind major versions (including openai 2 majors behind), and 10.4MB GIF committed to the repo. CI uses GitHub Actions with 17 workflows but lacks least-privilege token permissions on 2 workflows.

The Bottom Line

Pipelex is a serious, well-documented attempt at declarative AI workflows with real typing and model abstraction. The hub architecture and deep nesting will make it painful to modify at scale, and the missing lockfile complicates deployment. Worth evaluating if you need portable, typed AI method definitions across multiple model providers.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,696 files

Python1288
Markdown157
TOML81
YAML23
JSON15
HTML4

ReactFlaskTransformers

Module dependencies

The 10 most depended-upon modules of 1,259, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_pipelex___init__["__init__"] n1_pipelex_hub["hub"] n2_pipelex_types["types"] n3_ipelex_pipeline_job_metadata["job_metadata"] n4_lex_core_stuffs_text_content["text_content"] n5_pipelex_cogt_exceptions["exceptions"] n6_ncepts_native_concept_native["concept_native"] n7_re_stuffs_structured_content["structured_content"] n8__tools_typing_pydantic_utils["pydantic_utils"] n9_ore_concepts_concept_factory["concept_factory"] n5_pipelex_cogt_exceptions --> n2_pipelex_types n9_ore_concepts_concept_factory --> n6_ncepts_native_concept_native n9_ore_concepts_concept_factory --> n4_lex_core_stuffs_text_content n9_ore_concepts_concept_factory --> n2_pipelex_types n6_ncepts_native_concept_native --> n4_lex_core_stuffs_text_content n6_ncepts_native_concept_native --> n2_pipelex_types n7_re_stuffs_structured_content --> n8__tools_typing_pydantic_utils n1_pipelex_hub --> n0_pipelex___init__ n1_pipelex_hub --> n6_ncepts_native_concept_native n3_ipelex_pipeline_job_metadata --> n2_pipelex_types n8__tools_typing_pydantic_utils --> n2_pipelex_types

Dependencies

8 of 33 declared dependencies are a major version behind. Resolved 33 of 33 against the registry.

Package	Declared	Latest	Behind
`aiofiles`	>=23.2.1	25.1.0	2 major
`openai`	>=1.108.1	3.1.0	2 major
`rich`	>=13.8.1	15.0.0	2 major
`pillow`	>=11.2.1	12.3.0	1 major
`polyfactory`	>=2.21.0	3.3.0	1 major
`posthog`	>=6.7.0	7.39.1	1 major
`pypdfium2`	>=4.30.0,!=4.30.1,<5.0.0	5.13.0	1 major
`reportlab`	>=4.0,<5	5.0.0	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds package.json

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

medium4

low1

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/changelog-check.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium2 occurrences

.github/assets/pipelex-tutorial-v2.gif

2 blobs over 5MB: pipelex-tutorial-v2.gif 10.4MB, illustrated_train_article.pdf 6.2MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/deploy-docs.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/changelog-check.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.