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/Pipelex-docs-hosted-runs · L-261009-32c329 (#1385)
Louis Choquel863d7b53d0bf
diff --git a/.badges/tests.json b/.badges/tests.jsonindex 6b1286fd2..0732f89f3 100644--- a/.badges/tests.json+++ b/.badges/tests.json@@ -1,7 +1,7 @@{"schemaVersion": 1,"label": "tests",- "message": "16568",+ "message": "16581","color": "blue","cacheSeconds": 300}diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.tomlindex 346d99d16..02e8f4c59 100644--- a/.drift/acks/cli-docs.toml+++ b/.drift/acks/cli-docs.toml@@ -1,17 +1,17 @@contract = "cli-docs"-digest = "sha256:97cce33271beed9b555021ecd78eb67e83261f51634f4e8e99054ad3d08269e1"+digest = "sha256:eb78038e1f2fe78d06f60a6af4327c2fcba3d92292d5b856d88f21e893b79b96"reviewed_by = "Claude (Opus 5.5)"-reviewed_at = "2026-10-08T13:35:43Z"-rationale = "clean-pass: merge of origin/dev into this branch, the ack file taken from dev. The open trigger changes are this branch's own work and nothing else: every other trigger file now equals dev's acked blob, and the five changed files only escape square brackets in help strings so Rich markup stops dropping them, the --hosted/--local help of pipelex run bundle, pipe and method, the shared --runner help of pipelex-agent run, and the --config help of pipelex-agent init. The rendered help now reads [run] execution and list[str], which run.md, agent-cli.md and init.md under docs/tools/cli already describe, and the agent CLI CLAUDE.md names [run] execution in prose but quotes none of these help strings, so nothing under the review targets is stale. The help guard test walks every help text of the three CLIs, the login, init and migrate commands dev brought included, and passes."+reviewed_at = "2026-10-09T11:47:00Z"+rationale = "real-catch: the trigger changes are this branch's help and next-step text: the run help of both CLIs (catalog ids, local method directories, TOML or inline inputs), the pipelex-agent --help description, the login closing line, the agent boot-failure hint, the FormerReleaseConfigError hint moving from the agent lookup dict to the class's user_action, and the doctor's credentials row offering the hosted Pipelex API. Reviewing docs/tools/cli against them caught one stale target: doctor.md did not say the Backend Credentials row now names the hosted Pipelex API, which it now does. run.md already lists inline JSON and the new options, agent-cli.md and migrate.md describe the FormerReleaseConfigError loop the new user_action carries, and the agent CLI CLAUDE.md now says --graph and --costs are ignored on a hosted run; none of the docs quote the changed help strings."[trigger_files]"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"-"pipelex/cli/_cli.py" = "blob:404604dc7bb89f0eb5e89773b9f4f631dc0c6fac"+"pipelex/cli/_cli.py" = "blob:2f95b05d84078bf40a59dce030dd9fecf8e500bc""pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/_agent_cli.py" = "blob:d3aa51f4472da74c48de39d5b15ee3f6a2fe16a8"+"pipelex/cli/agent_cli/_agent_cli.py" = "blob:690be5b3b3f0fbe69ed3e7baddd24538f590de01""pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"-"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:947ac4b789f2800811d653dc30a63419336c1b5d"-"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:e37898df47cfbb5b6d0ec42468be31463f82bff1"+"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:050ca1344abc4c1ca22d431923e1577681552fe6"+"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:a3651bb1023350e358d7865c3e9d401b3408b5c7""pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:a1904517c731afb72af7d49adf6d217dc50b2660""pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:3a9c93daecadf266b3eba466904b3d005d448d40""pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"@@ -38,10 +38,10 @@ rationale = "clean-pass: merge of origin/dev into this branch, the ack file take"pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6""pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:32f973c5c754b23016f3e708ab3235856e8bc5f4""pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:cea011e61feb082a7b9d82d7693b4fd3246737e5"-"pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:cf85194e29f44b0691eb81b216d2e506fcdd75f2"-"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:7c5f73a28e50f30196088af2435cbc2f635a65e5"-"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:08b676ee02526fd7d5ab85c6d5af70c8507ad9f3"+"pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df"+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:86988b3506ebc057df6a55d8862105ba6ceb693b"+"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:a83bb4df195d696e72a9c51704ee6c681a6d50a1"+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:f421c75ee696c18f85a7f63805455ef23637302f""pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:c7c7d7495508f1c4e5a46eba336a4ab1694ebcf7""pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:2a04aeff94db4afc56ac0c033a9d4add54d85c88"@@ -74,7 +74,7 @@ rationale = "clean-pass: merge of origin/dev into this branch, the ack file take"pipelex/cli/commands/codegen/inputs_cmd.py" = "blob:28b22cfbca717d3f5ee75162b68e132439655deb""pipelex/cli/commands/codegen/types_cmd.py" = "blob:27d7a06d571ad832b449d21b6f9eb66c017fb197""pipelex/cli/commands/crate_loading.py" = "blob:3d7d651931ecf1a15a3e2d72411b3212b55d74ef"-"pipelex/cli/commands/doctor_cmd.py" = "blob:c5944ed93b9a33cac01db9e8fa996a763cc8048b"+"pipelex/cli/commands/doctor_cmd.py" = "blob:84439f945eabf34917d73dc843d9513ed3daeb25""pipelex/cli/commands/fix/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/fix/_diff_sandbox.py" = "blob:d39c0df92b95567f74881deb01f8c1b3119fc8ef""pipelex/cli/commands/fix/_fix_core.py" = "blob:aa698305e6b60dfb7caf133698dc1d5c1f5f68f1"@@ -98,7 +98,7 @@ rationale = "clean-pass: merge of origin/dev into this branch, the ack file take"pipelex/cli/commands/init/ui/types.py" = "blob:e263802d8e9c9f9687435de1eb992afa5336544f""pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391""pipelex/cli/commands/login/api_key_store.py" = "blob:3a64ee921b54131dcba8c829880c060b5195e2ed"-"pipelex/cli/commands/login/command.py" = "blob:ee5f422b91acadaeadfae7f3a9b1541f1621de94"+"pipelex/cli/commands/login/command.py" = "blob:d277c28bf331f073c96c2980182a3bd543830088""pipelex/cli/commands/login/loopback.py" = "blob:b66eaa021caa1270a64237169f5a2585267f488c""pipelex/cli/commands/migrate_cmd.py" = "blob:3839424ccbf1c7f8e7af8a7f124a062cba18cece""pipelex/cli/commands/plugins_cmd.py" = "blob:9657b713c3650ff4a929e92ae68af453d896393e"@@ -110,11 +110,11 @@ rationale = "clean-pass: merge of origin/dev into this branch, the ack file take"pipelex/cli/commands/run/_main_stuff_file.py" = "blob:ca806e55085aa2e5748492751521296ce1f42960""pipelex/cli/commands/run/_run_core.py" = "blob:a41aafa3ee899c51e4b3b3919d164c8aaebe2095""pipelex/cli/commands/run/_run_hosted.py" = "blob:dd5801877a636f71187e9b23c2fab18d4d25ba32"-"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"-"pipelex/cli/commands/run/bundle_cmd.py" = "blob:169220d5ec5784a47802c3894c13b9809fd569fd"+"pipelex/cli/commands/run/app.py" = "blob:e312b159625e0a72bc9a18d3bfd2c73e7ac59f24"+"pipelex/cli/commands/run/bundle_cmd.py" = "blob:aba274dc8d6d0ac08baa3f21afbc06b2fdbec356""pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"-"pipelex/cli/commands/run/method_cmd.py" = "blob:549d356113febc4888ad36eb94ffb51e4a89232a"-"pipelex/cli/commands/run/pipe_cmd.py" = "blob:e43e844a9877832aa89c308cb4b6f52486cf2ce5"+"pipelex/cli/commands/run/method_cmd.py" = "blob:924bca6e242d8490e32eeb9ed2329db3d1b58b8d"+"pipelex/cli/commands/run/pipe_cmd.py" = "blob:f58885186d59142146eed340451b21832526af47""pipelex/cli/commands/show_cmd.py" = "blob:4c87c70058ea3b15827d03a370f3345569a2b705""pipelex/cli/commands/update_cmd.py" = "blob:b2db6170ddd9c67f17d88096ba1f1796a897557d""pipelex/cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e3a0ad08b..abf595e03 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,11 @@# Changelog+## [Unreleased]++### Changed++- **Hosted-run guidance in messages and help**: the next step of a refused Pipelex API key names `pipelex login` and the working directory's `.env` rather than a shell export, which a `.env` file setting the key overrides, and `pipelex login` names `[run] execution = "hosted"` rather than `pipelex init` to make hosted runs the default. A CLI run missing a provider key, and the `pipelex doctor` report, offer the hosted Pipelex API as a way out; a failed `pipelex-agent` boot points at `pipelex-agent migrate` and `pipelex-agent init` rather than the interactive `pipelex init config`; and `FormerReleaseConfigError` carries its remedy, `pipelex migrate`, as its `user_action`. The `run` help of both CLIs names hosted runs, catalog ids, local method directories and TOML or inline inputs, and `pipelex-agent --help` describes the program rather than printing an internal note.+## [v0.79.1] - 2026-10-09### Fixeddiff --git a/api/README.md b/api/README.mdindex 04a01e408..2b9f5a7ad 100644--- a/api/README.md+++ b/api/README.md@@ -123,7 +123,7 @@ The full reference for this API server is part of the Pipelex documentation, und- [Resolve & Codegen](https://docs.pipelex.com/latest/api-server/codegen/) — `/resolve`, `/codegen`- [Configuration](https://docs.pipelex.com/latest/api-server/configuration/) — env vars, mounting your own `.pipelex/` config-For broader Pipelex documentation (MTHDS language, concepts, pipe types, the Gateway): **[https://docs.pipelex.com/](https://docs.pipelex.com/)**+For broader Pipelex documentation (MTHDS language, concepts, pipe types, running on the hosted Pipelex API): **[https://docs.pipelex.com/](https://docs.pipelex.com/)**# 💬 Supportdiff --git a/docs/api-server/index.md b/docs/api-server/index.mdindex de99d0b37..16d6f5f2e 100644--- a/docs/api-server/index.md+++ b/docs/api-server/index.md@@ -90,6 +90,8 @@ Once deployed locally, the API is available at:http://localhost:8081/v1```+To run methods on it from the `pipelex` CLI, give its origin, without `/v1`, to `--base-url` or `PIPELEX_BASE_URL`: `http://localhost:8081`. A value with a path is refused before any request is sent. See [Running on the Hosted API](../tools/cli/run.md#running-on-the-hosted-api) for what such a server does and does not do for a CLI run.+## AuthenticationThe API supports three authentication modes via the `AUTH_MODE` environment variable:diff --git a/docs/building-methods/pipes/csv-input-and-output.md b/docs/building-methods/pipes/csv-input-and-output.mdindex d874b7aa4..e3b778b1d 100644--- a/docs/building-methods/pipes/csv-input-and-output.md+++ b/docs/building-methods/pipes/csv-input-and-output.md@@ -168,6 +168,8 @@ The codec defaults to a comma delimiter and UTF-8 encoding. Reads use `utf-8-sig- **Local file paths only.** A remote `url` with a tabular suffix — `http(s)://`, `s3://`, `gs://`, a signed URL — is actively rejected with a clear error, never opened. Reading remote tabular files is a deferred follow-up.+- **Not uploaded on a hosted run.** A run on the hosted Pipelex API uploads the local files named at document and image inputs only, so a `.csv` path at a structured-list input reaches the hosted runner as a path on your machine, which it cannot read. Give the rows as a JSON list of objects instead, or run with `--local`. `--save-csv` is refused on a hosted run too (see [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api)).+- **`.xlsx` is recognized but not yet implemented.** An `.xlsx` path is detected as tabular and routed to a clear "needs `pipelex[tabular]`" message; the Excel backend itself is not built in v1.- **Empty string is indistinguishable from `None`.** An empty cell reads as `None`, and on write `None` is rendered as an empty cell, so a genuinely empty string `""` cannot be told apart from a missing value through a CSV round trip.diff --git a/docs/building-methods/pipes/running-on-the-hosted-api.md b/docs/building-methods/pipes/running-on-the-hosted-api.mdindex c02578acb..066317c43 100644--- a/docs/building-methods/pipes/running-on-the-hosted-api.md+++ b/docs/building-methods/pipes/running-on-the-hosted-api.md@@ -10,7 +10,7 @@ Use the client directly: it has no Pipelex wrapper, and it needs no `Pipelex.mak## The Key and the Origin-The client reads its key from `PIPELEX_API_KEY` and its origin from `PIPELEX_BASE_URL`, falling back to `https://api.pipelex.com`. Both can also be passed to the constructor, as `api_key=` and `base_url=`. The client reads the process environment only. To use a key saved in `~/.pipelex/.env`, as `pipelex run --hosted` does, import `pipelex.system.environment` before creating the client: importing it loads `~/.pipelex/.env` (or the one in `PIPELEX_HOME`), then a `.env` in the working directory.+The client reads its key from `PIPELEX_API_KEY` and its origin from `PIPELEX_BASE_URL`, falling back to `https://api.pipelex.com`. Both can also be passed to the constructor, as `api_key=` and `base_url=`. The client reads the process environment only. To use a key saved in `~/.pipelex/.env`, as `pipelex run --hosted` does, import `pipelex.system.environment` before creating the client: importing it loads `~/.pipelex/.env` (or the one in `PIPELEX_HOME`), then a `.env` in the working directory. Each of those files replaces the variables it sets, so a `PIPELEX_API_KEY` or `PIPELEX_BASE_URL` set in one of them wins over the same variable already in the process environment, whether exported in your shell or set by your program before the import. To use a key of your own whatever the files say, pass it to the constructor as `api_key=`.## Running a Methoddiff --git a/docs/configuration/config-practical/run-config.md b/docs/configuration/config-practical/run-config.mdindex ab8fac4df..efdfd1ef0 100644--- a/docs/configuration/config-practical/run-config.md+++ b/docs/configuration/config-practical/run-config.md@@ -21,12 +21,12 @@ class RunConfig(ConfigModel):### Fields- `execution`: where a run executes when the command passes neither `--hosted` nor `--local` (nor `--runner` on the agent CLI).- - `"local"` (the default) runs on this machine, with the inference backends configured in `.pipelex/inference/` and your own provider keys.+ - `"local"`, the package default that applies when no configuration file sets `execution`, runs on this machine, with the inference backends configured in `.pipelex/inference/` and your own provider keys.- `"hosted"` runs on the hosted Pipelex API, with the Pipelex API key in `PIPELEX_API_KEY`, at the origin in `PIPELEX_BASE_URL` (`https://api.pipelex.com` when unset). Nothing is booted locally, so no provider key or inference configuration is needed on this machine.A flag on the command always wins: with `execution = "hosted"`, `pipelex run … --local` still runs on this machine, and with `"local"`, `--hosted` sends that one run to the hosted API.-[`pipelex init`](../../tools/cli/init.md#where-your-runs-execute) writes this setting from your answer to "Where should your runs execute?", and `pipelex-agent init` from the `execution` of its `--config`.+[`pipelex init`](../../tools/cli/init.md#where-your-runs-execute) writes this setting from your answer to "Where should your runs execute?", whose default answer is `"hosted"`, and `pipelex-agent init` from the `execution` of its `--config`, `"local"` when the config names none.## Example Configuration@@ -41,9 +41,11 @@ Put it in your project's `.pipelex/pipelex.toml` to make hosted runs the defaultA hosted run reads its key and its origin from the environment, never from this file:-- `PIPELEX_API_KEY` holds the Pipelex API key (`plx_sk_…`). [`pipelex login`](../../tools/cli/login.md) gets one through your browser and saves it in `~/.pipelex/.env`, which Pipelex loads at startup; you can also export it in your shell.+- `PIPELEX_API_KEY` holds the Pipelex API key (`plx_sk_…`). [`pipelex login`](../../tools/cli/login.md) gets one through your browser and saves it in `~/.pipelex/.env`, which Pipelex loads at startup.- `PIPELEX_BASE_URL` overrides the origin, for a staging plane or a self-hosted Pipelex API server. `--base-url` on the command overrides it in turn. Either must be `scheme://host[:port]`, with no path such as `/v1`.+Pipelex loads `~/.pipelex/.env`, then the `.env` of the working directory, and each file replaces the variables it sets. So for either variable, the working directory's `.env` wins over `~/.pipelex/.env`, which wins over a value exported in your shell: an exported value is read only when neither file sets the variable.+## Related Documentation- [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api) — What a hosted run sends, uploads, saves and refusesdiff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.mdindex 29171a167..1d2d84660 100644--- a/docs/configuration/config-technical/inference-backend-config.md+++ b/docs/configuration/config-technical/inference-backend-config.md@@ -8,7 +8,7 @@ The Inference Backend Configuration System manages how Pipelex handles AI model## Configuration Approaches-Pipelex calls AI models through backends you configure with your own provider API keys.+Pipelex calls AI models through backends you configure with your own provider API keys. This is how runs on this machine reach their models: a run on the hosted Pipelex API uses none of this configuration and no provider key, only a Pipelex API key (see [Running on the Hosted API](../../tools/cli/run.md#running-on-the-hosted-api)).### Bring Your Own Keysdiff --git a/docs/configuration/index.md b/docs/configuration/index.mdindex 72dd275a2..e57eacd92 100644--- a/docs/configuration/index.md+++ b/docs/configuration/index.md@@ -21,7 +21,7 @@ pipelex init config --local # creates the project config at {project_root}/.pip!!! important "Configuration Setup Notes"1. By default `pipelex init config` targets the **global** `~/.pipelex/` directory, or the one `PIPELEX_HOME` names (see [below](#the-home-configuration-directory-pipelex_home)); pass `--local` to create the project-level `.pipelex/` instead.2. `pipelex init config` creates a **template** configuration file with sample settings. It does not include all possible configuration options - it's meant as a starting point.- 3. Running `pipelex init config` will **overwrite** your existing `pipelex.toml` file without warning. Make sure to backup your configuration before running this command.+ 3. Running `pipelex init config` **replaces** your existing `pipelex.toml` with the template once you confirm, keeping only its `[run] execution` setting, so back up anything else you changed first. On a first setup, where no `inference/backends.toml` exists yet, it asks where your runs execute instead, and for the hosted Pipelex API it signs you in through your browser unless a Pipelex API key is already set (see [Init](../tools/cli/init.md#where-your-runs-execute)).4. Credentials (the `.env` in `~/.pipelex/`) always remain in the global directory regardless of `--local` — only config, inference, and telemetry files are written to the project `.pipelex/`.For a complete list of all possible configuration options, refer to the configuration group documentation below.diff --git a/docs/cookbook/index.md b/docs/cookbook/index.mdindex 4a6e7fe8e..6b7e6f8e9 100644--- a/docs/cookbook/index.md+++ b/docs/cookbook/index.md@@ -9,7 +9,7 @@ description: "The Pipelex Cookbook holds Pipelex's example methods, each one runThe [Pipelex Cookbook](https://github.com/Pipelex/pipelex-cookbook) holds Pipelex's example methods. Each one is a package that runs by its address on the hosted Pipelex API, `github.com/Pipelex/pipelex-cookbook/<method>@<release>`, so there is nothing to clone and nothing to install before you try it. Each method's page gives its address at the cookbook's latest release.-Every method has its own page in the cookbook, and every page shows the same ways to use it: in your chatbot through the Pipelex MCP, in your coding agent through the Pipelex plugin, in your code through the TypeScript or Python SDK or over HTTP, as a web app made from the method-app template, and how to make it yours by copying it, changing it and saving it to your account. The [list of methods](https://github.com/Pipelex/pipelex-cookbook#methods-you-can-run-by-address) on the cookbook's front page links to each page, and the page for [Gantt chart extraction](https://github.com/Pipelex/pipelex-cookbook/tree/main/methods/extract_gantt) is a good one to start with.+Every method has its own page in the cookbook, and every page shows the same ways to use it: in your chatbot through the Pipelex MCP, in your coding agent through the Pipelex plugin, in your code through the TypeScript or Python SDK or over HTTP, as a web app made from the method-app template, and how to make it yours by copying it, changing it and saving it to your account. The [list of methods](https://github.com/Pipelex/pipelex-cookbook#methods-you-can-run-by-address) on the cookbook's front page links to each page, and the page for [Gantt chart extraction](https://github.com/Pipelex/pipelex-cookbook/tree/main/methods/extract_gantt) is a good one to start with. From your terminal, `pipelex run method <address> --hosted` runs any of them on the hosted Pipelex API once [`pipelex login`](../tools/cli/login.md) has saved your key (see [Running on the Hosted API](../tools/cli/run.md#running-on-the-hosted-api)).The cookbook also has [recipes](https://github.com/Pipelex/pipelex-cookbook/tree/main/recipes), each of which takes one way of using a method further on a real case, such as a FastAPI endpoint, a Next.js server action or a web app you deploy. Its [tutorial](https://github.com/Pipelex/pipelex-cookbook/tree/main/tutorial) teaches you to write methods in MTHDS by hand and to run them on your own machine.diff --git a/docs/errors/former-release-config-error.md b/docs/errors/former-release-config-error.mdindex 542c78f0b..99974aa08 100644--- a/docs/errors/former-release-config-error.md+++ b/docs/errors/former-release-config-error.md@@ -17,5 +17,6 @@ The inference configuration still carries what a former release wrote for the Pi| `error_domain` | _(inherited from parent)_ || Defined in | `pipelex.migration.exceptions` || Parent class | [`PipelexSetupError`](pipelex-setup-error.md) |+| `user_action` | `unknown` — Run 'pipelex migrate' to remove what the former release left; it keeps a copy of each file it changes or removes. From an agent, run 'pipelex-agent migrate --dry-run --format json' to see what the cleanup would remove (its 'former_release' key), show the user, then run 'pipelex-agent migrate --yes'. |[Back to Error Reference](index.md)diff --git a/docs/errors/hosted-run-source-error.md b/docs/errors/hosted-run-source-error.mdindex 9f41374ef..244179b1d 100644--- a/docs/errors/hosted-run-source-error.md+++ b/docs/errors/hosted-run-source-error.md@@ -7,7 +7,7 @@ description: "Reference for the `HostedRunSourceError` Pipelex error class."# Hosted run source-A hosted run cannot be given the method to run: no bundle file, no `.mthds` file in the library directories, or no source at all.+A hosted run cannot be given its method: no bundle file, an unreadable method file, no `.mthds` file, or `-L` with an address or a catalog id.| Field | Value ||---|---|diff --git a/docs/features/cli.md b/docs/features/cli.mdindex 5466ddce6..b21b5f447 100644--- a/docs/features/cli.md+++ b/docs/features/cli.md@@ -18,11 +18,12 @@ The `pipelex` CLI is the primary tool for working with Pipelex methods. It cover| **`pipelex init`** | Initialize configuration, choose where runs execute (the hosted Pipelex API or this machine), and set up backends, credentials, routing, and telemetry || **`pipelex login`** | Get a Pipelex API key through your browser, or paste one with `--paste`, and save it for runs on the hosted Pipelex API || **`pipelex update`** | Refresh the model deck and `backends/internal.toml` to match the installed pipelex version |+| **`pipelex migrate`** | Bring your configuration files up to the schema the installed version expects, and clean up what a former release left || **`pipelex doctor`** | Check configuration health and suggest fixes; a setup whose runs execute on the hosted Pipelex API needs its Pipelex API key and no provider key || **`pipelex build`** | Generate the structures of your concepts and example inputs and outputs for a pipe || **`pipelex validate`** | Check pipeline syntax, structure, and run dry-run validation || **`pipelex fix`** | Apply deterministic safe fixes to a bundle and re-validate (with `--diff` preview) |-| **`pipelex run`** | Execute pipelines from bundle files or libraries |+| **`pipelex run`** | Execute pipelines from bundle files, libraries or methods, on this machine or on the hosted Pipelex API || **`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 |@@ -37,6 +38,7 @@ Package manifest management is currently exposed through the lowercase `mthds` C## Execution Options+- **Where it runs** — `--hosted` runs on the hosted Pipelex API, with only a Pipelex API key, and `--local` on this machine, with your own provider keys; without either, the run follows `[run] execution`. `--base-url` points a hosted run at another origin. See [Running on the Hosted API](../tools/cli/run.md#running-on-the-hosted-api)- **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 (requires `--dry-run`)- **Graph generation** — `--graph`, `--graph-full-data`, `--graph-no-data` for visual execution inspectiondiff --git a/docs/features/pipelex-plugin.md b/docs/features/pipelex-plugin.mdindex 7c13ac0a9..9f1023392 100644--- a/docs/features/pipelex-plugin.md+++ b/docs/features/pipelex-plugin.md@@ -73,4 +73,4 @@ The tools the skills call to validate a method, prepare its inputs, run it, gene- [Quick Start](../get-started/quick-start.md) — sign up, install the plugin and run your first method, then run it from your chatbot, as a webapp or via API- [MTHDS Language](mthds-language.md) — the language the plugin's skills write-- [Run It Yourself](../get-started/run-it-yourself.md) — the Pipelex runtime on your own machine+- [Run It Yourself](../get-started/run-it-yourself.md) — the Pipelex runtime in your terminal, running methods on the hosted Pipelex API or on your own machinediff --git a/docs/get-started/cv-batch-screening.md b/docs/get-started/cv-batch-screening.mdindex b1cf377b7..d090da13d 100644--- a/docs/get-started/cv-batch-screening.md+++ b/docs/get-started/cv-batch-screening.md@@ -1,11 +1,11 @@---title: "CV Batch Screening, Step by Step"-description: "Screen a stack of CVs against a job offer with a multi-step Pipelex method that extracts each document, analyzes it and scores the match, run on your own machine from the CLI and from Python."+description: "Screen a stack of CVs against a job offer with a multi-step Pipelex method that extracts each document, analyzes it and scores the match, run from the CLI on the hosted Pipelex API or on your own machine, and from Python."---# CV Batch Screening, Step by Step-A production method that takes a stack of CVs and a job offer PDF, extracts and analyzes each, then scores how well each candidate matches the role. This page reads it part by part and runs it on your own machine with the Pipelex runtime, from the CLI and from Python, once you have followed [Run It Yourself](./run-it-yourself.md).+A production method that takes a stack of CVs and a job offer PDF, extracts and analyzes each, then scores how well each candidate matches the role. This page reads it part by part and runs it with the Pipelex runtime, from the CLI and from Python, once you have followed [Run It Yourself](./run-it-yourself.md).## What it demonstrates@@ -263,6 +263,8 @@ flowchart LRpipelex run bundle cv_batch_screening.mthds --inputs inputs.json```+The command runs where your setup says. After the default answer to `pipelex init`, it runs on the hosted Pipelex API with your Pipelex API key, and a local file named in the inputs, such as `inputs/Jane-Smith-CV.pdf` below, is uploaded before the run. Add `--local` to run it on this machine instead, which needs the provider keys of a local setup (see [Configure AI Providers](./configure-ai-providers.md)).+Create an `inputs.json` file with your PDF URLs:```json@@ -285,6 +287,8 @@ Create an `inputs.json` file with your PDF URLs:### From Python+This code runs the method in your own process, so it always runs on this machine, whatever `[run] execution` says, and it needs the provider keys of a local setup (see [Configure AI Providers](./configure-ai-providers.md)). To run the method on the hosted Pipelex API from Python, use pipelex-sdk's `PipelexAPIClient`, as [Running on the Hosted API from Python](../building-methods/pipes/running-on-the-hosted-api.md) shows.+```pythonimport asynciofrom pathlib import Pathdiff --git a/docs/get-started/quick-start.md b/docs/get-started/quick-start.mdindex 7b212dc86..f0caf4980 100644--- a/docs/get-started/quick-start.md+++ b/docs/get-started/quick-start.md@@ -184,4 +184,4 @@ export PIPELEX_API_KEY=plx_sk_...## Prefer to run it yourself?-The Pipelex runtime runs your methods on your own machine, against the model providers you choose. [Run It Yourself](./run-it-yourself.md) installs it, and [The MTHDS Language Tutorial](./mthds-language-tutorial.md) walks through writing a method by hand.+The Pipelex runtime runs your methods from your terminal, either on the hosted Pipelex API once `pipelex login` has saved your key, or on your own machine against the model providers you choose. [Run It Yourself](./run-it-yourself.md) installs it, and [The MTHDS Language Tutorial](./mthds-language-tutorial.md) walks through writing a method by hand.diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.mdindex 85f4ebd30..78ff2e1d6 100644--- a/docs/tools/cli/agent-cli.md+++ b/docs/tools/cli/agent-cli.md@@ -19,7 +19,7 @@ It ships in the same `cli` extra as the main CLI, `uv tool install "pipelex[cli]There is no `--log-level` flag: `pipelex-agent` is machine-consumed, so logging is cut off process-wide by design.!!! warning "`--runner api` is gone"- The global `--runner pipelex|api` option and its MTHDS API runner path are removed. Where a run executes is now a `run` subcommand option, `--runner local|hosted`, and the hosted value runs on the hosted Pipelex API through pipelex-sdk, with the key in `PIPELEX_API_KEY` rather than `MTHDS_API_KEY`. A self-hosted runner is reached with `--runner hosted --base-url <origin>`. To target an arbitrary MTHDS runner, use the vendor-neutral `mthds-agent` CLI.+ The global `--runner pipelex|api` option and its MTHDS API runner path are removed. Where a run executes is now a `run` subcommand option, `--runner local|hosted`, and the hosted value runs on the hosted Pipelex API through pipelex-sdk, with the key in `PIPELEX_API_KEY` rather than `MTHDS_API_KEY`. A self-hosted runner is reached with `--runner hosted --base-url <origin>`; it keeps no runs, takes no uploads and has no catalog, as [Running on the Hosted API](run.md#running-on-the-hosted-api) describes. To target an arbitrary MTHDS runner, use the vendor-neutral `mthds-agent` CLI.## Commands Overview@@ -53,7 +53,7 @@ For `bundle` and `method`, use `--pipe` to target a specific pipe.#### Running on the hosted API-With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the run executes on the hosted Pipelex API and nothing local is booted: no provider key or inference configuration is needed on this machine, only a Pipelex API key in `PIPELEX_API_KEY` (in the shell, or in `~/.pipelex/.env`). What the run sends is what a local run would load. `run bundle` sends the bundle, then every `.mthds` file of its library directories. `run pipe` sends its library directories' files (the installed method exporting the pipe and `-L`, else `PIPELEXPATH`) and is refused when it has none. `run method` sends an installed or local method's files, but a published address (`github.com/owner/repo[/name][@tag]`) goes as a `method_ref` and a stored method's catalog id (`mt_…`) as a `method_id`, both resolved by the hosted API, so nothing is fetched or read locally and `-L` is refused with them. A local file named at a document or image input is uploaded first (a relative path in an inputs file resolves against that file's directory, and a `file://` URI is read as its path), and the run's inputs carry its storage URI; an explicit `null`, such as an optional image left out, reaches the run as `null`. The method's signature is read only when some value of the inputs names an existing file on this machine, so inputs naming none go straight to the run, a method calling another one by its address included. Such a method cannot have a local file uploaded yet: give the file as an `https://` URL. `run bundle` on a bundle file with no `-L` sends `PIPELEXPATH`'s files too, as a local run loads them, and `run method` takes a method installed under a name spelled like a catalog id (`mt_reports`) as that method. `--dry-run` and `--mock-inputs` are refused on a hosted run. Its requests name their client in the `User-Agent` as `pipelex-cli/<version>`, as `pipelex run --hosted` does, so the hosted API counts them as CLI runs.+With `--runner hosted` (or `--hosted`, or `[run] execution = "hosted"`), the run executes on the hosted Pipelex API and nothing local is booted: no provider key or inference configuration is needed on this machine, only a Pipelex API key in `PIPELEX_API_KEY`, saved in `~/.pipelex/.env` by `pipelex login` or exported in the shell. A `.env` file Pipelex loads wins over the shell, and the working directory's wins over `~/.pipelex/.env`, so an exported key is read only when neither file sets the variable. What the run sends is what a local run would load, and only the contents of its `.mthds` files: a PipeFunc's Python, structure classes, `METHODS.toml` and the packages a dependency alias names stay on this machine, so a local bundle relying on them runs with `--runner local`. `run bundle` sends the bundle, then every `.mthds` file of its library directories. `run pipe` sends its library directories' files (the installed method exporting the pipe and `-L`, else `PIPELEXPATH`) and is refused when it has none. `run method` sends an installed or local method's files, but a published address (`github.com/owner/repo[/name][@tag]`) goes as a `method_ref` and a stored method's catalog id (`mt_…`) as a `method_id`, both resolved by the hosted API, so nothing is fetched or read locally and `-L` is refused with them. A local file named at a document or image input is uploaded first (a relative path in an inputs file resolves against that file's directory, and a `file://` URI is read as its path), and the run's inputs carry its storage URI, while a `.csv` path at a structured-list input is not uploaded, so give its rows as a JSON list; an explicit `null`, such as an optional image left out, reaches the run as `null`. The method's signature is read only when some value of the inputs names an existing file on this machine, so inputs naming none go straight to the run, a method calling another one by its address included. Such a method cannot have a local file uploaded yet: give the file as an `https://` URL. `run bundle` on a bundle file with no `-L` sends `PIPELEXPATH`'s files too, as a local run loads them, and `run method` takes a method installed under a name spelled like a catalog id (`mt_reports`) as that method. `--dry-run` and `--mock-inputs` are refused on a hosted run, while `--graph` / `--no-graph` and `--costs` / `--no-costs` are accepted and have no effect there, since a hosted run writes nothing to disk and emits no cost events on this machine (`pipelex run --hosted` refuses `--costs`). Its requests name their client in the `User-Agent` as `pipelex-cli/<version>`, as `pipelex run --hosted` does, so the hosted API counts them as CLI runs.The success envelope has the shape of a local run's. Compact, it is the main output's content. With `--with-memory`, `main_stuff.json` is that content (the hosted API renders no Markdown, so the markdown output shows the JSON), `working_memory` is the whole working memory, `pipeline_run_id` names the run on the hosted API, and `uploads` lists the files uploaded for it. A hosted run writes nothing to disk.diff --git a/docs/tools/cli/doctor.md b/docs/tools/cli/doctor.mdnew file mode 100644index 000000000..fc3a35b34--- /dev/null+++ b/docs/tools/cli/doctor.md@@ -0,0 +1,68 @@+---+description: "Check the health of your Pipelex configuration, see what your setup needs for where its runs execute, and fix what can be fixed."+---++# Doctor Command++`pipelex doctor` checks your Pipelex configuration and says what to fix. It reads your configuration files and your environment, and it changes nothing unless you pass `--fix`.++```bash+pipelex doctor+pipelex doctor --fix+```++## What It Checks++The doctor checks the configuration a command run in the current directory would use: the project's `.pipelex/` when the project around the working directory has one, else the home configuration directory (`~/.pipelex/`, or the directory `PIPELEX_HOME` names; see [Configuration](../../configuration/index.md#the-home-configuration-directory-pipelex_home)). The report opens with an overall status, then gives one row per check:++- **Configuration Location** - Which configuration directory is used, the project's or the global one.+- **Configuration Files** - Whether every configuration file the kit ships is present, and whether `pipelex.toml` is valid.+- **Configuration Migrations** - What [`pipelex migrate`](migrate.md) would change: the files a migration would bring up to the current schema, the files that need a look from you, and what a former release left for the Pipelex Gateway, which the migration cleans up first. This row covers the home configuration directory and the project's `.pipelex/` together, as `pipelex migrate` does.+- **Telemetry Configuration** - Whether `telemetry.toml` is present and valid.+- **Plugins**, **Secrets Provider** and **Log Sink** - Whether the plugins, the secrets provider and the log sink your configuration names can be set up. These rows appear once the configuration loads.+- **Pipelex API Key** - Whether hosted runs have a key to send. This row appears only when your runs execute on the hosted Pipelex API, as described below.+- **Backend Credentials** - Whether the provider keys of the enabled inference backends are set. When some are missing, the row says how to set them, how to disable a backend you do not need, and that a run on the hosted Pipelex API needs none of them.+- **Models** - Whether the inference backends and the models they declare load.+- **Model Deck** - Whether the model deck and `backends/internal.toml` match the installed pipelex version; [`pipelex update`](update.md) refreshes them.++## Where Your Runs Execute++What a setup needs depends on where its runs execute, so the doctor reads the effective `[run] execution` setting (see [Run Configuration](../../configuration/config-practical/run-config.md)), and takes `"local"` when the configuration does not load.++- **On this machine** (`"local"`), every row counts toward the overall status.+- **On the hosted Pipelex API** (`"hosted"`), a run boots nothing on this machine and uses no provider key. The **Pipelex API Key** row appears and counts: it is healthy when a Pipelex API key is set, in `PIPELEX_API_KEY` or saved in the home `.env` by [`pipelex login`](login.md), and starts with `plx_sk_`; otherwise it names `pipelex login`. The row looks at the key only, without calling the hosted API, and never prints it. The **Backend Credentials** and **Models** rows are then shown as information, needed only for runs you start with `--local`, and they count neither toward the overall status nor toward the exit code.++## Fix Mode++```bash+pipelex doctor --fix+```++With `--fix` (`-f`), the doctor offers each fix it can make, one question at a time, with yes as the default answer:++- **Missing configuration files** are installed by running `pipelex init config` without its confirmation and without asking where runs execute. It never moves runs off this machine: it keeps the `[run] execution` the target `pipelex.toml` already sets, and a `pipelex.toml` that sets none stays on this machine. Only a brand-new home, with no `pipelex.toml` yet, takes the hosted Pipelex API, and it then prints `pipelex login` rather than opening a browser.+- **Configuration migrations** run the write pass of `pipelex migrate`: the cleanup of what a former release left, then the migration of the files that can be brought up to date, each file backed up beside itself first.+- **A missing telemetry configuration** is set up through `pipelex init telemetry`.+- **An outdated model deck or `backends/internal.toml`** is refreshed through `pipelex update`.+- **A backend file in an outdated format** is replaced by the kit's template, for a backend the kit ships, when your runs execute on this machine.++What no command can fix is listed under **Manual Fixes Required**: a missing or malformed Pipelex API key (run `pipelex login`, or `pipelex login --paste` on a machine without a browser), a `pipelex.toml` or `telemetry.toml` that does not validate, and, when your runs execute on this machine, the provider keys to set, shown as `.env` lines and as shell commands. A variable set in a `.env` file Pipelex loads wins over one exported in your shell (see [Running on the Hosted API](run.md#running-on-the-hosted-api)).++The report is measured before the fixes run, so run `pipelex doctor` again to see where things stand.++## Exit Codes++- `0`: every row that counts is healthy.+- `1`: something needs fixing. This is also the exit code of a `--fix` run that found something to fix, whatever it fixed.++## Machine-Readable Output++`pipelex-agent doctor` runs the same checks and answers in Markdown or JSON: `execution` at the top level, the Pipelex API key under `checks.pipelex_api_key` with a `finding` of `set`, `not_a_pipelex_key` or `missing`, and `informational: true` on the provider credentials and models rows of a hosted setup. See [Agent CLI](agent-cli.md).++## Related Documentation++- [Init](init.md): the first-run setup, and what `pipelex doctor --fix` runs to install missing files+- [Migrate](migrate.md): bring configuration files up to the current schema+- [Update](update.md): refresh the model deck and `backends/internal.toml`+- [Login](login.md): get the Pipelex API key a hosted setup needs+- [Init CLI Flows](../../under-the-hood/init-cli-flows.md): how the setup and the health check work insidediff --git a/docs/tools/cli/index.md b/docs/tools/cli/index.mdindex c3610053b..9acbdd103 100644--- a/docs/tools/cli/index.md+++ b/docs/tools/cli/index.md@@ -27,6 +27,7 @@ The Pipelex CLI is organized into several command groups:| [**login**](login.md) | Get a Pipelex API key through your browser, or paste one, and save it for runs on the hosted Pipelex API || [**update**](update.md) | Refresh the model deck and `backends/internal.toml` to match the installed pipelex version || [**migrate**](migrate.md) | Bring your configuration files up to the schema the installed version expects |+| [**doctor**](doctor.md) | Check configuration health, judged by where your runs execute, and fix what can be fixed || [**validate**](validate.md) | Validate configuration and pipelines || [**fix**](fix.md) | Apply deterministic safe fixes to a bundle and re-validate || [**show**](show.md) | Inspect configuration, pipes, and AI models |@@ -90,6 +91,7 @@ Package manifest management currently lives in the `mthds` CLI:4. **Configuration Management**+ - Use `pipelex doctor` to check that your configuration is healthy, and `pipelex doctor --fix` to fix what can be fixed- Use `pipelex show config` to verify current settings- Use `pipelex show backends` to check inference backend setup- Use `pipelex show models backend_name` to see available modelsdiff --git a/docs/tools/cli/init.md b/docs/tools/cli/init.mdindex 410cfcc21..90ecf86b9 100644--- a/docs/tools/cli/init.md+++ b/docs/tools/cli/init.md@@ -90,12 +90,12 @@ When you run `pipelex init`, Pipelex can guide you through:1. **What a former release left** - On a machine set up by a release that ran models through the Pipelex Gateway, the cleanup that release's files need, offered first (see [below](#a-machine-a-former-release-set-up))2. **Config reset** - Recreate the selected config files3. **Where your runs execute** - The hosted Pipelex API (the default) or this machine-4. On the hosted Pipelex API: **sign-in** - [`pipelex login`](login.md) gets a Pipelex API key, unless one is already set. It runs last, once every file is written-5. On this machine:+4. On this machine:1. **Backend selection** - Choose which AI providers to enable. The prompt pre-selects OpenAI, whose one key serves every default language-model and image-generation tier of the shipped model deck2. **Routing configuration** - Set up how models are routed to backends3. **Credential prompts** - Fill in missing keys when relevant-6. **Telemetry setup** - Configure observability and analytics+5. **Telemetry setup** - Configure observability and analytics+6. On the hosted Pipelex API: **sign-in** - [`pipelex login`](login.md) gets a Pipelex API key, unless one is already set. It runs last, once every file is written## A Machine a Former Release Set Up@@ -115,7 +115,7 @@ Yes runs the cleanup that [`pipelex migrate`](migrate.md#a-configuration-a-forme`pipelex doctor --fix` installs missing configuration files with nobody there to answer, and never moves runs off this machine. On a first setup it keeps the `[run] execution` the target `pipelex.toml` already sets; a `pipelex.toml` that sets none, such as one written before the setting existed, runs on this machine, as the package default says, and stays there. Only a brand-new home, with no `pipelex.toml` yet, takes the hosted Pipelex API, writing `execution = "hosted"` and printing `pipelex login` instead of opening a browser.-**A project can override the global choice.** A project's `.pipelex/pipelex.toml` wins over the one in `~/.pipelex/`, and the one `pipelex init --local` copies sets `execution = "local"`. When you set up the home configuration from inside a project whose own file sets the other value, `pipelex init` warns you, naming that file: runs started in that project execute where it says, until you change it there or pass `--hosted` or `--local` on a run.+**A project can override the global choice.** A project's `.pipelex/pipelex.toml` wins over the one in `~/.pipelex/`. `pipelex init --local` asks the same question and writes your answer to the project's file, Enter meaning the hosted Pipelex API there too. When you set up the home configuration from inside a project whose own file sets the other value, `pipelex init` warns you, naming that file: runs started in that project execute where it says, until you change it there or pass `--hosted` or `--local` on a run.## Non-Interactive Init (`pipelex-agent init`)@@ -150,6 +150,8 @@ All fields are optional:| `backends` | `list[str]` | Backend keys to enable (e.g. `openai`, `anthropic`, `openrouter`). Omit to keep the template's enabled backends and its routing profile, which sends each model to the first of them that serves it. || `primary_backend` | `str` | Required when 2+ backends are named. Named without `backends`, it routes the template's backends to it first. |+`pipelex-agent init` writes `execution = "local"` when its config names no `execution`, and by default it writes it to the project's `.pipelex/pipelex.toml`, which wins over the home one. A project set up this way therefore runs on this machine even when `~/.pipelex/pipelex.toml` says `"hosted"`, and no warning says so, since the file written is the project's own: pass `"execution": "hosted"` to keep the project's runs on the hosted Pipelex API.+**Output:** `success`, `target_dir`, `config_files_copied` and `execution`. A local setup adds `backends_enabled` and `routing_profile`; a hosted one adds `api_key_set`, whether a Pipelex API key is set in `PIPELEX_API_KEY` or saved in `~/.pipelex/.env`, never the key itself. A `warnings` list is added when the project around the working directory sets another `[run] execution` in its own `.pipelex/pipelex.toml`, which wins over the one just written.Telemetry is not configured via `--config`: init seeds a `telemetry.toml` from a template (a global init writes an active one; a project init drops a commented-out one).diff --git a/docs/tools/cli/login.md b/docs/tools/cli/login.mdindex a0a5d4569..c2bb45d1e 100644--- a/docs/tools/cli/login.md+++ b/docs/tools/cli/login.md@@ -26,10 +26,10 @@ The key is never printed. The `.env` file is readable and writable by you only (- When the hosted API accepts the key, it is saved, and the command says which account it belongs to.- When the hosted API refuses it (HTTP 401 or 403), nothing is saved and the command exits with code `1`, naming the status.-- When the key cannot be checked, because the hosted API cannot be reached or answers anything else, it is saved anyway, with a warning saying why it was not checked.+- When the key cannot be checked, because the hosted API cannot be reached, answers anything else, or `PIPELEX_BASE_URL` is not an origin, it is saved anyway, with a warning saying why it was not checked.- A value that does not start with `plx_sk_` is refused before any check.-**A `.env` in the working directory wins.** Pipelex loads the `.env` of the directory a command runs in after `~/.pipelex/.env`, so a `PIPELEX_API_KEY` line there, even an empty one, is what commands run in that directory send. When that file sets another value than the key just saved, `pipelex login` names it, without printing either value: remove the line from it.+**A `.env` in the working directory wins.** Pipelex loads the `.env` of the directory a command runs in after `~/.pipelex/.env`, so a `PIPELEX_API_KEY` line there, even an empty one, is what commands run in that directory send. When that file sets another value than the key just saved, `pipelex login` names it, without printing either value: remove the line from it. Both files also win over your shell, since each `.env` Pipelex loads replaces the variables it sets: a `PIPELEX_API_KEY` exported in your shell is read only when neither file sets it.**The handover is protected.** Each login sends the app a random `state` value along with the port, and the app sends it back with the key. A request to the port that does not carry this login's `state` is refused and its key discarded: any page open in your browser can send a request to a local port, so a key that arrives without it did not come from the page this login opened. The command says so in the terminal and keeps waiting.@@ -43,7 +43,7 @@ pipelex login --pasteOn a machine where no browser can reach a local port, such as a remote server over SSH or a CI job, create a key in the Pipelex app on any machine, then paste it at the prompt. The key is not shown as you type. It goes through the same check and is saved the same way.-In CI, you can also skip the file entirely and set `PIPELEX_API_KEY` as a secret of the job.+In CI, you can also skip the file entirely and set `PIPELEX_API_KEY` as a secret of the job. The job's value is read as long as no `.env` file Pipelex loads, in the home configuration directory or in the working directory, sets the variable.## Other Apps and APIs@@ -52,13 +52,15 @@ In CI, you can also skip the file entirely and set `PIPELEX_API_KEY` as a secret| `PIPELEX_APP_URL` | The Pipelex app the browser opens, given as an origin (`scheme://host[:port]`, no path) | `https://app.pipelex.com` || `PIPELEX_BASE_URL` | The hosted API the key is checked against, and that hosted runs go to | `https://api.pipelex.com` |-A value that is not an origin is refused before anything opens. Most people never set either; they point the command at a development or staging plane, for instance:+A `PIPELEX_APP_URL` that is not an origin is refused before anything opens. A `PIPELEX_BASE_URL` that is not one is only met when the key is checked, after the browser has handed it back or the key was pasted: the key cannot be checked, so it is saved anyway, with a warning that names `PIPELEX_BASE_URL` and what an origin looks like, and the command exits with code `0`. Correct the value before a hosted run uses it.++Most people never set either; they point the command at a development or staging plane, for instance:```bashPIPELEX_APP_URL=https://app-dev.pipelex.com PIPELEX_BASE_URL=https://api-dev.pipelex.com pipelex login```-Set them in `~/.pipelex/.env` to keep them for every command.+Set them in `~/.pipelex/.env` to keep them for every command. Once a `.env` file Pipelex loads sets one of them, that file wins over a value given on the command line as above, which is then ignored: change the value in the file instead.## Exit Codesdiff --git a/docs/tools/cli/migrate.md b/docs/tools/cli/migrate.mdindex 3b7fef868..32850c104 100644--- a/docs/tools/cli/migrate.md+++ b/docs/tools/cli/migrate.md@@ -91,5 +91,5 @@ An agent usually meets this command through a failure rather than by choosing it## See also-- [`pipelex doctor`](index.md) — check configuration health+- [`pipelex doctor`](doctor.md) — check configuration health- [`pipelex init`](init.md) — create configuration files from scratchdiff --git a/docs/tools/cli/run-by-address.md b/docs/tools/cli/run-by-address.mdindex 0837f9600..6a43a976d 100644--- a/docs/tools/cli/run-by-address.md+++ b/docs/tools/cli/run-by-address.md@@ -61,7 +61,7 @@ pipelex run method github.com/Pipelex/methods/[email protected] --hosted --inputWhat decides whether Python in a method is acceptable is **where it would execute**:- `.mthds` content is data — always fine.-- **PipeFunc `.py`** is supported: on hosted deployments it executes in a network-blocked sandbox, never in the runner's process.+- **PipeFunc `.py`** is supported: on hosted deployments it executes in a network-blocked sandbox, never in the runner's process. This holds for a package the hosted runner fetches by its address; a local bundle sent with `--hosted` carries only its `.mthds` files, so its PipeFuncs stay behind (see [Running on the Hosted API](run.md#running-on-the-hosted-api)).- **Python structure classes** (`StructuredContent` subclasses) would have to be imported into the runner's own process to back a concept, so *hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python*. A fetched method declaring structure classes runs locally, but the CLI prints a hosted-parity warning with the route: declare the types as MTHDS concepts with inline structures, and have a PipeFunc import the classes the sandbox generates from them (`from structures import <domain>__<Concept>`). The module `pipelex build structures` writes is accepted as long as it is left as generated.## Boundsdiff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.mdindex 47687d49f..6cecdb2ab 100644--- a/docs/tools/cli/run.md+++ b/docs/tools/cli/run.md@@ -28,7 +28,7 @@ Runs a pipe by code from your project's pipe library.**Options:**-- `--inputs`, `-i` - Path to a JSON or TOML file containing inputs (discriminated by file extension — see [Input File Formats](#input-file-formats))+- `--inputs`, `-i` - Path to a JSON or TOML file containing inputs (discriminated by file extension), or inline JSON starting with `{` — see [Input File Formats](#input-file-formats)- `--output-dir`, `-o` - Directory to save outputs (defaults to `results/`)- `--save-main-stuff` / `--no-save-main-stuff` - Whether to save the main output to a file- `--save-working-memory` / `--no-save-working-memory` - Whether to save the full working memory@@ -39,6 +39,9 @@ Runs a pipe by code from your project's pipe library.- `--graph-full-data` / `--graph-no-data` - Include full data in the graph visualization- `--dry-run` - Dry-run the pipeline without calling AI providers; no inference credentials are needed- `--mock-inputs` - Use mock inputs for the pipeline (requires `--dry-run`)+- `--costs` / `--no-costs` - Emit usage (cost) tracing events and render the end-of-run cost report, on by default (see [Cost Tracking](../../features/cost-tracking.md))+- `--orchestrator NAME` - Boot this process under the named orchestrator plugin, such as `temporal`; without it, the run executes in-process (see [Durable Execution](../../reliability/durable-execution.md))+- `--dynamic-output-concept`, `-O` - The concept ref, such as `document_qa.ReferenceCount`, that resolves a pipe whose output is declared `Dynamic`- `--library-dir`, `-L` - Directory to search for pipe definitions. Can be specified multiple times.- `--hosted` / `--local` - Run on the hosted Pipelex API or on this machine. Defaults to `[run] execution` (see [Running on the Hosted API](#running-on-the-hosted-api)), else local- `--base-url` - The origin a hosted run calls, `scheme://host[:port]`. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`@@ -86,7 +89,7 @@ Runs a pipeline from a bundle file (`.mthds`) or a pipeline directory. When a di**Options:**- `--pipe PIPE_CODE` - Run a specific pipe from the bundle (defaults to the bundle's main pipe)-- `--inputs`, `-i` - Path to a JSON or TOML file containing inputs (discriminated by file extension — see [Input File Formats](#input-file-formats))+- `--inputs`, `-i` - Path to a JSON or TOML file containing inputs (discriminated by file extension), or inline JSON starting with `{` — see [Input File Formats](#input-file-formats)- `--output-dir`, `-o` - Directory to save outputs- `--save-main-stuff` / `--no-save-main-stuff` - Whether to save the main output- `--save-working-memory` / `--no-save-working-memory` - Whether to save the full working memory@@ -97,6 +100,9 @@ Runs a pipeline from a bundle file (`.mthds`) or a pipeline directory. When a di- `--graph-full-data` / `--graph-no-data` - Include full data in the graph visualization- `--dry-run` - Dry-run the pipeline without calling AI providers; no inference credentials are needed- `--mock-inputs` - Use mock inputs for the pipeline (requires `--dry-run`)+- `--costs` / `--no-costs` - Emit usage (cost) tracing events and render the end-of-run cost report, on by default (see [Cost Tracking](../../features/cost-tracking.md))+- `--orchestrator NAME` - Boot this process under the named orchestrator plugin, such as `temporal`; without it, the run executes in-process (see [Durable Execution](../../reliability/durable-execution.md))+- `--dynamic-output-concept`, `-O` - The concept ref, such as `document_qa.ReferenceCount`, that resolves a pipe whose output is declared `Dynamic`- `--library-dir`, `-L` - Directory to search for additional pipe definitions. Can be specified multiple times.- `--hosted` / `--local` - Run on the hosted Pipelex API or on this machine. Defaults to `[run] execution` (see [Running on the Hosted API](#running-on-the-hosted-api)), else local- `--base-url` - The origin a hosted run calls, `scheme://host[:port]`. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`@@ -129,17 +135,17 @@ pipelex run bundle my_bundle.mthds --hostedpipelex run method <NAME> [OPTIONS]```-Runs a pipeline from an installed method package.+Runs a pipeline from a method package: an installed one, one in a local directory, one published at an address, or, on a hosted run, one stored on the hosted platform.**Arguments:**-- `NAME` - The name of the installed method to run, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](run-by-address.md). On a hosted run, also a stored method's catalog id (`mt_…`)+- `NAME` - The name of the installed method to run, the path of a local method directory, a method address (`github.com/owner/repo[/name][@tag]`), or a GitHub URL — see [Run a Method by Address](run-by-address.md). On a hosted run, also a stored method's catalog id (`mt_…`)**Options:**- `--pipe PIPE_CODE` - Run a specific pipe within the method (defaults to the method's main pipe)-- `--inputs`, `-i` - Path to a JSON or TOML file containing inputs (discriminated by file extension — see [Input File Formats](#input-file-formats))-- `--output-dir`, `-o` - Directory to save outputs (defaults to `results/` inside the method's directory; for a method fetched by address, `results/` under your current working directory — see [Run a Method by Address](run-by-address.md))+- `--inputs`, `-i` - Path to a JSON or TOML file containing inputs (discriminated by file extension), or inline JSON starting with `{` — see [Input File Formats](#input-file-formats)+- `--output-dir`, `-o` - Directory to save outputs (defaults to `results/` inside the method's directory; for a method fetched by address, and on a hosted run for an address or a catalog id, `results/` under your current working directory — see [Run a Method by Address](run-by-address.md))- `--save-main-stuff` / `--no-save-main-stuff` - Whether to save the main output- `--save-working-memory` / `--no-save-working-memory` - Whether to save the full working memory- `--working-memory-path` - Custom path for the working memory output file@@ -149,6 +155,9 @@ Runs a pipeline from an installed method package.- `--graph-full-data` / `--graph-no-data` - Include full data in the graph visualization- `--dry-run` - Dry-run the pipeline without calling AI providers; no inference credentials are needed- `--mock-inputs` - Use mock inputs for the pipeline (requires `--dry-run`)+- `--costs` / `--no-costs` - Emit usage (cost) tracing events and render the end-of-run cost report, on by default (see [Cost Tracking](../../features/cost-tracking.md))+- `--orchestrator NAME` - Boot this process under the named orchestrator plugin, such as `temporal`; without it, the run executes in-process (see [Durable Execution](../../reliability/durable-execution.md))+- `--dynamic-output-concept`, `-O` - The concept ref, such as `document_qa.ReferenceCount`, that resolves a pipe whose output is declared `Dynamic`- `--library-dir`, `-L` - Directory to search for additional pipe definitions. Can be specified multiple times.- `--hosted` / `--local` - Run on the hosted Pipelex API or on this machine. Defaults to `[run] execution` (see [Running on the Hosted API](#running-on-the-hosted-api)), else local- `--base-url` - The origin a hosted run calls, `scheme://host[:port]`. Overrides `PIPELEX_BASE_URL`, which overrides `https://api.pipelex.com`@@ -177,7 +186,7 @@ pipelex run method mt_abc123 --hosted --inputs data.json## Running on the Hosted API-A run executes on this machine by default, with the inference backends configured in `.pipelex/inference/` and your own provider keys. It can execute on the hosted Pipelex API instead, which needs only a Pipelex API key: no provider key and no inference configuration on this machine, since a hosted run boots nothing locally.+Without a `[run] execution` setting, a run executes on this machine, with the inference backends configured in `.pipelex/inference/` and your own provider keys. It can execute on the hosted Pipelex API instead, which needs only a Pipelex API key: no provider key and no inference configuration on this machine, since a hosted run boots nothing locally. [`pipelex init`](init.md#where-your-runs-execute) writes the setting from your answer, and the answer Enter takes is the hosted Pipelex API.Where a run executes is decided in this order:@@ -185,7 +194,11 @@ Where a run executes is decided in this order:2. `[run] execution` in `.pipelex/pipelex.toml` (`"local"` or `"hosted"`; the project's file over the one in `~/.pipelex/`), which [`pipelex init`](init.md#where-your-runs-execute) writes from your answer, see [Run Configuration](../../configuration/config-practical/run-config.md).3. Local.-The key is read from `PIPELEX_API_KEY`, exported in your shell or saved in `~/.pipelex/.env` (or a `.env` in the working directory), which Pipelex loads at startup. [`pipelex login`](login.md) gets a key through your browser and saves it there. The run goes to `--base-url` when given, else to `PIPELEX_BASE_URL`, else to `https://api.pipelex.com`. Either value must be an origin, `scheme://host[:port]` with `http` or `https` and no path such as `/v1`; anything else is refused before a request is sent, naming the setting it came from. A self-hosted Pipelex API server is reached the same way, by pointing the base URL at it. Every request a hosted run sends names its client in its `User-Agent` as `pipelex-cli/<version>`, followed by the versions of the pipelex-sdk and mthds clients it runs on, so the hosted API counts it as a CLI run; the header carries no key and nothing that identifies you.+The key is read from `PIPELEX_API_KEY`. [`pipelex login`](login.md) gets a key through your browser and saves it in `~/.pipelex/.env` (or in the `.env` of the directory `PIPELEX_HOME` names), which Pipelex loads at startup, followed by the `.env` of the working directory when there is one. The run goes to `--base-url` when given, else to `PIPELEX_BASE_URL`, else to `https://api.pipelex.com`. Either value must be an origin, `scheme://host[:port]` with `http` or `https` and no path such as `/v1`; anything else is refused before a request is sent, naming the setting it came from.++**The `.env` files win over your shell.** Each `.env` file Pipelex loads replaces the variables it sets, so for `PIPELEX_API_KEY`, `PIPELEX_BASE_URL` or any other variable, the working directory's `.env` wins over `~/.pipelex/.env`, which wins over a value exported in your shell: an exported value is read only when neither file sets the variable. To replace the saved key, run `pipelex login` again; to use another key, or another origin, in one directory, set it in that directory's `.env`.++Every request a hosted run sends names its client in its `User-Agent` as `pipelex-cli/<version>`, followed by the versions of the pipelex-sdk and mthds clients it runs on and by this machine's Python version, operating system and processor architecture (`python/<x.y.z> (<os>; <arch>)`), so the hosted API counts it as a CLI run; the header carries no key and nothing that identifies you.**What a hosted run sends** is what a local run would load:@@ -193,18 +206,26 @@ The key is read from `PIPELEX_API_KEY`, exported in your shell or saved in `~/.p- `run pipe` sends every `.mthds` file of its library directories: the installed method exporting the pipe and `-L`, else `PIPELEXPATH`. With none of them, the run is refused and asks for `-L`.- `run method` sends an installed or local method's files. A published address goes as a reference and a catalog id (`mt_…`) as an id, both resolved by the hosted API: nothing is fetched or read locally, `-L` is refused with them, and a relative `--inputs` path resolves against the working directory rather than the method's. A method installed under a name spelled like a catalog id, such as `mt_reports`, is that installed method, not an id.-**Local files in the inputs** are uploaded before the run. A path at a document or image input (compact, as `"invoice.pdf"`, or as the `url` of a document or image object, in a list or nested in a structure) is uploaded, and the run receives its storage URI instead. A relative path written in an inputs file resolves against that file's directory, as on a local run, and a `file://` URI is read as the path it names. A text that reads like a file name at any other input is left as text, `http(s)://` URLs, whatever the case of the scheme, are passed through for the hosted API to fetch, and an explicit `null`, such as an optional image left out, reaches the run as `null`.+Only the contents of the `.mthds` files are sent. A PipeFunc's Python function, Python structure classes, the package manifest `METHODS.toml` and the packages a bundle calls through a dependency alias (`alias->domain.pipe_code`) stay on this machine, and the hosted runner does not have them, so a local bundle or method that relies on any of them runs with `--local`. A published method run by its address is not limited this way: the hosted runner fetches the whole package itself (see [Python in fetched methods](run-by-address.md#python-in-fetched-methods-the-hosted-rule)).++**Local files in the inputs** are uploaded before the run. A path at a document or image input (compact, as `"invoice.pdf"`, or as the `url` of a document or image object, in a list or nested in a structure) is uploaded, and the run receives its storage URI instead. A relative path written in an inputs file resolves against that file's directory, as on a local run, and a `file://` URI is read as the path it names. A text that reads like a file name at any other input is left as text, and that includes a `.csv` path given to a structured-list input: it is not uploaded, the hosted runner receives a path it cannot read, so give the rows as a JSON list instead, or run with `--local`. `http(s)://` URLs, whatever the case of the scheme, are passed through for the hosted API to fetch, and an explicit `null`, such as an optional image left out, reaches the run as `null`.The method's signature, which says where a file sits, is read from the hosted API only when some value of the inputs, at any depth, names an existing file on this machine (from the inputs file's directory or the working directory). Inputs naming none go straight to the run. When the signature is read, a method that does not load is refused there, before any run starts, with validation errors that name the file each fault is in. A method that calls another method by its address (`github.com/…`) cannot have its signature read yet, so a local file cannot be uploaded for it: the run is refused before it starts, and the file has to be given as an `https://` URL instead. The same method runs with inputs that name no local file.-**What it saves** goes where a local run saves its outputs, in `<output-dir>/<pipe>_output_NN/`: `main_stuff.json` (and `main_stuff.md` when the main output is text), `working_memory.json`, and `graphspec.json` when the hosted API returned the run's graph, which [`pipelex graph render`](../../features/execution-graph.md) turns into a viewer. The run id is printed as soon as the hosted API acknowledges the run, as `Run <id> started on the hosted API`, and again with the recap.+**What it saves** goes where a local run saves its outputs, in `<output-dir>/<label>_output_NN/`: `main_stuff.json` (and `main_stuff.md` when the main output is text), `working_memory.json`, and `graphspec.json` when the hosted API returned the run's graph, which [`pipelex graph render`](../../features/execution-graph.md) turns into a viewer. The label is the pipe that ran, or, for a method run by its address or its catalog id without `--pipe`, the last segment of the address or the id itself, as in `mt_abc123_output_01/`. The run id is printed as soon as the hosted API acknowledges the run, as `Run <id> started on the hosted API`, and again with the recap.**When you interrupt it** with Ctrl-C, the command stops waiting, but a run the hosted API acknowledged keeps going and is paid for: the command prints its run id, so you can look it up on app.pipelex.com, and exits with `130`. Interrupted before the acknowledgement, it says that a run may have started if the request had reached the hosted API, and to check the run history before running again.-**What it refuses**: `--dry-run`, `--mock-inputs`, `--mock-usage`, `--orchestrator`, `--save-csv`, `--costs` / `--no-costs` and `--graph-full-data` / `--graph-no-data` steer this machine's runtime, which a hosted run never boots, so each is refused with a message pointing at `--local`. `--base-url` on a run that executes locally is refused too.+**What it refuses**: `--dry-run`, `--mock-inputs`, `--orchestrator`, `--save-csv`, `--costs` / `--no-costs` and `--graph-full-data` / `--graph-no-data` steer this machine's runtime, which a hosted run never boots, so each is refused with a message pointing at `--local`. `--base-url` on a run that executes locally is refused too.**When it fails**, the message gives the hosted API's reason and a next step: the one the server advised when it gave one, else one that follows the status (a refused key points at `PIPELEX_API_KEY` and `pipelex login`, an unknown method or route at the method's address and the base URL, a rate limit says to wait). A bundle the hosted API refuses lists its validation errors, and so does a run that started and failed on them. Once the hosted API has acknowledged the run, the failure also prints the run id: a run that failed, one that outlived the wait, one that completed without a main output, and one whose result could not be read, because the network or the hosted API failed while the run was being followed. That last one may still be running and is paid for, so look it up by its id on app.pipelex.com rather than running the command again. A connection lost after the request that runs the method was sent is not reported as a network failure either: the hosted API may have created the run before the connection failed, and its id never arrived, so check the run history before running again. Only a failure before the request left this machine, a connection that could not be made, points at the network and the base URL. A server that keeps no runs to poll, such as a self-hosted runner, is run on the blocking route, and when the connection is cut before its result comes back, the run may still be going there: running the command again runs the method again, so raise the timeout of the proxy in front of that server, or point the base URL at a server that keeps runs. The exit code is `1`.+**A self-hosted Pipelex API server**, such as the [Pipelex API server](../../api-server/index.md) run from its Docker image, is reached the same way, by pointing `--base-url` or `PIPELEX_BASE_URL` at its origin (`http://localhost:8081`, without `/v1`). `PIPELEX_API_KEY` is sent to it as the bearer token, so set it to the key that server expects when it requires one. Such a server runs your methods, but it does less than the hosted Pipelex API:++- It keeps no runs, so the run goes through its blocking route, and the run id is printed only with the recap, never at the start.+- It takes no uploads, so a local file named in the inputs is refused, with a next step saying to give it as an `http(s)://` URL.+- It has no catalog, so a catalog id (`mt_…`) is refused. A published address is fetched by the server itself.+## Input File FormatsAn inputs file is a dictionary whose keys are input variable names, and each value is interpreted **against the pipe's declared signature** — so you provide the values directly (a string, a number, an object) and Pipelex types them as the declared concept. See [Providing Inputs](../../building-methods/pipes/provide-inputs.md) for the full model, including the explicit `{concept, content}` escape hatch. Pipelex accepts **both JSON and TOML**, discriminated by the file extension:diff --git a/docs/tools/cli/update.md b/docs/tools/cli/update.mdindex 15b1a7b83..1f7898bef 100644--- a/docs/tools/cli/update.md+++ b/docs/tools/cli/update.md@@ -15,7 +15,7 @@ When a new `pipelex` release ships changes to the model deck — new models, new## When to run it-Pipelex prints a one-line yellow advisory on most CLI invocations when it detects that the installed deck is older than the running package, or when no deck manifest is present yet. It is suppressed for `init`, `doctor`, `update`, `migrate`, and `which`, and `pipelex run` prints it only for a run that executes on this machine, since a run on the hosted API reads no local deck:+Pipelex prints a one-line yellow advisory on most CLI invocations when it detects that the installed deck is older than the running package, or when no deck manifest is present yet. It is suppressed for `init`, `login`, `doctor`, `update`, `migrate`, and `which`, and `pipelex run` prints it only for a run that executes on this machine, since a run on the hosted API reads no local deck:```text⚠ Pipelex model deck may be out of date — run pipelex update to refreshdiff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.mdindex 84d80faaa..1e7c999d5 100644--- a/docs/under-the-hood/init-cli-flows.md+++ b/docs/under-the-hood/init-cli-flows.md@@ -26,7 +26,7 @@ These two categories are managed by separate steps. `init_config()` copies only| Command | Focus | What It Does ||---------|-------|--------------|-| `pipelex init` | `all` | Full setup: config, where runs execute, then inference + routing + credentials (this machine) or sign-in (hosted), then telemetry |+| `pipelex init` | `all` | Full setup: config, where runs execute, then inference + routing + credentials (this machine), then telemetry, then sign-in (hosted) || `pipelex init config` | `config` | Copy config templates, then ask where runs execute and set it up if first-time || `pipelex init inference` | `inference` | Interactive backend selection + routing for runs on this machine; never asks where runs execute || `pipelex init routing` | `routing` | Routing profile customization only |diff --git a/mkdocs.yml b/mkdocs.ymlindex 800c03cdd..9c15e13b1 100644--- a/mkdocs.yml+++ b/mkdocs.yml@@ -294,6 +294,7 @@ plugins:- tools/cli/login.md: "CLI Login"- tools/cli/update.md: "CLI Update"- tools/cli/migrate.md: "CLI Migrate"+ - tools/cli/doctor.md: "CLI Doctor"- tools/cli/validate.md: "CLI Validate"- tools/cli/fix.md: "CLI Fix"- tools/cli/run.md: "CLI Run"@@ -536,6 +537,7 @@ nav:- Login: tools/cli/login.md- Update: tools/cli/update.md- Migrate: tools/cli/migrate.md+ - Doctor: tools/cli/doctor.md- Validate: tools/cli/validate.md- Fix: tools/cli/fix.md- Run: tools/cli/run.mddiff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.pyindex 404604dc7..2f95b05d8 100644--- a/pipelex/cli/_cli.py+++ b/pipelex/cli/_cli.py@@ -283,7 +283,7 @@ app.add_typer()app.command(name="resolve", help="Resolve a bundle closure into the normalized library crate (JSON or TOML) on stdout")(resolve_cmd)app.add_typer(codegen_app, name="codegen", help="Project the resolved crate into typed, runnable artifacts (types, inputs) and check for drift")-app.add_typer(run_app, name="run", help="Run a method or pipe, optionally providing a specific bundle file (.mthds)")+app.add_typer(run_app, name="run", help="Run a method, a pipe, or a bundle (.mthds), on this machine or on the hosted Pipelex API (--hosted)")app.add_typer(graph_app, name="graph", help="Generate and render execution graphs")app.add_typer(show_app, name="show", help="Show configuration, pipes, and list AI models")app.command(name="which", help="Locate where a pipe is defined, similar to 'which' for executables")(which_cmd)diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.mdindex 3c6a3dc08..335adb978 100644--- a/pipelex/cli/agent_cli/CLAUDE.md+++ b/pipelex/cli/agent_cli/CLAUDE.md@@ -105,7 +105,7 @@ commands/- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`). Exception: `run method` on a fetched target (a method address or GitHub URL) anchors its run outputs in `results/` under the caller's CWD via `run_pipeline_core`'s `output_dir_override` — the fetched clone is an ephemeral temp dir deleted at process exit, so bundle-adjacent outputs would be lost.- **Validate refusals are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every input-domained refusal raised while loading a bundle, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid-verdict envelope and exit 1. No `validate` command keeps an arm of its own for a model-choice error; exit 2 stays for a failure of the tool or its environment (config, runtime, security).- **Run refusals are verdicts too**: a run loads its bundle inside the same translation (`acquire_library`), so an invalid bundle leaves `run pipe` / `run bundle` / `run method` as a `ValidateBundleError` with exit 1, through the generic `agent_error` arm, and `_assemble_error_payload` copies the report's `validation_errors` into the envelope for any cause that carries them. `run_pipeline_core` sets `library_dirs_are_callers=True`, so a refusal in a `-L` directory (or the bundle's own directory) is the same verdict; `run bundle`'s own parse of a bundle without `--pipe` goes through the translation too. So no `run` command keeps an arm of its own for a model-choice error either: an unknown model reaches it as the verdict's `unknown_model` item.-- **Hosted runs**: every `run` subcommand takes `--runner local|hosted`, `--hosted/--local` and `--base-url`; `resolve_agent_run_execution()` (`run/_run_hosted.py`) settles them through `pipelex.hosted.execution.resolve_run_execution` (the flag, then `[run] execution`, then local), refusing a `--runner` that contradicts the flag pair and a `--base-url` on a local run; a `PipelexConfigError` there carries `AGENT_INIT_FAILURE_HINT`, the hint a failed boot gives (`agent_cli_factory.py`). A hosted run boots nothing: it builds a `HostedRunRequest` from what `pipelex/cli/commands/run/_hosted_sources.py` resolves (the bundle and its library's `.mthds` files, a pipe's library, or a method's files; an address or a catalog id as `method_ref` / `method_id`, never fetched) and `run_hosted_for_agent()` runs it through `pipelex.hosted.hosted_run.run_hosted`, which reads the signature and uploads local input files (only when some input string names an existing local file, so a method with an address-based dependency runs with any other inputs), then drives the lifecycle `start_and_wait` drives step by step (the `/v1/version` handshake, `start`, `wait_for_result`, and the blocking `execute` on a server with no run store), so a failure while following an acknowledged run is a `HostedRunPollingError` naming the run, and a transport failure after the run request was sent is a `HostedRunOutcomeUnknownError` rather than an `ApiUnreachableError`. `run_hosted`'s `on_started` callback records the acknowledged run's id, so Ctrl-C (`KeyboardInterrupt`, or the `CancelledError` of a cancelled task) leaves as a `HostedRunInterruptedError` envelope carrying `pipeline_run_id`, with exit code 130. `run bundle` on a file with no `-L` sends `PIPELEXPATH`'s files (`hosted_library_dirs`), and an installed method named like a catalog id is that method. An exception no hosted arm names leaves through the command-boundary catch-all as the envelope. Its success envelope is `build_run_output()`'s, with the main output's content as `json`, an empty `markdown`, the working memory dump and `pipeline_run_id`; nothing is written to disk. `--dry-run` / `--mock-inputs` are refused on it. There is no global `--runner` any more, and no `ctx.obj`.+- **Hosted runs**: every `run` subcommand takes `--runner local|hosted`, `--hosted/--local` and `--base-url`; `resolve_agent_run_execution()` (`run/_run_hosted.py`) settles them through `pipelex.hosted.execution.resolve_run_execution` (the flag, then `[run] execution`, then local), refusing a `--runner` that contradicts the flag pair and a `--base-url` on a local run; a `PipelexConfigError` there carries `AGENT_INIT_FAILURE_HINT`, the hint a failed boot gives (`agent_cli_factory.py`). A hosted run boots nothing: it builds a `HostedRunRequest` from what `pipelex/cli/commands/run/_hosted_sources.py` resolves (the bundle and its library's `.mthds` files, a pipe's library, or a method's files; an address or a catalog id as `method_ref` / `method_id`, never fetched) and `run_hosted_for_agent()` runs it through `pipelex.hosted.hosted_run.run_hosted`, which reads the signature and uploads local input files (only when some input string names an existing local file, so a method with an address-based dependency runs with any other inputs), then drives the lifecycle `start_and_wait` drives step by step (the `/v1/version` handshake, `start`, `wait_for_result`, and the blocking `execute` on a server with no run store), so a failure while following an acknowledged run is a `HostedRunPollingError` naming the run, and a transport failure after the run request was sent is a `HostedRunOutcomeUnknownError` rather than an `ApiUnreachableError`. `run_hosted`'s `on_started` callback records the acknowledged run's id, so Ctrl-C (`KeyboardInterrupt`, or the `CancelledError` of a cancelled task) leaves as a `HostedRunInterruptedError` envelope carrying `pipeline_run_id`, with exit code 130. `run bundle` on a file with no `-L` sends `PIPELEXPATH`'s files (`hosted_library_dirs`), and an installed method named like a catalog id is that method. An exception no hosted arm names leaves through the command-boundary catch-all as the envelope. Its success envelope is `build_run_output()`'s, with the main output's content as `json`, an empty `markdown`, the working memory dump and `pipeline_run_id`; nothing is written to disk. `--dry-run` / `--mock-inputs` are refused on it, while `--graph` and `--costs` are accepted and ignored. There is no global `--runner` any more, and no `ctx.obj`.- **Hosted refusals**: `agent_error_hosted()` routes pipelex-sdk's `ApiResponseError` (every `PipelexAPIClient` route raises it on a non-2xx answer) to `agent_error_api_response()`. `api_response_error_payload()` builds the envelope from the problem document alone: `error_type` is the runner's class (`ValidateBundleError` at load, as a local run reports it, or the root fault of a failed run, which a local run reports as `cause_type` under `PipelineExecutionError`; this path has no `cause_type`), `message` is the error's own `API POST /v1/start failed (<status>): <reason>` without the next step it appends, `hint` is `user_action.detail`, and `error_domain` / `error_category` / `retryable` / `validation_errors` / `pipe_code` / `pipe_stack` / `request_id` are the runner's, plus `error_code` (the problem's `code`), `retry_after_seconds` (the `Retry-After` header) and `http_status`. It deliberately bypasses `agent_error()`'s lookups: the dict hints keyed on a class name local commands (`doctor`, `check-model`) that cannot fix a remote refusal, and the domain is only the runner's to say, so one with no `error_domain` carries none. A refusal with no `user_action` — the hosted plane's own answers in front of the runner: the gateway's 403 for a bad key, the rate limiter's 429, the unreachable runner's 503 — gets its status's next step from `pipelex.hosted.error_rendering` (`HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS`, the table the human CLI reads too; 401 and 403 point at `PIPELEX_API_KEY` and `pipelex login`, 404 at the method and the origin), else `HOSTED_REFUSAL_CALLER_NEXT_STEP` for any other 4xx and `HOSTED_SERVER_FAULT_NEXT_STEP` for the rest. Only a 429 that did not say otherwise is inferred `retryable`: the platform can answer a 503 after the run completed, when it failed to record the result, so its hint warns that a retry can repeat a paid run. Every other failure, the SDK's and pipelex's own `HostedRunError` subclasses alike, goes through `agent_error()` with what `describe_hosted_error()` reads off it, the view the human CLI prints too: the class, message, next step, domain and `retryable`, the `pipeline_run_id` of any failure met once the run was acknowledged (`RunFailedError`, `RunTimeoutError`, `MissingMainStuffError`, `HostedRunPollingError`, `HostedRunInterruptedError`), a `retryable` passed whenever the hosted API gave a verdict, `false` included, so `RETRYABLE_ERROR_TYPES` keyed on the runner's class never overrides it, and the `validation_errors` of a failed run or of a `HostedMethodInvalidError` (pipe-io's verdict on a method that does not load, whose items name the faulty file in `source`); a `RunFailedError` adds `run_status` and its report's category, model and provider. The markdown renderer keeps a runner item this pipelex's `ValidationErrorItem` cannot type (a newer `error_type`, an unknown field) as JSON under Details instead of failing.- **Method-reference failures**: the `run`/`validate`/`inputs` method commands call `resolve_method_target(..., raise_ref_errors=True)` and shape the typed `MethodRefError` subclasses into `agent_error(...)` themselves (validate uses `exit_code=2`, its no-verdict convention) — the human CLI's red-text rendering stays in `resolve_method_target`'s default arm.- **TOML handling**: Uses `tomlkit` (not `tomllib`) to preserve formatting and inline tables.diff --git a/pipelex/cli/agent_cli/_agent_cli.py b/pipelex/cli/agent_cli/_agent_cli.pyindex d3aa51f44..690be5b3b 100644--- a/pipelex/cli/agent_cli/_agent_cli.py+++ b/pipelex/cli/agent_cli/_agent_cli.py@@ -77,7 +77,15 @@ def version_callback(value: bool) -> None: # kw-only: ignore — click invokesraise typer.Exit[email protected](invoke_without_command=True)+#: What `pipelex-agent --help` says of the program. Given explicitly, since Typer would otherwise print the callback's+#: docstring, which is written for this module's maintainers.+AGENT_CLI_HELP = (+ "The machine-oriented Pipelex CLI, for AI agents, IDE extensions and automation: no prompts and no logs, results on stdout "+ "(Markdown or JSON for most commands), and errors as a structured envelope on stderr."+)++[email protected](invoke_without_command=True, help=AGENT_CLI_HELP)def app_callback(version: Annotated[ # ruff: ignore[unused-function-argument]bool,diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.pyindex 947ac4b78..050ca1344 100644--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py@@ -128,8 +128,13 @@ AGENT_CLI_CONFIG_OVERRIDES: Mapping[str, Any] = MappingProxyType()-#: The next step of a boot that failed, and of any other failure to read this machine's configuration.-AGENT_INIT_FAILURE_HINT = "Initialization failed. Run 'pipelex-agent doctor' to diagnose, or 'pipelex init config' to reset configuration"+#: The next step of a boot that failed, and of any other failure to read this machine's configuration. It names only+#: commands an agent can run: `pipelex init config` asks questions and can open a browser.+AGENT_INIT_FAILURE_HINT = (+ "Initialization failed. Run 'pipelex-agent doctor' to diagnose. An out-of-date configuration is brought up to date by "+ "'pipelex-agent migrate --dry-run --format json', shown to the user, then 'pipelex-agent migrate --yes'; "+ "'pipelex-agent init' (--global for the home configuration) writes a fresh one instead, discarding its settings"+)def apply_agent_cli_output_discipline() -> None:@@ -208,8 +213,8 @@ def make_pipelex_for_agent_cli(*, library_dirs: list[str] | list[Path] | None =except TelemetryConfigValidationError as exc:agent_error(exc.message, error_type="TelemetryConfigValidationError", cause=exc)except FormerReleaseConfigError as exc:- # Its own hint rather than the generic one, which offers a reset: the cleanup keeps everything but what a former- # release left, and an agent can run it.+ # Its own hint, the class's user_action, rather than the generic one, which offers a reset: the cleanup keeps+ # everything but what a former release left, and an agent can run it.agent_error(exc.message, error_type="FormerReleaseConfigError", cause=exc)except ModelDeckPresetValidatonError as exc:agent_error(diff --git a/pipelex/cli/agent_cli/commands/agent_output.py b/pipelex/cli/agent_cli/commands/agent_output.pyindex e37898df4..a3651bb10 100644--- a/pipelex/cli/agent_cli/commands/agent_output.py+++ b/pipelex/cli/agent_cli/commands/agent_output.py@@ -130,13 +130,6 @@ AGENT_ERROR_HINTS: dict[str, str] = {"False means the migration would write nothing and its 'plans' name what to correct by hand. ""Without a 'migration' field, correct the telemetry.toml settings named in the message."),- # A configuration a former release set up for the Pipelex Gateway: the cleanup is the loop, and- # a reset would discard every other setting the cleanup keeps.- "FormerReleaseConfigError": (- "This configuration still carries what a former release left for the Pipelex Gateway. "- "Run 'pipelex-agent migrate --dry-run --format json' to see what the cleanup would remove (its 'former_release' key), "- "show the user, then run 'pipelex-agent migrate --yes'. It keeps a copy of each file it changes or removes."- ),"BinaryNotFoundError": "Install pipelex-tools: uv tool install pipelex-tools",# Graph errors"GraphSpecParseError": "Validate graphspec.json structure; ensure it matches the expected GraphSpec schema",diff --git a/pipelex/cli/agent_cli/commands/run/app.py b/pipelex/cli/agent_cli/commands/run/app.pyindex 64b2ecc02..7546d9b31 100644--- a/pipelex/cli/agent_cli/commands/run/app.py+++ b/pipelex/cli/agent_cli/commands/run/app.py@@ -13,6 +13,9 @@ run_app = typer.Typer(no_args_is_help=True,)-run_app.command(name="method", help="Execute a pipeline for an installed method")(run_method_cmd)+run_app.command(+ name="method",+ help="Execute a method by installed name, local directory, published address, or, on a hosted run, catalog id (mt_…)",+)(run_method_cmd)run_app.command(name="pipe", help="Execute a pipeline by pipe code")(run_pipe_cmd)run_app.command(name="bundle", help="Execute a pipeline from a bundle file or directory")(run_bundle_cmd)diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.pyindex cf85194e2..86988b350 100644--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py@@ -52,7 +52,7 @@ def run_bundle_cmd(] = None,inputs: Annotated[str | None,- typer.Option("--inputs", "-i", help="Path to JSON file with inputs or inline JSON"),+ typer.Option("--inputs", "-i", help="Inputs: a JSON or TOML file (by its extension), or inline JSON starting with {"),] = None,dry_run: Annotated[bool,diff --git a/pipelex/cli/agent_cli/commands/run/method_cmd.py b/pipelex/cli/agent_cli/commands/run/method_cmd.pyindex 7c5f73a28..a83bb4df1 100644--- a/pipelex/cli/agent_cli/commands/run/method_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/method_cmd.py@@ -44,7 +44,12 @@ from pipelex.pipeline.exceptions import PipelineExecutionErrordef run_method_cmd(name: Annotated[str,- typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL"),+ typer.Argument(+ help=(+ "Installed method name, local method directory, method address (github.com/owner/repo\\[/name]\\[@tag]), "+ "GitHub URL, or, on a hosted run, a catalog id (mt_…)"+ ),+ ),],pipe: Annotated[str | None,@@ -52,7 +57,7 @@ def run_method_cmd(] = None,inputs: Annotated[str | None,- typer.Option("--inputs", "-i", help="Path to JSON file with inputs or inline JSON"),+ typer.Option("--inputs", "-i", help="Inputs: a JSON or TOML file (by its extension), or inline JSON starting with {"),] = None,dry_run: Annotated[bool,diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.pyindex 08b676ee0..f421c75ee 100644--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py@@ -46,7 +46,7 @@ def run_pipe_cmd(],inputs: Annotated[str | None,- typer.Option("--inputs", "-i", help="Path to JSON file with inputs or inline JSON"),+ typer.Option("--inputs", "-i", help="Inputs: a JSON or TOML file (by its extension), or inline JSON starting with {"),] = None,dry_run: Annotated[bool,diff --git a/pipelex/cli/commands/doctor_cmd.py b/pipelex/cli/commands/doctor_cmd.pyindex c5944ed93..84439f945 100644--- a/pipelex/cli/commands/doctor_cmd.py+++ b/pipelex/cli/commands/doctor_cmd.py@@ -990,7 +990,10 @@ def display_health_report(if backend_credential_report.placeholder_vars:console.print(f" [yellow]⚠[/yellow] Placeholders: {escape(', '.join(backend_credential_report.placeholder_vars))}")- error_msg = BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg(backend_credential_reports=bad_backend_credential_reports)+ error_msg = BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg(+ backend_credential_reports=bad_backend_credential_reports,+ suggest_hosted_runs=True,+ )console.print(error_msg)console.print()diff --git a/pipelex/cli/commands/login/command.py b/pipelex/cli/commands/login/command.pyindex ee5f422b9..d277c28bf 100644--- a/pipelex/cli/commands/login/command.py+++ b/pipelex/cli/commands/login/command.py@@ -274,8 +274,11 @@ def login_cmd(*, paste: bool = False) -> None:console.print()if not outcome.is_saved:raise typer.Exit(code=1)+ # `pipelex init` would also make hosted runs the default, but it resets every configuration file: the one setting is lighter.+ home_pipelex_toml_path = get_global_env_path().parent / "pipelex.toml"console.print(- "[dim]Run a method on the hosted API with[/dim] [cyan]pipelex run … --hosted[/cyan][dim], or make it the default with[/dim] "- "[cyan]pipelex init[/cyan][dim].[/dim]"+ "[dim]Run a method on the hosted API with[/dim] [cyan]pipelex run … --hosted[/cyan][dim], or make it the default by setting[/dim] "+ f'[cyan]\\[run] execution = "hosted"[/cyan] [dim]in {escape(str(home_pipelex_toml_path))}, '+ "or in a project's .pipelex/pipelex.toml.[/dim]")console.print()diff --git a/pipelex/cli/commands/run/app.py b/pipelex/cli/commands/run/app.pyindex a7090b0ff..e312b1596 100644--- a/pipelex/cli/commands/run/app.py+++ b/pipelex/cli/commands/run/app.py@@ -4,8 +4,11 @@ from pipelex.cli.commands.run.bundle_cmd import run_bundle_cmdfrom pipelex.cli.commands.run.method_cmd import run_method_cmdfrom pipelex.cli.commands.run.pipe_cmd import run_pipe_cmd-run_app = typer.Typer(help="Run a method, pipe, or bundle", no_args_is_help=True)+run_app = typer.Typer(help="Run a method, a pipe, or a bundle, on this machine or on the hosted Pipelex API (--hosted)", no_args_is_help=True)-run_app.command("method", help="Run an installed method by name")(run_method_cmd)+run_app.command(+ "method",+ help="Run a method by installed name, local directory, published address, or, on a hosted run, catalog id (mt_…)",+)(run_method_cmd)run_app.command("pipe", help="Run a pipe by code")(run_pipe_cmd)run_app.command("bundle", help="Run a pipeline from a bundle file (.mthds) or directory")(run_bundle_cmd)diff --git a/pipelex/cli/commands/run/bundle_cmd.py b/pipelex/cli/commands/run/bundle_cmd.pyindex 169220d5e..aba274dc8 100644--- a/pipelex/cli/commands/run/bundle_cmd.py+++ b/pipelex/cli/commands/run/bundle_cmd.py@@ -26,7 +26,7 @@ def run_bundle_cmd(] = None,inputs: Annotated[str | None,- typer.Option("--inputs", "-i", help="Path to JSON file with inputs"),+ typer.Option("--inputs", "-i", help="Inputs: a JSON or TOML file (by its extension), or inline JSON starting with {"),] = None,save_working_memory: Annotated[bool,diff --git a/pipelex/cli/commands/run/method_cmd.py b/pipelex/cli/commands/run/method_cmd.pyindex 549d35611..924bca6e2 100644--- a/pipelex/cli/commands/run/method_cmd.py+++ b/pipelex/cli/commands/run/method_cmd.py@@ -17,7 +17,12 @@ from pipelex.methods.exceptions import MethodRefErrordef run_method_cmd(name: Annotated[str,- typer.Argument(help="Installed method name, method address (github.com/owner/repo\\[/name]\\[@tag]), or GitHub URL to run"),+ typer.Argument(+ help=(+ "Installed method name, local method directory, method address (github.com/owner/repo\\[/name]\\[@tag]), "+ "GitHub URL, or, on a hosted run, a catalog id (mt_…)"+ ),+ ),],pipe: Annotated[str | None,@@ -25,7 +30,7 @@ def run_method_cmd(] = None,inputs: Annotated[str | None,- typer.Option("--inputs", "-i", help="Path to JSON file with inputs"),+ typer.Option("--inputs", "-i", help="Inputs: a JSON or TOML file (by its extension), or inline JSON starting with {"),] = None,save_working_memory: Annotated[bool,diff --git a/pipelex/cli/commands/run/pipe_cmd.py b/pipelex/cli/commands/run/pipe_cmd.pyindex e43e844a9..f58885186 100644--- a/pipelex/cli/commands/run/pipe_cmd.py+++ b/pipelex/cli/commands/run/pipe_cmd.py@@ -20,7 +20,7 @@ def run_pipe_cmd(],inputs: Annotated[str | None,- typer.Option("--inputs", "-i", help="Path to JSON file with inputs"),+ typer.Option("--inputs", "-i", help="Inputs: a JSON or TOML file (by its extension), or inline JSON starting with {"),] = None,save_working_memory: Annotated[bool,diff --git a/pipelex/cogt/model_backends/backend_credentials.py b/pipelex/cogt/model_backends/backend_credentials.pyindex a05d77c3a..4cc4a4385 100644--- a/pipelex/cogt/model_backends/backend_credentials.py+++ b/pipelex/cogt/model_backends/backend_credentials.py@@ -13,6 +13,16 @@ class BackendCredentialsReport(ConfigModel):all_credentials_valid: bool+#: The way out a command-line user has besides provider keys: a run on the hosted Pipelex API needs none. Only a caller that+#: knows it serves the `pipelex` or `pipelex-agent` CLI adds it, since a server operator cannot act on it. No square+#: brackets: the message is printed through Rich markup and as plain text alike.+HOSTED_RUNS_HINT = (+ "\n☁ Or run on the hosted Pipelex API, which needs no provider key:\n"+ " Run 'pipelex login' to save a Pipelex API key, then add --hosted to a run, or make hosted runs\n"+ ' the default with execution = "hosted" in the run section of your pipelex.toml.\n'+)++class BackendCredentialsErrorMsgFactory:@classmethoddef make_one_variable_missing_error_msg(@@ -21,6 +31,7 @@ class BackendCredentialsErrorMsgFactory:secrets_provider: SecretsProviderAbstract,backend_name: str | None,var_name: str,+ suggest_hosted_runs: bool = False,) -> str:"""Build an error message for a single missing credential variable.@@ -28,6 +39,7 @@ class BackendCredentialsErrorMsgFactory:secrets_provider: The secrets provider being usedbackend_name: Name of the backend with the missing credentialvar_name: Name of the missing variable+ suggest_hosted_runs: Whether to add the hosted Pipelex API as a way out, for a command-line user"""error_msg: strif isinstance(secrets_provider, EnvSecretsProvider):@@ -60,6 +72,9 @@ class BackendCredentialsErrorMsgFactory:" backends in '.pipelex/inference/backends.toml'.\n")+ if suggest_hosted_runs:+ error_msg += HOSTED_RUNS_HINT+return error_msg@classmethod@@ -68,12 +83,14 @@ class BackendCredentialsErrorMsgFactory:backend_credential_reports: dict[str, BackendCredentialsReport],*,secrets_provider: SecretsProviderAbstract | None = None,+ suggest_hosted_runs: bool = False,) -> str:"""Build a comprehensive error message for missing backend credentials.Args:secrets_provider: The secrets provider being usedbackend_credential_reports: Dict of backend_name -> credential report for backends with issues+ suggest_hosted_runs: Whether to add the hosted Pipelex API as a way out, for a command-line user"""# Build the details section for each backend with issuesbackend_details_lines: list[str] = []@@ -139,4 +156,7 @@ class BackendCredentialsErrorMsgFactory:" backends in '.pipelex/inference/backends.toml'.\n")+ if suggest_hosted_runs:+ error_msg += HOSTED_RUNS_HINT+return error_msgdiff --git a/pipelex/hosted/error_rendering.py b/pipelex/hosted/error_rendering.pyindex 692db549f..c226f2845 100644--- a/pipelex/hosted/error_rendering.py+++ b/pipelex/hosted/error_rendering.py@@ -35,10 +35,12 @@ from pipelex.hosted.exceptions import HostedMethodInvalidError, HostedRunError,#: The command that gets a Pipelex API key and saves it where a hosted run reads it.PIPELEX_LOGIN_COMMAND = "pipelex login"-#: Where a hosted run takes its key from, and how a person gets one.+#: Where a hosted run takes its key from, and how a person gets one. The runtime loads the home `.env`, then the working+#: directory's, each over the environment, so a key exported in the shell cannot replace one either file sets.HOSTED_API_KEY_NEXT_STEP = (- f"Run {PIPELEX_LOGIN_COMMAND} to get a Pipelex API key (plx_sk_…) and save it to ~/.pipelex/.env as {PIPELEX_API_KEY_ENV_KEY}, "- f"or set {PIPELEX_API_KEY_ENV_KEY} to one in your shell"+ f"Run {PIPELEX_LOGIN_COMMAND} to get a Pipelex API key (plx_sk_…) and save it to ~/.pipelex/.env as {PIPELEX_API_KEY_ENV_KEY}. "+ f"A .env in the working directory that sets {PIPELEX_API_KEY_ENV_KEY} wins over that file, so correct or remove the line there; "+ f"a key exported in your shell is used only when neither .env file sets {PIPELEX_API_KEY_ENV_KEY}")#: Where a hosted run takes its origin from.HOSTED_BASE_URL_NEXT_STEP = (diff --git a/pipelex/hosted/exceptions.py b/pipelex/hosted/exceptions.pyindex 5fbcc12d0..c54591137 100644--- a/pipelex/hosted/exceptions.py+++ b/pipelex/hosted/exceptions.py@@ -33,7 +33,12 @@ class HostedBaseUrlError(HostedRunError):class HostedRunSourceError(HostedRunError):- """A hosted run cannot be given the method to run: no bundle file, no `.mthds` file in the library directories, or no source at all."""+ """A hosted run cannot be given its method: no bundle file, an unreadable method file, no `.mthds` file, or `-L` with an address or a catalog id.++ The hosted API resolves a published address or a catalog id itself and loads no local library, so `-L` is refused+ with either. Every other case is about the files a hosted run sends: none named, none found in the library+ directories, or one that cannot be read.+ """error_domain = ErrorDomain.INPUT_authors_caller_facing_message: ClassVar[bool] = Truediff --git a/pipelex/migration/exceptions.py b/pipelex/migration/exceptions.pyindex bb913aa56..cf17ed80d 100644--- a/pipelex/migration/exceptions.py+++ b/pipelex/migration/exceptions.py@@ -1,4 +1,5 @@from pipelex.base_exceptions import ErrorDomain, PipelexError, PipelexSetupError+from pipelex.cogt.inference.error_classification import UserAction, UserActionKindclass MigrationError(PipelexError):@@ -47,3 +48,13 @@ class FormerReleaseConfigError(PipelexSetupError):"""_declared_title = "Configuration left by a former release"+ # One next step for a person and an agent alike, since both read it: the human command first, then the loop an+ # agent runs, which shows the user what the cleanup would remove before it writes anything.+ user_action = UserAction(+ kind=UserActionKind.UNKNOWN,+ detail=(+ "Run 'pipelex migrate' to remove what the former release left; it keeps a copy of each file it changes or removes. "+ "From an agent, run 'pipelex-agent migrate --dry-run --format json' to see what the cleanup would remove "+ "(its 'former_release' key), show the user, then run 'pipelex-agent migrate --yes'."+ ),+ )diff --git a/pipelex/runtime_boot.py b/pipelex/runtime_boot.pyindex f1d9ff9c7..857b37225 100644--- a/pipelex/runtime_boot.py+++ b/pipelex/runtime_boot.py@@ -546,6 +546,8 @@ If you need help, drop by our Discord: we're happy to assist: {URLs.discord}.secrets_provider=secrets_provider,backend_name=backend_name,var_name=var_name,+ # A person at either CLI can run on the hosted Pipelex API instead; a server's operator cannot.+ suggest_hosted_runs=integration_mode.is_pipelex_command_line,)raise PipelexSetupError(error_msg) from credentials_excdiff --git a/pipelex/system/runtime.py b/pipelex/system/runtime.pyindex d673bd9cb..47dad882f 100644--- a/pipelex/system/runtime.py+++ b/pipelex/system/runtime.py@@ -19,6 +19,27 @@ class IntegrationMode(StrEnum):PYTEST = "pytest"PYTHON = "python"+ @property+ def is_pipelex_command_line(self) -> bool:+ """Whether this process serves the `pipelex` or `pipelex-agent` command line, whose user can act on CLI advice.++ Such a user can run `pipelex login` and pass `--hosted`, so an error may offer the hosted Pipelex API as a way out;+ a server, a test run or an embedding program cannot.+ """+ match self:+ case IntegrationMode.CLI:+ return True+ case (+ IntegrationMode.CI+ | IntegrationMode.DOCKER+ | IntegrationMode.FASTAPI+ | IntegrationMode.MCP+ | IntegrationMode.N8N+ | IntegrationMode.PYTEST+ | IntegrationMode.PYTHON+ ):+ return False+class RunMode(StrEnum):NORMAL = "normal"diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.py b/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.pyindex f3997272d..3eb451c59 100644--- a/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.py+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_credentials.py@@ -2,6 +2,7 @@ import pytestfrom pytest_mock import MockerFixturefrom pipelex.cogt.model_backends.backend_credentials import (+ HOSTED_RUNS_HINT,BackendCredentialsErrorMsgFactory,BackendCredentialsReport,)@@ -180,3 +181,33 @@ class TestBackendCredentials:" - Add 'enabled = false' under '\\[bedrock]'\n" + BYOK_HINT)assert error_msg == expected_msg++ @pytest.mark.parametrize("suggest_hosted_runs", [True, False])+ def test_one_variable_missing_offers_hosted_runs_only_when_asked(self, suggest_hosted_runs: bool):+ """A command-line caller gets the hosted Pipelex API as the last way out, after the BYOK hint; the default leaves it out."""+ error_msg = BackendCredentialsErrorMsgFactory.make_one_variable_missing_error_msg(+ secrets_provider=EnvSecretsProvider(),+ backend_name="openai",+ var_name="OPENAI_API_KEY",+ suggest_hosted_runs=suggest_hosted_runs,+ )+ assert error_msg.endswith(BYOK_HINT + HOSTED_RUNS_HINT) is suggest_hosted_runs+ assert ("pipelex login" in error_msg) is suggest_hosted_runs++ @pytest.mark.parametrize("suggest_hosted_runs", [True, False])+ def test_comprehensive_offers_hosted_runs_only_when_asked(self, suggest_hosted_runs: bool):+ """The doctor's report offers the hosted Pipelex API after the BYOK hint; the default leaves it out."""+ reports = {"openai": make_report(backend_name="openai", missing_vars=["OPENAI_API_KEY"], placeholder_vars=[])}+ error_msg = BackendCredentialsErrorMsgFactory.make_comprehensive_error_msg(+ backend_credential_reports=reports,+ secrets_provider=EnvSecretsProvider(),+ suggest_hosted_runs=suggest_hosted_runs,+ )+ assert error_msg.endswith(BYOK_HINT + HOSTED_RUNS_HINT) is suggest_hosted_runs+ assert ("--hosted" in error_msg) is suggest_hosted_runs++ def test_hosted_runs_hint_holds_no_square_bracket(self):+ """The hint is printed through Rich markup and as plain text, so it names the setting without a bracketed table."""+ assert "[" not in HOSTED_RUNS_HINT+ assert "pipelex login" in HOSTED_RUNS_HINT+ assert 'execution = "hosted"' in HOSTED_RUNS_HINTdiff --git a/tests/unit/pipelex/system/test_integration_mode.py b/tests/unit/pipelex/system/test_integration_mode.pynew file mode 100644index 000000000..e273d2541--- /dev/null+++ b/tests/unit/pipelex/system/test_integration_mode.py@@ -0,0 +1,14 @@+import pytest++from pipelex.system.runtime import IntegrationMode+++class TestIntegrationMode:+ def test_only_the_cli_is_the_pipelex_command_line(self):+ """The CLI integration is the one whose user can act on command-line advice such as `pipelex login`."""+ assert IntegrationMode.CLI.is_pipelex_command_line is True++ @pytest.mark.parametrize("integration_mode", [mode for mode in IntegrationMode if mode is not IntegrationMode.CLI])+ def test_every_other_integration_is_not_the_pipelex_command_line(self, integration_mode: IntegrationMode):+ """A server, a test run or an embedding program is never offered command-line advice."""+ assert integration_mode.is_pipelex_command_line is False