Skip to content

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.

8.0 KB
Raw Blame
"""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.exceptions import ApiBootConfigError, OrchestrationOverrideForbiddenError

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 ``AUTH_MODE``. 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 422 ``pipelex.deployment.orchestration_override_forbidden`` — 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 OrchestrationOverrideForbiddenError(msg, requested_mode=requested)


def is_callers_override(*, orchestration_mode: str, config: ApiConfig) -> bool:
    """Whether a resolved orchestration mode is a per-request override the caller named, not the deployment's default.

    :func:`resolve_orchestration_mode` returns the default unless the caller named a different mode the policy
    allows, so a resolved mode other than the default is always the caller's. A refusal of such a mode, such as
    one no installed plugin serves, is the caller's to change (``runtime.unsupported``), where the same refusal of
    the default is the operator's (``pipelex.plugin.not_found``).
    """
    return orchestration_mode != config.orchestration_mode


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