"""Uniform enricher contract. Every OSINT module returns the same envelope so the platform

can store entities, relationships, evidence, source metadata, confidence and the raw response

reference identically regardless of source."""

from __future__ import annotations

from abc import ABC, abstractmethod

from dataclasses import asdict, dataclass, field

from datetime import datetime, timezone

@dataclass

class EnrichEntity:

    kind: str

    value: str

    attributes: dict = field(default_factory=dict)

@dataclass

class EnrichRelationship:

    src_kind: str

    src_value: str

    dst_kind: str

    dst_value: str

    relation: str

    confidence: float = 0.7

@dataclass

class EnrichResult:

    enricher: str

    target: str

    entities: list[EnrichEntity] = field(default_factory=list)

    relationships: list[EnrichRelationship] = field(default_factory=list)

    evidence: list[dict] = field(default_factory=list)

    source_metadata: dict = field(default_factory=dict)

    confidence: float = 0.5

    raw_response: object | None = None

    error: str | None = None

    fetched_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())

    def to_dict(self) -> dict:

        d = asdict(self)

        d.pop("raw_response", None)

        return d

class BaseEnricher(ABC):

    name: str = "base"

    kind: str = "generic"

    requires_network: bool = True

    @abstractmethod

    def run(self, target: str) -> EnrichResult:

        ...

    def _empty(self, target: str, error: str | None = None) -> EnrichResult:

        return EnrichResult(enricher=self.name, target=target, error=error, confidence=0.0)