Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
Pipelex Coding Rules
Codex Cloud Commands
Linting
After making code changes, you must always lint using make agent-check.
make agent-check
# If the current system doesn't have the `make` command,
# lookup the "agent-check" target in the Makefile and run the commands one by one (targets fix-unused-imports fix-keyword-only format lint pyright mypy check-ledger check-keyword-only check-hub-layering check-rich-imports check-actions-allowlist check-log-calls drift-check api-agent-check)
This runs multiple code quality tools:
- Pyright: Static type checking
- Ruff: Fix unused imports, lint, format
- Mypy: Static type checker
- plxt: Format and lint TOML, MTHDS, and PLX files
- Migration ledgers: every checked-in ledger must be legal and replay harmlessly over its reference documents (
make check-ledger, aliascl) - Drift contracts: open code↔docs review obligations fail the gate (note the digest reads the git index, so stage your changes for the check to see them)
- The Pipelex API server's own gate (
make -C api agent-check): the server lives inapi/as a uv workspace member with its own environment, and its checks include the drift of its OpenAPI artifact and of its vendored inference tree
Always fix any issues reported by these tools before proceeding.
Keyword-only arguments check
Non-subject function parameters across pipelex/ source must be keyword-only (a bare * after the subject). The convention is mechanically enforced and already runs as part of make agent-check, but you can invoke it on its own:
make check-keyword-only # alias: make cko — read-only gate; hard-blocks on any violation
make fix-keyword-only # alias: make fko — auto-insert a bare * for mechanically-fixable violations
check-keyword-only owns the pass/fail gate; fix-keyword-only rewrites what it can and reports the shapes it can't fix mechanically (resolve those by hand). See docs/contribute/keyword-only-arguments.md for the full convention.
Cleaning Derived Files
If you need to clean derived files and caches, typically after you erased files or moved tests, the linters can get confused, the pytest collection can be off...
make cleanderived
Running Tests in Codex Cloud
To test everything that can be tested from within the Codex Cloud sandbox, run this:
```bash
make codex-tests
# It's equivalent to running pytest with `-m "(dry_runnable or not inference) and not (pipelex_api or codex_disabled)"`
# If some test fails, re-run it with `-s -vv` to see more details
```
Prerequisites for running command lines: use virtual environment
CRITICAL: Before running any pipelex commands or pytest, you MUST use the appropriate Python virtual environment. The only exceptions are our make commands which already include the env activation.
Call the CLI directly from the virtual environment:
.venv/bin/pytest -s -v -k test_render_jinja2_from_text
.venv/bin/pipelex validate --all
For standard installations, the virtual environment is named .venv. Always check this first. On Windows, the path is .venv\Scripts\ instead of .venv/bin/.
Pipelex Dev CLI (pipelex-dev)
The pipelex-dev CLI provides internal development tools that are not distributed with the package. It is available in the virtual environment.
.venv/bin/pipelex-dev --help
Key commands:
generate-mthds-schema: Regenerate the MTHDS JSON Schema (derived/mthds_schema.json). Run this after modifyingmthds_schema_generator.py..venv/bin/pipelex-dev generate-mthds-schemagenerate-error-registry: Write every file derived from the Pipelex error registry,pipelex/errors/registry/pipelex-error-registry.yaml: its JSON snapshot, its typed codes inpipelex/errors/registry/pipelex_codes.py, and one page per code underdocs/errors/. Run after adding or changing a code in the registry, and after a version bump, since the snapshot carries the version. A source the format's schema, the typed model or the registry's rules refuse writes nothing. Also available asmake generate-error-registry(aliasmake ger). Seedocs/contribute/error-registry.md..venv/bin/pipelex-dev generate-error-registrycheck-error-registry: Check the error registry against the MTHDS standard, and that every file derived from it is whatgenerate-error-registrywrites, without writing anything. Also available asmake check-error-registry(aliasmake cer)..venv/bin/pipelex-dev check-error-registrygenerate-error-identity: Regenerate the committed(error_type, title, type_uri)snapshot of everyPipelexErrorsubclass attests/data/errors/error_identity.txt.error_typeis the bare class name and consumers outside this repo branch on it, so a rename is a silent wire break — the snapshot turns it into a reviewable diff, gated bytests/unit/pipelex/errors/test_error_identity_snapshot.py. Run after adding, renaming or removing an error class. Also available asmake generate-error-identity(aliasmake gei)..venv/bin/pipelex-dev generate-error-identitytrace-input-semantics: Capture harness for the input-schema emission chain — given one or more.mthdsbundles, dumps one artifact per hop (parse blueprint, generated class source, raw pydantic schema, SCHEMA render, wire contract) plus a manifest of each pipe input's wire framing, so a lost or mangled authored fact is localized to exactly one hop. Use when changing the structure blueprint, the structure generator, the schema render, or the contract builder. Seedocs/contribute/trace-input-semantics.md..venv/bin/pipelex-dev trace-input-semantics tests/data/input_semantics/probe_bundle.mthds -o /tmp/probe-tracegenerate-projection-corpus: Write the shared inputs-template projection fixture corpus — the descriptors, the expected fill-in templates in both shapes and both formats, and the record of where the expectation deliberately differs from the engine's own renderer. Sole producer of the capture committed byte-identically inmthds-js/tests/fixtures/protocol/andmthds-python/tests/fixtures/protocol/, which is what pins the TypeScript and Python projections against each other. Seedocs/contribute/generate-projection-corpus.md..venv/bin/pipelex-dev generate-projection-corpus \ tests/data/input_semantics/hinted_bundle.mthds \ tests/data/input_semantics/probe_bundle.mthds \ tests/data/input_semantics/scaffold_bundle.mthds \ tests/data/input_semantics/output_bundle.mthds \ -o /tmp/projection-corpus
Pipelex CLI Commands
To run the Pipelex CLI commands without the logo, you can use the --no-logo flag, this will avoid useless tokens in the console output.
.venv/bin/pipelex --help
.venv/bin/pipelex build --help --no-logo
.venv/bin/pipelex run --help --no-logo
.venv/bin/pipelex validate --help --no-logo
.venv/bin/pipelex doctor --help --no-logo
.venv/bin/pipelex init --help --no-logo
Coding Standards & Best Practices for Python Code
Python Version Compatibility
typestatement (PEP 695) was added in Python 3.12. UseTypeAliasfromtypinginstead.
Variables, loops and indexes
- Variable names should have a minimum length of 3 characters. No exceptions: name your
forloop indexes likeindex_foobar, your exceptionsexcor more specific likevalidation_errorwhen there are several layers of exceptions, and usefor key, value in ...for key/value pairs. - When looping on the keys of a dict, use
for key in the_dictrather thanfor key in the_dict.keys()otherwise you won't pass linting. - Avoid inline for loops, unless it's ultra-simple and holds on oneline.
- If you have a variable that will get its value differently through different code paths, declare it first with a type, e.g.
pipe_code: strbut DO NOT give it a default value likepipe_code: str = ""unless it's really justified. We want the variable to be unbound until all paths are covered, and the linters will help us avoid bugs this way.
Enums and tests
- When defining enums related to string values, always inherit from
StrEnum - When you need the enum value as a string, don't use
str(enum_var)orenum_var.value, just useenum_varitself, that is the point of using StrEnum! - Never test equality to an enum value: use match/case, even to single out 1 case out of 10 cases. To avoid heavy match/case code in awkward places, add @property methods to the enum class such as
is_foobar(). This is to avoid bugs: when new enum values are added we want the linter to complain. Use the|operator to group cases - As our match/case constructs over enums are always exhaustive, NEVER add a default
case _: .... Otherwise, you won't pass linting. - Import
StrEnumdirectly from the stdlib:from enum import StrEnum
Optionals
- Don't write things like
a = b if b else c, writea = b or cinstead.
Filesystem Paths
- Use
pathlib.Pathfor all filesystem paths. Any function parameter, return type, or variable that holds a location of a file or directory on disk must be typedPath, notstr. Convert to/fromstronly at genuine boundaries. - Boundaries where
stris correct (convert at the edge, then work withPathinternally):- CLI argument parsing (typer/click options and arguments arrive as
str). - Config / TOML (de)serialization — Pydantic config fields and
.tomlvalues arestr. - Env-var parsing, e.g. splitting
PIPELEXPATHonos.pathsep. - URIs / URLs — these are not filesystem paths.
importlib.resourcespackage-resource traversables.- Third-party calls whose signature requires
str.
- CLI argument parsing (typer/click options and arguments arrive as
- Prefer
Pathidioms overos.path:base / "sub" / "file.txt"(notos.path.join),.parent(notos.path.dirname),.name(notos.path.basename),.suffix,.stem,.exists(),.is_dir(),.is_file(),.mkdir(parents=True, exist_ok=True)(notos.makedirs),.iterdir()/.rglob(...)(notos.listdir/os.walk),.read_text()/.read_bytes()/.write_text()/.write_bytes()(notopen()),.unlink(). - Watch the semantic shifts when porting
os.pathcode — these are NOT drop-in equivalents:os.path.relpath(p, base)returns a relative path that may walk up with..;Path.relative_to(base)raisesValueErrorwhenpis not underbase. Never swap one for the other blindly.os.path.abspath(p)collapses./..lexically but does not resolve symlinks. No singlePathmethod matches it:Path.resolve()both normalizes..and follows symlinks, whilePath.absolute()only prepends the cwd and normalizes neither (Path("a/../b").absolute()stays<cwd>/a/../b, whereasos.path.abspath("a/../b")is<cwd>/b). Reach forPath.resolve()in the common case; if you genuinely need abspath's no-symlink semantics, normalize explicitly (Path(os.path.normpath(p.absolute()))).
- Logical (non-filesystem) "paths" stay
str. Dotted module/import paths, domain paths, and variable/key paths (variable_path,dotted_path,var_path,key_path, and similar) are identifiers, not locations on disk — keep themstr. This rule is about files and directories, not everything named*_path.
Imports
Imports at the top of the file
- Avoid as much as possible import statements outside of a module's top-level scope.
- Do not import libraries in functions or classes unless in very specific cases, to be discussed with the user, as they would required a
# noqa: ...comment to pass linting - Do not bother with ordering the imports or removing unused imports, our Ruff linter will handle it for us.
if TYPE_CHECKING:blocks must always be the last block in the imports section, placed after all regular imports.- Rich is the standing exception. It is the
cliextra, which a server does not install, so outsidepipelex/cli/it is imported inside the function that renders, afterrequire_rich(...)(pipelex.tools.misc.rich_extra) orrequire_rich_for_rendering()(pipelex.tools.misc.pretty), and a type-only import of it goes underif TYPE_CHECKING:. Such a deferred import needs no suppression comment, andmake check-rich-importsrefuses a module-level one, as well as a module-level import of a CLI module that imports Rich. Seedocs/contribute/rich-imports.md.
Removing unused imports
- To remove unused imports, run
make fix-unused-importsormake fui(shorthand). This is faster and cheaper than rewriting with LLM.
No re-exports in __init__.py
- Do NOT fill
__init__.pyfiles with re-exports. - Always use direct full-path imports everywhere.
Logging and Pretty Printing
- Both
log()andpretty_print()can be imported frompipelexdirectly:from pipelex import log, pretty_print log.info("Hello, world!") - Both have a title arg which is handy when logging/printing objects:
log.verbose("Hello, world!", title="Your first Pipelex log") pretty_print(output_object, title="Your first Pipelex output") - Both handle formatting json using Rich, pretty_print makes it prettier.
- A log message is a fixed sentence with its values in
fields=, never interpolated at INFO and above, and never holding Rich markup:log.warning("A dependency holds no valid bundle", fields={"dependency_alias": alias}). It is one short sentence, subject first, starting with a capital and ending with no period or..., with no backtick and, at INFO and above, no identifier and at most 80 characters; advice rides in auser_actionfield ("Wording a message" indocs/tools/logging.md). A handled exception at WARNING and below rides infields=as**error_fields(exc=exc)(pipelex.tools.log.error_fields), at ERROR asinclude_exception=True, never as{exc}in the text, at any level; an exception logged and then re-raised rides as**error_fields(exc=exc)at every level, its traceback being its catcher's to print, and so do a cleanup's failure while another exception propagates, whose traceback would chain the primary's text, and a swallowed pydanticValidationError, whose traceback quotes the values it refused. The API's error handler, the catcher of an unexpected failure, logs it at ERROR withinclude_exception=Trueand prints no traceback of its own. A CLI command's root logs an unexpected failure at ERROR with identifiers only,fields=failure_log_fields(error=exc, problem=problem)(pipelex.errors.failure_problem: the problem's code and the chain's classes, never a chained exception's text, which can quote a run's data) andinclude_exception=is_traceback_requested(), so the traceback rides only under--traceback; it prints the failure's problem in its own output (print_failure_probleminpipelex.cli.error_handlers), so the terminal names the cause whatever the sink and the level. Field names come from the vocabulary table indocs/tools/logging.md("Log-call conventions"), which review holds the calls to:make check-log-callsreads the messages, never thefields=keys.
StrEnum and Self type
- Import
StrEnumandSelfdirectly from the stdlib:from enum import StrEnum from typing import Self
Typing
Always Use Type Hints
- Every function parameter must be typed
- Every function return must be typed
- Use type hints for all variables where type is not obvious
- Use dict, list, tuple types with lowercase first letter: dict[], list[], tuple[]
- Use type hints for all fields
- Use Field(default_factory=...) for mutable defaults
- Use
# pyright: ignore[specificError]or# type: ignoreonly as a last resort. In particular, if you are sure about the type, you often solve issues by using cast() or creating a new typed variable.
One scoped exception to "every function return must be typed": a pydantic @model_serializer / @field_serializer return must stay unannotated unless the annotation is the exact type the model publishes. Pydantic turns a serializer's return annotation into the model's serialization JSON Schema and prefers it over the schema it would generate, so a -> dict[str, Any] publishes the whole model as an opaque {"type": "object", "additionalProperties": true} — no properties, no required, no closed shape — for every consumer that generates response schemas, which FastAPI always does for its responses. A precise annotation is fine and desirable (-> str on a model that serializes to its raw string); a dict/Any one erases the model, and nothing in a normal test suite notices because validation-mode schemas and model_dump() both stay correct.
Data-holder shapes (NamedTuple, dataclass, BaseModel)
The deciding question is does this value ever get serialized — sent across a process or network boundary, persisted to disk or a database, or round-tripped through (de)serialization? If yes, it must be one of the two serialization-safe forms (a BaseModel or a pydantic dataclass): a NamedTuple or stdlib @dataclass loses its type on the way through and silently corrupts the data across the boundary. (A distributed executor like Temporal is the canonical case — its payloads cross the wire between worker processes — but the same applies to any cache, queue, API response, or on-disk record.) Stdlib @dataclass is banned outright; pick one of these four forms:
NamedTuple(from typing import NamedTuple) — small fixed records replacing bare tuples, or any holder of a@runtime_checkableProtocol / arbitrary non-pydantic field (avoidsarbitrary_types_allowed). Not serialization-safe, zero validation. Avoid when the value is returned in a union beside a realtuple— it would also satisfyisinstance(x, tuple)and blur the two arms; use a frozenBaseModelthere instead.- pydantic dataclass (
from pydantic.dataclasses import dataclass) — internal records that are built and field-read but never serialized; the lowest-churn swap from a stdlib@dataclass(just change the decorator). Default tofrozen=True; drop it only when the instance is genuinely mutated in place after construction. - frozen
BaseModel(model_config = ConfigDict(frozen=True)) — immutable value objects that need the full model API (model_dump, validators, discriminated unions), must sit in a uniformly-BaseModellayer, or must stay type-distinct from atuplein a union. - mutable
BaseModel— objects genuinely mutated in place that also want the model API or layer consistency.
Don't reach for TypeAdapter on a shape you designed — needing it there means the top-level shape was chosen wrong: wrap it in a named BaseModel, which brings model_validate and the rest for free. Its one legitimate use is validating into a top-level type that is not a model class and not yours to wrap — a discriminated union or container owned by an external contract (a standard's wire model, a log stream of one-of-many event types); build that adapter once at module level and reuse it, and never use a TypeAdapter as a runtime substitute for cast on a value that is already typed. And don't convert an existing serialized BaseModel to a dataclass just because dataclasses are serialization-safe too: a model that relies on discriminated unions or validators must stay a BaseModel. When a serialized dataclass/model field references a type from an optional dependency, alias it to Any at runtime so it validates as Any without importing the extra (e.g. if TYPE_CHECKING: from temporalio.common import RetryPolicy / else: RetryPolicy = Any) — a bare forward ref instead raises PydanticUserError on construction.
Once you've landed on a BaseModel (the default for anything that serializes), respect Pydantic v2 standards:
- Use the modern
ConfigDictwhen needed, e.g.model_config = ConfigDict(extra="forbid", strict=True) - Keep models focused and single-purpose
- For list fields with non-string items, use
empty_list_factory_of()to avoid linter complaints:from pydantic import BaseModel, Field from pipelex.tools.typing.pydantic_utils import empty_list_factory_of class MyModel(BaseModel): names: list[str] = Field(default_factory=list) # OK for strings numbers: list[int] = Field(default_factory=empty_list_factory_of(int), description="A list of numbers") items: list[MyItem] = Field(default_factory=empty_list_factory_of(MyItem), description="A list of items")
Keyword-only arguments
Across pipelex/ source, non-subject function parameters must be keyword-only, so call sites are self-documenting: do_thing(retries=3, timeout=30) over the opaque do_thing(3, 30). The compliant shapes:
def f(*, opt1, opt2): ...— fully keyword-only. Always compliant, needs nothing.def f(subject, *, opt1, opt2): ...— a positional subject is legal ONLY under a subject grant recorded insubject_grants.tomlat the repo root. A lone subject (def render(node)) needs a grant too. No grant → violation.- A second bare positional (
def f(a, b),def truncate(text, max_length=80)) is always a violation, grant or not. - A subject annotated
bool/int/float(includingOptional[X]/X | Noneforms) is banned outright — grants are impossible; call sites likef(True)are never acceptable.strsubjects stay grantable.
To keep a subject positional, record a grant with an honest, def-specific rationale: make subject-grant FUNC="<relative_path>::<qualified_name>" RATIONALE="…" (alias make sgr). The command validates the def, records the param automatically, and rewrites the registry sorted. A grant is warranted when the call reads as a verb–object sentence with a single obvious operand (render(node), validate_bundle(bundle)) and call sites pass self-labelling expressions — when in doubt, go keyword-only instead. Grants are checked symmetrically: a grant whose def was renamed, moved, demoted, or deleted hard-fails the check until the registry is cleaned up (delete the entry or re-grant).
The rule is mechanically enforced by the check-keyword-only AST guard (make cko), which runs in make agent-check, in the make check aggregate, in CI, and via a Claude Code PostToolUse hook that checks each edited file at edit time. The tree is fully compliant, so it hard-blocks on any violation, and each violation kind names its remedy in the output. Carve-outs — dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, @override impls, and a small curated symmetric-tuple allowlist — are skipped automatically (they neither need nor hold grants). A genuinely justified one-off uses an inline # kw-only: ignore comment on the def line (place it right after the open paren so ruff format keeps it on the header line).
Auto-fix. make fix-keyword-only (alias fko, or pipelex-dev check-keyword-only --fix) rewrites every mechanically-fixable violation by inserting a bare * as far left as possible — right after self/cls — so every non-self/cls parameter becomes keyword-only, and re-parses each rewrite before writing (a rewrite that would not parse is discarded and reported instead). Ungranted-subject and literal-subject defs are fixable this way too; a grant-param mismatch is never rewritten (that is a registry decision). It runs automatically early in make agent-check, before ruff format. It is non-gating: it mutates and reports but never exits non-zero — the read-only check-keyword-only (run last in agent-check, and the variant make check / CI use) owns the pass/fail gate. ⚠ Because an ungranted subject is a violation, make agent-check will silently keyword-only it — record the grant BEFORE running checks if the subject should stay positional. Shapes a single * insert cannot fix are reported for a manual fix: a *args is present, a keyword-only section already exists (move the * by hand — the common def f(subject, *, opt) case when the subject is ungranted or literal-typed), or two-or-more positional-only params remain.
Auto-fix is not a substitute for review: the guard is blind to functions a framework or the interpreter invokes positionally (callbacks, __import__ hooks, route handlers, Jinja2 filters) — pyright/mypy will pass a wrongly-keywordized callback, so make agent-test is the safety net after a bulk fix.
Factory Pattern
- Use factory pattern for object creation when dealing with multiple implementations
- Our factory methods are named
make_from_...and such
Protocols and Interfaces
- When a getter (e.g.
get_report_delegate(),get_library_manager()) returns aProtocoltype, callers must only rely on methods declared on thatProtocol. If you need to call a method that lives on a concrete implementation, extend theProtocol— do not work around it withisinstance(...)checks,cast(...), or inline imports of the concrete class. - When extending the
Protocol, also update every implementation (including no-op / null implementations) so structural typing is satisfied. For implementations where the method has nothing to do, give it apassbody — that is the whole point of having aProtocolrather than a concrete base class. - Smell to watch for: an inline
from ... import ConcreteImpl # noqa: PLC0415followed byif isinstance(delegate, ConcreteImpl): delegate.some_method(...). This is almost always a missing method on theProtocol. Promote it. - Use
@override(fromtyping_extensions) on every implementation of aProtocolmethod, so that signature drift between theProtocoland its implementations is caught by the type checker.
Error Handling
Always catch exceptions at the place where you can add useful context to it.
Use try/except blocks with specific exceptions
Convert third-party exceptions to our custom ones except in pydantic validators where you can raise a ValueError or a TypeError
NEVER write
except Exception:(or bareexcept:). Catching the genericExceptionis FORBIDDEN except in two cases, each of which REQUIRES a one-line comment directly under theexceptnaming which case applies: (1) the absolute root of a CLI command or an API endpoint handler; (2) the wrapped call invokes genuinely unbounded code whose exception surface cannot be enumerated — a user-registered callback or function, dynamic plugin dispatch, or a third-party SDK with no documented exception types (this is only for genuinely open-ended surfaces; "I didn't look the exceptions up" does NOT qualify). There are NO other exceptions to this rule. The following are NOT valid justifications and the agent must reject them when tempted:- "I want to log and re-raise" → just let it propagate; logging happens at the root.
- "I want to swallow it just in case" → don't. Unknown failures must surface.
- "I want to convert it to our error type" → only if you know which specific exception(s) the call can raise; catch those explicitly. Catching a project base class (
PipelexError) or a package base (CogtError,ToolError) is acceptable when the operation legitimately fails in many domain-specific ways — that is still specific. CatchingExceptionis not. - "The third-party lib isn't well typed" → look up the actual exceptions it raises and catch those by name.
- "It's safer this way" → it isn't. It hides bugs. Crashing loudly on an unexpected exception is the desired behavior.
If you find yourself writing
except Exceptionoutside the two cases above, STOP and ask the user before proceeding.
Do NOT add try/except speculatively. Only add a
try/exceptwhen (a) a specific exception type is documented or known to be raised by the call, AND (b) you have a concrete recovery path or a meaningful context to attach. Otherwise, let the error bubble up — that is the correct behavior, not a gap to fill.Use
try/finally(withoutexcept) for required cleanup. When a piece of code MUST run on the way out — releasing a resource, closing a tracer, tearing down a library, clearing per-context state on a manager — put it in afinallyblock (or awith/context manager). This is the correct way to guarantee cleanup on both the happy path and the error path: it does NOT suppress the exception, it just ensures cleanup happens before the exception propagates. Do not invent anexcept Exceptionjust to attach cleanup; usefinallyinstead. Conversely, do not move cleanup into the success path "to keep things simple" — if it must run on errors too, it belongs infinally.When reviewing existing code, treat any
except Exceptionyou encounter as a bug to fix (replace it with the specific exception(s) actually raised, or remove the try/except entirely), not as a precedent to follow.from excon raise statements — default yes.raise NewError(msg) from excwhenever you raise a new exception while handling another. The point is preserving the cause for debugging tracebacks.Carve-out — translation helpers. When the actual
raiselives one frame down inside a translation helper (raise_validation_error(message=str(exc)), an API 4xx shaper, anything(msg: str) -> NoReturnwhose job is shaping the outgoing response), Python's implicit__context__chaining already preserves the original — the helper'sraiseruns while yourexceptframe is still active, structured logs walk the chain either way, and only the traceback intro line differs ("During handling of the above exception" vs "The above exception was the direct cause"). Don't bolt acause=excparameter onto every such helper just to swap implicit__context__for explicit__cause__. Revisit only if a helper grows an internal try/except that would break the implicit chain, or if a downstream tool (Sentry-style) is wired to distinguish the two.Always write the error message as a variable before raising it, for cleaner error traces
try: self.models_manager.setup() except RoutingProfileLibraryNotFoundError as exc: msg = "The routing library could not be found, please call `pipelex init config` to create it" raise PipelexSetupError(msg) from exc
Error class location
Put every custom error class in a module named exceptions.py (default — one per package directory) or <topic>_exceptions.py (when a directory needs several separate-concern error modules); the base error class gets its own module. This is a discoverability contract, not style: tooling that enumerates errors (doc generation, URI/uniqueness checks) finds them by importing these well-known module names, so an error defined in a sibling non-error module (worker, factory, parser) may never be imported and silently escapes that tooling.
- Default: append to the package's existing
exceptions.py. - Topical split: when appending would cause a circular import, or a package hosts genuinely separate error families, use
<topic>_exceptions.pyimporting only the base error class. - Forbidden:
*_errors.py(synonym, drift magnet), or defining an error alongside non-error code.
Use one casing per acronym (LLMError vs LlmError collide when kebab-cased into filenames/URIs). Enforce the convention with a test in CI.
Documentation
Docstring Format
def process_image(image_path: str, size: tuple[int, int]) -> bytes: """Process and resize an image. Args: image_path: Path to the source image size: Tuple of (width, height) for resizing Returns: Processed image as bytes """ passClass Documentation
class ImageProcessor: """Handles image processing operations. Provides methods for resizing, converting, and optimizing images. """
Standards related to developing the Pipelex codebase
Blueprints
Blueprints (pipelex/pipe_operators/, pipelex/pipe_controllers/, pipelex/pipe_machinery/, pipelex/mthds_parsing/, pipelex/core/) are the MTHDS language reference — what .mthds files parse into. The base PipeBlueprint lives in pipe_machinery/, the bundle blueprint the parser produces in mthds_parsing/, and the concept/domain blueprints in core/. A language rule or field goes on the blueprint, since a method is written as MTHDS directly.
Main config
- The main config model is defined using
ConfigModelclasses, derived frompydantic BaseModel - The model is defined in
pipelex/system/configuration/configs.py, some of the submodels being defined in their respective sub-packages - When adding new configs, place them where it makes most sense, ask the user if you need arbitrage
- As per our python standards, use StrEnum for multiple-value enums. In that case they must not be strict pydantic fields, i.e. add
= Field(strict=False) Field(strict=False)does not reach a container's items, so a container ofStrEnumis writtenlist[LaxEnum[MyEnum]]ordict[LaxEnum[MyEnum], ...], withLaxEnumfrompipelex/system/configuration/config_model.py. Amode="before"validator never assumes the raw value's type: it returns a value of an unexpected type untouched so the field's own type refuses it, and raises onlyValueError, since pydantic turns no other exception into a validation error.- Important: NEVER EVER set default values for config attributes in the class definition. All the default values are defined in the main config file
pipelex/pipelex.toml. The only exception si for Optional values which must be set toNonein the class definition. - If (and only if) you add some config that will clearly make sense for client projects to override, for instance if it's a case of user preference, then you can also add a copy of the settings to the project override config file
.pipelex/pipelex.toml. NEVER add them commented out: commented-out TOML is never parsed or validated, so it rots silently when keys are refactored. Instead, write the actual default values (matchingpipelex/pipelex.toml, even empty ones likeactivity_queues = {}) so the override file stays valid and behaves like setting nothing. Plain prose comments explaining the setting are fine — it's commented-out keys/values that are forbidden. - The different
pipelex.tomlfiles and the python modelconfigs.pymust be up to date with each other in terms of structure and attributes, otherwise the loading of teh config fails. To check quickly that you're good, just runmake tbwhich tests the boot sequence, which includes the config loading.
Keyword-only arguments
Non-subject function parameters across pipelex/ source must be keyword-only, so call sites are self-documenting: do_thing(retries=3, timeout=30) over the opaque do_thing(3, 30). The compliant shapes:
def f(*, opt1, opt2): ...— fully keyword-only. Always compliant, needs nothing.def f(subject, *, opt1, opt2): ...— a positional subject (including a lone one,def render(node)) is legal ONLY under a subject grant recorded insubject_grants.tomlat the repo root:make subject-grant FUNC="<path>::<qualname>" RATIONALE="…"(aliassgr). Grant when the call reads as a verb–object sentence with a single obvious operand; when in doubt, go keyword-only.- A second bare positional (
def f(a, b),def truncate(text, max_length=80)) is always a violation, grant or not. - A
bool/int/floatsubject (incl.Optional/union-with-Noneforms) is banned outright — grants are impossible;f(True)call sites are never acceptable.
The rule is mechanically enforced by the check-keyword-only AST guard, which runs in make agent-check, in the make check aggregate, and in CI; the tree is fully compliant, so it hard-blocks on any violation, and staleness is symmetric (a grant whose def was renamed, moved, demoted, or deleted fails the check until the registry is cleaned up). Carve-outs (dunders, pydantic validators/serializers, Typer/pytest/Jinja2 framework entrypoints, @override impls) are skipped automatically. A genuinely justified one-off uses an inline # kw-only: ignore comment on the def line (place it right after the open paren so ruff format keeps it on the header line). Watch for functions a framework or the interpreter invokes positionally (callbacks, __import__ hooks, route handlers): the type checker is blind to those, so make agent-test is the safety net. ⚠ make agent-check runs the auto-fixer, which will silently keyword-only an ungranted subject — record the grant BEFORE running checks if the subject should stay positional.
The full specification — the grant registry and rubric, the symmetric-tuple allowlist, the carve-out list, the escape hatch, and worked examples — is in docs/contribute/keyword-only-arguments.md.
Writing Tests
Unit test generalities
NEVER USE unittest.mock. Instead YOU MUST USE pytest-mock: from pytest_mock import MockerFixture.
NEVER EVER put more than one TestClass into a test module.
Test file structure
- Name test files with
test_prefix - Place test files in the appropriate test category directory:
tests/unit/- for unit tests that test individual functions/classes in isolationtests/integration/- for integration tests that test component interactionstests/e2e/- for end-to-end tests that test complete methods
- Do NOT add
__init__.pyfiles to test directories. Test directories do not need to be Python packages. - Fixtures are defined in conftest.py modules at different levels of the hierarchy, their scope is handled by pytest
- Test data is placed inside test_data.py at different levels of the hierarchy, they must be imported with package paths from the root like
from tests.integration.pipelex.cogt.test_data. Their content is all constants, regrouped inside classes to keep things tidy. - Always put tests inside Test classes: 1 TestClass per module.
- NEVER EVER put more than one TestClass into a test module.
- Put fixtures into conftest.py files for easy sharing.
Markers
Apply the appropriate markers:
- "gha_disabled: will not be able to run properly on GitHub Actions"
- "llm: uses an LLM to generate text or objects"
- "img_gen: uses an image generation AI"
- "extract: uses text/image extraction from documents"
- "inference: uses either an LLM or an image generation AI"
- never add "@pytest.mark.dry_runnable" if you haven't set the "inference" marker
Several markers may be applied. For instance, if the test uses an LLM, then it uses inference, so you must mark with both inference and llm.
Important rules
- Never use the unittest.mock. Use pytest-mock.
Test Class Structure
- Always group the tests of a module into a test class:
@pytest.mark.llm
@pytest.mark.inference
@pytest.mark.asyncio(loop_scope="class")
class TestFooBar:
@pytest.mark.parametrize(
"topic, test_case_blueprint",
[
TestCases.CASE_1,
TestCases.CASE_2,
],
)
async def test_pipe_processing(
self,
request: FixtureRequest,
topic: str,
test_case_blueprint: StuffBlueprint,
):
# Test implementation
- Never more than 1 class per test module.
- When testing one method, if possible, limit the number of test functions, but with different test cases in parameters
Test Data Organization
- If it's not already there, create a
test_data.pyfile in the proper test directory - Note how we avoid initializing a default mutable value within a class instance, instead we use ClassVar.
- Also note that we provide a topic for the test case, which is purely for convenience.
Best Practices for Testing
- Use strong asserts: test value, not just type and presence.
- Use parametrize for multiple test cases
- Test both success and failure cases
- Verify working memory state
- Check output structure and content
- Use meaningful test case names
- Include concise docstrings explaining test purpose but not on top of the file and not on top of the class.
- Log outputs for debugging
Writing Docs
We use Material for MkDocs. All markdown in our docs must be compatible with Material for MkDocs and done using best practices to get the best results with Material for MkDocs.
MkDocs Markdown Requirements
- Always add a blank line before any bullet lists or numbered lists in MkDocs markdown.