pipelex-api 0.71.0__py3-none-any.whl

pipelex_api/openapi_responses.py

@@ -0,0 +1,186 @@
+"""Documentation-only models and shared `responses=` declarations for the API's RFC 7807 errors.
+
+Every failure this server emits is an `application/problem+json` document built
+by the global handlers in `pipelex_api.exception_handlers` — from a pipelex
+`ErrorReport` (`build_problem_document`) or from an API-authored `ApiError`
+(`build_problem_document_from_api_error`). Neither path validates through a
+Pydantic model: they build plain dicts. The models here exist **only** so the
+committed OpenAPI artifact can publish that shape with a real schema instead of
+an untyped `additionalProperties: true` blob — nothing in the request path
+imports them, and adding a field here does not change a single response byte.
+Keep them in step with `docs/error-responses.md`, which is the prose contract.
+
+`ProblemDocument.validation_errors` reuses pipelex's own `ValidationErrorItem`,
+so the item shape published on the error wire is the same one `/validate`'s 200
+invalid arm publishes — including `suggested_fix`, which rides along for free.
+
+The response dicts below are attached two ways:
+
+- `COMMON_PROBLEM_RESPONSES` goes on the composite router in `pipelex_api.routes`, so
+  every auth-wrapped `/v1` operation documents the four failures any of them can
+  produce. Declaring a `422` there also suppresses FastAPI's automatic
+  `HTTPValidationError` response, which advertised the wrong media type and the
+  wrong schema on nearly every route.
+- The single-status constants go on the routes that can additionally produce
+  them (`responses=` on the decorator merges over the router-level set).
+
+The media type is NOT set here. FastAPI renders a `responses` entry's `model`
+under the route's own response-class media type (`application/json`), with no
+per-response override; `PipelexFastAPI.openapi()` in `pipelex_api.openapi_schema`
+re-keys every 4xx/5xx response onto `application/problem+json` (via
+`use_problem_json_media_type`) after the schema is generated.
+"""
+
+from typing import Any
+
+from pipelex.base_exceptions import ValidationErrorItem
+from pipelex.cogt.inference.error_classification import ProviderErrorMetadata, UserAction
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProblemDocument(BaseModel):
+    """An RFC 7807 `application/problem+json` error body — the shape of every failure response.
+
+    Standard RFC 7807 members (`type`, `title`, `status`, `detail`, `instance`)
+    plus the extension members pipelex's classification adds. Only `type`,
+    `title`, `status`, `detail`, and `error_type` are always present: the rest
+    ride along when the originating error populates them, so a consumer must
+    treat them as optional. `extra="allow"` mirrors RFC 7807's open-ended
+    extension-member rule.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str = Field(..., description="Stable URI for the error class: `https://docs.pipelex.com/latest/errors/<kebab-class-name>/`.")
+    title: str = Field(..., description="Short, human-readable summary of the error class.")
+    status: int = Field(..., description="HTTP status code, repeated in the body per RFC 7807.")
+    detail: str = Field(..., description="Human-readable explanation of this specific failure. Redacted under `ERROR_DISCLOSURE=strict`.")
+    instance: str | None = Field(default=None, description="Path of the request that failed.")
+    request_id: str | None = Field(default=None, description="Correlation id, echoed in the `X-Request-ID` response header.")
+    error_type: str = Field(..., description="Stable class name of the originating error (e.g. `ValidateBundleError`, `Unauthenticated`).")
+    error_domain: str | None = Field(
+        default=None,
+        description="`input` (caller can fix it → 422), `config` or `runtime` (deployment must fix it → 500). Absent for domain-less errors.",
+    )
+    retryable: bool | None = Field(
+        default=None,
+        description=(
+            "Whether retrying the same request can plausibly succeed. Always present on API-authored errors; "
+            "on pipelex errors only when the originating error classifies it."
+        ),
+    )
+    error_category: str | None = Field(default=None, description="Finer classification, when the originating error provides one (inference errors).")
+    user_action: UserAction | None = Field(default=None, description="Structured suggestion of what the caller should do next, when available.")
+    model: str | None = Field(default=None, description="Inference model that failed. Stripped under `ERROR_DISCLOSURE=strict`.")
+    provider: str | None = Field(default=None, description="Inference provider that failed. Stripped under `ERROR_DISCLOSURE=strict`.")
+    provider_metadata: ProviderErrorMetadata | None = Field(
+        default=None,
+        description="Upstream provider error metadata. Stripped (bar a curated slice) under `ERROR_DISCLOSURE=strict`.",
+    )
+    validation_errors: list[ValidationErrorItem] | None = Field(
+        default=None,
+        description=(
+            "Structured per-error diagnostics, carried by a `ValidateBundleError`. Each item may carry a `suggested_fix`. "
+            "Retained under `ERROR_DISCLOSURE=strict` — it describes the caller's own bundle, not server internals. "
+            "On `/validate`, `/resolve`, `/codegen` and `/build/*` an invalid bundle is a **200** verdict instead, so the "
+            "items ride the response body there rather than a problem document."
+        ),
+    )
+
+
+def _problem(description: str, *, headers: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Build one `responses=` entry documenting a `ProblemDocument` failure.
+
+    `model` registers `ProblemDocument` in the artifact's components and emits a
+    `$ref` to it; `PipelexFastAPI.openapi()` (`pipelex_api.openapi_schema`) then moves
+    the schema onto the `application/problem+json` media type.
+    """
+    response: dict[str, Any] = {"description": description, "model": ProblemDocument}
+    if headers is not None:
+        response["headers"] = headers
+    return response
+
+
+PROBLEM_400_START_REQUIRES_ASYNC: dict[str, Any] = _problem(
+    "`StartRequiresAsyncOrchestration` — this deployment's orchestrator is blocking-only and cannot honor "
+    "fire-and-forget delivery. Use `POST /execute` instead.",
+)
+
+PROBLEM_401: dict[str, Any] = _problem(
+    "Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`).",
+    headers={
+        "WWW-Authenticate": {
+            "description": "Authentication challenge — always `Bearer`.",
+            "schema": {"type": "string"},
+        }
+    },
+)
+
+PROBLEM_403_RUN_POLICY: dict[str, Any] = _problem(
+    "A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an "
+    "`orchestration_mode` this deployment does not allow overriding per request "
+    "(`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox` — the method (a bundle, or a "
+    "fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted; or "
+    "`MethodStructuresRefusedError` — the method's Python declares structure classes (`StructuredContent` "
+    "subclasses), whether it arrived as a bundle (`files` or `bundle_b64`) or as a fetched `method_ref` package: "
+    "a sandbox-hosted deployment imports no caller Python into its own process, so it refuses them before "
+    "loading anything (express the types as MTHDS concepts instead).",
+)
+
+PROBLEM_409_DUPLICATE_RUN: dict[str, Any] = _problem(
+    "`PipelineManagerAlreadyExistsError` — 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.",
+)
+
+PROBLEM_413: dict[str, Any] = _problem(
+    "Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).",
+)
+
+PROBLEM_422: dict[str, Any] = _problem(
+    "The request could not be processed: a malformed body, a field failing validation, or an `input`-domain pipelex "
+    "error (a `.mthds` bundle the caller must fix). Note that on the diagnostic routes an *invalid bundle* is a **200** "
+    "verdict, not a 422 — see each route's response contract.",
+)
+
+PROBLEM_429: dict[str, Any] = _problem(
+    "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"},
+        }
+    },
+)
+
+PROBLEM_500: dict[str, Any] = _problem(
+    "A `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML override, a "
+    "backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.",
+)
+
+PROBLEM_501_ASYNC_NOT_ENABLED: dict[str, Any] = _problem(
+    "`AsyncExecutionNotEnabledError` — this deployment does not provide async pipeline execution. Permanent under the "
+    "current deployment; do not retry.",
+)
+
+PROBLEM_404_METHOD_PACKAGE: dict[str, Any] = _problem(
+    "`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches the "
+    "requested address by manifest identity. The message lists the packages the repository does contain.",
+)
+
+PROBLEM_501_METHOD_REF: dict[str, Any] = _problem(
+    "`MethodRefNotSupported` — the request selected its closure by a **registry-form** `method_ref` (not a "
+    "`github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference "
+    "or submit inline `files[]` instead.",
+)
+
+
+# Attached to the composite `/v1` router (`pipelex_api.routes`), so every auth-wrapped operation documents
+# the failures any of them can produce: the router-level auth check (401), the body-size middleware
+# (413), request-shape and input-domain rejections (422), and the server-fault floor (500). Declaring
+# the 422 here is also what suppresses FastAPI's automatic `HTTPValidationError` response.
+COMMON_PROBLEM_RESPONSES: dict[int | str, dict[str, Any]] = {
+    401: PROBLEM_401,
+    413: PROBLEM_413,
+    422: PROBLEM_422,
+    500: PROBLEM_500,
+}

