resolutionflow/backend/app/models/ai_session_step.py

"""AI session step model.

Every interaction within an AI session is captured as a step.
Steps are the raw material that becomes flow nodes in the Knowledge Flywheel.
"""
import uuid
from datetime import datetime, timezone
from typing import Optional, Any, TYPE_CHECKING

from sqlalchemy import String, Text, DateTime, ForeignKey, Integer, Float, CheckConstraint
from sqlalchemy.orm import Mapped, mapped_column, relationship
from sqlalchemy.dialects.postgresql import UUID, JSONB

from app.core.database import Base

if TYPE_CHECKING:
    from app.models.ai_session import AISession
    from app.models.script_template import ScriptGeneration
    from app.models.session_branch import SessionBranch
    from app.models.fork_point import ForkPoint


class AISessionStep(Base):
    """A single interaction step within a FlowPilot session.

    Step types:
    - question: FlowPilot asks a diagnostic question with options
    - action: FlowPilot suggests an action for the engineer to perform
    - script_generation: FlowPilot invokes the Script Generator
    - verification: FlowPilot asks engineer to verify a condition
    - info_request: FlowPilot asks engineer to gather specific data
    - note: Engineer or FlowPilot adds a contextual note
    - intake_analysis: Initial analysis of the intake content
    """
    __tablename__ = "ai_session_steps"
    __table_args__ = (
        CheckConstraint(
            "step_type IN ('question', 'action', 'script_generation', 'verification', "
            "'info_request', 'note', 'intake_analysis', 'fork', 'status_update')",
            name="ck_ai_session_steps_step_type",
        ),
    )

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True), primary_key=True, default=uuid.uuid4
    )
    session_id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("ai_sessions.id", ondelete="CASCADE"),
        nullable=False,
        index=True,
    )
    step_order: Mapped[int] = mapped_column(
        Integer, nullable=False,
        comment="Sequential position in the session (0-indexed)",
    )
    step_type: Mapped[str] = mapped_column(
        String(30), nullable=False,
    )

    # ── Content presented to engineer ──
    content: Mapped[dict[str, Any]] = mapped_column(
        JSONB, nullable=False, default=dict,
        comment="The question/action content rendered in the session UI",
    )
    context_message: Mapped[Optional[str]] = mapped_column(
        Text, nullable=True,
        comment="Why FlowPilot is asking this (shown above the question)",
    )

    # ── Options (for question steps) ──
    options_presented: Mapped[Optional[list[dict[str, Any]]]] = mapped_column(
        JSONB, nullable=True,
        comment="Array of {label, value, followup_hint} options shown to engineer",
    )

    # ── Engineer response ──
    selected_option: Mapped[Optional[str]] = mapped_column(
        String(500), nullable=True,
        comment="Which option the engineer selected (value field)",
    )
    free_text_input: Mapped[Optional[str]] = mapped_column(
        Text, nullable=True,
        comment="If engineer typed a custom response instead of selecting an option",
    )
    was_free_text: Mapped[bool] = mapped_column(
        default=False,
        comment="True if the engineer used the free-text escape hatch",
    )
    was_skipped: Mapped[bool] = mapped_column(
        default=False,
        comment="True if engineer selected 'I don't know / Can't check'",
    )

    # ── Action results ──
    action_result: Mapped[Optional[dict[str, Any]]] = mapped_column(
        JSONB, nullable=True,
        comment="Outcome of action step: {success: bool, details: str, next_hint: str}",
    )

    # ── Script generation link ──
    script_generation_id: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("script_generations.id", ondelete="SET NULL"),
        nullable=True,
    )

    # ── AI internals ──
    confidence_at_step: Mapped[float] = mapped_column(
        Float, nullable=False, default=0.0,
        comment="FlowPilot confidence level at this point (0.0-1.0)",
    )
    ai_reasoning: Mapped[Optional[str]] = mapped_column(
        Text, nullable=True,
        comment="Why FlowPilot chose this step (internal, for debugging/training)",
    )
    input_tokens: Mapped[int] = mapped_column(
        Integer, nullable=False, default=0,
    )
    output_tokens: Mapped[int] = mapped_column(
        Integer, nullable=False, default=0,
    )

    # ── Branching ──
    branch_id: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("session_branches.id", ondelete="SET NULL"),
        nullable=True,
        index=True,
        comment="NULL = pre-branching/root messages",
    )
    is_fork_point: Mapped[bool] = mapped_column(
        default=False,
        comment="Whether this step triggered a fork",
    )
    fork_point_id: Mapped[Optional[uuid.UUID]] = mapped_column(
        UUID(as_uuid=True),
        ForeignKey("fork_points.id", ondelete="SET NULL"),
        nullable=True,
    )

    # ── Timestamps ──
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
    )
    responded_at: Mapped[Optional[datetime]] = mapped_column(
        DateTime(timezone=True), nullable=True,
        comment="When the engineer responded to this step",
    )

    # ── Relationships ──
    session: Mapped["AISession"] = relationship("AISession", back_populates="steps")
    script_generation: Mapped[Optional["ScriptGeneration"]] = relationship("ScriptGeneration")