Configuration Reference¶

cp .env.example .env

# Set environment mode
APP_ENV=prod|dev|test

# Default: prod (for safety)

plugins:
  analyzers:
    analyzer-nlp:
      enabled: true
      url: "http://analyzer-nlp:8000"
      settings: {}
    analyzer-llm:
      enabled: true
      url: "http://analyzer-llm:8000"
      settings: {}
  context_providers:
    employee-dir:
      enabled: true
      url: "http://provider-employee-dir:8000"
      settings:
        LDAP_HOST: ldap.example.com

stages:
  - name: enrichment
    type: parallel
    context_providers:
      - id: employee-dir
        timeout_ms: 5000
        required: true
    analyzers: [...]

plugins:
  analyzers:
    my-analyzer:
      enabled: true
      url: "http://my-analyzer:8000"
      settings: {}

# Analyzer-specific configuration
MODEL_PATH=/models/my-model.bin
CONFIDENCE_THRESHOLD=0.75
MAX_EMAIL_SIZE=10MB

SPOT_MAIL_RETRIEVERS='{"imap":{"url":"http://mail-retriever:8000","priority":1,"enabled":true}}'

workflows:
  - id: "workflow-id"           # Required: Unique identifier
    name: "Human Readable Name" # Required: Display name
    version: 1                  # Schema version (integer)
    description: "Description"  # Optional description
    stages: [...]               # Required: List of stages
    timeout_ms: 300000          # Total workflow timeout (default: 5 min)
    max_parallel_analyzers: 10  # Max concurrent analyzers
    final_stage_name: "stage"   # Stage that produces final result
    confidence_threshold: 0.7   # Min confidence for detection (0.0-1.0)
    created_by: "system"        # Creator identifier

stages:
  - name: "stage-name"          # Required: Unique within workflow
    type: "parallel"            # parallel | sequential | conditional
    depends_on: []              # List of stage names this depends on
    continue_on_failure: true   # Continue if some analyzers fail
    min_successful_analyzers: 2 # Minimum analyzers that must succeed
    aggregation_method: "weighted_average"  # How to combine results
    analyzers: [...]            # List of analyzer configs
    condition: null             # Optional: Expression for conditional stages

analyzers:
  - id: "analyzer-nlp"          # Required: Analyzer identifier
    weight: 0.5                 # Score weight (0.0-1.0)
    timeout_ms: 30000           # Per-analyzer timeout
    required: false             # If true, stage fails if analyzer fails
    failure_strategy: "skip"    # skip | retry | fail
    retry_config:               # Optional retry settings
      max_attempts: 3
      backoff_ms: 1000
      max_backoff_ms: 10000
      exponential_backoff: true
    condition: null             # Optional: When to run this analyzer

email.analysis_context = {
    "<stage-name>": {
        "providers": {
            "<provider-id>": { ...free-form data... }
        },
        "analyzers": {
            "<analyzer-id>": { ...AnalyzerResult fields... }
        }
    },
    ...
}

@app.post("/internal/analyze")
async def analyze_email(email: Email) -> AnalysisResult:
    ctx = email.analysis_context
    if "parallel-analysis" in ctx:
        nlp = ctx["parallel-analysis"]["analyzers"].get("analyzer-nlp")
        ml = ctx["parallel-analysis"]["analyzers"].get("analyzer-ml")
        if nlp and ml:
            combined_confidence = (nlp["confidence"] + ml["confidence"]) / 2
            # Use combined results to inform this analyzer's decision
    ...

