spot-sdk-python 1.2.0__tar.gz → 2.0.0__tar.gz

spot_sdk_python-2.0.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: spot-sdk-python
+Version: 2.0.0
+Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
+Author: SPOT Project
+Author-email: SPOT Project <spot@sonn.lu>
+License-Expression: Apache-2.0
+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: pydantic>=2.10,<3
+Requires-Dist: pydantic-settings>=2.0.0,<3
+Requires-Dist: httpx2>=2.13.1,<3
+Requires-Dist: selectolax>=1.0,<1.1
+Requires-Dist: idna>=3.11,<4
+Requires-Dist: fastapi>=0.133.0,<1
+Requires-Dist: starlette>=1.7.0,<2
+Requires-Python: >=3.11, <3.16
+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.0
+```
+
+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",
+    kind=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.0/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.0
+```
+
+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",
+    kind=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.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "spot-sdk-python"
+version = "2.0.0"
+description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "pydantic>=2.10,<3",
+    "pydantic-settings>=2.0.0,<3",
+    "httpx2>=2.13.1,<3",
+    "selectolax>=1.0,<1.1",
+    "idna>=3.11,<4",
+    "fastapi>=0.133.0,<1",
+    "starlette>=1.7.0,<2",
+]
+
+[[project.authors]]
+name = "SPOT Project"
+email = "spot@sonn.lu"
+
+[project.urls]
+Homepage = "https://sonn.lu"
+
+[tool.uv.build-backend]
+module-name = "spot_sdk"
+module-root = ""
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "N",
+    "W",
+]
+ignore = ["E501"]

spot_sdk_python-2.0.0/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "spot-sdk-python"
+version = "2.0.0"
+description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "SPOT Project", email = "spot@sonn.lu" }]
+requires-python = ">=3.11,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "pydantic>=2.10,<3",
+    "pydantic-settings>=2.0.0,<3",
+    "httpx2>=2.13.1,<3",
+    "selectolax>=1.0,<1.1",
+    "idna>=3.11,<4",
+    "fastapi>=0.133.0,<1",
+    "starlette>=1.7.0,<2",
+]
+
+[project.urls]
+Homepage = "https://sonn.lu"
+
+[tool.uv.build-backend]
+module-name = "spot_sdk"
+module-root = ""
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]  # Line too long

spot_sdk_python-2.0.0/spot_sdk/__init__.py

@@ -0,0 +1,161 @@
+"""SPOT SDK: the plugin contract v2, the plugin runtime and its clients."""
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any
+
+from .config import ConfigOption, ConfigStatus, ConfigUpdateRequest
+from .email import Address, Anomaly, AuthResult, EmailView, Envelope, Header, Part, Url
+from .errors import ErrorResponse
+from .knowledge_tags import KnowledgeTag
+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 .proxy import PROXY_SECRET, apply_proxy_credentials
+from .retriever import ActionReport, 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,
+)
+
+if TYPE_CHECKING:
+    from .app import CorrelationMiddleware, PluginHealth, SyncState, create_plugin_app
+    from .clients import SpotAPIError, SpotClient
+    from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
+    from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
+
+# 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(
+        ("CorrelationMiddleware", "PluginHealth", "SyncState", "create_plugin_app"),
+        ".app",
+    ),
+    **dict.fromkeys(("SpotAPIError", "SpotClient"), ".clients"),
+    **dict.fromkeys(
+        ("KnowledgeClient", "KnowledgeDocument", "chunk_text", "content_hash"),
+        ".knowledge",
+    ),
+    **dict.fromkeys(
+        ("LLMClient", "LLMOutputError", "LLMToolCall", "LLMToolCalls", "LLMToolRound"),
+        ".llm",
+    ),
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_LAZY})
+
+
+__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
+    "ActionReport",
+    "IngestionRequest",
+    "IngestionResult",
+    "IngestionStatus",
+    # Plugin manifest
+    "CONTRACT_VERSION",
+    "Egress",
+    "Manifest",
+    "PluginKind",
+    "Resources",
+    "SettingField",
+    "SettingType",
+    # Plugin runtime
+    "CorrelationMiddleware",
+    "PROXY_SECRET",
+    "PluginHealth",
+    "PluginSettings",
+    "SyncState",
+    "apply_proxy_credentials",
+    "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.0/spot_sdk/_json.py

@@ -0,0 +1,46 @@
+"""Strings measured and cut by the size of their JSON.
+
+The view and the LLM client's rendering are sent as JSON, where escapes make
+a string larger than its text: a control character takes six bytes
+(``\\u0001``). ``json.dumps`` with ``ensure_ascii=False`` and pydantic's
+``model_dump_json`` escape strings alike, so sizes here are theirs.
+"""
+
+from __future__ import annotations
+
+import json
+
+_MAX_CHARACTER_BYTES = 6
+"""The most bytes one character takes: a control character's escape."""
+
+
+def json_size(text: str) -> int:
+    """The UTF-8 bytes of ``text``'s JSON string between its quotes, escapes
+    included; a lone surrogate (possible in a string built in Python) counts
+    as three."""
+    escaped = json.dumps(text, ensure_ascii=False)[1:-1]
+    return len(escaped.encode("utf-8", "surrogatepass"))
+
+
+def cut_json(text: str, max_bytes: int) -> tuple[str, bool]:
+    """The longest start of ``text`` whose JSON string takes at most
+    ``max_bytes`` bytes between its quotes (``json_size``), and whether that
+    cut anything.
+
+    A character is kept or dropped whole, so neither an escape nor a
+    character's UTF-8 bytes are split. The text is measured in chunks that
+    surely fit, a sixth of the room left each, then character by character:
+    the work follows ``max_bytes``, whatever the text's length.
+    """
+    if len(text) * _MAX_CHARACTER_BYTES <= max_bytes:
+        return text, False  # it surely fits
+    kept = 0
+    room = max_bytes
+    while kept < len(text):
+        chunk = text[kept : kept + max(room // _MAX_CHARACTER_BYTES, 1)]
+        used = json_size(chunk)
+        if used > room:  # one character, which does not fit
+            break
+        kept += len(chunk)
+        room -= used
+    return text[:kept], kept < len(text)