spot-sdk-python 2.0.0b8__tar.gz → 2.0.0b10__tar.gz

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b8
+Version: 2.0.0b10
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 License: Apache-2.0
 Author: SPOT Project
@@ -51,7 +51,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b8
+pip install spot-sdk-python==2.0.0b10
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b8
+pip install spot-sdk-python==2.0.0b10
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "2.0.0b8"
+version = "2.0.0b10"
 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"

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/spot_sdk/__init__.py

@@ -25,7 +25,7 @@ from .orchestrator import (
     RespondRequest,
     StageOutcome,
 )
-from .retriever import IngestionRequest, IngestionResult, IngestionStatus
+from .retriever import ActionReport, IngestionRequest, IngestionResult, IngestionStatus
 from .settings import PluginSettings
 from .verdict import AnalyzerVerdict, Score, Signal, VerdictClass
 from .workflow import (
@@ -110,6 +110,7 @@ __all__ = [
     "RespondRequest",
     "StageOutcome",
     # Ingestion
+    "ActionReport",
     "IngestionRequest",
     "IngestionResult",
     "IngestionStatus",

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/spot_sdk/clients.py

@@ -27,7 +27,12 @@ from pydantic import BaseModel, SecretStr, ValidationError
 
 from .email import Envelope
 from .orchestrator import OrchestrationResult
-from .retriever import IngestionPriority, IngestionRequest, IngestionResult
+from .retriever import (
+    ActionReport,
+    IngestionPriority,
+    IngestionRequest,
+    IngestionResult,
+)
 from .settings import PluginSettings
 
 # The bytes of a raw message encoded at a time: a few milliseconds of a thread
@@ -111,7 +116,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 +125,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 +135,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 +151,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,
@@ -191,7 +192,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 +211,6 @@ class SpotClient:
             ingestion_body,
             raw,
             envelope=envelope,
-            workflow_id=workflow_id,
             priority=priority,
             wait_for_verdict=wait_for_verdict,
             timeout_ms=timeout_ms,
@@ -225,6 +224,16 @@ class SpotClient:
         )
         return read_answer(IngestionResult, response, "POST", "/internal/ingest")
 
+    async def report_action(self, job_id: str, action: str, *, applied: bool) -> None:
+        """Tell SPOT what the retriever did with a message: ``action``, and whether
+        it was ``applied`` (in observe, it is not) (scope ``ingest``)."""
+        report = ActionReport(action=action, applied=applied)
+        await self._call(
+            "POST",
+            f"/internal/jobs/{quote(job_id, safe='')}/action",
+            content=json_body(report.model_dump(mode="json")),
+        )
+
     async def raw(self, email_id: UUID) -> bytes:
         """The stored message, as received (scope ``content:read``)."""
         response = await self._call("GET", f"/internal/emails/{email_id}/raw")

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/spot_sdk/orchestrator.py

@@ -88,5 +88,5 @@ class RespondRequest(BaseModel):
     decided_by: str
     signals: list[AttributedSignal]
     mode: ResponseMode = Field(
-        description="The workflow's response_mode; a responder acts only in enforce"
+        description="The job's mode (its connection's and its route's); a responder acts only in enforce"
     )

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/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,10 +30,12 @@ from pydantic import (
     Field,
     PlainSerializer,
     WithJsonSchema,
+    model_validator,
 )
 
 from .email import Envelope
 from .verdict import Score, VerdictClass
+from .workflow import ResponseMode
 
 
 def _decode_message(value: object) -> bytes:
@@ -78,9 +80,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 +89,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."""
@@ -106,3 +116,18 @@ class IngestionResult(BaseModel):
     error: str | None = Field(
         default=None, description="Why there is no verdict, when the status is timeout"
     )
+    mode: ResponseMode = Field(
+        default="observe",
+        description=(
+            "The job's mode: enforce only when its connection and its route both "
+            "are; a retriever applies its actions only in enforce"
+        ),
+    )
+
+
+class ActionReport(BaseModel):
+    """The body of ``POST /internal/jobs/{job_id}/action``: what a retriever
+    did with a message (or, in observe, would have done)."""
+
+    action: str = Field(pattern=r"^[a-z][a-z0-9_]{0,31}$")
+    applied: bool

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/spot_sdk/testing/fake_spot.py

@@ -21,24 +21,33 @@ from ..email import Envelope
 from ..mime import PartNotFoundError, part_bytes
 from ..orchestrator import OrchestrationResult
 from ..retriever import (
+    ActionReport,
     IngestionPriority,
     IngestionRequest,
     IngestionResult,
     IngestionStatus,
 )
 from ..verdict import VerdictClass
+from ..workflow import ResponseMode
 
 
 class FakeSpot:
     """In-memory gateway with the methods of ``SpotClient``."""
 
     def __init__(
-        self, *, verdict: VerdictClass = VerdictClass.BENIGN, score: int = 0
+        self,
+        *,
+        verdict: VerdictClass = VerdictClass.BENIGN,
+        score: int = 0,
+        mode: ResponseMode = "observe",
     ) -> None:
-        """``verdict`` and ``score`` answer an ingest that waits for the verdict."""
+        """``verdict`` and ``score`` answer an ingest that waits for the verdict;
+        ``mode`` is the mode of every job."""
         self.verdict = verdict
         self.score = score
+        self.mode = mode
         self.ingested: list[IngestionRequest] = []
+        self.actions: list[tuple[str, ActionReport]] = []
         self._emails: dict[UUID, bytes] = {}
         self._results: dict[str, OrchestrationResult] = {}
 
@@ -57,7 +66,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 +73,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,
@@ -75,7 +82,10 @@ class FakeSpot:
         email_id = self.add_email(request.raw)
         if not wait_for_verdict:
             return IngestionResult(
-                job_id=job_id, email_id=email_id, status=IngestionStatus.ACCEPTED
+                job_id=job_id,
+                email_id=email_id,
+                status=IngestionStatus.ACCEPTED,
+                mode=self.mode,
             )
         return IngestionResult(
             job_id=job_id,
@@ -83,8 +93,12 @@ class FakeSpot:
             status=IngestionStatus.ANALYZED,
             verdict=self.verdict,
             score=self.score,
+            mode=self.mode,
         )
 
+    async def report_action(self, job_id: str, action: str, *, applied: bool) -> None:
+        self.actions.append((job_id, ActionReport(action=action, applied=applied)))
+
     async def raw(self, email_id: UUID) -> bytes:
         return self._stored(email_id, f"/internal/emails/{email_id}/raw")
 

{spot_sdk_python-2.0.0b8 → spot_sdk_python-2.0.0b10}/spot_sdk/workflow.py

@@ -10,7 +10,7 @@ from pydantic import BaseModel, Field, model_validator
 from .verdict import VerdictClass
 
 ResponseMode = Literal["observe", "enforce"]
-"""Whether responders act on verdicts (``enforce``) or only record them (``observe``)."""
+"""Whether responders and retrievers act on verdicts (``enforce``) or only record them (``observe``): the mode of a job, from its connection and its route."""
 
 DECISIVE_SIGNAL_PATTERN = r"^[a-z0-9_]+(\.[a-z0-9_]+)*\.([a-z0-9_]+|\*)$"
 """A signal name, or a prefix ending in ``.*``."""
@@ -181,10 +181,6 @@ class Workflow(BaseModel):
     on_verdict: dict[VerdictClass, list[str]] = Field(
         default_factory=dict, description="Responder ids to call, by verdict"
     )
-    response_mode: ResponseMode = Field(
-        default="observe",
-        description="Sent to responders as mode; a responder acts only in enforce",
-    )
 
     @model_validator(mode="after")
     def _decision_stages_exist(self) -> Self: