A local-first, deterministic state management engine for live church presentation systems. Uses hybrid triggers (hot-word detection + manual overrides) to seamlessly transition between presentation modes (Lyrics, Bible, Idle).
- Pattern: Finite State Machine (FSM) with strict type validation
- Latency Target: <500ms for hot-word processing
- Matching: Fuzzy matching using Levenshtein distance (threshold: 0.85)
- Data Integrity: All outputs validated against Pydantic schemas
.
├── orchestrator_schema.py # Pydantic data models
├── state_machine_def.json # FSM configuration
├── orchestration_engine.py # Core engine implementation
├── verify_engine.py # Verification test suite
├── requirements.txt # Python dependencies
└── README.md # This file
This project uses uv for dependency management:
# Create virtual environment (if not already created)
uv venv
# Install dependencies
uv syncuv run verify_engine.pyThis will:
- Initialize the engine in IDLE state
- Test fuzzy matching ("Let us sing" → LYRICS)
- Test exact matching ("Turn your bibles to" → BIBLE)
- Test no-match behavior ("Hot dog" → no transition)
- Generate
transition_log.jsonwith all state transitions
from orchestration_engine import OrchestrationEngine
from orchestrator_schema import ServiceState
# Initialize engine
engine = OrchestrationEngine()
# Hot-word trigger (fuzzy match)
event = engine.transition("Let us sing")
print(event.to_state) # ServiceState.LYRICS
# Manual override
event = engine.transition("", trigger_source="manual", manual_state=ServiceState.IDLE)
print(event.to_state) # ServiceState.IDLE- IDLE: Default state, clear screen
- LYRICS: Display song lyrics
- BIBLE: Display scripture
- "Let's sing", "Worship with me", "Join me and sing" → LYRICS
- "Open your Bibles", "Turn to", "Let's read" → BIBLE
- "Thank you everyone" → IDLE
- IDLE → [LYRICS, BIBLE]
- LYRICS → [IDLE, BIBLE, LYRICS]
- BIBLE → [IDLE, LYRICS, BIBLE]
- Engine initializes in IDLE state
- Fuzzy match "Let us sing" → LYRICS
- Exact match "Turn your bibles to" → BIBLE
- No-match "Hot dog" → no transition
- JSON payload logging with confidence scores
- Integrate with audio input (Vosk/Porcupine for local speech recognition)
- Build renderer (React/Flutter UI) to consume state events
- Add telemetry for latency monitoring
- Implement phonetic matching for accent variations