How aqua32a7/sunkguard works
SunkGuard admits and schedules multi-step AI workflows against contended resource capacity, aiming to protect near-complete work from late failure. The principal path is workflow registration, step-admission scoring and resource allocation, execution/usage reporting, then monitoring through the API and dashboard; the Python SDK can initiate the same control-plane operations. The README documents simulation, policy modes, reservations, analytics, demos and Gemini support. Links among engine internals are based on the documented architecture; sampled excerpts do not expose every runtime call. Authentication and offline reconciliation are shown as distinct supporting capabilities.
Main entry points: server.py FastAPI endpoints · runtime.py Control runtime · App.tsx Dashboard application · controller.py Admission controller
Components 26
Admission engine
- Workflow state
core/workflow.py - Admission controller
core/controller.py - Failure predictor
core/predictor.py - Resource accounting
core/resources.py - Deterministic simulation
core/sim.py - Metrics and events
core/metrics.py
API control plane
- FastAPI endpoints
server.py - Control runtime
core/runtime.py
SDK integrations
- Python SDK client
sdk/client.py - Reservation decorators
sdk/decorator.py - Gemini adapter
core/gemini_adapter.py
Operations dashboard
- Dashboard application
src/App.tsx - Workflow and resource views
src/pages/OperationsPages.tsx - Frontend API service
src/services/api.ts - Static demo data
src/services/staticDemoData.ts
Identity and resilience
- Frontend auth
src/services/supabaseAuth.ts - Supabase client
src/services/supabaseClient.ts - OTP and session manager
core/auth.py - Email delivery
core/email_service.py - Auth database
core/auth_db.py - Connectivity monitor
core/connectivity.py - Offline journal
core/offline_journal.py - Offline reconciler
core/reconciler.py
Other components
- Workflow engineer
- Gemini API
- Supabase auth
Connections 31
- Workflow engineer → Reservation decorators: wraps workflow steps
- Workflow engineer → Python SDK client: registers workflow
- Reservation decorators → Python SDK client: requests reservations
- Python SDK client → FastAPI endpoints: sends REST requests
- Workflow engineer → Dashboard application: monitors operations
- Dashboard application → Frontend API service: loads and updates
- Frontend API service → FastAPI endpoints: calls endpoints
- Dashboard application → Workflow and resource views: renders routes
- Dashboard application → Static demo data: loads demo state
- FastAPI endpoints → Control runtime: dispatches requests
- Control runtime → Workflow state: tracks workflow state
- Control runtime → Admission controller: requests admission
- Admission controller → Failure predictor: estimates failure risk
- Admission controller → Resource accounting: checks and reserves capacity
- Control runtime → Resource accounting: accounts usage
- Control runtime → Deterministic simulation: runs scenarios
- Control runtime → Metrics and events: aggregates measurements
- FastAPI endpoints → Gemini adapter: invokes adapter
- Gemini adapter → Gemini API: sends model requests
- Dashboard application → Frontend auth: handles sign-in
- Frontend auth → Supabase client: uses configured client
- Supabase client → Supabase auth: authenticates
- Frontend auth → FastAPI endpoints: uses local OTP fallback
- FastAPI endpoints → OTP and session manager: handles OTP requests
- OTP and session manager → Email delivery: delivers verification code
- OTP and session manager → Auth database: reads and writes accounts
- FastAPI endpoints → Connectivity monitor: reports connectivity
- Connectivity monitor → Offline journal: records offline events
- FastAPI endpoints → Offline reconciler: triggers reconciliation
- Offline reconciler → Offline journal: reads pending events
- Offline reconciler → Control runtime: replays updates