spot-sdk-python 2.0.0b7__tar.gz → 2.0.0b9__tar.gz

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b7
+Version: 2.0.0b9
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 License: Apache-2.0
 Author: SPOT Project
@@ -13,12 +13,13 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
-Requires-Dist: fastapi (>=0.115.3,<1)
-Requires-Dist: httpx (>=0.25,<1)
+Requires-Dist: fastapi (>=0.133.0,<1)
+Requires-Dist: httpx2 (>=2.13.1,<3)
 Requires-Dist: idna (>=3.11,<4)
 Requires-Dist: pydantic (>=2.10,<3.0)
 Requires-Dist: pydantic-settings (>=2.0.0,<3.0.0)
 Requires-Dist: selectolax (>=1.0,<1.1)
+Requires-Dist: starlette (>=1.7.0,<2)
 Project-URL: Homepage, https://sonn.lu
 Description-Content-Type: text/markdown
 
@@ -50,7 +51,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b7
+pip install spot-sdk-python==2.0.0b9
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
@@ -75,7 +76,7 @@ from spot_sdk.signals import AUTH_DMARC_FAIL
 MANIFEST = Manifest(
     id="analyzer-dmarc",
     version="1.0.0",
-    kinds=[PluginKind.ANALYZER],
+    kind=PluginKind.ANALYZER,
     egress=Egress.NONE,
 )
 

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b7
+pip install spot-sdk-python==2.0.0b9
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
@@ -51,7 +51,7 @@ from spot_sdk.signals import AUTH_DMARC_FAIL
 MANIFEST = Manifest(
     id="analyzer-dmarc",
     version="1.0.0",
-    kinds=[PluginKind.ANALYZER],
+    kind=PluginKind.ANALYZER,
     egress=Egress.NONE,
 )
 

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "2.0.0b7"
+version = "2.0.0b9"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 authors = ["SPOT Project <spot@sonn.lu>"]
 license = "Apache-2.0"
