"""Grounding schemas: citations, sources, show-your-work for AGI verification."""

from datetime import datetime, timezone
from typing import Any

from pydantic import BaseModel, Field


def _utc_now() -> datetime:
    return datetime.now(timezone.utc)


class Citation(BaseModel):
    """Reference to a source supporting a claim."""

    source_id: str = Field(..., min_length=1, description="e.g. doc id, URL, trace step")
    excerpt: str = Field(default="", description="Relevant excerpt or quote")
    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
    metadata: dict[str, Any] = Field(default_factory=dict)


class GroundedClaim(BaseModel):
    """A claim with citations and optional show-your-work trace."""

    claim_id: str = Field(..., min_length=1)
    claim: str = Field(..., min_length=1)
    citations: list[Citation] = Field(default_factory=list)
    reasoning_trace: list[dict[str, Any]] = Field(default_factory=list, description="Show-your-work steps")
    confidence: float = Field(default=1.0, ge=0.0, le=1.0)
    created_at: datetime = Field(default_factory=_utc_now)