pipelex_api/openapi_schema.py

@@ -0,0 +1,83 @@
+"""The FastAPI subclass that publishes this API's error responses under the right media type.
+
+Every failure the API emits is an RFC 7807 `application/problem+json` document — that is the
+whole contract of `pipelex_api.exception_handlers`. But FastAPI renders a `responses` entry's `model`
+under the **route's** response-class media type (`application/json` for every route here) and
+offers no per-response override (`route_response_media_type` in `fastapi.openapi.utils`). Left
+alone, the published artifact would therefore promise `application/json` on every error — a
+contract the server never honors.
+
+Hand-writing the media type into each `responses` entry would mean hand-writing a `$ref` too,
+forfeiting FastAPI's component registration for `ProblemDocument` (`pipelex_api.openapi_responses`). So
+the schema is generated normally and the error responses are re-keyed afterwards, in
+`PipelexFastAPI.openapi()` — FastAPI's documented "Extending OpenAPI" seam, and the single place
+the API asserts the error media type. It holds for the live `/openapi.json` and for the committed
+YAML alike: both go through `openapi()`.
+
+Deliberately import-side-effect-free, mirroring `pipelex_api.exception_handlers`: no env var reads, no app
+construction, no router wiring. That is what lets a test build a production-faithful app —
+one that renders the error media type the way the real server does — without dragging in
+`pipelex_api.main`'s startup chain (`Pipelex.make`, `get_auth_dependency`, the `ERROR_DISCLOSURE`
+fail-fast), so a misconfigured env var cannot crash collection of every module that needs the
+app class.
+"""
+
+from typing import Any
+
+from fastapi import FastAPI
+from typing_extensions import override
+
+from pipelex_api.problem_document import PROBLEM_JSON_MEDIA_TYPE
+
+# HTTP methods that carry an operation object in an OpenAPI path item. A path item can also hold
+# non-operation keys (`parameters`, `summary`, `servers`), so the pass below iterates this set
+# rather than every key it finds.
+_OPENAPI_OPERATION_KEYS = frozenset({"get", "put", "post", "delete", "options", "head", "patch", "trace"})
+
+
+def _is_error_status(status_code: str) -> bool:
+    """Whether an OpenAPI response key denotes a 4xx/5xx status.
+
+    Response keys are strings, and beyond the numeric ones OpenAPI allows the wildcard forms
+    (`4XX`, `5XX`) and `default`. This server declares only numeric statuses, so anything
+    non-numeric is left alone rather than guessed at.
+    """
+    return status_code.isdigit() and int(status_code) >= 400
+
+
+def use_problem_json_media_type(schema: dict[str, Any]) -> None:
+    """Re-key every documented 4xx/5xx response onto `application/problem+json`, in place.
+
+    See the module docstring for why this is a post-pass rather than a per-response declaration.
+    """
+    for path_item in schema.get("paths", {}).values():
+        for method, operation in path_item.items():
+            if method not in _OPENAPI_OPERATION_KEYS:
+                continue
+            for status_code, response in operation.get("responses", {}).items():
+                if not _is_error_status(status_code):
+                    continue
+                content: dict[str, Any] | None = response.get("content")
+                if content is None:
+                    continue
+                json_content = content.pop("application/json", None)
+                if json_content is not None:
+                    content[PROBLEM_JSON_MEDIA_TYPE] = json_content
+
+
+class PipelexFastAPI(FastAPI):
+    """The app class. Stock FastAPI, extended only to publish errors as `application/problem+json`."""
+
+    @override
+    def openapi(self) -> dict[str, Any]:
+        """The OpenAPI schema, with every documented 4xx/5xx moved onto `application/problem+json`.
+
+        The early return keeps the rewrite a one-shot: the base builds the schema and caches it on
+        `self.openapi_schema`, returning that same dict, so mutating it in place fixes up the cached
+        copy and every later call short-circuits here.
+        """
+        if self.openapi_schema is not None:
+            return self.openapi_schema
+        schema = super().openapi()
+        use_problem_json_media_type(schema)
+        return schema

