"""Knowledge Base and agent contract models (Phase 0)."""
from typing import Any, Dict, List, Optional
from pydantic import BaseModel, Field, ConfigDict


class VectorMetadata(BaseModel):
    """Minimal vector metadata schema for KB indexing."""
    model_config = ConfigDict(extra="allow")

    id: str = Field(..., description="Unique embedding/document ID")
    source_type: str = Field(..., description="Source type (doc, hierarchy, mapping, dbt, etc.)")
    source_id: str = Field(..., description="Source-specific ID")
    hierarchy_id: Optional[str] = Field(default=None, description="Hierarchy ID if applicable")
    tags: List[str] = Field(default_factory=list)
    created_at: Optional[str] = Field(default=None, description="ISO timestamp")
    updated_at: Optional[str] = Field(default=None, description="ISO timestamp")
    extra: Dict[str, Any] = Field(default_factory=dict)


class GraphNode(BaseModel):
    """Graph node representation for KB graph store."""
    model_config = ConfigDict(extra="allow")

    id: str = Field(..., description="Node ID")
    type: str = Field(..., description="Node type (Hierarchy, Table, Column, Model, etc.)")
    properties: Dict[str, Any] = Field(default_factory=dict)


class GraphEdge(BaseModel):
    """Graph edge representation for KB graph store."""
    model_config = ConfigDict(extra="allow")

    source: str = Field(..., description="Source node ID")
    target: str = Field(..., description="Target node ID")
    type: str = Field(..., description="Edge type (MAPS_TO, DERIVES_FROM, IMPACTS, etc.)")
    properties: Dict[str, Any] = Field(default_factory=dict)


class AgentResultEnvelope(BaseModel):
    """Standard agent result envelope for orchestration."""
    model_config = ConfigDict(extra="allow")

    items: List[Any] = Field(default_factory=list)
    scores: List[float] = Field(default_factory=list)
    citations: List[str] = Field(default_factory=list)
    trace: Dict[str, Any] = Field(default_factory=dict)
    confidence: float = Field(default=0.0)
