pipelex-api 0.71.0__py3-none-any.whl

pipelex_api/api.toml

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

pipelex_api/api_config.py

@@ -0,0 +1,144 @@
+"""Pipelex-API deployment config: the top-level orchestration mode + override policy.
+
+The runner is orchestrator-agnostic. WHICH orchestrator a top-level run dispatches
+to — ``direct`` in-process (the base default), ``temporal``, ``mistral-workflows``,
+… — is a *deployment* choice, never a property of this source-available base.
+``orchestration_mode`` is an open string token (core owns ``"direct"``; each plugin
+owns its own); the *delivery* axis (blocking vs fire-and-forget) is endpoint-set, not
+configured here. It is read from a packaged ``api.toml`` (keys at the file root — no
+``[api]`` wrapper, since :meth:`load_plugin_config` validates the whole document
+against the schema, exactly like ``temporal.toml``), env-layered like the main pipelex
+config and every plugin config (D2): the packaged default ``api.toml`` (shipped in this
+wheel) is deep-merged with the env-selected ``api_{environment}.toml`` and
+``api_override.toml`` from ``~/.pipelex`` then the project ``.pipelex``, with
+``PIPELEX_ENV`` (``runtime_manager.environment``) choosing the env file. One image
+bakes every env file; a deployment flavor (e.g. ``pipelex-api-hosted``) bakes
+``.pipelex/api_{env}.toml`` to flip the default. The base names no orchestrator and
+ships ``orchestration_mode = "direct"``.
+
+Why a separate ``api.toml`` and not the core ``pipelex_{env}.toml``: core's
+config is ``extra="forbid"``, so an ``[api]`` section there is rejected at load.
+Loading it via core's reusable :meth:`load_plugin_config` keeps this a pure
+pipelex-api concern while reusing the identical env-layering machinery — and
+keeps it symmetric with how ``pipelex-temporal`` self-loads ``temporal.toml``.
+"""
+
+from functools import cache
+from pathlib import Path
+
+from pipelex.runtime_bridge.orchestration_mode import DIRECT_ORCHESTRATION_MODE
+from pipelex.system.configuration.config_loader import config_manager
+from pydantic import BaseModel, ConfigDict
+
+from pipelex_api.error_types import ErrorType
+from pipelex_api.errors import raise_forbidden
+
+API_CONFIG_NAME = "api"
+
+# The packaged default ``api.toml`` ships in the wheel alongside this module.
+_PACKAGE_DIR = Path(__file__).resolve().parent
+
+
+class ApiConfig(BaseModel):
+    """The ``[api]`` deployment config: default orchestration mode + override policy.
+
+    No field defaults — the packaged ``api.toml`` is the single source of the
+    base defaults (mirroring core's "defaults live in the TOML, never in the
+    model" discipline). ``extra="forbid"`` so a typo'd key in a baked override
+    fails loud at load instead of being silently ignored.
+
+    ``orchestration_mode`` is an open string token (core owns ``"direct"``; each
+    plugin owns its own). It is NOT validated against a closed enum here — an
+    unregistered token is refused at dispatch by ``MissingOrchestratorError``,
+    the single validation point. The delivery axis (blocking vs fire-and-forget)
+    is endpoint-set, never configured, so nothing about wait-semantics lives here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    orchestration_mode: str
+    allow_request_orchestration_mode_override: bool
+
+
+def load_api_config() -> ApiConfig:
+    """Load the ``[api]`` config from ``api.toml`` with env-aware layering (D2).
+
+    Delegates to core's reusable plugin-config loader: the packaged ``api.toml``
+    is deep-merged with the env-selected overrides. The packaged default alone is
+    a valid, fully-resolved config — every override tier is optional. Requires
+    Pipelex to be booted (``runtime_manager.environment`` must be resolved), so
+    it is called only after ``Pipelex.make`` — never at import.
+    """
+    return config_manager.load_plugin_config(name=API_CONFIG_NAME, package_dir=_PACKAGE_DIR, schema=ApiConfig)
+
+
+@cache
+def get_api_config() -> ApiConfig:
+    """Process-cached :class:`ApiConfig`.
+
+    The config is immutable for the life of the process (``PIPELEX_ENV`` is fixed
+    at boot), so it is loaded once and cached. ``pipelex_api.main`` warms this at startup
+    so a malformed ``api.toml`` / baked override fails the app fast — the same
+    fail-fast posture as ``ERROR_DISCLOSURE``. Tests that need a different mode
+    patch this getter (or call :func:`resolve_orchestration_mode` with a hand-built
+    config) rather than mutating the cache.
+    """
+    return load_api_config()
+
+
+def resolve_orchestration_mode(requested: str | None, *, config: ApiConfig) -> str:
+    """Resolve the effective orchestration mode for a top-level run, applying policy.
+
+    The deployment default (``config.orchestration_mode``) wins unless the caller
+    supplied a *different* token AND the deployment opted into per-request
+    override (``allow_request_orchestration_mode_override``). A caller-supplied
+    token equal to the default is always honored (it changes nothing). A caller
+    trying to FORCE a different mode on a runner whose policy forbids it is refused
+    with a 403 — so a locked-down Temporal runner can never be coerced into
+    ``direct`` (whose whole point would be to bypass distributed execution), and
+    vice versa. The token is a plain string compare; an *unregistered* token is
+    not rejected here — that surfaces at dispatch as ``MissingOrchestratorError``.
+    """
+    if requested is None or requested == config.orchestration_mode:
+        return config.orchestration_mode
+    if config.allow_request_orchestration_mode_override:
+        return requested
+    msg = (
+        f"This deployment does not allow overriding orchestration_mode per request "
+        f"(configured mode '{config.orchestration_mode}', requested '{requested}')."
+    )
+    raise_forbidden(msg, error_type=ErrorType.ORCHESTRATION_MODE_OVERRIDE_FORBIDDEN)
+
+
+class ApiBootConfigError(ValueError):
+    """Raised at startup when the deployment's orchestration config cannot boot coherently."""
+
+
+def resolve_boot_orchestrator(config: ApiConfig) -> str | None:
+    """The orchestrator plugin this process boots under, derived from the deployment config.
+
+    The base ``direct`` mode names no orchestrator and boots in-process (``None``); any other
+    mode (a plugin token like ``"temporal"``) boots the process under that orchestrator so its
+    execution-hub slots are claimed and async dispatch is enabled.
+
+    A process boots under exactly one orchestrator, so a ``direct`` default that ALSO enables
+    per-request override is incoherent: no async hub is claimed at boot, yet
+    :func:`resolve_orchestration_mode` would honor a request overriding to a non-direct mode and
+    resolve that orchestrator's dispatch arm — which then fails at dispatch with
+    ``AsyncExecutionNotEnabledError``. Refuse it here: fail loud at boot, where the operator sees
+    it, rather than on the first overriding request. The mirror case (a non-direct default with
+    override on) IS coherent — the async hub is claimed at boot, and a per-request ``direct``
+    override still runs in-process — so it boots normally under that orchestrator.
+    """
+    mode = config.orchestration_mode
+    if config.allow_request_orchestration_mode_override and mode == DIRECT_ORCHESTRATION_MODE:
+        msg = (
+            "allow_request_orchestration_mode_override=true with a 'direct' orchestration_mode default "
+            "cannot service a non-direct per-request override: no async execution hub is claimed at boot, "
+            "so such a request would fail at dispatch. Set a non-direct orchestration_mode default or "
+            "disable per-request override."
+        )
+        raise ApiBootConfigError(msg)
+    if mode == DIRECT_ORCHESTRATION_MODE:
+        return None
+    return mode