pipelex_api/problem_document.py

@@ -0,0 +1,134 @@
+"""RFC 7807 problem-document construction.
+
+A pure module — no FastAPI imports, no I/O. It turns the two error sources of
+the API into the single `application/problem+json` body shape clients see:
+
+- `build_problem_document` — for a pipelex `ErrorReport`. Delegates to
+  `ErrorReport.to_problem_document(...)`: pipelex owns the field mapping
+  (standard RFC 7807 slots plus classification extension members) and the
+  `disclosure_mode` redaction. The API only chooses the disclosure mode and
+  supplies the request context.
+- `build_problem_document_from_api_error` — for an API-authored 4xx that has
+  no `ErrorReport` behind it (`raise_validation_error` and friends in
+  `pipelex_api.errors`). Built from the static `ErrorType` enum; always `INPUT` domain.
+
+Both return a plain `dict` the caller serializes as `application/problem+json`.
+"""
+
+from typing import Any
+
+from pipelex.base_exceptions import DisclosureMode, ErrorDomain, ErrorReport
+
+from pipelex_api.error_types import ErrorType
+from pipelex_api.error_uri import error_type_title, error_type_uri
+
+# Content type for every error response — RFC 7807 problem documents. Lives
+# here, the module that builds them, so the FastAPI app, the middleware, and
+# the error handlers can all reference one constant without a circular import.
+PROBLEM_JSON_MEDIA_TYPE = "application/problem+json"
+
+
+def build_problem_document(
+    report: ErrorReport,
+    *,
+    instance: str | None,
+    request_id: str | None,
+    disclosure_mode: DisclosureMode,
+) -> dict[str, Any]:
+    """Build an RFC 7807 problem document from a pipelex `ErrorReport`.
+
+    Thin wrapper over `ErrorReport.to_problem_document(...)`: the field mapping
+    and the `disclosure_mode` redaction both live upstream in pipelex. The
+    API's only responsibility is to choose the disclosure mode and pass the
+    request context through.
+    """
+    return report.to_problem_document(
+        instance=instance,
+        request_id=request_id,
+        disclosure_mode=disclosure_mode,
+    )
+
+
+def build_problem_document_from_api_error(
+    error_type: ErrorType,
+    message: str,
+    status: int,
+    *,
+    instance: str | None,
+    request_id: str | None,
+    error_domain: ErrorDomain | None = ErrorDomain.INPUT,
+    retryable: bool = False,
+) -> dict[str, Any]:
+    """Build an RFC 7807 problem document for an API-authored error.
+
+    Used by the `pipelex_api.errors` 4xx/5xx helpers, whose failures are the API's own
+    request validation, auth, or configuration checks rather than a pipelex
+    domain error — there is no `ErrorReport` to delegate to. The `type` URI and
+    `title` are derived from the static `ErrorType` enum the same way pipelex
+    derives them for its own classes, so the standard RFC 7807 slots and the
+    `error_type` / `error_domain` members line up with what a pipelex error
+    renders.
+
+    Extension-member parity with a pipelex `ErrorReport` is by-field, not
+    wholesale, with two distinct rules:
+
+    - `retryable` is emitted unconditionally here (every API-authored error is
+      non-retryable; see below). pipelex emits it only when the source error
+      populated it, so a non-inference pipelex report (`PipelexConfigError`,
+      `EnvVarNotFoundError`) renders with no `retryable`. Asymmetric by design:
+      the API knows the answer for every error it authors, and clients can
+      drive retry logic uniformly without branching on field presence.
+    - Classification fields pipelex sets only on classifiable failures
+      (`error_category`, `user_action`, `model`, `provider`, `provider_metadata`)
+      are NOT manufactured here. The same omission rule pipelex applies to its
+      own non-inference reports (`PipelexConfigError`, `EnvVarNotFoundError`
+      carry no `error_category` either) — surfacing a fake category for an
+      API-authored validation or auth failure would lie about what the API
+      actually classified.
+
+    `error_domain` defaults to `INPUT` — the caller can fix a 4xx. API-owned
+    5xx (a missing secret, a misconfigured backend) pass `CONFIG`: an operator,
+    not the caller, fixes those. `None` omits the member entirely, matching how
+    a domain-less pipelex error renders.
+
+    `retryable` defaults to `False`: every error this builder authors is a
+    caller-input mistake or a server misconfiguration, neither of which a blind
+    retry fixes. Carried as a positional contract member rather than dropped on
+    `None`, so clients can drive retry logic uniformly without branching on
+    field presence.
+
+    `None`-valued context (`instance`, `request_id`) is dropped rather than
+    emitted as `null`, matching `ErrorReport.to_problem_document` semantics.
+    """
+    document: dict[str, Any] = {
+        "type": error_type_uri(error_type),
+        "title": error_type_title(error_type),
+        "status": status,
+        "detail": message,
+    }
+    if instance is not None:
+        document["instance"] = instance
+    if request_id is not None:
+        document["request_id"] = request_id
+    document["error_type"] = error_type
+    if error_domain is not None:
+        document["error_domain"] = error_domain
+    document["retryable"] = retryable
+    return document
+
+
+def with_request_context(document: dict[str, Any], *, instance: str | None, request_id: str | None) -> dict[str, Any]:
+    """Return a copy of a problem document carrying the two request-scoped members.
+
+    The `pipelex_api.errors` helpers build their document where no `Request` is in hand — a validation
+    check deep inside a route, an auth refusal — so `instance` and `request_id` are stamped later,
+    by the handler that renders the response and does hold the request. A copy rather than an
+    in-place edit, because the `ApiError` a caller catches and inspects must read exactly as it was
+    raised. `None` is dropped rather than emitted as `null`, the rule every builder here follows.
+    """
+    stamped = dict(document)
+    if instance is not None:
+        stamped["instance"] = instance
+    if request_id is not None:
+        stamped["request_id"] = request_id
+    return stamped

