How anh-08/penumbra works
Penumbra is a satellite mission-operations simulator: an incident produces telemetry and alerts, an AI agent diagnoses and proposes recovery plans, physics checks plans across plausible faults, and flight rules or an operator authorize execution. The API streams the evolving fleet state and decision trace to an interactive operations UI. The graph retains documented orbit, voice, anatomy, Monte Carlo, replay, and scheduling capabilities. Some subsystem links are documented in the README rather than visible in sampled implementation; those are marked accordingly.
Main entry points: dispatcher.py Tool Dispatcher · app.py FastAPI and WebSocket · scenarios.py Incident Scenarios · session.py Recorded Agent Run
Components 25
Orbit and Simulation
- Incident Scenarios
backend/fleet/scenarios.py - Orbit Environment
backend/orbit/eclipse.py - Power Simulation
backend/eps/truth.py - Fault Models
backend/eps/faults.py
Fleet Operations
- Detection and Triage
backend/fleet/detect.py - Fleet Backend
backend/fleet/backend.py - Uplink Scheduler
backend/sched/scheduler.py - Flight Rules and Approval
backend/fleet/flight_rules.py
Agent and Verification
- Agent Loop
backend/agent/loop.py - Tool Dispatcher
backend/agent/dispatcher.py - Gemini Model
backend/agent/gemini.py - Safety Checks
backend/agent/safety.py - Plan Model
backend/eps/planning.py - Monte Carlo Verifier
backend/verify/verifier.py - Hypothesis Scoring
backend/verify/scoring.py
API and Flight Records
- Flight Recorder and Replay
backend/recorder/flight.py - Recorded Agent Run
backend/agent/session.py - FastAPI and WebSocket
backend/api/app.py - Fault-Storm Director
backend/api/storm.py - Voice Commands
backend/api/voice_command.py
Operator Interface
- Operations Dashboard
frontend/src/App.jsx - Plan Matrix
frontend/src/Matrix.jsx - Satellite Anatomy
frontend/src/anatomy/AnatomyView.jsx - Monte Carlo View
frontend/src/montecarlo/MonteCarloOverlay.jsx
Other components
- Mission Operator
Connections 30
- Mission Operator → FastAPI and WebSocket: starts incident
README.md - FastAPI and WebSocket → Incident Scenarios: creates scenario
backend/api/app.py - Incident Scenarios → Orbit Environment: builds environment
backend/fleet/scenarios.py - Incident Scenarios → Power Simulation: initializes world
backend/fleet/scenarios.py - Incident Scenarios → Fault Models: supplies faults
backend/fleet/scenarios.py - Power Simulation → Fleet Backend: provides telemetry
- Fleet Backend → Detection and Triage: supports triage
- Detection and Triage → Agent Loop: initiates diagnosis
README.md - Agent Loop → Gemini Model: queries model
backend/agent/loop.py - Agent Loop → Tool Dispatcher: dispatches tools
backend/agent/loop.py - Tool Dispatcher → Safety Checks: checks actions
backend/agent/dispatcher.py - Tool Dispatcher → Hypothesis Scoring: scores causes
backend/agent/dispatcher.py - Tool Dispatcher → Plan Model: builds plans
backend/agent/dispatcher.py - Tool Dispatcher → Monte Carlo Verifier: simulates plans
- Monte Carlo Verifier → Plan Model: evaluates plans
backend/verify/verifier.py - Tool Dispatcher → Uplink Scheduler: books uplinks
README.md - Tool Dispatcher → Flight Rules and Approval: requests approval
- Mission Operator → Flight Rules and Approval: approves plan
README.md - Recorded Agent Run → Agent Loop: runs agent
backend/agent/session.py - Recorded Agent Run → Tool Dispatcher: provides dispatcher
backend/agent/session.py - Recorded Agent Run → Flight Recorder and Replay: records events
backend/agent/session.py - FastAPI and WebSocket → Fault-Storm Director: starts storm
backend/api/app.py - Fault-Storm Director → Recorded Agent Run: runs agent
backend/api/storm.py - FastAPI and WebSocket → Voice Commands: handles voice request
backend/api/app.py - Voice Commands → Incident Scenarios: resolves incident
backend/api/voice_command.py - FastAPI and WebSocket → Operations Dashboard: streams fleet state
README.md - Operations Dashboard → Plan Matrix: renders plans
frontend/src/App.jsx - Operations Dashboard → Satellite Anatomy: renders anatomy
frontend/src/App.jsx - Operations Dashboard → Monte Carlo View: shows simulations
frontend/src/App.jsx - Flight Recorder and Replay → Recorded Agent Run: replays runs
backend/recorder/flight.py