nextcraft/apps/ai-service/ai_service/api/defense.py

"""Oral-defense endpoints (Task 5-3-01, REQ-3-006, A-109).

Full defense loop over HTTP with mock-first voice (D-030) and the seventh
Examiner agent (SSE question streaming happens through the chat pipeline;
these endpoints are the session orchestration + transcript persistence):

    POST /v1/defense/start          {learner_id, task_id}
    POST /v1/defense/{id}/answer    {text} | multipart audio (STT)
    GET  /v1/defense/{id}/audio/{turn_id}      TTS bytes (streaming)
    POST /v1/defense/{id}/finish    verdict + integrity signals
    GET  /v1/defense/{id}           transcript + signals

Integrity signals (A-109) are computed server-side from turn metadata:
long pauses = learner turns whose latency_ms exceeds PAUSE_THRESHOLD_MS.
The defense does NOT gate on trace completeness (the grader does, G-4);
an incomplete trace is surfaced as `trace_complete: false` so the UI can
disclose it before the learner defends.
"""

from __future__ import annotations

import time
from datetime import UTC, datetime
from typing import TYPE_CHECKING

from fastapi import APIRouter, Depends, File, Form, HTTPException, UploadFile
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field

from ..agents.examiner import ExaminerAgent
from ..grading.features import TraceDigest, compute_digest
from ..llm.types import Message
from ..voice.base import VoiceDescriptor
from ..voice.browser import BROWSER_FALLBACK_DESCRIPTOR
from ..voice.defense_store import DefenseRecord, DefenseStore, DefenseTurn
from .deps import (
    get_examiner,
    get_settings,
    get_trace_store,
    get_variant_store,
    get_voice_provider,
    get_voice_store,
)

if TYPE_CHECKING:  # pragma: no cover
    pass

router = APIRouter(prefix="/v1/defense", tags=["defense"])

#: A-109: learner turns slower than this are flagged as long pauses (ms).
PAUSE_THRESHOLD_MS = 15_000

_ROLE_EXAMINER = "examiner"
_ROLE_LEARNER = "learner"


class StartRequest(BaseModel):
    learner_id: str = Field(min_length=1)
    task_id: str = Field(min_length=1)


class StartResponse(BaseModel):
    defense_id: str
    voice_descriptor: dict
    trace_complete: bool
    first_question: str


class AnswerResponse(BaseModel):
    question: str
    turn_latency: dict[str, int | None]


class FinishResponse(BaseModel):
    verdict: dict
    integrity_signals: dict


async def _digest_for_task(
    trace_store, learner_id: str, task_id: str
) -> tuple[TraceDigest | None, bool]:
    """Digest of the learner's trace for this task + completeness flag."""
    if not trace_store.list_tasks(learner_id) or task_id not in trace_store.list_tasks(
        learner_id
    ):
        return None, True  # no trace at all is "complete" for defense purposes
    trace = trace_store.get_trace(learner_id, task_id)
    gaps = trace_store.gaps(learner_id, task_id)
    return (compute_digest(trace) if trace else None), (len(gaps) == 0)


def _voice_descriptor(settings) -> VoiceDescriptor:
    """The capability descriptor for the configured voice mode (D-030).

    Must-Have #6: browser mode returns BROWSER_FALLBACK_DESCRIPTOR so the
    web client selects native SpeechRecognition/speechSynthesis; mock mode
    returns the mock descriptor. (A v0.4 server provider would return
    mode="server" — the protocol seam.)
    """
    if (settings.voice_provider or "mock").strip().lower() == "browser":
        return BROWSER_FALLBACK_DESCRIPTOR
    return VoiceDescriptor(
        mode="mock", sr_available=True, tts_available=True, hint=""
    )