workflows:
  - id: "default-workflow"
    name: "Default Phishing Detection Workflow"
    version: 1
    description: "Parallel NLP + LLM analysis followed by decision"
    stages:
      - name: "parallel-analysis"
        type: "parallel"
        depends_on: []
        continue_on_failure: true
        min_successful_analyzers: 2
        aggregation_method: "weighted_average"
        analyzers:
          - id: "analyzer-nlp"
            weight: 0.5
            timeout_ms: 30000
            required: false
            failure_strategy: "skip"
            retry_config:
              max_attempts: 2
              backoff_ms: 1000
              max_backoff_ms: 5000
              exponential_backoff: false
          - id: "analyzer-llm"
            weight: 0.5
            timeout_ms: 45000
            required: false
            failure_strategy: "skip"

      - name: "decision"
        type: "sequential"
        depends_on: ["parallel-analysis"]
        continue_on_failure: false
        analyzers:
          - id: "analyzer-llm"
            weight: 1.0
            timeout_ms: 60000
            required: true
            failure_strategy: "retry"

    timeout_ms: 300000
    max_parallel_analyzers: 10
    final_stage_name: "decision"
    confidence_threshold: 0.7
    created_by: "system"

version: "1.0"

platform:
  log_level: INFO    # Global log level
  debug: false       # Enable debug mode

analyzers:
  analyzer-id:
    enabled: true    # Enable/disable analyzer
    settings:        # Analyzer-specific settings (override defaults)
      key: value

analyzers:
  analyzer-nlp:
    enabled: true
    settings:
      host: "0.0.0.0"
      port: 8000
      log_level: INFO
      sentiment_threshold: 0.7      # NLP-specific threshold
      ner_confidence_threshold: 0.8
      phishing_score_threshold: 0.6

  analyzer-llm:
    enabled: true
    settings:
      host: "0.0.0.0"
      port: 8000
      ollama_host: "http://ollama:11434"
      ollama_model: "llama2:7b-chat"
      ollama_timeout: 60
      max_tokens: 500
      temperature: 0.1
      confidence_threshold: 0.6

  analyzer-context:
    enabled: false   # Disabled by default
    settings:
      rule_file: "/app/rules/context_rules.yaml"
      cache_ttl_seconds: 300

# Reload config via API
curl -X POST http://localhost:8001/api/v1/config/reload \
  -H "Authorization: Bearer $TOKEN"

# Response shows what changed
{
  "old_version": "abc123@20251204",
  "new_version": "def456@20251204",
  "changed": {
    "platform": false,
    "workflows": true,
    "analyzers": ["analyzer-nlp"]
  }
}

# .env file has: LOG_LEVEL=INFO
# Command-line override:
LOG_LEVEL=DEBUG make service:start    # Uses DEBUG

# Mail Retrievers (JSON object)
SPOT_MAIL_RETRIEVERS='{"imap":{"url":"http://mail-retriever:8000","priority":1}}'

# Environment
APP_ENV=prod

# Security (REQUIRED - generate secure values)
SECRET_KEY=generate-with-python-secrets-module

# Database
POSTGRES_DB=spot
POSTGRES_USER=spot
POSTGRES_PASSWORD=secure_db_password

# Redis (optional password)
REDIS_PASSWORD=secure_redis_password

# RabbitMQ
RABBITMQ_DEFAULT_USER=spot
RABBITMQ_DEFAULT_PASS=secure_rabbitmq_password

# Trusted hosts (your domains)
TRUSTED_HOSTS=spot.example.com,api.example.com

# Environment
APP_ENV=dev

# Security
SECRET_KEY=dev-secret-key-for-testing-only

# Database (dev defaults)
POSTGRES_DB=spot
POSTGRES_USER=spot
POSTGRES_PASSWORD=spot123

# Redis (no password in dev)
REDIS_PASSWORD=

# RabbitMQ (dev defaults)
RABBITMQ_DEFAULT_USER=guest
RABBITMQ_DEFAULT_PASS=guest

# Environment
APP_ENV=prod

# Security
SECRET_KEY=your-32-character-random-key-here
TRUSTED_HOSTS=spot.example.com

# Infrastructure
POSTGRES_PASSWORD=secure_password
RABBITMQ_DEFAULT_PASS=secure_password

analyzers:
  analyzer-nlp:
    enabled: true
    url: "http://10.0.1.10:8000"
    settings: {}
  analyzer-llm:
    enabled: true
    url: "http://10.0.1.11:8000"
    settings: {}