@@ -18,14 +18,15 @@ packages = [
 python = ">=3.11,<3.16"
 pydantic = "^2.10"
 pydantic-settings = "^2.0.0"
-httpx = ">=0.25,<1"
+httpx2 = ">=2.13.1,<3"
 selectolax = ">=1.0,<1.1"
 idna = ">=3.11,<4"
-fastapi = ">=0.115.3,<1"
+fastapi = ">=0.133.0,<1"
+starlette = ">=1.7.0,<2"
 
 [tool.poetry.group.dev.dependencies]
-pytest = "^7.4.0"
-pytest-asyncio = "^0.21.0"
+pytest = "^9.0.3"
+pytest-asyncio = "^1.3.0"
 pytest-cov = "^4.1.0"
 mypy = "^1.5.0"
 

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/__init__.py

@@ -47,7 +47,7 @@ if TYPE_CHECKING:
     from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
     from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
 
-# The modules that import FastAPI, Starlette or httpx load on first use, so importing
+# The modules that import FastAPI, Starlette or httpx2 load on first use, so importing
 # `spot_sdk.mime` or the models stays light (PEP 562).
 _LAZY = {
     **dict.fromkeys(("PluginHealth", "SyncState", "create_plugin_app"), ".app"),

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/app.py

@@ -215,9 +215,9 @@ def create_plugin_app(
 ) -> FastAPI:
     """Build the plugin's app; the settings are read once, here.
 
-    Each kind the manifest declares needs its handler (analyzer: ``analyze``,
-    responder: ``respond``, context provider: ``sync``; a mail retriever has
-    none), and each handler its kind, or ``ValueError`` is raised.
+    The manifest's kind needs its handler (analyzer: ``analyze``, responder:
+    ``respond``, context provider: ``sync``; a mail retriever has none), and
+    each handler its kind, or ``ValueError`` is raised.
 
     ``lifespan`` is passed to FastAPI as is: an async context manager run
     around the app's life, to load a model at startup, say.
@@ -248,7 +248,7 @@ def create_plugin_app(
     components of that document alone, so read it from this app: another
     FastAPI app that includes its routes leaves their ``$ref`` dangling.
     """
-    _check_kinds(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
+    _check_kind(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
     settings = settings_cls()
     if not settings.spot_plugin_token.get_secret_value():
         logger.warning(
@@ -398,10 +398,10 @@ _HANDLER_KINDS = {
 """The kind each handler serves; a mail retriever has no handler."""
 
 
-def _check_kinds(manifest: Manifest, handlers: dict[str, object]) -> None:
-    """Each kind the manifest declares has its handler, and each handler its kind."""
+def _check_kind(manifest: Manifest, handlers: dict[str, object]) -> None:
+    """The manifest's kind has its handler, and each handler its kind."""
     for name, kind in _HANDLER_KINDS.items():
-        declared = kind in manifest.kinds
+        declared = kind is manifest.kind
         given = handlers[name] is not None
         if declared and not given:
             raise ValueError(

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/clients.py

@@ -22,7 +22,7 @@ from typing import Any, TypeVar
 from urllib.parse import quote
 from uuid import UUID
 
-import httpx
+import httpx2
 from pydantic import BaseModel, SecretStr, ValidationError
 
 from .email import Envelope
@@ -56,7 +56,7 @@ class SpotAPIError(Exception):
 
 
 def read_answer(
-    model: type[ModelT], response: httpx.Response, method: str, path: str
+    model: type[ModelT], response: httpx2.Response, method: str, path: str
 ) -> ModelT:
     """SPOT's answer as ``model``. One that does not validate raises
     ``SpotAPIError`` after the handler, so no validation error, which quotes
@@ -70,8 +70,8 @@ def read_answer(
 
 def json_body(value: Any) -> bytes:
     """``value`` as ASCII JSON, lone surrogates escaped, for a body sent with
-    ``Content-Type: application/json``: the bytes do not depend on the httpx
-    version (0.28 encodes a ``json=`` body as UTF-8 and refuses them)."""
+    ``Content-Type: application/json``: httpx2 encodes a ``json=`` body as UTF-8
+    and refuses lone surrogates, so the SDK encodes the body itself."""
     return json.dumps(value).encode()
 
 
@@ -84,8 +84,8 @@ async def spot_request(
     json: Any = None,
     content: bytes | None = None,
     timeout: float,
-    transport: httpx.AsyncBaseTransport | None = None,
-) -> httpx.Response:
+    transport: httpx2.AsyncBaseTransport | None = None,
+) -> httpx2.Response:
     """Call a SPOT service as a plugin; an error status raises ``SpotAPIError``.
 
     The body is ``json`` encoded by :func:`json_body`, or ``content``, a JSON
@@ -98,7 +98,7 @@ async def spot_request(
         content = json_body(json)
     if content is not None:
         headers["Content-Type"] = "application/json"
-    async with httpx.AsyncClient(timeout=timeout, transport=transport) as client:
+    async with httpx2.AsyncClient(timeout=timeout, transport=transport) as client:
         response = await client.request(
             method, base_url + path, content=content, headers=headers
         )
@@ -111,7 +111,6 @@ def ingestion_request(
     raw: bytes,
     *,
     envelope: Envelope | None = None,
-    workflow_id: str | None = None,
     priority: IngestionPriority = "normal",
     wait_for_verdict: bool = False,
     timeout_ms: int = 30_000,
@@ -121,7 +120,6 @@ def ingestion_request(
     return IngestionRequest(
         raw=base64.b64encode(raw).decode("ascii"),
         envelope=envelope,
-        workflow_id=workflow_id,
         priority=priority,
         wait_for_verdict=wait_for_verdict,
         timeout_ms=timeout_ms,
@@ -132,7 +130,6 @@ def ingestion_body(
     raw: bytes,
     *,
     envelope: Envelope | None = None,
-    workflow_id: str | None = None,
     priority: IngestionPriority = "normal",
     wait_for_verdict: bool = False,
     timeout_ms: int = 30_000,
@@ -149,7 +146,6 @@ def ingestion_body(
     request = IngestionRequest(
         raw=(pieces[0] if pieces else b"").decode("ascii"),
         envelope=envelope,
-        workflow_id=workflow_id,
         priority=priority,
         wait_for_verdict=wait_for_verdict,
         timeout_ms=timeout_ms,
@@ -169,12 +165,12 @@ class SpotClient:
         token: SecretStr,
         *,
         timeout: float = DEFAULT_TIMEOUT,
-        transport: httpx.AsyncBaseTransport | None = None,
+        transport: httpx2.AsyncBaseTransport | None = None,
     ) -> None:
         """Build a client of the gateway at ``base_url``.
 
         ``timeout`` bounds each call, in seconds; ``transport`` replaces the
-        network, for tests (``httpx.MockTransport``).
+        network, for tests (``httpx2.MockTransport``).
         """
         self.base_url = base_url.rstrip("/")
         self.token = token
@@ -191,7 +187,6 @@ class SpotClient:
         raw: bytes,
         *,
         envelope: Envelope | None = None,
-        workflow_id: str | None = None,
         priority: IngestionPriority = "normal",
         wait_for_verdict: bool = False,
         timeout_ms: int = 30_000,
@@ -211,7 +206,6 @@ class SpotClient:
             ingestion_body,
             raw,
             envelope=envelope,
-            workflow_id=workflow_id,
             priority=priority,
             wait_for_verdict=wait_for_verdict,
             timeout_ms=timeout_ms,
@@ -250,7 +244,7 @@ class SpotClient:
         *,
         content: bytes | None = None,
         timeout: float | None = None,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         return await spot_request(
             self.base_url,
             self.token,

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/knowledge.py

@@ -36,7 +36,7 @@ from datetime import datetime
 from typing import TYPE_CHECKING, Any
 from urllib.parse import quote
 
-import httpx
+import httpx2
 from pydantic import BaseModel, Field, SecretStr
 
 from .clients import read_answer, spot_request
@@ -187,7 +187,7 @@ class KnowledgeClient:
         source: str = "",
         timeout: float = DEFAULT_TIMEOUT,
         retrieval_limits: RetrievalLimits | None = None,
-        transport: httpx.AsyncBaseTransport | None = None,
+        transport: httpx2.AsyncBaseTransport | None = None,
     ) -> None:
         """Build a client of the store at ``url``.
 
@@ -201,7 +201,7 @@ class KnowledgeClient:
             retrieval_limits: Caps applied to ``fetch()``; they only shrink
                 what the caller asks for.
             transport: Replaces the network, for tests
-                (``httpx.MockTransport``).
+                (``httpx2.MockTransport``).
         """
         self.url = url.rstrip("/")
         self.token = token
@@ -318,7 +318,7 @@ class KnowledgeClient:
 
     async def _call(
         self, method: str, path: str, *, json: Any = None
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         return await spot_request(
             self.url,
             self.token,

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/llm.py

@@ -40,7 +40,7 @@ from datetime import UTC, datetime
 from typing import Any, Self, TypeVar, overload
 from uuid import UUID
 
-import httpx
+import httpx2
 from pydantic import (
     BaseModel,
     Field,
@@ -154,7 +154,7 @@ class LLMClient:
         options: Mapping[str, Any] | None = None,
         max_bytes: int = DEFAULT_MAX_BYTES,
         timeout: float = DEFAULT_TIMEOUT,
-        transport: httpx.AsyncBaseTransport | None = None,
+        transport: httpx2.AsyncBaseTransport | None = None,
     ) -> None:
         """Build a client of the server at ``base_url``.
 
@@ -178,7 +178,7 @@ class LLMClient:
                 lowered value is used.
             timeout: Request timeout in seconds.
             transport: Replaces the network, for tests
-                (``httpx.MockTransport``).
+                (``httpx2.MockTransport``).
         """
         _check_budget(max_bytes)
         self.base_url = base_url.rstrip("/")
@@ -249,7 +249,7 @@ class LLMClient:
         results of earlier calls go back in ``tool_rounds``, oldest first,
         with the same ``tools``. Raises ``LLMOutputError`` when the answer
         is empty, does not parse, or calls tools that were not given, and
-        ``httpx.HTTPStatusError`` on an error status.
+        ``httpx2.HTTPStatusError`` on an error status.
         """
         body: dict[str, Any] = {
             **self.options,
@@ -291,7 +291,7 @@ class LLMClient:
         headers = {"Content-Type": "application/json"}
         if self.api_key is not None:
             headers["Authorization"] = f"Bearer {self.api_key.get_secret_value()}"
-        async with httpx.AsyncClient(
+        async with httpx2.AsyncClient(
             timeout=self.timeout, transport=self._transport
         ) as client:
             response = await client.post(

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/manifest.py

@@ -3,7 +3,7 @@
 ``Manifest.labels()`` renders the labels, so a plugin's Dockerfile labels
 come from the same object that its ``GET /manifest`` returns. The catalog
 refuses an image with an unknown kind or a contract other than
-``CONTRACT_VERSION``.
+``CONTRACT_VERSION``. A plugin has one kind.
 """
 
 from __future__ import annotations
@@ -33,7 +33,7 @@ LABEL_RESOURCES = "spot.plugin.resources"
 
 
 class PluginKind(StrEnum):
-    """What a plugin does; one plugin may be of several kinds."""
+    """What a plugin does; a plugin has exactly one kind."""
 
     ANALYZER = "analyzer"  # answers POST /internal/analyze with a verdict
     CONTEXT_PROVIDER = "context_provider"  # fills the Knowledge Store
@@ -230,7 +230,7 @@ class Manifest(BaseModel):
 
     id: str
     version: str
-    kinds: list[PluginKind] = Field(min_length=1)
+    kind: PluginKind
     contract: int = CONTRACT_VERSION
     egress: Egress = Egress.CONTENT
     capabilities: list[str] = Field(default_factory=list)
@@ -243,6 +243,18 @@ class Manifest(BaseModel):
     requires_external_ingress: bool = False
     resources: Resources | None = None
 
+    @model_validator(mode="before")
+    @classmethod
+    def _refuse_kinds(cls, data: Any) -> Any:
+        """Refuse ``kinds`` rather than drop it as other unknown fields are: a
+        plugin built for several kinds must be split, not silently cut to one."""
+        if isinstance(data, dict) and "kinds" in data:
+            raise ValueError(
+                "kinds is no longer taken: a plugin has one kind (kind); split a "
+                "plugin of several kinds into one plugin per kind"
+            )
+        return data
+
     def labels(self) -> dict[str, str]:
         """The OCI labels that declare this manifest; unset optional labels are left out."""
         settings = {
@@ -253,7 +265,7 @@ class Manifest(BaseModel):
         labels = {
             LABEL_ID: self.id,
             LABEL_VERSION: self.version,
-            LABEL_KIND: ",".join(self.kinds),
+            LABEL_KIND: self.kind.value,
             LABEL_CONTRACT: str(self.contract),
             LABEL_EGRESS: self.egress.value,
             LABEL_CAPABILITIES: ",".join(self.capabilities),

spot_sdk_python-2.0.0b9/spot_sdk/model_input.py

@@ -0,0 +1,190 @@
+"""The text a phishing model reads, and the manifest its files carry.
+
+Training (spot-models) and inference (analyzer-nlp, analyzer-ml) call the same
+``model_text``, so a model reads at inference the text it was trained on. A
+released normalisation never changes: another one gets a new name, and a
+model's ``spot-model.json`` names the one it was trained with.
+
+``tests/data/model_text_golden.json`` freezes ``spot-text-1``: a change to any
+of its outputs is a new normalisation name, never an edit of ``spot-text-1``.
+That includes what ``spot_sdk.mime.visible`` and the interpreter's HTML
+entities and Unicode tables give it.
+
+Every pattern below runs in linear time: a pattern that can rescan a long run
+of text from each of its starts is a denial of service on a 1 MiB body.
+"""
+
+import html
+import re
+from pathlib import Path
+from typing import Final
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from .mime import visible
+
+TEXT_V1: Final = "spot-text-1"
+TEXT_VERSIONS: Final = frozenset({TEXT_V1})
+MANIFEST_FILE: Final = "spot-model.json"
+
+# spot-text-1's models are trained on MeAJOR v2's ham, which its authors
+# anonymised with markers. Its URL and address markers read as real URLs and
+# addresses do; its other markers, and only these, are dropped. Bracketed text
+# that is not one of them ([EXTERNAL], [PATCH]) stays, in training and in mail.
+_WORDS: Final = {"URL": " URL ", "EMAIL": " EMAIL ", "EMAIL_ADDRESS": " EMAIL "}
+_ANGLE_DROPPED: Final = (
+    "SYMBOL",
+    "SIMBOL",
+    "EMOJI",
+    "EMAIL_SEPARATOR",
+    "FILE",
+    "PHONE",
+    "PGP",
+)
+# The bracket markers MeAJOR v2 uses at least 100 times that name an entity type
+_BRACKET_DROPPED: Final = (
+    "ORGANIZATION",
+    "PRODUCT",
+    "NAME",
+    "FINANCIAL_INFO",
+    "REFERENCE_NUMBER",
+    "DATE",
+    "ADDRESS",
+    "TIME",
+    "PHONE_NUMBER",
+    "FILE_NAME",
+    "USERNAME",
+    "INITIALS",
+    "FILE_PATH",
+    "IP_ADDRESS",
+    "NUMBER",
+    "VERSION",
+    "LOCATION",
+    "SYMBOL",
+    "VARIABLE",
+    "PASSWORD",
+    "FAX_NUMBER",
+    "IMAGE",
+)
+_ANGLE = re.compile(r"<\|(URL|EMAIL|" + "|".join(_ANGLE_DROPPED) + r")\|>")
+_BRACKET = re.compile(r"\[(URL|EMAIL_ADDRESS|" + "|".join(_BRACKET_DROPPED) + r")\]")
+# A tag is "<", an optional "/", a name (letters, digits, "_" and "-", with an
+# optional "prefix:" as in Outlook's <o:p>) followed by a space, "/" or ">", then
+# attributes without "<" or ">"; or "<!" or "<?" up to ">" (a comment, a doctype,
+# an XML declaration). A ">" inside a quoted attribute or a comment ends the tag.
+# So "1 < 2", "Bob <bob@corp.example>" and
+# "<https://evil.example/x>" hold no tag. The possessive quantifiers keep each
+# "<" from rescanning.
+_TAG = re.compile(
+    r"</?[A-Za-z][A-Za-z0-9_-]*+(?::[A-Za-z][A-Za-z0-9_-]*+)?+(?=[\s/>])[^<>]*+>"
+    r"|<[!?][^<>]*+>"
+)
+# A script or a style: the view's visible_text leaves their contents out, so
+# the text of a dataset does too. An unclosed one runs to the end.
+_RAW_OPEN = re.compile(r"<(script|style)(?=[\s/>])", re.IGNORECASE)
+_RAW_CLOSE = {
+    name: re.compile(rf"</{name}(?=[\s/>])[^<>]*+>?", re.IGNORECASE)
+    for name in ("script", "style")
+}
+_URL = re.compile(r"(?:https?://|www\.)[^\s<>]+", re.IGNORECASE)
+# The lookbehind starts a match only at the start of a run of address
+# characters, and the parts are bounded (RFC 5321: 64 for the local part, 63
+# for a label), so each character is scanned a bounded number of times.
+_EMAIL = re.compile(r"(?<![\w.+-])[\w.+-]{1,64}@[\w-]{1,63}(?:\.[\w-]{1,63}){1,8}")
+_SPACE = re.compile(r"\s+")
+
+
+def _marker(match: re.Match[str]) -> str:
+    return _WORDS.get(match.group(1), " ")
+
+
+def _without_raw_text(text: str) -> str:
+    """``text`` without its ``<script>`` and ``<style>`` elements, in one pass."""
+    parts: list[str] = []
+    position = 0
+    while opening := _RAW_OPEN.search(text, position):
+        parts.append(text[position : opening.start()])
+        closing = _RAW_CLOSE[opening.group(1).lower()].search(text, opening.end())
+        if closing is None:
+            return " ".join(parts)
+        position = closing.end()
+        parts.append(" ")
+    parts.append(text[position:])
+    return "".join(parts)
+
+
+def model_text(subject: str, body: str, version: str = TEXT_V1) -> str:
+    """The text a model of normalisation ``version`` reads from a subject and
+    a body: the email's visible text at inference, a dataset's text in training.
+
+    ``spot-text-1``: HTML entities decoded; characters that render as nothing
+    removed; ``<script>`` and ``<style>`` elements dropped, as the view's
+    ``visible_text`` leaves them out; MeAJOR's markers read as above (before
+    the tags, as <|URL|> looks like one); tags dropped (text that is not a
+    tag, such as ``1 < 2``, stays, and so do the angle brackets around an
+    address or a URL); each URL (up to the next space or angle bracket, so
+    trailing punctuation goes with it) and address replaced by the word URL or
+    EMAIL; whitespace collapsed. Case is kept: an uncased tokenizer lowers it.
+    Escaped markup (``&lt;b&gt;``) is decoded first, so it is dropped as a
+    tag.
+    """
+    if version not in TEXT_VERSIONS:
+        raise ValueError(f"unknown model text normalisation: {version}")
+    text = _without_raw_text(visible(html.unescape(f"{subject} {body}")))
+    text = _ANGLE.sub(_marker, text)
+    text = _TAG.sub(" ", text)
+    text = _URL.sub(" URL ", text)
+    text = _EMAIL.sub(" EMAIL ", text)
+    text = _BRACKET.sub(_marker, text)
+    return _SPACE.sub(" ", text).strip()
+
+
+class ModelManifest(BaseModel):
+    """``spot-model.json``: which model a directory holds, and the input it reads."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str = Field(pattern=r"^[a-z0-9][a-z0-9-]*$")
+    version: str = Field(pattern=r"^[A-Za-z0-9][A-Za-z0-9._+-]*$", max_length=64)
+    text: str = TEXT_V1
+    max_tokens: int | None = Field(default=None, ge=1, le=512)
+
+    @field_validator("text")
+    @classmethod
+    def _known_text(cls, text: str) -> str:
+        if text not in TEXT_VERSIONS:
+            raise ValueError(f"unknown model text normalisation: {text}")
+        return text
+
+    @property
+    def label(self) -> str:
+        """The model's name and version, as a verdict's ``model_version`` gives them."""
+        return f"{self.name} {self.version}"
+
+
+def read_manifest(directory: Path) -> ModelManifest:
+    """The manifest of a model directory; ``ValueError`` names the file and says
+    ``missing``, ``unreadable`` or ``invalid`` with the failing fields."""
+    path = directory / MANIFEST_FILE
+    try:
+        raw = path.read_bytes()
+    except FileNotFoundError:
+        raise ValueError(f"{MANIFEST_FILE}: missing") from None
+    except OSError:
+        raise ValueError(f"{MANIFEST_FILE}: unreadable") from None
+    try:
+        return ModelManifest.model_validate_json(raw)
+    except ValidationError as error:
+        # The names of the failing fields, never their values
+        names = sorted(
+            {
+                repr(".".join(map(str, e["loc"]))) if e["loc"] else "the document"
+                for e in error.errors()
+            }
+        )
+        raise ValueError(f"{MANIFEST_FILE}: invalid ({', '.join(names)})") from None
+
+
+def write_manifest(directory: Path, manifest: ModelManifest) -> None:
+    """Write ``manifest`` as the directory's ``spot-model.json``."""
+    (directory / MANIFEST_FILE).write_text(manifest.model_dump_json(indent=2) + "\n")

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/retriever.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 import base64
 import binascii
 from enum import StrEnum
-from typing import Annotated, Literal
+from typing import Annotated, Any, Literal
 from uuid import UUID
 
 from pydantic import (
@@ -30,6 +30,7 @@ from pydantic import (
     Field,
     PlainSerializer,
     WithJsonSchema,
+    model_validator,
 )
 
 from .email import Envelope
@@ -78,9 +79,6 @@ class IngestionRequest(BaseModel):
 
     raw: Base64Message = Field(description="The RFC 5322 message")
     envelope: Envelope | None = None
-    workflow_id: str | None = Field(
-        default=None, description="None: the platform's default workflow"
-    )
     priority: IngestionPriority = "normal"
     wait_for_verdict: bool = False
     timeout_ms: int = Field(
@@ -90,6 +88,17 @@ class IngestionRequest(BaseModel):
         description="The caller's budget when wait_for_verdict is set",
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _refuse_workflow_id(cls, data: Any) -> Any:
+        """Refuse ``workflow_id`` rather than drop it as other unknown fields are:
+        a retriever that still names a workflow would otherwise be silently routed."""
+        if isinstance(data, dict) and "workflow_id" in data:
+            raise ValueError(
+                "workflow_id is no longer taken: SPOT's routes choose the workflow"
+            )
+        return data
+
 
 class IngestionResult(BaseModel):
     """The response of ``POST /internal/ingest`` for a stored message."""

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/testing/contract.py

@@ -2,7 +2,7 @@
 calls as the contract says.
 
 FastAPI's ``TestClient`` is imported when a check runs, not with
-``spot_sdk.testing``: Starlette 1.x warns when it is imported with httpx.
+``spot_sdk.testing``, which stays free of the test client.
 """
 
 from __future__ import annotations
@@ -22,7 +22,7 @@ from .fake_knowledge_client import FakeKnowledgeClient
 from .views import view_from_eml
 
 if TYPE_CHECKING:
-    import httpx
+    import httpx2
     from fastapi.testclient import TestClient
 
 # The document the second sync of a provider must remove: a record gone from
@@ -184,7 +184,7 @@ def _sync(client: TestClient, token: str, timeout: float) -> SyncState:
     return state
 
 
-def _state(answer: httpx.Response, status: int) -> SyncState:
+def _state(answer: httpx2.Response, status: int) -> SyncState:
     """The ``SyncState`` a route answers with ``status``."""
     route = answer.request.url.path
     if answer.status_code != status:

{spot_sdk_python-2.0.0b7 → spot_sdk_python-2.0.0b9}/spot_sdk/testing/fake_spot.py

@@ -57,7 +57,6 @@ class FakeSpot:
         raw: bytes,
         *,
         envelope: Envelope | None = None,
-        workflow_id: str | None = None,
         priority: IngestionPriority = "normal",
         wait_for_verdict: bool = False,
         timeout_ms: int = 30_000,
@@ -65,7 +64,6 @@ class FakeSpot:
         request = ingestion_request(
             raw,
             envelope=envelope,
-            workflow_id=workflow_id,
             priority=priority,
             wait_for_verdict=wait_for_verdict,
             timeout_ms=timeout_ms,