pipelex_api/routes/__init__.py

@@ -0,0 +1,23 @@
+from fastapi import APIRouter
+
+from pipelex_api.openapi_responses import COMMON_PROBLEM_RESPONSES
+
+from .pipelex import router as pipelex_router
+
+# NOTE: the version router is NOT composed here — `GET /version` is always
+# public (protocol handshake), so `pipelex_api.main` mounts it under `/v1` directly,
+# WITHOUT the auth dependency this composite router gets wrapped in.
+#
+# `responses=` here merges into EVERY operation composed below (FastAPI's
+# `include_router` folds the including router's `responses` into each route's
+# own, route-level entries winning on a status collision). It documents the four
+# failures every auth-wrapped `/v1` route shares — 401 from the router-level auth
+# dependency `pipelex_api.main` wraps this in, 413 from the body-size middleware, 422 for
+# request-shape/input-domain rejections, 500 for the server-fault floor — so each
+# route only has to declare the extra statuses it alone can produce. Declaring the
+# 422 is also what suppresses FastAPI's automatic `HTTPValidationError` response,
+# whose media type (`application/json`) and schema both contradict the RFC 7807
+# document the global handlers actually emit.
+router = APIRouter(responses=COMMON_PROBLEM_RESPONSES)
+
+router.include_router(pipelex_router)

