Skip to content

agent_k.mission.state

Mission state models for the state machine.

agent_k.mission.state

Mission state for pydantic-graph.

@notice: | Mission state for pydantic-graph.

@dev: | See module for implementation details and extension points.

@graph: id: agent_k.mission.state provides: - agent_k.mission.state:MissionState - agent_k.mission.state:MissionResult - agent_k.mission.state:GraphContext pattern: mission-state

@similar: - id: agent_k.mission.nodes when: "Nodes drive phase transitions; this module holds state."

@agent-guidance: do: - "Use agent_k.mission.state as the canonical home for this capability." do_not: - "Create parallel modules without updating @similar or @graph."

@human-review: last-verified: 2026-01-26 owners: - agent-k-core

(c) Mike Casale 2025. Licensed under the MIT License.

MissionState

Bases: BaseModel

State flowing through the mission graph.

@pattern: name: mission-state rationale: "Single source of truth for mission progression." violations: "Phase-specific state stored elsewhere causes drift."

@concurrency: model: asyncio safe: false reason: "Mutable state shared across graph nodes."

@invariants: - "current_phase reflects the latest active phase." - "phases_completed is append-only."

Source code in agent_k/mission/state.py 
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class MissionState(BaseModel):
    """State flowing through the mission graph.

    @pattern:
        name: mission-state
        rationale: "Single source of truth for mission progression."
        violations: "Phase-specific state stored elsewhere causes drift."

    @concurrency:
        model: asyncio
        safe: false
        reason: "Mutable state shared across graph nodes."

    @invariants:
        - "current_phase reflects the latest active phase."
        - "phases_completed is append-only."
    """

    model_config = ConfigDict(validate_assignment=True, arbitrary_types_allowed=True)
    schema_version: str = Field(default=SCHEMA_VERSION, description="Schema version")
    mission_id: MissionId = Field(description="Unique mission identifier")
    competition_id: CompetitionId | None = Field(default=None, description="Selected competition id")
    criteria: MissionCriteria = Field(default_factory=MissionCriteria, description="Mission selection criteria")
    current_phase: MissionPhase = Field(default="discovery", description="Current mission phase")
    phases_completed: list[MissionPhase] = Field(default_factory=list, description="Completed phases")
    discovered_competitions: list[Competition] = Field(
        default_factory=list, description="Competitions found during discovery"
    )
    selected_competition: Competition | None = Field(default=None, description="Competition selected for execution")
    research_findings: ResearchFindings | None = Field(
        default=None, description="Research findings from scientist phase"
    )
    prototype_code: str | None = Field(default=None, description="Prototype solution code")
    prototype_score: float | None = Field(default=None, description="Prototype evaluation score")
    evolution_state: EvolutionState | None = Field(default=None, description="Evolution phase state")
    final_submission_id: str | None = Field(default=None, description="Final submission identifier")
    final_score: float | None = Field(default=None, description="Final leaderboard score")
    final_rank: int | None = Field(default=None, description="Final leaderboard rank")
    errors: list[dict[str, Any]] = Field(default_factory=list, description="Collected error details")
    started_at: datetime = Field(default_factory=lambda: datetime.now(UTC), description="Mission start time")
    phase_started_at: datetime | None = Field(default=None, description="Current phase start time")
    memory: MemoryState = Field(default_factory=MemoryState, description="Mission memory state")
    phases: list[PhasePlan] = Field(default_factory=list, description="Phase plans for UI display")
    current_task_id: TaskId | None = Field(default=None, description="Current task identifier")
    overall_progress: float = Field(default=0.0, ge=0.0, le=100.0, description="Overall mission progress (percentage)")

MissionResult

Bases: BaseModel

Final result of mission execution.

@pattern: name: output-model rationale: "Stable schema for mission results." violations: "Ad-hoc outputs hinder UI/reporting."

Source code in agent_k/mission/state.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
class MissionResult(BaseModel):
    """Final result of mission execution.

    @pattern:
        name: output-model
        rationale: "Stable schema for mission results."
        violations: "Ad-hoc outputs hinder UI/reporting."
    """

    model_config = ConfigDict(frozen=True)
    schema_version: str = Field(default=SCHEMA_VERSION, description="Schema version")
    success: bool = Field(..., description="Whether mission completed successfully")
    mission_id: MissionId = Field(..., description="Mission identifier")
    competition_id: CompetitionId | None = Field(default=None, description="Competition identifier")
    final_rank: int | None = Field(default=None, description="Final leaderboard rank")
    final_score: float | None = Field(default=None, description="Final leaderboard score")
    total_submissions: int = Field(default=0, description="Number of submissions made")
    evolution_generations: int = Field(default=0, description="Evolution generations completed")
    duration_ms: int = Field(default=0, description="Mission duration in milliseconds")
    phases_completed: list[MissionPhase] = Field(default_factory=list, description="Phases completed during mission")
    error_message: str | None = Field(default=None, description="Error message when mission fails")

GraphContext dataclass

Context passed to graph execution.

@pattern: name: dependency-container rationale: "Bundles runtime services for graph execution." violations: "Hidden globals make graph runs brittle."

Source code in agent_k/mission/state.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
142
@dataclass(slots=True)
class GraphContext:
    """Context passed to graph execution.

    @pattern:
        name: dependency-container
        rationale: "Bundles runtime services for graph execution."
        violations: "Hidden globals make graph runs brittle."
    """

    event_emitter: EventEmitter | None = None
    http_client: httpx.AsyncClient | None = None
    platform_adapter: PlatformAdapter | None = None
    agents: dict[str, Agent[Any, Any]] | None = None