USD Substrate

Python state engine for the Cognitive Orchestrator platform.

Installation

pip install usd-substrate

Usage

from datetime import datetime
from usd_substrate import (
    JsonInterchangeReader,
    JsonInterchangeWriter,
    SessionState,
    ActiveMode,
    Paradigm,
    EnergyLevel,
    BurnoutLevel,
    MomentumPhase,
    AgentType,
)

# Create a session state
state = SessionState(
    session_id="my-session",
    timestamp=datetime.now().isoformat(),
    active_mode=ActiveMode.FOCUSED,
    active_paradigm=Paradigm.CORTEX,
    energy_level=EnergyLevel.MEDIUM,
    burnout_level=BurnoutLevel.GREEN,
    momentum_phase=MomentumPhase.BUILDING,
    session_start_goal="Complete the project",
)

# Write to file
writer = JsonInterchangeWriter()
doc = writer.create_session_state_document(state)
writer.write_to_file(doc, "cognitive_state.json")

# Read from file
reader = JsonInterchangeReader()
loaded = reader.read_from_file("cognitive_state.json")
session = reader.extract_session_state(loaded)

# Create a cross-agent handoff
arc_doc = writer.create_mycelium_arc(
    session_state=state,
    source_agent=AgentType.CLAUDE_CODE,
    target_agent=AgentType.GEMINI_CLI,
    resume_summary="Working on implementation",
)

Features

• Pydantic Models: Full type validation
• Checksum Verification: Document integrity
• Safety Constraints: RED burnout protection
• Cross-Agent Handoffs: Mycelium Arc protocol

License

MIT