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

spot_sdk/workflow.py

@@ -0,0 +1,139 @@
+"""Workflow configuration models for SPOT platform."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class FailureStrategy(str, Enum):
+    """Strategy for handling analyzer failures."""
+
+    RETRY = "retry"
+    SKIP = "skip"
+    FAIL = "fail"
+    FALLBACK = "fallback"
+
+
+class RetryConfig(BaseModel):
+    """Retry configuration for analyzer execution."""
+
+    max_attempts: int = Field(
+        default=3, ge=1, le=10, description="Maximum number of retry attempts"
+    )
+    backoff_ms: int = Field(
+        default=1000,
+        ge=100,
+        le=60000,
+        description="Initial backoff time in milliseconds",
+    )
+    max_backoff_ms: int = Field(
+        default=10000,
+        ge=1000,
+        le=300000,
+        description="Maximum backoff time in milliseconds",
+    )
+    exponential_backoff: bool = Field(
+        default=True, description="Use exponential backoff"
+    )
+
+
+class AnalyzerConfig(BaseModel):
+    """Configuration for a single analyzer in a workflow stage."""
+
+    id: str = Field(..., description="Analyzer ID")
+    weight: float = Field(
+        default=1.0, ge=0.0, le=10.0, description="Weight for result aggregation"
+    )
+    timeout_ms: int = Field(
+        default=30000, ge=1000, le=300000, description="Timeout in milliseconds"
+    )
+    required: bool = Field(
+        default=False, description="Whether this analyzer is required"
+    )
+    failure_strategy: FailureStrategy = Field(
+        default=FailureStrategy.RETRY, description="Failure handling strategy"
+    )
+    retry_config: RetryConfig = Field(
+        default_factory=RetryConfig, description="Retry configuration"
+    )
+    condition: str | None = Field(None, description="Conditional execution expression")
+
+
+class RetrievalLimits(BaseModel):
+    """Operator policy for Knowledge Store retrieval inside a stage.
+
+    Caps only — these shrink what an analyzer asks for, never expand it.
+    The orchestrator passes this on the per-analysis request payload;
+    ``KnowledgeClient.for_analysis(email)`` enforces them transparently.
+    """
+
+    max_top_k: int | None = Field(
+        default=None,
+        ge=1,
+        le=1000,
+        description="Cap on top_k requested by any analyzer in this stage",
+    )
+    min_score_floor: float | None = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description="Raise the min_score floor even if analyzer asked for less",
+    )
+
+
+class WorkflowStage(BaseModel):
+    """A stage in a workflow with multiple analyzers."""
+
+    name: str = Field(..., description="Stage name")
+    type: str = Field(
+        default="sequential",
+        description="Stage type (parallel, sequential, conditional)",
+    )
+    analyzers: list[AnalyzerConfig] = Field(
+        default_factory=list, description="List of analyzers in this stage"
+    )
+    retrieval_limits: RetrievalLimits | None = Field(
+        default=None,
+        description="Operator-policy caps on knowledge-store retrieval for this stage",
+    )
+    depends_on: list[str] = Field(
+        default_factory=list, description="Names of stages this depends on"
+    )
+    continue_on_failure: bool = Field(
+        default=True, description="Continue if some analyzers fail"
+    )
+    min_successful_analyzers: int = Field(
+        default=1, ge=0, description="Minimum successful analyzers required"
+    )
+    aggregation_method: str = Field(
+        default="weighted_average", description="Method for aggregating results"
+    )
+    condition: str | None = Field(None, description="Conditional execution expression")
+
+
+class Workflow(BaseModel):
+    """Complete workflow configuration for email analysis."""
+
+    id: str = Field(..., description="Workflow ID")
+    name: str = Field(..., description="Workflow name")
+    version: int = Field(default=1, ge=1, description="Workflow version")
+    description: str = Field(default="", description="Workflow description")
+    stages: list[WorkflowStage] = Field(
+        default_factory=list, description="List of workflow stages"
+    )
+    final_stage_name: str = Field(
+        default="",
+        description="Name of the final decision stage. Empty means aggregate all results.",
+    )
+    timeout_ms: int = Field(
+        default=300000,
+        ge=1000,
+        le=600000,
+        description="Total workflow timeout in milliseconds",
+    )
+    max_parallel_analyzers: int = Field(
+        default=10, ge=1, le=100, description="Maximum parallel analyzer executions"
+    )
+    created_by: str = Field(default="system", description="Creator of the workflow")

spot_sdk_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,353 @@
+Metadata-Version: 2.4
+Name: spot-sdk-python
+Version: 1.0.0
+Summary: Python SDK for SPOT platform - API contracts, models, and utilities
+License: Apache-2.0
+Author: SPOT Project
+Author-email: spot@sonn.lu
+Requires-Python: >=3.11,<4.0
+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
+Requires-Dist: httpx (>=0.25.0,<0.26.0)
+Requires-Dist: pydantic-settings (>=2.0.0,<3.0.0)
+Requires-Dist: pydantic[email] (>=2.0.0,<3.0.0)
+Requires-Dist: typing-extensions (>=4.8.0,<5.0.0)
+Project-URL: Homepage, https://sonn.lu
+Description-Content-Type: text/markdown
+
+# SPOT Contracts Python SDK
+
+Python SDK generated from SPOT Platform OpenAPI specifications.
+
+## Installation
+
+```bash
+pip install spot-sdk-python
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from spot_sdk.analyzer import Email, EmailHeader, AnalysisResult
+from spot_sdk.api_gateway import AnalysisRequest
+
+# Create email header
+header = EmailHeader(
+    message_id="msg-001",
+    subject="Test Email",
+    sender="sender@example.com", 
+    recipients=["recipient@example.com"],
+    date="2024-01-01T12:00:00Z"
+)
+
+# Create email object
+email = Email(
+    id="12345",
+    headers=header,
+    body_text="This is the email content"
+)
+
+# Use with API Gateway
+request = AnalysisRequest(email=email.dict())
+```
+
+### Pydantic Models
+
+All models are Pydantic v2 BaseModel instances with:
+
+- **Type validation** - Automatic validation of field types
+- **Serialization** - `.dict()` and `.json()` methods
+- **Field descriptions** - Documentation from OpenAPI specs
+- **IDE support** - Full type hints and autocompletion
+
+### Example: Email Analysis
+
+```python
+import httpx
+from spot_sdk.analyzer import Email
+from spot_sdk.api_gateway import AnalysisRequest
+
+async def analyze_email(email: Email) -> dict:
+    async with httpx.AsyncClient() as client:
+        request = AnalysisRequest(email=email.dict())
+        response = await client.post(
+            "http://localhost:8001/api/v1/analyze",
+            json=request.dict()
+        )
+        return response.json()
+
+# Usage
+email = Email(
+    id="sample-123",
+    headers={
+        "message_id": "msg-sample",
+        "subject": "Urgent: Action Required",
+        "sender": "suspicious@example.com",
+        "recipients": ["target@company.com"],
+        "date": "2024-01-15T10:30:00Z"
+    },
+    body_text="Please click this link immediately..."
+)
+
+result = await analyze_email(email)
+print(f"Phishing detected: {result['is_phishing']}")
+```
+
+### Accessing Previous Stage Results (`analysis_context`)
+
+The orchestrator automatically populates `Email.analysis_context` with the results of all previously-completed stages before calling each analyzer. No workflow configuration is required -- analyzers can read whatever they need.
+
+**Structure:**
+
+```python
+email.analysis_context = {
+    "<stage-name>": {
+        "providers": {
+            "<provider-id>": { ...free-form data... }
+        },
+        "analyzers": {
+            "<analyzer-id>": { ...AnalyzerResult fields... }
+        }
+    },
+    ...
+}
+```
+
+- Top-level keys are stage names
+- Each stage has a `providers` dict (populated by Context Providers) and an `analyzers` dict
+- Analyzer values expose all `AnalyzerResult` fields (`is_phishing`, `confidence`, `threat_level`, `indicators`, `analyzer_details`, ...)
+- Only stages that have completed before the current analyzer runs are present
+
+**Recommended: use the `email.ctx` helper**
+
+The SDK provides an `AnalysisContextReader` (via the `Email.ctx` property) with ergonomic accessors so you don't have to write manual dict traversal:
+
+```python
+@app.post("/internal/analyze")
+async def analyze_email(email: Email) -> AnalysisResult:
+    ctx = email.ctx  # AnalysisContextReader
+
+    # Get a specific analyzer from any stage (first match)
+    nlp = ctx.analyzer("analyzer-nlp")
+    if nlp:
+        confidence = nlp["confidence"]
+
+    # Get a specific analyzer from a specific stage
+    ml = ctx.analyzer("analyzer-ml", stage="parallel-analysis")
+
+    # Get a provider's data
+    dept = ctx.provider("employee-dir")
+    if dept:
+        role = dept.get("role")
+
+    # Iterate all analyzers in a stage
+    for aid, result in ctx.analyzers_in("parallel-analysis").items():
+        print(aid, result["confidence"])
+
+    # Listing helpers
+    ctx.stages()                                # ['enrichment', 'parallel-analysis']
+    ctx.analyzer_ids()                          # ['analyzer-nlp', 'analyzer-ml']
+    ctx.provider_ids()                          # ['employee-dir', 'threat-feed']
+    ctx.analyzer_ids_in("parallel-analysis")    # stage-scoped
+    ctx.provider_ids_in("enrichment")
+    ctx.has_stage("parallel-analysis")          # True/False
+
+    # Bulk accessors: {stage: {id: data, ...}, ...}
+    ctx.all_analyzers()
+    ctx.all_providers()
+    ...
+```
+
+All single accessors (`analyzer()`, `provider()`) return `None` when not found. Bulk accessors return empty dicts. Nothing raises -- missing stages or IDs are treated as normal.
+
+**Raw access (if you prefer)**
+
+You can also read `email.analysis_context` directly as a plain dict:
+
+```python
+prev = email.analysis_context.get("parallel-analysis", {})
+nlp = prev.get("analyzers", {}).get("analyzer-nlp")
+```
+
+Analyzers that don't need previous results can safely ignore this field -- it defaults to an empty dict.
+
+## Plugins
+
+SPOT's umbrella vocabulary for pluggable components is **plugin**.
+``PluginKind`` discriminates between the two kinds today:
+
+```python
+from spot_sdk import PluginKind
+
+PluginKind.ANALYZER           # analyzer kind
+PluginKind.CONTEXT_PROVIDER   # context provider kind
+```
+
+- **Analyzers** run ``POST /internal/analyze`` and return an
+  ``AnalysisResult`` (a phishing verdict contributing to aggregation).
+- **Context providers** run ``POST /internal/enrich`` and return an
+  ``EnrichmentResult`` whose data populates ``analysis_context`` for
+  downstream analyzers.
+
+Plugins are discovered from OCI image labels prefixed ``spot.plugin.*``
+(see the platform documentation for the label contract) and installed
+into the platform via the ``/api/v1/plugins/*`` and
+``/api/v1/config/plugin/{kind}`` APIs.
+
+## Context Providers
+
+Context providers enrich an email with organizational data (employee directory,
+sender history, threat intelligence, knowledge bases, ...) before analyzers run.
+They are defined per workflow stage and run in parallel, just like analyzers.
+
+Each provider exposes a single HTTP endpoint:
+
+```
+POST /internal/enrich
+Content-Type: application/json
+
+Input:  Email (same model analyzers receive)
+Output: EnrichmentResult
+```
+
+### Implementing a provider
+
+```python
+from fastapi import FastAPI
+from spot_sdk import Email, EnrichmentResult
+
+app = FastAPI()
+
+@app.post("/internal/enrich")
+async def enrich(email: Email) -> EnrichmentResult:
+    sender = email.headers.sender
+    return EnrichmentResult(
+        provider_id="employee-dir",
+        data={
+            "sender_known": True,
+            "sender_department": "Finance",
+            "sender_role": "CFO",
+        },
+        source="company-ldap",
+        confidence=0.95,
+    )
+```
+
+The orchestrator merges each provider's `data` dict into
+`email.analysis_context["<stage-name>"]["providers"]["<provider-id>"]`,
+where downstream analyzers can read it via `email.ctx.provider(...)`.
+
+## Knowledge Store
+
+The Knowledge Store is the platform's RAG layer: context providers
+deposit tagged documents, analyzers fetch them on demand. Neither side
+references the other — they share only the tag vocabulary.
+
+```python
+from spot_sdk import KnowledgeClient, KnowledgeDocument, KnowledgeTag, chunk_text
+```
+
+### Ingestion (providers)
+
+Upsert is idempotent on `id`. Use stable deterministic ids so re-syncs
+replace rather than duplicate.
+
+```python
+kb = KnowledgeClient(
+    url=os.environ["SPOT_KNOWLEDGE_URL"],        # injected by installer
+    api_key=os.environ["SPOT_INTERNAL_API_KEY"], # idem
+)
+
+await kb.bulk_upsert([
+    KnowledgeDocument(
+        id=f"employee:{e.email}",
+        content=f"{e.name}, {e.title}, {e.department}",
+        tags=[KnowledgeTag.EMPLOYEE, *([KnowledgeTag.EXECUTIVE] if e.is_exec else [])],
+        metadata={"email": e.email, "title": e.title},
+        source="provider-employee-dir",
+    )
+    for e in employees
+])
+```
+
+For long content use `chunk_text(body, max_chars=2000, overlap=200)`
+and upsert each chunk with `metadata["parent_id"]` set to the source
+doc id.
+
+### Consumption (analyzers)
+
+```python
+kb = KnowledgeClient.for_analysis(email)  # reads SPOT_KNOWLEDGE_URL +
+                                          # email.retrieval_limits
+docs = await kb.fetch(tags="employee+executive", text=email.sender, top_k=3)
+```
+
+Tag-expression syntax: `a`, `a+b` (AND), `a|b` (OR), `a+b|c`
+(`(a AND b) OR c`). `+` binds tighter than `|`. Empty or `None` means
+no tag filter.
+
+Workflow-declared `retrieval_limits` (stage-level caps on `top_k` and
+`min_score`) are enforced transparently by `for_analysis()` — the
+analyzer doesn't need to know about them.
+
+### Testing
+
+```python
+from spot_sdk.testing.fake_knowledge_client import FakeKnowledgeClient
+
+kb = FakeKnowledgeClient()
+await kb.upsert(KnowledgeDocument(id="e:a", content="Alice", tags=["employee"]))
+assert (await kb.fetch(tags="employee", text="Alice"))[0].id == "e:a"
+```
+
+## Available Models
+
+### Analyzer Service (`spot_sdk.analyzer`)
+- `Email` - Email data structure
+- `EmailHeader` - Email header fields
+- `Attachment` - Email attachment
+- `AnalysisResult` - Analysis results
+- `AnalysisIndicator` - Phishing indicators
+- `ThreatLevel` - Threat level enum
+
+### API Gateway (`spot_sdk.api_gateway`)
+- `AnalysisRequest` - Analysis request
+- `AnalysisResponse` - Analysis response
+- `ConfigRequest` - Configuration request
+- `ConfigResponse` - Configuration response
+
+### Workflow (`spot_sdk.workflow`)
+- `Workflow`, `WorkflowStage`
+- `AnalyzerConfig`, `ContextProviderConfig`
+- `RetryConfig`, `FailureStrategy`
+
+### Plugin vocabulary (`spot_sdk.plugin`)
+- `PluginKind` - `ANALYZER` | `CONTEXT_PROVIDER`
+
+### Enrichment (`spot_sdk.enrichment`)
+- `EnrichmentResult` - Returned by context providers from `/internal/enrich`
+
+## Requirements
+
+- Python 3.11+
+- pydantic >= 2.0.0
+- httpx >= 0.25.0
+- typing-extensions >= 4.8.0
+
+## Development
+
+This SDK is automatically generated from OpenAPI specifications. 
+Do not modify generated files directly - update the OpenAPI specs instead.
+
+## Version
+
+Current version: 1.0.0
+
+Generated from SPOT Contracts repository.
+

spot_sdk_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+spot_sdk/__init__.py,sha256=upOtpYDG0mhdii-ZC5tCY0qoYoMEG3-i-ZxLYoilmEA,2289
+spot_sdk/analysis_context.py,sha256=ghdGhmWUOrkCrrEZWNn9nbVinMW1kmtei2xOKZyVGBI,3605
+spot_sdk/analyzer.py,sha256=bDrXVOO5YlP6M9Vh390XczWVTsgUaJlbR2ziibQwsag,2594
+spot_sdk/analyzer_base.py,sha256=ADrVNfyxtZWRff9UCgN0IGzFWkCUioRHwOKw7MAbtHQ,10223
+spot_sdk/api_gateway.py,sha256=8p_CPqP77gQPqgiBQzgfHhco-j1GnoucOMEQKx9bM4A,6222
+spot_sdk/config.py,sha256=7nkYo4gJ4tWLAqoA_dNAzbmasPmSxw8WesyDJ9tm_IA,1878
+spot_sdk/config_client.py,sha256=7L9ws9UPYLgfZ-QsLl1MBlHXrRxjmi90Oy37vSnSfu8,6515
+spot_sdk/config_helpers.py,sha256=_L72GjQ339SUQhGweAZQLzeqCYr-NwfT-F2aLweRiDo,839
+spot_sdk/email.py,sha256=uL7DIFOHCUN0aKTVb6zv8hmQN16GpJFQ2aBUqTfHdbI,4399
+spot_sdk/errors.py,sha256=HTaRaoDfn5XV4v03qD4eCM-IgNaR7upQ08UF-I-1qaI,813
+spot_sdk/knowledge.py,sha256=b1wNUrkFpqHK3nD65fT3n4adFA2cgeFhyoKs7E9gJmo,11930
+spot_sdk/knowledge_tags.py,sha256=BGhDsNeF8Q0MMNEIZjWrgQWjwH_Vf7dGBNN_hlBqTXs,978
+spot_sdk/logging.py,sha256=lY-OdTvShp3Vb-1Gmhi88z810YGFhh6y21PbNscBGSg,3907
+spot_sdk/ollama.py,sha256=Vaa1r0-boy0Gz6pxQqXplUMIdpLh_H1l75uIo9xRbO0,1794
+spot_sdk/orchestrator.py,sha256=GwZkvHyyONEmJVDChJCb8OT98GJ-vQTng2PHhD39Aso,2985
+spot_sdk/plugin.py,sha256=JGib8UoS9vDH7rK7-aAmnCab4CH1t2Zk1qy7O-Oz4AU,981
+spot_sdk/results.py,sha256=IdPHksHJ6zTY4zXS2tp4jk_N--Yxnf49Edswc1G-3vY,4226
+spot_sdk/settings_schema.py,sha256=FKoIWTxPaLDara2LMaXtLudJ9Xa_-OR2meC4m63iycE,1916
+spot_sdk/testing/README.md,sha256=EIRGybgaY8sQ6J6U5poezhz4HyK_pmFrANPMnWCEQSM,1782
+spot_sdk/testing/__init__.py,sha256=G8F0FNePLMcKn-pocQQMzA_iv1WcbdJFfwBWW7JqlJ4,483
+spot_sdk/testing/factories.py,sha256=ADJL0JkzS3DsEc4m9T0seuzPJuQuF7aWJaBUbIdecgY,4917
+spot_sdk/testing/fake_knowledge_client.py,sha256=aGLYqFHtHTqJvN0j1VDRmaLIgEEbpQyxuAC4XGJUuK4,3729
+spot_sdk/threat_levels.py,sha256=eRkd2GBS0TCKw4VGERkFYGMa-fxhrxB7TMa2UHi7e_Q,910
+spot_sdk/workflow.py,sha256=CYtAIuTJYN1qS0rmZzQXBrAgOYb46v8aCHJP7qzEHdU,4586
+spot_sdk_python-1.0.0.dist-info/METADATA,sha256=9OTIeSzpBxzwC4MJbsWbn2F1PsHt89qwabWMCBupK9k,10682
+spot_sdk_python-1.0.0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+spot_sdk_python-1.0.0.dist-info/RECORD,,

spot_sdk_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any