pipelex_api/routes/health.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter
+from pydantic import BaseModel, Field
+
+router = APIRouter(tags=["health"])
+
+
+class HealthResponse(BaseModel):
+    """Body of `GET /health`."""
+
+    status: str = Field(..., description="Always `ok` — the endpoint answers only when the process is serving.")
+    message: str = Field(..., description="Human-readable confirmation that the server is up.")
+
+
+@router.get("/health", summary="Liveness probe")
+async def get_health() -> HealthResponse:
+    """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.
+    """
+    return HealthResponse(status="ok", message="Pipelex API is running")

pipelex_api/routes/pipelex/__init__.py

@@ -0,0 +1,21 @@
+from fastapi import APIRouter
+
+from .agent import router as agent_router
+from .build import router as build_router
+from .codegen import router as codegen_router
+from .pipe_io import router as pipe_io_router
+from .pipeline import router as pipeline_router
+from .resolve import router as resolve_router
+from .tools import router as tools_router
+from .validate import router as validate_router
+
+router = APIRouter()
+
+router.include_router(build_router)
+router.include_router(pipeline_router)
+router.include_router(validate_router)
+router.include_router(resolve_router)
+router.include_router(pipe_io_router)
+router.include_router(codegen_router)
+router.include_router(tools_router)
+router.include_router(agent_router)

