pipelex-api 0.71.0__tar.gz

pipelex_api-0.71.0/.gitignore

@@ -0,0 +1,60 @@
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+*.egg-info/
+
+# Unit test / coverage reports
+htmlcov/
+.pytest_cache/
+.coverage
+coverage.xml
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+
+# Ruff
+.ruff_cache/
+
+# General System Files
+*.log
+.DS_Store
+Thumbs.db
+
+# Files generated by unit tests
+reports/
+results/
+
+# temporary files
+temp/
+
+# editor/tool backup artifacts
+*.bak
+*.bak.*
+
+gcp_credentials.json
+
+.pipelex/storage
+
+# personnal pipelex config files that overrides the default one
+pipelex_super.toml
+pipelex_override.toml
+telemetry_override.toml
+# local-only env override (boots the runner as the hosted runner; needs a plugin CI lacks)
+.pipelex/pipelex_dev.toml
+
+.gstack/

pipelex_api-0.71.0/LICENSE

@@ -0,0 +1,95 @@
+Copyright (c) 2025-2026 Evotis S.A.S.
+
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

pipelex_api-0.71.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: pipelex-api
+Version: 0.71.0
+Summary: Pipelex API
+Project-URL: Homepage, https://pipelex.com
+Project-URL: Repository, https://github.com/Pipelex/pipelex
+Project-URL: Documentation, https://docs.pipelex.com/latest/api-server/
+Project-URL: Changelog, https://docs.pipelex.com/latest/changelog/
+Author-email: "Evotis S.A.S." <oss@pipelex.com>
+Maintainer-email: Pipelex staff <oss@pipelex.com>
+License-Expression: Elastic-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.11
+Requires-Dist: fastapi<0.142,>=0.118.0
+Requires-Dist: pipelex[anthropic,bedrock,fal,google,google-genai,mistralai]==0.71.0
+Requires-Dist: pyjwt>=2.10.1
+Requires-Dist: uvicorn>=0.37.0
+Provides-Extra: dev
+Requires-Dist: boto3-stubs>=1.35.24; extra == 'dev'
+Requires-Dist: httpx2>=2.4.0; extra == 'dev'
+Requires-Dist: mypy>=1.11.2; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.2.3.241126; extra == 'dev'
+Requires-Dist: pylint>=3.3.8; extra == 'dev'
+Requires-Dist: pyright>=1.1.405; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
+Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
+Requires-Dist: pytest-sugar>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.3; extra == 'dev'
+Requires-Dist: ruff>=0.6.8; extra == 'dev'
+Requires-Dist: types-aiobotocore[bedrock,bedrock-runtime]>=3.0.0; extra == 'dev'
+Requires-Dist: types-aiofiles>=24.1.0.20240626; extra == 'dev'
+Requires-Dist: types-beautifulsoup4>=4.12.0.20240907; extra == 'dev'
+Requires-Dist: types-markdown>=3.6.0.20240316; extra == 'dev'
+Requires-Dist: types-networkx>=3.3.0.20241020; extra == 'dev'
+Requires-Dist: types-openpyxl>=3.1.5.20250306; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.12.20250326; extra == 'dev'
+Requires-Dist: types-requests>=2.32.0.2024091; extra == 'dev'
+Requires-Dist: types-toml>=0.10.8.20240310; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <a href="https://www.pipelex.com/"><img src="https://raw.githubusercontent.com/Pipelex/pipelex/main/.github/assets/logo.png" alt="Pipelex Logo" width="400" style="max-width: 100%; height: auto;"></a>
+
+  <h2 align="center">Pipelex API</h2>
+
+The official REST API server for building and executing Pipelex pipelines. Deploy your pipelines as HTTP endpoints and integrate them into any application or workflow.
+
+  <div>
+    <a href="https://docs.pipelex.com/latest/api-server/"><strong>API Documentation</strong></a> -
+    <a href="https://github.com/Pipelex/pipelex"><strong>Pipelex Core</strong></a> -
+    <a href="https://go.pipelex.com/discord"><strong>Discord</strong></a>
+  </div>
+  <br/>
+
+  <p align="center">
+    <a href="https://docs.pipelex.com/latest/license/"><img src="https://img.shields.io/badge/License-Elastic--2.0-blue.svg" alt="Elastic License 2.0"></a>
+    <a href="https://go.pipelex.com/discord"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+    <a href="https://docs.pipelex.com/"><img src="https://img.shields.io/badge/Docs-03bb95?logo=read-the-docs&logoColor=white&style=flat" alt="Documentation"></a>
+  </p>
+</div>
+
+---
+
+> **Released with pipelex, under pipelex's version.** This server is the [`api/` directory](https://github.com/Pipelex/pipelex/tree/main/api) of [`Pipelex/pipelex`](https://github.com/Pipelex/pipelex), and every pipelex release ships it: the `pipelex-api` package on PyPI pins the `pipelex` of the same version, and `pipelex/pipelex-api:X.Y.Z` runs pipelex X.Y.Z. It was released on its own from `Pipelex/pipelex-api` until v0.33.2, so the image tag that follows 0.33.2 is a pipelex version. The image keeps its name, its port and its `/root/.pipelex` configuration mount. Please open issues on `Pipelex/pipelex`.
+
+# 📑 Table of Contents
+
+- [Introduction](#introduction)
+- [Quick Start with Docker](#-quick-start-with-docker)
+- [Run your first pipeline](#-run-your-first-pipeline)
+- [How to scale Pipelex](#-how-to-scale-pipelex)
+- [API Documentation](#-api-documentation)
+- [Support](#-support)
+- [License](#-license)
+
+# Introduction
+
+The **Pipelex API Server** is a FastAPI-based REST API that allows you to execute [Pipelex](https://github.com/Pipelex/pipelex) pipelines via HTTP requests. Deploy your pipelines as HTTP endpoints and integrate them into any application or workflow.
+
+It is the source-available reference implementation of the **[MTHDS Protocol](https://mthds.ai)** — the minimal HTTP contract every MTHDS runner implements (`POST /execute`, `POST /start`, `POST /validate`, `GET /models`, `GET /version`). The contracts nest: **MTHDS Protocol ⊂ Pipelex API (this server) ⊂ Pipelex hosted API**. This server adds the build tooling extensions (`/build/*`) on top of the protocol; the hosted API at `api.pipelex.com/v1` adds durable runs, the method catalog, and account management on top of this server — same shapes throughout. All routes live under the `/v1` base path; the committed contract is [`pipelex-api.openapi.yaml`](https://github.com/Pipelex/pipelex/blob/main/docs/api-server/openapi/pipelex-api.openapi.yaml).
+
+# 🚀 Quick Start with Docker
+
+**Official Docker image available at:** [`pipelex/pipelex-api`](https://hub.docker.com/r/pipelex/pipelex-api)
+
+The published image is **generic and configuration-light**: Temporal is off, no S3, no remote tracing. It boots with a single required env var (`PIPELEX_GATEWAY_API_KEY`), and you bring your own [Pipelex configuration](https://docs.pipelex.com/latest/api-server/configuration/) on top to enable storage, tracing, Temporal, or anything else.
+
+### 1. Run with Docker
+
+The only required env var is `PIPELEX_GATEWAY_API_KEY`. Get a free key (with free credits) at https://app.pipelex.com, then run:
+
+```bash
+docker run --name pipelex-api -p 8081:8081 \
+  -e PIPELEX_GATEWAY_API_KEY=your-pipelex-gateway-api-key \
+  pipelex/pipelex-api:latest
+```
+
+To require authentication on the API, add `-e AUTH_MODE=api_key -e API_KEY=your-secret` (or `AUTH_MODE=jwt` + `JWT_SECRET_KEY`). See [`.env.example`](https://github.com/Pipelex/pipelex/blob/main/api/.env.example) for the full list of supported variables and the [Configuration page](https://docs.pipelex.com/latest/api-server/configuration/) for `--env-file` and `docker compose` patterns if you'd rather keep config out of your shell history.
+
+If you'd rather build the image yourself instead of pulling, replace `pipelex/pipelex-api:latest` with a local tag after `docker build -f api/Dockerfile -t pipelex-api .`, run from the root of a `Pipelex/pipelex` checkout: the build context is the repository root, so the image installs the pipelex library of the same commit.
+
+### 2. Verify
+
+```bash
+curl http://localhost:8081/health
+```
+
+The API is now running at `http://localhost:8081`. To customize behavior (enable Temporal, swap to S3 storage, layer in env-specific overrides, …), see the [Configuration page](https://docs.pipelex.com/latest/api-server/configuration/).
+
+# 🧪 Run your first pipeline
+
+Once `/health` is green, send an inline pipeline definition and inputs to `/v1/execute`. The example below summarizes a string with a one-pipe MTHDS bundle — no files, no auth, copy-paste:
+
+```bash
+curl -s http://localhost:8081/v1/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pipe_code": "summarize",
+    "mthds_contents": ["domain = \"hello\"\nmain_pipe = \"summarize\"\n\n[pipe.summarize]\ntype = \"PipeLLM\"\ndescription = \"Summarize the input text in one sentence\"\ninputs = { text = \"Text\" }\noutput = \"Text\"\nprompt = \"Summarize in one sentence:\\n@text\"\n"],
+    "inputs": { "text": "Pipelex turns plain-language pipeline definitions into reproducible AI workflows that run as HTTP endpoints." }
+  }'
+```
+
+You'll get back a JSON response with `state: "COMPLETED"` and the summary under `pipe_output.working_memory.root.<main_stuff_name>.content`.
+
+**Passing files (PDFs, images) as inputs.** Use the `Document` concept and point it at any HTTP(S) URL:
+
+```json
+{
+  "pipe_code": "your_pipe",
+  "mthds_contents": ["...your MTHDS..."],
+  "inputs": {
+    "cv": { "concept": "Document", "content": { "url": "https://example.com/resume.pdf" } }
+  }
+}
+```
+
+`Document` accepts public HTTP/HTTPS URLs, `pipelex-storage://` URIs, or base64 data URLs. For images, use the `Image` concept with the same `{ "url": "..." }` shape.
+
+For inline MTHDS in the request, `mthds_contents` is a JSON array of raw `.mthds` (TOML) file contents as strings — typically `[open("my_pipe.mthds").read()]` from a client. See the [Pipe Run page](https://docs.pipelex.com/latest/api-server/pipe-run/) for every supported input shape and the full `/execute` reference.
+
+# 📈 How to scale Pipelex
+
+A single Pipelex API container is great for development, prototyping, and low-concurrency workloads — pipelines run in-process and `/v1/execute` blocks the request thread until they finish.
+
+For production-scale workloads (high concurrency, long-running pipelines, retries, durable execution, horizontal scaling), the recommended path is to run Pipelex on top of [**Temporal**](https://temporal.io/). With Temporal enabled:
+
+- Pipeline runs become durable workflows — survive worker crashes, support retries and timeouts out of the box.
+- The API container becomes a thin orchestrator: it submits workflows to a Temporal cluster and returns a `pipeline_run_id` immediately (this is what `POST /v1/start` already does).
+- Pipeline execution itself runs on a separate pool of **Pipelex workers** that you scale independently from the HTTP layer.
+- Async completion callbacks (`callback_urls` + `X-Completion-Signature`, see [Pipe Run](https://docs.pipelex.com/latest/api-server/pipe-run/)) let your application be notified when each run finishes, without polling.
+
+Pipelex already integrates with Temporal under the hood, and the Docker image accepts `TEMPORAL_API_KEY` plus a `[temporal] is_enabled = true` override in `.pipelex/`. **A complete deployment recipe (Temporal cluster sizing, worker container, autoscaling guidance, and an end-to-end docker-compose) is coming soon.** In the meantime, if you need to scale today, get in touch on [Discord](https://go.pipelex.com/discord) and we'll help you wire it up.
+
+# 📖 API Documentation
+
+The full reference for this API server is part of the Pipelex documentation, under [API Server](https://docs.pipelex.com/latest/api-server/):
+
+- [Overview](https://docs.pipelex.com/latest/api-server/) — endpoints, authentication, deployment
+- [Pipe Run](https://docs.pipelex.com/latest/api-server/pipe-run/) — `/execute`, `/start`, every input shape
+- [Pipe Validate](https://docs.pipelex.com/latest/api-server/pipe-validate/) — `/validate`
+- [Pipe Builder](https://docs.pipelex.com/latest/api-server/pipe-builder/) — `/build/inputs`, `/build/output`, `/build/runner`
+- [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/)**
+
+# 💬 Support
+
+- **API Documentation**: [https://docs.pipelex.com/latest/api-server/](https://docs.pipelex.com/latest/api-server/)
+- **Pipelex Documentation**: [https://docs.pipelex.com/](https://docs.pipelex.com/)
+- **Discord Community**: [https://go.pipelex.com/discord](https://go.pipelex.com/discord)
+- **Main Repository**: [https://github.com/Pipelex/pipelex](https://github.com/Pipelex/pipelex)
+
+# 📝 License
+
+This project is licensed under the Elastic License 2.0 (ELv2); see [LICENSE](https://github.com/Pipelex/pipelex/blob/main/LICENSE) for the terms, and the [license page](https://docs.pipelex.com/latest/license/) for how Pipelex reads them. Runtime dependencies are distributed under their own licenses via PyPI.
+
+---
+
+"Pipelex" is a trademark of Evotis S.A.S.
+
+© 2025-2026 Evotis S.A.S.

pipelex_api-0.71.0/README.md

@@ -0,0 +1,142 @@
+<div align="center">
+  <a href="https://www.pipelex.com/"><img src="https://raw.githubusercontent.com/Pipelex/pipelex/main/.github/assets/logo.png" alt="Pipelex Logo" width="400" style="max-width: 100%; height: auto;"></a>
+
+  <h2 align="center">Pipelex API</h2>
+
+The official REST API server for building and executing Pipelex pipelines. Deploy your pipelines as HTTP endpoints and integrate them into any application or workflow.
+
+  <div>
+    <a href="https://docs.pipelex.com/latest/api-server/"><strong>API Documentation</strong></a> -
+    <a href="https://github.com/Pipelex/pipelex"><strong>Pipelex Core</strong></a> -
+    <a href="https://go.pipelex.com/discord"><strong>Discord</strong></a>
+  </div>
+  <br/>
+
+  <p align="center">
+    <a href="https://docs.pipelex.com/latest/license/"><img src="https://img.shields.io/badge/License-Elastic--2.0-blue.svg" alt="Elastic License 2.0"></a>
+    <a href="https://go.pipelex.com/discord"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+    <a href="https://docs.pipelex.com/"><img src="https://img.shields.io/badge/Docs-03bb95?logo=read-the-docs&logoColor=white&style=flat" alt="Documentation"></a>
+  </p>
+</div>
+
+---
+
+> **Released with pipelex, under pipelex's version.** This server is the [`api/` directory](https://github.com/Pipelex/pipelex/tree/main/api) of [`Pipelex/pipelex`](https://github.com/Pipelex/pipelex), and every pipelex release ships it: the `pipelex-api` package on PyPI pins the `pipelex` of the same version, and `pipelex/pipelex-api:X.Y.Z` runs pipelex X.Y.Z. It was released on its own from `Pipelex/pipelex-api` until v0.33.2, so the image tag that follows 0.33.2 is a pipelex version. The image keeps its name, its port and its `/root/.pipelex` configuration mount. Please open issues on `Pipelex/pipelex`.
+
+# 📑 Table of Contents
+
+- [Introduction](#introduction)
+- [Quick Start with Docker](#-quick-start-with-docker)
+- [Run your first pipeline](#-run-your-first-pipeline)
+- [How to scale Pipelex](#-how-to-scale-pipelex)
+- [API Documentation](#-api-documentation)
+- [Support](#-support)
+- [License](#-license)
+
+# Introduction
+
+The **Pipelex API Server** is a FastAPI-based REST API that allows you to execute [Pipelex](https://github.com/Pipelex/pipelex) pipelines via HTTP requests. Deploy your pipelines as HTTP endpoints and integrate them into any application or workflow.
+
+It is the source-available reference implementation of the **[MTHDS Protocol](https://mthds.ai)** — the minimal HTTP contract every MTHDS runner implements (`POST /execute`, `POST /start`, `POST /validate`, `GET /models`, `GET /version`). The contracts nest: **MTHDS Protocol ⊂ Pipelex API (this server) ⊂ Pipelex hosted API**. This server adds the build tooling extensions (`/build/*`) on top of the protocol; the hosted API at `api.pipelex.com/v1` adds durable runs, the method catalog, and account management on top of this server — same shapes throughout. All routes live under the `/v1` base path; the committed contract is [`pipelex-api.openapi.yaml`](https://github.com/Pipelex/pipelex/blob/main/docs/api-server/openapi/pipelex-api.openapi.yaml).
+
+# 🚀 Quick Start with Docker
+
+**Official Docker image available at:** [`pipelex/pipelex-api`](https://hub.docker.com/r/pipelex/pipelex-api)
+
+The published image is **generic and configuration-light**: Temporal is off, no S3, no remote tracing. It boots with a single required env var (`PIPELEX_GATEWAY_API_KEY`), and you bring your own [Pipelex configuration](https://docs.pipelex.com/latest/api-server/configuration/) on top to enable storage, tracing, Temporal, or anything else.
+
+### 1. Run with Docker
+
+The only required env var is `PIPELEX_GATEWAY_API_KEY`. Get a free key (with free credits) at https://app.pipelex.com, then run:
+
+```bash
+docker run --name pipelex-api -p 8081:8081 \
+  -e PIPELEX_GATEWAY_API_KEY=your-pipelex-gateway-api-key \
+  pipelex/pipelex-api:latest
+```
+
+To require authentication on the API, add `-e AUTH_MODE=api_key -e API_KEY=your-secret` (or `AUTH_MODE=jwt` + `JWT_SECRET_KEY`). See [`.env.example`](https://github.com/Pipelex/pipelex/blob/main/api/.env.example) for the full list of supported variables and the [Configuration page](https://docs.pipelex.com/latest/api-server/configuration/) for `--env-file` and `docker compose` patterns if you'd rather keep config out of your shell history.
+
+If you'd rather build the image yourself instead of pulling, replace `pipelex/pipelex-api:latest` with a local tag after `docker build -f api/Dockerfile -t pipelex-api .`, run from the root of a `Pipelex/pipelex` checkout: the build context is the repository root, so the image installs the pipelex library of the same commit.
+
+### 2. Verify
+
+```bash
+curl http://localhost:8081/health
+```
+
+The API is now running at `http://localhost:8081`. To customize behavior (enable Temporal, swap to S3 storage, layer in env-specific overrides, …), see the [Configuration page](https://docs.pipelex.com/latest/api-server/configuration/).
+
+# 🧪 Run your first pipeline
+
+Once `/health` is green, send an inline pipeline definition and inputs to `/v1/execute`. The example below summarizes a string with a one-pipe MTHDS bundle — no files, no auth, copy-paste:
+
+```bash
+curl -s http://localhost:8081/v1/execute \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pipe_code": "summarize",
+    "mthds_contents": ["domain = \"hello\"\nmain_pipe = \"summarize\"\n\n[pipe.summarize]\ntype = \"PipeLLM\"\ndescription = \"Summarize the input text in one sentence\"\ninputs = { text = \"Text\" }\noutput = \"Text\"\nprompt = \"Summarize in one sentence:\\n@text\"\n"],
+    "inputs": { "text": "Pipelex turns plain-language pipeline definitions into reproducible AI workflows that run as HTTP endpoints." }
+  }'
+```
+
+You'll get back a JSON response with `state: "COMPLETED"` and the summary under `pipe_output.working_memory.root.<main_stuff_name>.content`.
+
+**Passing files (PDFs, images) as inputs.** Use the `Document` concept and point it at any HTTP(S) URL:
+
+```json
+{
+  "pipe_code": "your_pipe",
+  "mthds_contents": ["...your MTHDS..."],
+  "inputs": {
+    "cv": { "concept": "Document", "content": { "url": "https://example.com/resume.pdf" } }
+  }
+}
+```
+
+`Document` accepts public HTTP/HTTPS URLs, `pipelex-storage://` URIs, or base64 data URLs. For images, use the `Image` concept with the same `{ "url": "..." }` shape.
+
+For inline MTHDS in the request, `mthds_contents` is a JSON array of raw `.mthds` (TOML) file contents as strings — typically `[open("my_pipe.mthds").read()]` from a client. See the [Pipe Run page](https://docs.pipelex.com/latest/api-server/pipe-run/) for every supported input shape and the full `/execute` reference.
+
+# 📈 How to scale Pipelex
+
+A single Pipelex API container is great for development, prototyping, and low-concurrency workloads — pipelines run in-process and `/v1/execute` blocks the request thread until they finish.
+
+For production-scale workloads (high concurrency, long-running pipelines, retries, durable execution, horizontal scaling), the recommended path is to run Pipelex on top of [**Temporal**](https://temporal.io/). With Temporal enabled:
+
+- Pipeline runs become durable workflows — survive worker crashes, support retries and timeouts out of the box.
+- The API container becomes a thin orchestrator: it submits workflows to a Temporal cluster and returns a `pipeline_run_id` immediately (this is what `POST /v1/start` already does).
+- Pipeline execution itself runs on a separate pool of **Pipelex workers** that you scale independently from the HTTP layer.
+- Async completion callbacks (`callback_urls` + `X-Completion-Signature`, see [Pipe Run](https://docs.pipelex.com/latest/api-server/pipe-run/)) let your application be notified when each run finishes, without polling.
+
+Pipelex already integrates with Temporal under the hood, and the Docker image accepts `TEMPORAL_API_KEY` plus a `[temporal] is_enabled = true` override in `.pipelex/`. **A complete deployment recipe (Temporal cluster sizing, worker container, autoscaling guidance, and an end-to-end docker-compose) is coming soon.** In the meantime, if you need to scale today, get in touch on [Discord](https://go.pipelex.com/discord) and we'll help you wire it up.
+
+# 📖 API Documentation
+
+The full reference for this API server is part of the Pipelex documentation, under [API Server](https://docs.pipelex.com/latest/api-server/):
+
+- [Overview](https://docs.pipelex.com/latest/api-server/) — endpoints, authentication, deployment
+- [Pipe Run](https://docs.pipelex.com/latest/api-server/pipe-run/) — `/execute`, `/start`, every input shape
+- [Pipe Validate](https://docs.pipelex.com/latest/api-server/pipe-validate/) — `/validate`
+- [Pipe Builder](https://docs.pipelex.com/latest/api-server/pipe-builder/) — `/build/inputs`, `/build/output`, `/build/runner`
+- [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/)**
+
+# 💬 Support
+
+- **API Documentation**: [https://docs.pipelex.com/latest/api-server/](https://docs.pipelex.com/latest/api-server/)
+- **Pipelex Documentation**: [https://docs.pipelex.com/](https://docs.pipelex.com/)
+- **Discord Community**: [https://go.pipelex.com/discord](https://go.pipelex.com/discord)
+- **Main Repository**: [https://github.com/Pipelex/pipelex](https://github.com/Pipelex/pipelex)
+
+# 📝 License
+
+This project is licensed under the Elastic License 2.0 (ELv2); see [LICENSE](https://github.com/Pipelex/pipelex/blob/main/LICENSE) for the terms, and the [license page](https://docs.pipelex.com/latest/license/) for how Pipelex reads them. Runtime dependencies are distributed under their own licenses via PyPI.
+
+---
+
+"Pipelex" is a trademark of Evotis S.A.S.
+
+© 2025-2026 Evotis S.A.S.

pipelex_api-0.71.0/hatch_build.py

@@ -0,0 +1,48 @@
+"""The hatch metadata hook that pins the published server on the pipelex it was released with.
+
+The server and the library are released together under one version number, which this member reads from the
+repository root's `pyproject.toml` (`[tool.hatch.version]`). In the workspace, its `pipelex` dependency resolves
+from the same commit and carries no version, because uv ignores a version specifier on a workspace source. A
+published `pipelex-api` has no workspace to resolve from, so its metadata must say which pipelex it was released
+with, or an install would pair the server with whatever pipelex PyPI serves.
+
+This hook writes the dependencies: each requirement of `lockstep-dependencies` pinned to `==` this distribution's
+own version, then `dependencies` as written. Both lists live in `[tool.hatch.metadata.hooks.custom]` of
+`pyproject.toml`, and `dependencies` is declared dynamic there, since a build backend may not rewrite a static
+field. A wheel built from the sdist reads the dependencies back from `PKG-INFO`, so this hook runs once per release.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.requirements import Requirement
+
+
+class LockstepPinMetadataHook(MetadataHookInterface):
+    def update(self, metadata: dict[str, Any]) -> None:
+        version = metadata.get("version")
+        if not isinstance(version, str) or not version:
+            msg = "The lockstep pin needs the distribution's version, which hatch had not resolved when the hook ran."
+            raise ValueError(msg)
+        lockstep_requirements = self._string_list(option="lockstep-dependencies")
+        other_requirements = self._string_list(option="dependencies")
+        pinned_requirements: list[str] = []
+        for requirement_text in lockstep_requirements:
+            requirement = Requirement(requirement_text)
+            if requirement.specifier or requirement.url or requirement.marker:
+                msg = (
+                    f"`{requirement_text}` in `lockstep-dependencies` must name the package and its extras only: "
+                    "the hook supplies the version, so a specifier, a URL or a marker written here would be overridden."
+                )
+                raise ValueError(msg)
+            pinned_requirements.append(f"{requirement_text}=={version}")
+        metadata["dependencies"] = [*pinned_requirements, *other_requirements]
+
+    def _string_list(self, *, option: str) -> list[str]:
+        value = self.config.get(option)
+        if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+            msg = f"Option `{option}` of the custom metadata hook must be a list of strings."
+            raise TypeError(msg)
+        return list(value)

pipelex_api-0.71.0/pipelex_api/api.toml

@@ -0,0 +1,21 @@
+# Pipelex-API deployment config — the packaged default, loaded by `load_api_config()`
+# (pipelex_api/api_config.py) via core's env-aware `load_plugin_config` and validated into `ApiConfig`.
+# Keys live at the file root (no `[api]` wrapper) — `load_plugin_config` validates the whole merged
+# document against the schema, exactly like `pipelex-temporal`'s `temporal.toml`. The packaged
+# default here is deep-merged with an optional `api_{env}.toml` / `api_override.toml` at `~/.pipelex`
+# then the project `.pipelex` (env selected by `PIPELEX_ENV`). This source-available base names NO
+# orchestrator: it ships the in-process `direct` mode and refuses per-request override. A deployment
+# flavor bakes its own `.pipelex/api_{env}.toml` to flip this (e.g. `pipelex-api-hosted` sets
+# `orchestration_mode = "temporal"`).
+
+# Which orchestrator a top-level run dispatches to, through the orchestrator registry.
+# `orchestration_mode` is an OPEN string token: core owns "direct" (in-process); each orchestrator
+# plugin owns its own ("temporal" from pipelex-temporal, "mistral-workflows" from
+# pipelex-mistral-workflows). A token whose plugin is not installed fails loud at dispatch with the
+# plugin's install hint. The delivery axis (blocking vs fire-and-forget) is NOT configured here — it
+# is set by the endpoint (`/execute` and `/validate` block; `/start` is fire-and-forget).
+orchestration_mode = "direct"
+
+# Whether a caller may override `orchestration_mode` per request. Off on the base (and recommended off
+# on hosted flavors): a locked-down distributed runner must not be coercible into `direct`.
+allow_request_orchestration_mode_override = false