"""cortex/types/entities.py — Entity resolution and peer types."""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Optional


# ---------------------------------------------------------------------------
# Entity
# ---------------------------------------------------------------------------

@dataclass
class Entity:
    """A resolved real-world entity (person, project, concept, etc.).

    Entities are the nodes in Cortex's knowledge graph. Claims reference
    entities via subject_entity_id / object_entity_id foreign keys.

    Created by: EntityResolver (M3) during extraction pipeline.
    Used by: ReconciliationEngine (M4) for claim dedup, RetrievalPipeline (M8)
             for entity-scoped queries.
    """
    id: str
    owner_id: str
    canonical_name: str
    entity_type: str
    description: Optional[str] = None
    metadata_json: Optional[str] = None
    first_seen: Optional[str] = None
    last_seen: Optional[str] = None
    mention_count: int = 1
    created_at: Optional[str] = None
    updated_at: Optional[str] = None
    visibility_status: str = "extracted"
    connection_count: int = 0
    last_promoted_at: Optional[str] = None
    promotion_reason: Optional[str] = None


@dataclass
class EntityAlias:
    """An alternative name/spelling that maps to a canonical Entity.

    Aliases enable fuzzy entity resolution — "Andy", "andrew", "@andrew"
    all resolve to the same Entity with canonical_name="Andrew".

    Created by: EntityResolver (M3) when new name variants are encountered.
    Used by: StorageAdapter.find_entity_by_alias() for case-insensitive lookup.
    """
    id: str
    entity_id: str
    alias: str
    alias_type: str = 'name'
    source: str = 'extracted'
    confidence: float = 1.0
    created_at: Optional[str] = None


# ---------------------------------------------------------------------------
# Entity Resolution types (M3)
# ---------------------------------------------------------------------------

@dataclass
class ResolvedEntity:
    """Result of entity resolution for a mention."""
    entity_id: str
    canonical_name: str
    entity_type: str
    confidence: float
    is_new: bool
    matched_alias: Optional[str] = None


@dataclass
class CandidateEntity:
    """An entity mention candidate (before resolution)."""
    name: str
    entity_type: str
    aliases: list = field(default_factory=list)
    is_new: bool = False


@dataclass
class Peer:
    """A tracked interaction partner with a learned representation.

    Peers are created automatically from entity mentions (when mention_count
    reaches the configured threshold) or manually via the API.
    """
    id: str
    owner_id: str
    entity_id: Optional[str]
    display_name: str
    relationship: str
    first_interaction: str
    last_interaction: str
    interaction_count: int
    representation: str  # JSON blob
    created_at: str
    updated_at: str
    # v22 peer-promotion fields (#932)
    peer_type: str = "person"        # person | agent | system
    status: str = "active"           # active | inactive | archived
    permissions_json: str = "{}"
    description: Optional[str] = None
    promoted_at: Optional[str] = None
    promotion_reason: Optional[str] = None
    connection_count: int = 0


@dataclass
class MergeSuggestion:
    """A candidate entity merge suggestion for human/operator review."""
    keep_id: str
    merge_id: str
    keep_name: str
    merge_name: str
    similarity_score: float
    reason: str