pipelex_api/routes/pipelex/agent/__init__.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from .concept import router as concept_router
+from .models import router as models_router
+from .pipe_spec import router as pipe_spec_router
+
+router = APIRouter()
+
+router.include_router(models_router)
+router.include_router(concept_router)
+router.include_router(pipe_spec_router)

pipelex_api/routes/pipelex/agent/concept.py

@@ -0,0 +1,60 @@
+"""Concept endpoint — convert JSON concept spec to TOML."""
+
+import json
+from typing import Any
+
+from fastapi import APIRouter
+from pipelex.builder.operations.concept_ops import concept_spec_to_toml, parse_concept_spec
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+from pipelex_api.errors import raise_validation_error
+from pipelex_api.json_body import JsonBodyRoute
+from pipelex_api.limits import MAX_AGENT_SPEC_BYTES
+
+router = APIRouter(tags=["agent"], route_class=JsonBodyRoute)
+
+
+class BuildConceptRequest(BaseModel):
+    spec: dict[str, Any] = Field(..., description="JSON concept specification.")
+
+    @field_validator("spec")
+    @classmethod
+    def _bound_spec_size(cls, value: dict[str, Any]) -> dict[str, Any]:
+        if len(json.dumps(value).encode("utf-8")) > MAX_AGENT_SPEC_BYTES:
+            msg = f"spec exceeds {MAX_AGENT_SPEC_BYTES // 1024} KiB limit"
+            raise ValueError(msg)
+        return value
+
+
+class BuildConceptResponse(BaseModel):
+    success: bool = Field(default=True, description="Whether the operation was successful")
+    concept_code: str = Field(..., description="The concept code that was generated")
+    toml: str = Field(..., description="Generated TOML content for the concept")
+
+
+@router.post("/build/concept")
+async def build_concept(request_data: BuildConceptRequest) -> BuildConceptResponse:
+    """Convert a JSON concept spec to TOML format.
+
+    A malformed spec surfaces as a Pydantic `ValidationError` — an API-owned
+    422. Pipelex domain failures propagate untouched to the global
+    `PipelexError` handler in `pipelex_api.exception_handlers`.
+
+    A malformed shape — a non-mapping `structure` (`{"structure": "string"}`)
+    or a `structure` field that is neither a string nor a mapping
+    (`{"structure": {"f": 42}}`) — is refused by `parse_concept_spec` itself
+    with a typed `ConceptSpecError`, which that same handler answers. Nothing
+    broader is caught here: a bare exception from pipelex is the signal of a
+    real programming bug, and a route-level catch would mask it.
+    """
+    try:
+        concept_spec = parse_concept_spec(request_data.spec)
+        toml_content = concept_spec_to_toml(concept_spec)
+
+        return BuildConceptResponse(
+            success=True,
+            concept_code=concept_spec.concept_code,
+            toml=toml_content,
+        )
+    except ValidationError as exc:
+        raise_validation_error(message=str(exc))

pipelex_api/routes/pipelex/agent/models.py

