from typing import Optional
from pydantic import BaseModel, Field


class Citation(BaseModel):
    """A citation to a source document or reference."""
    source_id: str = Field(..., description="Unique identifier for the source (e.g., document ID, URL, DOI)")
    title: Optional[str] = Field(None, description="Title of the source document")
    author: Optional[str] = Field(None, description="Author(s) of the source")
    publication_date: Optional[str] = Field(None, description="Publication date or last modified date")
    page_number: Optional[int] = Field(None, description="Specific page number if applicable")
    section: Optional[str] = Field(None, description="Section, chapter, or heading within the source")
    url: Optional[str] = Field(None, description="URL or link to the source")


class SourceReference(BaseModel):
    """A reference to a specific part of a source with the relevant content."""
    citation: Citation = Field(..., description="Citation information for this source")
    excerpt: str = Field(..., description="The relevant text excerpt from the source")
    relevance_score: Optional[float] = Field(None, ge=0.0, le=1.0, description="How relevant this source is to the query (0-1)")
    context: Optional[str] = Field(None, description="Additional context about where this excerpt fits in the source")


class SourceBundle(BaseModel):
    """A collection of related source references supporting a specific point."""
    claim: str = Field(..., description="The claim or point being supported by these sources")
    sources: list[SourceReference] = Field(..., description="List of source references supporting this claim")
    synthesis: Optional[str] = Field(None, description="A synthesis or summary of what the sources collectively say")
