src/models/api/report.py

"""Request / response models for report routes (KM-644).

The full report payload is the `AnalysisReport` contract
(src/agents/report/schemas.py); this module only adds the lightweight list-entry
returned by the versions endpoint.
"""

from datetime import datetime

from pydantic import BaseModel, Field


class ReportVersionEntry(BaseModel):
    """One row in a session's report-version list (for the Analysis-menu sidebar)."""

    report_id: str = Field(..., description="Stable report identifier.")
    version: int = Field(..., description="Monotonic version (V1, V2, …).")
    generated_at: datetime = Field(..., description="When this version was generated.")
    record_count: int = Field(..., description="Number of AnalysisRecords it was built from.")


class AnalysisRecordEntry(BaseModel):
    """One persisted analysis run, listed for report curation (KM-644 report v2).

    The FE shows these before generating so the user can exclude runs
    (`exclude_record_ids` on POST /tools/report). `substantive` mirrors the
    report's own inclusion rule: non-substantive runs land in the report's
    `unresolved` list rather than the findings body (the "Attempted, Unresolved"
    markdown section was dropped 2026-07-09; the JSON field remains).
    """

    record_id: str = Field(..., description="Id to pass in exclude_record_ids.")
    goal_restated: str = Field("", description="The run's question, as the agent restated it.")
    created_at: datetime = Field(..., description="When the run was recorded.")
    substantive: bool = Field(
        ..., description="True if an analyze_* step succeeded (counts toward the report floor)."
    )
    findings_count: int = Field(0, description="Number of findings the run recorded.")


class ReportReadinessResponse(BaseModel):
    """Deterministic report-readiness signal (same producer as Help's signal)."""

    ready: bool = Field(..., description="Whether generating a report now makes sense.")
    missing: list[str] = Field(
        default_factory=list,
        description="Human-readable gaps when not ready (e.g. the delta-since-report check).",
    )