"""
Semantic and entity annotation layer for DecoupleRpy results.

Problem this solves
-------------------
Enrichment tools (CollecTRI, PROGENy, Hallmark) return labels that are not
all the same entity type.  CollecTRI TF enrichment may return individual gene
symbols (HIF1A, JUN) alongside complex/family/regulon labels (AP1, NFKB).
Downstream reporting must distinguish these — AP1 is not a single gene.

Architecture
------------
schemas.py         EntityAnnotation dataclass — the common return type for all
                   classifiers.  JSON-serializable via .to_dict().

gene_symbols.py    normalize_gene_symbol() — local check against a seed set of
                   known HGNC-like symbols.  Returns resolved/unresolved.

regulators.py      classify_regulator_label() — routes via regulator_overrides.yaml
                   first, then gene_symbols, then marks unresolved.

gene_sets.py       classify_gene_set_label() — Hallmark/PROGENy pattern matching
                   plus gene_set_overrides.yaml.

result_annotation.py
                   annotate_result_entities() — adds semantic annotation columns
                   to a results DataFrame.  The main entry point for MCP tools.

semantic_audit.py  semantic_audit() — summarises an annotated DataFrame: entity
                   type counts, unresolved labels, warnings, mixed-type flag.

When to use this layer
----------------------
Call annotate_result_entities() on any enrichment result DataFrame before
returning it to the agent or user.  Call semantic_audit() to generate a
reporting note that the agent can include in its final summary.

Static resources
----------------
resources/semantic/regulator_overrides.yaml  — known complex/family labels
resources/semantic/gene_set_overrides.yaml   — known gene set labels
"""

from .gene_sets import classify_gene_set_label
from .gene_symbols import normalize_gene_symbol
from .regulators import classify_regulator_label
from .result_annotation import annotate_result_entities
from .schemas import EntityAnnotation
from .semantic_audit import semantic_audit

__all__ = [
    "EntityAnnotation",
    "normalize_gene_symbol",
    "classify_regulator_label",
    "classify_gene_set_label",
    "annotate_result_entities",
    "semantic_audit",
]