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

spot_sdk/api_gateway.py

@@ -0,0 +1,271 @@
+# generated by datamodel-codegen:
+#   filename:  api-gateway.yaml
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+from pydantic import AwareDatetime, BaseModel, EmailStr, Field, SecretStr, constr
+
+
+class Features(BaseModel):
+    configuration_api: bool | None = None
+    database_config: bool | None = None
+    oauth: bool | None = None
+    rate_limiting: bool | None = None
+    audit_logging: bool | None = None
+
+
+class HealthStatus(BaseModel):
+    status: str | None = Field(None, examples=['healthy'])
+    service: str | None = Field(None, examples=['api-gateway'])
+    version: str | None = None
+    features: Features | None = None
+
+
+class Token(BaseModel):
+    access_token: str
+    refresh_token: str
+    token_type: str = Field(..., examples=['bearer'])
+    expires_in: int
+
+
+class RefreshRequest(BaseModel):
+    refresh_token: str
+    """
+    Valid refresh token
+    """
+
+
+class UserRole(StrEnum):
+    admin = 'admin'
+    analyst = 'analyst'
+    viewer = 'viewer'
+
+
+class UserCreate(BaseModel):
+    username: constr(min_length=3, max_length=50)
+    email: EmailStr
+    password: SecretStr
+    role: UserRole | None = 'analyst'
+
+
+class UserUpdate(BaseModel):
+    username: constr(min_length=3, max_length=50) | None = None
+    email: EmailStr | None = None
+
+
+class UserRoleUpdate(BaseModel):
+    role: UserRole
+
+
+class UserPasswordUpdate(BaseModel):
+    current_password: str | None = None
+    new_password: constr(min_length=8)
+
+
+class UserProfile(BaseModel):
+    id: str | None = None
+    username: str | None = None
+    email: str | None = None
+    role: UserRole | None = None
+    is_active: bool | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class UserListResponse(BaseModel):
+    users: list[UserProfile]
+    total: int
+    limit: int
+    offset: int
+
+
+class MessageResponse(BaseModel):
+    message: str | None = None
+
+
+class AnalyzerConfigResponse(BaseModel):
+    analyzer_id: str | None = None
+    enabled: bool | None = None
+    settings: dict[str, Any] | None = None
+    config_version: str | None = None
+
+
+class WorkflowsConfigResponse(BaseModel):
+    workflows: list[dict[str, Any]] | None = None
+    config_version: str | None = None
+
+
+class ConfigReloadResponse(BaseModel):
+    old_version: str | None = None
+    new_version: str | None = None
+    changed: dict[str, Any] | None = None
+
+
+class PluginInfo(BaseModel):
+    name: str | None = None
+    type: str | None = None
+    version: str | None = None
+    enabled: bool | None = None
+    created_at: AwareDatetime | None = None
+
+
+class PluginListResponse(BaseModel):
+    plugins: list[PluginInfo] | None = None
+    total: int | None = None
+
+
+class Type(StrEnum):
+    oci = 'oci'
+    git = 'git'
+    bundle = 'bundle'
+
+
+class Source(BaseModel):
+    type: Type
+    ref: str | None = None
+
+
+class PluginRequireRequest(BaseModel):
+    source: Source
+    dry_run: bool | None = False
+
+
+class AnalysisRequest(BaseModel):
+    email: dict[str, Any]
+    analyzers: list[str] | None = None
+    priority: str | None = 'normal'
+    workflow_id: str | None = None
+
+
+class AnalysisResponse(BaseModel):
+    job_id: str | None = None
+    email_id: str | None = None
+    status: str | None = None
+    workflow: str | None = None
+    message: str | None = None
+
+
+class EmailAnalysisStatus(BaseModel):
+    job_id: str | None = None
+    email_id: str | None = None
+    workflow_id: str | None = None
+    """
+    ID of the workflow used for analysis
+    """
+    status: str | None = None
+    created_at: AwareDatetime | None = None
+    started_at: AwareDatetime | None = None
+    completed_at: AwareDatetime | None = None
+    result: dict[str, Any] | None = None
+    error: str | None = None
+
+
+class AnalysisStatsResponse(BaseModel):
+    total: int | None = None
+    """
+    Total number of analysis jobs
+    """
+    by_status: dict[str, int] | None = None
+    """
+    Count of jobs by status
+    """
+    by_threat_level: dict[str, int] | None = None
+    """
+    Count of completed jobs by threat level
+    """
+    phishing_count: int | None = None
+    """
+    Number of emails classified as phishing
+    """
+    legitimate_count: int | None = None
+    """
+    Number of emails classified as legitimate
+    """
+    avg_confidence: float | None = None
+    """
+    Average confidence score (0.0-1.0)
+    """
+
+
+class EmailResponse(BaseModel):
+    id: str
+    original_id: str | None = None
+    subject: str | None = None
+    body_text: str | None = None
+    body_html: str | None = None
+    headers: dict[str, Any] | None = None
+    attachments: list[dict[str, Any]] | None = None
+    language: str | None = None
+    source: str | None = None
+    received_at: str | None = None
+    created_at: str | None = None
+    analyzed_at: str | None = None
+    expires_at: str | None = None
+
+
+class EmailListResponse(BaseModel):
+    emails: list[dict[str, Any]]
+    total: int
+    limit: int
+    offset: int
+
+
+class EmailDeleteResponse(BaseModel):
+    deleted: bool
+    message: str
+
+
+class EmailSourcesResponse(BaseModel):
+    sources: list[str]
+
+
+class WorkflowSummary(BaseModel):
+    id: str | None = None
+    name: str | None = None
+    version: int | None = None
+    description: str | None = None
+    stages: int | None = None
+    final_stage: str | None = None
+
+
+class WorkflowTestRequest(BaseModel):
+    email: dict[str, Any]
+    wait_for_completion: bool | None = True
+
+
+class RetrieverInfo(BaseModel):
+    id: str | None = None
+    url: str | None = None
+    priority: int | None = None
+    enabled: bool | None = None
+    capabilities: list[str] | None = None
+    status: str | None = None
+    last_check: str | None = None
+
+
+class Source1(BaseModel):
+    id: str
+    type: str
+    config: dict[str, Any]
+    enabled: bool | None = True
+    fetch_interval: int | None = 300
+
+
+class FetchRequest(BaseModel):
+    source: Source1
+    priority: str | None = 'normal'
+
+
+class FetchJobStatus(BaseModel):
+    job_id: str | None = None
+    source_id: str | None = None
+    retriever_id: str | None = None
+    status: str | None = None
+    created_at: str | None = None
+    started_at: str | None = None
+    completed_at: str | None = None
+    emails_fetched: int | None = 0
+    error: str | None = None

