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:
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
|
||||
Reference in new issue
Block a user