@router.post("/start", response_model=StartResponse)
async def start_defense(
    body: StartRequest,
    examiner: ExaminerAgent = Depends(get_examiner),
    voice_store: DefenseStore = Depends(get_voice_store),
    voice_provider=Depends(get_voice_provider),
    trace_store=Depends(get_trace_store),
    variant_store=Depends(get_variant_store),
    settings=Depends(get_settings),
) -> StartResponse:
    record = voice_store.start(
        DefenseRecord(
            id=f"dfn-{int(time.time() * 1000):x}-{body.learner_id[:8]}",
            learner_id=body.learner_id,
            task_id=body.task_id,
            status="in_progress",
            created_at=datetime.now(UTC),
        )
    )
    digest, trace_complete = await _digest_for_task(trace_store, body.learner_id, body.task_id)
    variant = variant_store.get_by_task(body.task_id)
    statement = variant.statement if variant is not None else None

    started = time.perf_counter()
    question = await examiner.next_question(
        history=[], trace_digest=digest, variant_statement=statement
    )
    llm_ms = int((time.perf_counter() - started) * 1000)
    voice_store.append_turn(
        record.id,
        DefenseTurn(
            defense_id=record.id,
            seq=0,
            role=_ROLE_EXAMINER,
            text=question,
            ts=datetime.now(UTC),
            latency_ms=llm_ms,
            created_at=datetime.now(UTC),
        ),
    )
    descriptor = getattr(voice_provider, "descriptor", None) or _voice_descriptor(
        settings
    )
    return StartResponse(
        defense_id=record.id,
        voice_descriptor=descriptor.model_dump(),
        trace_complete=trace_complete,
        first_question=question,
    )


@router.post("/{defense_id}/answer", response_model=AnswerResponse)
async def answer_defense(
    defense_id: str,
    text: str | None = Form(default=None),
    audio: UploadFile | None = File(default=None),
    voice_store: DefenseStore = Depends(get_voice_store),
    voice_provider=Depends(get_voice_provider),
    examiner: ExaminerAgent = Depends(get_examiner),
    trace_store=Depends(get_trace_store),
    variant_store=Depends(get_variant_store),
) -> AnswerResponse:
    record = voice_store.get(defense_id)
    if record is None:
        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
    if record.status == "finished":
        # The store owns the finished transition but does NOT police turn
        # sequencing (defense_store.py: "turns after finalize are a sequencing
        # bug for the endpoints to prevent") — this is the endpoint half of
        # that contract: a sealed transcript is append-only-no-more.
        raise HTTPException(
            status_code=409, detail="defense is finished; start a new defense"
        )
    if text is None and audio is None:
        raise HTTPException(status_code=422, detail="provide {text} or audio")

    # STT (typed fallback bypasses the voice provider entirely).
    stt_ms: int | None = None
    if audio is not None:
        stt_started = time.perf_counter()
        raw = await audio.read()
        if not raw:
            # Empty upload is a client error (422), not a provider crash
            # (500): validate before the provider call so every provider —
            # mock today, the v0.4 real one — sees the same contract.
            raise HTTPException(status_code=422, detail="audio upload is empty")
        fmt = (audio.content_type or "audio/wav").split("/")[-1]
        segment = await voice_provider.transcribe(raw, fmt)
        stt_ms = int((time.perf_counter() - stt_started) * 1000)
        text = segment.text

    turns = record.turns if hasattr(record, "turns") else []
    history = [
        Message(role="assistant" if t.role == _ROLE_EXAMINER else "user", content=t.text)
        for t in turns
    ]
    next_seq = len(turns)

    voice_store.append_turn(
        defense_id,
        DefenseTurn(
            defense_id=defense_id,
            seq=next_seq,
            role=_ROLE_LEARNER,
            text=text or "",
            ts=datetime.now(UTC),
            latency_ms=stt_ms,
            created_at=datetime.now(UTC),
        ),
    )

    digest, _ = await _digest_for_task(trace_store, record.learner_id, record.task_id)
    variant = variant_store.get_by_task(record.task_id)

    llm_started = time.perf_counter()
    question = await examiner.next_question(
        history=history + [Message(role="user", content=text or "")],
        trace_digest=digest,
        variant_statement=variant.statement if variant is not None else None,
    )
    llm_ms = int((time.perf_counter() - llm_started) * 1000)

    voice_store.append_turn(
        defense_id,
        DefenseTurn(
            defense_id=defense_id,
            seq=next_seq + 1,
            role=_ROLE_EXAMINER,
            text=question,
            ts=datetime.now(UTC),
            latency_ms=llm_ms,
            created_at=datetime.now(UTC),
        ),
    )
    return AnswerResponse(
        question=question,
        turn_latency={"stt_ms": stt_ms, "llm_ms": llm_ms, "tts_ms": None},
    )


