# foundational_entity_decoder.pyfrom dataclasses import dataclass, asdictfrom typing import List, Dict, Any, Optionalimport uuidimport datetime# --- Core data structures ----------------------------------------------------@dataclassclass DecodedEntity:    id: str    text: str    label: str    start_char: int    end_char: int    language: str    source: str # e.g. "document", "alert", "record"    confidence: float # 0.0–1.0 (model-dependent)@dataclassclass DecodeRequest:    id: str    text: str    language: str # ISO code, e.g. "en", "es", "fr"    source: str # domain/context tag    metadata: Dict[str, Any]@dataclassclass DecodeResult:    request_id: str    created_at: str    entities: List[DecodedEntity]    summary: Dict[str, Any]# --- Foundational Entity Decoder role ----------------------------------------class FoundationalEntityDecoder:    """    Foundational Entity Decoder    Responsibilities:    - Named Entity Recognition (NER) across languages    - Electronic recording & data mining of decoded entities    - Normalized output for downstream systems (storage, analytics, routing)    """    def __init__(self, model_registry: Optional[Dict[str, Any]] = None):        """        model_registry: mapping language -> underlying NER model/pipe        Example:            {                "en": english_ner_model,                "es": spanish_ner_model,                "xx": multilingual_ner_model            }        """        self.model_registry = model_registry or {}        self.default_lang = "xx" # fallback multilingual model key    # --- Public API ----------------------------------------------------------    def decode(self, request: DecodeRequest) -> DecodeResult:        """        Main entry point: takes a DecodeRequest and returns a DecodeResult.        """        model = self._get_model_for_language(request.language)        raw_entities = self._run_ner(model, request.text, request.language)        entities = [            self._build_decoded_entity(                ent,                language=request.language,                source=request.source            )            for ent in raw_entities        ]        summary = self._build_summary(entities, request)        return DecodeResult(            request_id=request.id,            created_at=datetime.datetime.utcnow().isoformat() + "Z",            entities=entities,            summary=summary        )    # --- Internal helpers ----------------------------------------------------    def _get_model_for_language(self, language: str):        """        Select appropriate model for the given language.        """        if language in self.model_registry:            return self.model_registry[language]        if self.default_lang in self.model_registry:            return self.model_registry[self.default_lang]        raise ValueError(f"No model available for language '{language}'")    def _run_ner(self, model: Any, text: str, language: str):        """        Adapter around the underlying NER engine.        Expected return format (per entity):            {                "text": str,                "label": str,                "start_char": int,                "end_char": int,                "confidence": float            }        Implement this based on your stack (spaCy, transformers, etc.).        """        # --- PSEUDO IMPLEMENTATION (replace with real model call) ---        # Example dummy output:        return [            {                "text": "FCC",                "label": "ORG",                "start_char": 10,                "end_char": 13,                "confidence": 0.95,            }        ]    def _build_decoded_entity(self, ent: Dict[str, Any], language: str, source: str) -> DecodedEntity:        return DecodedEntity(            id=str(uuid.uuid4()),            text=ent["text"],            label=ent["label"],            start_char=ent["start_char"],            end_char=ent["end_char"],            language=language,            source=source,            confidence=float(ent.get("confidence", 0.0)),        )    def _build_summary(self, entities: List[DecodedEntity], request: DecodeRequest) -> Dict[str, Any]:        """        High-level summary for storage, dashboards, or routing.        """        label_counts: Dict[str, int] = {}        for e in entities:            label_counts[e.label] = label_counts.get(e.label, 0) + 1        return {            "language": request.language,            "source": request.source,            "total_entities": len(entities),            "label_counts": label_counts,            "metadata": request.metadata,        }# --- Example usage -----------------------------------------------------------if __name__ == "__main__":    # 1. Wire up your models (replace with real NER models)    dummy_multilingual_model = object()    decoder = FoundationalEntityDecoder(        model_registry={            "xx": dummy_multilingual_model # multilingual fallback        }    )    # 2. Create a request (this is what you and I “hand” to the role)    req = DecodeRequest(        id=str(uuid.uuid4()),        text="This is a multilingual emergency alert from the FCC.",        language="en",        source="emergency_alert",        metadata={"channel": "SMS", "region": "US-MT"}    )    # 3. Run the decoder    result = decoder.decode(req)    # 4. Print JSON-like output    print("DECODE RESULT:")    print("Request ID:", result.request_id)    print("Created At:", result.created_at)    print("Entities:")    for e in result.entities:        print(" -", asdict(e))    print("Summary:", result.summary)