spot-sdk-python 1.0.0__tar.gz → 1.1.0__tar.gz

{spot_sdk_python-1.0.0 → spot_sdk_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 1.0.0
+Version: 1.1.0
 Summary: Python SDK for SPOT platform - API contracts, models, and utilities
 License: Apache-2.0
 Author: SPOT Project

{spot_sdk_python-1.0.0 → spot_sdk_python-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "1.0.0"
+version = "1.1.0"
 description = "Python SDK for SPOT platform - API contracts, models, and utilities"
 authors = ["SPOT Project <spot@sonn.lu>"]
 license = "Apache-2.0"

{spot_sdk_python-1.0.0 → spot_sdk_python-1.1.0}/spot_sdk/__init__.py

@@ -3,6 +3,7 @@
 from .analysis_context import AnalysisContextReader
 from .analyzer import AnalyzerCapability, AnalyzerInterface, ThreatLevel
 from .config import ConfigOption, ConfigReloadResult, ConfigStatus, ConfigUpdateRequest
+from .config_client import ConfigClient
 from .config_helpers import merge_settings
 from .email import Attachment, Email, EmailHeader
 from .errors import ErrorResponse
@@ -18,6 +19,12 @@ from .results import (
     AnalysisResult,
     IndicatorType,
 )
+from .retriever import (
+    IngestionRequest,
+    IngestionResult,
+    IngestionStatus,
+    MailRetrieverClient,
+)
 from .settings_schema import register_settings_schema
 from .threat_levels import confidence_to_threat_level
 from .workflow import (
@@ -39,6 +46,7 @@ __all__ = [
     "ConfigStatus",
     "ConfigUpdateRequest",
     "ConfigReloadResult",
+    "ConfigClient",
     # Error response
     "ErrorResponse",
     # Email models
@@ -70,6 +78,11 @@ __all__ = [
     "content_hash",
     # Plugin vocabulary
     "PluginKind",
+    # Mail-retriever ingest contract
+    "IngestionRequest",
+    "IngestionResult",
+    "IngestionStatus",
+    "MailRetrieverClient",
     # Orchestration
     "OrchestrationResult",
     "AnalyzerResult",

{spot_sdk_python-1.0.0 → spot_sdk_python-1.1.0}/spot_sdk/plugin.py

@@ -1,14 +1,18 @@
 """Plugin vocabulary shared across the platform.
 
 A "plugin" is any pluggable component registered with a SPOT platform
-through the plugin catalog, installer, and sources. Plugins come in two
-kinds today:
+through the plugin catalog, installer, and sources. Plugins come in
+three kinds today:
 
 - ``analyzer``: runs ``POST /internal/analyze`` and produces an
   ``AnalysisResult`` (a phishing verdict contributing to aggregation).
 - ``context_provider``: runs ``POST /internal/enrich`` and produces an
   ``EnrichmentResult`` whose data populates ``analysis_context`` for
   downstream analyzers.
+- ``mail_retriever``: ingests emails from any source (SMTP filter,
+  IMAP, mailbox API, ...) and submits them to the platform via
+  ``POST /internal/ingest`` on the mail-orchestrator. Retrievers push;
+  the platform never polls them.
 
 The ``PluginKind`` value is surfaced by the platform catalog (derived
 from OCI image labels) so the installer can route a plugin to the
@@ -25,6 +29,7 @@ class PluginKind(str, Enum):
 
     ANALYZER = "analyzer"
     CONTEXT_PROVIDER = "context_provider"
+    MAIL_RETRIEVER = "mail_retriever"
 
     def __str__(self) -> str:  # pragma: no cover - trivial
         return self.value

spot_sdk_python-1.1.0/spot_sdk/retriever.py

@@ -0,0 +1,267 @@
+"""Mail-retriever SDK: ingest models and client.
+
+A mail-retriever is a SPOT plugin that delivers emails to the
+mail-orchestrator. The platform never polls retrievers; retrievers
+**push** by calling ``POST /internal/ingest`` whenever they have a new
+email — irrespective of how they obtained it (Postfix ``content_filter``,
+IMAP IDLE, Maildir watch, future Microsoft Graph webhook, ...).
+
+Two ingestion modes are supported, selected per-call via
+:attr:`IngestionRequest.wait_for_verdict`:
+
+- **Asynchronous** (``wait_for_verdict=False``, default): the
+  orchestrator queues the email for analysis and returns immediately
+  with ``status="accepted"``. Used by retrievers that don't need a
+  per-message decision (Maildir watchers, fire-and-forget journaling).
+- **Synchronous** (``wait_for_verdict=True``): the orchestrator runs
+  the workflow inline and returns the verdict. Used by SMTP-time
+  filters that must decide accept / tag / reject within the MTA's
+  timeout. The retriever supplies its own ``timeout_ms``; on platform
+  timeout the orchestrator returns ``status="timeout"`` so the caller
+  can apply its fail-open / fail-closed policy.
+
+Quick start (a Postfix content_filter retriever)::
+
+    from spot_sdk import Email, EmailHeader, MailRetrieverClient
+
+    client = MailRetrieverClient(
+        url=os.environ["SPOT_MAIL_ORCHESTRATOR_URL"],
+        api_key=os.environ["SPOT_INTERNAL_API_KEY"],
+    )
+    email = Email(headers=EmailHeader(...), body_text="...", source="smtp")
+    result = await client.ingest(email, wait_for_verdict=True, timeout_ms=30000)
+    if result.status == "analyzed" and result.is_phishing:
+        # tag headers, quarantine, or 5xx the SMTP transaction
+        ...
+"""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from typing import Any, cast
+
+import httpx
+from pydantic import BaseModel, Field
+
+from .email import Email
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+# ----------------------------------------------------------------------- #
+# Models
+# ----------------------------------------------------------------------- #
+
+
+class IngestionStatus(str, Enum):
+    """Terminal state of an ingestion call."""
+
+    ACCEPTED = "accepted"  # async path: queued, no verdict yet
+    ANALYZED = "analyzed"  # sync path: verdict is in the response
+    REJECTED = "rejected"  # platform refused (validation / quota)
+    TIMEOUT = "timeout"    # sync path: workflow did not complete in time
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.value
+
+
+class IngestionRequest(BaseModel):
+    """Payload sent by a retriever to ``POST /internal/ingest``."""
+
+    email: Email = Field(
+        ...,
+        description="The full email to analyse, as a spot-sdk Email model.",
+    )
+    workflow_id: str | None = Field(
+        default=None,
+        description=(
+            "Workflow to run for this email. ``None`` means the platform "
+            "default workflow chosen by the orchestrator."
+        ),
+    )
+    priority: str = Field(
+        default="normal",
+        pattern="^(low|normal|high)$",
+        description="Job priority hint for the analyzer-orchestrator queue.",
+    )
+    wait_for_verdict: bool = Field(
+        default=False,
+        description=(
+            "When True, the orchestrator runs the workflow synchronously "
+            "and the response carries the verdict. When False, the "
+            "orchestrator queues the work and returns ``accepted`` "
+            "immediately."
+        ),
+    )
+    timeout_ms: int = Field(
+        default=30_000,
+        ge=1_000,
+        le=300_000,
+        description=(
+            "Caller-side budget when ``wait_for_verdict=True``. The "
+            "orchestrator returns ``status='timeout'`` if the workflow "
+            "does not complete in time so the retriever can apply its "
+            "own fail-open / fail-closed policy."
+        ),
+    )
+
+
+class IngestionResult(BaseModel):
+    """Response returned from ``POST /internal/ingest``."""
+
+    job_id: str = Field(
+        ...,
+        description="Stable id for this ingestion. Track via /internal/jobs/{id}.",
+    )
+    status: IngestionStatus = Field(
+        ...,
+        description="Terminal state of the call.",
+    )
+    is_phishing: bool | None = Field(
+        default=None,
+        description="Verdict; populated only when ``status='analyzed'``.",
+    )
+    threat_level: str | None = Field(
+        default=None,
+        description="Threat level string; populated only when ``status='analyzed'``.",
+    )
+    confidence: float | None = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description="Verdict confidence 0.0–1.0; populated only when ``status='analyzed'``.",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Human-readable error message when ``status='rejected'``.",
+    )
+
+
+# ----------------------------------------------------------------------- #
+# Client
+# ----------------------------------------------------------------------- #
+
+
+class MailRetrieverClient:
+    """HTTP client used by mail-retriever plugins to call the orchestrator.
+
+    Mirrors the shape of :class:`spot_sdk.knowledge.KnowledgeClient`: thin
+    httpx wrapper, internal API key on a fixed header, no retry logic
+    beyond the underlying httpx defaults. Every retriever — push or pull
+    — uses the same client to deliver emails to the mail-orchestrator.
+    """
+
+    DEFAULT_TIMEOUT = 35.0  # slightly above the default IngestionRequest.timeout_ms
+
+    def __init__(
+        self,
+        url: str,
+        api_key: str | None = None,
+        retriever_id: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        """Initialize the client.
+
+        Args:
+            url: Base URL of the mail-orchestrator
+                (e.g. ``http://mail-orchestrator:8000``).
+            api_key: ``SPOT_INTERNAL_API_KEY`` value used to authenticate
+                the call. Required for the orchestrator's
+                ``/internal/ingest`` endpoint.
+            retriever_id: Identifier sent in the ``X-Retriever-Id`` header
+                so the orchestrator can attribute jobs to this plugin
+                (e.g. ``retriever-postfix``). Optional but recommended.
+            timeout: HTTP timeout in seconds. Should be >= the longest
+                ``IngestionRequest.timeout_ms`` the caller will use.
+        """
+        self.url = url.rstrip("/")
+        self.api_key = api_key
+        self.retriever_id = retriever_id
+        self.timeout = timeout
+
+    @classmethod
+    def from_env(cls, *, timeout: float = DEFAULT_TIMEOUT) -> MailRetrieverClient:
+        """Build a client from standard SPOT environment variables.
+
+        Reads ``SPOT_MAIL_ORCHESTRATOR_URL``, ``SPOT_INTERNAL_API_KEY``
+        and ``SPOT_RETRIEVER_ID`` — the same convention used by the
+        api-gateway and knowledge service.
+        """
+        url = os.environ.get("SPOT_MAIL_ORCHESTRATOR_URL")
+        if not url:
+            raise RuntimeError(
+                "SPOT_MAIL_ORCHESTRATOR_URL is not set. The SPOT installer "
+                "normally injects this when the plugin is installed; in "
+                "tests, set it explicitly."
+            )
+        return cls(
+            url=url,
+            api_key=os.environ.get("SPOT_INTERNAL_API_KEY"),
+            retriever_id=os.environ.get("SPOT_RETRIEVER_ID"),
+            timeout=timeout,
+        )
+
+    async def ingest(
+        self,
+        email: Email,
+        *,
+        workflow_id: str | None = None,
+        priority: str = "normal",
+        wait_for_verdict: bool = False,
+        timeout_ms: int = 30_000,
+    ) -> IngestionResult:
+        """Submit an email to the mail-orchestrator for analysis.
+
+        See :class:`IngestionRequest` for the field semantics.
+        """
+        request = IngestionRequest(
+            email=email,
+            workflow_id=workflow_id,
+            priority=priority,
+            wait_for_verdict=wait_for_verdict,
+            timeout_ms=timeout_ms,
+        )
+        # Caller's HTTP timeout must outlive the orchestrator's own work
+        # window; otherwise we'd cancel a synchronous wait that could
+        # still complete server-side.
+        http_timeout = max(self.timeout, (timeout_ms / 1000.0) + 5.0)
+        data = await self._post(
+            "/internal/ingest",
+            json=request.model_dump(mode="json"),
+            timeout=http_timeout,
+        )
+        return IngestionResult(**data)
+
+    async def get_job(self, job_id: str) -> IngestionResult:
+        """Look up a previously-submitted ingestion by id."""
+        async with httpx.AsyncClient(timeout=self.timeout) as c:
+            r = await c.get(
+                f"{self.url}/internal/jobs/{job_id}",
+                headers=self._headers(),
+            )
+            r.raise_for_status()
+            return IngestionResult(**r.json())
+
+    # ------------------------------------------------------------------ #
+    # HTTP helpers
+    # ------------------------------------------------------------------ #
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {"Content-Type": "application/json"}
+        if self.api_key:
+            h["X-Internal-API-Key"] = self.api_key
+        if self.retriever_id:
+            h["X-Retriever-Id"] = self.retriever_id
+        return h
+
+    async def _post(
+        self, path: str, *, json: dict[str, Any], timeout: float
+    ) -> dict[str, Any]:
+        async with httpx.AsyncClient(timeout=timeout) as c:
+            r = await c.post(self.url + path, json=json, headers=self._headers())
+            r.raise_for_status()
+            if r.status_code == 204 or not r.content:
+                return {}
+            return cast("dict[str, Any]", r.json())