spot-sdk-python 1.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

spot_sdk/__init__.py

@@ -1,99 +1,161 @@
-"""SPOT API interfaces and data models."""
+"""SPOT SDK: the plugin contract v2, the plugin runtime and its clients."""
 
-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 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 import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
 from .knowledge_tags import KnowledgeTag
 from .logging import configure_logging, get_logger, get_logging_config
-from .ollama import LLMResponse, OllamaClientProtocol
-from .orchestrator import AnalyzerResult, OrchestrationResult, WorkflowStageResult
-from .plugin import PluginKind
-from .results import (
-    AnalysisIndicator,
-    AnalysisMetadata,
-    AnalysisResult,
-    IndicatorType,
+from .manifest import (
+    CONTRACT_VERSION,
+    Egress,
+    Manifest,
+    PluginKind,
+    Resources,
+    SettingField,
+    SettingType,
 )
-from .retriever import (
-    IngestionRequest,
-    IngestionResult,
-    IngestionStatus,
-    MailRetrieverClient,
+from .orchestrator import (
+    AnalyzeRequest,
+    AnalyzerOutcome,
+    AttributedSignal,
+    OrchestrationResult,
+    RespondRequest,
+    StageOutcome,
 )
-from .settings_schema import register_settings_schema
-from .threat_levels import confidence_to_threat_level
+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__ = [
-    # Analyzer interface
-    "AnalyzerInterface",
-    "AnalyzerCapability",
-    "ThreatLevel",
+    # 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",
-    "ConfigReloadResult",
-    "ConfigClient",
     # Error response
     "ErrorResponse",
-    # Email models
-    "Email",
-    "EmailHeader",
-    "Attachment",
-    "AnalysisContextReader",
-    # Analysis results
-    "AnalysisResult",
-    "AnalysisIndicator",
-    "AnalysisMetadata",
-    "IndicatorType",
     # Logging
     "configure_logging",
     "get_logger",
     "get_logging_config",
-    # Workflow
-    "Workflow",
-    "WorkflowStage",
-    "AnalyzerConfig",
-    "RetryConfig",
-    "RetrievalLimits",
-    "FailureStrategy",
-    # Knowledge Store
-    "KnowledgeDocument",
-    "KnowledgeClient",
-    "KnowledgeTag",
-    "chunk_text",
-    "content_hash",
-    # Plugin vocabulary
-    "PluginKind",
-    # Mail-retriever ingest contract
-    "IngestionRequest",
-    "IngestionResult",
-    "IngestionStatus",
-    "MailRetrieverClient",
-    # Orchestration
-    "OrchestrationResult",
-    "AnalyzerResult",
-    "WorkflowStageResult",
-    # Ollama protocol
-    "OllamaClientProtocol",
-    "LLMResponse",
-    # Settings schema
-    "register_settings_schema",
-    # Config helpers
-    "merge_settings",
-    # Threat levels
-    "confidence_to_threat_level",
 ]

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)