spot-sdk-python 1.0.0__py3-none-any.whl

spot_sdk/__init__.py

@@ -0,0 +1,86 @@
+"""SPOT API interfaces and data models."""
+
+from .analysis_context import AnalysisContextReader
+from .analyzer import AnalyzerCapability, AnalyzerInterface, ThreatLevel
+from .config import ConfigOption, ConfigReloadResult, ConfigStatus, ConfigUpdateRequest
+from .config_helpers import merge_settings
+from .email import Attachment, Email, EmailHeader
+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 .settings_schema import register_settings_schema
+from .threat_levels import confidence_to_threat_level
+from .workflow import (
+    AnalyzerConfig,
+    FailureStrategy,
+    RetrievalLimits,
+    RetryConfig,
+    Workflow,
+    WorkflowStage,
+)
+
+__all__ = [
+    # Analyzer interface
+    "AnalyzerInterface",
+    "AnalyzerCapability",
+    "ThreatLevel",
+    # Config models
+    "ConfigOption",
+    "ConfigStatus",
+    "ConfigUpdateRequest",
+    "ConfigReloadResult",
+    # 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",
+    # 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/analysis_context.py

@@ -0,0 +1,99 @@
+"""Ergonomic accessor for Email.analysis_context.
+
+Wraps the stage-scoped dict produced by the orchestrator so analyzers can
+look up previous stage results without writing manual dict traversal.
+
+The underlying structure is:
+
+    {
+      "<stage-name>": {
+        "analyzers": {"<analyzer-id>": {...AnalyzerResult fields...}}
+      },
+      ...
+    }
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+class AnalysisContextReader:
+    """Read-only accessor for Email.analysis_context data.
+
+    Use via the Email.ctx property:
+
+        nlp = email.ctx.analyzer("analyzer-nlp")
+        if nlp:
+            confidence = nlp["confidence"]
+
+        # All analyzers in a specific stage
+        for aid, data in email.ctx.analyzers_in("parallel-analysis").items():
+            ...
+
+    Missing keys return None (single accessors) or empty dict (bulk accessors).
+    Nothing in this class raises.
+    """
+
+    def __init__(self, context: dict[str, Any] | None) -> None:
+        self._ctx: dict[str, Any] = context or {}
+
+    # ------------------------------------------------------------------
+    # Stage listing
+    # ------------------------------------------------------------------
+    def stages(self) -> list[str]:
+        """Return the names of all stages that have completed, in insertion order."""
+        return list(self._ctx.keys())
+
+    def has_stage(self, stage: str) -> bool:
+        """Return True if the given stage has completed."""
+        return stage in self._ctx
+
+    # ------------------------------------------------------------------
+    # Analyzer accessors
+    # ------------------------------------------------------------------
+    def analyzer_ids(self) -> list[str]:
+        """Return all analyzer IDs across all stages (deduplicated, stable order)."""
+        seen: dict[str, None] = {}
+        for stage in self._ctx.values():
+            for aid in (stage.get("analyzers") or {}).keys():
+                seen[aid] = None
+        return list(seen.keys())
+
+    def analyzer_ids_in(self, stage: str) -> list[str]:
+        """Return analyzer IDs in a specific stage. Empty list if stage is absent."""
+        return list((self._ctx.get(stage, {}).get("analyzers") or {}).keys())
+
+    def analyzer(
+        self, analyzer_id: str, stage: str | None = None
+    ) -> dict[str, Any] | None:
+        """Return a single analyzer result, or None if not found.
+
+        If ``stage`` is given, only look in that stage.
+        If ``stage`` is None, return the first match across all stages (in stage order).
+        """
+        if stage is not None:
+            hit = (self._ctx.get(stage, {}).get("analyzers") or {}).get(analyzer_id)
+            return cast("dict[str, Any] | None", hit)
+        for stage_data in self._ctx.values():
+            analyzers = stage_data.get("analyzers") or {}
+            if analyzer_id in analyzers:
+                return cast("dict[str, Any]", analyzers[analyzer_id])
+        return None
+
+    def analyzers_in(self, stage: str) -> dict[str, dict[str, Any]]:
+        """Return all analyzer results in a stage as {analyzer_id: data}.
+
+        Empty dict if the stage is absent or has no analyzers.
+        """
+        return dict(self._ctx.get(stage, {}).get("analyzers") or {})
+
+    def all_analyzers(self) -> dict[str, dict[str, dict[str, Any]]]:
+        """Return all analyzer results across every stage.
+
+        Shape: ``{stage_name: {analyzer_id: data, ...}, ...}``
+        """
+        return {
+            stage_name: dict(stage_data.get("analyzers") or {})
+            for stage_name, stage_data in self._ctx.items()
+        }

spot_sdk/analyzer.py

@@ -0,0 +1,106 @@
+"""Analyzer interface definition."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from .email import Email
+
+if TYPE_CHECKING:
+    from .results import AnalysisResult
+
+
+class ThreatLevel(str, Enum):
+    """Email threat level classification."""
+
+    SAFE = "safe"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class AnalyzerCapability(str, Enum):
+    """Analyzer capability types."""
+
+    SENTIMENT_ANALYSIS = "sentiment_analysis"
+    ENTITY_RECOGNITION = "entity_recognition"
+    URL_ANALYSIS = "url_analysis"
+    ATTACHMENT_SCANNING = "attachment_scanning"
+    LANGUAGE_DETECTION = "language_detection"
+    PHISHING_PATTERNS = "phishing_patterns"
+    SOCIAL_ENGINEERING = "social_engineering"
+    DOMAIN_REPUTATION = "domain_reputation"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class AnalyzerInterface(ABC):
+    """
+    Standard interface that all SPOT analyzers must implement.
+
+    This interface ensures compatibility across all analyzer plugins,
+    enabling the orchestrator to coordinate analysis workflows.
+    """
+
+    @abstractmethod
+    async def analyze(self, email: Email) -> AnalysisResult:
+        """
+        Analyze an email and return threat assessment.
+
+        Args:
+            email: Email object containing headers, body, and attachments
+
+        Returns:
+            AnalysisResult: Structured analysis result with threat assessment
+
+        Raises:
+            AnalysisError: If analysis cannot be completed
+        """
+        pass
+
+    @abstractmethod
+    async def get_capabilities(self) -> list[AnalyzerCapability]:
+        """
+        Return list of analysis capabilities this analyzer provides.
+
+        Returns:
+            List of AnalyzerCapability enums
+        """
+        pass
+
+    @abstractmethod
+    async def health_check(self) -> bool:
+        """
+        Check if analyzer is healthy and ready to process emails.
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_version(self) -> str:
+        """
+        Return analyzer version string.
+
+        Returns:
+            Semantic version string (e.g., "1.2.3")
+        """
+        pass
+
+    @abstractmethod
+    async def get_configuration(self) -> dict[str, Any]:
+        """
+        Return current analyzer configuration.
+
+        Returns:
+            Dictionary containing analyzer configuration parameters
+        """
+        pass

spot_sdk/analyzer_base.py

@@ -0,0 +1,316 @@
+"""Base classes for SPOT analyzer implementations.
+
+Provides:
+- BaseAnalyzerSettings: Common settings fields all analyzers share
+- settings_singleton: Decorator to add caching to a get_settings() function
+- merge_settings: Merge base settings with central config overrides
+- create_analyzer_app: Factory for FastAPI app with standard analyzer endpoints
+
+Usage in an analyzer's config.py::
+
+    from spot_sdk.analyzer_base import BaseAnalyzerSettings, settings_singleton
+
+    class Settings(BaseAnalyzerSettings):
+        app_name: str = "analyzer-nlp"
+        model_path: str = "/models/distilbert"
+        use_gpu: bool = False
+
+    @settings_singleton
+    def get_settings() -> Settings:
+        return Settings()
+
+Usage in an analyzer's main.py::
+
+    from spot_sdk.analyzer_base import create_analyzer_app
+
+    app, state = create_analyzer_app(
+        title="SPOT NLP Analyzer",
+        description="NLP-based phishing email analyzer",
+        analyzer_id="analyzer-nlp",
+        settings_factory=get_settings,
+    )
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Awaitable, Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+import uvicorn
+from fastapi import FastAPI
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.responses import Response
+
+from .config_client import ConfigClient
+from .logging import configure_logging, get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T", bound=BaseSettings)
+
+
+class BaseAnalyzerSettings(BaseSettings):
+    """Common settings shared by all SPOT analyzers.
+
+    Analyzers extend this class with their own specific fields::
+
+        class Settings(BaseAnalyzerSettings):
+            app_name: str = "analyzer-nlp"
+            model_path: str = "/models/distilbert"
+            use_gpu: bool = False
+
+    Fields:
+        app_name: Human-readable analyzer name
+        app_version: Semantic version string
+        debug: Enable debug mode (hot reload, verbose logging)
+        log_level: Python log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        host: Server bind address
+        port: Server bind port
+        platform_url: URL of the SPOT API gateway for config fetching
+    """
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    app_name: str = "spot-analyzer"
+    app_version: str = "1.0.0"
+    debug: bool = False
+    log_level: str = "INFO"
+
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8000
+
+    # Platform URL for ConfigClient
+    platform_url: str = "http://api-gateway:8000"
+
+
+def settings_singleton(func: Callable[[], T]) -> Callable[[], T]:
+    """Decorator that turns a settings factory into a cached singleton.
+
+    Usage::
+
+        @settings_singleton
+        def get_settings() -> Settings:
+            return Settings()
+
+        # First call creates the instance, subsequent calls return cached value
+        settings = get_settings()
+
+    The cache can be cleared by setting the internal list element to None::
+
+        get_settings._instance[0] = None
+    """
+    instance: list[T | None] = [None]
+
+    @wraps(func)
+    def wrapper() -> T:
+        if instance[0] is None:
+            instance[0] = func()
+        result = instance[0]
+        assert result is not None
+        return result
+
+    # Allow cache clearing for testing
+    wrapper._instance = instance  # type: ignore[attr-defined]
+    return wrapper
+
+
+def merge_settings(base: T, overrides: dict[str, Any]) -> T:
+    """Merge base settings with central config overrides.
+
+    Only applies overrides for fields that actually exist in the Settings model.
+    Returns a new Settings instance (the original is not mutated).
+
+    Args:
+        base: Base Settings instance from local env/defaults
+        overrides: Dict of override values from central config
+
+    Returns:
+        New Settings instance with overrides applied.
+    """
+    valid_keys = set(type(base).model_fields.keys())
+    filtered = {k: v for k, v in overrides.items() if k in valid_keys}
+    return base.model_copy(update=filtered)
+
+
+class AnalyzerState:
+    """Shared mutable state for an analyzer application.
+
+    Holds the settings, config client, and analysis service references
+    that are initialized during the lifespan and used by endpoints.
+
+    Attributes:
+        settings: Current merged settings (None before startup)
+        config_client: ConfigClient for central config fetching
+        analysis_service: The analyzer's AnalysisService instance (None before startup)
+        settings_factory: Callable that returns a fresh Settings instance
+        on_reload: Optional async callback invoked after config reload
+    """
+
+    def __init__(
+        self,
+        config_client: ConfigClient,
+        settings_factory: Callable[[], BaseAnalyzerSettings],
+    ) -> None:
+        self.settings: BaseAnalyzerSettings | None = None
+        self.config_client = config_client
+        self.analysis_service: Any = None
+        self.settings_factory = settings_factory
+        self.on_reload: Callable[[], Awaitable[None]] | None = None
+
+    def apply_settings(self) -> BaseAnalyzerSettings:
+        """Load base settings, merge with central overrides, configure logging.
+
+        Updates ``self.settings`` with the merged result and configures
+        the logging level. Does NOT touch ``self.analysis_service`` --
+        that is the caller's responsibility.
+
+        Returns:
+            Merged settings instance.
+        """
+        base = self.settings_factory()
+        overrides = self.config_client.config
+        self.settings = merge_settings(base, overrides)
+        configure_logging(log_level=self.settings.log_level)
+        return self.settings
+
+
+def create_analyzer_app(
+    *,
+    title: str,
+    description: str,
+    analyzer_id: str,
+    settings_factory: Callable[[], BaseAnalyzerSettings],
+    platform_url: str | None = None,
+    lifespan: Any | None = None,
+) -> tuple[FastAPI, AnalyzerState]:
+    """Create a FastAPI app with standard analyzer endpoints.
+
+    Returns the app and a state object. The caller is responsible for:
+
+    1. Adding a lifespan or startup handler that calls
+       ``state.config_client.fetch_config()``, ``state.apply_settings()``,
+       and sets ``state.analysis_service``.
+    2. Adding a ``/health`` endpoint (health checks are analyzer-specific).
+    3. Adding a ``/internal/analyze`` endpoint (pre-checks are analyzer-specific).
+    4. Optionally setting ``state.on_reload`` for post-reload logic.
+
+    Standard endpoints provided:
+
+    - GET  /capabilities        -- delegates to analysis_service.get_capabilities()
+    - GET  /config              -- delegates to analysis_service.get_configuration()
+    - POST /admin/reload-config -- reloads central config, calls state.on_reload if set
+
+    Args:
+        title: FastAPI app title
+        description: FastAPI app description
+        analyzer_id: Unique analyzer identifier for config client
+        settings_factory: Callable returning a Settings instance
+        platform_url: Override platform URL (default: from settings or env)
+        lifespan: Optional lifespan async context manager for the app
+
+    Returns:
+        Tuple of (FastAPI app, AnalyzerState).
+    """
+    initial_settings = settings_factory()
+
+    # Determine platform URL
+    if platform_url is None:
+        _platform_url = getattr(
+            initial_settings,
+            "platform_url",
+            os.getenv("SPOT_PLATFORM_URL", "http://api-gateway:8000"),
+        )
+    else:
+        _platform_url = platform_url
+
+    default_version = initial_settings.app_version
+
+    config_client = ConfigClient(
+        analyzer_id=analyzer_id,
+        platform_url=_platform_url,
+    )
+
+    state = AnalyzerState(
+        config_client=config_client,
+        settings_factory=settings_factory,
+    )
+
+    app_kwargs: dict[str, Any] = {
+        "title": title,
+        "description": description,
+        "version": default_version,
+    }
+    if lifespan is not None:
+        app_kwargs["lifespan"] = lifespan
+
+    app = FastAPI(**app_kwargs)
+
+    # --- Standard endpoints ---
+
+    @app.get("/capabilities")
+    async def get_capabilities() -> list[str]:
+        """Get analyzer capabilities."""
+        if state.analysis_service is None:
+            return []
+        capabilities = await state.analysis_service.get_capabilities()
+        return [cap.value for cap in capabilities]
+
+    @app.get("/config")
+    async def get_configuration() -> dict[str, Any]:
+        """Get analyzer configuration."""
+        if state.analysis_service is None:
+            return {}
+        config: dict[str, Any] = await state.analysis_service.get_configuration()
+        return config
+
+    @app.post("/admin/reload-config", status_code=204, response_class=Response)
+    async def reload_config() -> Response:
+        """Reload configuration from central platform.
+
+        Called by spot-cli config reload when analyzer config changes.
+        Fetches fresh central overrides, re-applies settings, and
+        invokes the on_reload callback if one is registered.
+        """
+        logger.info("Reloading configuration...")
+
+        # Fetch fresh central overrides
+        await config_client.reload()
+
+        # Apply settings
+        state.apply_settings()
+
+        # Invoke analyzer-specific post-reload logic
+        if state.on_reload is not None:
+            await state.on_reload()
+
+        logger.info(
+            "Configuration reloaded (version: %s)",
+            config_client.version or "local-only",
+        )
+        return Response(status_code=204)
+
+    return app, state
+
+
+def run_analyzer(app_import_path: str, settings: BaseAnalyzerSettings) -> None:
+    """Run an analyzer with uvicorn using standard settings.
+
+    Intended for use in ``if __name__ == "__main__":`` blocks::
+
+        if __name__ == "__main__":
+            run_analyzer("src.main:app", get_settings())
+
+    Args:
+        app_import_path: Dotted import path to the app (e.g. "src.main:app")
+        settings: Settings instance for host/port/log_level/debug
+    """
+    uvicorn.run(
+        app_import_path,
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+        reload=settings.debug,
+    )