pipelex_api/bundle.py

@@ -0,0 +1,243 @@
+"""Materialize a caller-supplied method bundle into a temporary library directory.
+
+A run request may carry the whole method — the `.mthds` bundle plus its PipeFunc
+Python (`pipe_func.py`) and a `requirements.txt` — instead of only
+the inline `mthds_contents` text. Two transport forms are accepted, exactly one
+per request:
+
+  - `bundle_b64`: a base64-encoded zip archive of the bundle directory.
+  - `files`: a `{relative_path: text_content}` map (the zip's contents, unzipped).
+
+The two are equivalent: `files` ≡ the zip's entries. This module decodes either
+form, enforces the ingest guards (both transport forms are refused together; a
+hard file-count and total-size ceiling; per-entry path-safety against absolute
+paths and `..` traversal; a zip-bomb guard that bounds actual decompression),
+writes the surviving files into a fresh temp directory, and hands that directory
+back so the runner can load it via `library_dirs`. In a sandbox-hosted
+deployment the load path reads every `.py` as source text, never importing it:
+it refuses a bundle whose Python declares a structure class
+(`MethodStructuresRefusedError`, a 403) and captures the rest onto the crate for
+the sandbox. The caller is responsible for the hosted-mode gate.
+
+Nothing here imports or executes the bundle's Python — it only writes bytes to
+disk. The caller cleans the directory up via the `materialized_bundle` context
+manager's guaranteed teardown.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import shutil
+import tempfile
+import zipfile
+from contextlib import contextmanager
+from io import BytesIO
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING, NamedTuple
+
+from pipelex import log
+from pydantic import ConfigDict
+from pydantic.dataclasses import dataclass
+
+from pipelex_api.error_types import ErrorType
+from pipelex_api.errors import raise_bad_request, raise_payload_too_large, raise_validation_error
+from pipelex_api.limits import MAX_BUNDLE_FILES, MAX_BUNDLE_TOTAL_BYTES
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+@dataclass(frozen=True, config=ConfigDict(arbitrary_types_allowed=True))
+class MaterializedBundle:
+    """A bundle written to disk: the directory to load and the relpaths written."""
+
+    directory: Path
+    relpaths: tuple[str, ...]
+
+    @property
+    def has_python_sources(self) -> bool:
+        """True when the bundle ships any `.py` — the trigger for the hosted-mode gate."""
+        return any(relpath.endswith(".py") for relpath in self.relpaths)
+
+
+def _safe_relpath(name: str) -> PurePosixPath:
+    """Validate one bundle entry name and return it as a normalized relative POSIX path.
+
+    Rejects anything that could escape the destination directory: absolute paths,
+    Windows drive/backslash forms (a bare drive prefix like `C:foo` has no slash or
+    backslash yet is drive-relative on Windows, so `:` is rejected outright), and any
+    `..` component. Directory-only entries (trailing slash) return an empty path and
+    are filtered by the caller.
+    """
+    if not name or name in {".", "./"}:
+        return PurePosixPath()
+    if "\\" in name:
+        msg = f"Bundle entry {name!r} uses backslashes; use forward-slash relative paths only"
+        raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+    if ":" in name:
+        msg = f"Bundle entry {name!r} contains ':' (a Windows drive/stream form); use plain relative paths only"
+        raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+    pure = PurePosixPath(name)
+    if pure.is_absolute():
+        msg = f"Bundle entry {name!r} is an absolute path; only relative paths are allowed"
+        raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+    if any(part == ".." for part in pure.parts):
+        msg = f"Bundle entry {name!r} escapes the bundle root via '..'; not allowed"
+        raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+    return pure
+
+
+def _guard_count(count: int) -> None:
+    if count == 0:
+        raise_validation_error(message="Bundle is empty (no files)", error_type=ErrorType.INVALID_BUNDLE)
+    if count > MAX_BUNDLE_FILES:
+        raise_payload_too_large(message=f"Bundle exceeds the {MAX_BUNDLE_FILES}-file limit (got {count})")
+
+
+def _guard_running_total(total_bytes: int) -> None:
+    if total_bytes > MAX_BUNDLE_TOTAL_BYTES:
+        raise_payload_too_large(message=f"Bundle exceeds the {MAX_BUNDLE_TOTAL_BYTES // 1024} KiB decompressed-size limit")
+
+
+# Base64 inflates by 4/3; a zip is compressed, so a bundle whose DECOMPRESSED content is within
+# the ceiling encodes to well under this. Bounding the base64 string BEFORE decoding stops a
+# ~100 MiB request-body (the only other bound) from being expanded into ~75 MiB of heap just to
+# be rejected later by the decompressed-size guard. Slack (+4) covers padding.
+_MAX_BUNDLE_B64_CHARS = MAX_BUNDLE_TOTAL_BYTES * 4 // 3 + 4
+
+
+def _entries_from_zip(bundle_b64: str) -> list[tuple[PurePosixPath, bytes]]:
+    """Decode a base64 zip and return its (safe relpath, bytes) file entries.
+
+    Zip-bomb guard: each member is read through a bounded stream so a lying
+    uncompressed-size header cannot force unbounded decompression — the running
+    total is checked against `MAX_BUNDLE_TOTAL_BYTES` as bytes are pulled. A cheap
+    length check on the still-encoded string runs FIRST, so an oversized payload is
+    refused before it is buffered into memory as decoded bytes.
+    """
+    if len(bundle_b64) > _MAX_BUNDLE_B64_CHARS:
+        raise_payload_too_large(message=f"bundle_b64 exceeds the {MAX_BUNDLE_TOTAL_BYTES // 1024} KiB compressed-size limit")
+    try:
+        raw = base64.b64decode(bundle_b64, validate=True)
+    except (binascii.Error, ValueError) as decode_error:
+        log.warning(f"bundle: invalid base64 ({decode_error})")
+        raise_bad_request(message="bundle_b64 is not valid base64", error_type=ErrorType.INVALID_BASE64)
+
+    try:
+        archive = zipfile.ZipFile(BytesIO(raw))
+    except zipfile.BadZipFile as zip_error:
+        log.warning(f"bundle: corrupt zip ({zip_error})")
+        raise_validation_error(message="bundle_b64 is not a valid zip archive", error_type=ErrorType.INVALID_BUNDLE)
+
+    entries: list[tuple[PurePosixPath, bytes]] = []
+    total_bytes = 0
+    with archive:
+        members = [info for info in archive.infolist() if not info.is_dir()]
+        _guard_count(len(members))
+        budget = MAX_BUNDLE_TOTAL_BYTES
+        for info in members:
+            relpath = _safe_relpath(info.filename)
+            if not relpath.parts:
+                continue
+            # Bounded read: pull at most (remaining budget + 1) bytes so a zip bomb whose header
+            # under-reports its size still cannot decompress past the ceiling.
+            with archive.open(info) as member:
+                data = member.read(budget + 1)
+            total_bytes += len(data)
+            _guard_running_total(total_bytes)
+            budget = MAX_BUNDLE_TOTAL_BYTES - total_bytes
+            entries.append((relpath, data))
+    return entries
+
+
+def _entries_from_files(files: dict[str, str]) -> list[tuple[PurePosixPath, bytes]]:
+    """Validate a {relpath: text} map and return its (safe relpath, bytes) entries."""
+    _guard_count(len(files))
+    entries: list[tuple[PurePosixPath, bytes]] = []
+    total_bytes = 0
+    for name, content in files.items():
+        relpath = _safe_relpath(name)
+        if not relpath.parts:
+            msg = f"Bundle entry {name!r} has no filename"
+            raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+        data = content.encode("utf-8")
+        total_bytes += len(data)
+        _guard_running_total(total_bytes)
+        entries.append((relpath, data))
+    return entries
+
+
+class ParsedBundle(NamedTuple):
+    """A decoded-and-validated bundle held in memory, NOT yet written to disk.
+
+    Splitting parse from materialize lets the caller apply the sandbox-hosted gate
+    (which keys on `has_python_sources`) BEFORE any disk write — so a bundle destined
+    for a 403 never touches the filesystem. Entries are `(safe relpath, bytes)`.
+    """
+
+    entries: tuple[tuple[PurePosixPath, bytes], ...]
+
+    @property
+    def has_python_sources(self) -> bool:
+        """True when the bundle ships any `.py` — the trigger for the hosted-mode gate."""
+        return any(str(relpath).endswith(".py") for relpath, _ in self.entries)
+
+
+def parse_bundle(*, bundle_b64: str | None, files: dict[str, str] | None) -> ParsedBundle:
+    """Decode + guard a bundle into an in-memory `ParsedBundle` (no disk writes).
+
+    Exactly one of `bundle_b64` / `files` must be supplied; supplying both is a
+    caller mistake (they are the same content in two forms) and is refused. All
+    ingest guards (base64, size, count, path-safety, zip-bomb) run here, so the
+    caller can inspect `has_python_sources` and reject BEFORE materializing to disk.
+    """
+    if bundle_b64 is not None and files is not None:
+        msg = "Provide either bundle_b64 or files, not both"
+        raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+    if bundle_b64 is not None:
+        entries = _entries_from_zip(bundle_b64)
+    elif files is not None:
+        entries = _entries_from_files(files)
+    else:
+        msg = "No bundle supplied (bundle_b64 and files are both absent)"
+        raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+    return ParsedBundle(entries=tuple(entries))
+
+
+@contextmanager
+def materialize_parsed(parsed: ParsedBundle) -> Generator[MaterializedBundle, None, None]:
+    """Write an already-parsed bundle into a fresh temp directory, cleaned up on exit.
+
+    The yielded `MaterializedBundle.directory` is safe to pass as a `library_dirs`
+    entry; it is removed when the context exits, on both the happy and error path.
+    """
+    directory = Path(tempfile.mkdtemp(prefix="pipelex-bundle-"))
+    try:
+        root = directory.resolve()
+        relpaths: list[str] = []
+        for relpath, data in parsed.entries:
+            target = (directory / relpath).resolve()
+            # Defense-in-depth: even after per-part validation, confirm the resolved target stays
+            # under the temp root before writing (guards against symlink/edge normalization surprises).
+            if root != target and root not in target.parents:
+                msg = f"Bundle entry {str(relpath)!r} resolves outside the bundle root"
+                raise_validation_error(message=msg, error_type=ErrorType.INVALID_BUNDLE)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(data)
+            relpaths.append(relpath.as_posix())
+        yield MaterializedBundle(directory=directory, relpaths=tuple(relpaths))
+    finally:
+        shutil.rmtree(directory, ignore_errors=True)
+
+
+@contextmanager
+def materialized_bundle(*, bundle_b64: str | None, files: dict[str, str] | None) -> Generator[MaterializedBundle, None, None]:
+    """Parse AND materialize a bundle in one step (convenience for callers that don't gate).
+
+    Equivalent to `parse_bundle(...)` followed by `materialize_parsed(...)`; a caller
+    that must apply the sandbox-hosted gate before disk writes should use the two
+    steps directly instead.
+    """
+    with materialize_parsed(parse_bundle(bundle_b64=bundle_b64, files=files)) as bundle:
+        yield bundle

pipelex_api/disclosure.py

@@ -0,0 +1,43 @@
+"""Resolution of the `ERROR_DISCLOSURE` environment variable.
+
+`ERROR_DISCLOSURE` selects how much of an error report reaches the client:
+
+- `verbose` (default) — the full report, including the human-readable message.
+  The intended default for a self-hosted server, where the operator and the
+  debugging developer are usually the same person.
+- `strict` — the lossy projection pipelex's `DisclosureMode.STRICT` produces,
+  for hosted multi-tenant deployments.
+
+The value is resolved once, at app startup (`pipelex_api.main`). An unrecognized value
+fails the app at boot rather than silently degrading — a misconfigured
+disclosure mode is a security-relevant mistake the operator must see.
+"""
+
+from pipelex.base_exceptions import DisclosureMode
+from pipelex.system.environment import get_optional_env
+
+ERROR_DISCLOSURE_ENV_VAR = "ERROR_DISCLOSURE"
+
+
+class InvalidErrorDisclosureError(ValueError):
+    """Raised at startup when `ERROR_DISCLOSURE` holds an unrecognized value."""
+
+
+def resolve_disclosure_mode() -> DisclosureMode:
+    """Resolve `ERROR_DISCLOSURE` to a `DisclosureMode`.
+
+    Returns `DisclosureMode.VERBOSE` when the variable is unset, empty, or
+    whitespace-only. Raises `InvalidErrorDisclosureError` for any value other
+    than `verbose` or `strict` (matched case-insensitively, surrounding
+    whitespace ignored).
+    """
+    raw = get_optional_env(ERROR_DISCLOSURE_ENV_VAR)
+    normalized = (raw or "").strip().lower()
+    if not normalized:
+        return DisclosureMode.VERBOSE
+    try:
+        return DisclosureMode(normalized)
+    except ValueError as exc:
+        valid = ", ".join(f"'{mode}'" for mode in DisclosureMode)
+        msg = f"{ERROR_DISCLOSURE_ENV_VAR}={raw!r} is not a valid disclosure mode. Valid values: {valid}."
+        raise InvalidErrorDisclosureError(msg) from exc

pipelex_api/error_types.py

@@ -0,0 +1,80 @@
+"""Centralized `error_type` symbols for API-authored error responses.
+
+Every fixed (non-dynamic) `error_type` an API-authored error emits lives here
+so call sites reference symbols, not literals — easier to grep, rename, and
+document. The `pipelex_api.errors` helpers stamp one of these onto the RFC 7807
+problem document as the `error_type` extension member.
+
+Pipelex domain errors carry their own open-ended `error_type` (the exception
+class name, from the `ErrorReport`) and are NOT enumerated here — they are
+deliberately not a fixed set.
+"""
+
+from enum import StrEnum
+
+
+class ErrorType(StrEnum):
+    # Authentication / authorization
+    UNAUTHENTICATED = "Unauthenticated"
+    FORBIDDEN = "Forbidden"
+    # A caller asked to run in an orchestration_mode this deployment forbids overriding
+    # (per-request override is off — see `allow_request_orchestration_mode_override` in api.toml).
+    # A 403: the deployment policy refuses to honor the requested mode.
+    ORCHESTRATION_MODE_OVERRIDE_FORBIDDEN = "OrchestrationModeOverrideForbidden"
+    INVALID_TOKEN = "InvalidToken"
+    TOKEN_EXPIRED = "TokenExpired"
+    SERVER_MISCONFIGURED = "ServerMisconfigured"
+
+    # A caller hit `/start` on a deployment whose resolved orchestration mode cannot do genuine
+    # async (its orchestrator's `supports_fire_and_forget` is False — e.g. the in-process `direct`
+    # base). `/start` is fire-and-forget by nature, so rather than silently running blocking and
+    # acking, it refuses HONESTLY with a 400: use `/execute` (synchronous) instead. Checked AFTER
+    # the override policy, so a forbidden per-request override still 403s first.
+    START_REQUIRES_ASYNC_ORCHESTRATION = "StartRequiresAsyncOrchestration"
+
+    # Request validation
+    BAD_REQUEST = "BadRequest"
+    VALIDATION_ERROR = "ValidationError"
+    INVALID_JSON = "InvalidJSON"
+    # A run request's body carries, at any depth, an object key a kajson decoder reads as a class
+    # marker: `__class__`, `__module__`, or anything starting with `__kajson`. A 422, not data: the
+    # run body is plain JSON, and such a key would make a later kajson round trip of the inputs
+    # import and instantiate whatever class the caller named.
+    RESERVED_OBJECT_KEY = "ReservedObjectKey"
+    INVALID_CALLBACK_URLS = "InvalidCallbackUrls"
+    # A run request's `storage_scope` extra is not one to three path-safe segments. A 422, not a
+    # 500 from deep in the run: the value becomes a storage key prefix, so a `..` escapes the tenant.
+    INVALID_STORAGE_SCOPE = "InvalidStorageScope"
+    # A run request's `read_scope` extra is not one to three path-safe segments, or the run's storage
+    # scope does not lie under it, so the run could not read back what it writes.
+    INVALID_READ_SCOPE = "InvalidReadScope"
+    # A run request's `analytics_groups` extra is not a mapping of group type to group key within
+    # the runtime's charset and entry cap (`pipelex.system.run_extras`).
+    INVALID_ANALYTICS_GROUPS = "InvalidAnalyticsGroups"
+    INVALID_MODEL_CATEGORY = "InvalidModelCategory"
+    INVALID_BASE64 = "InvalidBase64"
+    PAYLOAD_TOO_LARGE = "PayloadTooLarge"
+    # A run request carried a malformed method bundle (`bundle_b64` / `files`): a corrupt zip, an
+    # unsafe entry name (absolute path or `..` traversal), or both transport forms supplied at once.
+    INVALID_BUNDLE = "InvalidBundle"
+    # A method carrying custom Python (`.py` in a bundle, or in a fetched `method_ref` package)
+    # reached a deployment that is NOT sandbox-hosted. Running customer code in-process is
+    # refused (403): custom code is a sandbox-hosted capability only. Use a sandbox-hosted
+    # deployment. (On a sandbox-hosted deployment, a bundle or a fetched package declaring Python
+    # STRUCTURE classes is still refused — that is pipelex's `MethodStructuresRefusedError`, not this.)
+    CUSTOM_CODE_REQUIRES_SANDBOX = "CustomCodeRequiresSandbox"
+
+    # A caller selected a closure by a REGISTRY-FORM `method_ref` (not a `github.com/...`
+    # address) on a tooling route. Address-form refs resolve server-side (fetch at tag, package
+    # located by manifest identity); the registry form is the packaging program's closing phase,
+    # so it keeps an honest 501 until a method registry exists — never a silent empty verdict.
+    METHOD_REF_NOT_SUPPORTED = "MethodRefNotSupported"
+
+    # Misc
+    PACKAGE_NOT_FOUND = "PackageNotFound"
+    # The `error_type` for the catch-all 500 emitted by `handle_unexpected_error`
+    # (any failure matched by no more-specific handler — not an `ApiError`, a
+    # `RequestValidationError`, a `PipelexError`, or an orchestrator plugin's mapped
+    # transport exception). Stays in this enum so the same `build_problem_document_from_api_error`
+    # builder renders it — same shape as every other API-authored 500.
+    INTERNAL_SERVER_ERROR = "InternalServerError"

pipelex_api/error_uri.py

@@ -0,0 +1,45 @@
+"""RFC 7807 `type` URI and `title` for API-authored errors.
+
+A pipelex `ErrorReport` always carries its own `type_uri` and `title` (set
+upstream by `PipelexError.type_uri()` / `PipelexError.title()`, both required
+fields), so the global exception handler never needs these helpers for a
+`PipelexError`.
+
+They exist for the *other* error source: the API's own 4xx responses
+(`raise_validation_error` and friends in `pipelex_api.errors`), authored from the
+static `pipelex_api.error_types.ErrorType` enum with no `ErrorReport` behind them.
+`build_problem_document_from_api_error` uses these to give an API-authored
+error the same RFC 7807 `type` / `title` shape as a pipelex one. They also
+serve as a defensive backstop should a future pipelex ever hand back a report
+with an absent identity pair.
+
+The URI namespace and the kebab / humanize transforms are deliberately the
+same ones pipelex uses (`URLs.error_docs_base`, `pascal_case_to_kebab`,
+`pascal_case_to_sentence`), so an API-authored error and a pipelex error are
+indistinguishable in shape on the wire. Both functions are pure.
+"""
+
+from pipelex.tools.misc.string_utils import pascal_case_to_kebab, pascal_case_to_sentence
+from pipelex.urls import URLs
+
+
+def error_type_uri(error_type: str) -> str:
+    """Return the RFC 7807 `type` URI for an error type name.
+
+    `EnvVarNotFoundError` -> `https://docs.pipelex.com/latest/errors/env-var-not-found-error/`.
+    The trailing slash matches the canonical docs URL form, exactly as
+    `PipelexError.type_uri()` produces it upstream.
+    """
+    return f"{URLs.error_docs_base}/{pascal_case_to_kebab(error_type)}/"
+
+
+def error_type_title(error_type: str) -> str:
+    """Return a human-readable RFC 7807 `title` for an error type name.
+
+    `ValidationError` -> `Validation error`; `BadRequest` -> `Bad request`.
+    Sentence case via the same `pascal_case_to_sentence` transform pipelex uses
+    in `PipelexError.title()`. Unlike `PipelexError.title()` it does NOT strip a
+    trailing `Error`: an API `ErrorType` such as `ValidationError` must keep the
+    suffix — `"Validation"` alone would be a worse label than `"Validation error"`.
+    """
+    return pascal_case_to_sentence(error_type)