spot-sdk-python 1.2.1__tar.gz → 2.0.0b1__tar.gz

spot_sdk_python-2.0.0b1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: spot-sdk-python
+Version: 2.0.0b1
+Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
+License: Apache-2.0
+Author: SPOT Project
+Author-email: spot@sonn.lu
+Requires-Python: >=3.11,<3.16
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+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: pydantic (>=2.10,<3.0)
+Requires-Dist: pydantic-settings (>=2.0.0,<3.0.0)
+Requires-Dist: selectolax (>=1.0,<1.1)
+Project-URL: Homepage, https://sonn.lu
+Description-Content-Type: text/markdown
+
+# spot-sdk-python
+
+The SDK for writing plugins of SPOT, the Spear-Phishing Overwatching
+Tool: analyzers, context providers, mail retrievers and responders.
+
+SPOT runs each plugin as a container and calls its `/internal/*` routes
+with the plugin's own token. This package holds what SPOT's core and its
+plugins share:
+
+- **the contract** (Pydantic models): the email view, verdicts and
+  signals, workflow policies, results, and the plugin manifest with its
+  OCI labels;
+- **the parser** core runs on every message at intake
+  (`spot_sdk.mime.parse`), bounded against hostile input, which records
+  what mail clients may read differently as anomalies;
+- **the plugin runtime**: `create_plugin_app` builds the FastAPI app with
+  the routes core calls, token-checked; `PluginSettings` reads the token
+  and secrets from `/run/secrets` and the settings from the environment;
+- **the clients**: `SpotClient` (ingest, message content, results),
+  `KnowledgeClient` (the Knowledge Store) and `LLMClient`
+  (OpenAI-compatible chat models, with the email kept apart from the
+  instructions as untrusted data);
+- **test helpers**: `view_from_eml`, `make_view`, `FakeSpot`,
+  `FakeKnowledgeClient`, `FakeLLM` and `assert_contract`.
+
+## Install
+
+```bash
+pip install spot-sdk-python==2.0.0b1
+```
+
+Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
+SPOT 2.0.
+
+## An analyzer
+
+```python
+from spot_sdk import (
+    AnalyzerVerdict,
+    AnalyzeRequest,
+    Egress,
+    Manifest,
+    PluginKind,
+    PluginSettings,
+    Signal,
+    VerdictClass,
+    create_plugin_app,
+)
+from spot_sdk.signals import AUTH_DMARC_FAIL
+
+MANIFEST = Manifest(
+    id="analyzer-dmarc",
+    version="1.0.0",
+    kinds=[PluginKind.ANALYZER],
+    egress=Egress.NONE,
+)
+
+
+def analyze(request: AnalyzeRequest, settings: PluginSettings) -> AnalyzerVerdict:
+    failed = [
+        result
+        for result in request.email.authentication
+        if result.method == "dmarc" and result.result == "fail"
+    ]
+    if not failed:
+        return AnalyzerVerdict(verdict=VerdictClass.BENIGN, score=10, confidence=60)
+    return AnalyzerVerdict(
+        verdict=VerdictClass.SUSPICIOUS,
+        score=70,
+        confidence=80,
+        signals=[Signal(name=AUTH_DMARC_FAIL, weight=60, evidence="dmarc=fail")],
+    )
+
+
+app = create_plugin_app(MANIFEST, PluginSettings, analyze=analyze)
+```
+
+Serve it with `uvicorn analyzer_dmarc:app --host 0.0.0.0 --port 8000`,
+and test it with `spot_sdk.testing.assert_contract(app, "tests/phish.eml",
+token=...)`.
+
+## Documentation
+
+- [Documentation](https://spot-project.codeberg.page/documentation/sdk/):
+  the contract, writing each kind of plugin, the reference.
+- [Migrating from 1.x](https://spot-project.codeberg.page/documentation/sdk/MIGRATION-2/):
+  every removed name and its replacement. SDK 2 has no compatibility
+  with contract 1.
+- [Source and changelog](https://codeberg.org/SPOT_Project/sdk).
+
+## License
+
+Apache License 2.0.
+

spot_sdk_python-2.0.0b1/README.md

@@ -0,0 +1,93 @@
+# spot-sdk-python
+
+The SDK for writing plugins of SPOT, the Spear-Phishing Overwatching
+Tool: analyzers, context providers, mail retrievers and responders.
+
+SPOT runs each plugin as a container and calls its `/internal/*` routes
+with the plugin's own token. This package holds what SPOT's core and its
+plugins share:
+
+- **the contract** (Pydantic models): the email view, verdicts and
+  signals, workflow policies, results, and the plugin manifest with its
+  OCI labels;
+- **the parser** core runs on every message at intake
+  (`spot_sdk.mime.parse`), bounded against hostile input, which records
+  what mail clients may read differently as anomalies;
+- **the plugin runtime**: `create_plugin_app` builds the FastAPI app with
+  the routes core calls, token-checked; `PluginSettings` reads the token
+  and secrets from `/run/secrets` and the settings from the environment;
+- **the clients**: `SpotClient` (ingest, message content, results),
+  `KnowledgeClient` (the Knowledge Store) and `LLMClient`
+  (OpenAI-compatible chat models, with the email kept apart from the
+  instructions as untrusted data);
+- **test helpers**: `view_from_eml`, `make_view`, `FakeSpot`,
+  `FakeKnowledgeClient`, `FakeLLM` and `assert_contract`.
+
+## Install
+
+```bash
+pip install spot-sdk-python==2.0.0b1
+```
+
+Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
+SPOT 2.0.
+
+## An analyzer
+
+```python
+from spot_sdk import (
+    AnalyzerVerdict,
+    AnalyzeRequest,
+    Egress,
+    Manifest,
+    PluginKind,
+    PluginSettings,
+    Signal,
+    VerdictClass,
+    create_plugin_app,
+)
+from spot_sdk.signals import AUTH_DMARC_FAIL
+
+MANIFEST = Manifest(
+    id="analyzer-dmarc",
+    version="1.0.0",
+    kinds=[PluginKind.ANALYZER],
+    egress=Egress.NONE,
+)
+
+
+def analyze(request: AnalyzeRequest, settings: PluginSettings) -> AnalyzerVerdict:
+    failed = [
+        result
+        for result in request.email.authentication
+        if result.method == "dmarc" and result.result == "fail"
+    ]
+    if not failed:
+        return AnalyzerVerdict(verdict=VerdictClass.BENIGN, score=10, confidence=60)
+    return AnalyzerVerdict(
+        verdict=VerdictClass.SUSPICIOUS,
+        score=70,
+        confidence=80,
+        signals=[Signal(name=AUTH_DMARC_FAIL, weight=60, evidence="dmarc=fail")],
+    )
+
+
+app = create_plugin_app(MANIFEST, PluginSettings, analyze=analyze)
+```
+
+Serve it with `uvicorn analyzer_dmarc:app --host 0.0.0.0 --port 8000`,
+and test it with `spot_sdk.testing.assert_contract(app, "tests/phish.eml",
+token=...)`.
+
+## Documentation
+
+- [Documentation](https://spot-project.codeberg.page/documentation/sdk/):
+  the contract, writing each kind of plugin, the reference.
+- [Migrating from 1.x](https://spot-project.codeberg.page/documentation/sdk/MIGRATION-2/):
+  every removed name and its replacement. SDK 2 has no compatibility
+  with contract 1.
+- [Source and changelog](https://codeberg.org/SPOT_Project/sdk).
+
+## License
+
+Apache License 2.0.

{spot_sdk_python-1.2.1 → spot_sdk_python-2.0.0b1}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "spot-sdk-python"
-version = "1.2.1"
-description = "Python SDK for SPOT platform - API contracts, models, and utilities"
+version = "2.0.0b1"
+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"
 homepage = "https://sonn.lu"
@@ -15,18 +15,22 @@ packages = [
 ]
 
 [tool.poetry.dependencies]
-python = "^3.11"
-pydantic = {extras = ["email"], version = "^2.0.0"}
+python = ">=3.11,<3.16"
+pydantic = "^2.10"
 pydantic-settings = "^2.0.0"
-httpx = "^0.25.0"
-typing-extensions = "^4.8.0"
+httpx = ">=0.25,<1"
+selectolax = ">=1.0,<1.1"
+fastapi = ">=0.115.3,<1"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.0"
 pytest-asyncio = "^0.21.0"
+pytest-cov = "^4.1.0"
 mypy = "^1.5.0"
 
 [tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
 select = ["E", "F", "I", "N", "W"]
 ignore = ["E501"]  # Line too long
-target-version = "py311"

spot_sdk_python-2.0.0b1/spot_sdk/__init__.py

@@ -0,0 +1,118 @@
+"""SPOT SDK: the plugin contract v2, the plugin runtime and its clients."""
+
+from .app import SyncState, create_plugin_app
+from .clients import SpotAPIError, SpotClient
+from .config import ConfigOption, ConfigStatus, ConfigUpdateRequest
+from .email import Address, Anomaly, AuthResult, EmailView, Envelope, Header, Part, Url
+from .errors import ErrorResponse
+from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
+from .knowledge_tags import KnowledgeTag
+from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
+from .logging import configure_logging, get_logger, get_logging_config
+from .manifest import (
+    CONTRACT_VERSION,
+    Egress,
+    Manifest,
+    PluginKind,
+    Resources,
+    SettingField,
+    SettingType,
+)
+from .orchestrator import (
+    AnalyzeRequest,
+    AnalyzerOutcome,
+    AttributedSignal,
+    OrchestrationResult,
+    RespondRequest,
+    StageOutcome,
+)
+from .retriever import IngestionRequest, IngestionResult, IngestionStatus
+from .settings import PluginSettings
+from .verdict import AnalyzerVerdict, Score, Signal, VerdictClass
+from .workflow import (
+    AggregationMethod,
+    AnalyzerConfig,
+    DecisiveSignal,
+    FailureStrategy,
+    ResponseMode,
+    RetrievalLimits,
+    RetryConfig,
+    VerdictPolicy,
+    Workflow,
+    WorkflowStage,
+)
+
+__all__ = [
+    # Email view
+    "Address",
+    "Anomaly",
+    "AuthResult",
+    "EmailView",
+    "Envelope",
+    "Header",
+    "Part",
+    "Url",
+    # Verdicts
+    "AnalyzerVerdict",
+    "Score",
+    "Signal",
+    "VerdictClass",
+    # Workflow
+    "AggregationMethod",
+    "AnalyzerConfig",
+    "DecisiveSignal",
+    "FailureStrategy",
+    "ResponseMode",
+    "RetrievalLimits",
+    "RetryConfig",
+    "VerdictPolicy",
+    "Workflow",
+    "WorkflowStage",
+    # Analyzer and responder calls, results
+    "AnalyzeRequest",
+    "AnalyzerOutcome",
+    "AttributedSignal",
+    "OrchestrationResult",
+    "RespondRequest",
+    "StageOutcome",
+    # Ingestion
+    "IngestionRequest",
+    "IngestionResult",
+    "IngestionStatus",
+    # Plugin manifest
+    "CONTRACT_VERSION",
+    "Egress",
+    "Manifest",
+    "PluginKind",
+    "Resources",
+    "SettingField",
+    "SettingType",
+    # Plugin runtime
+    "PluginSettings",
+    "SyncState",
+    "create_plugin_app",
+    # Clients
+    "LLMClient",
+    "LLMOutputError",
+    "LLMToolCall",
+    "LLMToolCalls",
+    "LLMToolRound",
+    "SpotAPIError",
+    "SpotClient",
+    # Knowledge Store
+    "KnowledgeClient",
+    "KnowledgeDocument",
+    "KnowledgeTag",
+    "chunk_text",
+    "content_hash",
+    # Config models
+    "ConfigOption",
+    "ConfigStatus",
+    "ConfigUpdateRequest",
+    # Error response
+    "ErrorResponse",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "get_logging_config",
+]

spot_sdk_python-2.0.0b1/spot_sdk/app.py

@@ -0,0 +1,332 @@
+"""The plugin runtime: one FastAPI app with the routes core calls.
+
+``create_plugin_app`` builds it from the plugin's manifest, its settings
+class and its handlers:
+
+- ``GET /health`` and ``GET /manifest`` are open;
+- ``POST /internal/analyze``, ``POST /internal/respond``, and
+  ``POST /internal/sync`` with ``GET /internal/state``, exist for the
+  handlers given. Each checks ``Authorization: Bearer <the plugin's own
+  token>`` before it reads the request, and answers 401 otherwise; an empty
+  configured token refuses every call.
+
+An ``async def`` handler, or an object whose ``__call__`` is ``async def``,
+runs on the event loop; any other callable runs in a worker thread, so it may
+block. Either way the clients send the call's ``X-Correlation-ID`` on to SPOT.
+
+Neither the logs nor the error answers hold the request's content: a
+handler's exception is logged by its type and place only, and an invalid
+request is answered with the fields refused, never the values sent.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import inspect
+import traceback
+from collections.abc import Awaitable, Callable, Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from typing import Any, TypeAlias, TypeVar
+
+from fastapi import APIRouter, Depends, FastAPI, HTTPException, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, SecretStr, ValidationError
+from pydantic_core import PydanticSerializationError
+from starlette.concurrency import run_in_threadpool
+from starlette.types import Lifespan
+
+from .clients import correlation_id
+from .logging import get_logger
+from .manifest import Manifest, PluginKind
+from .orchestrator import AnalyzeRequest, RespondRequest
+from .settings import PluginSettings
+from .verdict import AnalyzerVerdict
+
+logger = get_logger(__name__)
+
+SettingsT = TypeVar("SettingsT", bound=PluginSettings)
+ModelT = TypeVar("ModelT", bound=BaseModel)
+
+AnalyzeHandler: TypeAlias = Callable[
+    [AnalyzeRequest, SettingsT], AnalyzerVerdict | Awaitable[AnalyzerVerdict]
+]
+"""``analyze(request, settings) -> AnalyzerVerdict``; an exception is answered 500."""
+RespondHandler: TypeAlias = Callable[
+    [RespondRequest, SettingsT], None | Awaitable[None]
+]
+"""``respond(request, settings) -> None``; it acts only when ``request.mode`` is enforce."""
+SyncHandler: TypeAlias = Callable[[SettingsT], int | Awaitable[int]]
+"""``sync(settings) -> int``: the number of documents written."""
+
+
+class SyncState(BaseModel):
+    """A context provider's syncs, as ``/internal/sync`` and ``/internal/state`` answer."""
+
+    in_progress: bool = False
+    last_sync_at: datetime | None = Field(
+        default=None, description="When the last sync started"
+    )
+    last_finished_at: datetime | None = Field(
+        default=None, description="When the last sync ended"
+    )
+    last_sync_count: int = Field(
+        default=0, description="Documents written by the last sync that succeeded"
+    )
+    last_error: str | None = Field(
+        default=None,
+        description="The exception's type when the last sync failed; None when it succeeded",
+    )
+
+
+def create_plugin_app(
+    manifest: Manifest,
+    settings_cls: type[SettingsT],
+    *,
+    analyze: AnalyzeHandler[SettingsT] | None = None,
+    respond: RespondHandler[SettingsT] | None = None,
+    sync: SyncHandler[SettingsT] | None = None,
+    lifespan: Lifespan[FastAPI] | None = None,
+) -> 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.
+
+    ``lifespan`` is passed to FastAPI as is: an async context manager run
+    around the app's life, to load a model at startup, say.
+
+    ``POST /internal/sync`` answers 202 at once and runs ``sync`` in the
+    background. While a sync runs, another call starts nothing and answers
+    202 with the running sync's state.
+    """
+    _check_kinds(manifest, {"analyze": analyze, "respond": respond, "sync": sync})
+    settings = settings_cls()
+    if not settings.spot_plugin_token.get_secret_value():
+        logger.warning(
+            "The plugin has no token: every /internal call will be refused. Core "
+            "mounts it as /run/secrets/spot_plugin_token; outside a container, set "
+            "SPOT_PLUGIN_TOKEN."
+        )
+    app = FastAPI(
+        title=manifest.id,
+        version=manifest.version,
+        openapi_url=None,
+        lifespan=lifespan,
+    )
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "healthy", "version": manifest.version}
+
+    @app.get("/manifest")
+    async def get_manifest() -> Manifest:
+        return manifest
+
+    internal = APIRouter(
+        prefix="/internal",
+        dependencies=[Depends(_token_check(settings.spot_plugin_token))],
+    )
+
+    if analyze is not None:
+
+        @internal.post("/analyze")
+        async def analyze_route(request: Request) -> Response:
+            call = await _parse(request, AnalyzeRequest)
+            with _correlated(request):
+                try:
+                    answer = await _run(analyze, call, settings)
+                except Exception as error:
+                    _log_failure(f"analysis of job {call.job_id}", error)
+                    return JSONResponse({"detail": "analysis failed"}, status_code=500)
+            try:
+                verdict = AnalyzerVerdict.model_validate(answer)
+            except ValidationError as error:
+                _log_invalid_answer(f"analysis of job {call.job_id}", error)
+                return JSONResponse({"detail": "analysis failed"}, status_code=500)
+            try:
+                body = verdict.model_dump_json()
+            except PydanticSerializationError as error:
+                _log_failure(f"analysis of job {call.job_id}", error)
+                return JSONResponse({"detail": "analysis failed"}, status_code=500)
+            return Response(body, media_type="application/json")
+
+    if respond is not None:
+
+        @internal.post("/respond")
+        async def respond_route(request: Request) -> Response:
+            call = await _parse(request, RespondRequest)
+            with _correlated(request):
+                try:
+                    await _run(respond, call, settings)
+                except Exception as error:
+                    _log_failure(f"response to job {call.job_id}", error)
+                    return JSONResponse({"detail": "response failed"}, status_code=500)
+            return Response(status_code=204)
+
+    if sync is not None:
+        syncs = _SyncRunner(sync, settings)
+
+        @internal.post("/sync", status_code=202)
+        async def sync_route(request: Request) -> SyncState:
+            with _correlated(request):
+                return syncs.start()
+
+        @internal.get("/state")
+        async def state_route() -> SyncState:
+            return syncs.state.model_copy()
+
+    app.include_router(internal)
+    return app
+
+
+_HANDLER_KINDS = {
+    "analyze": PluginKind.ANALYZER,
+    "respond": PluginKind.RESPONDER,
+    "sync": PluginKind.CONTEXT_PROVIDER,
+}
+"""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."""
+    for name, kind in _HANDLER_KINDS.items():
+        declared = kind in manifest.kinds
+        given = handlers[name] is not None
+        if declared and not given:
+            raise ValueError(
+                f"the manifest declares {kind}, but no {name} handler is given"
+            )
+        if given and not declared:
+            raise ValueError(
+                f"the {name} handler is given, but the manifest does not declare {kind}"
+            )
+
+
+class _SyncRunner:
+    """Runs the sync handler in the background, one run at a time."""
+
+    def __init__(self, handler: SyncHandler[Any], settings: PluginSettings) -> None:
+        self._handler = handler
+        self._settings = settings
+        self._task: asyncio.Task[None] | None = None
+        self.state = SyncState()
+
+    def start(self) -> SyncState:
+        """Start a sync unless one runs; the state either way."""
+        if not self.state.in_progress:
+            self.state.in_progress = True
+            self.state.last_sync_at = datetime.now(UTC)
+            self.state.last_error = None
+            self._task = asyncio.create_task(self._run())
+        return self.state.model_copy()
+
+    async def _run(self) -> None:
+        try:
+            count = await _run(self._handler, self._settings)
+            if not isinstance(count, int):
+                raise TypeError(
+                    f"the sync handler returned {type(count).__name__}, not int"
+                )
+            self.state.last_sync_count = count
+        except Exception as error:
+            self.state.last_error = type(error).__name__
+            _log_failure("sync", error)
+        finally:
+            self.state.last_finished_at = datetime.now(UTC)
+            self.state.in_progress = False
+
+
+def _token_check(token: SecretStr) -> Callable[[Request], Awaitable[None]]:
+    expected = token.get_secret_value().encode()
+
+    async def check_token(request: Request) -> None:
+        if not _is_bearer(request.headers.get("authorization"), expected):
+            raise HTTPException(
+                status_code=401,
+                detail="unauthorized",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+    return check_token
+
+
+def _is_bearer(header: str | None, token: bytes) -> bool:
+    """Whether ``header`` is ``Bearer <token>``; an empty token matches nothing."""
+    if not token or header is None:
+        return False
+    scheme, _, presented = header.partition(" ")
+    return scheme.lower() == "bearer" and hmac.compare_digest(presented.encode(), token)
+
+
+async def _parse(request: Request, model: type[ModelT]) -> ModelT:
+    """The request body as ``model``; a 422 names the fields refused, never the values sent.
+
+    The 422 is raised after the handler, so the validation error, which holds
+    the request's content, is not attached as its context.
+    """
+    try:
+        return model.model_validate_json(await request.body())
+    except ValidationError as error:
+        detail = error.errors(
+            include_url=False, include_context=False, include_input=False
+        )
+    raise HTTPException(status_code=422, detail=detail)
+
+
+async def _run(handler: Callable[..., Any], *args: Any) -> Any:
+    """Await an async handler; run any other in a worker thread, in this context.
+
+    A handler is async when it is an ``async def`` function, or an object whose
+    ``__call__`` is one, as FastAPI tells them apart.
+    """
+    if inspect.iscoroutinefunction(handler) or inspect.iscoroutinefunction(
+        getattr(handler, "__call__", None)
+    ):
+        return await handler(*args)
+    return await run_in_threadpool(handler, *args)
+
+
+@contextmanager
+def _correlated(request: Request) -> Iterator[None]:
+    """Make the call's ``X-Correlation-ID`` the one the clients send."""
+    reset = correlation_id.set(request.headers.get("x-correlation-id"))
+    try:
+        yield
+    finally:
+        correlation_id.reset(reset)
+
+
+def _log_failure(what: str, error: Exception) -> None:
+    """Log a handler's failure by its type and place only: its message, or the
+    locations of a validation error, may quote the email, or a directory URL
+    with its credentials."""
+    frame = traceback.extract_tb(error.__traceback__)[-1]
+    logger.error(
+        "%s failed: %s at %s:%s in %s",
+        what,
+        type(error).__name__,
+        frame.filename,
+        frame.lineno,
+        frame.name,
+    )
+
+
+def _log_invalid_answer(what: str, error: ValidationError) -> None:
+    """Log a handler's answer that does not validate by the fields refused and
+    why (``loc`` and ``type``), never their values. The locations are the
+    answer model's own fields, so they hold none of the email."""
+    fields = ", ".join(
+        f"{'.'.join(str(part) for part in detail['loc'])} ({detail['type']})"
+        for detail in error.errors(
+            include_url=False, include_context=False, include_input=False
+        )
+    )
+    logger.error(
+        "%s failed: the handler's answer is not a valid %s; invalid: %s",
+        what,
+        error.title,
+        fields,
+    )