feat(report-collaboration): complete RC-BE-015–018 backend, eval suite, and MySQL sync

Ship report rewrite/version APIs, security budget and audit persistence, AgentScope worker wiring, and the 20-task quality eval harness so the frontend can integrate against a stable contract once enabled in config.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-09-06 17:32:15 +08:00
1 parent 814a44f0b9
commit 5e953c9fcb
123 files changed
+26816 -3505

No files matched your search

@@ -0,0 +1,127 @@
"""Frozen Pydantic contracts aligned with ``frontend-web/src/report-collaboration/api/types.ts``."""
from app.report_collaboration.contracts.agent_runs import AgentRun
from app.report_collaboration.contracts.artifacts import (
AngleAnalysis,
CitationEntry,
CollaborationArtifact,
CoverageMatrix,
EvidenceBundle,
EvidenceClaim,
ReportSectionDraft,
ReviewDecision,
ReviewIssue,
SynthesisOutline,
VerificationResult,
)
from app.report_collaboration.contracts.clarifications import ClarificationRecord
from app.report_collaboration.contracts.commands import CollaborationCommand, IntentDecision
from app.report_collaboration.contracts.enums import (
ALL_COLLABORATION_EVENT_TYPES,
AgentRunStatus,
ArtifactType,
ArtifactValidationStatus,
CollaborationEventType,
CollaborationMessageRole,
CollaborationNodeStatus,
CommandIntent,
CommandScope,
CommandStatus,
MessageVisibility,
ReportChangeType,
ReportCostLevel,
ReportPlanStatus,
ReportRunStatus,
ReportSessionStatus,
ReviewVerdict,
)
from app.report_collaboration.contracts.events import CollaborationEventEnvelope
from app.report_collaboration.contracts.ids import make_node_run_id, parse_node_run_id
from app.report_collaboration.contracts.messages import CollaborationMessage, CollaborationToolCall
from app.report_collaboration.contracts.node_machine import (
NODE_TRANSITIONS,
can_transition_node,
require_transition,
)
from app.report_collaboration.contracts.nodes import (
CollaborationNodeContract,
CollaborationNodeState,
NodeAttemptState,
NodeAwaitingInput,
NodeContractDetail,
)
from app.report_collaboration.contracts.plans import (
PlanEdge,
PlanNode,
PlanRole,
PlanValidation,
QualityGateSpec,
ReportPlanCandidate,
RoleDemand,
)
from app.report_collaboration.contracts.reports import ReportRewriteProposal, ReportSource, ReportVersion
from app.report_collaboration.contracts.requirements import ReportRequirementSnapshot
from app.report_collaboration.contracts.runs import ReportRun, ReportSession
from app.report_collaboration.contracts.snapshots import SessionSnapshot
__all__ = [
"ALL_COLLABORATION_EVENT_TYPES",
"AgentRun",
"AgentRunStatus",
"AngleAnalysis",
"ArtifactType",
"ArtifactValidationStatus",
"CitationEntry",
"ClarificationRecord",
"CollaborationArtifact",
"CollaborationCommand",
"CollaborationEventEnvelope",
"CollaborationEventType",
"CollaborationMessage",
"CollaborationMessageRole",
"CollaborationNodeContract",
"CollaborationNodeState",
"CollaborationNodeStatus",
"CollaborationToolCall",
"CommandIntent",
"CommandScope",
"CommandStatus",
"CoverageMatrix",
"EvidenceBundle",
"EvidenceClaim",
"IntentDecision",
"MessageVisibility",
"NODE_TRANSITIONS",
"NodeAttemptState",
"NodeAwaitingInput",
"NodeContractDetail",
"PlanEdge",
"PlanNode",
"PlanRole",
"PlanValidation",
"QualityGateSpec",
"ReportChangeType",
"ReportCostLevel",
"ReportPlanCandidate",
"ReportPlanStatus",
"ReportRequirementSnapshot",
"ReportRewriteProposal",
"ReportRun",
"ReportRunStatus",
"ReportSectionDraft",
"ReportSession",
"ReportSessionStatus",
"ReportSource",
"ReportVersion",
"ReviewDecision",
"ReviewIssue",
"ReviewVerdict",
"RoleDemand",
"SessionSnapshot",
"SynthesisOutline",
"VerificationResult",
"can_transition_node",
"make_node_run_id",
"parse_node_run_id",
"require_transition",
]
@@ -0,0 +1,21 @@
"""Parallel-stage member identity. Status is projected via ``session.snapshot``."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict
from app.report_collaboration.contracts.enums import AgentRunStatus
class AgentRun(BaseModel):
model_config = ConfigDict(extra="forbid")
agent_run_id: str
node_run_id: str | None = None
phase_id: str | None = None
role: str
display_name: str
avatar_key: str | None = None
status: AgentRunStatus
started_at: str | None = None
ended_at: str | None = None
@@ -0,0 +1,140 @@
"""Typed artifacts. Nodes complete only after a validated artifact is stored."""
from __future__ import annotations
from typing import Any, Literal
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import ArtifactType, ArtifactValidationStatus, ReviewVerdict
class CollaborationArtifact(BaseModel):
"""User-visible artifact card. ``summary`` never carries the body."""
model_config = ConfigDict(extra="forbid")
id: str
run_id: str
node_id: str
attempt: int
artifact_type: ArtifactType | str
schema_version: int = 1
validation_status: ArtifactValidationStatus
summary: str | None = None
created_at: str
class CitationEntry(BaseModel):
model_config = ConfigDict(extra="forbid")
source_id: str
url: str | None = None
document_id: str | None = None
title: str
published_at: str | None = None
retrieved_at: str | None = None
excerpt: str
credibility: float | None = Field(default=None, ge=0, le=1)
class EvidenceClaim(BaseModel):
model_config = ConfigDict(extra="forbid")
claim_id: str
text: str
kind: Literal["fact", "inference"] = "fact"
source_ids: list[str] = Field(default_factory=list)
excerpt: str | None = None
published_at: str | None = None
retrieved_at: str | None = None
scope: str | None = None
unit: str | None = None
credibility: float | None = Field(default=None, ge=0, le=1)
class EvidenceBundle(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
claims: list[EvidenceClaim] = Field(default_factory=list)
sources: list[CitationEntry] = Field(default_factory=list)
conflicts: list[str] = Field(default_factory=list)
coverage_gaps: list[str] = Field(default_factory=list)
class VerificationResult(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
claim_id: str
supporting_source_ids: list[str] = Field(default_factory=list)
opposing_source_ids: list[str] = Field(default_factory=list)
conflicts: list[str] = Field(default_factory=list)
freshness: str | None = None
independent_sources: bool = False
usable_conclusion: str
verdict: Literal["supported", "contested", "unsupported", "stale"] = "supported"
class AngleAnalysis(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
angle: str
thesis: str
evidence_ids: list[str] = Field(default_factory=list)
facts: list[str] = Field(default_factory=list)
inferences: list[str] = Field(default_factory=list)
assumptions: list[str] = Field(default_factory=list)
limitations: list[str] = Field(default_factory=list)
gaps: list[str] = Field(default_factory=list)
class SynthesisOutline(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
argument_spine: str
sections: list[dict[str, Any]] = Field(default_factory=list)
conclusions: list[str] = Field(default_factory=list)
evidence_allocation: dict[str, list[str]] = Field(default_factory=dict)
class ReportSectionDraft(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
section_id: str
title: str
markdown: str
evidence_ids: list[str] = Field(default_factory=list)
claim_citation_map: dict[str, list[str]] = Field(default_factory=dict)
class ReviewIssue(BaseModel):
model_config = ConfigDict(extra="forbid")
severity: str
target: str
requirement: str
evidence: str | None = None
class ReviewDecision(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
verdict: ReviewVerdict
issues: list[ReviewIssue] = Field(default_factory=list)
class CoverageMatrix(BaseModel):
model_config = ConfigDict(extra="forbid")
schema_version: int = 1
required_angles: list[str] = Field(default_factory=list)
covered_angles: list[str] = Field(default_factory=list)
required_questions: list[str] = Field(default_factory=list)
covered_questions: list[str] = Field(default_factory=list)
gaps: list[str] = Field(default_factory=list)
@@ -0,0 +1,15 @@
"""User-visible clarification records (pre-run and in-run)."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
class ClarificationRecord(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
questions: list[str] = Field(default_factory=list)
impact: list[str] = Field(default_factory=list)
resolved: bool = False
created_at: str
@@ -0,0 +1,46 @@
"""User commands and the intent-router decision object."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import CommandIntent, CommandScope, CommandStatus, ReportCostLevel
from app.report_collaboration.contracts.requirements import ReportRequirementSnapshot
class IntentDecision(BaseModel):
"""Pydantic-constrained output of IntentRouterAgent. It never dispatches work."""
model_config = ConfigDict(extra="forbid")
intent: CommandIntent
confidence: float = Field(ge=0, le=1)
normalized_instruction: str
scope: CommandScope
requested_target_ids: list[str] = Field(default_factory=list)
requirement_patch: ReportRequirementSnapshot | None = None
requires_confirmation: bool = False
cost_level: ReportCostLevel = "low"
reason: str
class CollaborationCommand(BaseModel):
model_config = ConfigDict(extra="forbid")
command_id: str
idempotency_key: str
text: str
intent: CommandIntent | None = None
confidence: float | None = Field(default=None, ge=0, le=1)
target_type: str | None = None
target_ids: list[str] = Field(default_factory=list)
normalized_instruction: str | None = None
requires_confirmation: bool = False
cost_level: ReportCostLevel | None = None
reason: str | None = None
impact_nodes: list[str] = Field(default_factory=list)
status: CommandStatus
expected_revision: int | None = None
error: str | None = None
created_at: str
updated_at: str | None = None
@@ -0,0 +1,199 @@
"""Shared enumerations. Names and values match the frontend frozen contract."""
from __future__ import annotations
from typing import Literal
ReportSessionStatus = Literal[
"empty",
"clarifying",
"planning",
"proposal_ready",
"running",
"awaiting_input",
"reviewing",
"completed",
"failed",
"cancelled",
]
CollaborationMessageRole = Literal["human", "ai", "tool"]
MessageVisibility = Literal["visible", "internal"]
ReportPlanStatus = Literal[
"proposed",
"selected",
"superseded",
"rejected",
"executing",
"completed",
]
ReportCostLevel = Literal["low", "medium", "high"]
CollaborationNodeStatus = Literal[
"planned",
"queued",
"running",
"validating",
"completed",
"failed",
"awaiting_input",
"cancel_requested",
"cancelled",
"superseded",
"reopened",
"interrupted",
]
AgentRunStatus = Literal[
"pending",
"running",
"waiting_input",
"completed",
"failed",
"cancelled",
]
ReportRunStatus = Literal[
"queued",
"planning",
"running",
"awaiting_input",
"reviewing",
"completed",
"failed",
"cancelled",
"recovering",
]
CommandIntent = Literal[
"answer_question",
"update_requirements",
"add_angle",
"research_again",
"reanalyze",
"rerun_node",
"rewrite_section",
"polish_report",
"ask_report",
"replan",
"cancel",
]
CommandStatus = Literal[
"pending",
"classified",
"confirmation_required",
"accepted",
"accepted_waiting_boundary",
"executing",
"completed",
"failed",
"cancelled",
"rejected",
]
CommandScope = Literal["conversation", "node", "artifact_lineage", "section", "plan"]
ArtifactValidationStatus = Literal["pending", "validated", "rejected", "superseded"]
ArtifactType = Literal[
"EvidenceBundle",
"VerificationResult",
"AngleAnalysis",
"SynthesisOutline",
"ReportSectionDraft",
"ReviewDecision",
"ReportVersion",
"CoverageMatrix",
]
ReportChangeType = Literal["initial", "section_rewrite", "polish", "restore", "revision"]
ReviewVerdict = Literal["pass", "revise"]
CollaborationEventType = Literal[
"session.snapshot",
"message.created",
"message.delta",
"message.completed",
"tool_call.created",
"tool_call.delta",
"tool_call.completed",
"tool_result.created",
"tool_result.delta",
"tool_result.completed",
"team_message.created",
"team_message.delta",
"team_message.completed",
"requirement.updated",
"clarification.requested",
"clarification.resolved",
"plan.progress",
"plan.proposed",
"plan.selected",
"run.status.changed",
"node.created",
"node.status.changed",
"node.progress",
"node.attempt.created",
"artifact.created",
"artifact.validated",
"artifact.rejected",
"source.added",
"command.classified",
"command.confirmation.required",
"command.accepted",
"command.completed",
"command.failed",
"command.cancelled",
"report.delta",
"report.version.created",
"review.created",
"error",
"heartbeat",
]
ALL_COLLABORATION_EVENT_TYPES: tuple[CollaborationEventType, ...] = (
"session.snapshot",
"message.created",
"message.delta",
"message.completed",
"tool_call.created",
"tool_call.delta",
"tool_call.completed",
"tool_result.created",
"tool_result.delta",
"tool_result.completed",
"team_message.created",
"team_message.delta",
"team_message.completed",
"requirement.updated",
"clarification.requested",
"clarification.resolved",
"plan.progress",
"plan.proposed",
"plan.selected",
"run.status.changed",
"node.created",
"node.status.changed",
"node.progress",
"node.attempt.created",
"artifact.created",
"artifact.validated",
"artifact.rejected",
"source.added",
"command.classified",
"command.confirmation.required",
"command.accepted",
"command.completed",
"command.failed",
"command.cancelled",
"report.delta",
"report.version.created",
"review.created",
"error",
"heartbeat",
)
@@ -0,0 +1,26 @@
"""SSE / replay envelope. Wire names are camelCase; payloads stay snake_case."""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import CollaborationEventType
class CollaborationEventEnvelope(BaseModel):
"""Durable event envelope consumed by the frontend reducer."""
model_config = ConfigDict(extra="forbid", populate_by_name=True)
event_id: str = Field(alias="eventId")
session_id: str = Field(alias="sessionId")
run_id: str | None = Field(default=None, alias="runId")
seq: int = Field(ge=1)
type: CollaborationEventType
timestamp: str
data: dict[str, Any] = Field(default_factory=dict)
def to_sse_dict(self) -> dict[str, Any]:
return self.model_dump(by_alias=True, exclude_none=False)
@@ -0,0 +1,26 @@
"""Stable identifiers shared with the frontend canvas and SSE payloads."""
from __future__ import annotations
import re
_NODE_RUN_ID_RE = re.compile(r"^(?P<node_id>.+)-attempt(?P<attempt>\d+)$")
def make_node_run_id(node_id: str, attempt: int) -> str:
"""Return ``${node_id}-attempt{attempt}``. Random UUIDs are forbidden."""
if not node_id or node_id.strip() != node_id:
raise ValueError("node_id must be a non-empty trimmed string")
if attempt < 1:
raise ValueError("attempt must be >= 1")
return f"{node_id}-attempt{attempt}"
def parse_node_run_id(node_run_id: str) -> tuple[str, int]:
"""Split a canonical node_run_id back into ``(node_id, attempt)``."""
match = _NODE_RUN_ID_RE.match(node_run_id or "")
if match is None:
raise ValueError(f"invalid node_run_id: {node_run_id!r}")
return match.group("node_id"), int(match.group("attempt"))
@@ -0,0 +1,36 @@
"""Conversation-replica message rows (snake_case wire fields)."""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import CollaborationMessageRole, MessageVisibility
class CollaborationToolCall(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
name: str
args: str | dict[str, Any]
class CollaborationMessage(BaseModel):
model_config = ConfigDict(extra="forbid")
message_id: str
role: CollaborationMessageRole
content: str = ""
name: str | None = None
tool_calls: list[CollaborationToolCall] = Field(default_factory=list)
tool_call_id: str | None = None
agent_run_id: str | None = None
node_run_id: str | None = None
phase_id: str | None = None
visibility: MessageVisibility = "visible"
metadata: dict[str, Any] | None = None
command_id: str | None = None
created_at: str
completed_at: str | None = None
@@ -0,0 +1,54 @@
"""Node status machine. Transitions must match the frontend reducer exactly."""
from __future__ import annotations
from app.report_collaboration.contracts.enums import CollaborationNodeStatus
NODE_TRANSITIONS: dict[CollaborationNodeStatus, tuple[CollaborationNodeStatus, ...]] = {
"planned": ("queued", "running", "superseded", "cancelled"),
"queued": ("running", "cancel_requested", "cancelled", "superseded", "interrupted"),
"running": (
"validating",
"awaiting_input",
"cancel_requested",
"failed",
"superseded",
"interrupted",
),
"validating": ("completed", "failed", "superseded"),
"awaiting_input": ("queued", "cancel_requested", "cancelled", "superseded"),
"cancel_requested": ("cancelled",),
"cancelled": (),
"completed": ("reopened", "superseded"),
"reopened": ("queued", "superseded"),
"failed": ("queued", "reopened", "superseded"),
"interrupted": ("queued", "reopened", "superseded"),
"superseded": (),
}
TERMINAL_NODE_STATUSES: frozenset[CollaborationNodeStatus] = frozenset({"cancelled", "superseded"})
class IllegalNodeTransition(ValueError):
"""Raised when a caller attempts a status change the machine forbids."""
def can_transition_node(from_status: CollaborationNodeStatus | None, to_status: CollaborationNodeStatus) -> bool:
"""Return whether ``from_status -> to_status`` is legal.
A missing or ``planned`` source is treated as the bootstrap start so the
first durable snapshot can land a node in any later state.
"""
if from_status is None or from_status == "planned":
return True
if from_status == to_status:
return False
return to_status in NODE_TRANSITIONS.get(from_status, ())
def require_transition(from_status: CollaborationNodeStatus, to_status: CollaborationNodeStatus) -> None:
"""Raise ``IllegalNodeTransition`` unless the move is allowed."""
if not can_transition_node(from_status, to_status):
raise IllegalNodeTransition(f"illegal node transition: {from_status} -> {to_status}")
@@ -0,0 +1,87 @@
"""Node contracts and live node state. The public contract endpoint never returns execution bodies."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import CollaborationNodeStatus
class NodeAwaitingInput(BaseModel):
model_config = ConfigDict(extra="forbid")
reason: str
question: str
impact: list[str] = Field(default_factory=list)
class NodeAttemptState(BaseModel):
model_config = ConfigDict(extra="forbid")
attempt: int
status: CollaborationNodeStatus
started_at: str | None = None
ended_at: str | None = None
error: str | None = None
class CollaborationNodeState(BaseModel):
model_config = ConfigDict(extra="forbid")
node_id: str
label: str
role_display_name: str | None = None
angle: str | None = None
status: CollaborationNodeStatus
attempt: int
progress: str | None = None
awaiting_input: NodeAwaitingInput | None = None
error: str | None = None
attempts: list[NodeAttemptState] = Field(default_factory=list)
class CollaborationNodeContract(BaseModel):
"""Internal full contract stored on a node-run row."""
model_config = ConfigDict(extra="forbid")
node_id: str
mission: str
input_artifact_types: list[str] = Field(default_factory=list)
output_artifact_type: str
allowed_tools: list[str] = Field(default_factory=list)
source_policy: str | None = None
acceptance_criteria: list[str] = Field(default_factory=list)
max_attempts: int = 3
time_budget_seconds: int | None = None
token_budget: int | None = None
agent_profile_snapshot: dict[str, object] = Field(default_factory=dict)
dependencies: list[str] = Field(default_factory=list)
forbidden: list[str] = Field(default_factory=list)
output_structure: str | None = None
class NodeContractDetail(BaseModel):
"""``GET /runs/{run_id}/nodes/{node_id}/contract`` — duties only, never result text."""
model_config = ConfigDict(extra="forbid")
node_id: str
label: str
role: str | None = None
angle: str | None = None
status: CollaborationNodeStatus
attempt: int
mission: str
input_artifact_types: list[str] = Field(default_factory=list)
source_policy: str | None = None
output_artifact_type: str
output_structure: str | None = None
acceptance_criteria: list[str] = Field(default_factory=list)
allowed_tools: list[str] = Field(default_factory=list)
forbidden: list[str] = Field(default_factory=list)
time_budget_seconds: int | None = None
token_budget: int | None = None
max_attempts: int
upstream: list[str] = Field(default_factory=list)
downstream: list[str] = Field(default_factory=list)
@@ -0,0 +1,94 @@
"""Candidate plans. Models emit RoleDemand; the server binds real agents."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import ReportCostLevel, ReportPlanStatus
class PlanRole(BaseModel):
model_config = ConfigDict(extra="forbid")
key: str
display_name: str
responsibility: str
angle: str | None = None
class QualityGateSpec(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
label: str
description: str | None = None
class PlanValidation(BaseModel):
model_config = ConfigDict(extra="forbid")
ok: bool
errors: list[str] = Field(default_factory=list)
class PlanNode(BaseModel):
"""User-visible node summary. Execution bodies never travel on this type."""
model_config = ConfigDict(extra="forbid")
id: str
label: str
role_key: str | None = None
role_display_name: str | None = None
angle: str | None = None
depends_on: list[str] = Field(default_factory=list)
mission: str | None = None
output_artifact_type: str | None = None
input_artifact_types: list[str] = Field(default_factory=list)
allowed_tools: list[str] = Field(default_factory=list)
acceptance_criteria: list[str] = Field(default_factory=list)
class PlanEdge(BaseModel):
model_config = ConfigDict(extra="forbid")
source: str
target: str
label: str | None = None
class RoleDemand(BaseModel):
"""Planner output before the assembler binds catalog agents and budgets."""
model_config = ConfigDict(extra="forbid")
role_key: str
display_name: str
angle: str | None = None
mission: str
depends_on_roles: list[str] = Field(default_factory=list)
output_artifact_type: str
suggested_tools: list[str] = Field(default_factory=list)
class ReportPlanCandidate(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
proposal_group_id: str
title: str
strategy: str
summary: str
rationale: str
recommended: bool = False
estimated_duration_seconds: int
estimated_cost_level: ReportCostLevel
requirement_revision: int
roles: list[PlanRole] = Field(default_factory=list)
nodes: list[PlanNode] = Field(default_factory=list)
edges: list[PlanEdge] = Field(default_factory=list)
quality_gates: list[QualityGateSpec] = Field(default_factory=list)
report_structure_id: str | None = None
validation: PlanValidation
revision: int
status: ReportPlanStatus
@@ -0,0 +1,47 @@
"""Report versions, rewrite candidates and user-visible sources."""
from __future__ import annotations
from typing import Literal
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import ReportChangeType
class ReportSource(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
url: str | None = None
title: str
published_at: str | None = None
added_at: str
agent_run_id: str | None = None
class ReportVersion(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
session_id: str
version: int
parent_version_id: str | None = None
change_type: ReportChangeType
change_summary: str | None = None
markdown: str
source_index: list[ReportSource] = Field(default_factory=list)
created_at: str
is_head: bool = False
class ReportRewriteProposal(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
session_id: str
section: str | None = None
instruction: str
status: Literal["proposed", "applied", "dismissed"]
markdown: str | None = None
created_at: str
@@ -0,0 +1,25 @@
"""Requirement snapshot. A scope-changing user reply must bump ``revision``."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
class ReportRequirementSnapshot(BaseModel):
model_config = ConfigDict(extra="forbid")
topic: str
objective: str | None = None
audience: str | None = None
language: str | None = None
time_range: str | None = None
geography: str | None = None
required_angles: list[str] = Field(default_factory=list)
excluded_angles: list[str] = Field(default_factory=list)
source_constraints: str | None = None
report_structure_id: str | None = None
length_target: str | None = None
tone: str | None = None
deadline_hint: str | None = None
quality_priority: str | None = None
revision: int = Field(ge=1)
@@ -0,0 +1,39 @@
"""Session and run records returned by ``GET /sessions/{id}``."""
from __future__ import annotations
from typing import Any
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.enums import ReportRunStatus, ReportSessionStatus
class ReportSession(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
title: str
status: ReportSessionStatus
requirement_revision: int
selected_plan_id: str | None = None
active_run_id: str | None = None
current_report_version_id: str | None = None
created_at: str
updated_at: str
class ReportRun(BaseModel):
model_config = ConfigDict(extra="forbid")
id: str
session_id: str
plan_id: str
status: ReportRunStatus
cancel_requested: bool = False
next_event_seq: int = 0
current_phase: str | None = None
usage: dict[str, Any] = Field(default_factory=dict)
budget_exhausted_reason: str | None = None
created_at: str
updated_at: str
@@ -0,0 +1,27 @@
"""``GET /sessions/{id}`` snapshot — the frontend's only fact source before SSE."""
from __future__ import annotations
from pydantic import BaseModel, ConfigDict, Field
from app.report_collaboration.contracts.agent_runs import AgentRun
from app.report_collaboration.contracts.commands import CollaborationCommand
from app.report_collaboration.contracts.messages import CollaborationMessage
from app.report_collaboration.contracts.nodes import CollaborationNodeState
from app.report_collaboration.contracts.plans import ReportPlanCandidate
from app.report_collaboration.contracts.reports import ReportVersion
from app.report_collaboration.contracts.runs import ReportRun, ReportSession
class SessionSnapshot(BaseModel):
model_config = ConfigDict(extra="forbid")
session: ReportSession
messages: list[CollaborationMessage] = Field(default_factory=list)
plans: list[ReportPlanCandidate] = Field(default_factory=list)
run: ReportRun | None = None
nodes: list[CollaborationNodeState] = Field(default_factory=list)
agent_runs: list[AgentRun] = Field(default_factory=list)
commands: list[CollaborationCommand] = Field(default_factory=list)
report_versions: list[ReportVersion] = Field(default_factory=list)
last_seq: int = 0