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/Readme-hero-website-line · L-260924-58e869 (#1242)

Louis Choquel5275a4162607
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e04e2fab..6c810d182 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@
### Changed
-- **The README leads with the hosted route**: its quick start is the onboarding region included from `Pipelex/.github` — sign up at app.pipelex.com, then the Pipelex plugin in Claude Code or Codex or the Pipelex MCP in ChatGPT or Claude — and the runtime's own install, configuration and first run follow under their own heading, **Run it yourself**. The CV batch screening walkthrough moved from the README to the cookbook in the documentation.
+- **The README leads with the hosted route**: its quick start is the onboarding region included from `Pipelex/.github` — sign up at app.pipelex.com, then the Pipelex plugin in Claude Code or Codex or the Pipelex MCP in ChatGPT or Claude — and the runtime's own install, configuration and first run follow under their own heading, **Run it yourself**. The CV batch screening walkthrough moved from the README to the cookbook in the documentation. Its hero is the website's line, "Turn your expertise into an AI-powered App, MCP or API", with a paragraph on building a method with your coding agent and where it runs, and **What a method looks like** and **Why methods?** follow the install instead of preceding it.
- **A run's `analytics_groups` is renamed `extras` (Breaking)**: the base library no longer names an analytics concept in its run model or its job-preparation signatures. `RunMetadata.analytics_groups`, the runtime-bridge payload's `analytics_groups`, and the `analytics_groups` parameter of `pipeline_run_setup`, `prepare_pipe_job`, `PipelexKernel.make` and `PipelexRunner` are now `extras`: an opaque `dict[str, str]` of labels the host attaches to a run, which the library never reads by name. The module `pipelex.system.analytics_groups` is now `pipelex.system.run_extras`, with `validate_run_extras`, `RUN_EXTRAS_KEY_PATTERN`, `RUN_EXTRAS_VALUE_PATTERN` and `RUN_EXTRAS_MAX_ENTRIES`, and the span attribute `pipelex.run.analytics_groups` is now `pipelex.run.extras` (`PipelexSpanAttr.RUN_EXTRAS`). Behaviour is unchanged: the mapping is validated where it enters under the same bounds, and telemetry still forwards it whole as the PostHog groups of each capture. There is no alias; a host passing `analytics_groups` must pass `extras` instead.
- **Pipelex's own telemetry stream receives the run's `user_id` as it is**: the Gateway stream sent a one-way digest of the caller taken inside the Gateway-key hash, and carried a `deployment` group instead of the run's own groups. It now resolves identity like the operator's identified stream — the run's `user_id` is the PostHog `distinct_id` and its `extras` ride the groups facet — so a host's events and the runtime's land on the same person and the same organization. The `NAMESPACED` identity policy and the `deployment` group type are removed. Anything that names no caller still reports under the Gateway-key hash.
- **`BundleValidatorProtocol.validate_bundles` requires `caller_identity` (Breaking)**: a validator is handed who asked for the validation, `None` meaning nobody, so a hosted `/validate` attributes its telemetry to its caller. Every validator implementation must accept the argument, and a host must pass it — `caller_identity=self.caller_identity` from a `PipelexMTHDSProtocol` runner. `validate_bundles_in_process`, `validate_bundle`, `dry_run_pipe_in_process` and the `BundleValidator` sweep methods gain an optional `caller_identity` of their own.
diff --git a/README.md b/README.md
index a2d71c384..ab1ef13f7 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,8 @@
<div align="center">
<h1 align="center"><a href="https://www.pipelex.com/"><img src="https://raw.githubusercontent.com/Pipelex/pipelex/main/.github/assets/logo.png" alt="Pipelex" width="400" style="max-width: 100%; height: auto;"></a></h1>
- <h2 align="center">Turn your expertise into an AI-powered App/MCP/API</h2>
- <p align="center">Pipelex runs your AI methods. Write a method once: a webapp runs it for your team or as SaaS for your customers, your agent runs it over MCP, your software runs it over the API.</p>
+ <h2 align="center">Turn your expertise into an AI-powered App, MCP or API</h2>
+ <p align="center">Describe how the work gets done in plain English, and your coding agent builds it into a method with the Pipelex plugin. A method is a multi-step, deterministic AI procedure that chains LLMs, OCR, image generation and more. Then run it as a webapp for your team or as SaaS for your customers, from your agent or your chatbot via MCP, or via API in any software.</p>
<div>
<a href="https://go.pipelex.com/demo"><strong>Demo</strong></a> -
@@ -84,29 +84,6 @@ Give the file as a URL the Pipelex MCP can reach. In ChatGPT you can attach it t
Prefer to run it yourself? This repository is the Pipelex runtime — its own install and configuration are below.
<!-- /onboarding -->
-## What a method looks like
-
-A method is a reusable, typed AI procedure, written in [MTHDS](https://mthds.ai/latest/), an open standard, and saved as a `.mthds` file. Each step is explicit, each output is structured, and every run is repeatable.
-
-```toml
-domain = "articles"
-main_pipe = "summarize_article"
-
-[pipe.summarize_article]
-type = "PipeLLM"
-description = "Summarize an article for a given audience"
-inputs = { article = "Text", audience = "Text" }
-output = "Text"
-prompt = "Summarize $article in three bullet points for $audience."
-```
-
-From here, Pipelex handles model routing across providers, structured output parsing, and pipeline orchestration.
-
-| | |
-|---|---|
-| **Declarative** — Human-readable `.mthds` files that work across models | **Typed** — Semantic types: AI understands what you mean, every input/output connects with purpose |
-| **Repeatable** — Deterministic orchestration with controlled room for AI creativity | **Composable** — Chain pipes into sequences, nest methods inside methods, share with the community |
-
## Run it yourself
This repository is the Pipelex runtime: the Python package that reads a `.mthds` file and runs it. Install it and everything happens on your own machine, against the model providers you choose.
@@ -148,7 +125,7 @@ uv tool install "pipelex[anthropic,google,google-genai,mistralai,bedrock,fal,lin
### Run a method
-Save the method above as `summarize.mthds` and its inputs as `inputs.json`:
+Save the method shown under [What a method looks like](#what-a-method-looks-like), further down, as `summarize.mthds`, and its inputs as `inputs.json`:
```json
{
@@ -177,6 +154,31 @@ The result is written under `results/`. For a method with several steps, typed c
<img src="https://go.pipelex.com/demo-thumbnail" alt="Pipelex Demo" width="500" style="max-width: 100%; height: auto;">
</a>
+## What a method looks like
+
+A method is a reusable, typed AI procedure, written in [MTHDS](https://mthds.ai/latest/), an open standard, and saved as a `.mthds` file. Each step is explicit, each output is structured, and every run is repeatable.
+
+```toml
+domain = "articles"
+main_pipe = "summarize_article"
+
+[pipe.summarize_article]
+type = "PipeLLM"
+description = "Summarize an article for a given audience"
+inputs = { article = "Text", audience = "Text" }
+output = "Text"
+prompt = "Summarize $article in three bullet points for $audience."
+```
+
+From here, Pipelex handles model routing across providers, structured output parsing, and pipeline orchestration.
+
+## Why methods?
+
+| | |
+|---|---|
+| **Declarative** — Human-readable `.mthds` files that work across models | **Typed** — Semantic types: AI understands what you mean, every input/output connects with purpose |
+| **Repeatable** — Deterministic orchestration with controlled room for AI creativity | **Composable** — Chain pipes into sequences, nest methods inside methods, share with the community |
+
## Run anywhere
The same `.mthds` file runs from multiple execution targets: