Schema Models¶

akms.schema.models ¶

Pydantic models for all AKMS v2 schemas.

Frozen specification — any change requires a version bump and migration script.

StructuralEdge ¶

Bases: BaseModel

An edge in the knowledge graph (from node frontmatter).

GlobalNodeFrontmatter ¶

Bases: BaseModel

Schema for global knowledge node YAML frontmatter (§1 of spec).

LocalNodeFrontmatter ¶

Bases: GlobalNodeFrontmatter

Schema for local knowledge node frontmatter (§1a of spec).

Same as global but with additional constraints: - source must be 'agent' or 'human' (not 'generated') - status must be 'tentative' when source is 'agent'

CodeMirrorNodeFrontmatter ¶

Bases: BaseModel

Schema for code-mirror node frontmatter (§6 of spec).

Existence markers only — no tags, no edges, confidence always 1.0.

NodeStateOverride ¶

Bases: BaseModel

Per-node experiential state in local_state.yaml.

LocalEdge ¶

Bases: BaseModel

A repo-local edge (typically pitfall edges).

SessionNodeEntry ¶

Bases: BaseModel

A session node registered in local_state.yaml.

LocalStateOverlay ¶

Bases: BaseModel

Schema for local_state.yaml (§2 of spec).

NodeUsedFeedback ¶

Bases: BaseModel

Feedback on a node used during a task.

NodeMissingEntry ¶

Bases: BaseModel

A node that was needed but didn't exist.

LessonFailed ¶

Bases: BaseModel

A failed approach with explanation.

Lessons ¶

Bases: BaseModel

Lessons learned from a task.

PitfallDiscovered ¶

Bases: BaseModel

A pitfall discovered during task execution.

NewKnowledge ¶

Bases: BaseModel

New knowledge proposed by an agent.

AgentMemory ¶

Bases: BaseModel

Schema for per-task AgentMemory (§3 of spec).

ReviewBreakdown ¶

Bases: BaseModel

Review severity breakdown.

PCDTaskSummary ¶

Bases: BaseModel

Per-task summary within a PCD.

OverallTestStatus ¶

Bases: BaseModel

Aggregate test status for a phase.

PCD ¶

Bases: BaseModel

Schema for Phase Completion Document (§3a of spec).

Split into ephemeral zone (for orchestrator + next agent) and persistent zone (for AKMS graph updates).

extract_persistent_zone ¶

extract_persistent_zone() -> dict

Extract the persistent zone fields for update_graph.py consumption.

Source code in packages/akms/src/akms/schema/models.py

def extract_persistent_zone(self) -> dict:
    """Extract the persistent zone fields for update_graph.py consumption."""
    return {
        "nodes_used": [n.model_dump() for n in self.nodes_used],
        "nodes_missing": [n.model_dump() for n in self.nodes_missing],
        "lessons": self.lessons.model_dump(),
        "pitfalls_discovered": [p.model_dump() for p in self.pitfalls_discovered],
        "new_knowledge": [k.model_dump() for k in self.new_knowledge],
    }

extract_ephemeral_zone ¶

extract_ephemeral_zone() -> dict

Extract the ephemeral zone fields for next-phase agent consumption.

Source code in packages/akms/src/akms/schema/models.py

def extract_ephemeral_zone(self) -> dict:
    """Extract the ephemeral zone fields for next-phase agent consumption."""
    return {
        "tasks": [t.model_dump() for t in self.tasks],
        "overall_test_status": (
            self.overall_test_status.model_dump()
            if self.overall_test_status
            else None
        ),
        "files_created": [f.model_dump() for f in self.files_created],
        "files_modified": [f.model_dump() for f in self.files_modified],
        "files_deleted": [f.model_dump() for f in self.files_deleted],
        "interfaces_added": [i.model_dump() for i in self.interfaces_added],
        "assumptions": [a.model_dump() for a in self.assumptions],
        "known_issues": self.known_issues.model_dump(),
        "next_phase_warnings": self.next_phase_warnings,
        "recommended_start": self.recommended_start,
    }

TaskJSONAKMS ¶

Bases: BaseModel

AKMS-specific fields added to task JSON (§4 of spec).

LoadoutHeader ¶

Bases: BaseModel

Schema for loadout file YAML frontmatter (§5 of spec).

ModelRoutingEntry ¶

Bases: BaseModel

Provider + model pair for a single LLM call type.

ModelRoutingConfig ¶

Bases: BaseModel

Routing config for AKMS internal LLM calls (dedup, drift).

NOT for subagent model selection — subagents use agent_configs.py.

MirrorConfig ¶

Bases: BaseModel

Optional code-mirror provider configuration (A2-4).

Additive on :class:PropagationConfig. Defaults preserve the legacy in-process Python AST generator. External providers (repo2md) are selected by name; fallback to legacy is never silent.

PropagationConfig ¶

Bases: BaseModel

Schema for propagation_config.yaml (§7 of spec).