@router.get("/{defense_id}/audio/{turn_id}")
async def defense_audio(
    defense_id: str,
    turn_id: int,
    voice_store: DefenseStore = Depends(get_voice_store),
    voice_provider=Depends(get_voice_provider),
):
    record = voice_store.get(defense_id)
    if record is None:
        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
    turn = next((t for t in record.turns if t.seq == turn_id), None)
    if turn is None or turn.role != _ROLE_EXAMINER:
        raise HTTPException(status_code=404, detail=f"no examiner turn {turn_id!r}")

    async def stream():
        async for chunk in voice_provider.synthesize(turn.text):
            yield chunk

    return StreamingResponse(stream(), media_type="audio/wav")


@router.post("/{defense_id}/finish", response_model=FinishResponse)
async def finish_defense(
    defense_id: str,
    voice_store: DefenseStore = Depends(get_voice_store),
    examiner: ExaminerAgent = Depends(get_examiner),
    trace_store=Depends(get_trace_store),
    variant_store=Depends(get_variant_store),
) -> FinishResponse:
    record = voice_store.get(defense_id)
    if record is None:
        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")

    turns = record.turns if hasattr(record, "turns") else []
    history = [
        Message(role="assistant" if t.role == _ROLE_EXAMINER else "user", content=t.text)
        for t in turns
    ]
    digest, _ = await _digest_for_task(trace_store, record.learner_id, record.task_id)
    variant = variant_store.get_by_task(record.task_id)
    verdict = await examiner.final_verdict(
        history=history,
        trace_digest=digest,
        variant_statement=variant.statement if variant is not None else None,
    )

    signals: dict = {
        "long_pauses": [
            {"turn": t.seq, "latency_ms": t.latency_ms}
            for t in turns
            if t.role == _ROLE_LEARNER and (t.latency_ms or 0) > PAUSE_THRESHOLD_MS
        ],
        "pause_threshold_ms": PAUSE_THRESHOLD_MS,
        # Must-Have #1: "verdict + transcript persisted" — the verdict is
        # stored INSIDE integrity_signals so GET /{id} after finish can
        # re-serve it (the finish response alone would lose it). Signals
        # are a JSON object dict (DefenseStore.finalize contract), so the
        # verdict nests under the "verdict" key alongside the A-109
        # markers the Proctor/Mentor feeds read.
        "verdict": verdict.model_dump(),
    }
    voice_store.finalize(defense_id, signals)
    return FinishResponse(verdict=verdict.model_dump(), integrity_signals=signals)


@router.get("/{defense_id}")
async def get_defense(
    defense_id: str,
    voice_store: DefenseStore = Depends(get_voice_store),
):
    record = voice_store.get(defense_id)
    if record is None:
        raise HTTPException(status_code=404, detail=f"no defense {defense_id!r}")
    return {
        "defense_id": record.id,
        "learner_id": record.learner_id,
        "task_id": record.task_id,
        "status": record.status,
        "turns": [
            {
                "seq": t.seq,
                "role": t.role,
                "text": t.text,
                "ts": t.ts,
                "latency_ms": t.latency_ms,
            }
            for t in record.turns
        ],
        "integrity_signals": record.integrity_signals or {},
    }