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.
Release v0.20.5 (#747)
Louis Choquelad2ee36b05fb
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 6625c731d..f4beca710 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "3953",+ "message": "3958","color": "blue","cacheSeconds": 300}\ No newline at end of filediff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.mdnew file mode 100644index 000000000..f649e58f2--- /dev/null+++ b/.claude/skills/release/SKILL.md@@ -0,0 +1,156 @@+---+name: release+description: >+ Automates the Pipelex release workflow: bumps the version in pyproject.toml,+ finalizes the CHANGELOG.md Unreleased section, runs quality checks, creates a+ release/vX.Y.Z branch, commits, pushes, and opens a PR to main. Use when user+ says "release", "cut a release", "bump version", "prepare a release", "make a+ release", "ship it", "create release branch", or any variation of shipping a+ new version of pipelex.+---++# Pipelex Release Workflow++This skill handles the full release cycle for the `pipelex` Python package.++## Files touched++- **`pyproject.toml`** — the `version` field (line 3)+- **`CHANGELOG.md`** — promote `[Unreleased]` to `[vX.Y.Z] - YYYY-MM-DD`+- **`uv.lock`** — regenerated via `make li` (lock + install)+- **`.badges/tests.json`** — test count updated to match actual count++## Workflow++### 1. Pre-flight checks++- Read the current version from `pyproject.toml`.+- Read `CHANGELOG.md` to understand the current state.+- Run `git status` and `git log origin/main..HEAD` to assess the working tree:+ - If there are **uncommitted changes** (staged or unstaged), warn the user and+ ask whether to commit them as part of the release, stash them, or abort.+ - If there are **unpushed commits** on the current branch, list them so the+ user is aware — these will be included in the release branch.++### 2. Determine the bump type++Ask the user which kind of version bump they want — **patch**, **minor**, or+**major** — unless they already specified it. Show the current version and what+the new version would be for each option so the choice is concrete.++### 3. Run quality checks++Run `make agent-check`. This is the gate — if it fails, stop and report the+errors so they can be fixed before retrying. Do not proceed past this step on+failure.++### 4. Finalize the changelog++The `CHANGELOG.md` has an `## [Unreleased]` section at the top with pending+changes.++1. If the `[Unreleased]` section is **empty** (no bullet points), warn the user+ and ask whether to proceed with an empty changelog entry or abort so they can+ add notes first.+2. If the `[Unreleased]` section has content:+ - Rename `## [Unreleased]` to `## [vX.Y.Z] - YYYY-MM-DD` (using today's+ date).+ - Insert a fresh empty `## [Unreleased]` section above the new version+ heading, with a blank line separating them.+3. The result should look like:++```markdown+# Changelog++## [Unreleased]++## [vX.Y.Z] - YYYY-MM-DD++### Changed+- ...+```++### 5. Bump the version in pyproject.toml++Edit `pyproject.toml` line 3 to the new version string. Only change the version+field — don't touch anything else.++### 6. Lock dependencies++Run `make li` to regenerate `uv.lock` and reinstall. This ensures the lockfile+reflects the new version in `pyproject.toml`. If this step fails, stop and+report the error.++### 7. Update the test count badge++Run `make test-count` to get the current number of tests. Then update+`.badges/tests.json` — set the `"message"` field to the count returned by+`make test-count`. Keep all other fields unchanged.++After updating, run `make check-test-badge` to verify the badge matches. If it+fails, re-check the count and fix the badge file.++### 8. Ensure we're on the right branch++The release branch must be named `release/vX.Y.Z` where X.Y.Z is the **new**+version.++- If already on `release/vX.Y.Z` matching the new version, stay on it.+- If on `dev`, `main`, or any other branch, create and switch to+ `release/vX.Y.Z` from the current HEAD.+- If on a `release/` branch for a **different** version, warn the user and ask+ how to proceed.++### 9. Commit and push++Stage all release-related changes. This includes at minimum `pyproject.toml`,+`CHANGELOG.md`, `uv.lock`, and `.badges/tests.json`, plus any other files the+user chose to include in step 1 (e.g. previously uncommitted work that belongs+in this release).++Commit with the message:++```+Release vX.Y.Z+```++Push the branch to origin with `-u` to set up tracking.++### 10. Open a PR++Create a pull request targeting `main` with:++- **Title:** `Release vX.Y.Z`+- **Body:** Include:+ - The changelog entries for this version (copied from CHANGELOG.md)+ - A note about the version bump from old to new++Use this format for the PR body:++```markdown+## Release vX.Y.Z++Bumps version from `A.B.C` to `X.Y.Z`.++### Changelog++<paste the changelog entries for this version here>+```++Report the PR URL back to the user.++## Important details++- The version follows semver: `MAJOR.MINOR.PATCH`.+- Always confirm the bump type with the user before making changes.+- If `make agent-check` fails, the release is blocked — help the user fix the+ issues rather than skipping the checks.+- The CI will validate that:+ - The `pyproject.toml` version matches the branch name (`version-check.yml`)+ - The `CHANGELOG.md` has an entry for the version (`changelog-check.yml`)+ - The `.badges/tests.json` count matches the actual test count (`check-test-badge`)+ - The `uv.lock` file is in sync with `pyproject.toml` (`uv-lock-check`)+- All checks must pass for the PR to be mergeable, so getting the changelog,+ version, test badge, and lockfile right is critical.+- Today's date for the changelog entry: use the current date in `YYYY-MM-DD`+ format.diff --git a/.pipelex/inference/backends/pipelex_gateway_models.md b/.pipelex/inference/backends/pipelex_gateway_models.mdindex 1172397fc..eeab8851d 100644--- a/.pipelex/inference/backends/pipelex_gateway_models.md+++ b/.pipelex/inference/backends/pipelex_gateway_models.md@@ -515,6 +515,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late> **AUTO-GENERATED FILE** - Do not edit manually.-> Last updated: 2026-03-04T07:00:39Z+> Last updated: 2026-03-10T06:49:52Z>> Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.\ No newline at end of filediff --git a/.pipelex/inference/backends/pipelex_gateway_models_plain.md b/.pipelex/inference/backends/pipelex_gateway_models_plain.mdindex be402f5a5..cd75c6723 100644--- a/.pipelex/inference/backends/pipelex_gateway_models_plain.md+++ b/.pipelex/inference/backends/pipelex_gateway_models_plain.md@@ -193,6 +193,6 @@ For configuration details, see the [documentation](https://docs.pipelex.com/late> **AUTO-GENERATED FILE** - Do not edit manually.-> Last updated: 2026-03-04T07:00:39Z+> Last updated: 2026-03-10T06:49:52Z>> Run `pipelex-dev update-gateway-models` or `make ugm` to regenerate.\ No newline at end of filediff --git a/CHANGELOG.md b/CHANGELOG.mdindex cf4037a25..998ed6f33 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,14 @@# Changelog+## [v0.20.5] - 2026-03-09++### Changed++- **Config paths use `pathlib.Path`**: All `ConfigLoader` properties and methods now return `Path` instead of `str`. Consumer code across the config system (doctor, init, backends, routing, credentials, telemetry, agent CLI) updated accordingly.+- **Layered config resolution for `pipelex doctor` and `pipelex init`**: Config files are now resolved with project-first, global-fallback layering per file. Fixed `replace_backend_file` using CWD-relative path that broke when run from another directory.+- **Gateway terms are explicitly global**: `update_service_terms_acceptance` now targets `~/.pipelex/` by default, since gateway terms are a user-level agreement, not project-level.+- Tweaks to the `pipelex-agent` CLI to play well with the Claude Code plugin and skills.+## [v0.20.4] - 2026-03-04- Improve README.md instructions for Claude Code and MTHDS skills.diff --git a/docs/home/1-features/advanced-customizations.md b/docs/home/1-features/advanced-customizations.mdnew file mode 100644index 000000000..43286d93e--- /dev/null+++ b/docs/home/1-features/advanced-customizations.md@@ -0,0 +1,28 @@+---+title: Advanced Customizations+---++# Advanced Customizations++A dependency injection framework for extending and customizing Pipelex behavior.++## Overview++Pipelex provides well-defined injection points that let you replace or extend core behaviors without modifying the framework itself. Each injection point follows a strict protocol contract, making implementations testable and swappable. Register custom providers at initialization time and the runtime uses them throughout execution.++## Injection Points++| Injection Point | Purpose |+|-----------------|---------|+| **[Secrets Provider](../10-advanced-customizations/secrets-provider-injection.md)** | Custom secret management (environment, vaults, etc.) |+| **[Storage Provider](../10-advanced-customizations/storage-provider-injection.md)** | Custom cloud storage backends |+| **[Observer](../10-advanced-customizations/observer-provider-injection.md)** | Custom execution data capture |+| **[Reporting Delegate](../10-advanced-customizations/reporting-delegate-injection.md)** | Custom cost reporting |+| **[Content Generator](../10-advanced-customizations/content-generator-injection.md)** | Override LLM output generation |+| **[Pipe Router](../10-advanced-customizations/pipe-router-injection.md)** | Dynamic routing of pipes to implementations |++## Built-in Defaults++Some injection points provide safe built-in defaults or no-op implementations, so you only need to implement the ones relevant to your use case.++For detailed documentation, see [Advanced Customizations](../10-advanced-customizations/index.md).diff --git a/docs/home/1-features/claude-code-skills-plugin.md b/docs/home/1-features/claude-code-skills-plugin.mdnew file mode 100644index 000000000..37a34fe84--- /dev/null+++ b/docs/home/1-features/claude-code-skills-plugin.md@@ -0,0 +1,38 @@+---+title: Claude Code Skills Plugin+---++# Claude Code Skills Plugin++Build, run, validate, and edit AI methods directly from Claude Code.++## Overview++The **MTHDS skills plugin** for Claude Code brings the full Pipelex workflow into your AI coding assistant. Build methods from natural language, validate them, run them, and iterate — all through conversational slash commands. The plugin leverages the `pipelex-agent` CLI under the hood for structured JSON communication.++Install from [mthds-ai/skills](https://github.com/mthds-ai/skills).++## Available Commands++| Command | Description |+|---------|-------------|+| `/mthds-build` | Build new AI method bundles from scratch |+| `/mthds-check` | Validate workflow bundles for issues (read-only) |+| `/mthds-edit` | Modify existing bundles — change pipes, update prompts, add or remove steps |+| `/mthds-explain` | Explain and document existing workflows in plain language |+| `/mthds-fix` | Automatically fix validation errors in a loop |+| `/mthds-run` | Execute methods and interpret JSON output (supports dry runs and graph generation) |+| `/mthds-inputs` | Prepare inputs: placeholder templates, synthetic test data, or user-provided files |+| `/mthds-install` | Install method packages from GitHub or local directories |+| `/mthds-pkg` | Manage packages — initialize, add dependencies, lock, install, update, validate |+| `/mthds-publish` | Publish methods to mthds.sh |++## Getting Started++```text+# Run these inside Claude Code:+/plugin marketplace add mthds-ai/skills+/plugin install mthds@mthds-ai-skills+```++Once installed, type `/mthds-build` in Claude Code to create your first method from a natural language description.diff --git a/docs/home/1-features/cli.md b/docs/home/1-features/cli.mdnew file mode 100644index 000000000..1604cdd78--- /dev/null+++ b/docs/home/1-features/cli.md@@ -0,0 +1,51 @@+---+title: CLI+---++# Command-Line Interface++A comprehensive CLI for developing, validating, and running AI methods.++## Overview++The `pipelex` CLI is the primary tool for working with Pipelex methods. It covers the full development lifecycle: authentication, initialization, building, validation, execution, inspection, and diagnostics.++## Core Commands++| Command | Description |+|---------|-------------|+| **`pipelex login`** | Authenticate with Pipelex Gateway via the browser and save your API key |+| **`pipelex init`** | Initialize configuration, backends, credentials, routing, and telemetry |+| **`pipelex doctor`** | Check configuration health and suggest fixes |+| **`pipelex build`** | AI-powered method generation from natural language requirements |+| **`pipelex validate`** | Check pipeline syntax, structure, and run dry-run validation |+| **`pipelex run`** | Execute pipelines from bundle files or libraries |+| **`pipelex graph`** | Generate and render execution graphs |+| **`pipelex show`** | Display configuration, pipes, and list AI models |+| **`pipelex which`** | Locate where a pipe is defined, similar to `which` for executables |++## Execution Options++- **Dry run** — `--dry-run` executes with mocked LLM responses to test pipeline logic without API calls+- **Mock inputs** — `--mock-inputs` generates synthetic inputs so you can test a pipeline without preparing real data+- **Graph generation** — `--graph`, `--graph-full-data`, `--graph-no-data` for visual execution inspection++## Agent CLI++The `pipelex-agent` CLI is a machine-first interface designed for automated environments like Claude Code skills. All output is structured JSON to stdout, with no interactive prompts or Rich formatting.++| Command | Description |+|---------|-------------|+| `init` | Non-interactive configuration setup |+| `run` | Execute a pipeline and output JSON results |+| `validate` | Validate pipes, bundles, or methods with JSON output |+| `fmt` | Format `.mthds`, `.toml`, or `.plx` files in-place |+| `lint` | Lint files for errors |+| `inputs` | Generate example input JSON for a pipe |+| `concept` | Convert a JSON concept spec into TOML |+| `pipe` | Convert a JSON pipe spec into TOML |+| `assemble` | Combine TOML parts into a complete `.mthds` file |+| `models` | List available model presets, aliases, and talent mappings |+| `doctor` | Check configuration health and auto-fix issues |++For detailed CLI documentation, see the [CLI reference](../9-tools/cli/index.md).diff --git a/docs/home/1-features/cloud-storage.md b/docs/home/1-features/cloud-storage.mdnew file mode 100644index 000000000..28c73758c--- /dev/null+++ b/docs/home/1-features/cloud-storage.md@@ -0,0 +1,29 @@+---+title: Cloud Storage+---++# Cloud Storage++Store generated artifacts on cloud infrastructure.++## Overview++Pipelex can automatically upload generated artifacts — images, extracted pages, and other outputs — to cloud storage providers with configurable access control. For development and testing, local filesystem and in-memory storage are also available.++## Supported Providers++- **Local filesystem** — Store artifacts on the local disk (default for development)+- **In-memory** — Ephemeral storage for testing, no persistence+- **AWS S3** — Amazon Simple Storage Service with configurable region and bucket+- **Google Cloud Storage** — GCS buckets with project-level credentials++## URL Options++- **Public URLs** — Directly accessible URLs for public content+- **Signed URLs** — Time-limited secure URLs for private content, with configurable lifespan++## Configuration++Storage is configured in `pipelex.toml` under `[pipelex.storage_config]`. Set `method` to `local`, `in_memory`, `s3`, or `gcp`, then provide provider-specific settings such as `bucket_name`, `region`, or `project_id` in the matching subsection.++For AWS configuration, see [AWS Configuration](../7-configuration/config-technical/aws-config.md).diff --git a/docs/home/1-features/concepts.md b/docs/home/1-features/concepts.mdnew file mode 100644index 000000000..e735bd444--- /dev/null+++ b/docs/home/1-features/concepts.md@@ -0,0 +1,46 @@+---+title: Concepts & Structured Types+---++# Concepts & Structured Types++The semantic typing system that gives meaning to your AI data.++## Overview++Concepts are Pipelex's type system. They define what kind of data flows through your pipelines — not just the shape, but the meaning. A concept can be as simple as "a tweet about a product" or as complex as "an invoice with line items, totals, and tax breakdowns." Every pipe declares the concepts it accepts as input and produces as output, enabling Pipelex to validate data flow at definition time rather than runtime.++## Native Concepts++Pre-built universal concepts available in every Pipelex project:++- **Dynamic** — Dynamic typing, resolved at runtime+- **Text** — Plain text content+- **Image** — Image data (base64, URL, or file path)+- **Document** — A document container (PDF, image, or other file)+- **Html** — HTML content+- **TextAndImages** — Combined text and image content in a single structure+- **Number** — Numeric value+- **ImgGenPrompt** — A prompt specifically crafted for image generation models+- **Page** — A single page extracted from a document, with markdown text and optional images+- **JSON** — Arbitrary JSON data+- **SearchResult** — Web search result with source citations+- **Anything** — Universal type that accepts any content++## Custom Concepts++Define your own concepts with natural language descriptions and optional structured fields. Custom concepts live in `.mthds` files within a domain and can carry a description that guides LLMs, structured fields for validation, or both.++## Inline Structures++Define structured fields directly in `.mthds` files without writing Python. Inline structures support typed fields (text, integer, boolean, number, list) and nested concepts for complex data shapes — making it possible to build fully structured methods without leaving the MTHDS language.++## Python StructuredContent Classes++For advanced use cases, generate Pydantic BaseModels from your declarative concepts. This gives you full IDE autocomplete, type checking, and runtime validation. You can also hand-write `StructuredContent` classes when you need custom logic beyond what MTHDS declarations provide.++## Concept Refinement & Hierarchies++Create specialized versions of existing concepts using the `refines` keyword. Build concept hierarchies for domain modeling — for example, a `DetailedInvoice` that refines a base `Invoice` concept, inheriting its structure while adding more specific semantics.++For detailed guidance, see [Define Your Concepts](../6-build-reliable-ai-workflows/concepts/define_your_concepts.md).diff --git a/docs/home/1-features/configuration.md b/docs/home/1-features/configuration.mdnew file mode 100644index 000000000..78a890ce3--- /dev/null+++ b/docs/home/1-features/configuration.md@@ -0,0 +1,36 @@+---+title: Configuration System+---++# Configuration System++Multi-level TOML configuration for full control over Pipelex behavior.++## Overview++Pipelex uses a layered TOML configuration system that lets you define sensible defaults and override them at any level: project, environment, or run mode. Each layer merges on top of the previous one, so you only need to specify what you want to change.++## Configuration Levels++1. **Base defaults** — Built into Pipelex (`pipelex.toml` in the package)+2. **Global overrides** — `~/.pipelex/pipelex.toml` for user-wide settings+3. **Project overrides** — `{project_root}/.pipelex/pipelex.toml` for project-specific settings+4. **Local overrides** — `pipelex_local.toml` (git-ignored) for machine-specific values+5. **Environment / run-mode-specific** — `pipelex_dev.toml`, `pipelex_prod.toml`, `pipelex_testing.toml`, etc.++A final `pipelex_override.toml` file can be used for last-resort overrides.++## Environment Variables++Use `${VAR_NAME}` syntax in TOML files for dynamic configuration from environment variables and secrets. Supports `${env:VAR}` for environment variables, `${secret:VAR}` for the secrets provider, and fallback chains like `${env:VAR|secret:VAR}`.++## Key Configuration Areas++- **[Inference Backends](../7-configuration/config-technical/inference-backend-config.md)** — LLM providers, models, and routing+- **[Logging](../7-configuration/config-practical/logging-config.md)** — Log levels and output+- **[Telemetry](../7-configuration/config-practical/telemetry-config.md)** — Observability settings+- **[Reporting](../7-configuration/config-practical/reporting-config.md)** — Cost tracking and reports+- **[Dry Run](../7-configuration/config-pipeline-validation/dry-run-config.md)** — Mock generation settings+- **[Features](../7-configuration/config-advanced/feature-config.md)** — Feature flags++For full configuration reference, see [Configuration](../7-configuration/index.md).diff --git a/docs/home/1-features/cost-tracking.md b/docs/home/1-features/cost-tracking.mdnew file mode 100644index 000000000..42bf139ff--- /dev/null+++ b/docs/home/1-features/cost-tracking.md@@ -0,0 +1,25 @@+---+title: Cost Tracking & Reporting+---++# Cost Tracking & Reporting++Automatic cost tracking for every AI operation in your methods.++## Overview++Pipelex automatically tracks token usage and calculates costs for every LLM call, extraction operation, and image generation. Stay informed about your AI spend at the method, pipe, and operation level.++## Console Reporting++Real-time cost information displayed in the console during pipeline execution. Each inference call reports its token usage and estimated cost, with a summary total at the end of the run.++## CSV Export++Export detailed cost reports as CSV files for analysis, billing, and audit trails. Each row captures the pipe, model, token counts (input/output), and cost for a single operation.++## Custom Reporting++Implement custom reporting backends via the [Reporting Delegate](advanced-customizations.md) injection point. The reporting protocol receives structured cost events during execution, allowing you to push data to your own analytics, dashboards, or billing systems.++For configuration, see [Reporting Configuration](../7-configuration/config-practical/reporting-config.md).diff --git a/docs/home/1-features/document-extraction.md b/docs/home/1-features/document-extraction.mdnew file mode 100644index 000000000..115107db1--- /dev/null+++ b/docs/home/1-features/document-extraction.md@@ -0,0 +1,36 @@+---+title: Document Extraction+---++# Document Extraction++Multi-provider OCR and document processing with a unified interface.++## Overview++From simple text extraction to advanced document understanding — Pipelex handles it all. Basic PDF text extraction works out of the box (via pypdfium2), but real documents demand more: OCR for scanned pages, layout analysis for complex structures, image extraction, and VLM-powered understanding.++Unlike LLM APIs (partly standardized around OpenAI's completions API), the OCR landscape is fragmented. Pipelex solves this with a unified interface: swap providers by changing your PipeExtract config, no code changes required.++## Supported Providers++| Provider | Type | Description |+|----------|------|-------------|+| **pypdfium2** | Built-in | Basic PDF text and image extraction without AI inference — works out of the box with no API keys |+| **Mistral OCR** | Cloud API | Industry-leading document understanding for media, text, tables, and equations |+| **docling** | Local SDK | IBM's open-source extraction library with local CPU processing and optional GPU acceleration |+| **Azure Document Intelligence** | Gateway | Enterprise-grade OCR with high accuracy for complex layouts, tables, and handwriting |+| **Deepseek-OCR** | Gateway | Open-source model optimized for markdown extraction from images |++## Key Capabilities++- **Page view generation** — High-fidelity image rendering of extracted pages via pypdfium2+- **Embedded image extraction** — Capture images found within documents+- **Layout analysis** — Structured extraction of complex document layouts+- **Table recognition** — Automatic table detection and extraction+- **Handwriting support** — Via providers that support handwriting recognition (e.g., Azure Document Intelligence)+- **Multi-page processing** — Batch processing of document pages with per-page results++## Documents in LLM Prompts++Include PDFs directly in your prompts using `@variable` syntax. PipeLLM automatically handles document rendering — single documents, multiple documents, and mixed content combining text, images, and PDFs are all supported.diff --git a/docs/home/1-features/execution-graph.md b/docs/home/1-features/execution-graph.mdnew file mode 100644index 000000000..8f0c03f3d--- /dev/null+++ b/docs/home/1-features/execution-graph.md@@ -0,0 +1,37 @@+---+title: Execution Graph Visualization+---++# Execution Graph Visualization++Full transparency into pipeline execution with interactive visualizations.++## Overview++Every pipeline execution can be visualized as an interactive graph, giving developers full transparency into what happened, in what order, and with what data at each step. Graphs are generated automatically when using the `--graph` flag and open in a browser.++## Interactive HTML Visualization++Inspect any pipeline execution with a local ReactFlow-based interface. Nodes represent pipes, edges show data flow, and clicking any node reveals the data at that stage. The visualization supports zooming, panning, and collapsing nested controllers.++## Mermaid Chart Export++Render pipeline diagrams anywhere that supports Mermaid: VS Code, GitHub, web applications, and documentation. Mermaid charts provide a static, embeddable view of the pipeline structure.++## Step-by-Step Data Inspection++View the actual data at each execution stage:++- **JSON** — Raw structured data+- **HTML preview** — Rendered content+- **Images** — Generated or extracted images+- **Embedded PDFs** — Document content++## CLI Flags++- `--graph` — Generate an execution graph after running a pipeline+- `--graph-full-data` — Include full data payloads in the graph+- `--graph-no-data` — Generate a structural graph without data++<!-- path verified: resolves to docs/images/flow-chart-example.png -->+{ width="400" }diff --git a/docs/home/1-features/gateway.md b/docs/home/1-features/gateway.mdnew file mode 100644index 000000000..dffef976d--- /dev/null+++ b/docs/home/1-features/gateway.md@@ -0,0 +1,52 @@+---+title: Pipelex Gateway & Model Access+---++# Pipelex Gateway & Model Access++Access AI models through the Pipelex Gateway or bring your own API keys.++## Pipelex Gateway++A fully managed infrastructure providing unified access to AI models through a single API key. The Gateway eliminates the need to manage multiple provider configurations.++- **Single API key** for all supported models+- **Remote model catalog** — always access the latest models without updating Pipelex+- **Enterprise-grade architecture** — built for reliability and scale+- **Extensive provider support** — OpenAI, Google, Anthropic, Mistral, xAI, and more++Browse all supported models in the [Gateway Models](../5-setup/gateway-models.md) reference.++Get your Gateway API key at [app.pipelex.com](https://app.pipelex.com/) or [join the waitlist](https://go.pipelex.com/waitlist).++## Bring Your Own Keys++Direct integration with major providers using your own API keys:++- **OpenAI** — GPT-4o, GPT-4.1, o1, o3, o4-mini, etc.+- **Anthropic** — Claude Sonnet 4, Claude Haiku, etc.+- **Google** — Gemini 2.5 Pro, Gemini 2.5 Flash, etc.+- **Mistral** — Mistral Large, Mistral Medium, etc.+- **Azure OpenAI** — Azure-hosted OpenAI models+- **Amazon Bedrock** — AWS-hosted models+- **Vertex AI** — Google Cloud-hosted models+- **xAI** — Grok models+- **Portkey** — AI gateway for routing and observability+- **OpenRouter** — Multi-provider aggregator+- **BlackboxAI** — Blackbox-hosted models+- **fal** — Image generation models++## Open-Source Models++Run open-source models through dedicated providers:++- **Ollama** — Run open-source LLMs locally (Llama, Mistral, Qwen, etc.)+- **Hugging Face Inference** — including qwen-image for text-to-image+- **Scaleway** — Deepseek R1, Llama 3.3, Qwen3, GPT-OSS+- **Groq** — Llama-4, Kimi-K2-Instruct++## Routing Profiles++Routing profiles control which backend handles each model. Define pattern-based routes, defaults, and fallback orders in `routing_profiles.toml`. Switch a pipeline from one provider to another — or from Pipelex Gateway to your own keys — without changing the method definition.++See [Configure AI Providers](../5-setup/configure-ai-providers.md) for setup details.diff --git a/docs/home/1-features/image-generation.md b/docs/home/1-features/image-generation.mdnew file mode 100644index 000000000..406448bba--- /dev/null+++ b/docs/home/1-features/image-generation.md@@ -0,0 +1,41 @@+---+title: Image Generation+---++# Image Generation++Text-to-image generation integrated directly into your pipelines.++## Overview++PipeImgGen generates images from text prompts using state-of-the-art models. Generated images can be stored locally or in cloud storage with public or signed URLs. Image generation supports both text-to-image and image-to-image workflows.++## Supported Models++Via **Pipelex Gateway**:++- **GPT-Image-1.5** — OpenAI's latest image generation model+- **GPT-Image-1** — OpenAI image generation+- **GPT-Image-1-mini** — Smaller, faster variant for quick generations+- **FLUX-2-pro** — Black Forest Labs' high-quality generation model+- **Nano Banana / Nano Banana Pro / Nano Banana 2** — Google Gemini-based image generation++Via **direct provider SDKs**:++- **OpenAI** — Direct OpenAI API for GPT Image models+- **Google Gemini** — Native Google image generation+- **fal** — FLUX and other models via the fal platform+- **Hugging Face Inference** — Open-source models like qwen-image+- **BlackboxAI** — Via completions-based image generation+- **Azure REST** — Azure-hosted image generation+- **OpenRouter** — Multi-provider image generation access++## Cloud Storage Integration++Generated images can be automatically uploaded to AWS S3 or Google Cloud Storage with configurable URL signing. See [Cloud Storage](cloud-storage.md) for details.++## Usage in Pipelines++Use PipeImgGen in your `.mthds` files to generate images as part of a pipeline. The operator accepts a text prompt (or an ImgGenPrompt concept) and outputs an Image concept. Model presets let you configure quality levels and default models in `2_img_gen_deck.toml`.++See [PipeImgGen reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeImgGen.md).diff --git a/docs/home/1-features/index.md b/docs/home/1-features/index.mdnew file mode 100644index 000000000..af8eb0ec6--- /dev/null+++ b/docs/home/1-features/index.md@@ -0,0 +1,125 @@+---+title: Features+---++# Pipelex Features++Pipelex is the AI method framework that eliminates the complexity of building AI-powered applications. One framework for prompts, pipelines, and structured outputs. One API key for dozens of AI models. One method from prototype to production.++This section covers all Pipelex capabilities, organized by area.++---++## Declarative AI Methods++<div class="grid cards" markdown>++- **[MTHDS Language](mthds-language.md)**++ A declarative, TOML-based `.mthds` file format for defining AI methods without writing code. Domains, bundles, packages, and cross-references.++- **[Concepts & Structured Types](concepts.md)**++ Semantic typing system for AI data. Native types, inline structures, Python classes, concept refinement, and hierarchies.++- **[Pipe Operators](pipe-operators.md)**++ The workers that do the actual processing: PipeLLM, PipeExtract, PipeImgGen, PipeSearch, PipeCompose, and PipeFunc.++- **[Pipeline Orchestration](pipeline-orchestration.md)**++ Controllers for building complex workflows: PipeSequence, PipeParallel, PipeBatch, PipeCondition, and working memory for data flow.++</div>++---++## AI Capabilities++<div class="grid cards" markdown>++- **[Pipelex Gateway & Model Access](gateway.md)**++ Unified access to 60+ AI models through a single API key, or bring your own keys for direct provider access. Open-source model support via Hugging Face, Scaleway, and Groq.++- **[LLM Integration](llm-integration.md)**++ Text generation, structured outputs, vision language models, prompting styles, system prompt inheritance, and model presets.++- **[Document Extraction](document-extraction.md)**++ Multi-provider OCR with Mistral OCR, Azure Document Intelligence, docling, and Deepseek-OCR. PDF processing, page rendering, layout analysis, and table recognition.++- **[Image Generation](image-generation.md)**++ Text-to-image generation with FLUX, GPT Image, and other providers. Cloud storage integration for generated images.++- **[Web Search](web-search.md)**++ Structured web search results with source citations and advanced filters via PipeSearch.++</div>++---++## Developer Tools++<div class="grid cards" markdown>++- **[Claude Code Skills Plugin](claude-code-skills-plugin.md)**++ Build, run, validate, and edit AI methods directly from Claude Code with the MTHDS skills plugin. 10+ slash commands for the full method lifecycle.++- **[CLI](cli.md)**++ Full command-line interface: `login`, `init`, `doctor`, `build`, `validate`, `run`, `graph`, `show`, `which`, and more. Dry run mode, graph generation, and agent CLI.++- **[plxt Formatter & Linter](plxt.md)**++ Fast formatting and linting for TOML, MTHDS, and PLX files. CI-ready with `--check` mode.++- **[Execution Graph Visualization](execution-graph.md)**++ Interactive HTML visualization and Mermaid chart export for pipeline execution. Step-by-step data inspection with JSON, HTML, images, and PDFs.++</div>++---++## Production & Operations++<div class="grid cards" markdown>++- **[Validation & Dry Run](validation-dry-run.md)**++ Pipeline validation without execution, dry run with mocked LLM responses, input validation, and allowed-to-fail pipes.++- **[Telemetry & Observability](telemetry.md)**++ Production monitoring with Langfuse, OpenTelemetry, and PostHog integration. Gateway telemetry, span tracing, and custom destinations.++- **[Cloud Storage](cloud-storage.md)**++ Store generated artifacts on AWS S3 or Google Cloud Storage with public or signed URLs.++- **[Cost Tracking & Reporting](cost-tracking.md)**++ Automatic token cost tracking per operation with console logging and CSV report export.++</div>++---++## Configuration & Extensibility++<div class="grid cards" markdown>++- **[Configuration System](configuration.md)**++ Multi-level TOML configuration: base defaults, project overrides, environment-specific, and run-mode-specific. Environment variable support.++- **[Advanced Customizations](advanced-customizations.md)**++ Dependency injection framework for secrets, storage, observers, content generators, and pipe routers.++</div>diff --git a/docs/home/1-features/llm-integration.md b/docs/home/1-features/llm-integration.mdnew file mode 100644index 000000000..264d8c9dc--- /dev/null+++ b/docs/home/1-features/llm-integration.md@@ -0,0 +1,40 @@+---+title: LLM Integration+---++# LLM Integration++Deep integration with large language models for text generation, structured outputs, and vision tasks.++## Overview++Pipelex provides a unified interface for working with LLMs across providers. Write your prompt once, run it on any supported model. The runtime handles provider-specific API differences, token management, and response parsing.++## Structured Output Generation++Two approaches for structured outputs:++- **Two-step** — Generate text first, then parse into a structured concept. More reliable for complex schemas.+- **Direct JSON** — Generate structured JSON directly from the LLM using provider-native structured output features.++See [LLM Structured Generation](../6-build-reliable-ai-workflows/llm-structured-generation-config.md).++## Vision Language Models++Include images and PDFs directly in LLM prompts using `@variable` syntax. Support for single documents, multiple documents, and mixed content (text + images + PDFs). The runtime automatically handles document rendering and provider-specific vision API formats.++## Prompting Styles++Adapt prompts for different LLM families (OpenAI, Anthropic, Mistral) to get the best results from each provider. Pipelex applies provider-specific formatting, system prompt handling, and structured output instructions automatically.++See [LLM Prompting Style](../6-build-reliable-ai-workflows/adapt-to-llm-prompting-style-openai-anthropic-mistral.md).++## System Prompt Inheritance++Define system prompts at the domain level and have them automatically inherited by all PipeLLM operators in that domain. Individual pipes can override the domain-level system prompt when needed.++## Model Presets++Named configurations (temperature, max tokens, model selection, etc.) for consistent model behavior. Define presets once in the model deck, then reference them by name across all your pipelines using `$preset_name` syntax.++See [Optimize Cost & Quality](../6-build-reliable-ai-workflows/configure-ai-llm-to-optimize-methods.md).diff --git a/docs/home/1-features/mthds-language.md b/docs/home/1-features/mthds-language.mdnew file mode 100644index 000000000..fe42a8a92--- /dev/null+++ b/docs/home/1-features/mthds-language.md@@ -0,0 +1,35 @@+---+title: MTHDS Language+---++# MTHDS Language++The declarative, TOML-based file format for defining AI methods without writing code.++## Overview++MTHDS (`.mthds` files) is a domain-specific language for defining AI methods. It lets developers declare concepts, pipes, and pipelines in a structured format that is both human-readable and machine-executable. The philosophy is separation of concerns: method logic is declared in MTHDS, while execution is handled by the Pipelex runtime. This keeps prompts, data flow, and orchestration version-controlled and reviewable.++## Domains++Semantic namespaces for organizing related concepts and pipes. Domains provide hierarchical naming and scoping, preventing name collisions across packages. Each `.mthds` file declares a single domain, and multiple files can contribute to the same domain.++## Bundles++A bundle is a complete method package defined in a single `.mthds` file. It contains a domain declaration, concepts, and pipes, and can optionally designate a `main_pipe` as the entry point. Bundles are self-contained and can be executed via the CLI or Python API.++## Packages & Dependencies++Package management with `METHODS.toml` manifest files. Declare package identity, dependencies with semantic version constraints (exact, caret, tilde, comparison), and export visibility controls. Packages can be installed from GitHub repositories or local directories.++## Cross-Package References++Reference concepts and pipes across package boundaries using the `->` operator with fully qualified names. This enables method composition — build complex methods from smaller, reusable packages.++## Pure MTHDS Development++Inline concept structures with nested concepts make Pipelex fully usable with just `.mthds` files and the CLI — no Python code required. Define structured outputs, orchestrate multi-step pipelines, and run everything from the command line.++## Language Specification++For the formal language specification, see [mthds.ai](https://mthds.ai).diff --git a/docs/home/1-features/pipe-operators.md b/docs/home/1-features/pipe-operators.mdnew file mode 100644index 000000000..cca450b9e--- /dev/null+++ b/docs/home/1-features/pipe-operators.md@@ -0,0 +1,47 @@+---+title: Pipe Operators+---++# Pipe Operators++The workers that perform the actual processing in your pipelines.++## Overview++Pipe operators are the building blocks of Pipelex methods. Each operator performs a specific type of work: calling an LLM, extracting text from documents, generating images, searching the web, composing data, or running custom code. Operators declare their input and output concepts, and the runtime validates type compatibility at definition time.++## PipeLLM++The core operator for LLM interaction. Supports text generation, structured output generation (two-step or direct JSON), vision (images and PDFs in prompts via `@variable` syntax), system prompts, and model presets. Works with any supported LLM provider.++See [PipeLLM reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeLLM.md).++## PipeExtract++OCR and document extraction from PDFs and images. Supports multiple providers (pypdfium2, Mistral OCR, Azure Document Intelligence, docling, Deepseek-OCR), page rendering, embedded image extraction, and layout analysis. Swap providers by changing configuration, no code changes needed.++See [PipeExtract reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeExtract.md).++## PipeImgGen++Text-to-image and image-to-image generation using models like FLUX, GPT Image, Nano Banana, and others. Outputs are stored locally or in cloud storage with configurable URL signing.++See [PipeImgGen reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeImgGen.md).++## PipeSearch++Web search with structured results and source citations. Powered by Linkup or Pipelex Gateway, results come back as typed SearchResult concepts ready for downstream processing.++See [PipeSearch reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeSearch.md).++## PipeCompose++Deterministic object construction without an LLM. Compose outputs from working memory variables, fixed values, Jinja2 templates, and nested structures. Ideal for aggregating results from previous steps or building inputs for downstream pipes.++See [PipeCompose reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeCompose.md).++## PipeFunc++Execute custom Python functions within pipelines. Functions are auto-discovered via the `@pipe_func()` decorator and receive the current working memory as their input. Use PipeFunc when you need logic that goes beyond what declarative operators provide.++See [PipeFunc reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeFunc.md).diff --git a/docs/home/1-features/pipeline-orchestration.md b/docs/home/1-features/pipeline-orchestration.mdnew file mode 100644index 000000000..2996a1104--- /dev/null+++ b/docs/home/1-features/pipeline-orchestration.md@@ -0,0 +1,47 @@+---+title: Pipeline Orchestration+---++# Pipeline Orchestration++Controllers for building complex workflows from simple building blocks.++## Overview++Pipeline controllers define how pipes are assembled and executed. They handle sequencing, parallelism, iteration, and conditional branching — all declaratively in `.mthds` files. Controllers are themselves pipes, so they can be nested to build arbitrarily complex workflows.++## PipeSequence++Run pipes one after another, passing data through working memory. The most common controller for multi-step methods. Each step can read variables written by previous steps, enabling progressive data enrichment.++See [PipeSequence reference](../6-build-reliable-ai-workflows/pipes/pipe-controllers/PipeSequence.md).++## PipeParallel++Execute multiple independent pipes concurrently for faster throughput. Each branch starts with a deep copy of the current working memory, and their outputs are merged back when all branches complete.++See [PipeParallel reference](../6-build-reliable-ai-workflows/pipes/pipe-controllers/PipeParallel.md).++## PipeBatch++Apply the same pipe to every item in a list — the map operation for pipelines. Takes a list input and produces a list output, processing each item independently.++See [PipeBatch reference](../6-build-reliable-ai-workflows/pipes/pipe-controllers/PipeBatch.md).++## PipeCondition++Conditional branching based on Jinja2 expressions evaluated against working memory. Route execution to different pipes depending on runtime data, enabling dynamic method behavior.++See [PipeCondition reference](../6-build-reliable-ai-workflows/pipes/pipe-controllers/PipeCondition.md).++## Working Memory++Temporary storage for data flowing between pipes within a single execution. Variables are typed by concepts and scoped to the pipeline. Each pipe reads from and writes to working memory, creating a shared data context across the method.++See [Working Memory](../6-build-reliable-ai-workflows/pipes/working-memory.md).++## Multiplicity++Control how many items pipes accept and produce: single values, variable-length lists (`[]`), or fixed-count lists (`[N]`). Multiplicity is declared in the pipe definition and validated at definition time.++See [Understanding Multiplicity](../6-build-reliable-ai-workflows/pipes/understanding-multiplicity.md).diff --git a/docs/home/1-features/plxt.md b/docs/home/1-features/plxt.mdnew file mode 100644index 000000000..bab760bc2--- /dev/null+++ b/docs/home/1-features/plxt.md@@ -0,0 +1,29 @@+---+title: plxt Formatter & Linter+---++# plxt Formatter & Linter++A Rust-based formatter and linter for TOML that supports schema-based validation, customized for the MTHDS language.++## Overview++`plxt` is a fast, Rust-based TOML formatter and linter with schema-based validation support. It has been customized to understand the MTHDS language, providing formatting and linting tailored to `.mthds` and `.plx` files. It is distributed as part of the `pipelex-tools` package.++## Formatting++- **TOML files** — Standard TOML formatting+- **MTHDS files** — Schema-aware formatting for method definitions+- **PLX files** — Pipelex configuration formatting+- **Alignment options** — Configurable alignment for entries and comments+- **Per-file-type rules** — Different formatting rules for different file types++## Linting++Schema-based validation that catches structural and semantic issues beyond basic syntax checking. Detects invalid keys, missing required fields, type mismatches, and MTHDS-specific violations such as unknown pipe operators or invalid concept references.++## CI Integration++Use `plxt fmt --check` to validate formatting without modifying files, and run `plxt lint` separately for schema and semantic checks. Both commands exit with a non-zero code on errors, making them easy to enforce in automated workflows.++For details, see the [plxt reference](../9-tools/plxt.md).diff --git a/docs/home/1-features/telemetry.md b/docs/home/1-features/telemetry.mdnew file mode 100644index 000000000..ba89c5213--- /dev/null+++ b/docs/home/1-features/telemetry.md@@ -0,0 +1,36 @@+---+title: Telemetry & Observability+---++# Telemetry & Observability++Production-ready monitoring for your AI methods.++## Overview++Pipelex provides comprehensive telemetry and observability capabilities to monitor your AI methods in production. Track costs, latency, errors, and execution patterns across multiple destinations. Custom telemetry is opt-in and configurable per integration mode (CLI, pytest, API). When Pipelex Gateway is enabled as an inference backend, privacy-respecting Gateway metrics are collected automatically.++## Langfuse Integration++Full LLM observability with complete span data. Track every LLM call, its inputs, outputs, tokens, cost, and latency. Supports both Langfuse Cloud and self-hosted instances via the OTLP exporter.++## OpenTelemetry (OTLP)++Send execution spans to any OTLP-compatible backend for integration with your existing observability stack. Configure multiple OTLP exporters with custom endpoints and headers to fan out telemetry to different destinations.++## PostHog Integration++Event tracking and AI span tracing with fine-grained privacy controls. Choose between anonymous and identified modes. Configure what data to capture: content, pipe codes, output class names, and content length limits.++## Gateway Telemetry++When using Pipelex Gateway as your inference backend, privacy-respecting metrics are automatically collected: models used, token counts, latency, and error rates. This data is tied to your Gateway API key (hashed for security) and requires no additional configuration.++## Privacy Controls++- **DO_NOT_TRACK** — Universal telemetry disable flag, respected by all integrations+- **Configurable destinations** — Choose independently what data goes to PostHog, Langfuse, OTLP, or Gateway+- **Content redaction** — Control whether prompt/completion content is included in spans+- **Mode-based gating** — Enable custom telemetry for CLI usage but disable it during unit tests++For configuration, see [Telemetry Configuration](../7-configuration/config-practical/telemetry-config.md) and [Telemetry Setup](../5-setup/telemetry.md).diff --git a/docs/home/1-features/validation-dry-run.md b/docs/home/1-features/validation-dry-run.mdnew file mode 100644index 000000000..2d3039a0a--- /dev/null+++ b/docs/home/1-features/validation-dry-run.md@@ -0,0 +1,39 @@+---+title: Validation & Dry Run+---++# Validation & Dry Run++Test your pipelines without making API calls.++## Overview++Pipelex provides multiple layers of validation to catch issues before they cost time and money. From static syntax checking to full dry-run execution with mocked responses, you can verify your methods at every stage of development.++## Pipeline Validation++Check pipeline syntax, structure, and compatibility without execution:++- **Syntax validation** — Catch MTHDS language errors via plxt linting+- **Structure validation** — Verify concept compatibility between pipes, ensuring inputs and outputs match+- **Input validation** — Ensure required inputs are provided and correctly typed++## Dry Run Mode++Execute pipelines with mocked LLM responses to test pipeline logic, data flow, and orchestration without making API calls.++- **Mock generation** — Format-compliant mock values for constrained fields, including structured outputs+- **Configurable mock behavior** — Control mock list sizes, template handling, and response formats+- **Full pipeline execution** — Working memory, controllers, and data flow all work as in production++## Allowed-to-Fail Pipes++List specific pipe codes in `pipelex.dry_run_config.allowed_to_fail_pipes` so dry-run validation can tolerate expected failures without failing the overall validation pass.++## CLI Usage++- `pipelex validate` — Static validation+- `pipelex run pipe my_pipe --dry-run` — Dry run execution+- `pipelex run pipe my_pipe --dry-run --mock-inputs` — Generate synthetic inputs++For configuration details, see [Dry Run Configuration](../7-configuration/config-pipeline-validation/dry-run-config.md).diff --git a/docs/home/1-features/web-search.md b/docs/home/1-features/web-search.mdnew file mode 100644index 000000000..d8a5f4a52--- /dev/null+++ b/docs/home/1-features/web-search.md@@ -0,0 +1,23 @@+---+title: Web Search+---++# Web Search++Structured web search integrated into your pipelines.++## Overview++PipeSearch brings web search directly into your methods. Results come back as structured data with source citations, making them ready for downstream processing by LLMs or other pipes. Search is powered by Linkup (direct SDK) or via Pipelex Gateway.++## Key Capabilities++- **Structured results** — Search results returned as typed SearchResult concepts with an answer and sourced citations+- **Source citations** — Automatic source tracking for provenance and attribution+- **Pipeline integration** — Feed search results directly into PipeLLM for grounded generation with real-time data++## Usage in Pipelines++Use PipeSearch in a PipeSequence to retrieve information from the web and then process it with an LLM. The search results are stored in working memory as SearchResult concepts, available to downstream pipes.++See [PipeSearch reference](../6-build-reliable-ai-workflows/pipes/pipe-operators/PipeSearch.md).diff --git a/docs/home/1-releases/chicago.md b/docs/home/1-releases/chicago.mddeleted file mode 100644index 01ae2893a..000000000--- a/docs/home/1-releases/chicago.md+++ /dev/null@@ -1,118 +0,0 @@-----title: "Chicago Release"------# Pipelex v0.18.0 "Chicago"--**The AI method framework that just works.**--## Why Pipelex--Pipelex eliminates the complexity of building AI-powered applications. Instead of managing multiple SDKs, API configurations, and infrastructure concerns, developers focus on what matters: their application logic.--- **One framework** for prompts, pipelines, and structured outputs-- **One API key** for dozens of AI models-- **One method** from prototype to production-------## A Major Milestone--Three months after our first public launch in San Francisco, Pipelex reaches a new level of maturity with the "Chicago" release (currently in beta-test). This version delivers on our core promise: **enabling every developer to build AI methods that are reliable, flexible, and production-ready**.--Version 0.18.0 represents our most significant release to date, addressing the three priorities that emerged from real-world usage:--- **Universal model access** — one API key for all leading AI models-- **State-of-the-art document extraction** — deployable anywhere-- **Visual pipeline inspection** — full transparency into your methods-------## What's New--### Pipelex Gateway--A fully managed infrastructure providing unified access to AI models through a single API key. Built on enterprise-grade architecture, the Gateway:--- Fetches model configurations remotely — always access the latest models without updating Pipelex-- Supports an extensive catalog of models from OpenAI, Google, Anthropic, Mistral, and more-- Includes the latest image generation capabilities: GPT-Image-1.5, Nano Banana, Nano Banana Pro, and Flux-2-pro--[Join the waitlist](https://go.pipelex.com/waitlist) to get early access to the Gateway.--!!! info "Full Model Catalog"- Browse all supported models in our [Gateway Models documentation](https://docs.pipelex.com/home/5-setup/gateway-models/).-------### Document Extraction--From simple text extraction to advanced document understanding—Pipelex handles it all. Basic PDF text extraction works out of the box (via pypdfium2), but real documents demand more: OCR for scanned pages, layout analysis for complex structures, image extraction, and VLM-powered understanding when needed.--Unlike LLM APIs (partly standardized around OpenAI's completions API), the OCR landscape is fragmented. Pipelex solves this with a unified interface: swap providers by changing your PipeExtract config, no code changes required.--| Provider | Description |-|----------|-------------|-| **Azure Document Intelligence** | Enterprise-grade OCR with high accuracy for complex layouts, tables, and handwriting |-| **docling** | IBM's open-source extraction library with local CPU processing and optional GPU acceleration |-| **Mistral OCR** | Industry-leading document understanding for media, text, tables, and equations |-| **Deepseek-OCR** | Open-source model optimized for markdown extraction from images |--**Documents in LLM Prompts** — Include PDFs directly in your prompts using `@variable` syntax. Single documents, multiple documents, mixed with text and images.-------### Execution Graph Visualization--Full transparency into pipeline execution:--- **Interactive HTML visualization** — Inspect any pipeline with a local ReactFlow-based interface-- **Mermaid chart export** — Render pipeline diagrams anywhere: VS Code, GitHub, web applications-- **Step-by-step data inspection** — View JSON, HTML preview, images, and embedded PDFs at each execution stage--{ width="400" }-------## Additional Capabilities--### Telemetry & Observability--Production-ready monitoring with **Langfuse** and **OpenTelemetry** integration.--### Open-Source Model Support--Broad support for open-source AI:--- **Hugging Face Inference** — including qwen-image for text-to-image-- **Scaleway** — Deepseek R1, Llama 3.3, Qwen3, GPT-OSS-- **Groq** — Llama-4, Kimi-K2-Instruct-- **Via the Pipelex Gateway** — Phi-4, Kimi-K2-Thinking, Mistral-Large-3, Deepseek-OCR--### Developer Experience--- **Pure MTHDS Methods** — Inline concept structures now support nested concepts, making Pipelex fully usable with just `.mthds` files and the CLI—no Python code required-- **Deep Integration Options** — Generate Pydantic BaseModels from your declarative concepts for full IDE autocomplete, type checking, and validation (TypeScript Zod structures coming soon)-- **PipeCompose Construct Mode** — Build `StructuredContent` objects deterministically without an LLM, composing outputs from working memory variables, fixed values, templates, and nested structures-- **Cloud Storage for Artifacts** — Store generated images and extracted pages on AWS S3 or Google Cloud Storage with public or signed URLs-- **Python 3.14 Support**-------## Getting Started--```bash-pip install pipelex --pre-```--Then run `pipelex init` to configure your environment and obtain your Gateway API key at [app.pipelex.com](https://app.pipelex.com/).--!!! tip "Documentation"- Explore our comprehensive guides at [docs.pipelex.com](https://docs.pipelex.com/)-------*Ready to build AI methods that just work?*--[Join the Waitlist](https://go.pipelex.com/waitlist){ .md-button .md-button--primary }-[Documentation](https://docs.pipelex.com){ .md-button }diff --git a/docs/home/10-advanced-customizations/index.md b/docs/home/10-advanced-customizations/index.mdindex 84cc48580..d7124d99e 100644--- a/docs/home/10-advanced-customizations/index.md+++ b/docs/home/10-advanced-customizations/index.md@@ -14,7 +14,6 @@ There are two main ways to inject custom implementations:from pipelex import Pipelexpipelex = Pipelex.make(- template_provider=MyTemplateProvider(),reporting_delegate=MyReportingDelegate(),secrets_provider=MySecretsProvider(),content_generator=MyContentGenerator(),@@ -28,7 +27,7 @@ pipelex = Pipelex.make(from pipelex.hub import PipelexHubhub = PipelexHub()-hub.set_template_provider(MyTemplateProvider())+hub.set_reporting_delegate(MyReportingDelegate())# ... and so on for other components```@@ -63,12 +62,6 @@ When a feature is disabled, the corresponding NoOp implementation is used automaPipelex supports injection of the following components:-**Template Provider** (`TemplateLibrary`)--- Protocol: `TemplateProviderAbstract`-- Default: `TemplateLibrary`-- [Details](template-provider-injection.md)-**Reporting Delegate** (`ReportingManager`)- Protocol: `ReportingProtocol`diff --git a/docs/home/10-advanced-customizations/plugin-injection.md b/docs/home/10-advanced-customizations/plugin-injection.mddeleted file mode 100644index dad784bac..000000000--- a/docs/home/10-advanced-customizations/plugin-injection.md+++ /dev/null@@ -1,4 +0,0 @@-# Content Generator Injection--!!! warning "Under Construction"- This section is currently under development.diff --git a/docs/home/10-advanced-customizations/template-provider-injection.md b/docs/home/10-advanced-customizations/template-provider-injection.mddeleted file mode 100644index 920498b61..000000000--- a/docs/home/10-advanced-customizations/template-provider-injection.md+++ /dev/null@@ -1,4 +0,0 @@-# Template Provider Injection--!!! warning "Under Construction"- This section is currently under development.diff --git a/docs/home/2-get-started/pipe-builder.md b/docs/home/2-get-started/pipe-builder.mddeleted file mode 100644index 715bad6e4..000000000--- a/docs/home/2-get-started/pipe-builder.md+++ /dev/null@@ -1,105 +0,0 @@-----title: "Generate Methods with Pipe Builder"--------## Install--```bash-pip install pipelex-```--```bash-pipelex init-```--During the second step of the initialization, we recommend, for a quick start, to use the Pipelex Gateway. Get your API key at [app.pipelex.com](https://app.pipelex.com/) with free credits (no credit card required, limited time offer). If you have questions, join our [Discord](https://go.pipelex.com/discord).--If you want to bring your own API keys, see [Configure AI Providers](../../home/5-setup/configure-ai-providers.md) for details.--# Generate methods with Pipe Builder--The fastest way to create production-ready AI methods is with the Pipe Builder. Just describe what you want, and Pipelex generates complete, validated pipelines.--```bash-pipelex build pipe "Take a CV and Job offer in PDF, analyze if they match and generate 5 questions for the interview"-```--The pipe builder generates three files in a numbered directory (e.g., `results/pipeline_01/`):--1. **`bundle.mthds`** - Complete production-ready script in our Pipelex language with domain definition, concepts, and pipe steps-2. **`inputs.json`** - Template describing the **mandatory** inputs for running the pipe-3. **`run_{pipe_code}.py`** - Ready-to-run Python script that you can customize and execute--!!! tip "Pipe Builder Requirements"- For now, the pipe builder requires access to **Claude 4.5 Sonnet**, either through Pipelex Inference, or using your own key through Anthropic, Amazon Bedrock or BlackboxAI. Don't hesitate to join our [Discord](https://go.pipelex.com/discord) to get a key, otherwise, you can also create the methods yourself, following our [documentation guide](./write-methods-manually.md).--!!! info "Learn More"- Want to understand how the Pipe Builder works under the hood? See [Pipe Builder Deep Dive](../9-tools/pipe-builder.md) for the full explanation of its multi-step generation process.--## Run your pipeline--**Option 1: CLI**--```bash-pipelex run bundle results/cv_match.mthds --inputs inputs.json-```--The `--inputs` file should be a JSON dictionary where keys are input variable names and values are the input data. Learn more on how to provide the inputs of a pipe: [Providing Inputs to Pipelines](../../home/6-build-reliable-ai-workflows/pipes/provide-inputs.md)--**Option 2: Python**--This requires having the `.mthds` file or your pipe inside the directory where the Python file is located.--```python-import json-from pipelex.pipeline.runner import PipelexRunner-from pipelex.pipelex import Pipelex--# Initialize Pipelex-Pipelex.make()--# Load the inputs from the JSON file-with open("inputs.json", "r", encoding="utf-8") as json_file:- inputs = json.load(json_file)--# Execute the pipeline-runner = PipelexRunner()-response = await runner.execute_pipeline(- pipe_code="analyze_cv_and_prepare_interview",- inputs=inputs-)-pipe_output = response.pipe_output--print(pipe_output.main_stuff)--```--## IDE Support--We **highly** recommend installing our own extension for MTHDS files into your IDE of choice. You can find it in the [Open VSX Registry](https://open-vsx.org/extension/Pipelex/pipelex) and download it directly using [this link](https://open-vsx.org/api/Pipelex/pipelex/0.2.1/file/Pipelex.pipelex-0.2.1.vsix). It's coming soon to the VS Code marketplace too and if you are using Cursor, Windsurf or another VS Code fork, you can search for it directly in your extensions tab.--## Examples--[Cookbook Examples](../../home/4-cookbook-examples/index.md) - Real-world patterns and use cases-------## Next Steps--Now that you know how to generate methods with the Pipe Builder, explore these resources:--**Learn how to Write Methods yourself**--- [:material-pencil: Write Methods Manually](./write-methods-manually.md){ .md-button .md-button--primary }-- [:material-book-open-variant: Build Reliable AI Methods](../6-build-reliable-ai-workflows/kick-off-a-methods-project.md){ .md-button .md-button--primary }--**Explore Examples:**--- [Cookbook Examples](../../home/4-cookbook-examples/index.md) - Real-world patterns and use cases--**Configure Your Setup:**--- [Configure AI Providers](../../home/5-setup/configure-ai-providers.md) - API keys, local AI, model providers-- [Project Organization](../../home/5-setup/project-organization.md) - Structure your Pipelex projectsdiff --git a/docs/home/2-get-started/write-methods-manually.md b/docs/home/2-get-started/write-methods-manually.mdindex 525cbe0e8..5b7bdeb12 100644--- a/docs/home/2-get-started/write-methods-manually.md+++ b/docs/home/2-get-started/write-methods-manually.md@@ -2,9 +2,6 @@Ready to dive deeper? This section shows you how to manually create pipelines and understand the `.mthds` language.-!!! tip "Prefer Automated Method Generation?"- If you have access to **Claude 4.5 Sonnet** (via Pipelex Inference, Anthropic, Amazon Bedrock, or BlackBox AI), you can use our **pipe builder** to generate methods from natural language descriptions. See the [Pipe Builder guide](./pipe-builder.md) to learn how to use `pipelex build pipe` commands. This tutorial is for those who want to write methods manually or understand the `.mthds` language in depth.-## Write Your First PipelineLet's build a **character generator** to understand the basics.@@ -346,7 +343,7 @@ Now that you understand the basics, explore more:**Explore Tools:**-- [Pipe Builder](../../home/9-tools/pipe-builder.md) - Generate pipelines from natural language+- [Claude Code Skills Plugin](../../home/1-features/claude-code-skills-plugin.md) - Generate pipelines from natural language- [CLI Commands](../9-tools/cli/index.md) - Command-line interface reference**Configure:**diff --git a/docs/home/3-understand-pipelex/language-spec-v0-1-0.md b/docs/home/3-understand-pipelex/language-spec-v0-1-0.mddeleted file mode 100644index f26e523ba..000000000--- a/docs/home/3-understand-pipelex/language-spec-v0-1-0.md+++ /dev/null@@ -1,184 +0,0 @@-# Pipelex (MTHDS) – Declarative AI Method Spec (v0.1.0)--**Build deterministic, repeatable AI methods using declarative TOML syntax.**--The Pipelex Language (MTHDS) uses a TOML-based syntax to define deterministic, repeatable AI methods. This specification documents version 0.1.0 of the language and establishes the canonical way to declare domains, concepts, and pipes inside `.mthds` bundles.-------## Core Idea--Pipelex is a method declaration language that gets interpreted at runtime, we already have a Python runtime (see [github.com/pipelex/pipelex](https://github.com/pipelex/pipelex)).--Pipelex lets you declare **what** your AI method should accomplish and **how** to execute it step by step. Each `.mthds` file represents a bundle where you define:--- **Concepts** (PascalCase): the structured or unstructured data flowing through your system-- **Pipes** (snake_case): operations or orchestrators that define your method-- **Domain** (named in snake_case): the topic or field of work this bundle is about--Write once in `.mthds` files. Run anywhere. Get the same results every time.-------## Semantics--Pipelex methods are **declarative and deterministic**:--- Pipes are evaluated based on their dependencies, not declaration order-- Controllers explicitly define execution flow (sequential, parallel, or conditional)--All concepts are strongly typed. All pipes declare their inputs and outputs. The runtime validates that data flowing between pipes matches the declared types before execution. Concepts are also conceptually defined, adding meaning on top of the technical typing.-------## Guarantees & Limits--**Guarantees:**--- Deterministic method execution and outputs-- Strong typing with validation before runtime--**Not supported in v0.1.0:**--- Pipe namespaces per domain--**More:**--- GitHub: [github.com/pipelex/pipelex](https://github.com/pipelex/pipelex)-------## Complete Example: CV Job Matching Method--This method analyses candidate CVs against job offer requirements to determine match quality.--```toml-domain = "cv_job_matching"-description = "Analyzing candidate CVs against job offer requirements to determine match quality."-main_pipe = "analyze_cv_job_matches"--[concept.JobRequirements]-description = "Structured representation of a job position's requirements and details."--[concept.JobRequirements.structure]-role_title = { type = "text", description = "The job title or position name", required = true }-key_responsibilities = { type = "text", description = "Main duties and responsibilities of the role", required = true }-required_qualifications = { type = "text", description = "Mandatory qualifications, skills, or experience needed", required = true }-preferred_qualifications = { type = "text", description = "Nice-to-have qualifications, skills, or experience" }-experience_level = { type = "text", description = "Required years or level of experience" }-technical_skills = { type = "text", description = "Specific technical skills or tools required" }-soft_skills = { type = "text", description = "Interpersonal or behavioral skills desired" }--[concept.CvMatchAnalysis]-description = "Assessment of how well a candidate's CV matches job requirements."--[concept.CvMatchAnalysis.structure]-overall_match_score = { type = "number", description = "Numerical score representing overall fit (0-100)", required = true }-strengths = { type = "text", description = "Areas where the candidate excels or meets requirements well", required = true }-weaknesses = { type = "text", description = "Areas where the candidate falls short or lacks requirements", required = true }-recommendation = { type = "text", description = "Final recommendation on whether to proceed with the candidate", required = true }-relevant_experience = { type = "text", description = "Summary of candidate's relevant work experience" }-skills_match = { type = "text", description = "Analysis of how candidate's skills align with job requirements" }--[pipe.analyze_cv_job_matches]-type = "PipeSequence"-description = """-Main pipeline that extracts job requirements from the job offer PDF and analyzes all candidate CVs against those requirements to determine match quality.-"""-inputs = { job_offer_pdf = "PDF", cv_pdfs = "PDF[]" }-output = "CvMatchAnalysis[]"-steps = [- { pipe = "extract_job_offer", result = "job_offer_pages" },- { pipe = "structure_job_requirements", result = "job_requirements" },- { pipe = "process_all_cvs", result = "cv_match_analyses" },-]--[pipe.extract_job_offer]-type = "PipeExtract"-description = "Extracts text content from the job offer PDF document into pages."-inputs = { job_offer_pdf = "PDF" }-output = "Page[]"-model = "@default-text-from-pdf"--[pipe.structure_job_requirements]-type = "PipeLLM"-description = """-Consolidates all pages from the job offer into a single structured job description with key requirements, qualifications, and responsibilities.-"""-inputs = { job_offer_pages = "Page[]" }-output = "JobRequirements"-model = "$retrieval"-system_prompt = """-You are an expert HR analyst specializing in extracting and structuring job requirements from job postings. Your task is to produce a structured JobRequirements object based on the provided job offer document.-"""-prompt = """-Analyze the following job offer pages and extract the key information into a structured format.--@job_offer_pages--Extract and organize the job requirements, including the role title, key responsibilities, required and preferred qualifications, experience level, technical skills, and soft skills.-"""--[pipe.process_all_cvs]-type = "PipeBatch"-description = "Processes each CV PDF concurrently to extract and analyze against job requirements."-inputs = { cv_pdfs = "PDF[]", job_requirements = "JobRequirements" }-output = "CvMatchAnalysis[]"-branch_pipe_code = "process_single_cv"-input_list_name = "cv_pdfs"-input_item_name = "cv_pdf"--[pipe.process_single_cv]-type = "PipeSequence"-description = "Processes a single CV through extraction and analysis against job requirements."-inputs = { cv_pdf = "PDF", job_requirements = "JobRequirements" }-output = "CvMatchAnalysis"-steps = [- { pipe = "extract_cv_content", result = "cv_pages" },- { pipe = "analyze_cv_match", result = "cv_match_analysis" },-]--[pipe.extract_cv_content]-type = "PipeExtract"-description = "Extracts text content from a single CV PDF into pages."-inputs = { cv_pdf = "PDF" }-output = "Page[]"-model = "@default-text-from-pdf"--[pipe.analyze_cv_match]-type = "PipeLLM"-description = """-Analyzes the CV content against the job requirements and produces a match assessment with scores, strengths, weaknesses, and overall recommendation.-"""-inputs = { cv_pages = "Page[]", job_requirements = "JobRequirements" }-output = "CvMatchAnalysis"-model = "$engineering-structured"-system_prompt = """-You are an expert HR analyst and recruiter. Your task is to analyze candidate CVs against job requirements and produce structured assessments. Be thorough, objective, and provide actionable insights.-"""-prompt = """-Analyze the following CV against the job requirements and provide a comprehensive match assessment.--@cv_pages--Job Requirements:-- Role: $job_requirements.role_title-- Key Responsibilities: $job_requirements.key_responsibilities-- Required Qualifications: $job_requirements.required_qualifications-- Preferred Qualifications: $job_requirements.preferred_qualifications-- Experience Level: $job_requirements.experience_level-- Technical Skills: $job_requirements.technical_skills-- Soft Skills: $job_requirements.soft_skills--Evaluate how well this candidate matches the job requirements.-"""-```--**What happens:**--- Extracts and structures job requirements from a job offer PDF using document extraction + LLM-- Processes all candidate CVs in parallel (batch processing)-- Each CV is extracted and analyzed against the structured job requirements using an LLM-- Produces a scored match analysis for each candidate with strengths, weaknesses, and hiring recommendations-- Demonstrates sequential orchestration, parallel processing, nested methods, and strong typing-diff --git a/docs/home/3-understand-pipelex/pipelex-paradigm/index.md b/docs/home/3-understand-pipelex/pipelex-paradigm/index.mddeleted file mode 100644index 0754ec490..000000000--- a/docs/home/3-understand-pipelex/pipelex-paradigm/index.md+++ /dev/null@@ -1,46 +0,0 @@-# The Pipelex Paradigm--Pipelex is an **open-source Python framework** for defining and running **repeatable AI methods**.--Here's what we've learned: LLMs are powerful, but asking them to do everything in one prompt is like asking a brilliant colleague to solve ten problems while juggling. The more complexity you pack into a single prompt, the more reliability drops. You've seen it: the perfect prompt that works 90% of the time until it doesn't.--The solution is straightforward: break complex tasks into focused steps. But without proper tooling, you end up with spaghetti code and prompts scattered across your codebase.--Pipelex introduces **knowledge pipelines**: a way to capture these method steps as **composable pipes**. Each pipe follows one rule: **knowledge in, knowledge out**. Unlike rigid templates, each pipe uses AI's full intelligence to handle variation while guaranteeing consistent output structure. You get **deterministic structure with adaptive intelligence**, the reliability of software with the flexibility of AI.--## Working with Knowledge and Using Concepts to Make Sense--Knowledge refers to information you input from various data sources such as documents, PDFs, images, or information output by our pipes. There are different kinds of knowledge.--### From Data Types to Concepts--In traditional programming, we work with data types: strings, integers, booleans (true/false), etc. But **knowledge work operates at a higher level.** Take for instance a *"non-compete clause from a contract"* and a *"description of a flower"*: they're both text, both are stored as strings, but they represent fundamentally different concepts. You can ask an AI to extract the duration in months from a non-compete clause. You can ask an AI to render a flower description as a Monet-style painting. But if you try the reverse, it doesn't make sense.--This is why Pipelex introduces **Concepts: typing with meaning attached.**--**Thanks to Pipelex's conceptual level of abstraction, knowledge pipelines can guarantee they make sense.**--## How *Making Sense* Translates to *Reliability*--Concretely, in Pipelex, a piece of knowledge is an object in the working memory. It could be anything, so we call that "stuff", and our Python class for it is `Stuff`.--Stuff can be pretty basic, like plain text or an image, but it can also be structured with attributes, comprise lists, include other nested stuff, you get it... the stuff's content is actually a `Pydantic BaseModel`. Also, each Stuff knows what concept it belongs to, e.g., `Text` or `NonCompeteClause` or `FlowerDescription`.--And with that we are fully equipped for Lego-style plug-n-play:--- Each pipe declares what inputs it uses, indicating the expected concept(s)-- Each pipe also declares what it outputs--So when you connect two pipes, Pipelex systematically checks that they are compatible. Actually, it's even more powerful than that: imagine you have a sequence of 5 pipes, maybe pipe #4 takes two inputs, one given from the output of previous pipe #3 and the other one from the output of pipe #1. Pipelex checks that running the previous steps will have generated the required stuff and with the required concepts.--What if you have a pipe that requires a `Text` input, to translate it to Spanish for instance, then it should also accept a `FlowerDescription`, right? Yes, the greater includes the lesser. This is expressed in Pipelex by indicating that concept `FlowerDescription` **refines** concept `Text`.--One problem that developers face when working with LLMs is that LLMs always try to answer your queries, and it pushes them to hallucinate. For instance, if you're trying to extract structured purchase details from an invoice, and there's a bug in your system so instead of receiving an invoice as input, the LLM received a picture of a flower, or nothing at all, there's a good chance it will generate a 100% hallucinated mock invoice. Pipelex prevents this kind of bugs, first by making sure the pipeline makes sense a priori, but it can also check any input for compatibility with the expected concept.--**By letting you clearly assign concepts to the input and output stuff of your pipes, Pipelex makes sure that your pipeline makes sense, that it works in theory, and detects any failure of meaning at the earliest stage possible in practice.**--## Who Defines the Concepts?--***You* define *your* concepts!**--Apart from a few very basic concepts (`Text`, `Image`, etc.), you can and you should define the concepts you work with. And that's a big win: the concepts you define make up the glossary of the domain you are working on. That's where you remove any ambiguity, because the same word can mean different things, and even the same concept can imply different things in various settings.diff --git a/docs/home/5-setup/configure-ai-providers.md b/docs/home/5-setup/configure-ai-providers.mdindex fd35a51b3..2b25d3daa 100644--- a/docs/home/5-setup/configure-ai-providers.md+++ b/docs/home/5-setup/configure-ai-providers.md@@ -173,7 +173,7 @@ Learn more in our [Inference Backend Configuration](../../home/7-configuration/cNow that you have your backend configured:1. **Organize your project**: [Project Organization](./project-organization.md)-2. **Learn the concepts**: [Writing Methods Tutorial](../../home/2-get-started/pipe-builder.md)+2. **Learn the concepts**: [Writing Methods Tutorial](../../home/2-get-started/write-methods-manually.md)3. **Explore examples**: [Cookbook Repository](https://github.com/Pipelex/pipelex-cookbook/tree/main)4. **Deep dive**: [Build Reliable AI Methods](../../home/6-build-reliable-ai-workflows/kick-off-a-methods-project.md)diff --git a/docs/home/5-setup/project-organization.md b/docs/home/5-setup/project-organization.mdindex ef91d2995..a4ab6fe79 100644--- a/docs/home/5-setup/project-organization.md+++ b/docs/home/5-setup/project-organization.md@@ -53,8 +53,8 @@ Learn more in our [Project Structure documentation](../../home/6-build-reliable-Now that you understand project organization:-1. **Start building**: [Get Started](../../home/2-get-started/pipe-builder.md)-2. **Learn the concepts**: [Writing Methods Tutorial](../../home/2-get-started/pipe-builder.md)+1. **Start building**: [Get Started](../../home/2-get-started/write-methods-manually.md)+2. **Learn the concepts**: [Writing Methods Tutorial](../../home/2-get-started/write-methods-manually.md)3. **Explore examples**: [Cookbook Repository](https://github.com/Pipelex/pipelex-cookbook/tree/main)4. **Deep dive**: [Build Reliable AI Methods](../../home/6-build-reliable-ai-workflows/kick-off-a-methods-project.md)diff --git a/docs/home/6-build-reliable-ai-workflows/concepts/inline-structures.md b/docs/home/6-build-reliable-ai-workflows/concepts/inline-structures.mdindex 7d82053f8..160ceb8a7 100644--- a/docs/home/6-build-reliable-ai-workflows/concepts/inline-structures.md+++ b/docs/home/6-build-reliable-ai-workflows/concepts/inline-structures.md@@ -306,5 +306,5 @@ See [Python StructuredContent Classes](python-classes.md) for advanced features.- [Define Your Concepts](define_your_concepts.md) - Learn about concept semantics and naming- [Python StructuredContent Classes](python-classes.md) - Advanced features with Python-- [Writing Methods Tutorial](../../2-get-started/pipe-builder.md) - Get started with structured outputs+- [Writing Methods Tutorial](../../2-get-started/write-methods-manually.md) - Get started with structured outputsdiff --git a/docs/home/6-build-reliable-ai-workflows/concepts/native-concepts.md b/docs/home/6-build-reliable-ai-workflows/concepts/native-concepts.mdindex 82a08c686..e591db861 100644--- a/docs/home/6-build-reliable-ai-workflows/concepts/native-concepts.md+++ b/docs/home/6-build-reliable-ai-workflows/concepts/native-concepts.md@@ -326,5 +326,5 @@ prompt = "What is $topic?"- [Define Your Concepts](define_your_concepts.md) - Learn about concept semantics- [Inline Structures](inline-structures.md) - Add structure to refined concepts- [Python StructuredContent Classes](python-classes.md) - Advanced customization-- [Writing Methods Tutorial](../../2-get-started/pipe-builder.md) - Use native concepts in pipelines+- [Writing Methods Tutorial](../../2-get-started/write-methods-manually.md) - Use native concepts in pipelinesdiff --git a/docs/home/6-build-reliable-ai-workflows/concepts/python-classes.md b/docs/home/6-build-reliable-ai-workflows/concepts/python-classes.mdindex dc19439c7..b8e3b9b77 100644--- a/docs/home/6-build-reliable-ai-workflows/concepts/python-classes.md+++ b/docs/home/6-build-reliable-ai-workflows/concepts/python-classes.md@@ -255,5 +255,6 @@ Product = "A product in the catalog"- [Inline Structures](inline-structures.md) - Fast prototyping with TOML- [Define Your Concepts](define_your_concepts.md) - Learn about concept semantics and naming-- [Writing Methods Tutorial](../../2-get-started/pipe-builder.md) - Get started with structured outputs+<!-- path verified: resolves to docs/home/2-get-started/write-methods-manually.md -->+- [Writing Methods Tutorial](../../2-get-started/write-methods-manually.md) - Get started with structured outputsdiff --git a/docs/home/6-build-reliable-ai-workflows/concepts/refining-concepts.md b/docs/home/6-build-reliable-ai-workflows/concepts/refining-concepts.mdindex de5cf0021..036b7ebfc 100644--- a/docs/home/6-build-reliable-ai-workflows/concepts/refining-concepts.md+++ b/docs/home/6-build-reliable-ai-workflows/concepts/refining-concepts.md@@ -277,15 +277,13 @@ Understanding how refined concepts interact with pipe inputs is crucial.### How Refinement Affects Type Checking!!! important "Key Rule"- A pipe that accepts a **base concept** will **NOT** accept concepts that refine it.+ A pipe that accepts a **base concept** will also accept any concept that **refines** it. Refined concepts are substitutable for their parent — this is standard subtype compatibility.```toml[pipe.extract_text]-inputs = { document = "Document" } # Only accepts Document, not Invoice or Contract+inputs = { document = "Document" } # Accepts Document, Invoice, Contract, or any concept that refines Document```- If you want a pipe to accept both a base concept and its refinements, you must explicitly define the pipe to accept the refined concepts or use a more general approach.-### Practical Example```toml@@ -295,19 +293,19 @@ refines = "Document"[concept.Contract]refines = "Document"-# This pipe only accepts generic documents+# This pipe accepts Document and any concept that refines it (Invoice, Contract, etc.)[pipe.extract_from_document]type = "PipeExtract"inputs = { document = "Document" }-output = "Page"+output = "Page[]"-# This pipe only accepts Invoices+# This pipe accepts Invoice (and any concept that refines Invoice)[pipe.process_invoice]type = "PipeLLM"inputs = { invoice = "Invoice" }output = "InvoiceData"-# This pipe only accepts Contracts+# This pipe accepts Contract (and any concept that refines Contract)[pipe.process_contract]type = "PipeLLM"inputs = { contract = "Contract" }@@ -316,9 +314,9 @@ output = "ContractData"In this setup:-- `extract_from_document` expects exactly `Document` (not `Invoice` or `Contract`)-- `process_invoice` expects exactly `Invoice`-- `process_contract` expects exactly `Contract`+- `extract_from_document` accepts `Document`, `Invoice`, `Contract`, or any other concept that refines `Document`+- `process_invoice` accepts `Invoice` or any concept that refines `Invoice`+- `process_contract` accepts `Contract` or any concept that refines `Contract`## Best Practicesdiff --git a/docs/home/6-build-reliable-ai-workflows/pipe-builder.md b/docs/home/6-build-reliable-ai-workflows/pipe-builder.mddeleted file mode 100644index 5a07926ad..000000000--- a/docs/home/6-build-reliable-ai-workflows/pipe-builder.md+++ /dev/null@@ -1,185 +0,0 @@-# Pipe Builder--Pipelex provides powerful tools to automatically generate complete, working pipelines from natural language requirements. This feature leverages AI to translate your ideas into fully functional pipeline code, dramatically speeding up development.--!!! tip "Pipe Builder Requirements"- For now, the pipe builder requires access to **Claude 4.5 Sonnet**, either through Pipelex Inference, or using your own key through Anthropic, Amazon Bedrock or BlackboxAI. Don't hesitate to join our [Discord](https://go.pipelex.com/discord) to get a key or see [Configure AI Providers](../../home/5-setup/configure-ai-providers.md) for details. Otherwise, you can also create the methods yourself, following our [documentation guide](./kick-off-a-methods-project.md).--## Overview--The pipeline creation system can generate pipelines in different modes depending on your needs - from quick one-shot generation to validated, production-ready pipelines that have been automatically tested and fixed.--## Build Pipe--Generate a validated pipeline with automatic fixing of deterministic issues:--```bash-pipelex build pipe "BRIEF IN NATURAL LANGUAGE" [OPTIONS]-```--This command runs a validation/fix loop to ensure the generated pipeline is correct and runnable. It automatically detects and corrects common issues.--**What Gets Generated:**--By default, the build command creates a numbered directory with three files:--1. **`bundle.mthds`** - Your complete pipeline definition with domain, concepts, and pipes-2. **`inputs.json`** - A pre-filled template showing the inputs your pipeline expects-3. **`run_{pipe_code}.py`** - A ready-to-run Python script you can customize and execute--After generation, you can fill in the `inputs.json` template with your actual data and run the pipeline. For detailed guidance on preparing and formatting inputs, see [Providing Inputs to Pipelines](./pipes/provide-inputs.md).--**Examples:**--```bash-# Default: creates results/pipeline_01/ with all three files-pipelex build pipe "Take a photo as input, and render the opposite of the photo"--# Custom name: creates results/photo_inverter_01/ with all three files-pipelex build pipe "Take a photo as input, and render the opposite of the photo" \- -o photo_inverter--# Single file only: creates results/photo_inverter_01.mthds-pipelex build pipe "Take a photo as input, and render the opposite of the photo" \- -o photo_inverter --no-extras--# Custom directory: creates custom_dir/pipeline_01/-pipelex build pipe "Take a photo as input, and render the opposite of the photo" \- --output-dir custom_dir-```--**Options:**--- `-o, --output-name`: Base name for the generated file or directory (without extension)-- `--output-dir`: Directory where files will be generated (default: `results`)-- `--no-extras`: Skip generating `inputs.json` and runner, only generate the `.mthds` bundle-- `--no-output`: Build the pipeline but don't save any files--## Quick Start Example--The simplest way to create a pipeline is to use the `build pipe` command with a clear description:--```bash-pipelex build pipe "Given an expense report, apply company rules and validate compliance"-```--This will:--1. Analyze your requirements-2. Generate a complete pipeline with appropriate concepts and pipes-3. Validate the pipeline for correctness-4. Fix any deterministic issues automatically-5. Save the working pipeline--## Best Practices--When creating pipelines with natural language:--**Be Specific About Inputs and Outputs:**--- ✅ Good: "Take a PDF invoice as input and extract the total amount, vendor name, and date"-- ❌ Vague: "Process invoices"--**Describe the Transformation:**--- ✅ Good: "Analyze sentiment of customer reviews and categorize as positive, negative, or neutral"-- ❌ Vague: "Do something with reviews"--**Mention Data Types When Relevant:**--- ✅ Good: "Extract text from a PDF, then summarize it into 3 bullet points"-- ❌ Unclear: "Summarize documents"--## What Gets Generated--When you run a build command, Pipelex automatically creates:--- **Domain definition**: The namespace for your pipeline-- **Concepts**: Structured data types for inputs and outputs-- **Pipes**: The processing steps and LLM operations-- **Python structures**: When structured output is needed (saved alongside the `.mthds` file with `_struct.py` suffix)--All generated pipelines follow Pipelex best practices and conventions automatically.--## Next Steps--After generating your pipeline:--1. **Review the generated `.mthds` file** to understand the structure-2. **Test the pipeline** using the generated example code-3. **Iterate if needed** by modifying the natural language description and regenerating-4. **Customize** the pipeline by editing the `.mthds` file directly for fine-tuning--## How It Works--The Pipe Builder is itself a Pipelex pipeline (`builder.pipe_builder`) that transforms your natural language brief into a complete, validated pipeline through a multi-stage process, demonstrating the power and flexibility of the framework. Here's what happens under the hood:--### 1. Draft the Plan--The builder analyzes your brief and creates a pseudo-code plan describing:-- The sequence of pipes needed-- Input and output variables for each step-- Where structured outputs are needed-- Which orchestration controllers to use (Sequence, Batch, Parallel, Condition)--### 2. Define Concepts--From the plan, the builder identifies and defines the concepts (data types) needed:-- Analyzes what inputs and outputs are required-- Creates concept definitions with clear descriptions-- Determines which concepts need structure vs. simple text-- Reuses concepts where possible (e.g., "Article" instead of "LongArticle", "ShortArticle")--### 3. Structure Concepts--For concepts that need structure, the builder:-- Designs field definitions with appropriate types (text, integer, boolean, number, date, list, dict)-- Determines which fields are required vs. optional-- Creates inline structures or Python classes as needed--### 4. Draft and Review Flow--The builder designs the complete flow architecture:-- Maps out pipe controllers (PipeSequence, PipeBatch, PipeParallel, PipeCondition)-- Assigns pipe operators (PipeLLM, PipeExtract, PipeImgGen, PipeSearch) to specific tasks-- Ensures variables flow correctly through the memory system-- Reviews the flow for consistency and fixes any issues--### 5. Design Pipe Signatures--Creates the contracts for each pipe:-- Assigns unique pipe codes (snake_case, verb-based)-- Defines inputs and outputs with proper concept types-- Handles multiplicity (single items, lists, fixed-size arrays)-- Identifies pipe dependencies--### 6. Detail Pipe Specifications--For each pipe signature, generates the complete specification:-- **PipeLLM**: Creates prompts and configures LLM settings-- **PipeExtract**: Sets up document/image extraction-- **PipeImgGen**: Configures image generation from prompts-- **PipeSearch**: Configures web search with structured results-- **PipeSequence**: Defines step-by-step execution-- **PipeBatch**: Sets up concurrent processing over lists-- **PipeParallel**: Orchestrates concurrent different pipes-- **PipeCondition**: Creates conditional branching logic--### 7. Create Domain and Assemble--Finally, the builder:-- Names the domain based on your brief-- Assembles all concepts and pipes into a complete bundle-- Generates the `.mthds` file with proper syntax-- Creates Python structure files (`*_struct.py`) when needed-- Validates the pipeline and fixes deterministic issues--## Explore the Source--Want to see how the Pipe Builder works internally? Check out the source code:--- **Main pipeline**: [`pipelex/builder/builder.mthds`](https://github.com/pipelex/pipelex/tree/main/pipelex/builder/builder.mthds)-- **Pipe design**: [`pipelex/builder/pipe/pipe_design.mthds`](https://github.com/pipelex/pipelex/tree/main/pipelex/builder/pipe/pipe_design.mthds)--The Pipe Builder is a great example of a complex, multi-stage Pipelex pipeline in action.-diff --git a/docs/home/9-tools/cli/build/index.md b/docs/home/9-tools/cli/build/index.mdindex 56ecbb26b..99ec8f19b 100644--- a/docs/home/9-tools/cli/build/index.md+++ b/docs/home/9-tools/cli/build/index.md@@ -6,7 +6,6 @@ Generate pipelines, runner code, Python structures, and JSON templates from natu| Command | Description ||---------|-------------|-| [**build pipe**](pipe.md) | Generate a pipeline from natural language || [**build runner**](runner.md) | Generate Python code to run a pipe || [**build structures**](structures.md) | Generate the structures (Pydantic models) of your concepts || [**build inputs**](inputs.md) | Generate example input JSON for a pipe |diff --git a/docs/home/9-tools/cli/build/pipe.md b/docs/home/9-tools/cli/build/pipe.mddeleted file mode 100644index 92f89294e..000000000--- a/docs/home/9-tools/cli/build/pipe.md+++ /dev/null@@ -1,129 +0,0 @@-# Build Pipe--!!! warning "Beta Feature"- The Pipe Builder is currently in beta and progressing fast. Expect frequent improvements and changes.--!!! tip "Built with Pipelex"- The Pipe Builder is itself a Pipelex pipeline! This showcases the power of Pipelex: a tool that builds pipelines... using a pipeline.--The Pipe Builder is an AI-powered tool that generates Pipelex pipelines from natural language descriptions. Describe what you want to achieve, and the builder translates your requirements into a working `.mthds` file.--!!! info "Deep Dive"- Want to understand how the Pipe Builder works under the hood? See [Pipe Builder Deep Dive](../../pipe-builder.md) for the full explanation of its multi-step generation process.--## Usage--```bash-pipelex build pipe <PROMPT> [OPTIONS]-```--**Arguments:**--- `PROMPT` - Description of what the pipeline should do (required)--**Options:**--- `--output-name`, `-o` - Base name for the generated file or directory (without extension)-- `--output-dir` - Directory where files will be generated-- `--no-output` - Skip saving the pipeline to file (useful for testing)-- `--no-extras` - Skip generating `inputs.json` and `runner.py`, only generate the MTHDS file-- `--builder-pipe` - Builder pipe to use for generating the pipeline (default: `pipe_builder`)-- `--graph` / `--no-graph` - Generate execution graphs for both build process and built pipeline-- `--graph-full-data` / `--graph-no-data` - Include or exclude full serialized data in graphs (requires `--graph`)--## Output--The resulting pipeline will be saved in a folder (e.g., `pipeline_01/`) containing:--| File | Description |-|------|-------------|-| `bundle.mthds` | The pipeline definition |-| `inputs.json` | Template for pipeline inputs |-| `run_{pipe_code}.py` | Python script to run the pipeline |-| `structures/` | Generated Pydantic models for your concepts |-| `bundle_view.html` | HTML visualization of the build process and plan |-| `bundle_view.svg` | SVG visualization of the build process and plan |-| `__init__.py` | Python package init file |--The HTML and SVG files provide a visual representation of the resulting method.--## Examples--**Basic usage:**--```bash-pipelex build pipe "Given an expense report, apply company rules"-```--**Custom output name:**--```bash-pipelex build pipe "Extract data from invoices" -o invoice_extractor-```--**Custom output directory:**--```bash-pipelex build pipe "Analyze customer feedback" --output-dir ./pipelines/-```--**Generate only the MTHDS file (no extras):**--```bash-pipelex build pipe "Summarize documents" --no-extras-```--## Example Use Cases--**Document Processing:**--```bash-pipelex build pipe "Take a CV in a PDF file and a Job offer text, and analyze if they match"-```--**Data Transformation:**--```bash-pipelex build pipe "Extract structured data from invoice images"-```--**Multi-step Methods:**--```bash-pipelex build pipe "Given an RFP PDF, build a compliance matrix"-```--## Tips for Best Results--- You can be specific in your brief about inputs, outputs, data formats, or structures if you know what you need-- If you're uncertain about the details, let the AI figure it out and see what it generates-- Include any domain-specific requirements you're aware of upfront--## Current Limitations--The Pipe Builder is in active development and currently:--- Can automatically fix input/output connection errors-- May require manual adjustments for complex conditional logic or custom functions-- Validation focuses on structural correctness, not business logic--## Next Steps--After generating your pipeline:--1. **Validate it**: `pipelex validate bundle your_pipe.mthds` - See [Validate Commands](../validate.md)-2. **Run it**: `pipelex run bundle your_pipe.mthds` - See [Run Command](../run.md)-3. **Generate a runner**: `pipelex build runner bundle your_pipe.mthds` - See [Build Runner](runner.md)-4. **Generate structures**: `pipelex build structures ./` - See [Build Structures](structures.md)-5. **Generate input template**: `pipelex build inputs bundle your_pipe.mthds` - See [Build Inputs](inputs.md)-6. **View output structure**: `pipelex build output bundle your_pipe.mthds` - See [Build Output](output.md)--## Related Documentation--- [Pipe Builder Deep Dive](../../pipe-builder.md) - How the builder works under the hood-- [Design and Run Pipelines](../../../6-build-reliable-ai-workflows/pipes/index.md)-- [Build Inputs](inputs.md) - Generate example input JSON-- [Build Output](output.md) - Generate example output JSON-- [Pipe Operators](../../../6-build-reliable-ai-workflows/pipes/pipe-operators/index.md)-- [Pipe Controllers](../../../6-build-reliable-ai-workflows/pipes/pipe-controllers/index.md)-diff --git a/docs/home/9-tools/cli/build/runner.md b/docs/home/9-tools/cli/build/runner.mdindex fea7081bb..0d9d8c07b 100644--- a/docs/home/9-tools/cli/build/runner.md+++ b/docs/home/9-tools/cli/build/runner.md@@ -96,7 +96,6 @@ After generating the runner file:## Related Documentation-- [Build Pipe](pipe.md) - Generate pipelines from natural language- [Build Structures](structures.md) - Generate Pydantic models separately- [Build Inputs](inputs.md) - Generate example input JSON for a pipe- [Build Output](output.md) - Generate example output JSON for a pipediff --git a/docs/home/9-tools/cli/build/structures.md b/docs/home/9-tools/cli/build/structures.mdindex 60551cc20..cf5e6084d 100644--- a/docs/home/9-tools/cli/build/structures.md+++ b/docs/home/9-tools/cli/build/structures.md@@ -85,7 +85,6 @@ class CandidateProfile(StructuredContent):## Related Documentation-- [Build Pipe](pipe.md) - Generate pipelines from natural language- [Build Runner](runner.md) - Generate Python runner scripts- [Build Inputs](inputs.md) - Generate example input JSON for a pipe- [Build Output](output.md) - Generate example output JSON for a pipediff --git a/docs/home/9-tools/cli/index.md b/docs/home/9-tools/cli/index.mdindex bf86bd5cf..4f950cb79 100644--- a/docs/home/9-tools/cli/index.md+++ b/docs/home/9-tools/cli/index.md@@ -42,7 +42,6 @@ The Pipelex CLI is organized into several command groups:## Related Documentation-- [Build Pipe](build/pipe.md) - Generate pipelines from natural language- [Configure AI Providers](../../5-setup/configure-ai-providers.md) - Set up LLM backends- [Design and Run Pipelines](../../6-build-reliable-ai-workflows/pipes/index.md) - Pipeline development guidediff --git a/docs/home/9-tools/pipe-builder.md b/docs/home/9-tools/pipe-builder.mddeleted file mode 100644index d68ca785b..000000000--- a/docs/home/9-tools/pipe-builder.md+++ /dev/null@@ -1,120 +0,0 @@-# Pipe Builder--!!! warning "Beta Feature"- The Pipe Builder is currently in beta and progressing fast. Expect frequent improvements and changes.--The Pipe Builder is an AI-powered tool that generates complete Pipelex pipelines from natural language descriptions. Describe what you want to achieve, and the builder creates a production-ready `.mthds` file with concepts, pipes, and all the necessary structure.--## What It Does--The Pipe Builder takes a brief description like:--> "Take a CV and Job offer in PDF, analyze if they match and generate 5 questions for the interview"--And generates:--- **Domain concepts** - Data structures for your method (e.g., `CVAnalysis`, `InterviewQuestion`)-- **Pipe operators** - LLM calls, extractions, image generation steps-- **Pipe controllers** - Sequences, batches, parallel branches, conditions to orchestrate the flow-- **A complete bundle** - Ready to validate and run--## How It Works--!!! tip "Built with Pipelex"- The Pipe Builder is itself a Pipelex pipeline! This showcases the power of Pipelex: a tool that builds pipelines... using a pipeline.--The builder follows a multi-step process:--### 1. Draft the Plan--First, the AI analyzes your brief and creates a narrative plan describing:--- The sequence of steps needed-- Inputs and outputs for each step-- Where structured data or lists are needed-- Which orchestration patterns to use (sequence, batch, parallel, condition)--### 2. Draft the Concepts--Based on the plan, it identifies and defines the concepts needed:--- What data structures are required-- Which fields each concept needs-- How concepts relate to each other-- Which native concepts to reuse (Text, Image, PDF, etc.)--### 3. Structure the Concepts--The concept drafts are formalized into proper Pipelex concept specifications with:--- Field names and types-- Descriptions-- Required/optional flags-- Default values--### 4. Design the Flow--The plan is translated into a structured flow with:--- Pipe operators (PipeLLM, PipeExtract, PipeImgGen, PipeSearch)-- Pipe controllers (PipeSequence, PipeBatch, PipeParallel, PipeCondition)-- Input/output contracts for each pipe-- Memory flow between steps--### 5. Review and Refine--The flow is reviewed for consistency:--- Are inputs and outputs properly connected?-- Is the main pipe correctly identified?-- Are batches and lists handled properly?--### 6. Generate Pipe Signatures--Each pipe gets a formal signature with:--- Unique pipe code-- Description-- Input/output types with multiplicity-- Dependencies on other pipes--### 7. Assemble the Bundle--Finally, everything is assembled into a complete Pipelex bundle:--- Domain header with name and description-- All concept definitions-- All pipe definitions-- Main pipe identification--## The Builder Pipeline--The Pipe Builder is defined in [`pipelex/builder/builder.mthds`](https://github.com/Pipelex/pipelex/blob/main/pipelex/builder/builder.mthds). The main orchestrator is a `PipeSequence` called `pipe_builder` that chains together:--```-draft_the_plan → draft_the_concepts → structure_concepts → draft_flow → review_flow → design_pipe_signatures → write_bundle_header → detail_pipe_spec (batched) → assemble_pipelex_bundle_spec-```--Each step uses `PipeLLM` with carefully crafted prompts to guide the AI through the generation process.--## Using the Pipe Builder--To use the Pipe Builder, use the CLI command:--```bash-pipelex build pipe "Your description here"-```--See the [Build Pipe CLI documentation](cli/build/pipe.md) for:--- Command options-- Generated file structure-- Example use cases-- Tips for best results--## Related Documentation--- [Build Pipe CLI](cli/build/pipe.md) - Command reference and options-- [Design and Run Pipelines](../6-build-reliable-ai-workflows/pipes/index.md) - Pipeline concepts-- [Concepts](../6-build-reliable-ai-workflows/concepts/define_your_concepts.md) - Understanding concept definitions-diff --git a/docs/index.md b/docs/index.mdindex fe76ee393..9e647675d 100644--- a/docs/index.md+++ b/docs/index.md@@ -55,9 +55,8 @@ Pipelex solves these problems by:Ready to get started?-- [:material-rocket-launch: Get Started](./home/2-get-started/pipe-builder.md){ .md-button .md-button--primary }+- [:material-rocket-launch: Get Started](./home/2-get-started/write-methods-manually.md){ .md-button .md-button--primary }- [:material-book-open: Read the Know-How Graph](./home/3-understand-pipelex/viewpoint.md){ .md-button }-- [:material-lightbulb: Explore the Paradigm](./home/3-understand-pipelex/pipelex-paradigm/index.md){ .md-button }**Explore Examples:**diff --git a/docs/under-the-hood/architecture-overview.md b/docs/under-the-hood/architecture-overview.mdindex 30995febd..bfa93168c 100644--- a/docs/under-the-hood/architecture-overview.md+++ b/docs/under-the-hood/architecture-overview.md@@ -158,5 +158,4 @@ flowchart TB## Next Steps-- [:material-book-open: Understand the Pipelex Paradigm](../home/3-understand-pipelex/pipelex-paradigm/index.md){ .md-button }- [:material-cog: Explore Configuration Internals](../contribute/configuration-defaults-and-overrides.md){ .md-button }diff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.mdindex 6b85697d9..e298234ab 100644--- a/docs/under-the-hood/init-cli-flows.md+++ b/docs/under-the-hood/init-cli-flows.md@@ -31,27 +31,33 @@ These two categories are managed by separate steps. `init_config()` copies only| `pipelex init routing` | `routing` | Routing profile customization only || `pipelex init telemetry` | `telemetry` | Telemetry config template copy || `pipelex init agreement` | `agreement` | Gateway terms acceptance (no reset) |+| `pipelex init credentials` | `credentials` | Credential setup for enabled backends |-All commands except `agreement` perform a **full reset** (overwrite existing files). Config updates are not yet supported.+All commands except `agreement` and `credentials` perform a **full reset** (overwrite existing files). Config updates are not yet supported.### Inputs- **`focus`** (`InitFocus` enum): Determines which steps run. Derived from the CLI subcommand.- **`skip_confirmation`** (`bool`): When `True`, skips the interactive confirmation prompt. Used when called from `pipelex doctor --fix`.+- **`local`** (`bool`): When `True`, targets the project-level `.pipelex/` directory instead of the global `~/.pipelex/`. Maps to the `--local` CLI flag.### Outputs / Side Effects-| Artifact | Produced By | Path |-|----------|-------------|------|-| `pipelex.toml` | `init_config()` | `.pipelex/pipelex.toml` |-| `plxt.toml` | `init_config()` | `.pipelex/plxt.toml` |-| `mthds_schema.json` | `init_config()` | `.pipelex/mthds_schema.json` |-| `backends.toml` | Inference step | `.pipelex/inference/backends.toml` |-| `backends/*.toml` | Inference step | `.pipelex/inference/backends/` |-| `deck/*.toml` | Inference step | `.pipelex/inference/deck/` |-| `routing_profiles.toml` | Inference step | `.pipelex/inference/routing_profiles.toml` |-| `telemetry.toml` | Telemetry step | `.pipelex/telemetry.toml` |-| `pipelex_service.toml` | Gateway terms acceptance | `.pipelex/pipelex_service.toml` |+| Artifact | Produced By | Target Dir | Path |+|----------|-------------|------------|------|+| `pipelex.toml` | `init_config()` | Project or global | `.pipelex/pipelex.toml` |+| `plxt.toml` | `init_config()` | Project or global | `.pipelex/plxt.toml` |+| `mthds_schema.json` | `init_config()` | Project or global | `.pipelex/mthds_schema.json` |+| `backends.toml` | Inference step | Project or global | `.pipelex/inference/backends.toml` |+| `backends/*.toml` | Inference step | Project or global | `.pipelex/inference/backends/` |+| `deck/*.toml` | Inference step | Project or global | `.pipelex/inference/deck/` |+| `routing_profiles.toml` | Inference step | Project or global | `.pipelex/inference/routing_profiles.toml` |+| `telemetry.toml` | Telemetry step | Project or global | `.pipelex/telemetry.toml` |+| `.env` | Credentials step | **Always global** | `~/.pipelex/.env` (mode 0600) |+| `pipelex_service.toml` | Gateway terms acceptance | **Always global** | `~/.pipelex/pipelex_service.toml` |++!!! info "Project vs global"+ Most files are written to the target directory chosen at init time (project `.pipelex/` or global `~/.pipelex/`). The exceptions are `.env` (credentials) and `pipelex_service.toml`, which are **always** written to and read from `~/.pipelex/` — see [Gateway Terms: Always Global](#gateway-terms-always-global).---@@ -66,6 +72,9 @@ flowchart TDFOCUS -- agreement --> AGREE[_init_agreement]AGREE --> DONE([Done])+ FOCUS -- credentials --> CREDS_DIRECT["prompt_credentials<br/>Prompt for missing API keys"]+ CREDS_DIRECT --> DONE+FOCUS -- "all / config / inference / routing / telemetry" --> NEEDS[determine_needs]NEEDS --> CONFIRM{User confirms?}CONFIRM -- No --> CANCEL([Cancelled])@@ -89,10 +98,15 @@ flowchart TDCOPY_INF --> CUST_BE[customize_backends_config<br/>Interactive backend selection]CUST_BE --> CHK_RT{check_routing?}CHK_RT -- "No (auto-route)" --> CUST_RT[customize_routing_profile<br/>Auto-routing based on selection]- CHK_RT -- "Yes (focus=routing)" --> S3- CUST_RT --> S3+ CUST_RT --> S25+ CHK_RT -- "Yes (focus=routing)" --> S25++ S2 -- No --> S25- S2 -- No --> S3+ S25{check_credentials?}+ S25 -- Yes --> CREDS["prompt_credentials<br/>Prompt for missing API keys"]+ S25 -- No --> S3+ CREDS --> S3S3{needs_routing?}S3 -- Yes --> ROUTE[customize_routing_profile<br/>Standalone routing setup]@@ -125,13 +139,13 @@ needs_telemetry = check_telemetry and (not path_exists(telemetry_config_path) orThe `check_*` flags are derived from the `focus` parameter:-| Focus | `check_config` | `check_inference` | `check_routing` | `check_telemetry` |-|-------|:-:|:-:|:-:|:-:|-| `all` | Yes | Yes | No | Yes |-| `config` | Yes | No | No | No |-| `inference` | No | Yes | No | No |-| `routing` | No | No | Yes | No |-| `telemetry` | No | No | No | Yes |+| Focus | `check_config` | `check_credentials` | `check_inference` | `check_routing` | `check_telemetry` |+|-------|:-:|:-:|:-:|:-:|:-:|+| `all` | Yes | Yes | Yes | No | Yes |+| `config` | Yes | Yes | No | No | No |+| `inference` | No | Yes | Yes | No | No |+| `routing` | No | No | No | Yes | No |+| `telemetry` | No | No | No | No | Yes |!!! info "Routing is separate from inference"`check_routing` is only `True` for `focus=routing`. When `focus=all`, routing is handled automatically as part of the inference step (Step 2), not as a standalone step.@@ -194,11 +208,15 @@ When `needs_inference` is `True` and `reset` is `True`, the inference step copieThen runs interactive customization:-1. `customize_backends_config()` — prompts user to select backends, handles gateway terms+1. `customize_backends_config()` — prompts user to select backends, handles gateway terms, and suggests IDE extension installation via `suggest_extension_install_if_needed()`2. `customize_routing_profile()` — auto-configures routing based on selected backends (**only when `check_routing` is `False`**, i.e. when routing is not the specific focus)When `focus=routing`, the inference step skips routing entirely because Step 3 handles it as a standalone operation.+### Step 2.5: Credentials Step++When `check_credentials` is `True` (for `focus` in `all`, `config`, `inference`), `prompt_credentials()` checks which backends are enabled and prompts the user for any missing API keys. Credentials are stored in `~/.pipelex/.env` with mode 0600.+### Step 3: Routing StepIf `needs_routing` is `True` (only for `focus=routing`), runs `customize_routing_profile()` as a standalone step.@@ -211,15 +229,16 @@ Copies the `telemetry.toml` template and prints instructions. No interactive pro## Scenario Matrix-| Scenario | Focus | Config Step | Inference Step | Routing Step | Gateway Terms | Telemetry Step |-|----------|-------|:-----------:|:--------------:|:------------:|:-------------:|:--------------:|-| Fresh project, full init | `all` | Copies config files | Copies templates + interactive selection | Auto (part of inference) | Via `customize_backends_config` | Copies template |-| Fresh project, config only | `config` | Copies config files | Forced (first-time detected) | Auto (part of inference) | Via `customize_backends_config` | Skipped |-| Existing project, full re-init | `all` | Overwrites config files | Resets templates + interactive selection | Auto (part of inference) | Via `customize_backends_config` | Overwrites template |-| Existing project, config only | `config` | Overwrites config files | Skipped (backends already exist) | Skipped | `_check_gateway_terms_if_needed` | Skipped |-| Existing project, inference only | `inference` | Skipped | Resets templates + interactive selection | Auto (part of inference) | Via `customize_backends_config` | Skipped |-| Existing project, routing only | `routing` | Skipped | Skipped | Resets template + interactive selection | Skipped | Skipped |-| Gateway terms only | `agreement` | Skipped | Skipped | Skipped | Direct acceptance | Skipped |+| Scenario | Focus | Config Step | Inference Step | Credentials | Routing Step | Gateway Terms | Telemetry Step |+|----------|-------|:-----------:|:--------------:|:-----------:|:------------:|:-------------:|:--------------:|+| Fresh project, full init | `all` | Copies config files | Copies templates + interactive selection | Prompted | Auto (part of inference) | Via `customize_backends_config` | Copies template |+| Fresh project, config only | `config` | Copies config files | Forced (first-time detected) | Prompted | Auto (part of inference) | Via `customize_backends_config` | Skipped |+| Existing project, full re-init | `all` | Overwrites config files | Resets templates + interactive selection | Prompted | Auto (part of inference) | Via `customize_backends_config` | Overwrites template |+| Existing project, config only | `config` | Overwrites config files | Skipped (backends already exist) | Prompted | Skipped | `_check_gateway_terms_if_needed` | Skipped |+| Existing project, inference only | `inference` | Skipped | Resets templates + interactive selection | Prompted | Auto (part of inference) | Via `customize_backends_config` | Skipped |+| Existing project, routing only | `routing` | Skipped | Skipped | Skipped | Resets template + interactive selection | Skipped | Skipped |+| Existing project, credentials only | `credentials` | Skipped | Skipped | Prompted | Skipped | Skipped | Skipped |+| Gateway terms only | `agreement` | Skipped | Skipped | Skipped | Skipped | Direct acceptance | Skipped |!!! warning "Config-Only on Existing Project"Running `pipelex init config` on a project that already has `inference/backends.toml` will overwrite config files (`pipelex.toml`, etc.) but will **not** touch the inference setup. Gateway terms are still checked via `_check_gateway_terms_if_needed`. The user's backend selection and routing are preserved.@@ -259,10 +278,191 @@ Copies the `telemetry.toml` template and prints instructions. No interactive pro| `pipelex/cli/commands/init/backends.py` | Backend customization: `customize_backends_config()`, `get_selected_backend_keys()` || `pipelex/cli/commands/init/routing.py` | Routing customization: `customize_routing_profile()` || `pipelex/cli/commands/init/telemetry.py` | Telemetry setup: `setup_telemetry()` |+| `pipelex/cli/commands/init/credentials.py` | Credential prompting: `prompt_credentials()`, `write_env_file()`, `read_env_file()` |+| `pipelex/cli/commands/init/ide_extension.py` | IDE extension suggestion: `suggest_extension_install_if_needed()` || `pipelex/cli/commands/init/ui/types.py` | `InitFocus` enum definition |---+## Config Directory Resolution++The `ConfigLoader` (singleton: `config_manager`) resolves where configuration files live. Understanding this logic is essential because bugs in directory resolution cause files to be written or read from the wrong location.++**Source:** `pipelex/system/configuration/config_loader.py`++### Three Directory Properties++| Property | Path | When it exists |+|----------|------|----------------|+| `global_config_dir` | `~/.pipelex/` | Always (created on first use) |+| `project_config_dir` | `{project_root}/.pipelex/` | Only if the directory exists on disk |+| `pipelex_config_dir` | Project if exists, else global | Always (backward-compat alias) |++### Project Root Detection++`find_project_root()` walks up from `cwd` looking for marker files:++- `.git`, `pyproject.toml`, `setup.py`, `setup.cfg`, `package.json`, `.hg`++The home directory (`~`) is explicitly excluded — even if it contains a `package.json`, it is never treated as a project root.++### File Resolution Order++`resolve_config_file(relative_path, config_dir)` uses layered resolution:++```mermaid+flowchart TD+ START([resolve_config_file]) --> EXPLICIT{config_dir<br/>provided?}+ EXPLICIT -- Yes --> USE_EXPLICIT["Return config_dir / relative_path"]+ EXPLICIT -- No --> PROJECT{project_config_dir<br/>exists?}+ PROJECT -- Yes --> FILE_EXISTS{file exists in<br/>project dir?}+ FILE_EXISTS -- Yes --> USE_PROJECT["Return project_dir / relative_path"]+ FILE_EXISTS -- No --> USE_GLOBAL["Return global_dir / relative_path"]+ PROJECT -- No --> USE_GLOBAL+```++This means a project-level file **wins** over the global one, but only if it actually exists on disk.++### Global Config Bootstrap++`ensure_global_config_exists()` creates `~/.pipelex/` with kit template files on first use (called automatically during `load_config()`). It skips all `GIT_IGNORED_CONFIG_FILES` (files like `pipelex_service.toml`) and `.DS_Store` — these are never part of the bootstrap copy.++### Config Loading Chain++`load_config()` merges configuration in this order (later values override earlier ones):++1. Package defaults (`pipelex/pipelex.toml`)+2. Global config (`~/.pipelex/pipelex.toml`)+3. Project config (`{project_root}/.pipelex/pipelex.toml`, if different from global)+4. Override files from the effective config dir (local, environment, run mode, override)++---++## Gateway Terms: Always Global++`pipelex_service.toml` is **always** written to and read from `~/.pipelex/`, never from a project directory. This is an intentional invariant.++**Why:** Gateway terms are a user-level agreement, not a per-project setting. Accepting terms once should apply everywhere.++### Write Locations++All writers explicitly target `config_manager.global_config_dir`:++| Context | Module | `mkdir` before write? |+|---------|--------|-----------------------|+| Interactive init (config step) | `init/command.py` → `_check_gateway_terms_if_needed()` | Yes |+| Interactive backends | `init/backends.py` → `customize_backends_config()` | Yes |+| Agreement step | `init/command.py` → `_init_agreement()` | Yes (in `update_service_terms_acceptance`) |+| Agent CLI | `agent_cli/commands/init_cmd.py` → `_configure_backends()` | Yes |++### Read Locations++| Context | Module | How |+|---------|--------|-----|+| Doctor | `doctor_cmd.py` → `check_models()` | `load_pipelex_service_config_if_exists(config_dir=global_config_dir)` |+| Runtime | `pipelex.py` setup | `load_pipelex_service_config_if_exists(config_dir=global_config_dir)` |++### Rules++- **`mkdir` before writing**: All write paths ensure the config directory exists before writing. Some callers call `global_config_dir.mkdir(parents=True, exist_ok=True)` explicitly, and `update_service_terms_acceptance()` itself ensures the directory exists, so every path is protected.+- **Git-ignored**: `pipelex_service.toml` is in `GIT_IGNORED_CONFIG_FILES`, so it is never copied by `init_config()` and never synced to a project directory.++**Source:** `pipelex/system/pipelex_service/pipelex_service_agreement.py`, `pipelex/system/pipelex_service/pipelex_service_config.py`++---++## Agent CLI Init++`pipelex-agent init` is the non-interactive counterpart to `pipelex init`. It runs the same steps but takes all inputs from a JSON config argument instead of interactive prompts.++**Source:** `pipelex/cli/agent_cli/commands/init_cmd.py`++### Target Directory Resolution++`_resolve_target_dir(global_)` determines where files are written:++| Flag | Target |+|------|--------|+| Default (no flag) | `{project_root}/.pipelex/` — project root detected via `find_project_root()` |+| `--global` / `-g` | `~/.pipelex/` |++If no project root is found and `--global` is not set, the command fails with an error.++### Config Input++`--config` / `-c` accepts a JSON string (inline or file path) with these optional fields:++| Field | Type | Purpose |+|-------|------|---------|+| `backends` | `list[str]` | Backend keys to enable (e.g. `"openai"`, `"anthropic"`, `"pipelex_gateway"`) |+| `primary_backend` | `str` | Required when 2+ backends selected and `pipelex_gateway` is not among them |+| `accept_gateway_terms` | `bool` | Sets gateway terms acceptance (defaults to `false` if omitted) |+| `telemetry_mode` | `str` | `"off"` (default), `"anonymous"`, or `"identified"` |++### Flow++```mermaid+flowchart TD+ START([pipelex-agent init]) --> PARSE["Parse --config JSON"]+ PARSE --> RESOLVE["Resolve target dir<br/>(project or --global)"]+ RESOLVE --> STEP1["Step 1: init_config()<br/>Copy config templates (skips inference/)"]+ STEP1 --> STEP15["Step 1.5: Copy inference templates<br/>(backends.toml, backends/*, deck/*, routing_profiles.toml)"]+ STEP15 --> STEP2["Step 2: Configure backends<br/>Enable requested backends in backends.toml"]+ STEP2 --> GW{pipelex_gateway<br/>in backends?}+ GW -- Yes --> TERMS["Write gateway terms to ~/.pipelex/<br/>(always global)"]+ GW -- No --> STEP3+ TERMS --> STEP3["Step 3: Configure routing<br/>Auto-derive routing profile"]+ STEP3 --> STEP4["Step 4: Configure telemetry<br/>Copy template + apply mode"]+ STEP4 --> OUTPUT["Output structured JSON result"]+```++!!! note "No credentials step"+ The agent CLI does **not** configure credentials. Use `pipelex-agent doctor` to check credential health, or `pipelex init credentials` for interactive credential setup.++### Key Differences from Interactive Init++| Aspect | `pipelex init` | `pipelex-agent init` |+|--------|---------------|---------------------|+| Prompts | Interactive (Rich prompts) | None — all input from `--config` JSON |+| Gateway terms | Prompted interactively | From `accept_gateway_terms` field in config |+| Output | Rich console output | Structured JSON via `agent_success()` / `agent_error()` |+| Credentials | Prompted interactively | Not configured — use `pipelex-agent doctor` or `pipelex init credentials` |+| Focus dispatch | Supports individual focus (`config`, `inference`, etc.) | Runs config, inference, routing, telemetry (no credentials) |+| Target dir default | Global (`~/.pipelex/`), use `--local` for project | Project (`{project_root}/.pipelex/`), use `--global` for global |++---++## Doctor Fix: Config Dir Handling++`pipelex doctor` and `pipelex doctor --fix` use the config directory resolution to find and fix configuration issues wherever they live.++**Source:** `pipelex/cli/commands/doctor_cmd.py`++### How Each Check Resolves Files++| Check | Resolution Method | Details |+|-------|-------------------|---------|+| `check_config_files()` | `resolve_config_file()` | Layered resolution (project > global) |+| `check_telemetry_config()` | `resolve_config_file()` | Layered resolution (project > global) |+| `check_backend_credentials()` | `resolve_config_file()` | Finds `backends.toml` wherever it lives |+| `check_backend_files()` | `resolve_config_file()` | Finds `inference/backends/` wherever it lives |+| `check_models()` gateway terms | `global_config_dir` | **Always global** — reads from `~/.pipelex/` |++### Fix Targeting++When `--fix` replaces an outdated backend file, it derives the config directory from the resolved file path:++```python+# File lives at {config_dir}/inference/backends/{name}.toml+# Walk up 3 levels to get the config_dir+resolved_config_dir = Path(backend_file_report.file_path).parent.parent.parent+replace_backend_file(backend_name, config_dir=resolved_config_dir)+```++This ensures the fix targets the same directory where the issue was found — if the broken file was in the project `.pipelex/`, the replacement goes there too, not to `~/.pipelex/`.++---+## Next Steps- [:material-cog: Configuration Internals](../contribute/configuration-defaults-and-overrides.md){ .md-button }diff --git a/mkdocs.yml b/mkdocs.ymlindex 5c744eb31..e12316443 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -91,15 +91,33 @@ extra_css:nav:- Home:- What is Pipelex?: index.md- - Releases:- - v0.18.0 "Chicago": home/1-releases/chicago.md- - Get Started:- - The Pipe Builder: home/2-get-started/pipe-builder.md- - Write Methods Manually: home/2-get-started/write-methods-manually.md- - Understand Pipelex:- - The Know-How Graph: home/3-understand-pipelex/viewpoint.md- - The Pipelex Paradigm: home/3-understand-pipelex/pipelex-paradigm/index.md- - Pipelex Language Spec v0.1.0: home/3-understand-pipelex/language-spec-v0-1-0.md+ - Getting Started: home/2-get-started/write-methods-manually.md+ - Features:+ - Overview: home/1-features/index.md+ - Declarative AI Methods:+ - MTHDS Language: home/1-features/mthds-language.md+ - Concepts & Structured Types: home/1-features/concepts.md+ - Pipe Operators: home/1-features/pipe-operators.md+ - Pipeline Orchestration: home/1-features/pipeline-orchestration.md+ - AI Capabilities:+ - Pipelex Gateway & Model Access: home/1-features/gateway.md+ - LLM Integration: home/1-features/llm-integration.md+ - Document Extraction: home/1-features/document-extraction.md+ - Image Generation: home/1-features/image-generation.md+ - Web Search: home/1-features/web-search.md+ - Developer Tools:+ - Claude Code Skills Plugin: home/1-features/claude-code-skills-plugin.md+ - CLI: home/1-features/cli.md+ - plxt Formatter & Linter: home/1-features/plxt.md+ - Execution Graph Visualization: home/1-features/execution-graph.md+ - Production & Operations:+ - Validation & Dry Run: home/1-features/validation-dry-run.md+ - Telemetry & Observability: home/1-features/telemetry.md+ - Cloud Storage: home/1-features/cloud-storage.md+ - Cost Tracking & Reporting: home/1-features/cost-tracking.md+ - Configuration & Extensibility:+ - Configuration System: home/1-features/configuration.md+ - Advanced Customizations: home/1-features/advanced-customizations.md- Cookbook Examples:- Overview: home/4-cookbook-examples/index.md- Hello World: home/4-cookbook-examples/hello-world.md@@ -122,7 +140,6 @@ nav:- Telemetry: home/5-setup/telemetry.md- Build Reliable AI Methods:- Kick off a Method Project: home/6-build-reliable-ai-workflows/kick-off-a-methods-project.md- - Pipe Builder: home/6-build-reliable-ai-workflows/pipe-builder.md- Pipelex Bundle Specification: home/6-build-reliable-ai-workflows/pipelex-bundle-specification.md- Domain: home/6-build-reliable-ai-workflows/domain.md- Concepts:@@ -184,13 +201,11 @@ nav:- Pkg: home/9-tools/cli/pkg.md- Build:- Overview: home/9-tools/cli/build/index.md- - Pipe: home/9-tools/cli/build/pipe.md- Runner: home/9-tools/cli/build/runner.md- Structures: home/9-tools/cli/build/structures.md- Inputs: home/9-tools/cli/build/inputs.md- Output: home/9-tools/cli/build/output.md- Agent CLI: home/9-tools/cli/agent-cli.md- - Pipe Builder: home/9-tools/pipe-builder.md- plxt (Formatter & Linter): home/9-tools/plxt.md- Logging: home/9-tools/logging.md- Advanced Customizations:@@ -198,11 +213,11 @@ nav:- Secrets Provider: home/10-advanced-customizations/secrets-provider-injection.md- Reporting Delegate: home/10-advanced-customizations/reporting-delegate-injection.md- Storage Provider: home/10-advanced-customizations/storage-provider-injection.md- - Template Provider: home/10-advanced-customizations/template-provider-injection.md- - Observer Provider: home/10-advanced-customizations/observer-provider-injection.md+ - Observer: home/10-advanced-customizations/observer-provider-injection.md- Content Generator: home/10-advanced-customizations/content-generator-injection.md- - Plugin Injection: home/10-advanced-customizations/plugin-injection.md- Pipe Router: home/10-advanced-customizations/pipe-router-injection.md+ - Viewpoint:+ - The Know-How Graph: home/3-understand-pipelex/viewpoint.md- Under the Hood:- Overview: under-the-hood/index.md- Architecture Overview: under-the-hood/architecture-overview.mddiff --git a/pipelex/builder/pipe/pipe_compose_spec.py b/pipelex/builder/pipe/pipe_compose_spec.pyindex 3fb022e34..e7a121a7b 100644--- a/pipelex/builder/pipe/pipe_compose_spec.py+++ b/pipelex/builder/pipe/pipe_compose_spec.py@@ -1,6 +1,6 @@from typing import Any, Literal-from pydantic import Field, field_validator, model_validator+from pydantic import ConfigDict, Field, field_validator, model_validatorfrom pydantic.json_schema import SkipJsonSchemafrom rich.console import Groupfrom rich.panel import Panel@@ -91,6 +91,8 @@ class PipeComposeSpec(PipeSpec):- NEVER use templates to manually replicate object attributes"""+ model_config = ConfigDict(populate_by_name=True)+type: SkipJsonSchema[Literal["PipeCompose"]] = "PipeCompose"pipe_category: SkipJsonSchema[Literal["PipeOperator"]] = "PipeOperator"diff --git a/pipelex/builder/pipe/pipe_spec.py b/pipelex/builder/pipe/pipe_spec.pyindex 76068354e..9a5920eb2 100644--- a/pipelex/builder/pipe/pipe_spec.py+++ b/pipelex/builder/pipe/pipe_spec.py@@ -1,7 +1,7 @@import refrom typing import Any-from pydantic import Field, field_validator+from pydantic import ConfigDict, Field, field_validatorfrom rich.console import Groupfrom rich.table import Tablefrom rich.text import Text@@ -36,6 +36,8 @@ class PipeSpec(StructuredContent):output = "Image[5]" # produces exactly 5 images"""+ model_config = ConfigDict(extra="forbid")+pipe_code: str = Field(description="Unique pipe identifier. Must be snake_case.", json_schema_extra={"mock_format": MockFormat.SNAKE_CASE})type: Any = Field(description=(diff --git a/pipelex/cli/agent_cli/commands/concept_cmd.py b/pipelex/cli/agent_cli/commands/concept_cmd.pyindex 9df0bf528..941307be8 100644--- a/pipelex/cli/agent_cli/commands/concept_cmd.py+++ b/pipelex/cli/agent_cli/commands/concept_cmd.py@@ -101,6 +101,14 @@ def _parse_concept_spec_from_json(spec_data: dict[str, Any]) -> ConceptSpec:Raises:ValidationError: If validation fails."""+ # Accept common aliases for "the_concept_code"+ for alias in ("concept_code", "code", "name", "concept_name"):+ if alias in spec_data:+ if "the_concept_code" not in spec_data:+ spec_data["the_concept_code"] = spec_data.pop(alias)+ else:+ spec_data.pop(alias)+# Convert structure if present - need to add field namesif spec_data.get("structure"):structure_data = spec_data["structure"]diff --git a/pipelex/cli/agent_cli/commands/doctor_cmd.py b/pipelex/cli/agent_cli/commands/doctor_cmd.pyindex 5f8c8b39f..a8f1290d2 100644--- a/pipelex/cli/agent_cli/commands/doctor_cmd.py+++ b/pipelex/cli/agent_cli/commands/doctor_cmd.py@@ -6,10 +6,12 @@ import typerfrom pipelex.cli.agent_cli.commands.agent_output import agent_error, agent_successfrom pipelex.cli.commands.doctor_cmd import (+ ConfigLocationInfo,check_backend_credentials,check_config_files,check_models,check_telemetry_config,+ gather_config_location,)from pipelex.system.configuration.config_loader import config_manager@@ -35,7 +37,19 @@ def agent_doctor_cmd(Use --global/-g to force checking the global ~/.pipelex/ directory."""try:- config_dir = config_manager.global_config_dir if global_ else config_manager.pipelex_config_dir+ # When --global, force checking ~/.pipelex/ only; otherwise use layered resolution+ config_dir = config_manager.global_config_dir if global_ else None++ # Gather config location info (override for --global flag)+ if global_:+ config_location = ConfigLocationInfo(+ config_dir=str(config_manager.global_config_dir),+ is_project_local=False,+ project_root=None,+ global_config_dir=str(config_manager.global_config_dir),+ )+ else:+ config_location = gather_config_location()config_healthy, config_missing_count, config_message = check_config_files(config_dir=config_dir)telemetry_healthy, telemetry_message = check_telemetry_config(config_dir=config_dir)@@ -43,6 +57,7 @@ def agent_doctor_cmd(models_healthy, models_message, backend_file_reports = check_models(config_dir=config_dir)except Exception as exc:agent_error(f"Health check failed unexpectedly: {exc}", type(exc).__name__, cause=exc)+ # agent_error has NoReturnall_healthy = config_healthy and telemetry_healthy and backends_healthy and models_healthy@@ -78,7 +93,7 @@ def agent_doctor_cmd(if not config_healthy and config_missing_count > 0:recommended_actions.append("Run 'pipelex init config' to install missing configuration files")if not config_healthy and config_missing_count == 0:- recommended_actions.append("Fix validation errors in .pipelex/pipelex.toml or run 'pipelex init config'")+ recommended_actions.append(f"Fix validation errors in {config_location.config_dir}/pipelex.toml or run 'pipelex init config'")if not telemetry_healthy:recommended_actions.append(f"Run 'pipelex init telemetry' to fix telemetry: {telemetry_message}")if not backends_healthy:@@ -94,11 +109,14 @@ def agent_doctor_cmd(if not file_report.is_valid and file_report.has_kit_template:recommended_actions.append(f"Run 'pipelex doctor --fix' to replace outdated backend config: {file_report.backend_name}")elif not file_report.is_valid:- recommended_actions.append(f"Manually fix backend configuration in .pipelex/inference/backends/{file_report.backend_name}.toml")+ recommended_actions.append(+ f"Manually fix backend configuration in {config_location.config_dir}/inference/backends/{file_report.backend_name}.toml"+ )result: dict[str, Any] = {"success": True,"all_healthy": all_healthy,+ "config_location": config_location.model_dump(),"checks": {"config_files": {"healthy": config_healthy,diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.pyindex 07a2a897c..63638fc49 100644--- a/pipelex/cli/agent_cli/commands/init_cmd.py+++ b/pipelex/cli/agent_cli/commands/init_cmd.py@@ -3,6 +3,7 @@import jsonimport osimport shutil+from pathlib import Pathfrom typing import Annotated, Any, castimport typer@@ -55,7 +56,7 @@ def _parse_config_arg(config_arg: str | None) -> dict[str, Any]:return {}-def _resolve_target_dir(global_: bool) -> str:+def _resolve_target_dir(global_: bool) -> Path:"""Resolve the target directory for initialization.Args:@@ -74,14 +75,54 @@ def _resolve_target_dir(global_: bool) -> str:"Use --global/-g to target the global ~/.pipelex/ directory.","ArgumentError",)- return os.path.join(project_root, ".pipelex")+ return project_root / ".pipelex"+++def _copy_inference_templates(target_dir: Path) -> None:+ """Copy inference template files to the target directory.++ init_config() skips the inference/ directory (handled independently).+ This function copies the inference templates that the agent CLI needs+ for backend and routing configuration.++ Args:+ target_dir: Target config directory (e.g. .pipelex/).+ """+ template_inference_dir = Path(str(get_kit_configs_dir())) / "inference"+ target_inference_dir = target_dir / "inference"++ # Copy backends.toml+ template_backends_path = template_inference_dir / "backends.toml"+ target_backends_path = target_inference_dir / "backends.toml"+ target_backends_path.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(template_backends_path, target_backends_path)++ # Copy backends/*.toml+ template_backends_dir = template_inference_dir / "backends"+ target_backends_dir = target_inference_dir / "backends"+ target_backends_dir.mkdir(parents=True, exist_ok=True)+ for backend_file in os.listdir(template_backends_dir):+ if backend_file.endswith(".toml"):+ shutil.copy2(template_backends_dir / backend_file, target_backends_dir / backend_file)++ # Copy deck/*.toml+ template_deck_dir = template_inference_dir / "deck"+ target_deck_dir = target_inference_dir / "deck"+ target_deck_dir.mkdir(parents=True, exist_ok=True)+ for deck_file in os.listdir(template_deck_dir):+ if deck_file.endswith(".toml"):+ shutil.copy2(template_deck_dir / deck_file, target_deck_dir / deck_file)++ # Copy routing_profiles.toml+ template_routing_path = template_inference_dir / "routing_profiles.toml"+ if template_routing_path.exists():+ shutil.copy2(template_routing_path, target_inference_dir / "routing_profiles.toml")def _configure_backends(config: dict[str, Any],backends_toml_path: str,template_backends_path: str,- target_dir: str,) -> list[str]:"""Configure backends in backends.toml based on config input.@@ -89,7 +130,6 @@ def _configure_backends(config: Parsed config dict with optional 'backends' key.backends_toml_path: Path to the user's backends.toml.template_backends_path: Path to the template backends.toml.- target_dir: Target config directory for writing service agreement.Returns:List of enabled backend keys.@@ -126,12 +166,13 @@ def _configure_backends(# Handle pipelex_gateway terms acceptanceif PipelexBackend.GATEWAY in requested_backends:accept_terms: bool = config.get("accept_gateway_terms", False)- update_service_terms_acceptance(accepted=accept_terms, config_dir=target_dir)+ config_manager.global_config_dir.mkdir(parents=True, exist_ok=True)+ update_service_terms_acceptance(accepted=accept_terms, config_dir=config_manager.global_config_dir)return requested_backends-def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any], target_dir: str) -> str:+def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any], target_dir: Path) -> str:"""Configure routing profile based on selected backends and config.Args:@@ -142,7 +183,7 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],Returns:Name of the active routing profile."""- routing_profiles_toml_path = os.path.join(target_dir, "inference", "routing_profiles.toml")+ routing_profiles_toml_path = str(target_dir / "inference" / "routing_profiles.toml")if not path_exists(routing_profiles_toml_path):agent_error("routing_profiles.toml not found after config initialization", "InitConfigError")@@ -220,7 +261,7 @@ def _configure_routing(selected_backend_keys: list[str], config: dict[str, Any],return "custom_routing"-def _configure_telemetry(target_dir: str, config: dict[str, Any]) -> str:+def _configure_telemetry(target_dir: Path, config: dict[str, Any]) -> str:"""Copy telemetry template to target directory and apply telemetry_mode if specified.Args:@@ -230,13 +271,13 @@ def _configure_telemetry(target_dir: str, config: dict[str, Any]) -> str:Returns:The telemetry mode that was set."""- telemetry_config_path = os.path.join(target_dir, TELEMETRY_CONFIG_FILE_NAME)- template_path = os.path.join(str(get_kit_configs_dir()), TELEMETRY_CONFIG_FILE_NAME)+ telemetry_config_path = target_dir / TELEMETRY_CONFIG_FILE_NAME+ template_path = Path(str(get_kit_configs_dir() / TELEMETRY_CONFIG_FILE_NAME))- if not path_exists(str(template_path)):+ if not template_path.exists():agent_error("Telemetry template not found in kit configs", "InitConfigError")- os.makedirs(os.path.dirname(telemetry_config_path), exist_ok=True)+ telemetry_config_path.parent.mkdir(parents=True, exist_ok=True)shutil.copy(template_path, telemetry_config_path)# Apply telemetry_mode if specified@@ -315,13 +356,16 @@ def agent_init_cmd(# Resolve target directorytarget_dir = _resolve_target_dir(global_)- # Step 1: Copy config files- config_files_copied = init_config(reset=True, target_dir=target_dir)+ # Step 1: Copy config files (skips inference/ directory)+ config_files_copied = init_config(reset=True, target_dir=str(target_dir))++ # Step 1.5: Copy inference templates (init_config skips inference/)+ _copy_inference_templates(target_dir)# Step 2: Configure backends- template_backends_path = os.path.join(str(get_kit_configs_dir()), "inference", "backends.toml")- backends_toml_path = os.path.join(target_dir, "inference", "backends.toml")- backends_enabled = _configure_backends(parsed_config, backends_toml_path, template_backends_path, target_dir)+ template_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")+ backends_toml_path = str(target_dir / "inference" / "backends.toml")+ backends_enabled = _configure_backends(parsed_config, backends_toml_path, template_backends_path)# Step 3: Configure routingrouting_profile = _configure_routing(backends_enabled, parsed_config, target_dir)@@ -333,7 +377,7 @@ def agent_init_cmd(agent_success({"success": True,- "target_dir": target_dir,+ "target_dir": str(target_dir),"config_files_copied": config_files_copied,"backends_enabled": backends_enabled,"routing_profile": routing_profile,diff --git a/pipelex/cli/agent_cli/commands/pipe_cmd.py b/pipelex/cli/agent_cli/commands/pipe_cmd.pyindex ba6759787..b4f233dcd 100644--- a/pipelex/cli/agent_cli/commands/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/pipe_cmd.py@@ -56,6 +56,22 @@ EXTRACT_TALENT_TO_MODEL: dict[str, str] = {"full-document-extractor": "@default-extract-document",}+# Reverse mappings: preset name → talent name (for fuzzy resolution)+_MODEL_TO_LLM_TALENT: dict[str, str] = {}+for _talent, _preset in LLM_TALENT_TO_MODEL.items():+ _MODEL_TO_LLM_TALENT[_preset] = _talent+ _MODEL_TO_LLM_TALENT[_preset.lstrip("$@")] = _talent++_MODEL_TO_IMG_GEN_TALENT: dict[str, str] = {}+for _talent, _preset in IMG_GEN_TALENT_TO_MODEL.items():+ _MODEL_TO_IMG_GEN_TALENT[_preset] = _talent+ _MODEL_TO_IMG_GEN_TALENT[_preset.lstrip("$@")] = _talent++_MODEL_TO_EXTRACT_TALENT: dict[str, str] = {}+for _talent, _preset in EXTRACT_TALENT_TO_MODEL.items():+ _MODEL_TO_EXTRACT_TALENT[_preset] = _talent+ _MODEL_TO_EXTRACT_TALENT[_preset.lstrip("$@")] = _talent+# Maps pipe types to their talent field names and valid values.# Used to enrich validation errors with field_hints so the agent knows# what values are valid when a talent field is missing or wrong.@@ -194,6 +210,26 @@ def _add_type_specific_fields(pipe_spec: PipeSpec, pipe_table: tomlkit.TOMLDocumpipe_table.add("function_name", pipe_spec.function_name)+def _resolve_talent_value(pipe_type: str, raw_value: Any) -> Any:+ """Attempt to resolve a talent value, accepting preset names as aliases."""+ if not isinstance(raw_value, str):+ return raw_value+ reverse_maps: dict[str, dict[str, str]] = {+ "PipeLLM": _MODEL_TO_LLM_TALENT,+ "PipeImgGen": _MODEL_TO_IMG_GEN_TALENT,+ "PipeExtract": _MODEL_TO_EXTRACT_TALENT,+ }+ reverse_map = reverse_maps.get(pipe_type)+ if not reverse_map:+ return raw_value+ # If it's already a valid talent, return as-is+ # Otherwise try reverse-mapping from preset+ resolved = reverse_map.get(raw_value)+ if resolved:+ return resolved+ return raw_value # Let Pydantic validation handle the error++def _parse_pipe_spec_from_json(pipe_type: str, spec_data: dict[str, Any]) -> PipeSpec:"""Parse and validate a PipeSpec from JSON data.@@ -218,9 +254,30 @@ def _parse_pipe_spec_from_json(pipe_type: str, spec_data: dict[str, Any]) -> Pip# Add type to spec_data if not presentspec_data["type"] = pipe_type- # Accept "code" as an alias for "pipe_code"- if "code" in spec_data and "pipe_code" not in spec_data:- spec_data["pipe_code"] = spec_data.pop("code")+ # Accept common aliases for "pipe_code"+ for alias in ("code", "the_pipe_code", "name"):+ if alias in spec_data:+ if "pipe_code" not in spec_data:+ spec_data["pipe_code"] = spec_data.pop(alias)+ else:+ spec_data.pop(alias)++ # Accept generic talent aliases and map to the type-specific field+ talent_aliases = ("talent_name", "talent")+ pipe_type_to_talent_field: dict[str, str] = {+ "PipeLLM": "llm_talent",+ "PipeExtract": "extract_talent",+ "PipeImgGen": "img_gen_talent",+ "PipeSearch": "search_talent",+ }+ talent_field = pipe_type_to_talent_field.get(pipe_type)+ if talent_field:+ for alias in talent_aliases:+ if alias in spec_data:+ if talent_field not in spec_data:+ spec_data[talent_field] = spec_data.pop(alias)+ else:+ spec_data.pop(alias)# Handle steps/branches conversion - need to convert pipe to pipe_codeif "steps" in spec_data:@@ -243,6 +300,18 @@ def _parse_pipe_spec_from_json(pipe_type: str, spec_data: dict[str, Any]) -> Pipif pipe_type == "PipeCondition" and "expression" in spec_data:if "jinja2_expression_template" not in spec_data:spec_data["jinja2_expression_template"] = spec_data.pop("expression")+ else:+ spec_data.pop("expression")++ # Resolve preset names to talent names (tolerance for agent mistakes)+ talent_field = pipe_type_to_talent_field.get(pipe_type)+ if talent_field and talent_field in spec_data:+ spec_data[talent_field] = _resolve_talent_value(pipe_type, spec_data[talent_field])++ # Accept output as dict with "type" key → extract the type string+ if "output" in spec_data and isinstance(spec_data["output"], dict):+ if "type" in spec_data["output"]:+ spec_data["output"] = spec_data["output"]["type"]return spec_class.model_validate(spec_data)@@ -250,7 +319,7 @@ def _parse_pipe_spec_from_json(pipe_type: str, spec_data: dict[str, Any]) -> Pipdef pipe_cmd(pipe_type: Annotated[str | None,- typer.Option("--type", "-t", help=f"Pipe type. Must be one of: {PipeType.value_list()}"),+ typer.Option("--type", "--pipe-type", "--pipe_type", "-t", help=f"Pipe type. Must be one of: {PipeType.value_list()}"),] = None,spec: Annotated[str | None,@@ -316,6 +385,12 @@ def pipe_cmd(except json.JSONDecodeError as exc:agent_error(f"Invalid JSON: {exc.msg}", "JSONDecodeError", cause=exc)+ # Accept "pipe_type" as an alias for "type" in the JSON spec+ if "pipe_type" in spec_data and "type" not in spec_data:+ spec_data["type"] = spec_data.pop("pipe_type")+ elif "pipe_type" in spec_data:+ spec_data.pop("pipe_type")+# Resolve pipe type: CLI option takes precedence, then extract from spec JSONresolved_pipe_type: strif pipe_type is not None:diff --git a/pipelex/cli/commands/build/pipe_cmd.py b/pipelex/cli/commands/build/pipe_cmd.pyindex cbdc57737..07fc59d67 100644--- a/pipelex/cli/commands/build/pipe_cmd.py+++ b/pipelex/cli/commands/build/pipe_cmd.py@@ -341,9 +341,9 @@ def build_pipe_cmd(console.print(f" [green]✓[/green] graphs/{graph_label}: {', '.join(graph_formats)}")if has_inputs:console.print(f"\n [yellow]Note:[/yellow] Fill {DEFAULT_INPUTS_FILE_NAME} with actual data before running.")- console.print(f" To run: [cyan]pipelex run {extras_output_dir}[/cyan]")+ console.print(f" To run: [cyan]pipelex run bundle {extras_output_dir}[/cyan]")else:- console.print(f"\n To run: [cyan]pipelex run {extras_output_dir}[/cyan]")+ console.print(f"\n To run: [cyan]pipelex run bundle {extras_output_dir}[/cyan]")except Exception as exc:typer.secho(f"⚠️ Warning: Could not generate extras: {exc}", fg=typer.colors.YELLOW)diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex 0d3b333e9..042c1b1df 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -47,6 +47,34 @@ if TYPE_CHECKING:from pipelex.cogt.model_backends.model_spec_factory import BackendModelSpecs+class ConfigLocationInfo(BaseModel):+ """Information about the resolved configuration location."""++ config_dir: str+ is_project_local: bool+ project_root: str | None = None+ global_config_dir: str+++def gather_config_location() -> ConfigLocationInfo:+ """Gather information about the current configuration location.++ Returns:+ ConfigLocationInfo with resolved paths and location type.+ """+ effective_config_dir = config_manager.pipelex_config_dir+ project_root = config_manager.project_root+ project_config_dir = config_manager.project_config_dir+ global_config_dir = config_manager.global_config_dir++ return ConfigLocationInfo(+ config_dir=str(effective_config_dir),+ is_project_local=project_config_dir is not None,+ project_root=str(project_root) if project_root is not None else None,+ global_config_dir=str(global_config_dir),+ )++class BackendFileReport(BaseModel):"""Report on the health of an individual backend configuration file."""@@ -57,18 +85,21 @@ class BackendFileReport(BaseModel):has_kit_template: bool = False-def check_config_files(config_dir: str | None = None) -> tuple[bool, int, str]:+def check_config_files(config_dir: Path | None = None) -> tuple[bool, int, str]:"""Check if configuration files are present and main config is valid.Args:- config_dir: Explicit config directory path. If None, uses CWD-relative .pipelex/.+ config_dir: Explicit config directory override (e.g. for --global).+ If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).Returns:Tuple of (is_healthy, missing_count, message)"""+ effective_config_dir = config_dir or config_manager.pipelex_config_dir+# Check for missing filestry:- missing_count = init_config(reset=False, dry_run=True, target_dir=config_dir)+ missing_count = init_config(reset=False, dry_run=True, target_dir=str(effective_config_dir))except Exception as exc:return False, 0, f"Error checking config files: {exc}"@@ -76,7 +107,7 @@ def check_config_files(config_dir: str | None = None) -> tuple[bool, int, str]:# Note: load_config() uses config_manager's own resolution chain (package → global → project)# which may differ from config_dir when --global is used. This is acceptable for a diagnostic# check — the existence check guards the path, while load_config() validates the merged config.- pipelex_config_path = os.path.join(config_dir, "pipelex.toml") if config_dir else ".pipelex/pipelex.toml"+ pipelex_config_path = config_manager.resolve_config_file("pipelex.toml", config_dir=config_dir)if path_exists(pipelex_config_path):try:# Suppress stderr and stdout to prevent tracebacks from being printed@@ -96,16 +127,17 @@ def check_config_files(config_dir: str | None = None) -> tuple[bool, int, str]:return False, missing_count, f"{missing_count} configuration file(s) missing"-def check_telemetry_config(config_dir: str | None = None) -> tuple[bool, str]:+def check_telemetry_config(config_dir: Path | None = None) -> tuple[bool, str]:"""Check if telemetry configuration is valid.Args:- config_dir: Explicit config directory path. If None, uses CWD-relative .pipelex/.+ config_dir: Explicit config directory override (e.g. for --global).+ If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).Returns:Tuple of (is_healthy, message)"""- telemetry_config_path = os.path.join(config_dir, TELEMETRY_CONFIG_FILE_NAME) if config_dir else f".pipelex/{TELEMETRY_CONFIG_FILE_NAME}"+ telemetry_config_path = config_manager.resolve_config_file(TELEMETRY_CONFIG_FILE_NAME, config_dir=config_dir)try:toml_doc = load_toml_from_path(telemetry_config_path)@@ -124,16 +156,17 @@ def check_telemetry_config(config_dir: str | None = None) -> tuple[bool, str]:return False, "Invalid configuration - run 'pipelex init telemetry' to fix"-def check_backend_credentials(config_dir: str | None = None) -> tuple[bool, dict[str, BackendCredentialsReport], str]:+def check_backend_credentials(config_dir: Path | None = None) -> tuple[bool, dict[str, BackendCredentialsReport], str]:"""Check if backend credentials are properly configured.Args:- config_dir: Explicit config directory path. If None, uses CWD-relative .pipelex/.+ config_dir: Explicit config directory override (e.g. for --global).+ If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).Returns:Tuple of (is_healthy, backend_reports_dict, summary_message)"""- backends_toml_path = os.path.join(config_dir, "inference", "backends.toml") if config_dir else ".pipelex/inference/backends.toml"+ backends_toml_path = config_manager.resolve_config_file(os.path.join("inference", "backends.toml"), config_dir=config_dir)if not path_exists(backends_toml_path):return False, {}, "Backend configuration file not found"@@ -221,12 +254,13 @@ def check_kit_template_exists(backend_name: str) -> bool:return False-def replace_backend_file(backend_name: str, dry_run: bool = False) -> bool:+def replace_backend_file(backend_name: str, dry_run: bool = False, config_dir: Path | None = None) -> bool:"""Replace a backend configuration file with the kit template.Args:backend_name: Name of the backend to replacedry_run: If True, only report what would be done without actually doing it+ config_dir: Explicit config directory path. If None, uses config_manager.pipelex_config_dir.Returns:True if successful, False otherwise@@ -243,7 +277,8 @@ def replace_backend_file(backend_name: str, dry_run: bool = False) -> bool:template_content = template_file.read_text(encoding="utf-8")# Determine target path- target_dir = Path(".pipelex") / "inference" / "backends"+ resolved_config_dir = config_dir or config_manager.pipelex_config_dir+ target_dir = Path(resolved_config_dir) / "inference" / "backends"target_file = target_dir / f"{backend_name}.toml"if dry_run:@@ -260,22 +295,23 @@ def replace_backend_file(backend_name: str, dry_run: bool = False) -> bool:return False-def check_backend_files(config_dir: str | None = None) -> tuple[bool, dict[str, BackendFileReport], str]:+def check_backend_files(config_dir: Path | None = None) -> tuple[bool, dict[str, BackendFileReport], str]:"""Check individual backend configuration files for validity.Args:- config_dir: Explicit config directory path. If None, uses CWD-relative .pipelex/.+ config_dir: Explicit config directory override (e.g. for --global).+ If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).Returns:Tuple of (is_healthy, backend_file_reports_dict, summary_message)"""- backends_dir_path = os.path.join(config_dir, "inference", "backends") if config_dir else ".pipelex/inference/backends"+ backends_dir_path = config_manager.resolve_config_file(os.path.join("inference", "backends"), config_dir=config_dir)if not path_exists(backends_dir_path):return True, {}, "No backend files to check"# Get list of enabled backends from backends.toml- backends_toml_path = os.path.join(config_dir, "inference", "backends.toml") if config_dir else ".pipelex/inference/backends.toml"+ backends_toml_path = config_manager.resolve_config_file(os.path.join("inference", "backends.toml"), config_dir=config_dir)if not path_exists(backends_toml_path):return True, {}, "No backends.toml to check"@@ -304,7 +340,7 @@ def check_backend_files(config_dir: str | None = None) -> tuple[bool, dict[str,continue# Check if backend file exists- backend_file_path = f"{backends_dir_path}/{backend_name}.toml"+ backend_file_path = str(backends_dir_path / f"{backend_name}.toml")if not path_exists(backend_file_path):# No separate file - this is OK, configuration might be inline@@ -322,8 +358,8 @@ def check_backend_files(config_dir: str | None = None) -> tuple[bool, dict[str,# Try to load just this backend's specstemp_library.load(secrets_provider=secrets_provider,- backends_library_path=backends_toml_path,- backends_dir_path=backends_dir_path,+ backends_library_path=str(backends_toml_path),+ backends_dir_path=str(backends_dir_path),include_disabled=False,)@@ -375,6 +411,7 @@ def display_health_report(models_healthy: bool,models_message: str,backend_file_reports: dict[str, BackendFileReport],+ config_location: ConfigLocationInfo,fix_mode: bool = False,) -> None:"""Display a comprehensive health report.@@ -391,6 +428,7 @@ def display_health_report(models_healthy: Whether models check passedmodels_message: Message about models statusbackend_file_reports: Dict of backend file validation reports+ config_location: Resolved configuration location informationfix_mode: Whether we're in interactive fix mode (--fix flag)"""all_healthy = config_healthy and telemetry_healthy and backends_healthy and models_healthy@@ -412,6 +450,17 @@ def display_health_report(console.print(status_panel)console.print()+ # Configuration Location section+ console.print("[bold]Configuration Location[/bold]")+ if config_location.is_project_local:+ console.print(f" [green]✓[/green] Using project config: [cyan]{config_location.config_dir}[/cyan]")+ console.print(f" [dim]Project root: {config_location.project_root}[/dim]")+ console.print(f" [dim]Global config: {config_location.global_config_dir}[/dim]")+ else:+ console.print(f" [green]✓[/green] Using global config: [cyan]{config_location.config_dir}[/cyan]")+ console.print(" [dim]No project .pipelex/ directory found[/dim]")+ console.print()+# Configuration Files sectionconsole.print("[bold]Configuration Files[/bold]")if config_healthy:@@ -526,7 +575,7 @@ def display_health_report(console.print(" • Run [cyan]pipelex init telemetry[/cyan] to configure telemetry preferences")if has_telemetry_validation_error and "pipelex init telemetry" not in telemetry_message:- console.print(" • Fix validation errors in [cyan].pipelex/telemetry.toml[/cyan]")+ console.print(f" • Fix validation errors in [cyan]{config_location.config_dir}/telemetry.toml[/cyan]")console.print(" or run [cyan]pipelex init telemetry[/cyan] to regenerate")# Backend file issues@@ -543,7 +592,9 @@ def display_health_report(if has_custom_backend_issues:invalid_custom = [name for name, report in backend_file_reports.items() if not report.is_valid and not report.has_kit_template]for backend_name in invalid_custom:- console.print(f" • Manually fix backend configuration in [cyan].pipelex/inference/backends/{backend_name}.toml[/cyan]")+ console.print(+ f" • Manually fix backend configuration in [cyan]{config_location.config_dir}/inference/backends/{backend_name}.toml[/cyan]"+ )if not backends_healthy and backend_credential_reports:# Collect all missing and placeholder vars@@ -582,11 +633,12 @@ def display_health_report(console.print()-def check_models(config_dir: str | None = None) -> tuple[bool, str, dict[str, BackendFileReport]]:+def check_models(config_dir: Path | None = None) -> tuple[bool, str, dict[str, BackendFileReport]]:"""Check if models are valid, including backend file validation.Args:- config_dir: Explicit config directory path. If None, uses CWD-relative .pipelex/.+ config_dir: Explicit config directory override (e.g. for --global).+ If None, uses layered resolution (project .pipelex/ → global ~/.pipelex/).Returns:Tuple of (is_healthy, message, backend_file_reports)@@ -619,7 +671,7 @@ def check_models(config_dir: str | None = None) -> tuple[bool, str, dict[str, Ba# Fetch gateway model specs if Gateway is enabledgateway_model_specs: BackendModelSpecs | None = Noneif is_pipelex_gateway_enabled():- pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.pipelex_config_dir)+ pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)if pipelex_service_config is None:return False, "Pipelex Gateway is enabled but service configuration is missing", backend_file_reportsif not pipelex_service_config.agreement.terms_accepted:@@ -684,7 +736,10 @@ def do_doctor_cmd(Args:fix: If True, offer to fix detected issues interactively"""- # Run health checks+ # Gather config location info+ config_location = gather_config_location()++ # Run health checks (config_dir=None uses layered resolution: project → global)config_healthy, config_missing_count, config_message = check_config_files()telemetry_healthy, telemetry_message = check_telemetry_config()backends_healthy, backend_credential_reports, backends_message = check_backend_credentials()@@ -703,6 +758,7 @@ def do_doctor_cmd(models_healthy=models_healthy,models_message=models_message,backend_file_reports=backend_file_reports,+ config_location=config_location,fix_mode=fix,)@@ -786,7 +842,11 @@ def do_doctor_cmd(if Confirm.ask("[bold]Replace with latest template from the Pipelex kit?[/bold]", default=True):try:- success = replace_backend_file(backend_name, dry_run=False)+ # Derive config_dir from the resolved file path so the fix targets the+ # same directory where the broken file was found (file lives at+ # {config_dir}/inference/backends/{name}.toml).+ resolved_config_dir = Path(backend_file_report.file_path).parent.parent.parent+ success = replace_backend_file(backend_name, dry_run=False, config_dir=resolved_config_dir)if success:console.print(f"[green]✓[/green] Replaced {backend_name} backend configuration")else:@@ -809,7 +869,7 @@ def do_doctor_cmd(console.print("[bold]Configuration validation error:[/bold]")console.print(f" {config_message}")console.print()- console.print("You can fix this manually by editing [cyan].pipelex/pipelex.toml[/cyan]")+ console.print(f"You can fix this manually by editing [cyan]{config_location.config_dir}/pipelex.toml[/cyan]")console.print("or run [cyan]pipelex init config[/cyan] to regenerate from template.")console.print()@@ -818,7 +878,7 @@ def do_doctor_cmd(console.print("[bold]Telemetry validation error:[/bold]")console.print(f" {telemetry_message}")console.print()- console.print("You can fix this manually by editing [cyan].pipelex/telemetry.toml[/cyan]")+ console.print(f"You can fix this manually by editing [cyan]{config_location.config_dir}/telemetry.toml[/cyan]")console.print("or run [cyan]pipelex init telemetry[/cyan] to regenerate from template.")console.print()diff --git a/pipelex/cli/commands/init/backends.py b/pipelex/cli/commands/init/backends.pyindex 9dc7a72f4..fb529eb58 100644--- a/pipelex/cli/commands/init/backends.py+++ b/pipelex/cli/commands/init/backends.py@@ -1,6 +1,6 @@"""Backend configuration logic for the init command."""-import os+from pathlib import Pathfrom typing import Anyfrom rich.markup import escape@@ -89,15 +89,17 @@ def disable_gateway_backend(backends_toml_path: str) -> None:save_toml_to_path(toml_doc, backends_toml_path)-def customize_backends_config(is_first_time_setup: bool = False) -> None:+def customize_backends_config(is_first_time_setup: bool = False, target_config_dir: Path | None = None) -> None:"""Interactively customize which inference backends are enabled in backends.toml.Args:is_first_time_setup: Whether this is the first time backends.toml is being set up.+ target_config_dir: Explicit target .pipelex directory. If None, uses config_manager.pipelex_config_dir."""console = get_console()- backends_toml_path = os.path.join(config_manager.pipelex_config_dir, "inference", "backends.toml")- template_backends_path = os.path.join(str(get_kit_configs_dir()), "inference", "backends.toml")+ effective_config_dir = target_config_dir or config_manager.pipelex_config_dir+ backends_toml_path = str(effective_config_dir / "inference" / "backends.toml")+ template_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")if not path_exists(backends_toml_path):console.print("[yellow]⚠ Warning: backends.toml not found, skipping backend customization[/yellow]")@@ -135,27 +137,49 @@ def customize_backends_config(is_first_time_setup: bool = False) -> None:except Exception as exc:log.debug(f"IDE extension suggestion failed: {exc}")- # Check if pipelex_gateway is selected and handle terms acceptance+ # Check if pipelex_gateway is selected and handle terms acceptance prompt+ gateway_terms_accepted: bool | None = Noneif PipelexBackend.GATEWAY in selected_backends:gateway_accepted = prompt_gateway_acceptance(console)if gateway_accepted:display_gateway_accepted_message(console)- update_service_terms_acceptance(accepted=True)+ gateway_terms_accepted = Trueelse:display_gateway_declined_message(console)- update_service_terms_acceptance(accepted=False)+ gateway_terms_accepted = False# Remove pipelex_gateway from selected indicesselected_indices = [idx for idx in selected_indices if backend_options[idx][0] != PipelexBackend.GATEWAY]- # Business logic: Update TOML+ # Business logic: Update and save backends.toml first (local operation)update_backends_in_toml(toml_doc, selected_indices, backend_options)save_toml_to_path(toml_doc, backends_toml_path)# UI: Display confirmationdisplay_selected_backends(console, selected_indices, backend_options)+ # Save gateway terms acceptance to global config (separate from backends save)+ if gateway_terms_accepted is not None:+ try:+ global_config_dir = config_manager.global_config_dir+ global_config_dir.mkdir(parents=True, exist_ok=True)+ update_service_terms_acceptance(accepted=gateway_terms_accepted, config_dir=global_config_dir)+ except Exception as terms_exc:+ log.warning(f"Could not save gateway terms acceptance to global config: {terms_exc}")+ if gateway_terms_accepted:+ # Gateway enabled in backends.toml but terms not recorded — runtime will fail.+ # Disable gateway as a safety measure.+ try:+ disable_gateway_backend(backends_toml_path)+ console.print("[yellow]⚠ Could not save gateway terms. Gateway has been disabled to prevent errors.[/yellow]")+ except Exception as disable_exc:+ log.warning(f"Could not disable gateway backend: {disable_exc}")+ console.print(+ "[red]⚠ Could not save gateway terms or disable gateway. Please manually disable pipelex_gateway in backends.toml.[/red]"+ )+ console.print("[dim]Re-run 'pipelex init' to set up gateway again.[/dim]")+except Exception as exc:console.print(f"[yellow]⚠ Warning: Failed to customize backends: {escape(str(exc))}[/yellow]")console.print("[dim]You can manually edit .pipelex/inference/backends.toml later[/dim]")diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.pyindex 814de1722..206020294 100644--- a/pipelex/cli/commands/init/command.py+++ b/pipelex/cli/commands/init/command.py@@ -2,6 +2,7 @@import osimport shutil+from pathlib import Pathimport typerfrom rich.console import Console@@ -57,20 +58,21 @@ def _check_gateway_terms_if_needed(console: Console, backends_toml_path: str) ->if PipelexBackend.GATEWAY not in selected_backend_keys:return- # Gateway is enabled - check if terms are already accepted- pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.pipelex_config_dir)+ # Gateway is enabled - check if terms are already accepted (always global)+ pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)if pipelex_service_config is not None and pipelex_service_config.agreement.terms_accepted:return# Gateway is enabled but terms not accepted - prompt usergateway_accepted = prompt_gateway_acceptance(console)+ config_manager.global_config_dir.mkdir(parents=True, exist_ok=True)if gateway_accepted:display_gateway_accepted_message(console)- update_service_terms_acceptance(accepted=True)+ update_service_terms_acceptance(accepted=True, config_dir=config_manager.global_config_dir)else:display_gateway_declined_message(console)- update_service_terms_acceptance(accepted=False)+ update_service_terms_acceptance(accepted=False, config_dir=config_manager.global_config_dir)# Actually disable the gateway in backends.tomldisable_gateway_backend(backends_toml_path)@@ -84,7 +86,7 @@ def determine_needs(backends_toml_path: str,routing_profiles_toml_path: str,telemetry_config_path: str,- target_config_dir: str | None = None,+ target_config_dir: Path | None = None,) -> tuple[bool, bool, bool, bool]:"""Determine what needs to be initialized based on current state.@@ -102,7 +104,9 @@ def determine_needs(Returns:Tuple of (needs_config, needs_inference, needs_routing, needs_telemetry) booleans."""- nb_missing_config_files = init_config(reset=False, dry_run=True, target_dir=target_config_dir) if check_config else 0+ nb_missing_config_files = (+ init_config(reset=False, dry_run=True, target_dir=str(target_config_dir) if target_config_dir else None) if check_config else 0+ )needs_config = check_config and (nb_missing_config_files > 0 or reset)needs_inference = check_inference and (not path_exists(backends_toml_path) or reset)needs_routing = check_routing and (not path_exists(routing_profiles_toml_path) or reset)@@ -172,7 +176,7 @@ def execute_initialization(backends_toml_path: str,telemetry_config_path: str,is_first_time_backends_setup: bool,- target_config_dir: str | None = None,+ target_config_dir: Path | None = None,):"""Execute the initialization steps.@@ -198,7 +202,7 @@ def execute_initialization(backends_existed_before = path_exists(backends_toml_path)console.print()- init_config(reset=reset, target_dir=target_config_dir)+ init_config(reset=reset, target_dir=str(target_config_dir) if target_config_dir else None)# init_config skips the inference/ directory (handled independently by the inference step).# Detect first-time setup: if backends.toml didn't exist before, inference needs to be set up.@@ -221,51 +225,51 @@ def execute_initialization(# Copy the inference template files when resetting (init_config skips inference/)if reset:- template_inference_dir = os.path.join(str(get_kit_configs_dir()), "inference")+ template_inference_dir = Path(str(get_kit_configs_dir())) / "inference"effective_config_dir = target_config_dir or config_manager.pipelex_config_dir- target_inference_dir = os.path.join(effective_config_dir, "inference")+ target_inference_dir = effective_config_dir / "inference"# Reset backends.toml- template_backends_path = os.path.join(template_inference_dir, "backends.toml")- os.makedirs(os.path.dirname(backends_toml_path), exist_ok=True)+ template_backends_path = template_inference_dir / "backends.toml"+ Path(backends_toml_path).parent.mkdir(parents=True, exist_ok=True)shutil.copy2(template_backends_path, backends_toml_path)# Reset all individual backend files in backends/ directory- template_backends_dir = os.path.join(template_inference_dir, "backends")- target_backends_dir = os.path.join(target_inference_dir, "backends")- os.makedirs(target_backends_dir, exist_ok=True)+ template_backends_dir = template_inference_dir / "backends"+ target_backends_dir = target_inference_dir / "backends"+ target_backends_dir.mkdir(parents=True, exist_ok=True)for backend_file in os.listdir(template_backends_dir):if backend_file.endswith(".toml"):- src_path = os.path.join(template_backends_dir, backend_file)- dst_path = os.path.join(target_backends_dir, backend_file)+ src_path = template_backends_dir / backend_file+ dst_path = target_backends_dir / backend_fileshutil.copy2(src_path, dst_path)# Reset deck/ directory files (model deck configurations)- template_deck_dir = os.path.join(template_inference_dir, "deck")- target_deck_dir = os.path.join(target_inference_dir, "deck")- os.makedirs(target_deck_dir, exist_ok=True)+ template_deck_dir = template_inference_dir / "deck"+ target_deck_dir = target_inference_dir / "deck"+ target_deck_dir.mkdir(parents=True, exist_ok=True)for deck_file in os.listdir(template_deck_dir):if deck_file.endswith(".toml"):- src_path = os.path.join(template_deck_dir, deck_file)- dst_path = os.path.join(target_deck_dir, deck_file)+ src_path = template_deck_dir / deck_file+ dst_path = target_deck_dir / deck_fileshutil.copy2(src_path, dst_path)# Reset routing_profiles.toml- template_routing_path = os.path.join(template_inference_dir, "routing_profiles.toml")- target_routing_path = os.path.join(target_inference_dir, "routing_profiles.toml")- if os.path.exists(template_routing_path):+ template_routing_path = template_inference_dir / "routing_profiles.toml"+ target_routing_path = target_inference_dir / "routing_profiles.toml"+ if template_routing_path.exists():shutil.copy2(template_routing_path, target_routing_path)console.print("✅ Reset routing_profiles.toml from template")first_time_setup = True # Treat as first-time setup since we just replaced the files- customize_backends_config(is_first_time_setup=first_time_setup)+ customize_backends_config(is_first_time_setup=first_time_setup, target_config_dir=target_config_dir)# Automatically set up routing after backends (unless routing is the specific focus)if not check_routing:selected_backend_keys = get_selected_backend_keys(backends_toml_path)if selected_backend_keys:- customize_routing_profile(selected_backend_keys)+ customize_routing_profile(selected_backend_keys, target_config_dir=target_config_dir)# Step 2.5: Prompt for missing credentialsif check_credentials:@@ -278,14 +282,15 @@ def execute_initialization(# If reset is True, copy the template file firstif reset:effective_config_dir_for_routing = target_config_dir or config_manager.pipelex_config_dir- routing_profiles_toml_path = os.path.join(effective_config_dir_for_routing, "inference", "routing_profiles.toml")- template_routing_path = os.path.join(str(get_kit_configs_dir()), "inference", "routing_profiles.toml")+ routing_profiles_toml_path = str(effective_config_dir_for_routing / "inference" / "routing_profiles.toml")+ template_routing_path = Path(str(get_kit_configs_dir())) / "inference" / "routing_profiles.toml"+ Path(routing_profiles_toml_path).parent.mkdir(parents=True, exist_ok=True)shutil.copy2(template_routing_path, routing_profiles_toml_path)console.print("✅ Reset routing_profiles.toml from template")selected_backend_keys = get_selected_backend_keys(backends_toml_path)if selected_backend_keys:- customize_routing_profile(selected_backend_keys)+ customize_routing_profile(selected_backend_keys, target_config_dir=target_config_dir)else:console.print("[yellow]⚠ Warning: No backends enabled. Please run 'pipelex init inference' first.[/yellow]")@@ -313,8 +318,8 @@ def _init_agreement(console: Console) -> None:console.print()return- # Check current terms acceptance status- pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.pipelex_config_dir)+ # Check current terms acceptance status (always global)+ pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)if pipelex_service_config is not None and pipelex_service_config.agreement.terms_accepted:console.print()@@ -335,12 +340,12 @@ def _init_agreement(console: Console) -> None:if accepted:display_gateway_accepted_message(console)- update_service_terms_acceptance(accepted=True)+ update_service_terms_acceptance(accepted=True, config_dir=config_manager.global_config_dir)else:display_gateway_declined_message(console)- update_service_terms_acceptance(accepted=False)+ update_service_terms_acceptance(accepted=False, config_dir=config_manager.global_config_dir)# Disable the gateway since terms were declined- backends_toml_path = os.path.join(config_manager.pipelex_config_dir, "inference", "backends.toml")+ backends_toml_path = str(config_manager.pipelex_config_dir / "inference" / "backends.toml")if path_exists(backends_toml_path):disable_gateway_backend(backends_toml_path)@@ -371,7 +376,7 @@ def init_cmd(# Handle credentials-only flow separately (no reset needed)if focus == InitFocus.CREDENTIALS:- backends_toml_path = os.path.join(config_manager.pipelex_config_dir, "inference", "backends.toml")+ backends_toml_path = str(config_manager.pipelex_config_dir / "inference" / "backends.toml")if not path_exists(backends_toml_path):console.print()console.print("[yellow]No backends.toml found. Please run 'pipelex init' first.[/yellow]")@@ -389,18 +394,18 @@ def init_cmd(# --local: create at project root, fall back to CWDproject_root = config_manager.project_rootif project_root is not None:- target_config_dir = os.path.join(project_root, ".pipelex")+ target_config_dir = project_root / ".pipelex"else:- target_config_dir = os.path.join(os.getcwd(), ".pipelex")+ target_config_dir = Path.cwd() / ".pipelex"else:# Default: create global config at ~/.pipelex/target_config_dir = config_manager.global_config_dirconsole.print(f"[dim]Target directory: {target_config_dir}[/dim]")pipelex_config_dir = target_config_dir- telemetry_config_path = os.path.join(pipelex_config_dir, TELEMETRY_CONFIG_FILE_NAME)- backends_toml_path = os.path.join(pipelex_config_dir, "inference", "backends.toml")- routing_profiles_toml_path = os.path.join(pipelex_config_dir, "inference", "routing_profiles.toml")+ telemetry_config_path = str(pipelex_config_dir / TELEMETRY_CONFIG_FILE_NAME)+ backends_toml_path = str(pipelex_config_dir / "inference" / "backends.toml")+ routing_profiles_toml_path = str(pipelex_config_dir / "inference" / "routing_profiles.toml")# Determine what to check based on focus parametercheck_config = focus in {InitFocus.ALL, InitFocus.CONFIG}diff --git a/pipelex/cli/commands/init/config_files.py b/pipelex/cli/commands/init/config_files.pyindex 81af48cc7..fc16c5cf2 100644--- a/pipelex/cli/commands/init/config_files.py+++ b/pipelex/cli/commands/init/config_files.py@@ -29,7 +29,7 @@ def init_config(reset: bool = False, dry_run: bool = False, target_dir: str | NoThe number of files copied."""config_template_dir = str(get_kit_configs_dir())- target_config_dir = target_dir or config_manager.pipelex_config_dir+ target_config_dir = target_dir or str(config_manager.pipelex_config_dir)os.makedirs(target_config_dir, exist_ok=True)diff --git a/pipelex/cli/commands/init/credentials.py b/pipelex/cli/commands/init/credentials.pyindex fb9f40137..727ae96e3 100644--- a/pipelex/cli/commands/init/credentials.py+++ b/pipelex/cli/commands/init/credentials.py@@ -17,7 +17,7 @@ from pipelex.tools.misc.toml_utils import load_toml_from_pathdef get_global_env_path() -> Path:"""Return the path to the global credentials file (~/.pipelex/.env)."""- return Path(config_manager.global_config_dir) / ".env"+ return config_manager.global_config_dir / ".env"def read_env_file(env_path: Path) -> dict[str, str]:diff --git a/pipelex/cli/commands/init/routing.py b/pipelex/cli/commands/init/routing.pyindex c043dc1f5..31359049e 100644--- a/pipelex/cli/commands/init/routing.py+++ b/pipelex/cli/commands/init/routing.py@@ -1,6 +1,6 @@"""Routing profile configuration logic for the init command."""-import os+from pathlib import Pathfrom typing import Any, castfrom rich.markup import escape@@ -65,16 +65,18 @@ def _migrate_profile_to_official_backend(profile: dict[str, Any]) -> None:optional_routes[pattern] = official_backend-def customize_routing_profile(selected_backend_keys: list[str]) -> None:+def customize_routing_profile(selected_backend_keys: list[str], target_config_dir: Path | None = None) -> None:"""Interactively customize routing profile based on selected backends.Args:selected_backend_keys: List of backend keys that are enabled.+ target_config_dir: Explicit target .pipelex directory. If None, uses config_manager.pipelex_config_dir."""console = get_console()- routing_profiles_toml_path = os.path.join(config_manager.pipelex_config_dir, "inference", "routing_profiles.toml")- template_routing_path = os.path.join(str(get_kit_configs_dir()), "inference", "routing_profiles.toml")- backends_toml_path = os.path.join(config_manager.pipelex_config_dir, "inference", "backends.toml")+ effective_config_dir = target_config_dir or config_manager.pipelex_config_dir+ routing_profiles_toml_path = str(effective_config_dir / "inference" / "routing_profiles.toml")+ template_routing_path = str(get_kit_configs_dir() / "inference" / "routing_profiles.toml")+ backends_toml_path = str(effective_config_dir / "inference" / "backends.toml")if not path_exists(routing_profiles_toml_path):console.print("[yellow]⚠ Warning: routing_profiles.toml not found, skipping routing customization[/yellow]")@@ -88,7 +90,7 @@ def customize_routing_profile(selected_backend_keys: list[str]) -> None:toml_doc = load_toml_with_tomlkit(routing_profiles_toml_path)# Get backend options for display names- template_backends_path = os.path.join(str(get_kit_configs_dir()), "inference", "backends.toml")+ template_backends_path = str(get_kit_configs_dir() / "inference" / "backends.toml")backend_options = get_backend_options_from_toml(template_backends_path, backends_toml_path)# Case 1: pipelex_gateway is enabled - use all_pipelex_gatewaydiff --git a/pipelex/cli/commands/show_cmd.py b/pipelex/cli/commands/show_cmd.pyindex 8553a9e7f..5ab571a9e 100644--- a/pipelex/cli/commands/show_cmd.py+++ b/pipelex/cli/commands/show_cmd.py@@ -76,8 +76,8 @@ def do_show_backends(show_all: bool = False) -> None:backend_library = InferenceBackendLibrary()backend_library.load(secrets_provider=secrets_provider,- backends_library_path=config_manager.backends_file_path,- backends_dir_path=config_manager.backends_dir_path,+ backends_library_path=str(config_manager.backends_file_path),+ backends_dir_path=str(config_manager.backends_dir_path),include_disabled=True,lenient=True,)diff --git a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.pyindex 2b4c409a2..23944f091 100644--- a/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py+++ b/pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py@@ -161,7 +161,7 @@ def _collect_all_model_availability() -> dict[str, Any]:"search": {},}- backends_dir = Path(config_manager.backends_dir_path)+ backends_dir = config_manager.backends_dir_path# Process each backend TOML filefor backend_file in sorted(backends_dir.glob("*.toml")):@@ -621,7 +621,7 @@ def preprocess_test_models_cmd(console.print()# Collect model availability- backends_dir = Path(config_manager.backends_dir_path)+ backends_dir = config_manager.backends_dir_pathif not backends_dir.exists():if quiet:console.print(f"[red]✗ Preprocessing failed:[/red] Backends directory not found: {backends_dir}")diff --git a/pipelex/cogt/models/model_manager.py b/pipelex/cogt/models/model_manager.pyindex 1a636f78f..6092e54c5 100644--- a/pipelex/cogt/models/model_manager.py+++ b/pipelex/cogt/models/model_manager.py@@ -60,18 +60,18 @@ class ModelManager(ModelManagerAbstract):) -> None:self.inference_backend_library.load(secrets_provider=secrets_provider,- backends_library_path=config_manager.backends_file_path,- backends_dir_path=config_manager.backends_dir_path,+ backends_library_path=str(config_manager.backends_file_path),+ backends_dir_path=str(config_manager.backends_dir_path),gateway_model_specs=gateway_model_specs,lenient=not needs_inference,)enabled_backends = self.inference_backend_library.all_enabled_backends()self._routing_profile = load_active_routing_profile(- routing_profile_library_path=config_manager.routing_profiles_file_path,+ routing_profile_library_path=str(config_manager.routing_profiles_file_path),enabled_backends=enabled_backends,lenient=not needs_inference,)- model_deck_paths = ModelManager.get_model_deck_paths(deck_dir_path=config_manager.model_decks_dir_path)+ model_deck_paths = ModelManager.get_model_deck_paths(deck_dir_path=str(config_manager.model_decks_dir_path))deck_blueprint = load_model_deck_blueprint(model_deck_paths=model_deck_paths)self.model_deck = self.build_deck(enabled_backends=enabled_backends, model_deck_blueprint=deck_blueprint)diff --git a/pipelex/graph/graph_rendering.py b/pipelex/graph/graph_rendering.pyindex f37878fe0..5c34ba892 100644--- a/pipelex/graph/graph_rendering.py+++ b/pipelex/graph/graph_rendering.py@@ -23,6 +23,19 @@ from pipelex.tools.misc.chart_utils import FlowchartDirectionfrom pipelex.types import StrEnum+def _sanitize_graph_name(graph_name: str) -> str:+ """Sanitize graph_name to prevent path traversal.++ Args:+ graph_name: The requested filename for the graph output.++ Returns:+ A safe filename with no directory components.+ """+ sanitized = Path(graph_name).name+ return sanitized or "graph.html"++class GraphFormat(StrEnum):"""Selectable graph output formats."""@@ -164,6 +177,7 @@ async def generate_graph_for_bundle(graph_format: GraphFormat,library_dirs: list[str] | None = None,direction: FlowchartDirection | None = None,+ graph_name: str = "dry_run.html",) -> dict[str, Any]:"""Generate graph visualization for a bundle via dry-run pipeline execution.@@ -175,6 +189,7 @@ async def generate_graph_for_bundle(graph_format: Which graph format(s) to generate.library_dirs: Optional library directories for pipe resolution.direction: Flowchart layout direction (default: None, uses TB).+ graph_name: Filename for the generated HTML graph (default: "dry_run.html").Returns:Dictionary with graph_files, graph_output_dir, and direction.@@ -215,6 +230,14 @@ async def generate_graph_for_bundle(direction=direction,)+ # Rename reactflow.html to the requested filename+ reactflow_path = saved_files.get("reactflow_html")+ safe_name = _sanitize_graph_name(graph_name)+ if reactflow_path and safe_name:+ final_path = reactflow_path.parent / safe_name+ reactflow_path.rename(final_path)+ saved_files["reactflow_html"] = final_path+return {"graph_files": {key: str(path) for key, path in saved_files.items()},"graph_output_dir": str(output_dir),diff --git a/pipelex/pipelex.py b/pipelex/pipelex.pyindex 76f3f24be..e8652c7b4 100644--- a/pipelex/pipelex.py+++ b/pipelex/pipelex.py@@ -92,7 +92,7 @@ PACKAGE_NAME, PACKAGE_VERSION = get_package_info()class Pipelex(metaclass=MetaSingleton):def __init__(self,- config_dir_path: str | None = None,+ config_dir_path: Path | None = None,config_cls: type[ConfigRoot] | None = None,) -> None:self.is_pipelex_service_enabled = False # Will be set during setup@@ -198,7 +198,7 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.# Skip terms check for CI mode - automated CI/CD pipelines don't require human consentif integration_mode.requires_terms_acceptance:# Check if terms are accepted- pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.pipelex_config_dir)+ pipelex_service_config = load_pipelex_service_config_if_exists(config_dir=config_manager.global_config_dir)if pipelex_service_config is None or not pipelex_service_config.agreement.terms_accepted:raise GatewayTermsNotAcceptedError# Fetch remote configurationdiff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.pyindex b5f4762ca..f0303b504 100644--- a/pipelex/system/configuration/config_loader.py+++ b/pipelex/system/configuration/config_loader.py@@ -1,4 +1,3 @@-import osimport shutilfrom pathlib import Pathfrom typing import Any@@ -20,13 +19,13 @@ MODEL_DECKS_DIR_NAME = "deck"class ConfigLoader:@property- def pipelex_root_dir(self) -> str:+ def pipelex_root_dir(self) -> Path:"""Get the root directory of the installed pipelex package.Uses __file__ to locate the package directory, which works in bothdevelopment and installed modes."""- return str(Path(__file__).resolve().parent.parent.parent)+ return Path(__file__).resolve().parent.parent.parent@staticmethoddef find_project_root(start_dir: Path) -> Path | None:@@ -51,20 +50,17 @@ class ConfigLoader:current = parent@property- def global_config_dir(self) -> str:+ def global_config_dir(self) -> Path:"""Get the global config directory at ~/.pipelex."""- return str(Path.home() / CONFIG_DIR_NAME)+ return Path.home() / CONFIG_DIR_NAME@property- def project_root(self) -> str | None:+ def project_root(self) -> Path | None:"""Get the detected project root directory, or None if no project root markers found."""- project_root = self.find_project_root(Path.cwd())- if project_root is None:- return None- return str(project_root)+ return self.find_project_root(Path.cwd())@property- def project_config_dir(self) -> str | None:+ def project_config_dir(self) -> Path | None:"""Get the project config directory if it exists on disk.Returns the path to {project_root}/.pipelex if the project root was found@@ -75,11 +71,11 @@ class ConfigLoader:return Noneproject_config = project_root / CONFIG_DIR_NAMEif project_config.is_dir():- return str(project_config)+ return project_configreturn None@property- def pipelex_config_dir(self) -> str:+ def pipelex_config_dir(self) -> Path:"""Get the effective config directory (project if exists, else global).This preserves backwards compatibility for all current consumers.@@ -89,68 +85,79 @@ class ConfigLoader:return project_dirreturn self.global_config_dir- def _resolve_inference_file(self, relative_path: str) -> str:- """Resolve an inference file path, checking project dir first, then global.+ def resolve_config_file(self, relative_path: str, config_dir: Path | None = None) -> Path:+ """Resolve a config file path with layered resolution.++ When config_dir is provided (e.g. for --global override), the file is+ resolved directly under that directory.++ Otherwise, the project .pipelex/ directory is checked first; if the file+ exists there it wins, otherwise the global ~/.pipelex/ is used.+ This works on all platforms (macOS, Linux, Windows) because Path.home()+ returns the correct home directory everywhere.Args:- relative_path: Path relative to the .pipelex directory (e.g. "inference/backends.toml").+ relative_path: Path relative to the .pipelex directory (e.g. "telemetry.toml",+ "inference/backends.toml").+ config_dir: Explicit config directory override. When set, skips layered+ resolution and uses this directory directly.Returns:The resolved absolute path."""+ if config_dir is not None:+ return config_dir / relative_pathproject_dir = self.project_config_dirif project_dir is not None:- candidate = os.path.join(project_dir, relative_path)- if os.path.exists(candidate):+ candidate = project_dir / relative_path+ if candidate.exists():return candidate- return os.path.join(self.global_config_dir, relative_path)+ return self.global_config_dir / relative_path@property- def backends_file_path(self) -> str:+ def backends_file_path(self) -> Path:"""Resolve backends.toml from project dir or global dir."""- return self._resolve_inference_file(os.path.join(INFERENCE_DIR_NAME, BACKENDS_FILE_NAME))+ return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / BACKENDS_FILE_NAME))@property- def backends_dir_path(self) -> str:+ def backends_dir_path(self) -> Path:"""Resolve backends/ directory from project dir or global dir."""- return self._resolve_inference_file(os.path.join(INFERENCE_DIR_NAME, BACKENDS_DIR_NAME))+ return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / BACKENDS_DIR_NAME))@property- def routing_profiles_file_path(self) -> str:+ def routing_profiles_file_path(self) -> Path:"""Resolve routing_profiles.toml from project dir or global dir."""- return self._resolve_inference_file(os.path.join(INFERENCE_DIR_NAME, ROUTING_PROFILES_FILE_NAME))+ return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / ROUTING_PROFILES_FILE_NAME))@property- def model_decks_dir_path(self) -> str:+ def model_decks_dir_path(self) -> Path:"""Resolve model decks directory from project dir or global dir."""- return self._resolve_inference_file(os.path.join(INFERENCE_DIR_NAME, MODEL_DECKS_DIR_NAME))+ return self.resolve_config_file(str(Path(INFERENCE_DIR_NAME) / MODEL_DECKS_DIR_NAME))def ensure_global_config_exists(self) -> None:"""Create the global ~/.pipelex/ directory with kit template files if it doesn't exist."""- global_dir = Path(self.global_config_dir)+ global_dir = self.global_config_dirif global_dir.is_dir():returnfrom pipelex.kit.paths import GIT_IGNORED_CONFIG_FILES, get_kit_configs_dir # noqa: PLC0415- config_template_dir = str(get_kit_configs_dir())- global_dir_str = str(global_dir)- os.makedirs(global_dir_str, exist_ok=True)+ config_template_dir = Path(str(get_kit_configs_dir()))+ global_dir.mkdir(parents=True, exist_ok=True)- def copy_directory_structure(src_dir: str, dst_dir: str) -> None:+ def copy_directory_structure(src_dir: Path, dst_dir: Path) -> None:"""Recursively copy directory structure from kit templates."""- for item in os.listdir(src_dir):- if item in GIT_IGNORED_CONFIG_FILES or item == ".DS_Store":+ for item in src_dir.iterdir():+ if item.name in GIT_IGNORED_CONFIG_FILES or item.name == ".DS_Store":continue- src_item = os.path.join(src_dir, item)- dst_item = os.path.join(dst_dir, item)- if os.path.isdir(src_item):- os.makedirs(dst_item, exist_ok=True)- copy_directory_structure(src_item, dst_item)+ dst_item = dst_dir / item.name+ if item.is_dir():+ dst_item.mkdir(parents=True, exist_ok=True)+ copy_directory_structure(item, dst_item)else:- shutil.copy2(src_item, dst_item)+ shutil.copy2(item, dst_item)- copy_directory_structure(src_dir=config_template_dir, dst_dir=global_dir_str)+ copy_directory_structure(src_dir=config_template_dir, dst_dir=global_dir)def load_config(self) -> dict[str, Any]:"""Load and merge configurations from pipelex and local config files.@@ -170,36 +177,36 @@ class ConfigLoader:"""self.ensure_global_config_exists()- list_of_configs: list[str] = []+ list_of_configs: list[Path] = []# 1. Pipelex package defaults- list_of_configs.append(os.path.join(self.pipelex_root_dir, CONFIG_NAME))+ list_of_configs.append(self.pipelex_root_dir / CONFIG_NAME)# 2. Global config- list_of_configs.append(os.path.join(self.global_config_dir, CONFIG_NAME))+ list_of_configs.append(self.global_config_dir / CONFIG_NAME)# 3. Project config (if different from global)project_dir = self.project_config_dirif project_dir is not None and project_dir != self.global_config_dir:- list_of_configs.append(os.path.join(project_dir, CONFIG_NAME))+ list_of_configs.append(project_dir / CONFIG_NAME)# Effective config dir for overrideseffective_config_dir = self.pipelex_config_dir# 4. Override for local execution- list_of_configs.append(os.path.join(effective_config_dir, "pipelex_local.toml"))+ list_of_configs.append(effective_config_dir / "pipelex_local.toml")# Override for environment- list_of_configs.append(os.path.join(effective_config_dir, f"pipelex_{runtime_manager.environment}.toml"))+ list_of_configs.append(effective_config_dir / f"pipelex_{runtime_manager.environment}.toml")# Override for run modeif runtime_manager.is_unit_testing:- list_of_configs.append(os.path.join(os.getcwd(), "tests", f"pipelex_{runtime_manager.run_mode}.toml"))+ list_of_configs.append(Path.cwd() / "tests" / f"pipelex_{runtime_manager.run_mode}.toml")else:- list_of_configs.append(os.path.join(effective_config_dir, f"pipelex_{runtime_manager.run_mode}.toml"))+ list_of_configs.append(effective_config_dir / f"pipelex_{runtime_manager.run_mode}.toml")# Final override- list_of_configs.append(os.path.join(effective_config_dir, "pipelex_override.toml"))+ list_of_configs.append(effective_config_dir / "pipelex_override.toml")return load_toml_from_path_and_merge_with_overrides(paths=list_of_configs)diff --git a/pipelex/system/pipelex_service/pipelex_service_agreement.py b/pipelex/system/pipelex_service/pipelex_service_agreement.pyindex afc53c3ff..b029e79be 100644--- a/pipelex/system/pipelex_service/pipelex_service_agreement.py+++ b/pipelex/system/pipelex_service/pipelex_service_agreement.py@@ -1,4 +1,4 @@-import os+from pathlib import Pathfrom pydantic import Field@@ -18,15 +18,15 @@ class PipelexServiceAgreement(ConfigModel):)-def update_service_terms_acceptance(accepted: bool, config_dir: str | None = None) -> None:+def update_service_terms_acceptance(accepted: bool, config_dir: Path | None = None) -> None:"""Update the service terms acceptance in pipelex_service.toml.Args:accepted: Whether the user accepted the terms.- config_dir: Explicit config directory path. If None, uses config_manager.pipelex_config_dir.+ config_dir: Explicit config directory path. If None, uses config_manager.global_config_dir."""- resolved_config_dir = config_dir or config_manager.pipelex_config_dir- service_config_path = os.path.join(resolved_config_dir, PIPELEX_SERVICE_CONFIG_FILE_NAME)+ resolved_config_dir = config_dir or config_manager.global_config_dir+ service_config_path = resolved_config_dir / PIPELEX_SERVICE_CONFIG_FILE_NAMEif path_exists(service_config_path):toml_doc = load_toml_with_tomlkit(service_config_path)@@ -38,4 +38,5 @@ def update_service_terms_acceptance(accepted: bool, config_dir: str | None = Non# Update terms_acceptedtoml_doc["agreement"]["terms_accepted"] = accepted # type: ignore[index]+ resolved_config_dir.mkdir(parents=True, exist_ok=True)save_toml_to_path(toml_doc, service_config_path)diff --git a/pipelex/system/pipelex_service/pipelex_service_config.py b/pipelex/system/pipelex_service/pipelex_service_config.pyindex 4cbee38e4..43ad552e3 100644--- a/pipelex/system/pipelex_service/pipelex_service_config.py+++ b/pipelex/system/pipelex_service/pipelex_service_config.py@@ -1,4 +1,4 @@-import os+from pathlib import Pathfrom typing import Any, castfrom pydantic import ValidationError@@ -19,7 +19,7 @@ class PipelexServiceConfig(ConfigModel):agreement: PipelexServiceAgreement-def load_pipelex_service_config_if_exists(config_dir: str) -> PipelexServiceConfig | None:+def load_pipelex_service_config_if_exists(config_dir: Path) -> PipelexServiceConfig | None:"""Load Pipelex service configuration if the file exists.Args:@@ -28,7 +28,7 @@ def load_pipelex_service_config_if_exists(config_dir: str) -> PipelexServiceConfReturns:PipelexServiceConfig instance or None if file doesn't exist."""- config_path = os.path.join(config_dir, PIPELEX_SERVICE_CONFIG_FILE_NAME)+ config_path = config_dir / PIPELEX_SERVICE_CONFIG_FILE_NAMEtry:config_toml = load_toml_from_path(path=config_path)return PipelexServiceConfig.model_validate(config_toml)diff --git a/pipelex/system/telemetry/telemetry_config.py b/pipelex/system/telemetry/telemetry_config.pyindex b0071fc7c..548c1d8bb 100644--- a/pipelex/system/telemetry/telemetry_config.py+++ b/pipelex/system/telemetry/telemetry_config.py@@ -1,4 +1,3 @@-import osfrom functools import partialfrom pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator@@ -240,9 +239,10 @@ def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> TelemetrRaises:TelemetryConfigValidationError: If configuration is invalid or variable substitution fails."""- telemetry_config_paths: list[str] = []- telemetry_config_paths.append(os.path.join(config_manager.pipelex_config_dir, TELEMETRY_CONFIG_FILE_NAME))- telemetry_config_paths.append(os.path.join(config_manager.pipelex_config_dir, TELEMETRY_CONFIG_OVERRIDE_FILE_NAME))+ telemetry_config_paths = [+ config_manager.pipelex_config_dir / TELEMETRY_CONFIG_FILE_NAME,+ config_manager.pipelex_config_dir / TELEMETRY_CONFIG_OVERRIDE_FILE_NAME,+ ]telemetry_config_toml_raw = load_toml_from_path_and_merge_with_overrides(paths=telemetry_config_paths)# Apply variable substitution to all string values (keep placeholders for missing vars)@@ -250,7 +250,7 @@ def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> Telemetrtry:telemetry_config_toml = apply_to_strings_recursive(telemetry_config_toml_raw, substitute_vars_with_provider)except UnknownVarPrefixError as exc:- paths_str = "\n".join(telemetry_config_paths)+ paths_str = "\n".join(str(path) for path in telemetry_config_paths)msg = f"Variable substitution failed in telemetry configuration based on '{paths_str}': {exc}"raise TelemetryConfigValidationError(msg) from exc@@ -258,7 +258,7 @@ def load_telemetry_config(secrets_provider: SecretsProviderAbstract) -> Telemetrtelemetry_config = TelemetryConfig.model_validate(telemetry_config_toml)except ValidationError as exc:validation_error_msg = format_pydantic_validation_error(exc)- paths_str = "\n".join(telemetry_config_paths)+ paths_str = "\n".join(str(path) for path in telemetry_config_paths)msg = f"Invalid telemetry configuration in '{paths_str}':\n{validation_error_msg}"raise TelemetryConfigValidationError(msg) from excreturn telemetry_configdiff --git a/pipelex/tools/misc/file_utils.py b/pipelex/tools/misc/file_utils.pyindex 351ac0c8c..06723d81c 100644--- a/pipelex/tools/misc/file_utils.py+++ b/pipelex/tools/misc/file_utils.py@@ -272,7 +272,7 @@ def ensure_directory_for_file_path(file_path: str) -> None:ensure_directory_exists(os.path.dirname(file_path))-def path_exists(path_str: str) -> bool:+def path_exists(path_str: str | Path) -> bool:"""Checks if a file or directory exists at the specified path.This function converts the input string path to a Path object and checksdiff --git a/pipelex/tools/misc/toml_utils.py b/pipelex/tools/misc/toml_utils.pyindex 8f649354e..fda5c2028 100644--- a/pipelex/tools/misc/toml_utils.py+++ b/pipelex/tools/misc/toml_utils.py@@ -1,6 +1,10 @@from __future__ import annotations-from typing import Any+from typing import TYPE_CHECKING, Any++if TYPE_CHECKING:+ from collections.abc import Sequence+ from pathlib import Pathimport tomliimport tomlkit@@ -31,7 +35,7 @@ def load_toml_from_content(content: str) -> dict[str, Any]:raise TomlError.from_tomli_error(exc) from exc-def load_toml_from_path(path: str) -> dict[str, Any]:+def load_toml_from_path(path: str | Path) -> dict[str, Any]:"""Load TOML from path.Args:@@ -52,14 +56,14 @@ def load_toml_from_path(path: str) -> dict[str, Any]:raise TomlError(message=msg, doc=exc.doc, pos=exc.pos, lineno=exc.lineno, colno=exc.colno) from exc-def load_toml_from_path_if_exists(path: str) -> dict[str, Any] | None:+def load_toml_from_path_if_exists(path: str | Path) -> dict[str, Any] | None:"""Load TOML from path if it exists."""if not path_exists(path):return Nonereturn load_toml_from_path(path)-def load_toml_with_tomlkit(path: str) -> tomlkit.TOMLDocument:+def load_toml_with_tomlkit(path: str | Path) -> tomlkit.TOMLDocument:"""Load TOML using tomlkit to preserve formatting and comments.Args:@@ -73,7 +77,7 @@ def load_toml_with_tomlkit(path: str) -> tomlkit.TOMLDocument:return tomlkit.load(file)-def save_toml_to_path(data: dict[str, Any] | tomlkit.TOMLDocument, path: str) -> None:+def save_toml_to_path(data: dict[str, Any] | tomlkit.TOMLDocument, path: str | Path) -> None:"""Save dictionary as TOML to path, preserving formatting and comments.Args:@@ -85,7 +89,7 @@ def save_toml_to_path(data: dict[str, Any] | tomlkit.TOMLDocument, path: str) ->tomlkit.dump(data, file) # type: ignore[arg-type]-def load_toml_from_path_and_merge_with_overrides(paths: list[str]) -> dict[str, Any]:+def load_toml_from_path_and_merge_with_overrides(paths: Sequence[str | Path]) -> dict[str, Any]:"""Load and merge toml files from paths if they exist, merged in sequence.Returns:diff --git a/pyproject.toml b/pyproject.tomlindex d15f14227..22d105c23 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -1,6 +1,6 @@[project]name = "pipelex"-version = "0.20.4"+version = "0.20.5"description = "Execute composable AI methods declared in the MTHDS open standard"authors = [{ name = "Evotis S.A.S.", email = "[email protected]" }]maintainers = [{ name = "Pipelex staff", email = "[email protected]" }]diff --git a/tests/conftest.py b/tests/conftest.pyindex ba2a28632..d0249b6ad 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -40,10 +40,10 @@ def _cached_fetch_remote_config() -> RemoteConfig:# Session-level cache for pipelex service config to avoid flaky tests from concurrent file reads-_pipelex_service_config_cache: dict[str, PipelexServiceConfig | None] = {}+_pipelex_service_config_cache: dict[Path, PipelexServiceConfig | None] = {}-def _cached_load_pipelex_service_config(config_dir: str) -> PipelexServiceConfig | None:+def _cached_load_pipelex_service_config(config_dir: Path) -> PipelexServiceConfig | None:"""Wrapper that caches the pipelex service config for the entire test session.This prevents flaky tests caused by concurrent file reads during parallel pytest-xdist execution.diff --git a/tests/helpers/init_cmd_helpers.py b/tests/helpers/init_cmd_helpers.pyindex 799b3554a..612388ee7 100644--- a/tests/helpers/init_cmd_helpers.py+++ b/tests/helpers/init_cmd_helpers.py@@ -180,14 +180,14 @@ class MockedInitEnvironment:def mock_config_manager_paths(self) -> None:"""Mock config_manager to use tmp_path."""self.mock_config_manager = self.mocker.MagicMock()- self.mock_config_manager.pipelex_config_dir = str(self.pipelex_dir)- self.mock_config_manager.global_config_dir = str(self.pipelex_dir)- self.mock_config_manager.project_config_dir = str(self.pipelex_dir)- self.mock_config_manager.project_root = str(self.tmp_path)- self.mock_config_manager.backends_file_path = str(self.inference_dir / "backends.toml")- self.mock_config_manager.backends_dir_path = str(self.inference_dir / "backends")- self.mock_config_manager.routing_profiles_file_path = str(self.inference_dir / "routing_profiles.toml")- self.mock_config_manager.model_decks_dir_path = str(self.inference_dir / "deck")+ self.mock_config_manager.pipelex_config_dir = self.pipelex_dir+ self.mock_config_manager.global_config_dir = self.pipelex_dir+ self.mock_config_manager.project_config_dir = self.pipelex_dir+ self.mock_config_manager.project_root = self.tmp_path+ self.mock_config_manager.backends_file_path = self.inference_dir / "backends.toml"+ self.mock_config_manager.backends_dir_path = self.inference_dir / "backends"+ self.mock_config_manager.routing_profiles_file_path = self.inference_dir / "routing_profiles.toml"+ self.mock_config_manager.model_decks_dir_path = self.inference_dir / "deck"# Patch all locations where config_manager is usedself.mocker.patch("pipelex.cli.commands.init.command.config_manager", self.mock_config_manager)diff --git a/tests/integration/pipelex/cli/test_init_cmd_backend_customization.py b/tests/integration/pipelex/cli/test_init_cmd_backend_customization.pyindex f042fae47..997f33e9a 100644--- a/tests/integration/pipelex/cli/test_init_cmd_backend_customization.py+++ b/tests/integration/pipelex/cli/test_init_cmd_backend_customization.py@@ -29,7 +29,8 @@ class TestBackendCustomization:# Mock config_managermock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(tmp_path / ".pipelex")+ mock_config_manager.pipelex_config_dir = tmp_path / ".pipelex"+ mock_config_manager.global_config_dir = tmp_path / ".pipelex"mocker.patch("pipelex.cli.commands.init.backends.config_manager", mock_config_manager)# Mock console provider@@ -91,7 +92,7 @@ class TestBackendCustomization:# Mock config_managermock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(tmp_path / ".pipelex")+ mock_config_manager.pipelex_config_dir = tmp_path / ".pipelex"mocker.patch("pipelex.cli.commands.init.backends.config_manager", mock_config_manager)# Mock console provider@@ -145,7 +146,8 @@ class TestBackendCustomization:# Mock config_managermock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(tmp_path / ".pipelex")+ mock_config_manager.pipelex_config_dir = tmp_path / ".pipelex"+ mock_config_manager.global_config_dir = tmp_path / ".pipelex"mocker.patch("pipelex.cli.commands.init.backends.config_manager", mock_config_manager)# Mock console provider@@ -207,7 +209,7 @@ class TestBackendCustomization:# Mock config_managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=str(kit_configs_dir))mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)mocker.patch("typer.echo")@@ -228,7 +230,7 @@ class TestBackendCustomization:config_dir.mkdir()mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(config_dir)+ mock_config_manager.pipelex_config_dir = config_dirmocker.patch("pipelex.cli.commands.init.backends.config_manager", mock_config_manager)mock_console = mocker.MagicMock()diff --git a/tests/unit/pipelex/cli/test_concept_cmd.py b/tests/unit/pipelex/cli/test_concept_cmd.pyindex bcec1c9ce..dbe00d271 100644--- a/tests/unit/pipelex/cli/test_concept_cmd.py+++ b/tests/unit/pipelex/cli/test_concept_cmd.py@@ -3,7 +3,7 @@from __future__ import annotationsimport json-from typing import Any+from typing import Any, ClassVarfrom pipelex.builder.concept.concept_spec import ConceptStructureSpec, ConceptStructureSpecFieldTypefrom pipelex.cli.agent_cli.commands.concept_cmd import (@@ -126,6 +126,83 @@ class TestStructureFieldToDict:assert result["default"] == "pending"+class TestConceptCodeAliases:+ """Tests for concept_code alias handling in _parse_concept_spec_from_json."""++ _BASE: ClassVar[dict[str, Any]] = {+ "description": "A test concept",+ "refines": "Text",+ }++ def test_canonical_the_concept_code(self) -> None:+ spec = {**self._BASE, "the_concept_code": "Invoice"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Invoice"++ def test_alias_concept_code(self) -> None:+ spec = {**self._BASE, "concept_code": "Invoice"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Invoice"++ def test_alias_code(self) -> None:+ spec = {**self._BASE, "code": "Invoice"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Invoice"++ def test_alias_name(self) -> None:+ spec = {**self._BASE, "name": "Invoice"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Invoice"++ def test_alias_concept_name(self) -> None:+ spec = {**self._BASE, "concept_name": "Invoice"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Invoice"++ def test_canonical_ignores_alias(self) -> None:+ """When the_concept_code is present, alias keys are removed so Pydantic doesn't reject them."""+ spec = {**self._BASE, "the_concept_code": "Canonical", "name": "Alias"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Canonical"++ def test_multiple_aliases_all_cleaned_up(self) -> None:+ """When the_concept_code and multiple aliases are present, all aliases are removed."""+ spec = {**self._BASE, "concept_code": "Invoice", "name": "Alt", "code": "Alt2"}+ result = _parse_concept_spec_from_json(spec)+ assert result.the_concept_code == "Invoice"+++class TestStructureFieldStringShorthand:+ """A bare string in structure should be treated as a text field with that description."""++ def test_string_field_becomes_text(self) -> None:+ spec: dict[str, Any] = {+ "the_concept_code": "Simple",+ "description": "A simple concept",+ "structure": {+ "title": "The title of the item",+ },+ }+ result = _parse_concept_spec_from_json(spec)+ assert result.structure is not None+ assert result.structure["title"].type == ConceptStructureSpecFieldType.TEXT+ assert result.structure["title"].description == "The title of the item"++ def test_mixed_string_and_dict_fields(self) -> None:+ spec: dict[str, Any] = {+ "the_concept_code": "Mixed",+ "description": "A mixed concept",+ "structure": {+ "name": "The person's name",+ "age": {"type": "integer", "description": "Age in years"},+ },+ }+ result = _parse_concept_spec_from_json(spec)+ assert result.structure is not None+ assert result.structure["name"].type == ConceptStructureSpecFieldType.TEXT+ assert result.structure["age"].type == ConceptStructureSpecFieldType.INTEGER++class TestParseConceptSpecFromJson:"""Tests for _parse_concept_spec_from_json function."""diff --git a/tests/unit/pipelex/cli/test_doctor_cmd.py b/tests/unit/pipelex/cli/test_doctor_cmd.pynew file mode 100644index 000000000..2efe985d6--- /dev/null+++ b/tests/unit/pipelex/cli/test_doctor_cmd.py@@ -0,0 +1,124 @@+"""Unit tests for the doctor command — layered config resolution."""++from __future__ import annotations++from typing import TYPE_CHECKING++import pytest++if TYPE_CHECKING:+ from pathlib import Path++ from pytest_mock import MockerFixture++from pipelex.cli.commands.doctor_cmd import (+ check_backend_credentials,+ check_telemetry_config,+ do_doctor_cmd,+)+from pipelex.system.configuration.config_loader import ConfigLoader+from pipelex.system.telemetry.telemetry_config import TELEMETRY_CONFIG_FILE_NAME++# Minimal valid telemetry TOML — only [custom_posthog].mode is needed, rest defaults+TELEMETRY_OFF = '[custom_posthog]\nmode = "off"\n'+TELEMETRY_ANONYMOUS = '[custom_posthog]\nmode = "anonymous"\n'+++class TestDoctorLayeredResolution:+ """Verify that doctor checks use layered config resolution:+ project .pipelex/ first, fall back to global ~/.pipelex/.++ This covers the scenario where pipelex is installed globally and run+ from a project that may or may not have its own .pipelex/ directory.+ """++ def test_do_doctor_cmd_delegates_layered_resolution_to_checks(self, mocker: MockerFixture) -> None:+ """do_doctor_cmd should call check functions with no config_dir so they use layered resolution."""+ mock_check_config = mocker.patch(+ "pipelex.cli.commands.doctor_cmd.check_config_files",+ return_value=(True, 0, "OK"),+ )+ mock_check_telemetry = mocker.patch(+ "pipelex.cli.commands.doctor_cmd.check_telemetry_config",+ return_value=(True, "OK"),+ )+ mock_check_backends = mocker.patch(+ "pipelex.cli.commands.doctor_cmd.check_backend_credentials",+ return_value=(True, {}, "OK"),+ )+ mock_check_models = mocker.patch(+ "pipelex.cli.commands.doctor_cmd.check_models",+ return_value=(True, "OK", {}),+ )+ mocker.patch("pipelex.cli.commands.doctor_cmd.display_health_report")++ with pytest.raises(SystemExit) as exc_info:+ do_doctor_cmd(fix=False)+ assert exc_info.value.code == 0++ # All checks must be called without config_dir (layered resolution)+ mock_check_config.assert_called_once_with()+ mock_check_telemetry.assert_called_once_with()+ mock_check_backends.assert_called_once_with()+ mock_check_models.assert_called_once_with()++ def test_telemetry_check_falls_back_to_global(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """When project .pipelex/ exists but has no telemetry.toml, fall back to global ~/.pipelex/."""+ global_dir = tmp_path / "global_pipelex"+ project_dir = tmp_path / "project_pipelex"+ # Create both dirs but only put telemetry.toml in global+ global_dir.mkdir()+ project_dir.mkdir()+ (global_dir / TELEMETRY_CONFIG_FILE_NAME).write_text(TELEMETRY_OFF, encoding="utf-8")++ mocker.patch.object(ConfigLoader, "project_config_dir", new_callable=mocker.PropertyMock, return_value=project_dir)+ mocker.patch.object(ConfigLoader, "global_config_dir", new_callable=mocker.PropertyMock, return_value=global_dir)++ # No config_dir override → layered resolution should find it in global+ healthy, message = check_telemetry_config()+ assert healthy is True+ assert "off" in message++ def test_telemetry_check_uses_project_override(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """When project .pipelex/ has telemetry.toml, it should be used instead of global."""+ global_dir = tmp_path / "global_pipelex"+ project_dir = tmp_path / "project_pipelex"+ global_dir.mkdir()+ project_dir.mkdir()+ (global_dir / TELEMETRY_CONFIG_FILE_NAME).write_text(TELEMETRY_OFF, encoding="utf-8")+ (project_dir / TELEMETRY_CONFIG_FILE_NAME).write_text(TELEMETRY_ANONYMOUS, encoding="utf-8")++ mocker.patch.object(ConfigLoader, "project_config_dir", new_callable=mocker.PropertyMock, return_value=project_dir)+ mocker.patch.object(ConfigLoader, "global_config_dir", new_callable=mocker.PropertyMock, return_value=global_dir)++ healthy, message = check_telemetry_config()+ assert healthy is True+ assert "anonymous" in message++ def test_telemetry_check_with_explicit_config_dir_skips_layering(self, tmp_path: Path) -> None:+ """When config_dir is explicitly provided (e.g. --global), use it directly without layering."""+ explicit_dir = tmp_path / "explicit_pipelex"+ explicit_dir.mkdir()+ (explicit_dir / TELEMETRY_CONFIG_FILE_NAME).write_text(TELEMETRY_OFF, encoding="utf-8")++ healthy, _message = check_telemetry_config(config_dir=explicit_dir)+ assert healthy is True++ def test_backend_credentials_falls_back_to_global(self, mocker: MockerFixture, tmp_path: Path) -> None:+ """When project .pipelex/ exists but has no backends.toml, fall back to global."""+ global_dir = tmp_path / "global_pipelex"+ project_dir = tmp_path / "project_pipelex"+ project_dir.mkdir()+ global_inference_dir = global_dir / "inference"+ global_inference_dir.mkdir(parents=True)++ # Only global has backends.toml — with only the internal backend+ backends_content = "[internal]\nenabled = true\n"+ (global_inference_dir / "backends.toml").write_text(backends_content, encoding="utf-8")++ mocker.patch.object(ConfigLoader, "project_config_dir", new_callable=mocker.PropertyMock, return_value=project_dir)+ mocker.patch.object(ConfigLoader, "global_config_dir", new_callable=mocker.PropertyMock, return_value=global_dir)++ _healthy, _, message = check_backend_credentials()+ # Should find backends.toml in global, not report "not found"+ assert "not found" not in message.lower()diff --git a/tests/unit/pipelex/cli/test_init_cmd.py b/tests/unit/pipelex/cli/test_init_cmd.pyindex 749d4bfe7..8ec352518 100644--- a/tests/unit/pipelex/cli/test_init_cmd.py+++ b/tests/unit/pipelex/cli/test_init_cmd.py@@ -27,7 +27,7 @@ class TestInitCmd:# Mock get_configs_dir and config managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)# Execute@@ -51,7 +51,7 @@ class TestInitCmd:# Mock get_configs_dir and config managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)# Execute@@ -78,7 +78,7 @@ class TestInitCmd:# Mock get_configs_dir and config managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)# Execute@@ -110,7 +110,7 @@ class TestInitCmd:# Mock get_configs_dir and config managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)# Execute@@ -137,7 +137,7 @@ class TestInitCmd:# Mock get_configs_dir and config managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)mocker.patch("shutil.copy2", side_effect=PermissionError("Permission denied"))@@ -158,7 +158,7 @@ class TestInitCmd:# Mock get_configs_dir and config managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)# Execute@@ -188,7 +188,7 @@ class TestInitCmd:# Mock config_managermocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)# Execute dry-run@@ -216,7 +216,7 @@ class TestInitCmd:# Mock config_manager and customize functionmocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)mock_customize = mocker.patch("pipelex.cli.commands.init.backends.customize_backends_config")@@ -240,7 +240,7 @@ class TestInitCmd:# Mock config_manager and customize functionmocker.patch("pipelex.cli.commands.init.config_files.get_kit_configs_dir", return_value=kit_configs_dir)mock_config_manager = mocker.MagicMock()- mock_config_manager.pipelex_config_dir = str(target_dir)+ mock_config_manager.pipelex_config_dir = target_dirmocker.patch("pipelex.cli.commands.init.config_files.config_manager", mock_config_manager)mock_customize = mocker.patch("pipelex.cli.commands.init.backends.customize_backends_config")diff --git a/tests/unit/pipelex/cli/test_init_credentials.py b/tests/unit/pipelex/cli/test_init_credentials.pyindex b170e21bc..72b093b84 100644--- a/tests/unit/pipelex/cli/test_init_credentials.py+++ b/tests/unit/pipelex/cli/test_init_credentials.py@@ -126,7 +126,7 @@ class TestInitCredentials:mocker.patch.dict(os.environ, {"OPENAI_API_KEY": "sk-test"})mocker.patch("pipelex.cli.commands.init.credentials.config_manager",- global_config_dir=str(tmp_path),+ global_config_dir=tmp_path,)mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")mock_console: MagicMock = mocker.MagicMock()@@ -145,7 +145,7 @@ class TestInitCredentials:mocker.patch("pipelex.cli.commands.init.credentials.config_manager",- global_config_dir=str(tmp_path),+ global_config_dir=tmp_path,)mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask",@@ -175,7 +175,7 @@ class TestInitCredentials:mocker.patch("pipelex.cli.commands.init.credentials.config_manager",- global_config_dir=str(tmp_path),+ global_config_dir=tmp_path,)mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask",@@ -200,7 +200,7 @@ class TestInitCredentials:mocker.patch("pipelex.cli.commands.init.credentials.config_manager",- global_config_dir=str(tmp_path),+ global_config_dir=tmp_path,)mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask",@@ -222,7 +222,7 @@ class TestInitCredentials:backends_toml.write_text('[openai]\nenabled = false\napi_key = "${OPENAI_API_KEY}"\n\n[internal]\nenabled = true\n')mocker.patch("pipelex.cli.commands.init.credentials.config_manager",- global_config_dir=str(tmp_path),+ global_config_dir=tmp_path,)mock_prompt = mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask")mock_console: MagicMock = mocker.MagicMock()diff --git a/tests/unit/pipelex/cli/test_pipe_cmd.py b/tests/unit/pipelex/cli/test_pipe_cmd.pynew file mode 100644index 000000000..9b2659509--- /dev/null+++ b/tests/unit/pipelex/cli/test_pipe_cmd.py@@ -0,0 +1,580 @@+"""Unit tests for the agent CLI pipe command — non-nominal / tolerance cases."""++from __future__ import annotations++from typing import Any, ClassVar++import pytest+from pydantic import ValidationError++from pipelex.cli.agent_cli.commands.pipe_cmd import (+ _MODEL_TO_EXTRACT_TALENT, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ _MODEL_TO_IMG_GEN_TALENT, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ _MODEL_TO_LLM_TALENT, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ LLM_TALENT_TO_MODEL,+ _parse_pipe_spec_from_json, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ _pipe_spec_to_toml, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+ _resolve_talent_value, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+)++# ---------------------------------------------------------------------------+# Reverse talent mappings+# ---------------------------------------------------------------------------+++class TestReverseTalentMappings:+ """Verify the module-level reverse mappings are built correctly."""++ def test_llm_preset_with_prefix(self) -> None:+ assert _MODEL_TO_LLM_TALENT["$writing-creative"] == "creative-writer"++ def test_llm_preset_without_prefix(self) -> None:+ assert _MODEL_TO_LLM_TALENT["writing-creative"] == "creative-writer"++ def test_llm_all_presets_have_reverse_entries(self) -> None:+ for talent, preset in LLM_TALENT_TO_MODEL.items():+ assert _MODEL_TO_LLM_TALENT[preset] == talent or _MODEL_TO_LLM_TALENT[preset] in LLM_TALENT_TO_MODEL+ assert _MODEL_TO_LLM_TALENT[preset.lstrip("$@")] == talent or _MODEL_TO_LLM_TALENT[preset.lstrip("$@")] in LLM_TALENT_TO_MODEL++ def test_img_gen_preset_with_prefix(self) -> None:+ assert _MODEL_TO_IMG_GEN_TALENT["$gen-image"] == "gen-image"++ def test_img_gen_preset_without_prefix(self) -> None:+ assert _MODEL_TO_IMG_GEN_TALENT["gen-image"] == "gen-image"++ def test_extract_preset_with_prefix(self) -> None:+ assert _MODEL_TO_EXTRACT_TALENT["@default-text-from-pdf"] == "pdf-basic-text-extractor"++ def test_extract_preset_without_prefix(self) -> None:+ assert _MODEL_TO_EXTRACT_TALENT["default-text-from-pdf"] == "pdf-basic-text-extractor"+++# ---------------------------------------------------------------------------+# _resolve_talent_value+# ---------------------------------------------------------------------------+++class TestResolveTalentValue:+ """Tests for the preset-to-talent resolution helper."""++ # --- PipeLLM ---++ def test_valid_talent_passes_through(self) -> None:+ assert _resolve_talent_value("PipeLLM", "creative-writer") == "creative-writer"++ def test_preset_without_prefix_resolves(self) -> None:+ assert _resolve_talent_value("PipeLLM", "writing-creative") == "creative-writer"++ def test_preset_with_dollar_prefix_resolves(self) -> None:+ assert _resolve_talent_value("PipeLLM", "$writing-creative") == "creative-writer"++ def test_invalid_talent_passes_through(self) -> None:+ """Unknown values pass through so Pydantic can produce a clear error."""+ assert _resolve_talent_value("PipeLLM", "totally-wrong") == "totally-wrong"++ def test_engineering_code_resolves(self) -> None:+ assert _resolve_talent_value("PipeLLM", "engineering-code") == "coder"++ def test_retrieval_resolves(self) -> None:+ assert _resolve_talent_value("PipeLLM", "retrieval") == "data-retrieval"++ # --- PipeImgGen ---++ def test_img_gen_preset_resolves(self) -> None:+ assert _resolve_talent_value("PipeImgGen", "$gen-image-fast") == "gen-image-fast"++ def test_img_gen_valid_talent_passes_through(self) -> None:+ assert _resolve_talent_value("PipeImgGen", "gen-image-high-quality") == "gen-image-high-quality"++ # --- PipeExtract ---++ def test_extract_preset_resolves(self) -> None:+ assert _resolve_talent_value("PipeExtract", "default-extract-document") == "full-document-extractor"++ def test_extract_preset_with_at_resolves(self) -> None:+ assert _resolve_talent_value("PipeExtract", "@default-extract-image") == "image-text-extractor"++ # --- Unknown pipe types ---++ def test_unknown_pipe_type_passes_through(self) -> None:+ assert _resolve_talent_value("PipeCompose", "anything") == "anything"++ def test_pipe_search_passes_through(self) -> None:+ """PipeSearch has no reverse mapping; values pass through."""+ assert _resolve_talent_value("PipeSearch", "web-search") == "web-search"++ def test_dict_value_passes_through(self) -> None:+ """Non-string values (dict) should pass through without crashing."""+ result = _resolve_talent_value("PipeLLM", {"name": "creative-writer"})+ assert result == {"name": "creative-writer"}++ def test_list_value_passes_through(self) -> None:+ """Non-string values (list) should pass through without crashing."""+ result = _resolve_talent_value("PipeLLM", ["creative-writer"])+ assert result == ["creative-writer"]++ def test_int_value_passes_through(self) -> None:+ """Non-string values (int) should pass through without crashing."""+ result = _resolve_talent_value("PipeLLM", 42)+ assert result == 42+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — pipe_code aliases+# ---------------------------------------------------------------------------+++class TestPipeCodeAliases:+ """The parser should accept 'code', 'the_pipe_code', and 'name' as aliases for 'pipe_code'."""++ _BASE_LLM: ClassVar[dict[str, Any]] = {+ "description": "Test pipe",+ "llm_talent": "creative-writer",+ "inputs": {"text": "Text"},+ "output": "Text",+ "prompt": "Write something about @text",+ }++ def test_canonical_pipe_code(self) -> None:+ spec = {**self._BASE_LLM, "pipe_code": "my_pipe"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "my_pipe"++ def test_alias_code(self) -> None:+ spec = {**self._BASE_LLM, "code": "my_pipe"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "my_pipe"++ def test_alias_the_pipe_code(self) -> None:+ spec = {**self._BASE_LLM, "the_pipe_code": "my_pipe"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "my_pipe"++ def test_alias_name(self) -> None:+ spec = {**self._BASE_LLM, "name": "my_pipe"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "my_pipe"++ def test_canonical_ignores_alias(self) -> None:+ """When pipe_code is present, alias keys are removed so Pydantic doesn't reject them."""+ spec = {**self._BASE_LLM, "pipe_code": "canonical", "code": "alias"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "canonical"++ def test_multiple_aliases_all_cleaned_up(self) -> None:+ """When pipe_code and multiple aliases are present, all aliases are removed."""+ spec = {**self._BASE_LLM, "code": "my_pipe", "name": "alt"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "my_pipe"++ def test_three_aliases_all_cleaned_up(self) -> None:+ """When pipe_code and all aliases are present, all aliases are removed."""+ spec = {**self._BASE_LLM, "code": "my_pipe", "the_pipe_code": "alt", "name": "alt2"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.pipe_code == "my_pipe"+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — talent field aliases+# ---------------------------------------------------------------------------+++class TestTalentFieldAliases:+ """The parser should accept 'talent_name' and 'talent' as generic talent aliases."""++ _BASE: ClassVar[dict[str, Any]] = {+ "pipe_code": "test_pipe",+ "description": "Test pipe",+ "inputs": {"text": "Text"},+ "output": "Text",+ "prompt": "Write about @text",+ }++ def test_talent_name_alias_for_llm(self) -> None:+ spec = {**self._BASE, "talent_name": "creative-writer"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "creative-writer" # type: ignore[attr-defined]++ def test_talent_alias_for_llm(self) -> None:+ spec = {**self._BASE, "talent": "engineer"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "engineer" # type: ignore[attr-defined]++ def test_canonical_talent_field_ignores_alias(self) -> None:+ """When llm_talent is present, generic alias is removed so Pydantic doesn't reject it."""+ spec = {**self._BASE, "llm_talent": "coder", "talent_name": "engineer"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "coder" # type: ignore[attr-defined]++ def test_talent_alias_for_extract(self) -> None:+ spec = {+ "pipe_code": "test_extract",+ "description": "Extract pipe",+ "inputs": {"doc": "Document"},+ "output": "Page[]",+ "talent_name": "full-document-extractor",+ }+ result = _parse_pipe_spec_from_json("PipeExtract", spec)+ assert result.extract_talent == "full-document-extractor" # type: ignore[attr-defined]++ def test_talent_alias_for_img_gen(self) -> None:+ spec = {+ "pipe_code": "test_img_gen",+ "description": "Image gen pipe",+ "inputs": {"prompt_text": "ImgGenPrompt"},+ "output": "Image",+ "talent": "gen-image",+ "prompt": "Generate: $prompt_text",+ }+ result = _parse_pipe_spec_from_json("PipeImgGen", spec)+ assert result.img_gen_talent == "gen-image" # type: ignore[attr-defined]+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — preset-to-talent resolution+# ---------------------------------------------------------------------------+++class TestPresetToTalentResolution:+ """Preset names used where talent names are expected should be auto-resolved."""++ _BASE_LLM: ClassVar[dict[str, Any]] = {+ "pipe_code": "test_pipe",+ "description": "Test pipe",+ "inputs": {"text": "Text"},+ "output": "Text",+ "prompt": "Write about @text",+ }++ def test_preset_name_resolved_to_talent_for_llm(self) -> None:+ spec = {**self._BASE_LLM, "llm_talent": "writing-creative"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "creative-writer" # type: ignore[attr-defined]++ def test_preset_with_dollar_resolved_for_llm(self) -> None:+ spec = {**self._BASE_LLM, "llm_talent": "$writing-creative"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "creative-writer" # type: ignore[attr-defined]++ def test_valid_talent_unchanged_for_llm(self) -> None:+ spec = {**self._BASE_LLM, "llm_talent": "creative-writer"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "creative-writer" # type: ignore[attr-defined]++ def test_invalid_talent_raises_validation_error(self) -> None:+ spec = {**self._BASE_LLM, "llm_talent": "totally-invalid"}+ with pytest.raises(ValidationError):+ _parse_pipe_spec_from_json("PipeLLM", spec)++ def test_preset_via_generic_alias_also_resolved(self) -> None:+ """talent_name alias + preset value should both be handled."""+ spec = {**self._BASE_LLM, "talent_name": "engineering-code"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "coder" # type: ignore[attr-defined]++ def test_extract_preset_resolved(self) -> None:+ spec = {+ "pipe_code": "test_extract",+ "description": "Extract pipe",+ "inputs": {"doc": "Document"},+ "output": "Page[]",+ "extract_talent": "default-text-from-pdf",+ }+ result = _parse_pipe_spec_from_json("PipeExtract", spec)+ assert result.extract_talent == "pdf-basic-text-extractor" # type: ignore[attr-defined]++ def test_img_gen_preset_resolved(self) -> None:+ spec = {+ "pipe_code": "test_img_gen",+ "description": "Image gen pipe",+ "inputs": {"prompt_text": "ImgGenPrompt"},+ "output": "Image",+ "img_gen_talent": "$gen-image-high-quality",+ "prompt": "Generate: $prompt_text",+ }+ result = _parse_pipe_spec_from_json("PipeImgGen", spec)+ assert result.img_gen_talent == "gen-image-high-quality" # type: ignore[attr-defined]+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — output dict tolerance+# ---------------------------------------------------------------------------+++class TestOutputDictTolerance:+ """The parser should accept output as {"type": "ConceptName"} and extract the string."""++ _BASE_LLM: ClassVar[dict[str, Any]] = {+ "pipe_code": "test_pipe",+ "description": "Test pipe",+ "llm_talent": "creative-writer",+ "inputs": {"text": "Text"},+ "prompt": "Write about @text",+ }++ def test_output_as_string(self) -> None:+ spec = {**self._BASE_LLM, "output": "ImgGenPrompt"}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.output == "ImgGenPrompt"++ def test_output_as_dict_with_type_key(self) -> None:+ spec = {**self._BASE_LLM, "output": {"type": "ImgGenPrompt"}}+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.output == "ImgGenPrompt"++ def test_output_dict_without_type_key_passes_through(self) -> None:+ """If the dict has no 'type' key, let Pydantic handle the error."""+ spec = {**self._BASE_LLM, "output": {"name": "ImgGenPrompt"}}+ with pytest.raises(ValidationError):+ _parse_pipe_spec_from_json("PipeLLM", spec)+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — steps/branches 'pipe' → 'pipe_code' alias+# ---------------------------------------------------------------------------+++class TestStepsBranchesAlias:+ """Steps and branches should accept 'pipe' as an alias for 'pipe_code'."""++ def test_sequence_steps_pipe_alias(self) -> None:+ spec: dict[str, Any] = {+ "pipe_code": "my_seq",+ "description": "A sequence",+ "inputs": {"doc": "Document"},+ "output": "Text",+ "steps": [+ {"pipe": "step_one", "result": "intermediate"},+ {"pipe": "step_two", "result": "final"},+ ],+ }+ result = _parse_pipe_spec_from_json("PipeSequence", spec)+ assert result.steps[0].pipe_code == "step_one" # type: ignore[attr-defined]+ assert result.steps[1].pipe_code == "step_two" # type: ignore[attr-defined]++ def test_sequence_steps_pipe_code_canonical(self) -> None:+ spec: dict[str, Any] = {+ "pipe_code": "my_seq",+ "description": "A sequence",+ "inputs": {"doc": "Document"},+ "output": "Text",+ "steps": [+ {"pipe_code": "step_one", "result": "intermediate"},+ ],+ }+ result = _parse_pipe_spec_from_json("PipeSequence", spec)+ assert result.steps[0].pipe_code == "step_one" # type: ignore[attr-defined]++ def test_parallel_branches_pipe_alias(self) -> None:+ spec: dict[str, Any] = {+ "pipe_code": "my_parallel",+ "description": "Parallel branches",+ "inputs": {"doc": "Document"},+ "output": "Text",+ "add_each_output": True,+ "branches": [+ {"pipe": "branch_a", "result": "result_a"},+ {"pipe": "branch_b", "result": "result_b"},+ ],+ }+ result = _parse_pipe_spec_from_json("PipeParallel", spec)+ assert result.branches[0].pipe_code == "branch_a" # type: ignore[attr-defined]+ assert result.branches[1].pipe_code == "branch_b" # type: ignore[attr-defined]+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — PipeCondition expression alias+# ---------------------------------------------------------------------------+++class TestConditionExpressionAlias:+ """PipeCondition should accept 'expression' as alias for 'jinja2_expression_template'."""++ def test_expression_alias(self) -> None:+ spec: dict[str, Any] = {+ "pipe_code": "my_condition",+ "description": "Route by status",+ "inputs": {"status": "Text"},+ "output": "Text",+ "expression": "{{ status }}",+ "outcomes": {"high": "handle_high", "low": "handle_low"},+ "default_outcome": "handle_default",+ }+ result = _parse_pipe_spec_from_json("PipeCondition", spec)+ assert result.jinja2_expression_template == "{{ status }}" # type: ignore[attr-defined]++ def test_canonical_expression_field(self) -> None:+ spec: dict[str, Any] = {+ "pipe_code": "my_condition",+ "description": "Route by status",+ "inputs": {"status": "Text"},+ "output": "Text",+ "jinja2_expression_template": "{{ status }}",+ "outcomes": {"high": "handle_high", "low": "handle_low"},+ "default_outcome": "handle_default",+ }+ result = _parse_pipe_spec_from_json("PipeCondition", spec)+ assert result.jinja2_expression_template == "{{ status }}" # type: ignore[attr-defined]+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — pipe_type alias in JSON+# ---------------------------------------------------------------------------+++class TestPipeTypeAlias:+ """'pipe_type' in spec JSON should be accepted as alias for 'type'."""++ def test_type_extracted_from_spec(self) -> None:+ """When type is in the spec dict it should be used (and popped)."""+ spec: dict[str, Any] = {+ "type": "PipeLLM",+ "pipe_code": "test",+ "description": "Test",+ "llm_talent": "creative-writer",+ "inputs": {"text": "Text"},+ "output": "Text",+ "prompt": "Write about @text",+ }+ # Simulate what pipe_cmd does: pop 'type' and pass it as pipe_type+ pipe_type = spec.pop("type")+ result = _parse_pipe_spec_from_json(pipe_type, spec)+ assert result.pipe_code == "test"+++# ---------------------------------------------------------------------------+# _parse_pipe_spec_from_json — invalid pipe type+# ---------------------------------------------------------------------------+++class TestInvalidPipeType:+ """Invalid pipe types should raise ValueError."""++ def test_invalid_pipe_type(self) -> None:+ with pytest.raises(ValueError, match="Invalid pipe type"):+ _parse_pipe_spec_from_json("PipeNonExistent", {"pipe_code": "x", "description": "x"})+++# ---------------------------------------------------------------------------+# _pipe_spec_to_toml — talent-to-model in TOML output+# ---------------------------------------------------------------------------+++class TestPipeSpecToToml:+ """Verify TOML output maps talents to model presets correctly."""++ _BASE_LLM: ClassVar[dict[str, Any]] = {+ "pipe_code": "my_llm_pipe",+ "description": "Test LLM pipe",+ "llm_talent": "creative-writer",+ "inputs": {"text": "Text"},+ "output": "Text",+ "prompt": "Write about @text",+ }++ def test_llm_talent_becomes_model_preset_in_toml(self) -> None:+ spec = _parse_pipe_spec_from_json("PipeLLM", {**self._BASE_LLM})+ toml = _pipe_spec_to_toml(spec)+ assert 'model = "$writing-creative"' in toml++ def test_llm_preset_input_still_maps_to_correct_model(self) -> None:+ """If the agent provides a preset name, it should resolve and then map to model."""+ spec = _parse_pipe_spec_from_json("PipeLLM", {**self._BASE_LLM, "llm_talent": "engineering-structured"})+ toml = _pipe_spec_to_toml(spec)+ assert 'model = "$engineering-structured"' in toml++ def test_extract_talent_becomes_model_in_toml(self) -> None:+ spec = _parse_pipe_spec_from_json(+ "PipeExtract",+ {+ "pipe_code": "my_extract",+ "description": "Extract pipe",+ "inputs": {"doc": "Document"},+ "output": "Page[]",+ "extract_talent": "full-document-extractor",+ },+ )+ toml = _pipe_spec_to_toml(spec)+ assert 'model = "@default-extract-document"' in toml++ def test_img_gen_talent_becomes_model_in_toml(self) -> None:+ spec = _parse_pipe_spec_from_json(+ "PipeImgGen",+ {+ "pipe_code": "my_img_gen",+ "description": "Image gen pipe",+ "inputs": {"prompt_text": "ImgGenPrompt"},+ "output": "Image",+ "img_gen_talent": "gen-image",+ "prompt": "Generate: $prompt_text",+ },+ )+ toml = _pipe_spec_to_toml(spec)+ assert 'model = "$gen-image"' in toml++ def test_toml_contains_pipe_section(self) -> None:+ spec = _parse_pipe_spec_from_json("PipeLLM", {**self._BASE_LLM})+ toml = _pipe_spec_to_toml(spec)+ assert "[pipe.my_llm_pipe]" in toml+ assert 'type = "PipeLLM"' in toml++ def test_toml_contains_prompt(self) -> None:+ spec = _parse_pipe_spec_from_json("PipeLLM", {**self._BASE_LLM})+ toml = _pipe_spec_to_toml(spec)+ assert 'prompt = "Write about @text"' in toml++ def test_sequence_toml_has_steps(self) -> None:+ spec = _parse_pipe_spec_from_json(+ "PipeSequence",+ {+ "pipe_code": "my_seq",+ "description": "A sequence",+ "inputs": {"doc": "Document"},+ "output": "Text",+ "steps": [+ {"pipe": "step_one", "result": "intermediate"},+ {"pipe": "step_two", "result": "final"},+ ],+ },+ )+ toml = _pipe_spec_to_toml(spec)+ assert "step_one" in toml+ assert "step_two" in toml+++# ---------------------------------------------------------------------------+# End-to-end: combined tolerance scenarios (the original bug)+# ---------------------------------------------------------------------------+++class TestEndToEndTolerance:+ """Reproduce the exact bug scenario that motivated these changes."""++ def test_original_bug_preset_as_talent_with_dict_output(self) -> None:+ """The agent sent 'writing-creative' (preset) and output as dict — both should be tolerated."""+ spec: dict[str, Any] = {+ "pipe_code": "generate_prompt",+ "description": "Generate an image prompt from an idea",+ "llm_talent": "writing-creative",+ "inputs": {"idea": "Text"},+ "output": {"type": "ImgGenPrompt"},+ "prompt": "Generate a creative image prompt based on @idea",+ }+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ assert result.llm_talent == "creative-writer" # type: ignore[attr-defined]+ assert result.output == "ImgGenPrompt"++ def test_original_bug_toml_output_has_correct_model(self) -> None:+ """After resolution, the TOML should contain the correct model preset."""+ spec: dict[str, Any] = {+ "pipe_code": "generate_prompt",+ "description": "Generate an image prompt from an idea",+ "llm_talent": "writing-creative",+ "inputs": {"idea": "Text"},+ "output": {"type": "ImgGenPrompt"},+ "prompt": "Generate a creative image prompt based on @idea",+ }+ result = _parse_pipe_spec_from_json("PipeLLM", spec)+ toml = _pipe_spec_to_toml(result)+ assert 'model = "$writing-creative"' in toml+ assert 'output = "ImgGenPrompt"' in tomldiff --git a/tests/unit/pipelex/cogt/models/test_model_deck_references.py b/tests/unit/pipelex/cogt/models/test_model_deck_references.pyindex cd60574df..a6164b956 100644--- a/tests/unit/pipelex/cogt/models/test_model_deck_references.py+++ b/tests/unit/pipelex/cogt/models/test_model_deck_references.py@@ -36,7 +36,7 @@ class TestModelDeckReferences:@pytest.fixture(scope="class")def model_deck_blueprint(self) -> ModelDeckBlueprint:"""Load actual model deck blueprint from TOML files."""- model_deck_paths = ModelManager.get_model_deck_paths(deck_dir_path=config_manager.model_decks_dir_path)+ model_deck_paths = ModelManager.get_model_deck_paths(deck_dir_path=str(config_manager.model_decks_dir_path))return load_model_deck_blueprint(model_deck_paths=model_deck_paths)@pytest.fixture(scope="class")@@ -94,7 +94,7 @@ class TestModelDeckReferences:known_handles: dict[str, ModelType] = {}backends_dir = config_manager.backends_dir_path- toml_files = find_files_in_dir(backends_dir, pattern="*.toml", is_recursive=False)+ toml_files = find_files_in_dir(str(backends_dir), pattern="*.toml", is_recursive=False)for toml_path in toml_files:backend_data = load_toml_from_path_if_exists(str(toml_path))if backend_data:diff --git a/tests/unit/pipelex/graph/test_graph_rendering.py b/tests/unit/pipelex/graph/test_graph_rendering.pynew file mode 100644index 000000000..4fc51a0c4--- /dev/null+++ b/tests/unit/pipelex/graph/test_graph_rendering.py@@ -0,0 +1,31 @@+"""Unit tests for graph rendering helpers."""++from __future__ import annotations++from pipelex.graph.graph_rendering import (+ _sanitize_graph_name, # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]+)+++class TestSanitizeGraphName:+ """Tests for the _sanitize_graph_name helper that prevents path traversal."""++ def test_plain_filename(self) -> None:+ """A plain filename should pass through unchanged."""+ assert _sanitize_graph_name("dry_run.html") == "dry_run.html"++ def test_traversal_stripped(self) -> None:+ """Directory traversal components should be stripped."""+ assert _sanitize_graph_name("../../etc/passwd") == "passwd"++ def test_absolute_path_stripped(self) -> None:+ """Absolute paths should be reduced to just the filename."""+ assert _sanitize_graph_name("/var/data/evil.html") == "evil.html"++ def test_subdirectory_stripped(self) -> None:+ """Subdirectory paths should be reduced to just the filename."""+ assert _sanitize_graph_name("subdir/graph.html") == "graph.html"++ def test_empty_string_returns_default(self) -> None:+ """An empty string should return the default filename."""+ assert _sanitize_graph_name("") == "graph.html"diff --git a/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.py b/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.pyindex 1f60b90bd..51257a4f6 100644--- a/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.py+++ b/tests/unit/pipelex/system/pipelex_service/test_pipelex_service_config.py@@ -33,7 +33,7 @@ class TestPipelexServiceConfig:def test_load_pipelex_service_config_if_exists_returns_none(self) -> None:"""Test load_pipelex_service_config_if_exists returns None when file doesn't exist."""with tempfile.TemporaryDirectory() as temp_dir:- config = load_pipelex_service_config_if_exists(config_dir=temp_dir)+ config = load_pipelex_service_config_if_exists(config_dir=pathlib.Path(temp_dir))assert config is Nonedef test_load_pipelex_service_config_if_exists_returns_config(self) -> None:@@ -45,6 +45,6 @@ terms_accepted = falseconfig_path = os.path.join(temp_dir, PIPELEX_SERVICE_CONFIG_FILE_NAME)pathlib.Path(config_path).write_text(config_content, encoding="utf-8")- config = load_pipelex_service_config_if_exists(config_dir=temp_dir)+ config = load_pipelex_service_config_if_exists(config_dir=pathlib.Path(temp_dir))assert config is not Noneassert config.agreement.terms_accepted is Falsediff --git a/tests/unit/pipelex/system/test_config_resolution.py b/tests/unit/pipelex/system/test_config_resolution.pyindex c9dddf79b..27edb4b8f 100644--- a/tests/unit/pipelex/system/test_config_resolution.py+++ b/tests/unit/pipelex/system/test_config_resolution.py@@ -96,7 +96,7 @@ class TestConfigResolution:loader = ConfigLoader()- assert loader.global_config_dir == str(fake_home / ".pipelex")+ assert loader.global_config_dir == fake_home / ".pipelex"def test_project_config_dir_when_exists(self, tmp_path: Path, mocker: MockerFixture) -> None:"""project_config_dir returns the path when .pipelex exists at the project root."""@@ -108,7 +108,7 @@ class TestConfigResolution:loader = ConfigLoader()- assert loader.project_config_dir == str((project_dir / ".pipelex").resolve())+ assert loader.project_config_dir == (project_dir / ".pipelex").resolve()def test_project_config_dir_none_when_no_pipelex_dir(self, tmp_path: Path, mocker: MockerFixture) -> None:"""project_config_dir returns None when project root has no .pipelex directory."""@@ -132,7 +132,7 @@ class TestConfigResolution:loader = ConfigLoader()- assert loader.pipelex_config_dir == str((project_dir / ".pipelex").resolve())+ assert loader.pipelex_config_dir == (project_dir / ".pipelex").resolve()def test_effective_config_dir_falls_back_to_global(self, tmp_path: Path, mocker: MockerFixture) -> None:"""pipelex_config_dir returns global path when no project .pipelex exists."""@@ -148,7 +148,7 @@ class TestConfigResolution:loader = ConfigLoader()- assert loader.pipelex_config_dir == str(fake_home / ".pipelex")+ assert loader.pipelex_config_dir == fake_home / ".pipelex"def test_project_root_returns_str_when_found(self, tmp_path: Path, mocker: MockerFixture) -> None:"""project_root returns the project root as a string."""@@ -161,7 +161,7 @@ class TestConfigResolution:loader = ConfigLoader()- assert loader.project_root == str(project_dir.resolve())+ assert loader.project_root == project_dir.resolve()def test_project_root_returns_none_without_markers(self, mocker: MockerFixture) -> None:"""project_root returns None when no project root markers are found.@@ -193,10 +193,10 @@ class TestConfigResolution:loader = ConfigLoader()- assert loader.backends_file_path == str(inference_dir / "backends.toml")- assert loader.backends_dir_path == str(backends_dir)- assert loader.routing_profiles_file_path == str(inference_dir / "routing_profiles.toml")- assert loader.model_decks_dir_path == str(deck_dir)+ assert loader.backends_file_path == inference_dir / "backends.toml"+ assert loader.backends_dir_path == backends_dir+ assert loader.routing_profiles_file_path == inference_dir / "routing_profiles.toml"+ assert loader.model_decks_dir_path == deck_dirdef test_inference_files_fallback_to_global(self, tmp_path: Path, mocker: MockerFixture) -> None:"""Inference file paths fall back to global dir when project dir has no files."""@@ -216,7 +216,7 @@ class TestConfigResolution:loader = ConfigLoader()# backends.toml exists in global, so it should resolve there- assert loader.backends_file_path == str(global_config / "backends.toml")+ assert loader.backends_file_path == global_config / "backends.toml"def test_ensure_global_config_created_on_first_run(self, tmp_path: Path, mocker: MockerFixture) -> None:"""ensure_global_config_exists creates ~/.pipelex/ with template files when it doesn't exist."""@@ -285,5 +285,5 @@ class TestConfigResolution:global_dir = loader.global_config_dir# Verify the path is valid and uses the correct separator for the platform- assert Path(global_dir).name == ".pipelex"- assert Path(global_dir).parent == fake_home+ assert global_dir.name == ".pipelex"+ assert global_dir.parent == fake_homediff --git a/uv.lock b/uv.lockindex c7f64e8ab..d6da7d91f 100644--- a/uv.lock+++ b/uv.lock@@ -3313,7 +3313,7 @@ wheels = [[[package]]name = "pipelex"-version = "0.20.4"+version = "0.20.5"source = { editable = "." }dependencies = [{ name = "aiofiles" },