spot_sdk/config.py

@@ -0,0 +1,46 @@
+"""Configuration management models for SPOT platform."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ConfigOption(BaseModel):
+    """Single configuration option with full metadata."""
+
+    path: str = Field(description="Dot-notation path (e.g., 'platform.log_level')")
+    value: Any = Field(description="Current value")
+    default: Any = Field(description="Default value from schema")
+    type: str = Field(description="JSON Schema type (string, boolean, integer, etc.)")
+    description: str = Field(default="", description="Human-readable description")
+    is_default: bool = Field(description="True if current value equals default")
+    enum: list[str] | None = Field(
+        default=None, description="Allowed values if restricted"
+    )
+    minimum: float | None = Field(default=None, description="Minimum value for numbers")
+    maximum: float | None = Field(default=None, description="Maximum value for numbers")
+
+
+class ConfigStatus(BaseModel):
+    """Configuration synchronization status."""
+
+    applied_hash: str = Field(description="Hash of last-applied configuration")
+    pending_hash: str = Field(description="Hash of current in-memory configuration")
+    needs_reload: bool = Field(description="True if pending differs from applied")
+    pending_changes: int = Field(
+        default=0, description="Number of options changed since last reload"
+    )
+
+
+class ConfigUpdateRequest(BaseModel):
+    """Request to update a single configuration option."""
+
+    value: Any = Field(description="New value for the option")
+
+
+class ConfigReloadResult(BaseModel):
+    """Result of a configuration reload operation."""
+
+    status: ConfigStatus = Field(description="Updated configuration status")
+    reloaded: bool = Field(description="True if reload was performed")
+    message: str = Field(default="", description="Optional status message")

spot_sdk/config_client.py

@@ -0,0 +1,203 @@
+"""Configuration client for SPOT analyzers.
+
+Provides:
+- Remote config fetching from core platform
+- Graceful handling of network errors (preserves last known good config)
+- Simple interface for getting config values
+
+Error handling:
+- On 404: Reset config (no central config, use local defaults)
+- On network/timeout errors: Keep last known good config unchanged
+
+Usage in analyzer main.py:
+    from spot_sdk.config_client import ConfigClient
+
+    config_client = ConfigClient(
+        analyzer_id="spot-analyzer-nlp",
+        platform_url="http://api-gateway:8000",
+    )
+
+    # Fetch config on startup
+    await config_client.fetch_config()
+
+    # Get config values (with fallback to defaults)
+    threshold = config_client.get("confidence_threshold", 0.7)
+
+    # Reload config (called from /admin/reload-config endpoint)
+    await config_client.reload()
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ConfigClient:
+    """Client for fetching configuration from SPOT platform.
+
+    Analyzers use this to fetch their centralized configuration overrides
+    from the api-gateway's /api/v1/config/analyzer/{id} endpoint.
+
+    The config is stored internally and can be accessed via get() method.
+    On network errors, the last known good config is preserved.
+    On 404, config is reset (meaning no central config exists).
+    """
+
+    def __init__(
+        self,
+        analyzer_id: str,
+        platform_url: str = "http://api-gateway:8000",
+        timeout: float = 10.0,
+    ) -> None:
+        """Initialize ConfigClient.
+
+        Args:
+            analyzer_id: The analyzer identifier (e.g., "spot-analyzer-nlp")
+            platform_url: Base URL of the api-gateway (default: http://api-gateway:8000)
+            timeout: HTTP request timeout in seconds (default: 10.0)
+        """
+        self.analyzer_id = analyzer_id
+        self.platform_url = platform_url.rstrip("/")
+        self.timeout = timeout
+
+        # Internal state
+        self._config: dict[str, Any] = {}
+        self._version: str | None = None
+        self._enabled: bool = True
+
+    @property
+    def config(self) -> dict[str, Any]:
+        """Get the current configuration dict."""
+        return self._config
+
+    @property
+    def version(self) -> str | None:
+        """Get the current config version (None if never fetched successfully)."""
+        return self._version
+
+    @property
+    def enabled(self) -> bool:
+        """Check if analyzer is enabled in central config."""
+        return self._enabled
+
+    async def fetch_config(self) -> dict[str, Any]:
+        """Fetch configuration from platform.
+
+        Makes HTTP GET request to /api/v1/config/analyzer/{analyzer_id}.
+
+        On success: Updates internal state with new settings.
+        On 404: Resets config to empty (no central config, use local defaults).
+        On network error: Keeps last known good config unchanged.
+
+        Returns:
+            Dict of configuration settings (may be unchanged on network error).
+        """
+        url = f"{self.platform_url}/api/v1/config/analyzer/{self.analyzer_id}"
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                response = await client.get(url)
+
+                if response.status_code == 404:
+                    # No central config for this analyzer - reset to empty
+                    logger.info(
+                        "No central config for %s, using local defaults",
+                        self.analyzer_id,
+                    )
+                    self._config = {}
+                    self._version = None
+                    self._enabled = True
+                    return self._config
+
+                response.raise_for_status()
+                data = response.json()
+
+                # Update state only on successful response
+                self._config = data.get("settings", {})
+                self._version = data.get("config_version")
+                self._enabled = data.get("enabled", True)
+
+                logger.info(
+                    "Fetched config for %s (version=%s, enabled=%s, keys=%s)",
+                    self.analyzer_id,
+                    self._version,
+                    self._enabled,
+                    list(self._config.keys()),
+                )
+
+                return self._config
+
+        except httpx.ConnectError as e:
+            # Network error - keep last known good config
+            logger.warning(
+                "Cannot connect to platform at %s: %s. Keeping current config.",
+                self.platform_url,
+                e,
+            )
+            return self._config
+
+        except httpx.TimeoutException:
+            # Timeout - keep last known good config
+            logger.warning(
+                "Timeout fetching config from %s. Keeping current config.",
+                url,
+            )
+            return self._config
+
+        except httpx.HTTPStatusError as e:
+            # HTTP error (not 404) - keep last known good config
+            logger.warning(
+                "HTTP error fetching config for %s: %s. Keeping current config.",
+                self.analyzer_id,
+                e,
+            )
+            return self._config
+
+        except Exception as e:
+            # Unexpected error - keep last known good config
+            logger.warning(
+                "Unexpected error fetching config for %s: %s. Keeping current config.",
+                self.analyzer_id,
+                e,
+            )
+            return self._config
+
+    async def reload(self) -> dict[str, Any]:
+        """Reload configuration from platform.
+
+        Alias for fetch_config(), called when analyzer receives reload signal.
+
+        Returns:
+            Dict of configuration settings.
+        """
+        logger.info("Reloading config for %s", self.analyzer_id)
+        return await self.fetch_config()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a configuration value.
+
+        Args:
+            key: Configuration key name
+            default: Default value if key not found
+
+        Returns:
+            Configuration value or default.
+        """
+        return self._config.get(key, default)
+
+    def has(self, key: str) -> bool:
+        """Check if a configuration key exists.
+
+        Args:
+            key: Configuration key name
+
+        Returns:
+            True if key exists in config.
+        """
+        return key in self._config

spot_sdk/config_helpers.py

@@ -0,0 +1,25 @@
+"""Shared configuration helpers for SPOT analyzers."""
+
+from typing import Any, TypeVar
+
+from pydantic_settings import BaseSettings
+
+T = TypeVar("T", bound=BaseSettings)
+
+
+def merge_settings(settings_class: type[T], base: T, overrides: dict[str, Any]) -> T:
+    """Merge base settings with central overrides.
+
+    Only applies overrides for fields that exist in the Settings model.
+
+    Args:
+        settings_class: The Pydantic Settings class (used for field discovery).
+        base: Base Settings instance from local env/defaults.
+        overrides: Override values from central config.
+
+    Returns:
+        New Settings instance with overrides applied.
+    """
+    valid_keys = set(settings_class.model_fields.keys())
+    filtered = {k: v for k, v in overrides.items() if k in valid_keys}
+    return base.model_copy(update=filtered)

spot_sdk/email.py

@@ -0,0 +1,136 @@
+"""Email data models."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, EmailStr, Field, field_validator, model_validator
+
+if TYPE_CHECKING:
+    from .analysis_context import AnalysisContextReader
+
+
+class EmailHeader(BaseModel):
+    """Email header fields."""
+
+    message_id: str
+    subject: str
+    sender: EmailStr
+    recipients: list[EmailStr] = Field(..., min_length=1)
+    cc: list[EmailStr] = Field(default_factory=list)
+    bcc: list[EmailStr] = Field(default_factory=list)
+    date: datetime
+    reply_to: EmailStr | None = None
+    return_path: EmailStr | None = None
+
+    # Raw headers for advanced analysis
+    raw_headers: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("recipients", "cc", "bcc", mode="before")
+    @classmethod
+    def ensure_list(cls, v: Any) -> list[str]:
+        if isinstance(v, str):
+            return [v]
+        return v or []
+
+
+class Attachment(BaseModel):
+    """Email attachment."""
+
+    filename: str
+    content_type: str
+    size_bytes: int
+    content_hash: str  # SHA256 hash
+    is_inline: bool = False
+
+    # Optional: actual content for analysis (base64 encoded)
+    content: str | None = None
+
+    @field_validator("content_hash")
+    @classmethod
+    def validate_hash(cls, v: str) -> str:
+        if len(v) != 64:  # SHA256 is 64 hex chars
+            raise ValueError("content_hash must be a valid SHA256 hash")
+        return v
+
+
+class Email(BaseModel):
+    """
+    Complete email representation for analysis.
+
+    This model contains all email data needed for phishing detection
+    while maintaining GDPR compliance through optional anonymization.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    headers: EmailHeader
+    body_text: str | None = None
+    body_html: str | None = None
+    attachments: list[Attachment] = Field(default_factory=list)
+
+    # Metadata
+    received_at: datetime = Field(default_factory=datetime.utcnow)
+    language: str | None = None  # ISO 639-1 language code
+    source: str = "unknown"  # imap, smtp, api, etc.
+
+    # Analysis context
+    organization_context: dict[str, str] = Field(default_factory=dict)
+
+    # Context from previously-executed workflow stages, populated by the orchestrator.
+    #
+    # Structure:
+    #   {
+    #     "<stage-name>": {
+    #       "providers": {"<provider-id>": {...data...}},
+    #       "analyzers": {"<analyzer-id>": {...AnalyzerResult fields...}}
+    #     },
+    #     ...
+    #   }
+    #
+    # Only stages that have already completed are included. Empty dict by default.
+    analysis_context: dict[str, Any] = Field(default_factory=dict)
+
+    # Operator policy for Knowledge Store retrieval inside the current stage.
+    # Populated by the orchestrator from WorkflowStage.retrieval_limits and
+    # consumed transparently by KnowledgeClient.for_analysis(email). Empty
+    # dict means "no caps" (use analyzer-supplied parameters as-is).
+    retrieval_limits: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def ensure_content(self) -> "Email":
+        """Ensure at least one body format is provided."""
+        if not self.body_text and not self.body_html:
+            raise ValueError("Email must have either body_text or body_html")
+        return self
+
+    @property
+    def content(self) -> str:
+        """Get email content, preferring text over HTML."""
+        return self.body_text or self.body_html or ""
+
+    @property
+    def has_attachments(self) -> bool:
+        """Check if email has attachments."""
+        return len(self.attachments) > 0
+
+    @property
+    def ctx(self) -> "AnalysisContextReader":
+        """Ergonomic accessor for analysis_context from previous stages.
+
+        Example:
+            nlp = email.ctx.analyzer("analyzer-nlp")
+            if nlp:
+                confidence = nlp["confidence"]
+        """
+        # Imported lazily to avoid a circular reference at module import time
+        from .analysis_context import AnalysisContextReader
+
+        return AnalysisContextReader(self.analysis_context)
+
+    def get_urls(self) -> list[str]:
+        """Extract URLs from email content (to be implemented in analyzer)."""
+        # This would be implemented in the actual analyzer
+        # Placeholder for interface definition
+        return []

spot_sdk/errors.py

@@ -0,0 +1,24 @@
+"""Standard error response models for SPOT API."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response for all SPOT API endpoints.
+
+    Provides a consistent error format across the platform:
+    - ``error``: machine-readable error code (e.g. "not_found", "validation_error")
+    - ``message``: human-readable explanation
+    - ``details``: optional structured context (validation errors, field info, etc.)
+    """
+
+    error: str = Field(..., description="Machine-readable error code")
+    message: str = Field(..., description="Human-readable error message")
+    details: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Optional structured details about the error",
+    )