Skip to content

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.

Feature/execute plx (#392)

Thomas Hebrarda7b4f657d6a5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 904501660..f23e362ca 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,10 @@
# Changelog
-## Unreleased
+## [v0.13.2] - 2025-10-25
+
+### Added
+
+- Added the `n8n` documentation page for the [n8n-nodes-pipelex](https://github.com/Pipelex/n8n-nodes-pipelex) package.
### Changed
diff --git a/PLAN.md b/PLAN.md
deleted file mode 100644
index 900544b65..000000000
--- a/PLAN.md
+++ /dev/null
@@ -1,292 +0,0 @@
-# Goal
-
-Add a `kit` command group that:
-
-1. Exports each `pipelex.kit/agents/*.md` to **Cursor** as `.cursor/rules/*.mdc` (adds YAML front-matter from `index.toml`).
-2. Builds a **merged single-file rules block** from ordered fragments (with `demote=1`) and inserts/updates it in targets (`AGENTS.md`, `CLAUDE.md`, etc.) using **marker spans**.
- All parsing/merging via **markdown-parser-py**; config via **TOML → dict** (`toml_utils`) → **Pydantic v2** models.
-
----
-
-# Package layout (as agreed)
-
-```
-pipelex/kit/
- __init__.py
- index.toml
- agents/
- pytest_standards.md
- python_standards.md
- run_pipelines.md
- write_pipelex.md
- configs/
- ... (as provided)
- migrations/
- ... (optional)
-```
-
----
-
-# Pydantic v2 models (dict → object via `model_validate`)
-
-```python
-# pipelex/kit/index_models.py
-from pydantic import BaseModel, Field
-from typing import Optional, List, Dict, Any
-
-class AgentsMerge(BaseModel):
- order: List[str]
- demote: int = 1
-
-class CursorFileOverride(BaseModel):
- front_matter: Dict[str, Any] = Field(default_factory=dict)
-
-class CursorSpec(BaseModel):
- front_matter: Dict[str, Any] = Field(default_factory=dict)
- files: Dict[str, CursorFileOverride] = Field(default_factory=dict)
-
-class Target(BaseModel):
- id: str
- path: str
- strategy: str # "merge" (for now)
- marker_begin: str
- marker_end: str
- parent: Optional[str] = None
-
-class KitIndex(BaseModel):
- meta: Dict[str, Any] = Field(default_factory=dict)
- agents: AgentsMerge
- cursor: CursorSpec
- targets: List[Target]
-```
-
-**Load `index.toml` using your utils:**
-
-```python
-# pipelex/kit/index_loader.py
-from pipelex.tools.misc.toml_utils import load_toml_from_path, TomlError
-from importlib.resources import files
-from .index_models import KitIndex
-
-def load_index() -> KitIndex:
- path = files("pipelex.kit") / "index.toml"
- data = load_toml_from_path(str(path))
- return KitIndex.model_validate(data)
-```
-
----
-
-# CLI integration (Typer)
-
-Add a **`kit`** sub-app under your existing CLI:
-
-```python
-# pipelex/cli/commands/kit_cmd.py
-import typer
-from pathlib import Path
-from typing_extensions import Annotated
-from pipelex.kit.index_loader import load_index
-from pipelex.kit.paths import get_agents_dir # small helper shown below
-from pipelex.kit.cursor_export import export_cursor_rules
-from pipelex.kit.targets_update import build_merged_rules, update_targets
-
-kit_app = typer.Typer(help="Manage kit assets: export Cursor rules and merge agent docs")
-
-@kit_app.command("sync")
-def sync(
- repo_root: Annotated[Path, typer.Option("--repo-root", dir_okay=True, writable=True)] = Path("."),
- cursor: Annotated[bool, typer.Option("--cursor/--no-cursor")] = True,
- single_files: Annotated[bool, typer.Option("--single-files/--no-single-files")] = True,
- dry_run: Annotated[bool, typer.Option("--dry-run")] = False,
- diff: Annotated[bool, typer.Option("--diff")] = False,
- backup: Annotated[str | None, typer.Option("--backup")] = None,
- force: Annotated[bool, typer.Option("--force")] = False,
-):
- idx = load_index()
- agents_dir = get_agents_dir()
-
- if cursor:
- export_cursor_rules(agents_dir, repo_root / ".cursor" / "rules", idx, dry_run=dry_run)
-
- if single_files:
- merged_md = build_merged_rules(agents_dir, idx) # ordered + demoted
- update_targets(repo_root, merged_md, idx.targets, dry_run=dry_run, diff=diff, backup=backup, force=force)
-```
-
-Wire it into your main CLI:
-
-```python
-# in your main cli module
-from pipelex.cli.commands.kit_cmd import kit_app
-app.add_typer(kit_app, name="kit", help="Manage kit assets")
-```
-
----
-
-# Core helpers
-
-## Paths
-
-```python
-# pipelex/kit/paths.py
-from importlib.resources import files
-from typing import Any
-from importlib.abc import Traversable
-
-def get_kit_root() -> Traversable:
- return files("pipelex.kit")
-
-def get_agents_dir() -> Traversable:
- return get_kit_root() / "agents"
-```
-
-## Cursor export (.md → .mdc with YAML front matter)
-
-```python
-# pipelex/kit/cursor_export.py
-from typing import Iterable
-from pathlib import Path
-import textwrap
-import yaml # pyyaml (MIT)
-from importlib.abc import Traversable
-from .index_models import KitIndex
-from pipelex.tools.misc.toml_utils import TomlError # (for symmetry if needed)
-
-def _iter_agent_files(agents_dir: Traversable) -> Iterable[tuple[str, str]]:
- for child in agents_dir.iterdir():
- if child.name.endswith(".md") and child.is_file():
- yield child.name, child.read_text(encoding="utf-8")
-
-def _front_matter_for(name: str, idx: KitIndex) -> dict:
- base = dict(idx.cursor.front_matter)
- key = name.removesuffix(".md")
- if key in idx.cursor.files:
- base |= idx.cursor.files[key].front_matter
- return base
-
-def export_cursor_rules(agents_dir: Traversable, out_dir: Path, idx: KitIndex, dry_run: bool=False) -> None:
- out_dir.mkdir(parents=True, exist_ok=True)
- for fname, body in _iter_agent_files(agents_dir):
- fm = _front_matter_for(fname, idx)
- yaml_block = "---\n" + yaml.safe_dump(fm, sort_keys=False).rstrip() + "\n---\n"
- mdc = yaml_block + body
- out_path = out_dir / (fname.removesuffix(".md") + ".mdc")
- if dry_run:
- typer.echo(f"[DRY] write {out_path}")
- else:
- out_path.write_text(mdc, encoding="utf-8")
-```
-
-## Merging for single-file targets (markdown-parser-py)
-
-```python
-# pipelex/kit/targets_update.py
-from dataclasses import dataclass
-from pathlib import Path
-from importlib.abc import Traversable
-from typing import List
-import difflib
-import typer
-
-from markdown_parser_py import Doc # replace with actual import names
-from markdown_parser_py import parse as md_parse, render as md_render # adjust to real API
-
-from .index_models import KitIndex, Target
-from .markers import find_span, wrap, replace_span
-from pipelex.tools.misc.toml_utils import load_toml_from_path # (not strictly needed here)
-
-def _read_agent_file(agents_dir: Traversable, name: str) -> str:
- return (agents_dir / name).read_text(encoding="utf-8")
-
-def _demote(doc: Doc, n: int) -> Doc:
- # Walk headings and +n to their level (implementation per markdown-parser-py API)
- # pseudo:
- # for h in doc.headings(): h.level += n
- return doc
-
-def build_merged_rules(agents_dir: Traversable, idx: KitIndex) -> str:
- parts: List[str] = []
- for name in idx.agents.order:
- md = _read_agent_file(agents_dir, name)
- d = md_parse(md)
- d = _demote(d, idx.agents.demote)
- parts.append(md_render(d).rstrip())
- return ("\n\n".join(parts)).strip() + "\n"
-
-def _insert_block_with_ast(target_md: str, block_md: str, parent: str | None) -> str:
- # Parse both; locate parent heading (if any) or choose heuristic (after first H1 or end)
- # Attach block as a new section. Return rendered string.
- tdoc = md_parse(target_md or "")
- bdoc = md_parse(block_md)
- # ... attach via library’s attach API (level handling already demoted)
- return md_render(tdoc)
-
-def _diff(before: str, after: str, path: str) -> str:
- return "".join(difflib.unified_diff(before.splitlines(True), after.splitlines(True), fromfile=path, tofile=path))
-
-def update_targets(repo_root: Path, merged_rules: str, targets: List[Target],
- dry_run: bool, diff: bool, backup: str | None, force: bool) -> None:
- for t in targets:
- p = repo_root / t.path
- before = p.read_text(encoding="utf-8") if p.exists() else ""
- span = find_span(before, t.marker_begin, t.marker_end)
-
- if span:
- after_block = wrap(t.marker_begin, t.marker_end, merged_rules)
- after = replace_span(before, span, after_block)
- else:
- inserted = _insert_block_with_ast(before, merged_rules, t.parent)
- after = inserted if inserted.endswith("\n") else inserted + "\n"
- # wrap only the inserted region — simplest approach is to wrap merged_rules before insert
- # or insert markers during AST attach (implementation detail)
-
- if dry_run:
- typer.echo(f"[DRY] update {p}")
- if diff:
- typer.echo(_diff(before, after, str(p)))
- else:
- if backup and p.exists():
- (p.with_suffix(p.suffix + backup)).write_text(before, encoding="utf-8")
- p.parent.mkdir(parents=True, exist_ok=True)
- p.write_text(after, encoding="utf-8")
-```
-
-## Markers
-
-```python
-# pipelex/kit/markers.py
-def find_span(text: str, begin: str, end: str):
- s = text.find(begin)
- if s == -1: return None
- e = text.find(end, s)
- if e == -1: return None
- e += len(end)
- return (s, e)
-
-def wrap(begin: str, end: str, md: str) -> str:
- return f"{begin}\n{md.rstrip()}\n{end}"
-
-def replace_span(text: str, span: tuple[int,int], replacement: str) -> str:
- s, e = span
- return text[:s] + replacement + text[e:]
-```
-
----
-
-# Behavior rules (quick)
-
-* **Cursor**: overwrite `.cursor/rules/*.mdc` each run (we own them).
-* **Single-file**: only mutate content within our markers; if absent, **insert via AST** and add markers.
-* **Demote before concat** (per `index.toml`).
-* Preserve front-matter/encoding/line endings.
-* `--dry-run` prints plan; `--diff` shows unified diff; `--backup` writes `*.bak`.
-
----
-
-# Exit codes
-
-* `0` success / no changes
-* `1` failures (I/O, parse, invalid index, write blocked)
-* `2` ambiguous parent resolution (if you choose to enforce)
-
-This plugs directly into your existing CLI, uses your TOML loader + Pydantic v2, and scopes the implementation clearly for another SWE to take over.
diff --git a/docs/pages/build-reliable-ai-workflows-with-pipelex/pipe-operators/PipeLLM.md b/docs/pages/build-reliable-ai-workflows-with-pipelex/pipe-operators/PipeLLM.md
index a608ccf65..99ea96c26 100644
--- a/docs/pages/build-reliable-ai-workflows-with-pipelex/pipe-operators/PipeLLM.md
+++ b/docs/pages/build-reliable-ai-workflows-with-pipelex/pipe-operators/PipeLLM.md
@@ -32,7 +32,7 @@ Describe the provided image in great detail.
"""
```
-**Important**: Do NOT reference image variables in your prompt template using `@image` or `$image`. Images are automatically passed to vision-enabled LLMs and should not be treated as text variables.
+**Important**: It is necessary to tag the image variable in the prompt with `@image` or `$image`, just like with regular objects.
**Flexible Image Inputs**
diff --git a/mkdocs.yml b/mkdocs.yml
index 90ce4672c..9b3104d63 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,9 +44,9 @@ extra:
- icon: fontawesome/brands/twitter
link: https://x.com/PipelexAI
name: Pipelex on X
- # - icon: fontawesome/brands/discord
- # link: https://go.pipelex.com/discord
- # name: Pipelex on Discord
+ - icon: fontawesome/brands/discord
+ link: https://go.pipelex.com/discord
+ name: Pipelex on Discord
generator: false
plugins:
@@ -134,6 +134,7 @@ nav:
- LLM Providers & Models: pages/configuration/config-technical/inference-backend-config.md
- API Reference:
- API Guide: pages/api/index.md
+ - n8n Node: https://pipelex.github.io/n8n-nodes-pipelex/
- Configuration:
- Overview: pages/configuration/index.md
- Pipeline Validation Configuration:
diff --git a/pyproject.toml b/pyproject.toml
index 995c78fdb..e780319da 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,8 +1,8 @@
[project]
name = "pipelex"
-version = "0.13.1"
+version = "0.13.2"
description = "Pipelex is an open-source dev tool based on a simple declarative language that lets you define replicable, structured, composable LLM pipelines."
-authors = [{ name = "Evotis S.A.S.", email = "[email protected]" }]
+authors = [{ name = "Evotis S.A.S.", email = "[email protected]" }]
maintainers = [{ name = "Pipelex staff", email = "[email protected]" }]
license = "MIT"
readme = "README.md"
diff --git a/uv.lock b/uv.lock
index ccd76480b..2b19d373e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1900,7 +1900,7 @@ wheels = [
[[package]]
name = "pipelex"
-version = "0.13.1"
+version = "0.13.2"
source = { editable = "." }
dependencies = [
{ name = "aiofiles" },