pipelex-api 0.76.0__tar.gz → 0.78.0__tar.gz

{pipelex_api-0.76.0 → pipelex_api-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pipelex-api
-Version: 0.76.0
+Version: 0.78.0
 Summary: Pipelex API
 Project-URL: Homepage, https://pipelex.com
 Project-URL: Repository, https://github.com/Pipelex/pipelex
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.11
 Requires-Dist: fastapi<0.142,>=0.118.0
-Requires-Dist: pipelex[anthropic,bedrock,fal,google,google-genai,mistralai]==0.76.0
+Requires-Dist: pipelex[anthropic,bedrock,fal,google,google-genai,mistralai]==0.78.0
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: uvicorn>=0.37.0
 Provides-Extra: dev

{pipelex_api-0.76.0 → pipelex_api-0.78.0}/pipelex_api/error_types.py

@@ -52,6 +52,10 @@ class ErrorType(StrEnum):
     # the runtime's charset and entry cap (`pipelex.system.run_extras`).
     INVALID_ANALYTICS_GROUPS = "InvalidAnalyticsGroups"
     INVALID_MODEL_CATEGORY = "InvalidModelCategory"
+    # `GET /v1/models/check` was given a `reference` it cannot check: blank once trimmed, a sigil or a
+    # namespace with nothing after it, or longer than the route's bound. A reference that parses and
+    # resolves nowhere is never refused: it is the `not_found` verdict.
+    INVALID_MODEL_REFERENCE = "InvalidModelReference"
     INVALID_BASE64 = "InvalidBase64"
     PAYLOAD_TOO_LARGE = "PayloadTooLarge"
     # A run request carried a malformed method bundle (`bundle_b64` / `files`): a corrupt zip, an

{pipelex_api-0.76.0 → pipelex_api-0.78.0}/pipelex_api/main.py

@@ -150,7 +150,8 @@ fastapi_app = PipelexFastAPI(
         f"This server implements the [MTHDS Protocol](https://mthds.ai) v{PROTOCOL_VERSION} "
         "(`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`), and editor tooling (`/lint`, `/format`). "
+        "(`/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 "

pipelex_api-0.78.0/pipelex_api/routes/pipelex/agent/models.py

@@ -0,0 +1,121 @@
+"""Models endpoints — the MTHDS Protocol model deck this runner routes to, and the model reference check."""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query, Request
+from mthds.protocol.models import ModelCategory
+from pipelex.cogt.models.exceptions import ModelReferenceParseError
+from pipelex.cogt.models.model_reference import ModelReference
+from pipelex.cogt.models.model_reference_check import ModelCheckCategory, ModelReferenceVerdict, check_model_reference
+from pipelex.pipeline.runner import PipelexModelDeck
+from pipelex.runtime_hub import get_model_deck
+
+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"])
+
+# The longest reference the check accepts once trimmed; one character more is refused with `InvalidModelReference`.
+MAX_MODEL_REFERENCE_LENGTH = 199
+
+
+@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, judgment. 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)
+
+
+# NOT tagged `x-mthds-protocol`: the check is a Pipelex API extension, and the flag marks the
+# standard's own operations alone. Its refusals are the composite router's shared problem+json 422.
+@router.get("/models/check")
+async def check_model(
+    request: Request,
+    reference: Annotated[
+        str,
+        Query(
+            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, "
+                f"and the trimmed reference holds at most {MAX_MODEL_REFERENCE_LENGTH} characters. Single value."
+            ),
+        ),
+    ],
+    model_type: Annotated[
+        str | None,
+        Query(
+            alias="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."
+            ),
+        ),
+    ] = None,
+) -> ModelReferenceVerdict:
+    """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`: `ValidationError` for a missing or
+    repeated `reference` or a repeated `type`, `InvalidModelReference` for a reference that is blank,
+    a sigil or a namespace alone, or too long, and `InvalidModelCategory` for an unknown `type`.
+    """
+    for parameter_name in ("reference", "type"):
+        if len(request.query_params.getlist(parameter_name)) > 1:
+            raise_validation_error(message=f"The `{parameter_name}` query parameter accepts a single value")
+
+    # The parser trims the reference itself, and its `raw` is the trimmed text the length limit measures.
+    try:
+        parsed_reference = ModelReference.parse(reference)
+    except ModelReferenceParseError as exc:
+        raise_validation_error(message=exc.message, error_type=ErrorType.INVALID_MODEL_REFERENCE)
+    if len(parsed_reference.raw) > MAX_MODEL_REFERENCE_LENGTH:
+        too_long_message = (
+            f"The model reference holds {len(parsed_reference.raw)} characters once trimmed, more than the {MAX_MODEL_REFERENCE_LENGTH} accepted"
+        )
+        raise_validation_error(message=too_long_message, error_type=ErrorType.INVALID_MODEL_REFERENCE)
+
+    category: ModelCheckCategory | None = None
+    if model_type is not None:
+        try:
+            category = ModelCheckCategory(model_type)
+        except ValueError:
+            valid = ", ".join(sorted(member.value for member in ModelCheckCategory))
+            raise_validation_error(
+                message=f"Invalid model category. Valid values: {valid}",
+                error_type=ErrorType.INVALID_MODEL_CATEGORY,
+            )
+
+    return check_model_reference(model_deck=get_model_deck(), reference=parsed_reference, category=category)

{pipelex_api-0.76.0 → pipelex_api-0.78.0}/pipelex_api/schemas/models.py

@@ -53,8 +53,9 @@ class RunRequest(BaseModel):
     deliberately open (`extra="allow"`): a caller may send extra request
     properties, and they are kept rather than silently dropped. Openness is not
     a waiver, though — an unknown key never satisfies the run-source
-    precondition. Under the layered extension policy (the Pipelex workspace
-    spec `docs/specs/pipelex-platform-api.md` → "Layered extension policy"), an
+    precondition. Under the layered extension policy
+    (`conformance/specs/pipelex-platform-api.md` → "Layered extension policy",
+    in the `conformance` repo beside the tests that verify it), an
     extension-borne method selector is resolved by the layer that owns it
     BEFORE the request reaches this one, so a body arriving here with no source
     this server understands is an error whatever else it carries.

pipelex_api-0.76.0/pipelex_api/routes/pipelex/agent/models.py

@@ -1,49 +0,0 @@
-"""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, judgment. 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)