@@ -0,0 +1,49 @@
+"""Models endpoint — the MTHDS Protocol model deck this runner routes to."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request
+from mthds.protocol.models import ModelCategory
+from pipelex.pipeline.runner import PipelexModelDeck
+
+from pipelex_api.error_types import ErrorType
+from pipelex_api.errors import raise_validation_error
+from pipelex_api.routes.pipelex.pipeline import ApiRunner
+
+router = APIRouter(tags=["agent"])
+
+
+@router.get("/models", openapi_extra={"x-mthds-protocol": True})
+async def get_models(
+    request: Request,
+    model_type: Annotated[
+        str | None,
+        Query(alias="type", description="Filter by model category: llm, extract, img_gen, search. Single value (protocol arity)."),
+    ] = None,
+) -> PipelexModelDeck:
+    """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
+    (arity, `ValidationError`) and unknown categories (`InvalidModelCategory`) are
+    both 422s (RFC 7807).
+    """
+    # Protocol arity: `type` is a plain single-value enum. FastAPI silently keeps one of
+    # several repeated scalar query params, so the multi-value rejection must be explicit.
+    # Generic ValidationError, not InvalidModelCategory: the values may all be valid —
+    # what's wrong is the arity.
+    if len(request.query_params.getlist("type")) > 1:
+        raise_validation_error(message="The `type` query parameter accepts a single value")
+    category: ModelCategory | None = None
+    if model_type is not None:
+        try:
+            category = ModelCategory(model_type)
+        except ValueError:
+            valid = ", ".join(sorted(member.value for member in ModelCategory))
+            raise_validation_error(
+                message=f"Invalid model category. Valid values: {valid}",
+                error_type=ErrorType.INVALID_MODEL_CATEGORY,
+            )
+    return await ApiRunner().models(category=category)

pipelex_api/routes/pipelex/agent/pipe_spec.py

@@ -0,0 +1,59 @@
+"""Pipe spec endpoint — convert JSON pipe spec to TOML."""
+
+import json
+from typing import Any
+
+from fastapi import APIRouter
+from pipelex.builder.operations.pipe_ops import parse_pipe_spec, pipe_spec_to_toml
+from pydantic import BaseModel, Field, ValidationError, field_validator
+
+from pipelex_api.errors import raise_validation_error
+from pipelex_api.json_body import JsonBodyRoute
+from pipelex_api.limits import MAX_AGENT_SPEC_BYTES
+
+router = APIRouter(tags=["agent"], route_class=JsonBodyRoute)
+
+
+class BuildPipeSpecRequest(BaseModel):
+    pipe_type: str = Field(..., min_length=1, max_length=128, description="The pipe type (e.g. PipeLLM, PipeSequence, etc.).")
+    spec: dict[str, Any] = Field(..., description="JSON pipe specification.")
+
+    @field_validator("spec")
+    @classmethod
+    def _bound_spec_size(cls, value: dict[str, Any]) -> dict[str, Any]:
+        if len(json.dumps(value).encode("utf-8")) > MAX_AGENT_SPEC_BYTES:
+            msg = f"spec exceeds {MAX_AGENT_SPEC_BYTES // 1024} KiB limit"
+            raise ValueError(msg)
+        return value
+
+
+class BuildPipeSpecResponse(BaseModel):
+    success: bool = Field(default=True, description="Whether the operation was successful")
+    pipe_code: str = Field(..., description="The pipe code that was generated")
+    pipe_type: str = Field(..., description="The pipe type")
+    toml: str = Field(..., description="Generated TOML content for the pipe")
+
+
+@router.post("/build/pipe-spec")
+async def build_pipe_spec(request_data: BuildPipeSpecRequest) -> BuildPipeSpecResponse:
+    """Convert a JSON pipe spec to TOML format.
+
+    Two caller-mistake paths surface as a 422 here: a `ValidationError` from
+    Pydantic when the spec shape doesn't match the chosen pipe type, and a
+    `ValueError` from `parse_pipe_spec` when `pipe_type` is not one of the
+    known pipe types (documented in `parse_pipe_spec`'s docstring; raised at
+    exactly one site). Pipelex domain failures propagate untouched to the
+    global `PipelexError` handler in `pipelex_api.exception_handlers`.
+    """
+    try:
+        pipe_spec = parse_pipe_spec(request_data.spec, pipe_type=request_data.pipe_type)
+        toml_content = pipe_spec_to_toml(pipe_spec)
+
+        return BuildPipeSpecResponse(
+            success=True,
+            pipe_code=pipe_spec.pipe_code,
+            pipe_type=request_data.pipe_type,
+            toml=toml_content,
+        )
+    except (ValidationError, ValueError) as exc:
+        raise_validation_error(message=str(exc))