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.
# GENERATED FILE — do not edit by hand. Regenerate with `make openapi-export`.
openapi: 3.1.0
info:
title: Pipelex API
summary: The source-available Pipelex runner — implements MTHDS Protocol v2.0.0.
description: 'This server implements the [MTHDS Protocol](https://mthds.ai) v2.0.0 (`POST /execute`, `POST /start`, `POST
/validate`, `GET /models`, `GET /version` — marked `x-mthds-protocol: true`) plus the Pipelex API extensions: resolve
and codegen (`/resolve`, `/codegen`), the pipe I/O route (`/pipe-io`), the model reference check (`/models/check`), and
editor tooling (`/lint`, `/format`). Contract layering: MTHDS Protocol ⊂ Pipelex API (this server) ⊂ Pipelex hosted API.
All endpoints are served under the `/v1` base path; every error is an RFC 7807 `application/problem+json` problem document,
documented per operation as a `ProblemDocument`.'
license:
name: Elastic License 2.0
identifier: Elastic-2.0
version: 0.93.1
paths:
/health:
get:
tags:
- health
summary: Liveness probe
description: 'Report that this server process is up and serving. No auth required.
A pure liveness probe for load balancers and orchestrators: it touches no
dependency (no pipelex library load, no storage, no inference provider), so
a 200 means "the process is serving", never "the deployment is correctly
configured". It is mounted outside the `/v1` base path and outside the auth
dependency, and cannot fail.'
operationId: get_health_health_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
/v1/version:
get:
tags:
- discovery
summary: Get Version
description: 'Protocol and implementation versions (MTHDS Protocol `GET /version`).
The handshake clients use for feature detection: `implementation`
identifies this runner, `implementation_version` is this server package''s
version, and `runtime_version` is the underlying pipelex runtime version.
`blob_store` is true: this runner keeps a blob store over its storage
provider and serves `POST /v1/blobs/missing` and `PUT /v1/blobs/{sha256}`,
so a sender may name a file of `files` by its hash.'
operationId: get_version_v1_version_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PipelexVersionInfo'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/blobs/{sha256}:
put:
tags:
- blobs
summary: Upload one blob's bytes to the target POST /blobs/missing named.
description: 'Store one blob''s bytes under its SHA-256, as the upload target `POST /v1/blobs/missing` named (MTHDS
Protocol).
The body is the blob''s bytes and nothing else. A target whose signature does not hold, or that has expired, is a
403 `auth.forbidden` whose `requirement` is a signed upload target, as is a query that is not one this runner signs,
such as an expiry that is not a decimal integer; a body past `MAX_METHOD_TREE_FILE_KIB` a 413 `request.too_large`;
and a body whose SHA-256 is not the path''s a 422 `request.invalid` naming the body. A blob is never changed:
uploading bytes the runner already holds answers 204 and changes nothing, and uploading bytes whose hash names an
object of another size, which only damaged storage could hold, is a 500 `pipelex.storage.damaged` that leaves the
object as it is.'
operationId: put_blob_v1_blobs__sha256__put
parameters:
- name: sha256
in: path
required: true
schema:
type: string
pattern: ^[0-9a-f]{64}$
description: The SHA-256 of the body, in lowercase hexadecimal.
title: Sha256
description: The SHA-256 of the body, in lowercase hexadecimal.
- name: scope
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The blob store's scope, as the signed target names it.
title: Scope
description: The blob store's scope, as the signed target names it.
- name: expires
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: When the target expires, in seconds since the epoch.
title: Expires
description: When the target expires, in seconds since the epoch.
- name: signature
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The target's signature.
title: Signature
description: The target's signature.
responses:
'204':
description: Successful Response
'403':
description: '`auth.forbidden`, whose `params.requirement` is `signed_upload_target` — the upload does not carry
the signed query an upload target of `POST /v1/blobs/missing` names, its signature does not hold for this hash
and scope, or it has expired. Ask `POST /v1/blobs/missing` again for a fresh target.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
requestBody:
required: true
content:
application/octet-stream:
schema:
type: string
format: binary
/v1/execute:
post:
tags:
- run
summary: Execute
description: 'Execute a method synchronously and return its full output (MTHDS Protocol `POST /execute`).
The backend is selected by the resolved `orchestration_mode` (deployment default + optional
policy-gated per-request override via the `orchestration_mode` extra), symmetric with `/start` —
not by `boot_orchestrator`. `/execute` is synchronous, so it dispatches with `BLOCKING` delivery
regardless of backend (wait-semantics is endpoint-set, never requestable). Pipelex domain
failures propagate untouched: the global `PipelexError` handler in `pipelex_api.exception_handlers`
turns them into an RFC 7807 problem response.'
operationId: execute_v1_execute_post
requestBody:
content:
application/json:
schema:
$defs:
Base64FileEntry:
properties:
base64:
type: string
title: Base64
description: The file's bytes in canonical padded standard Base64.
additionalProperties: false
type: object
required:
- base64
title: Base64FileEntry
description: A file entry carrying the file's bytes in canonical padded standard Base64.
HashFileEntry:
properties:
sha256:
type: string
pattern: ^[0-9a-f]{64}$
title: Sha256
description: The SHA-256 of the file's bytes, in lowercase hexadecimal.
size:
type: integer
minimum: 0.0
title: Size
description: The file's size in bytes, an integer written with no fraction or exponent.
additionalProperties: false
type: object
required:
- sha256
- size
title: HashFileEntry
description: A file entry naming, by their SHA-256 and their size, bytes the receiver already holds in its
blob store.
StuffContentAbstract:
properties: {}
type: object
title: StuffContentAbstract
properties:
pipe_code:
anyOf:
- type: string
- type: 'null'
title: Pipe Code
mthds_contents:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Mthds Contents
description: 'Being retired, and refused by a later release: send the method in `files`. The method''s `.mthds`
files as raw strings, always an array, even for a single file; with no `pipe_code`, a file must declare
`main_pipe`. Mutually exclusive with `files`, `bundle_b64` and `method_ref`.'
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- items:
type: string
type: array
- $ref: '#/$defs/StuffContentAbstract'
- items:
$ref: '#/$defs/StuffContentAbstract'
type: array
- additionalProperties: true
type: object
type: object
- type: 'null'
title: Inputs
output_name:
anyOf:
- type: string
- type: 'null'
title: Output Name
output_multiplicity:
anyOf:
- type: boolean
- type: integer
- type: 'null'
title: Output Multiplicity
dynamic_output_concept_ref:
anyOf:
- type: string
- type: 'null'
title: Dynamic Output Concept Ref
bundle_b64:
anyOf:
- type: string
- type: 'null'
title: Bundle B64
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — base64-encoded zip of the method''s
folder, read as a map of its entries, so the archive''s names are judged by the method tree''s rule as
the keys of `files` are. The method packages it calls by address may travel with it under `.mthds/methods/<name>/`,
each with its `METHODS.toml`; they are searched before the runner''s installed copies, for this run alone.
Mutually exclusive with `files`. Custom `.py` is only honored on a sandbox-hosted deployment. Being retired
with `mthds_contents`, and refused by a later release: send the method in `files`.'
files:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/$defs/Base64FileEntry'
- $ref: '#/$defs/HashFileEntry'
type: object
- type: 'null'
title: Files
description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels:
each key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment
starting with a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or
`{"sha256": ..., "size": ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing`
then `PUT /v1/blobs/{sha256}`). The map is read from the request''s JSON text: a key given twice, a key
the membership rule keeps out of every tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid`
whose `reason` is the refusal''s code and whose `path` names the first path, a key leaving the tree is
a 422 `security.input_path_refused`, a malformed entry is a 422 `request.invalid`, and hash entries the
runner does not hold are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists every such
hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read, such as
a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom
`.py` is only honored on a sandbox-hosted deployment.'
dependencies:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: string
- $ref: '#/$defs/Base64FileEntry'
- $ref: '#/$defs/HashFileEntry'
type: object
type: object
- type: 'null'
title: Dependencies
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls
by address that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map
of file entries>}`: each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its
root declaring the address it is keyed by. They are searched before the runner''s installed copies, for
this request alone. Accompanies `files`.'
method_ref:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Method Ref
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — run a published method by reference
instead of inline source. Address form: `github.com/<owner>/<repo>[/<selector>][@<tag>]` (e.g. `github.com/Pipelex/methods/[email protected]`)
— resolved by THIS runner: the repository is fetched at the tag (a bare address means the default branch
at HEAD), the package is located by manifest identity, and the resolved commit SHA is recorded as `method_provenance`
on the response. Mutually exclusive with `mthds_contents` and with a method bundle (`bundle_b64` / `files`);
`pipe_code` may accompany it to override the manifest''s `main_pipe`. A package shipping custom Python
is only honored on a sandbox-hosted deployment, and a package declaring Python structure classes is always
refused — hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python.'
resources:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Resources
description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
(an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative
path, exactly as the step names it, to the file''s bytes in standard base64. A path must be relative and
written with forward slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`,
every bundle of the request is read as sitting in one directory, and every file must be named by a step,
or the request is refused with a 422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`,
each file joins the tree at its path from the tree''s root, where a file the tree already holds must have
the same bytes. By default at most 32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment
sets its own with `MAX_RESOURCES_PER_REQUEST`, `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`.
The files make one method tree with the bundles, which the run names by its digest: no file''s bytes travel
with the run, each being read where a step uses it. Being retired with `mthds_contents`, and refused by
a later release: send these files in the method''s tree, in `files`.'
orchestration_mode:
anyOf:
- type: string
- type: 'null'
title: Orchestration Mode
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — request the orchestration mode (the
backend) for this run. An OPEN string token: `direct` (in-process, the base default), `temporal`, and
any other plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery
axis (blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment
sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs
from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
Omit it to use the deployment default.'
storage_scope:
anyOf:
- type: string
- type: 'null'
title: Storage Scope
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every object
this run writes lands under. One to three path-safe segments (e.g. `tenant/run` or `org/method/run`);
the runtime composes its own leaves (`assets/`, `generated/`, `results/`, `payloads/`) onto it and never
interprets the value. Omit it and the run is scoped to the caller's own id, which is correct for a single-tenant
deployment and wrong for a multi-tenant one — a host serving many tenants MUST send this.
read_scope:
anyOf:
- type: string
- type: 'null'
title: Read Scope
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every stored
object this run reads must lie under, and on a scoped run no local path is read at all. One to three path-safe
segments, which must be the `storage_scope` or one of its leading segments, since a run reads back what
it writes. Omit it and the run is scoped to the caller's own id when the deployment identifies callers,
and unscoped when it is single-tenant — a host serving many tenants MUST send this.
analytics_groups:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Analytics Groups
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied groups this run''s
telemetry belongs to, as a mapping of group type to group key (e.g. `{"organization": "org_acme"}`). The
runtime never reads a key by name: it carries the mapping on the run as its `extras` and stamps it on
every span as `pipelex.run.extras`, so every OpenTelemetry exporter receives it, and the deployment''s
own PostHog stream, in `identified` mode, forwards it as the capture''s groups. Group types are lowercase
snake_case starting with a letter, at most 32 characters; group keys are 1 to 128 characters from `[A-Za-z0-9_-]`;
at most five entries. Omit it and the run belongs to no group, which is right for a single-tenant deployment.'
additionalProperties: true
type: object
title: PipelexApiExecuteRequest
description: 'Documented body of `POST /execute` — the protocol''s `RunRequest` plus THIS server''s run extensions.
Used only to publish the OpenAPI request schema: `/execute` reads the body through the raw
`Request` (plain JSON, parsed by the route), so FastAPI cannot infer the body type; this model documents the
extensions the route actually honors (`orchestration_mode`, `storage_scope`, `read_scope`, `analytics_groups`,
all parsed by `PipelineApiExtras`).'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PipelexApiExecuteResponse'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'404':
description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
address by manifest identity.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'429':
description: An upstream inference provider rate-limited the run. Passed through from the provider; `Retry-After`
is set when the provider supplied a hint.
headers:
Retry-After:
description: Seconds to wait before retrying, when the upstream provider supplied a hint.
schema:
type: integer
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
since the method''s author changes it.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/start:
post:
tags:
- run
summary: Start
description: 'Start a method run and return its pipeline_run_id with a 202 ack (MTHDS Protocol `POST /start`).
Answers `202 Accepted` with a `StartAck`. A client-supplied `pipeline_run_id` is
honored (the protocol lets an implementation decline it; this runner accepts it, and
`StartAck.pipeline_run_id` is always authoritative). Pipelex domain failures propagate untouched: the global
`PipelexError` handler in `pipelex_api.exception_handlers` turns them into an
RFC 7807 problem response.
Fire-and-forget is a property of THIS endpoint (its delivery axis), honored only by an
async-capable backend. A deployment configures the backend (`orchestration_mode`) once; `/start`
sets `FIRE_AND_FORGET` delivery and checks the resolved orchestrator can honor it. A Temporal
deployment (`orchestration_mode = "temporal"`) enqueues the run and returns immediately with a
`workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default)
the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `501`
(`runtime.unsupported`) — use `/execute` — rather than silently blocking and acking.
The completion callback (`callback_urls` / storage delivery) fires on the async path.'
operationId: start_v1_start_post
requestBody:
content:
application/json:
schema:
$defs:
Base64FileEntry:
properties:
base64:
type: string
title: Base64
description: The file's bytes in canonical padded standard Base64.
additionalProperties: false
type: object
required:
- base64
title: Base64FileEntry
description: A file entry carrying the file's bytes in canonical padded standard Base64.
HashFileEntry:
properties:
sha256:
type: string
pattern: ^[0-9a-f]{64}$
title: Sha256
description: The SHA-256 of the file's bytes, in lowercase hexadecimal.
size:
type: integer
minimum: 0.0
title: Size
description: The file's size in bytes, an integer written with no fraction or exponent.
additionalProperties: false
type: object
required:
- sha256
- size
title: HashFileEntry
description: A file entry naming, by their SHA-256 and their size, bytes the receiver already holds in its
blob store.
StuffContentAbstract:
properties: {}
type: object
title: StuffContentAbstract
properties:
pipe_code:
anyOf:
- type: string
- type: 'null'
title: Pipe Code
mthds_contents:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Mthds Contents
description: 'Being retired, and refused by a later release: send the method in `files`. The method''s `.mthds`
files as raw strings, always an array, even for a single file; with no `pipe_code`, a file must declare
`main_pipe`. Mutually exclusive with `files`, `bundle_b64` and `method_ref`.'
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- items:
type: string
type: array
- $ref: '#/$defs/StuffContentAbstract'
- items:
$ref: '#/$defs/StuffContentAbstract'
type: array
- additionalProperties: true
type: object
type: object
- type: 'null'
title: Inputs
output_name:
anyOf:
- type: string
- type: 'null'
title: Output Name
output_multiplicity:
anyOf:
- type: boolean
- type: integer
- type: 'null'
title: Output Multiplicity
dynamic_output_concept_ref:
anyOf:
- type: string
- type: 'null'
title: Dynamic Output Concept Ref
bundle_b64:
anyOf:
- type: string
- type: 'null'
title: Bundle B64
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — base64-encoded zip of the method''s
folder, read as a map of its entries, so the archive''s names are judged by the method tree''s rule as
the keys of `files` are. The method packages it calls by address may travel with it under `.mthds/methods/<name>/`,
each with its `METHODS.toml`; they are searched before the runner''s installed copies, for this run alone.
Mutually exclusive with `files`. Custom `.py` is only honored on a sandbox-hosted deployment. Being retired
with `mthds_contents`, and refused by a later release: send the method in `files`.'
files:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/$defs/Base64FileEntry'
- $ref: '#/$defs/HashFileEntry'
type: object
- type: 'null'
title: Files
description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels:
each key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment
starting with a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or
`{"sha256": ..., "size": ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing`
then `PUT /v1/blobs/{sha256}`). The map is read from the request''s JSON text: a key given twice, a key
the membership rule keeps out of every tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid`
whose `reason` is the refusal''s code and whose `path` names the first path, a key leaving the tree is
a 422 `security.input_path_refused`, a malformed entry is a 422 `request.invalid`, and hash entries the
runner does not hold are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists every such
hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read, such as
a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom
`.py` is only honored on a sandbox-hosted deployment.'
dependencies:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: string
- $ref: '#/$defs/Base64FileEntry'
- $ref: '#/$defs/HashFileEntry'
type: object
type: object
- type: 'null'
title: Dependencies
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls
by address that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map
of file entries>}`: each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its
root declaring the address it is keyed by. They are searched before the runner''s installed copies, for
this request alone. Accompanies `files`.'
method_ref:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Method Ref
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — run a published method by reference
instead of inline source. Address form: `github.com/<owner>/<repo>[/<selector>][@<tag>]` (e.g. `github.com/Pipelex/methods/[email protected]`)
— resolved by THIS runner: the repository is fetched at the tag (a bare address means the default branch
at HEAD), the package is located by manifest identity, and the resolved commit SHA is recorded as `method_provenance`
on the response. Mutually exclusive with `mthds_contents` and with a method bundle (`bundle_b64` / `files`);
`pipe_code` may accompany it to override the manifest''s `main_pipe`. A package shipping custom Python
is only honored on a sandbox-hosted deployment, and a package declaring Python structure classes is always
refused — hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python.'
resources:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Resources
description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
(an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative
path, exactly as the step names it, to the file''s bytes in standard base64. A path must be relative and
written with forward slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`,
every bundle of the request is read as sitting in one directory, and every file must be named by a step,
or the request is refused with a 422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`,
each file joins the tree at its path from the tree''s root, where a file the tree already holds must have
the same bytes. By default at most 32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment
sets its own with `MAX_RESOURCES_PER_REQUEST`, `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`.
The files make one method tree with the bundles, which the run names by its digest: no file''s bytes travel
with the run, each being read where a step uses it. Being retired with `mthds_contents`, and refused by
a later release: send these files in the method''s tree, in `files`.'
pipeline_run_id:
anyOf:
- type: string
maxLength: 128
- type: 'null'
title: Pipeline Run Id
callback_urls:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Callback Urls
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — completion webhooks. When the run
finishes, the runner POSTs a completion notice to each URL, with an X-Completion-Signature header holding
the HMAC-SHA256 of the run id (not of the body). The body carries `pipeline_run_id`, `state` (with the
legacy `status` alias), `result_url` (the storage key prefix of the stored results, when results were
stored) and `error` on failure; it does not carry the run's output. http/https only; private, loopback,
link-local and cloud-metadata hosts are rejected.
orchestration_mode:
anyOf:
- type: string
- type: 'null'
title: Orchestration Mode
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — request the orchestration mode (the
backend) for this run. An OPEN string token: `direct` (in-process, the base default), `temporal`, and
any other plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery
axis (blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment
sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs
from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
Omit it to use the deployment default.'
storage_scope:
anyOf:
- type: string
- type: 'null'
title: Storage Scope
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every object
this run writes lands under. One to three path-safe segments (e.g. `tenant/run` or `org/method/run`);
the runtime composes its own leaves (`assets/`, `generated/`, `results/`, `payloads/`) onto it and never
interprets the value. Omit it and the run is scoped to the caller's own id, which is correct for a single-tenant
deployment and wrong for a multi-tenant one — a host serving many tenants MUST send this.
read_scope:
anyOf:
- type: string
- type: 'null'
title: Read Scope
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every stored
object this run reads must lie under, and on a scoped run no local path is read at all. One to three path-safe
segments, which must be the `storage_scope` or one of its leading segments, since a run reads back what
it writes. Omit it and the run is scoped to the caller's own id when the deployment identifies callers,
and unscoped when it is single-tenant — a host serving many tenants MUST send this.
analytics_groups:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Analytics Groups
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied groups this run''s
telemetry belongs to, as a mapping of group type to group key (e.g. `{"organization": "org_acme"}`). The
runtime never reads a key by name: it carries the mapping on the run as its `extras` and stamps it on
every span as `pipelex.run.extras`, so every OpenTelemetry exporter receives it, and the deployment''s
own PostHog stream, in `identified` mode, forwards it as the capture''s groups. Group types are lowercase
snake_case starting with a letter, at most 32 characters; group keys are 1 to 128 characters from `[A-Za-z0-9_-]`;
at most five entries. Omit it and the run belongs to no group, which is right for a single-tenant deployment.'
additionalProperties: true
type: object
title: PipelexApiStartRequest
description: 'Documented body of `POST /start` — the protocol''s `StartRequest` plus THIS server''s extensions.
Used only to publish the OpenAPI request schema: the protocol model no
longer advertises implementation extensions, so this server documents the
ones it implements itself. Wire validation happens in `PipelineApiExtras`.'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PipelexApiStartResponse'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'404':
description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
address by manifest identity.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'409':
description: '`pipelex.run.already_exists` — the submitted `pipeline_run_id` is still registered for an in-flight
run. Completed and failed runs free their id, so this only fires for genuinely concurrent duplicates.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
description: '`runtime.unsupported` — this deployment cannot honor fire-and-forget delivery: its orchestrator is
blocking-only, or its async execution is not enabled. Permanent under the current deployment; use `POST /execute`
instead. Or `pipelex.deployment.custom_code_requires_sandbox`, as on `POST /execute`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/validate:
post:
tags:
- validate
summary: Validate Mthds
description: "Validate MTHDS content by parsing, loading, and dry-running pipes (MTHDS Protocol `POST /validate`).\n\
\n`/validate` is a **diagnostic endpoint**: any verdict the validator can produce — valid,\ninvalid, or valid-but-not-runnable\
\ — rides a **200** discriminated in the body on `is_valid`.\nNon-2xx is reserved for the cases where *no verdict\
\ could be produced*.\n\nResponse contract:\n\n- **Valid verdict (200, `is_valid: true`):** the `ValidReport` arm\
\ — the canonical report\n (primary `bundle_blueprint`, `pipe_io_contracts` keyed by namespaced `pipe_ref`, per-pipe\n\
\ `validated_pipes` sweep outcomes, `pending_signatures` + `is_runnable` runnability verdict,\n best-effort `graph_spec`)\
\ plus the wire extras (`mthds_contents` echo, `message`,\n `default_pipe_ref`). The graph is drawn from the pipe\
\ a selector-less run of this request\n would execute: on a `method_ref` request whose manifest names a `main_pipe`,\
\ that pipe;\n otherwise the primary blueprint's `main_pipe`. A bundle that declares no `main_pipe`, with\n no manifest\
\ naming one, validates fine and carries `graph_spec=null`, and so does a\n manifest `main_pipe` the closure does\
\ not resolve. Pending signatures are reported as `pending_signatures` +\n `is_runnable: false`, never as an error.\
\ `default_pipe_ref` names the pipe a selector-less\n run of this same request would execute — on a `method_ref`\
\ request that is the fetched\n manifest's `main_pipe`, which the canonical report cannot see, so the field is the\
\ only\n signal a consumer can project a by-address entry signature from.\n The opt-in `views` tokens `input_form`\
\ and `output_form` additionally attach the per-pipe\n input-form and output-form descriptors as same-named top-level\
\ fields, keyed like\n `pipe_io_contracts`; without a token the matching field is absent and the body is\n byte-identical\
\ to a request that omits `views`. They are separate tokens because they answer\n separate questions — a caller building\
\ a fill-in form wants the inputs, a caller rendering a\n result or registering a tool signature with a return type\
\ wants the output.\n- **Invalid verdict (200, `is_valid: false`):** the `InvalidReport` arm — `errors[]`, one problem\
\ item per\n error with its own code (incl. one located item per pipe whose dry run failed, with the failure's code),\
\ the\n items of the verdict's problem — + `message`, with the structural artifacts absent. The runner\n returns\
\ this as a value (a `BundleValidationFailure` with validation items) regardless of backend — the\n in-process arm\
\ from the bundle's `ValidateBundleError`, the dispatched arm recovered from the\n worker — so the route maps it\
\ to a 200 by matching validation diagnostics, never by catching an\n exception. A returned failure without validation\
\ diagnostics is a backend, configuration or runtime\n fault, and its problem is answered as every raised failure's\
\ is.\n- **Either arm:** a member with no value is absent rather than `null`, at the arm's top level and in its\n\
\ problem items; the structured artifacts of the valid arm keep their own serialization.\n- **No verdict (non-2xx):**\
\ a malformed request body, an `mthds_sources` length mismatch, or\n more or fewer than one of `files` / `method_ref`\
\ / `mthds_contents` is a request-shape **422**, and so is a forbidden\n `orchestration_mode` override; a host-wiring\
\ programmer error or a genuine orchestrator fault is a\n **5xx**; auth is **401/403**. A `method_ref` **resolution\
\ failure** is also a no-verdict condition —\n never an `is_valid: false`: each answers the status its code declares,\
\ such as a **422** for a\n malformed reference, a **502** for a failed fetch, a **404** for no matching package\
\ in the\n repository and a **422** for the method's Python structure classes, and the custom-code sandbox gate\n\
\ a **501**. All are `application/problem+json` documents carrying a registry `code`, rendered by the\n global handlers\
\ in `pipelex_api.exception_handlers` — routes never shape them."
operationId: validate_mthds_v1_validate_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ValidReport'
- $ref: '#/components/schemas/InvalidReport'
title: Response Validate Mthds V1 Validate Post
discriminator:
propertyName: is_valid
mapping:
'True': '#/components/schemas/ValidReport'
'False': '#/components/schemas/InvalidReport'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'404':
description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
address by manifest identity.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
since the method''s author changes it.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/resolve:
post:
tags:
- resolve
summary: Resolve Mthds
description: "Resolve a method into its normalized crate (Pipelex API extension).\n\nResolution is a first-class language\
\ operation alongside validation: read the method's tree\n(`files`, or the package a `method_ref` fetches) exactly\
\ as `/validate` reads it, load + statically\nvalidate it as the caller's own library, and emit the **normalized library\
\ crate** (fully\nqualified refs, refinement flattened, natives materialized, fingerprint set) — the artifact\nshape\
\ the MTHDS standard specifies as the Library Crate Format. It runs no dry-run sweep —\nrunnability is `/validate`'s\
\ vocabulary.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):** the\
\ crate on the valid arm.\n- **Invalid verdict (200, `is_valid: false`):** the library could not be parsed, loaded,\
\ or\n validated — `errors[]`, one problem item per error.\n- **No verdict (non-2xx):** a malformed request body\
\ (neither or both method selectors) is a\n request-shape 422 `request.invalid`; a `files` map that is not a method\
\ tree is a 422\n `method.package_invalid`, and hash entries this runner does not hold a 422\n `request.blobs_missing`;\
\ custom Python on a deployment that is not sandbox-hosted is a 501\n `pipelex.deployment.custom_code_requires_sandbox`,\
\ and a Python structure class a 422\n `pipelex.deployment.python_structures_refused`; a registry-form `method_ref`\
\ is a 422\n `request.unsupported` until server-side method registry resolution exists; auth is 401/403;\n server\
\ fault is 5xx. All `application/problem+json` documents with a registry `code`, via the\n global handlers."
operationId: resolve_mthds_v1_resolve_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MethodTreeRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ResolveValidReport'
- $ref: '#/components/schemas/CrateInvalidReport'
title: Response Resolve Mthds V1 Resolve Post
discriminator:
propertyName: is_valid
mapping:
'True': '#/components/schemas/ResolveValidReport'
'False': '#/components/schemas/CrateInvalidReport'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'404':
description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
address by manifest identity.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
since the method''s author changes it.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
/v1/pipe-io:
post:
tags:
- pipe-io
summary: Pipe Io
description: "Return a method's pipe I/O contracts, input form and output form, with no dry run (Pipelex API extension).\n\
\nThe method is read as `/validate` reads a method tree and resolves through the static core\n`/resolve` rides, a\
\ pipe is selected the way the per-pipe routes select one, and the three\nartifacts are derived with `build_pipe_io_artifacts`,\
\ the builder `/validate` and every run call —\nso a call costs one load and one derivation where `/validate` dry-runs\
\ every pipe.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):** the\
\ three artifact maps keyed by qualified `pipe_ref`,\n beside `pipe_ref`, `default_pipe_ref`, `pending_signatures`,\
\ `is_runnable`, and `files` when\n `include_files` is true.\n- **Invalid verdict (200, `is_valid: false`):** the\
\ closure could not be parsed, loaded, or\n statically validated — the crate verdict, carrying no artifact, no selection\
\ and no files.\n- **No verdict (non-2xx):** a malformed body and neither or both method selectors are\n request-shape\
\ 422s (`request.invalid`); a `files` map that is not a method tree is a 422\n `method.package_invalid`, and hash\
\ entries this runner does not hold a 422\n `request.blobs_missing`, as on `/validate`; custom Python on a deployment\
\ that is not\n sandbox-hosted is a 501 `pipelex.deployment.custom_code_requires_sandbox`, and a Python\n structure\
\ class a 422 `pipelex.deployment.python_structures_refused`; a selection refusal is an\n input 422 named for its\
\ failure, `request.pipe_not_found` for an unknown `pipe_ref` or a\n single-pipe request whose chain finds no entry\
\ pipe, `request.pipe_ambiguous` for an ambiguous\n one or a chain that finds several; the `method_ref` fetch outcomes\
\ are those of `/resolve` (404,\n 422); an artifact that cannot be derived (`PipeIOContractError`) is a 500. All\n\
\ `application/problem+json` documents with a registry `code`, via the global handlers."
operationId: pipe_io_v1_pipe_io_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PipeIORequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/PipeIOValidReport'
- $ref: '#/components/schemas/CrateInvalidReport'
title: Response Pipe Io V1 Pipe Io Post
discriminator:
propertyName: is_valid
mapping:
'True': '#/components/schemas/PipeIOValidReport'
'False': '#/components/schemas/CrateInvalidReport'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'404':
description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
address by manifest identity.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
since the method''s author changes it.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
/v1/codegen:
post:
tags:
- codegen
summary: Codegen Mthds
description: "Generate typed artifacts from a method (Pipelex API extension).\n\nResolves the method to its normalized\
\ crate (exactly like `POST /resolve`), then projects it\nthrough the requested `kind`/`target` axes and returns the\
\ **stamped** artifact set plus its\n`codegen.lock` — everything a client needs to materialize a byte-identical local\
\ projection\nand run the offline drift check. There is deliberately **no** server-side check route: the\ncheck is\
\ offline by design.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):**\
\ the artifacts + lock on the valid arm.\n- **Invalid verdict (200, `is_valid: false`):** the library could not be\
\ parsed, loaded, or\n validated — `errors[]`, one problem item per error; no artifacts exist.\n- **No verdict (non-2xx):**\
\ an unknown projection `kind`/`target`, a `pipe_ref` on a\n concept-set-wide kind, or a malformed method selector\
\ is a request-shape 422 problem+json; the\n method's tree is refused as `/resolve` refuses it (a 422 `method.package_invalid`\
\ or\n `request.blobs_missing`, the Python policy's refusals, the `method_ref` fetch outcomes, a 422\n `request.unsupported`\
\ for a registry-form `method_ref`); auth is 401/403; server fault is 5xx."
operationId: codegen_mthds_v1_codegen_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CodegenRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CodegenValidReport'
- $ref: '#/components/schemas/CrateInvalidReport'
title: Response Codegen Mthds V1 Codegen Post
discriminator:
propertyName: is_valid
mapping:
'True': '#/components/schemas/CodegenValidReport'
'False': '#/components/schemas/CrateInvalidReport'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'404':
description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
address by manifest identity.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'501':
description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
since the method''s author changes it.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
/v1/lint:
post:
tags:
- tools
summary: Lint Mthds
description: 'Lint one .mthds file with the embedded MTHDS schema.
Malformed .mthds content is a produced diagnostic verdict and returns 200.
Request-shape problems remain RFC 7807 422 responses through the global handlers.'
operationId: lint_mthds_v1_lint_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LintRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LintResponse'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
/v1/format:
post:
tags:
- tools
summary: Format Mthds
description: 'Format one .mthds file with the canonical MTHDS formatter.
Syntax errors return 200 with diagnostics and unchanged content. Malformed
formatter options are caller input errors and return a 422 `request.invalid`
naming `options`.'
operationId: format_mthds_v1_format_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FormatRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FormatResponse'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
/v1/models:
get:
tags:
- agent
summary: Get Models
description: 'List the model deck this runner can route to (MTHDS Protocol `GET /models`).
Answers the protocol `ModelDeck` as produced by `PipelexMTHDSProtocol.models` —
the flat `models` list (`{name, type}` entries) plus this implementation''s
category-keyed routing extensions (`aliases`, `waterfalls`). The `type` query
param is a SINGLE protocol `ModelCategory` value: repeated `?type=` values
and unknown categories are both 422 `request.invalid` naming `type`.'
operationId: get_models_v1_models_get
parameters:
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'Filter by model category: llm, extract, img_gen, search, judgment. Single value (protocol arity).'
title: Type
description: 'Filter by model category: llm, extract, img_gen, search, judgment. Single value (protocol arity).'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PipelexModelDeck'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/v1/models/check:
get:
tags:
- agent
summary: Check Model
description: 'Check whether one model reference resolves on this runner, as what, to which model (Pipelex API extension).
Answers from pipelex''s own reference parser and deck lookups, the ones a validation runs, so a
reference found `resolved` in a category is one a pipe of that category may name, and one found
`not_found` is one a validation refuses. A verdict is a `200` whatever the resolution, and on
`not_found` it carries the suggestions a failing validation of the same reference offers. A
request that cannot produce a verdict is an input `422` `request.invalid` naming the parameter: a
missing or repeated `reference`, a repeated `type`, a reference that is blank, a sigil or a namespace
alone, or too long, and an unknown `type`.'
operationId: check_model_v1_models_check_get
parameters:
- name: reference
in: query
required: true
schema:
type: string
description: 'The model reference as a method''s `model` field writes it: `$preset`, `@alias`, `~waterfall`, a bare
model handle, or one of the namespaces `preset:`, `alias:`, `waterfall:` and `handle:`. Surrounding whitespace
is ignored, and the trimmed reference holds at most 199 characters. Single value.'
title: Reference
description: 'The model reference as a method''s `model` field writes it: `$preset`, `@alias`, `~waterfall`, a bare
model handle, or one of the namespaces `preset:`, `alias:`, `waterfall:` and `handle:`. Surrounding whitespace is
ignored, and the trimmed reference holds at most 199 characters. Single value.'
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'The category to check in: llm, extract, img_gen, search, judgment or doc_gen. When absent, the check
is made in every one of them. Single value.'
title: Type
description: 'The category to check in: llm, extract, img_gen, search, judgment or doc_gen. When absent, the check
is made in every one of them. Single value.'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ModelReferenceVerdict'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
/v1/blobs/missing:
post:
tags:
- blobs
summary: Which of these blobs the runner lacks, and where to upload each.
description: 'List every blob of the request this runner does not hold, each with a signed upload target (MTHDS Protocol).
A blob it holds at the stated size is left out, and an empty list means there is nothing to upload; a hash held
at another size than the one stated is listed too, and its upload tells the two cases apart: bytes of the size held
change nothing, and bytes of another size mean the object held is damaged, a 500 `pipelex.storage.damaged`, since
nothing writes over a blob. When the request names the tree the blobs
make up by its `digest`, this runner has recorded that tree as held in full, which it does only after reading every
file of a tree a request sent, and every listed blob is a file of that tree, the answer is an empty list at once.
A hash given twice with different sizes is a 422 `request.invalid` naming `blobs`, and a blob or a set of blobs past
this runner''s tree limits a 422 `method.package_invalid`, both refused before anything is uploaded. Each upload
target is this runner''s own
`PUT /v1/blobs/{sha256}`, at `PUBLIC_BASE_URL` when the deployment sets it, its query signed for that hash and
the caller''s scope, valid for `BLOB_UPLOAD_URL_TTL_SECONDS`, to send with exactly the headers it names.'
operationId: find_missing_blobs_v1_blobs_missing_post
parameters:
- name: read_scope
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: 'PIPELEX-API EXTENSION — the blob store''s scope, as a run''s `read_scope`: a multi-tenant host sends
the one of the organization it serves. Omit it and the caller''s own id is the scope.'
title: Read Scope
description: 'PIPELEX-API EXTENSION — the blob store''s scope, as a run''s `read_scope`: a multi-tenant host sends
the one of the organization it serves. Omit it and the caller''s own id is the scope.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MissingBlobsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MissingBlobsResult'
'401':
description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
or trusts a proxy''s forwarded identity and the proxy forwarded none.'
headers:
WWW-Authenticate:
description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
schema:
type: string
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'413':
description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
both in bytes.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'422':
description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'500':
description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
Report the `request_id`.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
'403':
description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
may read.'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDocument'
x-mthds-protocol: true
/:
get:
tags:
- health
summary: Service identity banner
description: 'Identify the service answering on this origin. No auth required.
A human-facing banner for someone who lands on the bare origin — not a
liveness probe (that is `GET /health`) and not the protocol handshake
(`GET /v1/version`). It reads nothing and can only succeed.'
operationId: root__get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceIdentity'
components:
schemas:
AbsenceKind:
type: string
enum:
- declared_absent
- skipped
- not_provided
title: AbsenceKind
description: "How a slot came to hold no value.\n\n- DECLARED_ABSENT: a producer with an optional (`?`) output declared\
\ it produced nothing\n (e.g. a PipeCondition `continue` outcome, or — phase 2 — an LLM maybe-wrapper), or a binding\n\
\ step's path reached a field holding nothing.\n- SKIPPED: the producing pipe was lifted (skipped) because one of\
\ its plain inputs was absent,\n or a binding step was, because its root was.\n- NOT_PROVIDED: the caller omitted\
\ an optional method input from the pipeline inputs."
AbsenceRecord:
properties:
variable_name:
type: string
title: Variable Name
kind:
$ref: '#/components/schemas/AbsenceKind'
reason:
type: string
title: Reason
producing_pipe:
anyOf:
- type: string
- type: 'null'
title: Producing Pipe
upstream:
anyOf:
- $ref: '#/components/schemas/AbsenceRecord'
- type: 'null'
additionalProperties: false
type: object
required:
- variable_name
- kind
- reason
title: AbsenceRecord
description: 'A recorded fact that a named slot holds no value, with provenance (D2).
Absence stays what it mechanically is — no Stuff under the name — but becomes a recorded
fact: who produced it, why, and which upstream absence it chains to. Provenance is captured
at the moment absence is produced, not reconstructed at failure time.'
AliasMatch:
properties:
category:
$ref: '#/components/schemas/ModelCheckCategory'
description: The category this entry is about.
resolves_to:
anyOf:
- type: string
- type: 'null'
title: Resolves To
description: The model handle a run through the reference would call now in this category, or null when it would
find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
serves, an alias cycle).
target:
type: string
title: Target
description: The model the deck binds the alias to, as the deck writes it, which may itself be a reference.
additionalProperties: false
type: object
required:
- category
- resolves_to
- target
title: AliasMatch
description: What an alias reference is in one category.
AspectRatio:
type: string
enum:
- square
- landscape_4_3
- landscape_3_2
- landscape_16_9
- landscape_21_9
- landscape_4_1
- landscape_8_1
- portrait_3_4
- portrait_2_3
- portrait_9_16
- portrait_9_21
- portrait_1_4
- portrait_1_8
title: AspectRatio
Background:
type: string
enum:
- transparent
- opaque
- auto
title: Background
Base64FileEntry:
properties:
base64:
type: string
title: Base64
description: The file's bytes in canonical padded standard Base64.
additionalProperties: false
type: object
required:
- base64
title: Base64FileEntry
description: A file entry carrying the file's bytes in canonical padded standard Base64.
BindingStepBlueprint:
properties:
from:
type: string
pattern: ^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$
title: From
description: 'The path to bind: a name in working memory followed by zero or more field names, separated by dots.'
result:
type: string
pattern: ^[a-z][a-z0-9_]*$
title: Result
description: 'The name under which the bound value is stored in working memory: a plain input name.'
additionalProperties: false
type: object
required:
- from
- result
title: BindingStepBlueprint
description: 'A PipeSequence step that binds the value at a path in working memory to a new name.
`{ from = "invoice.total", result = "total_amount" }` stores a deep copy of the value at `invoice.total`
under `total_amount`, as the concept the path derives through the declared structures. A binding step
lives in a PipeSequence''s `steps` only, and carries exactly these two fields.'
BlobRef:
properties:
sha256:
type: string
pattern: ^[0-9a-f]{64}$
title: Sha256
description: The SHA-256 of the bytes, in lowercase hexadecimal.
size:
type: integer
minimum: 0.0
title: Size
description: The length of the bytes, a JSON integer written without a fraction or an exponent. A size written 13.0
is refused, although JSON Schema's integer type admits it.
additionalProperties: false
type: object
required:
- sha256
- size
title: BlobRef
description: A blob, named by its SHA-256 in lowercase hexadecimal and its length in bytes.
BlockedEntry:
properties:
entry_id:
type: string
title: Entry Id
to_schema_version:
type: integer
title: To Schema Version
reason:
$ref: '#/components/schemas/BlockedEntryReason'
detail:
type: string
title: Detail
guidance:
anyOf:
- type: string
- type: 'null'
title: Guidance
applied_ops:
items:
oneOf:
- $ref: '#/components/schemas/DeleteKeyOp'
- $ref: '#/components/schemas/DeleteTableOp'
- $ref: '#/components/schemas/RenameTableKeyOp'
- $ref: '#/components/schemas/MoveKeyOp'
- $ref: '#/components/schemas/RemapValueOp'
discriminator:
propertyName: kind
mapping:
delete_key: '#/components/schemas/DeleteKeyOp'
delete_table: '#/components/schemas/DeleteTableOp'
move_key: '#/components/schemas/MoveKeyOp'
remap_value: '#/components/schemas/RemapValueOp'
rename_table_key: '#/components/schemas/RenameTableKeyOp'
type: array
title: Applied Ops
narrowed_paths:
items:
type: string
type: array
title: Narrowed Paths
additionalProperties: false
type: object
required:
- entry_id
- to_schema_version
- reason
- detail
title: BlockedEntry
description: An entry that this file needs and the run would not apply.
BlockedEntryReason:
type: string
enum:
- unsafe
- conflict
- value_domain_narrowed
title: BlockedEntryReason
description: Why an entry could not be applied to this file.
BooleanField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: boolean
title: Kind
default: boolean
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- name
title: BooleanField
description: '`boolean` at a named position.'
BooleanItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: boolean
title: Kind
default: boolean
additionalProperties: false
type: object
required:
- required
title: BooleanItem
description: '`boolean` — true or false.'
CodegenRequest:
properties:
files:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
- type: 'null'
title: Files
description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
type: object
- type: 'null'
title: Dependencies
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
method_ref:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Method Ref
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
until a method registry exists). Exactly one of `files` / `method_ref`.
resources:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Resources
description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
(an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
`MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
retired, and refused by a later release: a file the steps read travels inside the method''s tree, in `files`,
at its path beside the bundle that names it.'
read_scope:
anyOf:
- type: string
- type: 'null'
title: Read Scope
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the request reads the method under,
as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files`
resolves in that scope''s blob store, and the tree the request read is recorded there, so a later request can
send it by hash. Omit it and a hash entry resolves in the caller''s own id''s store, and nothing is recorded.'
kind:
$ref: '#/components/schemas/CodegenRouteKind'
description: What to project. `types` projects the crate's concept set into typed models.
target:
$ref: '#/components/schemas/CodegenTarget'
description: 'For whom: `ts-zod` (zod schemas + inferred types), `python-pydantic` (self-contained BaseModels),
or `python-structures` (runtime StructuredContent classes, for a Pipelex host).'
pipe_ref:
anyOf:
- type: string
maxLength: 512
- type: 'null'
title: Pipe Ref
description: Pipe selector for per-pipe projection kinds. Not accepted for `types` (a concept-set-wide projection).
type: object
required:
- kind
- target
title: CodegenRequest
description: 'The codegen request: the crate routes'' method selector plus the two explicit projection axes.'
CodegenRouteKind:
type: string
enum:
- types
title: CodegenRouteKind
description: 'The projection kinds this route serves — the `kind` axis of the codegen request.
Membership follows the **trust chain**: a kind is served here exactly when its artifacts are
stamped and locked, so a client can write them verbatim and pass the offline `codegen check` —
the promise this route''s valid arm makes by carrying a `lock`. Input templates are user-editable
scaffolds, never stamped or locked, so they cannot make that promise: a client projects one from
the input form `POST /pipe-io` serves, and `inputs` is therefore not a kind here. Future per-pipe kinds
(`docs`, `tools`, `tests`) do emit tracked artifacts, so they join this enum and select their
pipe via `pipe_ref`. An unknown kind is a request-shape 422 listing the served set.'
CodegenTarget:
type: string
enum:
- python-structures
- python-pydantic
- ts-zod
title: CodegenTarget
description: 'A codegen target flavor. All targets are Pipelex projections — the MTHDS standard specifies no
type projection (see the codegen spec → "Ownership"). They differ in audience:
`ts-zod` and `python-pydantic` emit idiom-neutral types any consumer can use; `python-structures`
emits StructuredContent classes for a Pipelex runtime host.'
CodegenValidReport:
properties:
is_valid:
type: boolean
const: true
title: Is Valid
default: true
kind:
$ref: '#/components/schemas/CodegenRouteKind'
description: The projected kind (echo of the request).
target:
$ref: '#/components/schemas/CodegenTarget'
description: The projection target (echo of the request).
crate_fingerprint:
type: string
title: Crate Fingerprint
description: Fingerprint of the normalized crate the artifacts were generated from.
engine_version:
type: string
title: Engine Version
description: The pipelex engine version that generated the artifacts.
artifacts:
items:
$ref: '#/components/schemas/GeneratedArtifact'
type: array
title: Artifacts
description: The stamped generated files.
lock:
type: string
title: Lock
description: The `codegen.lock` content (TOML) tracking the artifact set — write verbatim beside the artifacts.
lock_filename:
type: string
title: Lock Filename
description: Filename the lock content must be written as.
default: codegen.lock
message:
type: string
title: Message
description: Status message
default: Codegen artifacts generated successfully
type: object
required:
- kind
- target
- crate_fingerprint
- engine_version
- lock
title: CodegenValidReport
description: 'The 200 **valid** arm: the stamped artifact set plus its lock.
A client that writes each artifact and the lock verbatim reproduces a local
`pipelex codegen types` run byte-for-byte — the same stamps, the same `codegen.lock` — so the
offline `codegen check` passes on the written tree exactly as it would locally.'
Concept:
properties:
code:
type: string
title: Code
domain_code:
type: string
title: Domain Code
description:
type: string
title: Description
structure_class_name:
type: string
title: Structure Class Name
refines:
anyOf:
- type: string
- type: 'null'
title: Refines
additionalProperties: false
type: object
required:
- code
- domain_code
- description
- structure_class_name
title: Concept
description: 'A concept as the runtime holds it in memory: its name and its definition.
The protocol model, `ConceptAbstract`, is a name and nothing more — `code`, `domain_code`
and the `concept_ref` they form — because the standard keeps a concept''s definition in the
library a method loads, never beside a stuff. The runtime needs the definition in memory to
resolve a structure class, check compatibility and render a representation, so it declares
those fields here, on its own subclass.
The fields declared here never travel beside a stuff: `StuffAbstract` serializes `concept`
as the ref string, so every dump of a `Stuff`, of a `WorkingMemory` and of a `PipeOutput`
carries `{"concept": "<domain>.<Code>", "content": …}`. A reader of such a dump resolves the
ref through the concept library the method loads, the way the input side does.'
ConceptBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
description:
type: string
title: Description
structure:
anyOf:
- type: string
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/ConceptStructureBlueprint'
type: object
- type: 'null'
title: Structure
refines:
anyOf:
- type: string
- type: 'null'
title: Refines
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
additionalProperties: false
type: object
required:
- description
title: ConceptBlueprint
ConceptStructureBlueprint:
properties:
description:
type: string
title: Description
type:
anyOf:
- $ref: '#/components/schemas/ConceptStructureBlueprintFieldType'
- type: 'null'
key_type:
anyOf:
- type: string
- type: 'null'
title: Key Type
value_type:
anyOf:
- type: string
- type: 'null'
title: Value Type
item_type:
anyOf:
- type: string
- type: 'null'
title: Item Type
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
item_concept_ref:
anyOf:
- type: string
- type: 'null'
title: Item Concept Ref
choices:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Choices
default_value:
anyOf:
- {}
- type: 'null'
title: Default Value
required:
type: boolean
title: Required
default: false
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
additionalProperties: false
type: object
required:
- description
title: ConceptStructureBlueprint
description: 'One field of a concept''s structure table. Unknown keys are rejected — the field table''s
keys are strict, exactly like an input slot table''s; hint *content* stays lenient (unknown
hint keys warn and are preserved, per intent-hints.md).'
ConceptStructureBlueprintFieldType:
type: string
enum:
- text
- list
- dict
- integer
- boolean
- number
- date
- datetime
- time
- concept
title: ConceptStructureBlueprintFieldType
ConstructBlueprint:
properties:
fields:
additionalProperties:
$ref: '#/components/schemas/ConstructFieldBlueprint'
type: object
title: Fields
additionalProperties: false
type: object
required:
- fields
title: ConstructBlueprint
description: "Blueprint for composing a StructuredContent from working memory.\n\nParsed from `[pipe.name.construct]`\
\ section in MTHDS files.\n\nAttributes:\n fields: Dictionary mapping field names to their composition blueprints"
ConstructFieldBlueprint:
properties:
method:
$ref: '#/components/schemas/ConstructFieldMethod'
fixed_value:
anyOf:
- {}
- type: 'null'
title: Fixed Value
from_path:
anyOf:
- type: string
- type: 'null'
title: From Path
template:
anyOf:
- type: string
- type: 'null'
title: Template
nested:
anyOf:
- $ref: '#/components/schemas/ConstructBlueprint'
- type: 'null'
list_to_dict_keyed_by:
anyOf:
- type: string
- type: 'null'
title: List To Dict Keyed By
additionalProperties: false
type: object
required:
- method
title: ConstructFieldBlueprint
description: "Blueprint for composing a single field in a StructuredContent.\n\nDefines how a field value is composed\
\ using one of 4 methods:\n1. Fixed value: literal string, number, bool, or list\n2. Variable reference (from): path\
\ to variable in working memory\n3. Template: Jinja2 template string (with $ preprocessing)\n4. Nested construct:\
\ recursive ConstructBlueprint\n\nAttributes:\n method: The composition method to use\n fixed_value: Literal\
\ value (for FIXED method)\n from_path: Variable path in working memory (for FROM_VAR method)\n template: Jinja2\
\ template string (for TEMPLATE method)\n nested: Nested ConstructBlueprint (for NESTED method)\n list_to_dict_keyed_by:\
\ Optional modifier for FROM_VAR method that converts\n a ListContent/list to dict keyed by the specified attribute\
\ name"
ConstructFieldMethod:
type: string
enum:
- fixed
- from_var
- template
- nested
title: ConstructFieldMethod
description: Method used to compose a field value.
CrateInvalidReport:
properties:
is_valid:
type: boolean
const: false
title: Is Valid
default: false
errors:
items:
$ref: '#/components/schemas/ProblemItem'
type: array
title: Errors
description: One problem item per error, each with its own code, its parameters and its location — non-empty on
every invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them.
message:
type: string
title: Message
description: Human-readable summary of the verdict.
default: MTHDS library could not be resolved
type: object
title: CrateInvalidReport
description: 'The 200 **invalid** arm shared by `/resolve`, `/codegen` and `/pipe-io` — the crate-verdict vocabulary.
Same discipline as `/validate`''s `InvalidReport`: an invalid library is the *successful
product* of a diagnostic call (the request was well-formed; the library was not), so it rides
a 200 discriminated on `is_valid`, carrying the same problem items in `errors` that `/validate`
emits for the identical failure.'
DateField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: date
title: Kind
default: date
datetime:
type: boolean
title: Datetime
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- datetime
- name
title: DateField
description: '`date` at a named position.'
DateItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: date
title: Kind
default: date
datetime:
type: boolean
title: Datetime
additionalProperties: false
type: object
required:
- required
- datetime
title: DateItem
description: '`date` — a calendar date, or a point in time.'
DeleteKeyOp:
properties:
table_path:
items:
type: string
type: array
title: Table Path
kind:
type: string
const: delete_key
title: Kind
default: delete_key
key:
type: string
title: Key
additionalProperties: false
type: object
required:
- table_path
- key
title: DeleteKeyOp
description: Drop ``key`` from the addressed table.
DeleteTableOp:
properties:
table_path:
items:
type: string
type: array
minItems: 1
title: Table Path
kind:
type: string
const: delete_table
title: Kind
default: delete_table
additionalProperties: false
type: object
required:
- table_path
title: DeleteTableOp
description: 'Drop the addressed table, including every chunk of one written out of order.
``table_path`` *is* the target rather than its parent, so it cannot be empty — deleting the
document root is not a thing an op may express.'
Diagnostic:
properties:
kind:
type: string
enum:
- syntax
- semantic
- schema
title: Kind
severity:
type: string
title: Severity
message:
type: string
title: Message
location:
anyOf:
- type: string
- type: 'null'
title: Location
range:
anyOf:
- $ref: '#/components/schemas/Range'
- type: 'null'
type: object
required:
- kind
- severity
- message
- location
- range
title: Diagnostic
description: Structured lint/format diagnostic returned by `pipelex-tools-py`.
DiagnosticCause:
properties:
error_class:
type: string
title: Error Class
code:
anyOf:
- type: string
- type: 'null'
title: Code
additionalProperties: true
type: object
required:
- error_class
title: DiagnosticCause
description: One error of a failure's cause chain, by its class and the code it carries by itself.
DocGenFormat:
type: string
enum:
- pdf
- xlsx
- docx
- pptx
title: DocGenFormat
description: 'The file formats a `PipeDocGen` step can ask for.
The tokens are MTHDS: a method names one, and it loads wherever the standard is read. Which of them a
runtime prints depends on the document engines installed in it, each a model of the `doc_gen` family:
open Pipelex prints a `pdf` laid out without a template, on `reportlab-pdf`, and the Pipelex document
generation plugin prints the rest. HTML is not a format: `PipeCompose` already produces the native
`Html`.'
DocGenSetting:
properties:
model:
type: string
title: Model
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
required:
- model
title: DocGenSetting
description: 'The document engine a `PipeDocGen` step prints with: a model of the `doc_gen` family, such as `reportlab-pdf`.'
DocumentField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: document
title: Kind
default: document
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- name
title: DocumentField
description: '`document` at a named position.'
DocumentItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: document
title: Kind
default: document
additionalProperties: false
type: object
required:
- required
title: DocumentItem
description: '`document` — a document supplied as a file or a URL.
No accept-list and no upload affordance: what the value is rides `concept_ref` and `refines`,
and how a renderer offers a file is the renderer''s decision.'
DryRunStatus:
type: string
enum:
- SUCCESS
- FAILURE
- SKIPPED
title: DryRunStatus
EdgeKind:
type: string
enum:
- control
- data
- contains
- selected_outcome
- batch_item
- batch_aggregate
- parallel_combine
title: EdgeKind
description: Types of edges in the execution graph.
EdgeSpec:
properties:
id:
type: string
title: Id
source:
type: string
title: Source
target:
type: string
title: Target
kind:
$ref: '#/components/schemas/EdgeKind'
optional:
type: boolean
title: Optional
default: false
label:
anyOf:
- type: string
- type: 'null'
title: Label
source_stuff_digest:
anyOf:
- type: string
- type: 'null'
title: Source Stuff Digest
target_stuff_digest:
anyOf:
- type: string
- type: 'null'
title: Target Stuff Digest
meta:
additionalProperties: true
type: object
title: Meta
additionalProperties: false
type: object
required:
- id
- source
- target
- kind
title: EdgeSpec
description: Specification for an edge in the execution graph.
ElaborationMetadata:
properties:
parent_pipe_code:
type: string
title: Parent Pipe Code
step_role:
$ref: '#/components/schemas/StepRole'
type: object
required:
- parent_pipe_code
- step_role
title: ElaborationMetadata
description: Side-table entry recording how a synthetic pipe was generated by the bundle elaborator.
EnumField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: enum
title: Kind
default: enum
choices:
items:
type: string
type: array
title: Choices
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- choices
- name
title: EnumField
description: '`enum` at a named position.'
EnumItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: enum
title: Kind
default: enum
choices:
items:
type: string
type: array
title: Choices
additionalProperties: false
type: object
required:
- required
- choices
title: EnumItem
description: '`enum` — one of a fixed set of values.'
ExtractSetting:
properties:
model:
type: string
title: Model
max_nb_images:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Max Nb Images
image_min_size:
anyOf:
- type: integer
minimum: 0.0
- type: 'null'
title: Image Min Size
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
required:
- model
title: ExtractSetting
FileBlockedReason:
type: string
enum:
- unreadable
- unparseable
- unsupported_schema_version
- unwritable
- changed_during_run
- needs_a_hand_edit
- state_uncertain
title: FileBlockedReason
description: 'Why a file could not be processed at all.
One member per *state the file is in*, because that is what decides what the user does next —
not one per exception the run happened to catch. Every member but `STATE_UNCERTAIN` leaves the
file exactly as it was found; that one does not, and it says so.'
FormatRequest:
properties:
content:
type: string
title: Content
description: Single .mthds file content to lint or format.
options:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Options
description: Optional formatter options passed through to `pipelex_tools.format_mthds`, such as `column_width`.
Malformed option values return a 422 problem response.
type: object
required:
- content
title: FormatRequest
description: Body of `POST /format`.
FormatResponse:
properties:
formatted:
type: string
title: Formatted
changed:
type: boolean
title: Changed
diagnostics:
items:
$ref: '#/components/schemas/Diagnostic'
type: array
title: Diagnostics
type: object
required:
- formatted
- changed
- diagnostics
title: FormatResponse
description: Response body of `POST /format`.
GeneratedArtifact:
properties:
path:
type: string
title: Path
description: Artifact path, relative to the output root the client writes into.
content:
type: string
title: Content
description: Complete file content, stamp header included — write verbatim.
type: object
required:
- path
- content
title: GeneratedArtifact
description: 'One generated file: its path relative to the client''s chosen output root, and its full content.'
GraphSpec:
properties:
graph_id:
type: string
title: Graph Id
created_at:
type: string
format: date-time
title: Created At
pipeline_ref:
$ref: '#/components/schemas/PipelineRef'
nodes:
items:
$ref: '#/components/schemas/NodeSpec'
type: array
title: Nodes
edges:
items:
$ref: '#/components/schemas/EdgeSpec'
type: array
title: Edges
usage:
anyOf:
- $ref: '#/components/schemas/GraphUsageSpec'
- type: 'null'
meta:
additionalProperties: true
type: object
title: Meta
pipe_registry:
additionalProperties:
additionalProperties: true
type: object
type: object
title: Pipe Registry
concept_registry:
additionalProperties:
additionalProperties: true
type: object
type: object
title: Concept Registry
additionalProperties: false
type: object
required:
- graph_id
- created_at
title: GraphSpec
description: 'The canonical specification for a pipeline execution graph.
This is the top-level model representing a complete run graph.
It is versioned and designed for JSON serialization.'
GraphUsageSpec:
properties:
total:
$ref: '#/components/schemas/NodeUsageSpec'
unattributed:
$ref: '#/components/schemas/NodeUsageSpec'
additionalProperties: false
type: object
required:
- total
- unattributed
title: GraphUsageSpec
description: 'Run-level inference usage for a whole GraphSpec.
``total`` covers every usage the run reported, attributed or not — it is the graph''s
comparand for the cost report''s own total. ``unattributed`` is the part that named no
live node (the ``UNATTRIBUTED_NODE_ID`` fallback, or a node that never emitted a
start event): surfaced as its own bucket rather than dropped, so the graph''s total
can never silently disagree with the cost report''s.
Both reuse ``NodeUsageSpec`` — one usage shape in the contract, not two. Neither has
a subtree distinct from itself, so their ``subtree_*`` fields repeat their own.'
HandleMatch:
properties:
category:
$ref: '#/components/schemas/ModelCheckCategory'
description: The category this entry is about.
resolves_to:
anyOf:
- type: string
- type: 'null'
title: Resolves To
description: The model handle a run through the reference would call now in this category, or null when it would
find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
serves, an alias cycle).
via:
items:
type: string
type: array
title: Via
description: The presets, aliases and waterfalls of this category whose binding names the handle directly, each
written as a reference.
additionalProperties: false
type: object
required:
- category
- resolves_to
- via
title: HandleMatch
description: What a bare handle reference is in one category.
HashFileEntry:
properties:
sha256:
type: string
pattern: ^[0-9a-f]{64}$
title: Sha256
description: The SHA-256 of the file's bytes, in lowercase hexadecimal.
size:
type: integer
minimum: 0.0
title: Size
description: The file's size in bytes, an integer written with no fraction or exponent.
additionalProperties: false
type: object
required:
- sha256
- size
title: HashFileEntry
description: A file entry naming, by their SHA-256 and their size, bytes the receiver already holds in its blob store.
HealthResponse:
properties:
status:
type: string
title: Status
description: Always `ok` — the endpoint answers only when the process is serving.
message:
type: string
title: Message
description: Human-readable confirmation that the server is up.
type: object
required:
- status
- message
title: HealthResponse
description: Body of `GET /health`.
IOMultiplicity:
type: string
enum:
- single
- variable
- fixed
title: IOMultiplicity
description: 'How many items a slot takes or a pipe resolves to: one item, a variable-length list, or a fixed count.
Read together with `item_count`, which is non-null exactly on the `fixed` arm. `Concept[1]`
is `single` — one item, no list framing — because the language says so, so a `fixed` count on
this wire is always greater than one.'
IOSpec:
properties:
name:
type: string
title: Name
concept:
anyOf:
- type: string
- type: 'null'
title: Concept
content_type:
anyOf:
- type: string
- type: 'null'
title: Content Type
preview:
anyOf:
- type: string
- type: 'null'
title: Preview
size:
anyOf:
- type: integer
- type: 'null'
title: Size
digest:
anyOf:
- type: string
- type: 'null'
title: Digest
data:
anyOf:
- type: string
- additionalProperties: true
type: object
- items:
type: string
type: array
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Data
multiplicity:
anyOf:
- type: boolean
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Multiplicity
extra:
additionalProperties: true
type: object
title: Extra
additionalProperties: false
type: object
required:
- name
title: IOSpec
description: 'Specification for an input or output variable.
Previews are automatically truncated to MAX_PREVIEW_LENGTH to prevent
accidental storage of large payloads or sensitive data.
The optional `data` field can hold the full serialized content when
full data capture is enabled (via --graph-full-data CLI option).
`concept` is always the bare concept code; whether the stuff is a list is `multiplicity`,
in the encoding the pipe registry uses for a stuff spec''s multiplicity: `True` for a
variable-length list, a positive integer for a fixed count, `None` (or `False`) for a single
value, a count of one reading as single. A reader takes absence as single.'
ImageField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: image
title: Kind
default: image
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- name
title: ImageField
description: '`image` at a named position.'
ImageFormat:
type: string
enum:
- png
- jpeg
- webp
title: ImageFormat
ImageItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: image
title: Kind
default: image
additionalProperties: false
type: object
required:
- required
title: ImageItem
description: '`image` — an image, which a renderer may preview.'
ImageSize:
properties:
width:
type: integer
exclusiveMinimum: 0.0
title: Width
height:
type: integer
exclusiveMinimum: 0.0
title: Height
type: object
required:
- width
- height
title: ImageSize
ImgGenSetting:
properties:
model:
type: string
title: Model
quality:
anyOf:
- $ref: '#/components/schemas/Quality'
- type: 'null'
nb_steps:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Nb Steps
guidance_scale:
anyOf:
- type: number
exclusiveMinimum: 0.0
- type: 'null'
title: Guidance Scale
is_moderated:
anyOf:
- type: boolean
- type: 'null'
title: Is Moderated
safety_tolerance:
anyOf:
- type: integer
maximum: 6.0
minimum: 1.0
- type: 'null'
title: Safety Tolerance
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
required:
- model
title: ImgGenSetting
InputSlotBlueprint:
properties:
concept:
type: string
title: Concept
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
additionalProperties: false
type: object
required:
- concept
title: InputSlotBlueprint
description: 'The expanded input-slot form: `name = { concept = "…", hints = { … } }` (spec: intent-hints.md).
`concept` carries the full slot grammar of the string form (ref, optional multiplicity, optional
presence marker). The form is deliberately closed (`extra="forbid"` implements the spec''s
"unknown slot-table keys MUST be rejected") so future per-slot semantic keys land here without a
second syntax. A slot table carrying no hints collapses to its plain string at parse time (see
`PipeBlueprint.collapse_hint_free_slot_tables`), so a slot value that IS a table carries
non-empty hints — hint-free bundles produce byte-identical blueprints to the string form.'
InvalidReport:
properties:
is_valid:
type: boolean
const: false
title: Is Valid
default: false
errors:
items:
$ref: '#/components/schemas/ProblemItem'
type: array
title: Errors
description: One problem item per error, each with its own code, its parameters and its location — non-empty on
every invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them.
pending_signatures:
items:
type: string
type: array
title: Pending Signatures
description: Best-effort outstanding signatures; empty on the invalid arm since no library was assembled.
is_runnable:
type: boolean
const: false
title: Is Runnable
default: false
message:
type: string
title: Message
description: Human-readable summary of the verdict.
default: MTHDS validation found errors
rendered_markdown:
anyOf:
- type: string
- type: 'null'
title: Rendered Markdown
description: 'Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the invalid verdict''s errors,
present only when the request''s `render` includes `markdown`. Absent by default.'
type: object
title: InvalidReport
description: 'The 200 **invalid** arm: a produced "invalid" verdict, discriminated on `is_valid: false`.
An invalid bundle is the *successful product* of a diagnostic call, not a transport failure
(the request was well-formed; the bundle was not), so it rides a **200** — the global
`problem+json` 422/5xx is reserved for the no-verdict conditions (malformed request body,
`mthds_sources` length mismatch, auth, server fault). The structural artifacts
(`bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`) do not exist when
load/parse/wiring failed, so this arm omits them and carries only the per-error diagnostics,
as the problem items of the verdict''s problem (`errors`), plus the runnability facts. The
`input_form` and `output_form` views follow them into absence for the same reason — both derive
from a crate that was never assembled — so neither is declared here and `views` has no effect
on this arm (unlike `rendered_markdown`, which rides both arms because failure
text is exactly what a human surface wants).'
JudgeQuestionBlueprint:
properties:
question:
type: string
title: Question
options:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Options
levels:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/JudgeRatingLevel'
type: array
- type: 'null'
title: Levels
criteria:
anyOf:
- $ref: '#/components/schemas/JudgeYesNoCriteria'
- type: 'null'
threshold:
anyOf:
- type: number
- type: 'null'
title: Threshold
additionalProperties: false
type: object
required:
- question
title: JudgeQuestionBlueprint
description: 'One question of a PipeJudge asking several: what it asks, and the fields the single form sets on the pipe.
Closed, as the standard requires: `question` is the instruction, a plain text template, and the kind
is decided by which of `options` and `levels` the question declares, under the single form''s rules,
which `PipeJudgeBlueprint` checks, since a refusal names the question and only its key in `questions`
does. That key also names the output field holding its verdict.'
JudgeRatingLevel:
properties:
label:
anyOf:
- type: string
- type: 'null'
title: Label
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
title: JudgeRatingLevel
description: 'A rating level written as a table: a `label` naming it in a few words, a `description` of the situation
it stands for, or both.
Closed, as the standard requires. A level written as a plain string is its description.'
JudgeYesNoCriteria:
properties:
'yes':
type: string
title: 'Yes'
'no':
type: string
title: 'No'
additionalProperties: false
type: object
required:
- 'yes'
- 'no'
title: JudgeYesNoCriteria
description: 'What a yes and a no mean, for a yes/no question: both sides, each non-empty. Closed: a key other than
`yes` or `no` is refused.
The judging vendors silently ignore a criterion key they do not know, so this model is the only
place a typo in one is caught. Both sides are required because a lone side cannot be carried with
its meaning on every backend: one sends a single criterion as one of a pair of options, where the
side left out would be a blank.'
JudgmentSetting:
properties:
model:
type: string
title: Model
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
required:
- model
title: JudgmentSetting
LLMSetting:
properties:
model:
type: string
title: Model
temperature:
type: number
maximum: 1.0
minimum: 0.0
title: Temperature
max_tokens:
anyOf:
- type: integer
- enum:
- auto
- type: 'null'
title: Max Tokens
image_detail:
anyOf:
- $ref: '#/components/schemas/PromptImageDetail'
- type: 'null'
reasoning_effort:
anyOf:
- $ref: '#/components/schemas/ReasoningEffort'
- type: 'null'
reasoning_budget:
anyOf:
- type: integer
exclusiveMinimum: 0.0
- type: 'null'
title: Reasoning Budget
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
required:
- model
- temperature
title: LLMSetting
LiftablePipeEntry:
properties:
pipe_ref:
type: string
title: Pipe Ref
within_pipe_ref:
type: string
title: Within Pipe Ref
skipped_when_absent:
items:
type: string
type: array
title: Skipped When Absent
absence_source:
type: string
title: Absence Source
type: object
required:
- pipe_ref
- within_pipe_ref
- absence_source
title: LiftablePipeEntry
description: One pipe that may be skipped (lifted) when an optional slot resolves absent.
LintRequest:
properties:
content:
type: string
title: Content
description: Single .mthds file content to lint or format.
source:
anyOf:
- type: string
- type: 'null'
title: Source
description: Optional logical filename for the content. Accepted for parity with `pipelex_tools.lint_mthds`; current
diagnostics do not yet include the filename.
type: object
required:
- content
title: LintRequest
description: Body of `POST /lint`.
LintResponse:
properties:
diagnostics:
items:
$ref: '#/components/schemas/Diagnostic'
type: array
title: Diagnostics
type: object
required:
- diagnostics
title: LintResponse
description: Response body of `POST /lint`.
ListField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: list
title: Kind
default: list
item:
oneOf:
- $ref: '#/components/schemas/TextItem'
- $ref: '#/components/schemas/ProseItem'
- $ref: '#/components/schemas/DateItem'
- $ref: '#/components/schemas/NumberItem'
- $ref: '#/components/schemas/BooleanItem'
- $ref: '#/components/schemas/EnumItem'
- $ref: '#/components/schemas/DocumentItem'
- $ref: '#/components/schemas/ImageItem'
- $ref: '#/components/schemas/ObjectItem'
- $ref: '#/components/schemas/ListItem'
- $ref: '#/components/schemas/UnknownItem'
title: Item
discriminator:
propertyName: kind
mapping:
boolean: '#/components/schemas/BooleanItem'
date: '#/components/schemas/DateItem'
document: '#/components/schemas/DocumentItem'
enum: '#/components/schemas/EnumItem'
image: '#/components/schemas/ImageItem'
list: '#/components/schemas/ListItem'
number: '#/components/schemas/NumberItem'
object: '#/components/schemas/ObjectItem'
prose: '#/components/schemas/ProseItem'
text: '#/components/schemas/TextItem'
unknown: '#/components/schemas/UnknownItem'
item_count:
anyOf:
- type: integer
- type: 'null'
title: Item Count
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- item
- name
title: ListField
description: '`list` at a named position, recursing through a nameless `item`.'
ListItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: list
title: Kind
default: list
item:
oneOf:
- $ref: '#/components/schemas/TextItem'
- $ref: '#/components/schemas/ProseItem'
- $ref: '#/components/schemas/DateItem'
- $ref: '#/components/schemas/NumberItem'
- $ref: '#/components/schemas/BooleanItem'
- $ref: '#/components/schemas/EnumItem'
- $ref: '#/components/schemas/DocumentItem'
- $ref: '#/components/schemas/ImageItem'
- $ref: '#/components/schemas/ObjectItem'
- $ref: '#/components/schemas/ListItem'
- $ref: '#/components/schemas/UnknownItem'
title: Item
discriminator:
propertyName: kind
mapping:
boolean: '#/components/schemas/BooleanItem'
date: '#/components/schemas/DateItem'
document: '#/components/schemas/DocumentItem'
enum: '#/components/schemas/EnumItem'
image: '#/components/schemas/ImageItem'
list: '#/components/schemas/ListItem'
number: '#/components/schemas/NumberItem'
object: '#/components/schemas/ObjectItem'
prose: '#/components/schemas/ProseItem'
text: '#/components/schemas/TextItem'
unknown: '#/components/schemas/UnknownItem'
item_count:
anyOf:
- type: integer
- type: 'null'
title: Item Count
additionalProperties: false
type: object
required:
- required
- item
title: ListItem
description: '`list` — an array of one element type, recursing through its `item`.
An input slot authored `Concept[]` is a `list` with no `item_count`; one authored `Concept[N]`
carries `item_count: N`. `Concept[1]` is single — no list framing — so a stated count is always
at least 2. `concept_ref` and `refines` name the element concept, and the `item` carries the
same `concept_ref`; on a plural node the merged `hints` ride both the list and its item.'
MethodProvenance:
properties:
address:
type: string
title: Address
tag:
anyOf:
- type: string
- type: 'null'
title: Tag
commit_sha:
type: string
title: Commit Sha
tree_digest:
anyOf:
- type: string
- type: 'null'
title: Tree Digest
description: The digest of the package's method tree, `sha256:` and 64 lowercase hex characters, as read from the
commit's git objects, set by a runner that reads the package as a tree, and null otherwise.
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
description: The package's human-readable name, the `display_name` its `METHODS.toml` manifest declares at the fetched
commit, for a host to name the run's method by, and null when the manifest declares none.
type: object
required:
- address
- commit_sha
title: MethodProvenance
description: 'What a fetched-method run must record: address, tag, the resolved commit SHA, and the name the package
declares.'
MethodTreeRequest:
properties:
files:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
- type: 'null'
title: Files
description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
type: object
- type: 'null'
title: Dependencies
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
method_ref:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Method Ref
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
until a method registry exists). Exactly one of `files` / `method_ref`.
resources:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Resources
description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
(an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
`MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
retired, and refused by a later release: a file the steps read travels inside the method''s tree, in `files`,
at its path beside the bundle that names it.'
read_scope:
anyOf:
- type: string
- type: 'null'
title: Read Scope
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the request reads the method under,
as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files`
resolves in that scope''s blob store, and the tree the request read is recorded there, so a later request can
send it by hash. Omit it and a hash entry resolves in the caller''s own id''s store, and nothing is recorded.'
type: object
title: MethodTreeRequest
description: 'The method selector of the crate routes (`/resolve`, `/codegen`, `/pipe-io`): a tree sent in `files` XOR
a `method_ref`.
Exactly one of the two must be provided — both or neither is a request-shape 422. The tree is the MTHDS standard''s
map of file entries, read from the request''s raw JSON text exactly as `/validate` and the run routes read it
(`pipelex_api.method_tree_request`), with the `dependencies` it carries and the `resources` that join it. An
**address-form** `method_ref` (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is resolved by this server through
the run routes'' fetch path: the package''s tree is read from its commit''s git objects, with the packages it ships
under `.mthds/methods/`. The **registry form** (any non-address reference) stays reserved, a 422
`request.unsupported`, until server-side method-registry resolution exists. Either way the method is held to the run
routes'' Python policy:
custom `.py` only on a sandbox-hosted deployment, and no Python structure class at all.'
MigrationErrorBlock:
properties:
remedy:
type: string
title: Remedy
would_write:
type: boolean
title: Would Write
needs_attention:
type: boolean
title: Needs Attention
plans:
items:
$ref: '#/components/schemas/MigrationPlan'
type: array
title: Plans
additionalProperties: false
type: object
required:
- remedy
- would_write
- needs_attention
- plans
title: MigrationErrorBlock
description: 'A pending configuration migration, reported alongside the error it explains.
The structured half of the answer to *why does my configuration not load*, carried by the operator''s
``diagnostics.migration`` and present only when a scan of this machine''s configuration directories found something
to say. **Consumers branch on its presence**, never on the message text: an absent block means the failure is not
staleness. It describes the host''s own configuration directories, so only an operator reads it.
``plans`` is the same shape ``pipelex-agent migrate --dry-run --format json`` emits under its own ``plans`` key,
deliberately: an agent that reads one has already parsed the other.
> **No value read from a user''s file is ever rendered** here either. The plans carry paths, operation kinds and
> ledger-supplied values, and nothing else.'
MigrationPlan:
properties:
surface_id:
type: string
title: Surface Id
file_path:
type: string
format: path
title: File Path
blocked_reason:
anyOf:
- $ref: '#/components/schemas/FileBlockedReason'
- type: 'null'
blocked_detail:
anyOf:
- type: string
- type: 'null'
title: Blocked Detail
steps:
items:
$ref: '#/components/schemas/MigrationStep'
type: array
title: Steps
blocked:
items:
$ref: '#/components/schemas/BlockedEntry'
type: array
title: Blocked
unexplained:
items:
$ref: '#/components/schemas/UnexplainedPath'
type: array
title: Unexplained
backup_path:
anyOf:
- type: string
format: path
- type: 'null'
title: Backup Path
was_written:
type: boolean
title: Was Written
default: false
additionalProperties: false
type: object
required:
- surface_id
- file_path
title: MigrationPlan
description: What one file needs, and what this run did to it.
MigrationSafety:
type: string
enum:
- safe
- unsafe
title: MigrationSafety
description: 'Whether the applier may act on an entry.
Independent of `guidance`, which any entry may carry whatever its safety.'
MigrationStep:
properties:
entry_id:
type: string
title: Entry Id
to_schema_version:
type: integer
title: To Schema Version
title:
type: string
title: Title
description:
type: string
title: Description
breaking:
type: boolean
title: Breaking
safety:
$ref: '#/components/schemas/MigrationSafety'
applied_ops:
items:
oneOf:
- $ref: '#/components/schemas/DeleteKeyOp'
- $ref: '#/components/schemas/DeleteTableOp'
- $ref: '#/components/schemas/RenameTableKeyOp'
- $ref: '#/components/schemas/MoveKeyOp'
- $ref: '#/components/schemas/RemapValueOp'
discriminator:
propertyName: kind
mapping:
delete_key: '#/components/schemas/DeleteKeyOp'
delete_table: '#/components/schemas/DeleteTableOp'
move_key: '#/components/schemas/MoveKeyOp'
remap_value: '#/components/schemas/RemapValueOp'
rename_table_key: '#/components/schemas/RenameTableKeyOp'
type: array
title: Applied Ops
additionalProperties: false
type: object
required:
- entry_id
- to_schema_version
- title
- description
- breaking
- safety
- applied_ops
title: MigrationStep
description: One ledger entry that changed this file, and the operations of it that fired.
MissingBlob:
properties:
sha256:
type: string
pattern: ^[0-9a-f]{64}$
title: Sha256
size:
type: integer
minimum: 0.0
title: Size
description: The length of the bytes, a JSON integer written without a fraction or an exponent. A size written 13.0
is refused, although JSON Schema's integer type admits it.
upload:
$ref: '#/components/schemas/UploadTarget'
type: object
required:
- sha256
- size
- upload
title: MissingBlob
description: A blob the runner lacks, with where to upload it.
MissingBlobsRequest:
properties:
blobs:
items:
$ref: '#/components/schemas/BlobRef'
type: array
title: Blobs
description: The blobs to check, each hash listed once.
digest:
anyOf:
- type: string
pattern: ^sha256:[0-9a-f]{64}$
- type: 'null'
title: Digest
description: The tree digest of the method tree the blobs make up (optional).
additionalProperties: true
type: object
required:
- blobs
title: MissingBlobsRequest
description: The blobs a sender is about to send by hash, and optionally the tree they make up.
MissingBlobsResult:
properties:
missing:
items:
$ref: '#/components/schemas/MissingBlob'
type: array
title: Missing
type: object
required:
- missing
title: MissingBlobsResult
description: The blobs of the request the runner does not hold.
ModelCategory:
type: string
enum:
- llm
- extract
- img_gen
- search
- judgment
title: ModelCategory
description: 'The protocol''s model categories: what a deck entry''s `type` reports and the `GET /models?type=` filter
accepts.
A category is a settings family of the language — the inline settings a model
serves, and so the pipes that can name it: `llm` (`LLMSetting`, named by
`PipeLLM` and `PipeStructure`), `extract` (`ExtractSetting`, `PipeExtract`),
`img_gen` (`ImgGenSetting`, `PipeImgGen`), `search` (`SearchSetting`,
`PipeSearch`) and `judgment` (`JudgmentSetting`, `PipeJudge`). A settings
family the standard adds brings a category in the next protocol minor.'
ModelCheckCategory:
type: string
enum:
- llm
- extract
- img_gen
- search
- judgment
- doc_gen
title: ModelCheckCategory
description: 'The categories the model reference check covers, in the order every list it returns follows.
These are the MTHDS Protocol''s model categories, in the protocol''s order, then `doc_gen`, the family
of `PipeDocGen`. The protocol defines no category for `doc_gen`, so the model listing leaves it out,
but a method names a `doc_gen` model in its `model` field like any other, so the check covers it.'
ModelInfo:
properties:
name:
type: string
title: Name
type:
anyOf:
- $ref: '#/components/schemas/ModelCategory'
- type: string
- type: 'null'
title: Type
additionalProperties: true
type: object
required:
- name
title: ModelInfo
description: 'One entry of the model deck (`ModelDeck.models[]`) — base fields + extensions.
`type` is an open read of the entry''s category, under the protocol''s reader
rule: "A client reading a model list MUST NOT fail it because an entry carries
a category it does not recognize; it keeps that entry with its raw value or
leaves it out." This package keeps it: a category it knows reads as its
`ModelCategory` member, and one it does not — a category a runner of a later
protocol minor reports — keeps its raw string, so a consumer handles the
`str` case rather than the whole deck failing. The union is validated left to
right on purpose: pydantic''s default smart mode would keep every string,
known or not, as a plain `str`.'
ModelReference:
type: string
ModelReferenceKind:
type: string
enum:
- preset
- alias
- waterfall
- handle
title: ModelReferenceKind
description: The kind of model reference.
ModelReferenceResolution:
type: string
enum:
- resolved
- not_found
title: ModelReferenceResolution
description: Whether a reference resolves in a category in scope. Both values are definitive.
ModelReferenceVerdict:
properties:
reference:
type: string
title: Reference
description: The caller's reference, trimmed.
kind:
$ref: '#/components/schemas/ModelReferenceKind'
description: What the reference names, from its parsing.
name:
type: string
title: Name
description: The reference without its sigil or namespace.
category:
anyOf:
- $ref: '#/components/schemas/ModelCheckCategory'
- type: 'null'
description: The `type` asked, or null when none was.
resolution:
$ref: '#/components/schemas/ModelReferenceResolution'
description: Whether the reference resolves in a category in scope.
matches:
items:
anyOf:
- $ref: '#/components/schemas/PresetMatch'
- $ref: '#/components/schemas/AliasMatch'
- $ref: '#/components/schemas/WaterfallMatch'
- $ref: '#/components/schemas/HandleMatch'
type: array
title: Matches
description: One entry per category in scope where the reference resolves, in the order of the categories the check
covers.
suggestions:
items:
type: string
type: array
title: Suggestions
description: On `not_found`, the nearest names the caller may have meant; empty when it is `resolved`.
other_kinds:
items:
type: string
type: array
title: Other Kinds
description: On `not_found`, the same name under another kind, in the categories in scope; empty when it is `resolved`.
other_categories:
items:
$ref: '#/components/schemas/ModelCheckCategory'
type: array
title: Other Categories
description: On `not_found` with a `type`, the categories outside it where the same reference resolves; empty otherwise.
additionalProperties: false
type: object
required:
- reference
- kind
- name
- category
- resolution
- matches
- suggestions
- other_kinds
- other_categories
title: ModelReferenceVerdict
description: The verdict of the model reference check, discriminated on `resolution`.
ModelUsageSpec:
properties:
inference_model_name:
type: string
title: Inference Model Name
inference_model_id:
type: string
title: Inference Model Id
model_type:
type: string
title: Model Type
inference_calls:
type: integer
title: Inference Calls
default: 0
rated_inference_calls:
type: integer
title: Rated Inference Calls
default: 0
cost:
anyOf:
- type: number
- type: 'null'
title: Cost
additionalProperties: false
type: object
required:
- inference_model_name
- inference_model_id
- model_type
title: ModelUsageSpec
description: 'What one inference model actually did for a node.
This is the only place the graph records the model that **ran**. Everything else
in a GraphSpec that names a model records what was *asked for*:
``execution_data.resolved_model`` holds the handle the pipe resolved to — which may
still be an alias (``@default-premium``) — and the pipe blueprint holds the authored
choice (``$writing-factual``). Those are three rungs of one ladder, and only this
rung is the outcome: it survives alias resolution, deck defaults, and any fallback
or retry that landed somewhere other than what was requested.
A node genuinely uses more than one model in ordinary cases — a ``PipeLLM``''s text
pass and its object-structuring pass resolve separately — so a node''s models are a
LIST. Collapsing them to "the model" would be wrong in exactly the way a single
``cost`` for mixed rated/unrated calls is wrong.
``cost`` follows ``NodeUsageSpec`` invariant 2: ``None`` iff no call to this model
carried a rate table.'
MoveKeyOp:
properties:
table_path:
items:
type: string
type: array
title: Table Path
kind:
type: string
const: move_key
title: Kind
default: move_key
key:
type: string
title: Key
new_table_path:
items:
type: string
type: array
title: New Table Path
new_key:
type: string
title: New Key
additionalProperties: false
type: object
required:
- table_path
- key
- new_table_path
- new_key
title: MoveKeyOp
description: 'Relocate ``key`` from the addressed table into ``new_table_path``, under ``new_key``.
The moved key may be table-valued, in which case the whole subtree travels. Destination
parents that do not exist are created, as block tables, as part of the operation. Position
is preserved within a parent and never across parents — see ``docs/migration-ledger.md``
for the placement rule and for what happens to a moved table''s introducing comment.'
NextStep:
properties:
kind:
anyOf:
- $ref: '#/components/schemas/StepKind'
- type: string
title: Kind
detail:
type: string
title: Detail
additionalProperties: true
type: object
required:
- kind
- detail
title: NextStep
description: 'What the reader should do next: a kind from the protocol''s closed list, and the step in one sentence.'
NodeIOSpec:
properties:
inputs:
items:
$ref: '#/components/schemas/IOSpec'
type: array
title: Inputs
outputs:
items:
$ref: '#/components/schemas/IOSpec'
type: array
title: Outputs
additionalProperties: false
type: object
title: NodeIOSpec
description: Input/output specification for a node.
NodeKind:
type: string
enum:
- pipe_call
- controller
- operator
- input
- output
- artifact
- error
- binding
title: NodeKind
description: Types of nodes in the execution graph.
NodeSpec:
properties:
id:
type: string
title: Id
path:
anyOf:
- type: string
- type: 'null'
title: Path
kind:
$ref: '#/components/schemas/NodeKind'
pipe_code:
anyOf:
- type: string
- type: 'null'
title: Pipe Code
pipe_type:
anyOf:
- type: string
- type: 'null'
title: Pipe Type
description:
anyOf:
- type: string
- type: 'null'
title: Description
domain_code:
anyOf:
- type: string
- type: 'null'
title: Domain Code
status:
$ref: '#/components/schemas/NodeStatus'
skip_reason:
anyOf:
- type: string
- type: 'null'
title: Skip Reason
timing:
anyOf:
- $ref: '#/components/schemas/TimingSpec'
- type: 'null'
io:
$ref: '#/components/schemas/NodeIOSpec'
error:
anyOf:
- $ref: '#/components/schemas/PipelexProblem'
- type: 'null'
error_stack:
anyOf:
- type: string
- type: 'null'
title: Error Stack
tags:
additionalProperties:
type: string
type: object
title: Tags
metrics:
additionalProperties:
type: number
type: object
title: Metrics
usage:
anyOf:
- $ref: '#/components/schemas/NodeUsageSpec'
- type: 'null'
execution_data:
additionalProperties: true
type: object
title: Execution Data
additionalProperties: false
type: object
required:
- id
- kind
- status
title: NodeSpec
description: 'Specification for a node in the execution graph.
Each node represents a pipe invocation during execution.'
NodeStatus:
type: string
enum:
- scheduled
- running
- succeeded
- failed
- skipped
- canceled
title: NodeStatus
description: Execution status of a node.
NodeUsageSpec:
properties:
inference_calls:
type: integer
title: Inference Calls
default: 0
rated_inference_calls:
type: integer
title: Rated Inference Calls
default: 0
nb_tokens_by_category:
additionalProperties:
type: integer
type: object
title: Nb Tokens By Category
total_tokens:
type: integer
title: Total Tokens
default: 0
cost:
anyOf:
- type: number
- type: 'null'
title: Cost
cost_input:
anyOf:
- type: number
- type: 'null'
title: Cost Input
cost_output:
anyOf:
- type: number
- type: 'null'
title: Cost Output
by_model:
items:
$ref: '#/components/schemas/ModelUsageSpec'
type: array
title: By Model
subtree_inference_calls:
type: integer
title: Subtree Inference Calls
default: 0
subtree_rated_inference_calls:
type: integer
title: Subtree Rated Inference Calls
default: 0
subtree_nb_tokens_by_category:
additionalProperties:
type: integer
type: object
title: Subtree Nb Tokens By Category
subtree_total_tokens:
type: integer
title: Subtree Total Tokens
default: 0
subtree_cost:
anyOf:
- type: number
- type: 'null'
title: Subtree Cost
subtree_cost_input:
anyOf:
- type: number
- type: 'null'
title: Subtree Cost Input
subtree_cost_output:
anyOf:
- type: number
- type: 'null'
title: Subtree Cost Output
subtree_by_model:
items:
$ref: '#/components/schemas/ModelUsageSpec'
type: array
title: Subtree By Model
additionalProperties: false
type: object
title: NodeUsageSpec
description: "Inference usage attributed to one graph node.\n\nField names mirror the already-shipped client-facing\
\ ``TokensUsageRecord``\n(``reporting/usage_records.py``) so the graph does not introduce a fifth vocabulary\nfor\
\ numbers this codebase already names four ways (``TokenCategory``,\n``LLMTokenCostReportField``, ``GenAISpanAttr``,\
\ ``PostHogAttr``).\n\nINVARIANTS — the UI and every other consumer branch on these, not on guesses about\nwhy a number\
\ is missing:\n\n 1. ``NodeSpec.usage is None`` <=> no usage was reported anywhere in the run —\n either usage\
\ collection was off, or the run made zero inference calls. As soon\n as ONE usage event was seen, EVERY node\
\ carries a spec, zeroed where nothing\n ran. A controller, a lifted pipe, and a PipeFunc all get ``inference_calls=0``,\n\
\ never ``usage=None``. So the field is all-or-nothing across a graph: it never\n distinguishes \"this node\
\ was not measured\" from \"that node was\".\n\n 2. ``cost is None`` <=> ``rated_inference_calls == 0``. Nothing\
\ else. \"Made no\n call\" and \"made only unrated calls\" both land here and are told apart by\n ``inference_calls``.\n\
\n 3. ``inference_calls > rated_inference_calls > 0`` => ``cost`` is a LOWER BOUND,\n not a total: some of this\
\ node's calls carried no rate table. The UI must mark\n it (a leading \"≥\").\n\n 4. ``total_tokens`` is input_joined\
\ + output — the same definition as\n ``AggregatedCosts.total_nb_tokens``. It is NOT the sum of\n ``nb_tokens_by_category``:\
\ ``input_cached`` is a SUBSET of ``input``, not\n additive (see ``usage_records.py``), so summing double-counts.\
\ Never sum the\n dict; read this field.\n\n 5. ``cost_input`` + ``cost_output`` == ``cost`` (to float precision).\
\ They are\n the same number split by direction, not extra charges, and they are None on\n exactly the same\
\ condition.\n\n 6. ``by_model`` names the models that actually RAN, and its ``inference_calls``\n sum to this\
\ spec's own. It is a list because one node routinely uses more\n than one model (a PipeLLM's text pass and its\
\ object pass resolve\n separately). Ordered by descending calls, then by name, so a consumer can\n take the\
\ first entry as the dominant model without sorting.\n\nThe same invariants hold for the ``subtree_*`` half, which\
\ covers this node plus\nevery descendant (rolled up in the assembler, once, so no consumer re-derives it\nand disagrees)."
NumberField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: number
title: Kind
default: number
integer:
type: boolean
title: Integer
minimum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Minimum
maximum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Maximum
exclusive_minimum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Exclusive Minimum
exclusive_maximum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Exclusive Maximum
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- integer
- name
title: NumberField
description: '`number` at a named position.'
NumberItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: number
title: Kind
default: number
integer:
type: boolean
title: Integer
minimum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Minimum
maximum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Maximum
exclusive_minimum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Exclusive Minimum
exclusive_maximum:
anyOf:
- type: integer
- type: number
- type: 'null'
title: Exclusive Maximum
additionalProperties: false
type: object
required:
- required
- integer
title: NumberItem
description: '`number` — an integer or a floating-point number, with its optional bounds.'
ObjectField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: object
title: Kind
default: object
fields:
items:
oneOf:
- $ref: '#/components/schemas/TextField'
- $ref: '#/components/schemas/ProseField'
- $ref: '#/components/schemas/DateField'
- $ref: '#/components/schemas/NumberField'
- $ref: '#/components/schemas/BooleanField'
- $ref: '#/components/schemas/EnumField'
- $ref: '#/components/schemas/DocumentField'
- $ref: '#/components/schemas/ImageField'
- $ref: '#/components/schemas/ObjectField'
- $ref: '#/components/schemas/ListField'
- $ref: '#/components/schemas/UnknownField'
discriminator:
propertyName: kind
mapping:
boolean: '#/components/schemas/BooleanField'
date: '#/components/schemas/DateField'
document: '#/components/schemas/DocumentField'
enum: '#/components/schemas/EnumField'
image: '#/components/schemas/ImageField'
list: '#/components/schemas/ListField'
number: '#/components/schemas/NumberField'
object: '#/components/schemas/ObjectField'
prose: '#/components/schemas/ProseField'
text: '#/components/schemas/TextField'
unknown: '#/components/schemas/UnknownField'
type: array
title: Fields
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- fields
- name
title: ObjectField
description: '`object` at a named position, recursing through `fields` — themselves named.'
ObjectItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: object
title: Kind
default: object
fields:
items:
oneOf:
- $ref: '#/components/schemas/TextField'
- $ref: '#/components/schemas/ProseField'
- $ref: '#/components/schemas/DateField'
- $ref: '#/components/schemas/NumberField'
- $ref: '#/components/schemas/BooleanField'
- $ref: '#/components/schemas/EnumField'
- $ref: '#/components/schemas/DocumentField'
- $ref: '#/components/schemas/ImageField'
- $ref: '#/components/schemas/ObjectField'
- $ref: '#/components/schemas/ListField'
- $ref: '#/components/schemas/UnknownField'
discriminator:
propertyName: kind
mapping:
boolean: '#/components/schemas/BooleanField'
date: '#/components/schemas/DateField'
document: '#/components/schemas/DocumentField'
enum: '#/components/schemas/EnumField'
image: '#/components/schemas/ImageField'
list: '#/components/schemas/ListField'
number: '#/components/schemas/NumberField'
object: '#/components/schemas/ObjectField'
prose: '#/components/schemas/ProseField'
text: '#/components/schemas/TextField'
unknown: '#/components/schemas/UnknownField'
type: array
title: Fields
additionalProperties: false
type: object
required:
- required
- fields
title: ObjectItem
description: '`object` — a structured concept, recursing through its resolved payload fields.'
PipeBatchBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeController
title: Pipe Category
default: PipeController
type:
type: string
const: PipeBatch
title: Type
default: PipeBatch
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
branch_pipe_code:
type: string
title: Branch Pipe Code
input_list_name:
type: string
title: Input List Name
input_item_name:
type: string
title: Input Item Name
additionalProperties: false
type: object
required:
- description
- output
- branch_pipe_code
- input_list_name
- input_item_name
title: PipeBatchBlueprint
PipeComposeBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeCompose
title: Type
default: PipeCompose
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
template:
anyOf:
- type: string
- $ref: '#/components/schemas/TemplateBlueprint'
- type: 'null'
title: Template
construct:
anyOf:
- $ref: '#/components/schemas/ConstructBlueprint'
- type: 'null'
additionalProperties: false
type: object
required:
- description
- output
title: PipeComposeBlueprint
PipeConditionBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeController
title: Pipe Category
default: PipeController
type:
type: string
const: PipeCondition
title: Type
default: PipeCondition
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
expression_template:
anyOf:
- type: string
- type: 'null'
title: Expression Template
expression:
anyOf:
- type: string
- type: 'null'
title: Expression
outcomes:
additionalProperties:
type: string
type: object
title: Outcomes
x-schema-required: true
default_outcome:
anyOf:
- type: string
- $ref: '#/components/schemas/SpecialOutcome'
title: Default Outcome
add_alias_from_expression_to:
anyOf:
- type: string
- type: 'null'
title: Add Alias From Expression To
additionalProperties: false
type: object
required:
- description
- output
- default_outcome
title: PipeConditionBlueprint
PipeDocGenBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeDocGen
title: Type
default: PipeDocGen
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
format:
$ref: '#/components/schemas/DocGenFormat'
model:
anyOf:
- $ref: '#/components/schemas/DocGenSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
template:
anyOf:
- type: string
- type: 'null'
title: Template
template_file:
anyOf:
- type: string
- type: 'null'
title: Template File
filename:
anyOf:
- type: string
- type: 'null'
title: Filename
additionalProperties: false
type: object
required:
- description
- output
- format
title: PipeDocGenBlueprint
description: 'Generate a document file from a method''s structured result: a PDF, an Excel workbook, a Word document
or a PowerPoint deck.
It calls no AI model: it lays out or fills what its inputs already hold. With no template, the pipe lays its inputs
out by itself (the auto-layout), for every format but `pptx`. `template` is an inline HTML and Jinja2 template, for
`pdf` only; `template_file` is a path relative to the bundle''s file, inside its bundle and written with forward
slashes: an `.html` for `pdf`, an `.xlsx` for `xlsx`, a
`.docx` for `docx` and a `.pptx` for `pptx`, which `pptx` requires. `filename` is a Jinja expression over the
inputs; the suffix is added. The output must be a single `Document`, or a concept refining it. `model` names the
document engine that prints it, a model of the `doc_gen` family such as `reportlab-pdf` or, with the Pipelex
document generation plugin, `pipelex-pdf`; without it, the model deck''s default for the format and source prints
it. Which engines a runtime has depends on its plugins: open Pipelex prints a `pdf` without a template on
`reportlab-pdf`, and a runtime without the engine a step needs refuses the method when it loads.'
PipeExtractBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeExtract
title: Type
default: PipeExtract
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
model:
anyOf:
- $ref: '#/components/schemas/ExtractSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
max_page_images:
anyOf:
- type: integer
- type: 'null'
title: Max Page Images
page_image_captions:
anyOf:
- type: boolean
- type: 'null'
title: Page Image Captions
page_views:
anyOf:
- type: boolean
- type: 'null'
title: Page Views
page_views_dpi:
anyOf:
- type: integer
- type: 'null'
title: Page Views Dpi
render_js:
anyOf:
- type: boolean
- type: 'null'
title: Render Js
include_raw_html:
anyOf:
- type: boolean
- type: 'null'
title: Include Raw Html
additionalProperties: false
type: object
required:
- description
- output
title: PipeExtractBlueprint
PipeFuncBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeFunc
title: Type
default: PipeFunc
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
function_name:
type: string
pattern: ^[^.]+(\.[^.]+)+$
title: Function Name
description: 'The import path of the function to call, from the root of the method tree: the module''s dotted path,
then the function''s name, such as ''funcs.totals.compute_totals'' for the function compute_totals of funcs/totals.py.
The function must be a top-level def or async def of that module, decorated with @pipe_func().'
additionalProperties: false
type: object
required:
- description
- output
- function_name
title: PipeFuncBlueprint
PipeIOArtifacts:
properties:
pipe_io_contracts:
additionalProperties:
$ref: '#/components/schemas/PipeIOContract'
type: object
title: Pipe Io Contracts
input_form:
additionalProperties:
$ref: '#/components/schemas/PipeInputFormDescriptor'
type: object
title: Input Form
output_form:
additionalProperties:
$ref: '#/components/schemas/PipeOutputFormDescriptor'
type: object
title: Output Form
additionalProperties: false
type: object
required:
- pipe_io_contracts
- input_form
- output_form
title: PipeIOArtifacts
description: 'The validate report''s three I/O artifacts, under the report''s names and types.
A grouping, not a new shape: each field is the standard''s artifact, keyed by `pipe_ref`.'
PipeIOContract:
properties:
inputs:
additionalProperties:
$ref: '#/components/schemas/PipeInputContract'
type: object
title: Inputs
output:
$ref: '#/components/schemas/PipeOutputContract'
additionalProperties: false
type: object
required:
- inputs
- output
title: PipeIOContract
description: 'The contract of one pipe — one `pipe_io_contracts` entry, with both members required.
`inputs` is a map from authored input name to input contract, and it deliberately contracts no
order: an ordered view of a pipe''s inputs is the input-form descriptor''s job, which keeps this
artifact byte-stable whatever a renderer needs. A pipe with no declared inputs carries
`inputs: {}` — a stated fact, never an omitted member. Closed shape (`extra="forbid"`).'
PipeIORequest:
properties:
files:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
- type: 'null'
title: Files
description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
type: object
- type: 'null'
title: Dependencies
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
method_ref:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Method Ref
description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
until a method registry exists). Exactly one of `files` / `method_ref`.
resources:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Resources
description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
(an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
`MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
retired, and refused by a later release: a file the steps read travels inside the method''s tree, in `files`,
at its path beside the bundle that names it.'
read_scope:
anyOf:
- type: string
- type: 'null'
title: Read Scope
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the request reads the method under,
as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files`
resolves in that scope''s blob store, and the tree the request read is recorded there, so a later request can
send it by hash. Omit it and a hash entry resolves in the caller''s own id''s store, and nothing is recorded.'
pipe_ref:
anyOf:
- type: string
maxLength: 256
minLength: 1
- type: 'null'
title: Pipe Ref
description: Qualified pipe ref (`domain.pipe_code`) to select. Optional — defaults to the `main_pipe` of the `METHODS.toml`
at the method tree's root, else to the closure's declared `main_pipe`; a closure declaring none, or several, with
no manifest `main_pipe` to settle it, requires it unless `all_pipes` is set.
all_pipes:
type: boolean
title: All Pipes
description: 'Describe every pipe the closure loads instead of the selected one. The artifact maps are then keyed
by every pipe, and the route never refuses for want of an entry pipe: `pipe_ref` on the valid arm is the requested
ref, else the method''s own entry pipe, else `null`.'
default: false
include_files:
type: boolean
title: Include Files
description: 'Echo the method''s `.mthds` bundles on the valid arm, as a map of file entries in the request''s own
`files` shape, each bundle''s tree path to its text: the bundles of the tree sent in `files`, whatever entry carried
them, or those of the fetched package''s tree for a `method_ref`. Its other files and its dependencies are not
echoed. Absent from the response unless true.'
default: false
type: object
title: PipeIORequest
description: 'The pipe I/O request: the crate routes'' method selector and pipe selector, plus the whole-method and
echo opt-ins.
The hosted catalog selector is replaced by `files` before the request reaches the runner, so this
request has no field for it. It takes no `views` either, since the valid arm always carries all
three artifacts.'
PipeIOValidReport:
properties:
is_valid:
type: boolean
const: true
title: Is Valid
default: true
pipe_ref:
anyOf:
- type: string
- type: 'null'
title: Pipe Ref
description: The qualified `domain.pipe_code` the selection resolved, read back off the resolved pipe and never
echoed from the request. `null` only under `all_pipes` when no pipe was requested and the method declares no single
entry pipe.
pipe_io_contracts:
additionalProperties:
$ref: '#/components/schemas/PipeIOContract'
type: object
title: Pipe Io Contracts
description: The standard's pipe I/O contracts, keyed by qualified `pipe_ref`.
input_form:
additionalProperties:
$ref: '#/components/schemas/PipeInputFormDescriptor'
type: object
title: Input Form
description: The standard's input-form descriptors, keyed by qualified `pipe_ref`.
output_form:
additionalProperties:
$ref: '#/components/schemas/PipeOutputFormDescriptor'
type: object
title: Output Form
description: The standard's output-form descriptors, keyed by qualified `pipe_ref`.
default_pipe_ref:
anyOf:
- type: string
- type: 'null'
title: Default Pipe Ref
description: 'The method''s own entry pipe: the selection chain without the request''s `pipe_ref` — the fetched
package manifest''s `main_pipe`, else the closure''s single `main_pipe` declaration. A stated `null` when that
chain finds none or several. Not `/validate`''s field of the same name, which is the run default.'
pending_signatures:
items:
type: string
type: array
title: Pending Signatures
description: The qualified refs of every pipe of the closure still declared as a signature, exactly as on `/validate`.
is_runnable:
type: boolean
title: Is Runnable
description: '`not pending_signatures`, exactly as on `/validate`. No dry run backs it.'
files:
additionalProperties:
type: string
type: object
title: Files
description: 'The method''s `.mthds` bundles, each tree path to its text, a map of file entries as the request''s
`files` is. Present only with `include_files: true`.'
type: object
required:
- pipe_ref
- pipe_io_contracts
- input_form
- output_form
- default_pipe_ref
- pending_signatures
- is_runnable
title: PipeIOValidReport
description: 'The 200 **valid** arm: the method''s three I/O artifacts, with the selection and the runnability facts
beside them.
The three maps share one key set: the resolved `pipe_ref` alone by default, every pipe the
closure loads under `all_pipes`. Each map is the standard''s artifact under its neutral name, and
for a closure `/validate` also accepts it equals `/validate`''s same-named field restricted to the
same keys — both routes call the one builder, and both dump without dropping null members.
`is_valid: true` means what it means on `/resolve`: the closure parsed, loaded and passed static
validation. No dry run ran; that verdict stays `/validate`''s.'
PipeImgGenBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeImgGen
title: Type
default: PipeImgGen
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
prompt:
type: string
title: Prompt
negative_prompt:
anyOf:
- type: string
- type: 'null'
title: Negative Prompt
model:
anyOf:
- $ref: '#/components/schemas/ImgGenSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
aspect_ratio:
anyOf:
- $ref: '#/components/schemas/AspectRatio'
- type: 'null'
size:
anyOf:
- $ref: '#/components/schemas/SizeTier'
- $ref: '#/components/schemas/ImageSize'
- type: 'null'
title: Size
is_raw:
anyOf:
- type: boolean
- type: 'null'
title: Is Raw
seed:
anyOf:
- type: integer
- type: string
const: auto
- type: 'null'
title: Seed
background:
anyOf:
- $ref: '#/components/schemas/Background'
- type: 'null'
output_format:
anyOf:
- $ref: '#/components/schemas/ImageFormat'
- type: 'null'
additionalProperties: false
type: object
required:
- description
- output
- prompt
title: PipeImgGenBlueprint
PipeInputContract:
properties:
concept_ref:
type: string
title: Concept Ref
presence:
$ref: '#/components/schemas/PresenceMarker'
multiplicity:
$ref: '#/components/schemas/IOMultiplicity'
item_count:
anyOf:
- type: integer
- type: 'null'
title: Item Count
json_schema:
additionalProperties: true
type: object
title: Json Schema
additionalProperties: false
type: object
required:
- concept_ref
- presence
- multiplicity
- item_count
- json_schema
title: PipeInputContract
description: 'One declared input slot: the concept it expects, its presence, its plurality and the JSON Schema of its
content.
Keyed in `PipeIOContract.inputs` by the authored input name, a plain name.
Every member is required: `item_count` is always on the wire, `null` off the fixed arm.
Closed shape (`extra="forbid"`): an unknown member is version drift, rejected at the parse.'
PipeInputFormDescriptor:
properties:
fields:
items:
oneOf:
- $ref: '#/components/schemas/TextField'
- $ref: '#/components/schemas/ProseField'
- $ref: '#/components/schemas/DateField'
- $ref: '#/components/schemas/NumberField'
- $ref: '#/components/schemas/BooleanField'
- $ref: '#/components/schemas/EnumField'
- $ref: '#/components/schemas/DocumentField'
- $ref: '#/components/schemas/ImageField'
- $ref: '#/components/schemas/ObjectField'
- $ref: '#/components/schemas/ListField'
- $ref: '#/components/schemas/UnknownField'
discriminator:
propertyName: kind
mapping:
boolean: '#/components/schemas/BooleanField'
date: '#/components/schemas/DateField'
document: '#/components/schemas/DocumentField'
enum: '#/components/schemas/EnumField'
image: '#/components/schemas/ImageField'
list: '#/components/schemas/ListField'
number: '#/components/schemas/NumberField'
object: '#/components/schemas/ObjectField'
prose: '#/components/schemas/ProseField'
text: '#/components/schemas/TextField'
unknown: '#/components/schemas/UnknownField'
type: array
title: Fields
additionalProperties: false
type: object
required:
- fields
title: PipeInputFormDescriptor
description: 'The input form of one pipe — one `input_form` entry.
`fields` holds one descriptor per declared input slot, in authored input order: the order is why
the descriptor is a sibling artifact of the contract rather than a decoration inside it. A pipe
with no inputs maps to `{"fields": []}` — an empty form is a valid form, not an omitted entry.
Closed shape (`extra="forbid"`).'
PipeJudgeBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeJudge
title: Type
default: PipeJudge
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
prompt:
type: string
title: Prompt
question:
anyOf:
- type: string
- type: 'null'
title: Question
questions:
anyOf:
- additionalProperties:
$ref: '#/components/schemas/JudgeQuestionBlueprint'
type: object
- type: 'null'
title: Questions
model:
anyOf:
- $ref: '#/components/schemas/JudgmentSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
options:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Options
levels:
anyOf:
- items:
anyOf:
- type: string
- $ref: '#/components/schemas/JudgeRatingLevel'
type: array
- type: 'null'
title: Levels
criteria:
anyOf:
- $ref: '#/components/schemas/JudgeYesNoCriteria'
- type: 'null'
threshold:
anyOf:
- type: number
- type: 'null'
title: Threshold
additionalProperties: false
type: object
required:
- description
- output
- prompt
title: PipeJudgeBlueprint
description: 'Asks a judging model closed questions about the evidence its prompt presents: yes/no, a choice, or a rating.
`prompt` is the evidence template, rendered and checked as a PipeLLM''s prompt is, the images and
documents it reads presented to the model as files. The single form asks one `question`, a plain
text template, and produces its verdict native; the multi form asks the several `questions` of a
table keyed by name over the same evidence in one request, and fills a structure whose fields are
those names with one verdict each. A question''s kind is decided by which of `options` and `levels`
it declares, never by a field of its own, and the single form declares them on the pipe. Every
declared input is read by the prompt or by a question.'
PipeLLMBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeLLM
title: Type
default: PipeLLM
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
model:
anyOf:
- $ref: '#/components/schemas/LLMSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
model_to_structure:
anyOf:
- $ref: '#/components/schemas/LLMSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model To Structure
system_prompt:
anyOf:
- type: string
- type: 'null'
title: System Prompt
prompt:
anyOf:
- type: string
- type: 'null'
title: Prompt
structuring_method:
anyOf:
- $ref: '#/components/schemas/StructuringMethod'
- type: 'null'
templating_style:
anyOf:
- $ref: '#/components/schemas/TagStyle'
- $ref: '#/components/schemas/TemplatingStyle'
- type: 'null'
title: Templating Style
additionalProperties: false
type: object
required:
- description
- output
title: PipeLLMBlueprint
PipeOutputContract:
properties:
concept_ref:
type: string
title: Concept Ref
multiplicity:
$ref: '#/components/schemas/IOMultiplicity'
item_count:
anyOf:
- type: integer
- type: 'null'
title: Item Count
optional:
type: boolean
title: Optional
json_schema:
additionalProperties: true
type: object
title: Json Schema
additionalProperties: false
type: object
required:
- concept_ref
- multiplicity
- item_count
- optional
- json_schema
title: PipeOutputContract
description: 'What the pipe resolves to: the concept it produces, how many items that is, whether it may be absent,
and the shape of its payload.
Deliberately asymmetric with the input side in exactly one place, and no longer in a second.
An output carries a two-valued `optional` where an input carries a three-valued `presence`,
because `!` MUST NOT appear on an output — a force marker is a use-site assertion about an
input, so a three-valued output slot would have an arm nothing can ever produce. That
asymmetry is a language fact and it stays.
The schema asymmetry was not. An output used to carry none, on the reasoning that "the payload
a run produces is the run''s own result" — which answers *what did this run produce?*, correctly
not a contract''s business, rather than the question a consumer actually asks: *what shape will
it be?* That is declared in the `.mthds` source and knowable before any run happens, exactly as
it is on the input side. Withholding it left every consumer inferring a payload''s shape by
inspecting it, which is guessing at the standard rather than reading it.
Closed shape (`extra="forbid"`).'
PipeOutputFormDescriptor:
properties:
field:
oneOf:
- $ref: '#/components/schemas/TextField'
- $ref: '#/components/schemas/ProseField'
- $ref: '#/components/schemas/DateField'
- $ref: '#/components/schemas/NumberField'
- $ref: '#/components/schemas/BooleanField'
- $ref: '#/components/schemas/EnumField'
- $ref: '#/components/schemas/DocumentField'
- $ref: '#/components/schemas/ImageField'
- $ref: '#/components/schemas/ObjectField'
- $ref: '#/components/schemas/ListField'
- $ref: '#/components/schemas/UnknownField'
title: Field
discriminator:
propertyName: kind
mapping:
boolean: '#/components/schemas/BooleanField'
date: '#/components/schemas/DateField'
document: '#/components/schemas/DocumentField'
enum: '#/components/schemas/EnumField'
image: '#/components/schemas/ImageField'
list: '#/components/schemas/ListField'
number: '#/components/schemas/NumberField'
object: '#/components/schemas/ObjectField'
prose: '#/components/schemas/ProseField'
text: '#/components/schemas/TextField'
unknown: '#/components/schemas/UnknownField'
additionalProperties: false
type: object
required:
- field
title: PipeOutputFormDescriptor
description: 'The output form of one pipe — one `output_form` entry, carrying the single output node.
Closed shape (`extra="forbid"`). The node itself is an `InputFormField`, so it is parsed by
the same discriminated union every input node is, and a consumer narrows it the same way.'
PipeOutputWire:
properties:
working_memory:
$ref: '#/components/schemas/WorkingMemory'
pipeline_run_id:
type: string
title: Pipeline Run Id
default: untitled
working_memory_raw:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Working Memory Raw
graph_spec:
anyOf:
- $ref: '#/components/schemas/GraphSpec'
- type: 'null'
graph_assembly_error:
anyOf:
- type: string
- type: 'null'
title: Graph Assembly Error
pipe_io_artifacts:
anyOf:
- $ref: '#/components/schemas/PipeIOArtifacts'
- type: 'null'
pipe_io_artifacts_error:
anyOf:
- type: string
- type: 'null'
title: Pipe Io Artifacts Error
tokens_usages:
anyOf:
- items:
$ref: '#/components/schemas/TokensUsageRecord'
type: array
- type: 'null'
title: Tokens Usages
usage_assembly_error:
anyOf:
- type: string
- type: 'null'
title: Usage Assembly Error
additionalProperties: false
type: object
title: PipeOutputWire
description: '`PipeOutput` as it crosses the client boundary: usages trimmed to wire records.
The route applies pipelex''s `apply_tokens_usage_wire_shape` to the response dump, so
`tokens_usages` carries flat `TokensUsageRecord`s — not the internal usage models with
their `job_metadata` plumbing and `unit_costs` rate table.'
PipeParallelBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeController
title: Pipe Category
default: PipeController
type:
type: string
const: PipeParallel
title: Type
default: PipeParallel
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
branches:
items:
$ref: '#/components/schemas/SubPipeBlueprint'
type: array
title: Branches
add_each_output:
type: boolean
title: Add Each Output
default: false
additionalProperties: false
type: object
required:
- description
- output
- branches
title: PipeParallelBlueprint
PipeSearchBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeSearch
title: Type
default: PipeSearch
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
prompt:
type: string
title: Prompt
model:
anyOf:
- $ref: '#/components/schemas/SearchSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
include_images:
anyOf:
- type: boolean
- type: 'null'
title: Include Images
max_results:
anyOf:
- type: integer
- type: 'null'
title: Max Results
from_date:
anyOf:
- type: string
- type: 'null'
title: From Date
to_date:
anyOf:
- type: string
- type: 'null'
title: To Date
include_domains:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Include Domains
exclude_domains:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Exclude Domains
additionalProperties: false
type: object
required:
- description
- output
- prompt
title: PipeSearchBlueprint
PipeSequenceBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeController
title: Pipe Category
default: PipeController
type:
type: string
const: PipeSequence
title: Type
default: PipeSequence
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
steps:
items:
oneOf:
- $ref: '#/components/schemas/SubPipeBlueprint'
- $ref: '#/components/schemas/BindingStepBlueprint'
type: array
title: Steps
additionalProperties: false
type: object
required:
- description
- output
- steps
title: PipeSequenceBlueprint
PipeSignatureBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
signature_for:
anyOf:
- $ref: '#/components/schemas/PipeType'
- type: 'null'
description: Intended downstream pipe type when this signature is implemented (optional hint for agents).
additionalProperties: false
type: object
required:
- description
- output
title: PipeSignatureBlueprint
description: 'Contract-only pipe blueprint.
A `PipeSignature` declares inputs and output but has no implementation. It exists so
that an in-progress pipeline can be validated (dry-run mocks the declared output)
before all its pipes are implemented.'
PipeStructureBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
pipe_category:
type: string
const: PipeOperator
title: Pipe Category
default: PipeOperator
type:
type: string
const: PipeStructure
title: Type
default: PipeStructure
description:
type: string
title: Description
inputs:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/InputSlotBlueprint'
type: object
- type: 'null'
title: Inputs
output:
type: string
title: Output
model:
anyOf:
- $ref: '#/components/schemas/LLMSetting'
- type: string
- $ref: '#/components/schemas/ModelReference'
- type: 'null'
title: Model
additionalProperties: false
type: object
required:
- description
- output
title: PipeStructureBlueprint
PipeType:
type: string
enum:
- PipeFunc
- PipeImgGen
- PipeCompose
- PipeLLM
- PipeExtract
- PipeSearch
- PipeStructure
- PipeDocGen
- PipeJudge
- PipeBatch
- PipeCondition
- PipeParallel
- PipeSequence
title: PipeType
PipelexApiExecuteResponse:
properties:
pipeline_run_id:
type: string
title: Pipeline Run Id
pipe_output:
$ref: '#/components/schemas/PipeOutputWire'
created_at:
type: string
title: Created At
state:
$ref: '#/components/schemas/RunState'
finished_at:
anyOf:
- type: string
- type: 'null'
title: Finished At
main_stuff_name:
type: string
title: Main Stuff Name
crate_fingerprint:
anyOf:
- type: string
- type: 'null'
title: Crate Fingerprint
description: PIPELEX EXTENSION (not part of the MTHDS Protocol) — the fingerprint of the library crate the run's
method was loaded into, the identity of its concepts and pipes, which changes with their meaning and not with
their formatting or comments. Null when the run was built from no crate.
method_provenance:
anyOf:
- $ref: '#/components/schemas/MethodProvenance'
- type: 'null'
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — provenance of a `method_ref` run: the package''s
resolved full address, the requested tag (null for a bare address), the commit SHA that was actually fetched,
the digest of the method tree the run loaded, and the `display_name` the package''s manifest declares (null when
it declares none). The SHA is what keeps the run explainable when a tag moves. Absent (or null) for runs from
inline source or a bundle.'
additionalProperties: true
type: object
required:
- pipeline_run_id
- pipe_output
- created_at
- state
- main_stuff_name
title: PipelexApiExecuteResponse
description: 'Documented 200 body of `POST /execute` — the run result with the wire-shaped `pipe_output`.
Used only to publish the OpenAPI response schema. `/execute` returns a `JSONResponse`
built from the trimmed dump, so FastAPI never serializes through this model; declaring it
is what keeps the published artifact honest about what the route actually emits
(`method_provenance` is attached to the dump by the route for `method_ref` runs, and is
absent otherwise).'
PipelexApiStartResponse:
properties:
pipeline_run_id:
type: string
title: Pipeline Run Id
created_at:
type: string
title: Created At
state:
$ref: '#/components/schemas/RunState'
finished_at:
anyOf:
- type: string
- type: 'null'
title: Finished At
workflow_id:
anyOf:
- type: string
- type: 'null'
title: Workflow Id
crate_fingerprint:
anyOf:
- type: string
- type: 'null'
title: Crate Fingerprint
description: PIPELEX EXTENSION (not part of the MTHDS Protocol) — the fingerprint of the library crate the run's
method was loaded into, the identity of its concepts and pipes, which changes with their meaning and not with
their formatting or comments. Null when the run was built from no crate.
method_provenance:
anyOf:
- $ref: '#/components/schemas/MethodProvenance'
- type: 'null'
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — provenance of a `method_ref` run: the package''s
resolved full address, the requested tag (null for a bare address), the commit SHA that was actually fetched,
the digest of the method tree the run loaded, and the `display_name` the package''s manifest declares (null when
it declares none). The SHA is what keeps the run explainable when a tag moves. Absent (or null) for runs from
inline source or a bundle.'
additionalProperties: true
type: object
required:
- pipeline_run_id
- created_at
- state
title: PipelexApiStartResponse
description: 'The 202 body of `POST /start` — the protocol''s start ack plus this server''s `method_provenance` extension.
Unlike its `/execute` counterpart this model IS what the route returns (FastAPI serializes
through it): the ack is small, so wrapping it costs nothing and keeps the artifact and the
wire in lockstep. `method_provenance` is populated for `method_ref` runs and null otherwise.'
PipelexBundleBlueprint:
properties:
source:
anyOf:
- type: string
- type: 'null'
title: Source
domain:
type: string
title: Domain
description:
anyOf:
- type: string
- type: 'null'
title: Description
system_prompt:
anyOf:
- type: string
- type: 'null'
title: System Prompt
main_pipe:
anyOf:
- type: string
- type: 'null'
title: Main Pipe
concept:
anyOf:
- additionalProperties:
anyOf:
- $ref: '#/components/schemas/ConceptBlueprint'
- type: string
type: object
- type: 'null'
title: Concept
pipe:
anyOf:
- additionalProperties:
oneOf:
- $ref: '#/components/schemas/PipeFuncBlueprint'
- $ref: '#/components/schemas/PipeImgGenBlueprint'
- $ref: '#/components/schemas/PipeComposeBlueprint'
- $ref: '#/components/schemas/PipeLLMBlueprint'
- $ref: '#/components/schemas/PipeExtractBlueprint'
- $ref: '#/components/schemas/PipeSearchBlueprint'
- $ref: '#/components/schemas/PipeJudgeBlueprint'
- $ref: '#/components/schemas/PipeStructureBlueprint'
- $ref: '#/components/schemas/PipeDocGenBlueprint'
- $ref: '#/components/schemas/PipeBatchBlueprint'
- $ref: '#/components/schemas/PipeConditionBlueprint'
- $ref: '#/components/schemas/PipeParallelBlueprint'
- $ref: '#/components/schemas/PipeSequenceBlueprint'
- $ref: '#/components/schemas/PipeSignatureBlueprint'
discriminator:
propertyName: type
mapping:
PipeBatch: '#/components/schemas/PipeBatchBlueprint'
PipeCompose: '#/components/schemas/PipeComposeBlueprint'
PipeCondition: '#/components/schemas/PipeConditionBlueprint'
PipeDocGen: '#/components/schemas/PipeDocGenBlueprint'
PipeExtract: '#/components/schemas/PipeExtractBlueprint'
PipeFunc: '#/components/schemas/PipeFuncBlueprint'
PipeImgGen: '#/components/schemas/PipeImgGenBlueprint'
PipeJudge: '#/components/schemas/PipeJudgeBlueprint'
PipeLLM: '#/components/schemas/PipeLLMBlueprint'
PipeParallel: '#/components/schemas/PipeParallelBlueprint'
PipeSearch: '#/components/schemas/PipeSearchBlueprint'
PipeSequence: '#/components/schemas/PipeSequenceBlueprint'
PipeSignature: '#/components/schemas/PipeSignatureBlueprint'
PipeStructure: '#/components/schemas/PipeStructureBlueprint'
type: object
- type: 'null'
title: Pipe
additionalProperties: false
type: object
required:
- domain
title: PipelexBundleBlueprint
PipelexModelDeck:
properties:
models:
items:
$ref: '#/components/schemas/ModelInfo'
type: array
title: Models
aliases:
additionalProperties:
additionalProperties:
type: string
type: object
type: object
title: Aliases
waterfalls:
additionalProperties:
additionalProperties:
items:
type: string
type: array
type: object
type: object
title: Waterfalls
additionalProperties: true
type: object
title: PipelexModelDeck
description: 'Pipelex''s model deck — the protocol base plus this implementation''s
routing metadata (aliases, waterfalls), keyed by model category.
The routing extensions are category-scoped on purpose: the same alias name
(e.g. `default-small`) legitimately exists in several categories pointing at
different models, so a flat map would silently lose entries on collision.'
PipelexProblem:
properties:
type:
type: string
title: Type
title:
type: string
title: Title
status:
anyOf:
- type: integer
ge: 100
le: 599
- type: 'null'
title: Status
detail:
type: string
title: Detail
code:
type: string
pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,2}$
title: Code
domain:
anyOf:
- $ref: '#/components/schemas/ProblemDomain'
- type: string
title: Domain
retry:
anyOf:
- $ref: '#/components/schemas/RetryVerdict'
- type: string
title: Retry
retry_after:
anyOf:
- anyOf:
- type: integer
- type: number
ge: 0
- type: 'null'
title: Retry After
next_step:
$ref: '#/components/schemas/NextStep'
params:
anyOf:
- $ref: '#/components/schemas/ProblemParams'
- type: 'null'
location:
anyOf:
- $ref: '#/components/schemas/ProblemLocation'
- type: 'null'
errors:
anyOf:
- items:
$ref: '#/components/schemas/ProblemItem'
type: array
minItems: 1
- type: 'null'
title: Errors
pipeline_run_id:
anyOf:
- type: string
- type: 'null'
title: Pipeline Run Id
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
run_error:
anyOf:
- $ref: '#/components/schemas/PipelexProblem'
- type: 'null'
diagnostics:
anyOf:
- $ref: '#/components/schemas/ProblemDiagnostics'
- type: 'null'
additionalProperties: true
type: object
required:
- type
- title
- detail
- code
- domain
- retry
- next_step
title: PipelexProblem
description: "The MTHDS problem document with Pipelex's members.\n\nAttributes:\n request_id: The request that carried\
\ the failure, when known.\n run_error: On a read of a failed run's results, the run's own problem.\n diagnostics:\
\ What only an operator reads; present in the operator view alone."
PipelexVersionInfo:
properties:
protocol_version:
type: string
title: Protocol Version
runner_version:
anyOf:
- type: string
- type: 'null'
title: Runner Version
blob_store:
type: boolean
title: Blob Store
default: false
implementation:
type: string
title: Implementation
implementation_version:
type: string
title: Implementation Version
runtime_version:
anyOf:
- type: string
- type: 'null'
title: Runtime Version
additionalProperties: true
type: object
required:
- protocol_version
- implementation
- implementation_version
title: PipelexVersionInfo
description: 'Pipelex''s version handshake — the protocol base plus this
implementation''s identification.'
PipelineRef:
properties:
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
main_pipe:
anyOf:
- type: string
- type: 'null'
title: Main Pipe
entrypoint:
anyOf:
- type: string
- type: 'null'
title: Entrypoint
additionalProperties: false
type: object
title: PipelineRef
description: Reference to the pipeline that was executed.
PresenceMarker:
type: string
enum:
- plain
- optional
- force
title: PresenceMarker
description: 'The authored presence marker of a declared input slot, verbatim and three-valued.
`plain` (no marker) and `force` (`!`) are the same requirement on the caller — the slot
must be supplied — and differ only in what the author asserted; `optional` (`?`) means the
caller may omit the slot and the pipe handles the absence itself. The distinction is kept on
the wire because lint and graph surfaces read it, and a producer flattening it to a boolean
would destroy it for every consumer at once. A consumer that only needs "may this be absent?"
answers it as `is_optional`, in exactly one place.'
PresetMatch:
properties:
category:
$ref: '#/components/schemas/ModelCheckCategory'
description: The category this entry is about.
resolves_to:
anyOf:
- type: string
- type: 'null'
title: Resolves To
description: The model handle a run through the reference would call now in this category, or null when it would
find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
serves, an alias cycle).
target:
type: string
title: Target
description: The model the deck binds the preset to, as the deck writes it, which may itself be a reference.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: The preset's description, or null when the deck gives it none.
additionalProperties: false
type: object
required:
- category
- resolves_to
- target
- description
title: PresetMatch
description: What a preset reference is in one category.
ProblemDeleteKeyOp:
properties:
kind:
type: string
const: delete_key
title: Kind
table_path:
items:
type: string
type: array
title: Table Path
key:
type: string
title: Key
additionalProperties: true
type: object
required:
- kind
- table_path
- key
title: DeleteKeyOp
description: Remove `key` from the table at `table_path`.
ProblemDeleteTableOp:
properties:
kind:
type: string
const: delete_table
title: Kind
table_path:
items:
type: string
type: array
minItems: 1
title: Table Path
additionalProperties: true
type: object
required:
- kind
- table_path
title: DeleteTableOp
description: Remove the table at `table_path`, every part of it included.
ProblemDiagnostics:
properties:
error_class:
type: string
title: Error Class
message:
type: string
title: Message
causes:
anyOf:
- items:
$ref: '#/components/schemas/DiagnosticCause'
type: array
- type: 'null'
title: Causes
params:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Params
model:
anyOf:
- type: string
- type: 'null'
title: Model
provider:
anyOf:
- $ref: '#/components/schemas/ProviderDiagnostics'
- type: 'null'
migration:
anyOf:
- $ref: '#/components/schemas/MigrationErrorBlock'
- type: 'null'
runtime_version:
anyOf:
- type: string
- type: 'null'
title: Runtime Version
trace_id:
anyOf:
- type: string
- type: 'null'
title: Trace Id
span_id:
anyOf:
- type: string
- type: 'null'
title: Span Id
additionalProperties: true
type: object
required:
- error_class
- message
title: ProblemDiagnostics
description: "What only an operator reads of a problem: the operator view's ``diagnostics`` member.\n\nAttributes:\n\
\ error_class: The class of the error the problem was built from, the identity ``error_type`` once was.\n message:\
\ The error's own message, capped.\n causes: The errors below it on its cause chain, by class and code.\n params:\
\ The parameters the code declares operator-only.\n model: The model a failed inference call addressed.\n provider:\
\ What the provider said about the call.\n migration: A pending configuration migration that explains the failure.\n\
\ runtime_version: The version of the Pipelex runtime that built the problem.\n trace_id: The trace of the Pipelex\
\ span the failure happened in.\n span_id: That span."
ProblemDocument:
properties:
type:
type: string
title: Type
description: 'Stable URI of the documentation page of the error''s `code`: `https://mthds.ai/errors/<code>` for
a core code, `https://docs.pipelex.com/errors/<code>` for a Pipelex code.'
title:
type: string
title: Title
description: 'Short, human-readable summary: the title of the error''s `code`.'
status:
type: integer
title: Status
description: 'HTTP status code, repeated in the body per RFC 9457: the status its `code` declares.'
detail:
type: string
title: Detail
description: 'Human-readable explanation of this specific failure, rendered from its code''s template and parameters.
Never parsed: a program branches on `code`.'
code:
type: string
title: Code
description: 'Registry code of the error, what a client branches on: a core code of the MTHDS standard (e.g. `request.invalid`)
or a Pipelex code (e.g. `pipelex.config.invalid`).'
domain:
type: string
title: Domain
description: 'Who must act, the code''s domain: `input`, `method`, `account`, `operator` or `runtime`.'
retry:
type: string
title: Retry
description: 'Whether repeating the request can succeed, the code''s verdict: `yes`, `no` or `outcome_unknown`.'
retry_after:
anyOf:
- type: number
- type: 'null'
title: Retry After
description: Seconds to wait before a retry, when known, on a code whose verdict is `yes`.
next_step:
$ref: '#/components/schemas/NextStep'
description: 'What the reader should do next: a kind and a sentence, aimed at the caller, or at the operator in
the operator view.'
params:
anyOf:
- $ref: '#/components/schemas/ProblemParams'
- type: 'null'
description: The code's typed parameters, the ones its templates are rendered with.
location:
anyOf:
- $ref: '#/components/schemas/ProblemLocation'
- type: 'null'
description: 'Where the failure happened: the failing pipe and its path from the entry pipe, an input, a field,
a file.'
errors:
anyOf:
- items:
$ref: '#/components/schemas/ProblemItem'
type: array
- type: 'null'
title: Errors
description: One item per fault, for a refusal with several, such as a request whose fields the route refuses. On
`/validate`, `/resolve`, `/codegen` and `/pipe-io` an invalid bundle is a **200** verdict instead, whose `errors`
are items of this same shape.
pipeline_run_id:
anyOf:
- type: string
- type: 'null'
title: Pipeline Run Id
description: The run the failure belongs to.
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: 'Correlation id, echoed in the `X-Request-ID` response header: the caller''s own when valid, else one
the runner mints.'
diagnostics:
anyOf:
- $ref: '#/components/schemas/ProblemDiagnostics'
- type: 'null'
description: 'What only the operator reads: the error''s class and message, its causes, the provider''s answer,
the model. Present only when the request was authenticated as the operator''s (`AUTH_MODE=api_key`, or a trusted
proxy).'
additionalProperties: true
type: object
required:
- type
- title
- status
- detail
- code
- domain
- retry
- next_step
title: ProblemDocument
description: 'An RFC 9457 `application/problem+json` error body — the shape of every failure response.
Every failure answers its problem document: the RFC''s members (`type`, `title`, `status`, `detail`), the MTHDS
core''s (`code`, `domain`, `retry`, `next_step`, always present, and `retry_after`, `params`, `location`, `errors`,
`pipeline_run_id` when they hold a value) and Pipelex''s (`request_id`, always present on a response of this server,
and `diagnostics` in the operator view alone). No member is ever written as `null`: a member with no value is
absent. `extra="allow"` mirrors RFC 9457''s open-ended extension-member rule.'
ProblemDomain:
type: string
enum:
- input
- method
- account
- operator
- runtime
title: ProblemDomain
description: 'Who must act: the protocol''s closed list of domains.'
ProblemEnsureTableOp:
properties:
kind:
type: string
const: ensure_table
title: Kind
table_path:
items:
type: string
type: array
minItems: 1
title: Table Path
additionalProperties: true
type: object
required:
- kind
- table_path
title: EnsureTableOp
description: Create the table at `table_path` when it is absent.
ProblemFixSafety:
type: string
enum:
- safe
- unsafe
title: FixSafety
description: Whether a suggested fix may be applied without asking anyone.
ProblemItem:
properties:
code:
type: string
pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,2}$
title: Code
detail:
type: string
title: Detail
params:
anyOf:
- $ref: '#/components/schemas/ProblemParams'
- type: 'null'
location:
anyOf:
- $ref: '#/components/schemas/ProblemLocation'
- type: 'null'
suggestions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Suggestions
suggested_fix:
anyOf:
- $ref: '#/components/schemas/ProblemSuggestedFix'
- type: 'null'
additionalProperties: true
type: object
required:
- code
- detail
title: ProblemItem
description: 'One fault of a problem with several, and one finding of a `/validate` verdict.
An item carries its own code but no verdict; `effective_domain` reads its domain from its code,
`code_spec` is the code''s registry entry and `params_as` reads the parameters as a model.'
ProblemLocation:
properties:
pipe:
anyOf:
- type: string
- type: 'null'
title: Pipe
path:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Path
input:
anyOf:
- type: string
- type: 'null'
title: Input
field:
anyOf:
- type: string
- type: 'null'
title: Field
item:
anyOf:
- type: integer
ge: 0
- type: 'null'
title: Item
attempt:
anyOf:
- type: integer
ge: 1
- type: 'null'
title: Attempt
file:
anyOf:
- type: string
- type: 'null'
title: File
line:
anyOf:
- type: integer
ge: 1
- type: 'null'
title: Line
column:
anyOf:
- type: integer
ge: 1
- type: 'null'
title: Column
additionalProperties: true
type: object
title: ProblemLocation
description: Where the error happened, in the method, the request or the run; every member is optional.
ProblemMoveKeyOp:
properties:
kind:
type: string
const: move_key
title: Kind
table_path:
items:
type: string
type: array
title: Table Path
key:
type: string
title: Key
new_table_path:
items:
type: string
type: array
title: New Table Path
new_key:
type: string
title: New Key
additionalProperties: true
type: object
required:
- kind
- table_path
- key
- new_table_path
- new_key
title: MoveKeyOp
description: Move `key` from the table at `table_path` into the table at `new_table_path` under `new_key`.
ProblemParams:
properties:
missing_blobs:
anyOf:
- items:
type: string
pattern: ^[0-9a-f]{64}$
type: array
- type: 'null'
title: Missing Blobs
additionalProperties: true
type: object
title: ProblemParams
description: 'The typed facts a problem''s sentences were written from.
Each code declares its own parameters, and the generated registry gives each core code a model of
them (`CORE_CODE_SPECS[code].params_model`), which `Problem.params_as` validates into. This model
types only the parameter the protocol types for every reader, `missing_blobs`; every other
parameter rides `model_extra` as received.'
ProblemRemapValueOp:
properties:
kind:
type: string
const: remap_value
title: Kind
table_path:
items:
type: string
type: array
title: Table Path
key:
type: string
title: Key
mapping:
additionalProperties:
type: string
type: object
minProperties: 1
title: Mapping
additionalProperties: true
type: object
required:
- kind
- table_path
- key
- mapping
title: RemapValueOp
description: Rewrite the string value of `key` in the table at `table_path` through `mapping`.
ProblemRenameTableKeyOp:
properties:
kind:
type: string
const: rename_table_key
title: Kind
table_path:
items:
type: string
type: array
title: Table Path
key:
type: string
title: Key
new_key:
type: string
title: New Key
additionalProperties: true
type: object
required:
- kind
- table_path
- key
- new_key
title: RenameTableKeyOp
description: Rename `key` to `new_key` within the table at `table_path`.
ProblemSetKeyOp:
properties:
kind:
type: string
const: set_key
title: Kind
table_path:
items:
type: string
type: array
title: Table Path
key:
type: string
title: Key
value:
anyOf:
- type: boolean
- type: integer
- type: number
- type: string
- additionalProperties:
anyOf:
- type: boolean
- type: integer
- type: number
- type: string
type: object
title: Value
additionalProperties: true
type: object
required:
- kind
- table_path
- key
- value
title: SetKeyOp
description: Write `key = value` in the table at `table_path`.
ProblemSuggestedFix:
properties:
fix_code:
type: string
pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
title: Fix Code
description:
type: string
title: Description
safety:
anyOf:
- $ref: '#/components/schemas/ProblemFixSafety'
- type: string
title: Safety
file:
anyOf:
- type: string
- type: 'null'
title: File
ops:
items:
oneOf:
- $ref: '#/components/schemas/ProblemSetKeyOp'
- $ref: '#/components/schemas/ProblemEnsureTableOp'
- $ref: '#/components/schemas/ProblemDeleteKeyOp'
- $ref: '#/components/schemas/ProblemDeleteTableOp'
- $ref: '#/components/schemas/ProblemRenameTableKeyOp'
- $ref: '#/components/schemas/ProblemMoveKeyOp'
- $ref: '#/components/schemas/ProblemRemapValueOp'
- $ref: '#/components/schemas/ProblemUnknownFixOp'
type: array
minItems: 1
title: Ops
additionalProperties: true
type: object
required:
- fix_code
- description
- safety
- ops
title: SuggestedFix
description: 'A deterministic fix for one fault: operations over a bundle of the method, addressed by TOML key path.'
ProblemUnknownFixOp:
properties:
kind:
type: string
title: Kind
additionalProperties: true
type: object
required:
- kind
title: UnknownFixOp
description: 'The reader-side catch-all: an operation whose `kind` is none the protocol lists, which an applier never
applies.'
PromptImageDetail:
type: string
enum:
- high
- low
- auto
title: PromptImageDetail
ProseField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
min_length:
anyOf:
- type: integer
- type: 'null'
title: Min Length
max_length:
anyOf:
- type: integer
- type: 'null'
title: Max Length
pattern:
anyOf:
- type: string
- type: 'null'
title: Pattern
format:
anyOf:
- type: string
- type: 'null'
title: Format
kind:
type: string
const: prose
title: Kind
default: prose
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- name
title: ProseField
description: '`prose` at a named position.'
ProseItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
min_length:
anyOf:
- type: integer
- type: 'null'
title: Min Length
max_length:
anyOf:
- type: integer
- type: 'null'
title: Max Length
pattern:
anyOf:
- type: string
- type: 'null'
title: Pattern
format:
anyOf:
- type: string
- type: 'null'
title: Format
kind:
type: string
const: prose
title: Kind
default: prose
additionalProperties: false
type: object
required:
- required
title: ProseItem
description: '`prose` — flowing free text.'
ProviderDiagnostics:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
status:
anyOf:
- type: integer
- type: 'null'
title: Status
code:
anyOf:
- type: string
- type: 'null'
title: Code
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
message:
anyOf:
- type: string
- type: 'null'
title: Message
additionalProperties: true
type: object
title: ProviderDiagnostics
description: What the inference provider said about a failed call, for an operator.
Quality:
type: string
enum:
- low
- medium
- high
title: Quality
Range:
properties:
start_offset:
type: integer
title: Start Offset
end_offset:
type: integer
title: End Offset
start_line:
type: integer
title: Start Line
start_col:
type: integer
title: Start Col
end_line:
type: integer
title: End Line
end_col:
type: integer
title: End Col
type: object
required:
- start_offset
- end_offset
- start_line
- start_col
- end_line
- end_col
title: Range
description: Byte offsets plus 1-based line/column coordinates from `pipelex-tools-py`.
ReasoningEffort:
type: string
enum:
- none
- minimal
- low
- medium
- high
- xhigh
- max
title: ReasoningEffort
RemapValueOp:
properties:
table_path:
items:
type: string
type: array
title: Table Path
kind:
type: string
const: remap_value
title: Kind
default: remap_value
key:
type: string
title: Key
mapping:
additionalProperties:
type: string
type: object
minProperties: 1
title: Mapping
additionalProperties: false
type: object
required:
- table_path
- key
- mapping
title: RemapValueOp
description: 'Rewrite ``key``''s value through ``mapping``, doing nothing when it is not a mapped value.
Only string values are remapped: the operation exists for renamed enumerated values, whose
TOML representation is always a string.
``key`` may be the wildcard segment, and this is the one kind for which it means anything:
"each key of the addressed table". A mapping from the user''s own keys to an enumerated value
— ``dict[str, LogLevel]`` — keeps its spellings under keys only the document can enumerate,
so no fixed ``key`` reaches them and this is the only shape in which a member renamed beneath
an open mapping can be repaired at all.'
RenameTableKeyOp:
properties:
table_path:
items:
type: string
type: array
title: Table Path
kind:
type: string
const: rename_table_key
title: Kind
default: rename_table_key
key:
type: string
title: Key
new_key:
type: string
title: New Key
additionalProperties: false
type: object
required:
- table_path
- key
- new_key
title: RenameTableKeyOp
description: Rename ``key`` to ``new_key`` in place within the addressed table, keeping its position.
ResolveValidReport:
properties:
is_valid:
type: boolean
const: true
title: Is Valid
default: true
crate:
additionalProperties: true
type: object
title: Crate
description: The normalized library crate (canonical JSON encoding, `fingerprint` included).
message:
type: string
title: Message
description: Status message
default: MTHDS library resolved successfully
type: object
required:
- crate
title: ResolveValidReport
description: 'The 200 **valid** arm: the normalized library crate, ready for any consumer''s emitter.
The crate rides as the canonical JSON encoding''s object form (top-level maps key-sorted,
non-semantic provenance dropped) — the same bytes `pipelex resolve --format json` prints, so a
fingerprint computed from either surface agrees. Its `fingerprint` and `mthds_version` members
ride inside the crate payload itself.'
RetryVerdict:
type: string
enum:
- 'no'
- 'yes'
- outcome_unknown
title: RetryVerdict
description: 'Whether repeating the operation can succeed: the protocol''s closed list of verdicts.'
RunState:
type: string
enum:
- STARTED
- RUNNING
- COMPLETED
- FAILED
- CANCELLED
- ERROR
title: RunState
description: Run lifecycle state — a pipelex extension field on run responses (the protocol defines none).
SearchSetting:
properties:
model:
type: string
title: Model
include_images:
type: boolean
title: Include Images
default: false
include_inline_citations:
type: boolean
title: Include Inline Citations
default: true
max_results:
anyOf:
- type: integer
minimum: 1.0
- type: 'null'
title: Max Results
description:
anyOf:
- type: string
- type: 'null'
title: Description
additionalProperties: false
type: object
required:
- model
title: SearchSetting
ServiceIdentity:
properties:
message:
type: string
title: Message
description: Name of the service answering on this origin.
type: object
required:
- message
title: ServiceIdentity
description: Body of `GET /` — the service identity banner.
SizeTier:
type: string
enum:
- 0.5k
- 1k
- 2k
- 4k
title: SizeTier
description: 'Portable image size classes.
A tier promises a pixel class at the pipe''s chosen aspect ratio, not identical
pixel dimensions across providers: each provider maps the tier to its own grid
or computed dimensions.'
SpecialOutcome:
type: string
enum:
- fail
- continue
title: SpecialOutcome
StepKind:
type: string
enum:
- retry
- wait
- read_run
- refresh
- change_input
- change_method
- change_model
- check_credentials
- request_access
- check_account
- fix_configuration
- upgrade
- contact_owner
- report
title: StepKind
description: 'What the reader does next: the protocol''s closed list of step kinds.'
StepRole:
type: string
enum:
- draft_text
- structure
title: StepRole
description: 'Role played by a synthetic pipe inside an elaborated bundle.
DRAFT_TEXT: step-1 of a `preliminary_text` elaboration — the pipe that produces the draft Text.
STRUCTURE: step-2 of a `preliminary_text` elaboration — the pipe that turns the draft Text into the structured concept.'
StructuringMethod:
type: string
enum:
- direct
- preliminary_text
title: StructuringMethod
Stuff:
properties:
stuff_code:
type: string
title: Stuff Code
stuff_name:
anyOf:
- type: string
- type: 'null'
title: Stuff Name
concept:
type: string
content:
$ref: '#/components/schemas/StuffContent'
additionalProperties: false
type: object
required:
- stuff_code
- concept
- content
title: Stuff
StuffContent:
properties: {}
type: object
title: StuffContent
SubPipeBlueprint:
properties:
pipe:
type: string
title: Pipe
result:
anyOf:
- type: string
- type: 'null'
title: Result
nb_output:
anyOf:
- type: integer
- type: 'null'
title: Nb Output
multiple_output:
anyOf:
- type: boolean
- type: 'null'
title: Multiple Output
batch_over:
anyOf:
- type: string
- type: 'null'
title: Batch Over
batch_as:
anyOf:
- type: string
- type: 'null'
title: Batch As
additionalProperties: false
type: object
required:
- pipe
title: SubPipeBlueprint
TagStyle:
type: string
enum:
- no_tag
- ticks
- xml
- square_brackets
title: TagStyle
TemplateBlueprint:
properties:
template:
type: string
title: Template
description: Raw template source
templating_style:
anyOf:
- $ref: '#/components/schemas/TemplatingStyle'
- type: 'null'
description: How the tag and format filters render in this template; omit it to take the runtime default templating
style
category:
$ref: '#/components/schemas/TemplateCategory'
description: Category of the template (could also be HTML, MARKDOWN, MERMAID, etc.), influences template rendering
rules
extra_context:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Extra Context
description: Additional context variables for template rendering
additionalProperties: false
type: object
required:
- template
- category
title: TemplateBlueprint
description: 'The rich form of a template: its Jinja2 source and category, plus an optional templating style and extra
context.'
TemplateCategory:
type: string
enum:
- basic
- expression
- html
- markdown
- mermaid
- llm_prompt
- img_gen_prompt
title: TemplateCategory
TemplatingStyle:
properties:
tag_style:
$ref: '#/components/schemas/TagStyle'
text_format:
$ref: '#/components/schemas/TextFormat'
default: plain
additionalProperties: false
type: object
required:
- tag_style
title: TemplatingStyle
description: 'How a pipe''s inputs are tagged and formatted into its prompt: a tag style and a text format.'
TextField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
min_length:
anyOf:
- type: integer
- type: 'null'
title: Min Length
max_length:
anyOf:
- type: integer
- type: 'null'
title: Max Length
pattern:
anyOf:
- type: string
- type: 'null'
title: Pattern
format:
anyOf:
- type: string
- type: 'null'
title: Format
kind:
type: string
const: text
title: Kind
default: text
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- name
title: TextField
description: '`text` at a named position — a top-level field or a structure field.'
TextFormat:
type: string
enum:
- plain
- markdown
- html
- json
title: TextFormat
TextItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
min_length:
anyOf:
- type: integer
- type: 'null'
title: Min Length
max_length:
anyOf:
- type: integer
- type: 'null'
title: Max Length
pattern:
anyOf:
- type: string
- type: 'null'
title: Pattern
format:
anyOf:
- type: string
- type: 'null'
title: Format
kind:
type: string
const: text
title: Kind
default: text
additionalProperties: false
type: object
required:
- required
title: TextItem
description: '`text` — a short single-line string.'
TimingSpec:
properties:
started_at:
type: string
format: date-time
title: Started At
ended_at:
type: string
format: date-time
title: Ended At
duration:
type: number
title: Duration
description: Duration in seconds, included in JSON serialization.
readOnly: true
additionalProperties: false
type: object
required:
- started_at
- ended_at
- duration
title: TimingSpec
description: Timing information for a node execution.
TokensUsageRecord:
properties:
model_type:
type: string
title: Model Type
inference_model_name:
type: string
title: Inference Model Name
inference_model_id:
type: string
title: Inference Model Id
pipe_code:
anyOf:
- type: string
- type: 'null'
title: Pipe Code
job_category:
anyOf:
- type: string
- type: 'null'
title: Job Category
unit_job_id:
anyOf:
- type: string
- type: 'null'
title: Unit Job Id
nb_tokens_by_category:
additionalProperties:
type: integer
type: object
title: Nb Tokens By Category
cost:
anyOf:
- type: number
- type: 'null'
title: Cost
started_at:
anyOf:
- type: string
- type: 'null'
title: Started At
completed_at:
anyOf:
- type: string
- type: 'null'
title: Completed At
additionalProperties: false
type: object
required:
- model_type
- inference_model_name
- inference_model_id
- nb_tokens_by_category
title: TokensUsageRecord
description: 'One client-facing usage record per inference call.
``extra="forbid"`` is deliberate: server-side emission is the shape authority, so an
accidental new field fails loudly here instead of silently widening the contract.
Enum-ish fields (``model_type``, ``job_category``, ``unit_job_id``, and the
``nb_tokens_by_category`` keys) are open sets on the wire, typed as plain strings —
runtime enum churn is non-breaking for clients.'
TreeFileRead:
properties:
tree_path:
type: string
title: Tree Path
description: The file's path from the root of the step's method tree, such as `templates/invoice.html`.
use:
$ref: '#/components/schemas/TreeFileUse'
description: 'What the step reads the file as: `template`, the template a PipeDocGen step fills; `template_asset`,
an image, a stylesheet or a font its HTML template names; `python_module`, the module of the function a PipeFunc
step calls.'
additionalProperties: false
type: object
required:
- tree_path
- use
title: TreeFileRead
description: 'A file of its method tree a step reads: its tree path, and what the step reads it as.'
TreeFileUse:
type: string
enum:
- template
- template_asset
- python_module
title: TreeFileUse
description: What a step reads a file of its method tree as.
UnexplainedPath:
properties:
path:
type: string
title: Path
note:
type: string
title: Note
additionalProperties: false
type: object
required:
- path
- note
title: UnexplainedPath
description: 'A path the current schema does not know and no ledger entry removes.
Populated by the downgrade diagnosis, which lands with the commands: the file is either
carrying a typo or was written by a newer pipelex than the one running.'
UnknownField:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: unknown
title: Kind
default: unknown
name:
type: string
title: Name
additionalProperties: false
type: object
required:
- required
- name
title: UnknownField
description: '`unknown` at a named position.'
UnknownItem:
properties:
title:
anyOf:
- type: string
- type: 'null'
title: Title
concept_ref:
anyOf:
- type: string
- type: 'null'
title: Concept Ref
refines:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Refines
description:
anyOf:
- type: string
- type: 'null'
title: Description
required:
type: boolean
title: Required
presence:
anyOf:
- $ref: '#/components/schemas/PresenceMarker'
- type: 'null'
gating:
anyOf:
- type: boolean
- type: 'null'
title: Gating
default_value:
title: Default Value
examples:
anyOf:
- items: {}
type: array
- type: 'null'
title: Examples
hints:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Hints
kind:
type: string
const: unknown
title: Kind
default: unknown
additionalProperties: false
type: object
required:
- required
title: UnknownItem
description: '`unknown` — not honestly describable as any other kind.
The mandatory escape hatch that makes a total derivation truthful: a renderer falls back to raw
entry against the slot''s `json_schema` in the pipe I/O contract.'
UploadTarget:
properties:
method:
type: string
title: Method
description: The HTTP method, such as PUT.
url:
type: string
title: Url
description: 'Where to send the bytes: this runner''s own `PUT /v1/blobs/{sha256}`, with a signed query.'
headers:
additionalProperties:
type: string
type: object
title: Headers
description: The headers to send, exactly.
type: object
required:
- method
- url
- headers
title: UploadTarget
description: 'Where to upload one blob: send its bytes as the whole body of a request with this method to this URL,
with exactly these headers.'
ValidReport:
properties:
is_valid:
type: boolean
const: true
title: Is Valid
default: true
warnings:
items:
$ref: '#/components/schemas/ProblemItem'
type: array
title: Warnings
description: 'Advisory findings on the valid bundle, one problem item each, with the code the finding''s type names:
they never flip `is_valid`. The same item shape as the invalid arm''s `errors`.'
bundle_blueprint:
$ref: '#/components/schemas/PipelexBundleBlueprint'
pipe_io_contracts:
additionalProperties:
$ref: '#/components/schemas/PipeIOContract'
type: object
title: Pipe Io Contracts
input_form:
additionalProperties:
$ref: '#/components/schemas/PipeInputFormDescriptor'
type: object
title: Input Form
description: 'Opt-in Pipelex-API structured view: per-pipe input-form descriptors keyed exactly like `pipe_io_contracts`,
present only when the request''s `views` includes `input_form`. Absent by default — the structured contract fields
remain the verdict; this is a projection of them.'
output_form:
additionalProperties:
$ref: '#/components/schemas/PipeOutputFormDescriptor'
type: object
title: Output Form
description: 'Opt-in Pipelex-API structured view: per-pipe output-form descriptors keyed exactly like `pipe_io_contracts`,
present only when the request''s `views` includes `output_form`. Absent by default. Read with the output contract''s
`json_schema`, which states the shape of the payload this descriptor describes.'
liftable_pipes:
items:
$ref: '#/components/schemas/LiftablePipeEntry'
type: array
title: Liftable Pipes
tree_files_read:
additionalProperties:
items:
$ref: '#/components/schemas/TreeFileRead'
type: array
type: object
title: Tree Files Read
description: 'Per pipe, the files of the method''s tree the step reads, keyed by namespaced `pipe_ref` like `pipe_io_contracts`:
each file by its tree path, with what the step reads it as. A PipeDocGen step reads its template and the images,
stylesheets and fonts its HTML template names by literal relative URLs; a PipeFunc step reads the module of its
function. A pipe that reads no file of the tree, a controller included, has an empty list.'
tree_file_readers:
additionalProperties:
items:
type: string
type: array
type: object
title: Tree File Readers
description: 'The per-file view of `tree_files_read`: each tree path a step reads, in sorted order, to the namespaced
refs of the pipes that read it. A file of the method''s tree absent here is read by no step.'
graph_spec:
anyOf:
- $ref: '#/components/schemas/GraphSpec'
- type: 'null'
validated_pipes:
items:
$ref: '#/components/schemas/ValidatedPipeEntry'
type: array
title: Validated Pipes
pending_signatures:
items:
type: string
type: array
title: Pending Signatures
is_runnable:
type: boolean
title: Is Runnable
default: true
mthds_contents:
items:
type: string
type: array
title: Mthds Contents
description: 'The MTHDS contents that were validated: the request''s `mthds_contents`, or the texts of a method
tree''s `.mthds` bundles in tree path order.'
message:
type: string
title: Message
description: Status message
default: MTHDS content validated successfully
default_pipe_ref:
anyOf:
- type: string
- type: 'null'
title: Default Pipe Ref
description: 'The qualified `domain.pipe_code` a caller gets by omitting the pipe selector — the pipe a selector-less
run of THIS request would execute. For a method tree (`files` or a `method_ref`) it is the tree''s entry pipe
by the MTHDS protocol''s rule: the `main_pipe` of the `METHODS.toml` at its root, else the one `main_pipe` its
bundles declare. For inline `mthds_contents` it is the closure''s primary blueprint''s `main_pipe` qualified by
its domain. Absent when no entry pipe is determined, in which case a selector-less run would be refused too.'
rendered_markdown:
anyOf:
- type: string
- type: 'null'
title: Rendered Markdown
description: 'Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the valid verdict, present
only when the request''s `render` includes `markdown`. Absent by default — the structured fields remain the contract;
this is the view.'
additionalProperties: true
type: object
required:
- bundle_blueprint
- mthds_contents
title: ValidReport
description: 'The 200 **valid** arm: the canonical `PipelexValidationReport` plus this server''s wire-only extras.
The report fields are inherited — typed models, identical to what the local runtime
returns for the same bundle, with `is_valid: Literal[True]` (from the report) as the union
discriminant. The extras exist for HTTP clients only (the webapp reads back `mthds_contents`);
they are NOT part of the canonical report and no in-process consumer should depend on them.
`warnings` is re-declared as problem items: the canonical report holds the advisory findings as the validation
items the local channels render, and the wire carries each as the problem item its type''s code makes
(`pipelex.pipeline.validation_errors.warning_problem_items`), the item shape `errors` has on the invalid arm.
Two inherited fields are deliberately re-declared: `input_form` and `output_form`. The canonical
report requires both (a backend that forgets to derive one must fail loudly rather than ship an
empty view), but on the wire each is an opt-in structured view gated by the request''s `views` —
so both are re-declared with defaults here, keeping them out of the published schema''s `required`
set. The values still always arrive from the report; the route pops each when its token was not
requested. They are separate tokens rather than one because they answer separate questions: a
caller building a fill-in form wants the inputs, a caller rendering a result or registering a
tool signature wants the output, and neither should pay for the other.'
ValidateRequest:
properties:
analytics_groups:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Analytics Groups
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied groups the caller of this
request belongs to, as a mapping of group type to group key (e.g. `{"organization": "org_acme"}`), exactly as
a run request states them. The work this request does is not a run, but it still emits telemetry — the validation
sweep''s `pipe_dry_run` event and its dry runs — and that telemetry is attributed to the caller: the authenticated
user and these groups. Same rules and same 422 `InvalidAnalyticsGroups` refusal as on `/execute` and `/start`.
Omit it and the caller belongs to no group.'
mthds_contents:
anyOf:
- items:
type: string
type: array
maxItems: 16
minItems: 1
- type: 'null'
title: Mthds Contents
description: 'Being retired, and refused by a later release: send the method in `files`. MTHDS contents to load
(always an array, even for a single file). Exactly one of `mthds_contents` / `files` / `method_ref`.'
files:
anyOf:
- additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
- type: 'null'
title: Files
description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. The whole tree is validated, its
Python included, by syntax. Exactly one of `mthds_contents` / `files` / `method_ref`.'
dependencies:
anyOf:
- additionalProperties:
additionalProperties:
anyOf:
- type: string
- $ref: '#/components/schemas/Base64FileEntry'
- $ref: '#/components/schemas/HashFileEntry'
type: object
type: object
- type: 'null'
title: Dependencies
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
method_ref:
anyOf:
- type: string
maxLength: 512
minLength: 1
- type: 'null'
title: Method Ref
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — validate a published method by reference
instead of inline contents. Address form: `github.com/<owner>/<repo>[/<selector>][@<tag>]`, resolved by THIS runner
through the same fetch path as a `method_ref` run; the package''s tree, read from its commit, is validated as
a `files` tree is. Exactly one of `mthds_contents` / `files` / `method_ref`. A resolution failure (fetch, package
location, the custom-Python policy) is a non-2xx `problem+json` — never an `is_valid: false` verdict, which is
reserved for actual MTHDS content.'
allow_signatures:
type: boolean
title: Allow Signatures
description: When true, the validation sweep tolerates unimplemented pipe signatures instead of rejecting the bundle
(signatures dry-run trivially by minting a mock). Defaults to false (strict).
default: false
mthds_sources:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Mthds Sources
description: 'Being retired with `mthds_contents`, and refused by a later release: the bundles of a method sent
in `files` are named by their tree paths. Optional per-file sources, parallel to `mthds_contents`. When provided,
each entry is threaded onto the corresponding bundle''s `source` so server-side validation errors carry a `source`
pointing at the owning file. Must match `mthds_contents` in length when present.'
resources:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Resources
description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
(an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
`MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
retired with `mthds_contents`, and refused by a later release: send these files in the method''s tree, in `files`.'
render:
items:
type: string
type: array
title: Render
description: 'Opt-in Pipelex-API presentation extra: view formats to render server-side. A supported token (`markdown`)
adds a `rendered_<format>` field (e.g. `rendered_markdown`) to the 200 verdict, on both the valid and invalid
arms. Unknown/unsupported tokens are silently ignored (presentation hint, not part of the verdict contract); the
default empty list renders nothing and the response is unchanged.'
views:
items:
type: string
type: array
title: Views
description: 'Opt-in Pipelex-API structured views: extra projections to attach to the 200 verdict. A supported token
(`input_form`, `output_form`) adds a **same-named** top-level field to the valid arm only. Unknown/unsupported
tokens are silently ignored (a view is a projection of facts the verdict already determined, not part of the verdict
contract); the default empty list attaches nothing and the response is byte-identical to a request that omits
the field. Independent of `render`: a request may carry both, each resolving its own tokens.'
orchestration_mode:
anyOf:
- type: string
- type: 'null'
title: Orchestration Mode
description: 'Optional per-request orchestration-mode (backend) override for the validation dispatch (same plumbing
as `/start`). An OPEN string token: `direct` validates in-process; a `temporal` mode dispatches the whole job
to a worker; any plugin-provided token is accepted and an unregistered one is refused at dispatch. Honored only
when the deployment sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token
that differs from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
Omitted → the default.'
read_scope:
anyOf:
- type: string
- type: 'null'
title: Read Scope
description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the validation reads the method
under, as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry
of `files` resolves in that scope''s blob store, the tree the validation read is recorded there, and the runner
hands the scope to its validator, so a validation dispatched to a worker hands it the method through that store.
Omit it and a hash entry resolves in the caller''s own id''s store, but nothing is recorded and the validator
is handed no scope, so a dry run without one leaves nothing stored.'
type: object
title: ValidateRequest
description: 'The method to validate, in `files`, by `method_ref` or as `mthds_contents`, plus `allow_signatures` and
optional per-file sources.
`mthds_contents`, and the `mthds_sources` and `resources` that serve it, are being retired: a later release
refuses them, and a method is sent in `files`, whose bundles are named by their tree paths.
`mthds_sources`, when provided, pairs each `mthds_contents[i]` with a logical source (e.g. the
file''s path relative to the submitted directory). The runner threads it onto
`blueprint.source`, so the problem items in `errors` on a 200 `InvalidReport` carry a real
`location.file` the client maps back to the owning file — without it the in-memory load path
leaves the file unknown and cross-file diagnostics misfire. Omit it and behavior is unchanged.'
ValidatedPipeEntry:
properties:
pipe_ref:
type: string
title: Pipe Ref
status:
$ref: '#/components/schemas/DryRunStatus'
additionalProperties: true
type: object
required:
- pipe_ref
- status
title: ValidatedPipeEntry
description: 'One entry in the ``validated_pipes`` JSON envelope returned by the validate surfaces.
The ``pipe_ref`` key carries the namespaced ``pipe_ref`` (``domain.code``) — never the bare code.
``status`` is a ``DryRunStatus`` (a ``StrEnum``), so it serializes to its plain string value.'
WaterfallMatch:
properties:
category:
$ref: '#/components/schemas/ModelCheckCategory'
description: The category this entry is about.
resolves_to:
anyOf:
- type: string
- type: 'null'
title: Resolves To
description: The model handle a run through the reference would call now in this category, or null when it would
find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
serves, an alias cycle).
fallbacks:
items:
type: string
type: array
title: Fallbacks
description: The waterfall's steps, in order.
additionalProperties: false
type: object
required:
- category
- resolves_to
- fallbacks
title: WaterfallMatch
description: What a waterfall reference is in one category.
WorkingMemory:
properties:
root:
additionalProperties:
$ref: '#/components/schemas/Stuff'
type: object
title: Root
aliases:
additionalProperties:
type: string
type: object
title: Aliases
absences:
additionalProperties:
$ref: '#/components/schemas/AbsenceRecord'
type: object
title: Absences
additionalProperties: false
type: object
title: WorkingMemory