Programmatic APIs
The Digital Twin exposes one orchestration layer and multiple transports. The Python service API is the source of truth. The HTTP API, desktop automation API, and MCP server sit on top of it.
Python service API
python/backend/service_api.py exposes the main programmatic workflows: status/config, precision, optimisation, simulations, diagnostics, phasors, sessions, and instrument-profile creation helpers.
The service layer is the source of truth for all other transports. The desktop, HTTP API, and MCP server should all be documented in terms of DigitalTwinService.
The precision workflow always returns x_range, ideal, and raw detector-limited theory. When dead-time correction is enabled, it also returns a deadtime_correction companion block with the selected method, corrected theory arrays, and a summary note. When Monte Carlo validation is enabled, the top-level monte_carlo payload remains the raw detector-limited baseline and any corrected companion statistics are nested under monte_carlo.deadtime_correction.
HTTP API
The FastAPI app in python/backend/main.py mirrors the service layer. It is intended for remote scripting, dashboards, or external orchestration.
| Endpoint | Method | Meaning |
|---|---|---|
/api/v1/backend/status | GET | Readiness and effective-mode summary. |
/api/v1/backend/config | GET / POST | Read or patch active configuration. |
/api/v1/backend/gui/schema | GET | Declarative description of the controller/workspace. |
/api/v1/workflows/simulate/basic | POST | Basic synthetic dataset and fit. |
/api/v1/workflows/simulate/advanced | POST | Advanced synthetic dataset and fit. |
/api/v1/workflows/precision | POST | Precision analysis with ideal, raw theory, optional corrected companion theory, and optional Monte Carlo validation. |
/api/v1/workflows/optimisation | POST | Integrated optimisation workflow. |
/api/v1/data/summary | GET | Map availability and warnings. |
/api/v1/data/results | GET | Current result snapshot. |
/api/v1/data/tau-map | GET | Lifetime map only. |
/api/v1/data/phasor | GET | Phasor map for a selected harmonic. |
/api/v1/data/pixel/{y}/{x} | GET | Per-pixel decay and fit payload. |
/api/v1/data/diagnostics | GET | Time vector, gates, excitation profile, and reference PDF. |
/api/v1/theory/locus | GET | Theoretical phasor loci. |
/api/v1/session/save/{session_id} | POST | Persist current data state. |
/api/v1/session/load/{session_id} | POST | Restore a saved session. |
The API also keeps legacy compatibility routes at /simulate, /simulate/advanced, and /results/fisher/{n_photons}. The current React frontend still depends on those older routes.
Desktop automation API
python/gui/automation_api.py is an in-process API for a live Qt window. It exposes layout, controller state, run/export triggers, plot payloads, diagnostics frames, and optimisation state without going through HTTP.
This is separate from the GUI schema: the schema describes the workspace declaratively, while the automation API performs actions against a running desktop session.
Optimisation payloads expose throughput histories derived from all-photon Fisher efficiency internally, even when the active GUI display basis is conditional or collected-photon reporting. In count-rate mode, throughput can also be based on the dead-time-corrected Fisher curve when correction is enabled, and the returned history may include both coarse and refined count-rate candidates.
GUI schema
The GUI schema is a machine-readable description of the current desktop workspace and controller. It is used by automation, front-end mirroring, and MCP-guided navigation.