| ## Phase 0/1/2 Integration Guide |
|
|
| This document explains how the three phases of the agentic quantum dot tuning system integrate together. |
|
|
| --- |
|
|
| ## Architecture Overview |
|
|
| ``` |
| ┌─────────────────────────────────────────────────────────────────────┐ |
| │ EXECUTIVE AGENT (Phase 2) │ |
| │ Main orchestration loop (Fig. 2) │ |
| └─────────────────────────────────────────────────────────────────────┘ |
| │ |
| ┌─────────────────┼─────────────────┐ |
| │ │ │ |
| ▼ ▼ ▼ |
| ┌────────────────┐ ┌────────────┐ ┌─────────────┐ |
| │ PERCEPTION │ │ PLANNING │ │ HARDWARE │ |
| │ (Phase 1) │ │ (Phase 2) │ │ (Phase 0) │ |
| └────────────────┘ └────────────┘ └─────────────┘ |
| │ │ │ |
| │ - DQCGatekeeper │ - BeliefUpdater │ - DeviceAdapter |
| │ - InspectionAgent │ - ActiveSensingPolicy│ - SafetyCritic |
| │ - EnsembleCNN │ - MultiResBO │ - HITLManager |
| │ - OOD Detector │ - StateMachine │ - GovernanceLogger |
| │ │ - TranslationAgent │ |
| └───────────────────┴──────────────────────┴─────────────┘ |
| │ |
| ▼ |
| ┌─────────────────────┐ |
| │ EXPERIMENT STATE │ |
| │ (Phase 0) │ |
| │ Single source of │ |
| │ truth │ |
| └─────────────────────┘ |
| ``` |
|
|
| --- |
|
|
| ## Data Flow: One Complete Loop |
|
|
| ### 1. Active Sensing (Phase 2 Planning) |
| **ActiveSensingPolicy.select()** examines `ExperimentState.belief` and proposes a measurement: |
| ```python |
| plan = sensing_policy.select(state.belief, v1_range, v2_range) |
| # → MeasurementPlan(modality=COARSE_2D, v1_range=(-0.5, 0.5), ...) |
| ``` |
|
|
| ### 2. Translation (Phase 2 Agent) |
| **TranslationAgent.execute()** converts the plan to a DeviceAdapter call: |
| ```python |
| result = translator.execute(plan) |
| measurement = result.measurement # Measurement from CIMSimulatorAdapter |
| state.add_measurement(measurement) |
| ``` |
|
|
| ### 3. Data Quality Check (Phase 1 Perception) |
| **DQCGatekeeper.assess()** runs physics-based quality checks: |
| ```python |
| dqc_result = dqc.assess(measurement) |
| state.add_dqc_result(dqc_result) |
| |
| if dqc_result.quality == DQCQuality.LOW: |
| # STOP — do not pass to InspectionAgent |
| return failure_result |
| ``` |
|
|
| ### 4. Classification (Phase 1 Perception) |
| **InspectionAgent.inspect()** runs the full perception pipeline: |
| ```python |
| if measurement.is_2d: |
| classification, ood_result = inspector.inspect(measurement, dqc_result) |
| state.add_classification(classification) |
| state.add_ood_result(ood_result) |
| ``` |
|
|
| InspectionAgent internally: |
| - Log-preprocesses the array |
| - Runs EnsembleCNN (5-model ensemble) |
| - Extracts physics features (FFT peak ratio, diagonal strength) |
| - Checks for physics override |
| - Runs OOD detector on penultimate features |
| - Generates structured NL summary |
|
|
| ### 5. Belief Update (Phase 2 Planning) |
| **BeliefUpdater** updates the POMDP belief using CIM observation model: |
| ```python |
| belief_updater.update_from_2d(measurement, classification) |
| # Updates state.belief.charge_probs in-place |
| ``` |
|
|
| For line scans (bypass InspectionAgent per blueprint §5.1): |
| ```python |
| if measurement.modality == MeasurementModality.LINE_SCAN: |
| belief_updater.update_from_1d(measurement) |
| ``` |
|
|
| ### 6. Bayesian Optimization (Phase 2 Planning) |
| **MultiResBO.propose()** uses GP with CIM-informed priors: |
| ```python |
| bo.update(state.bo_history) |
| proposal = bo.propose(current=state.current_voltage, l1_max=0.10) |
| # → ActionProposal(delta_v=VoltagePoint(vg1=0.05, vg2=0.02), ...) |
| ``` |
|
|
| ### 7. Safety Critic (Phase 0 Hardware) |
| **SafetyCritic** enforces hard constraints: |
| ```python |
| proposal = safety_critic.clip(proposal, state.current_voltage) |
| verdict = safety_critic.verify(state.current_voltage, proposal) |
| |
| if not verdict.all_passed: |
| state.record_safety_violation() |
| return failure_result |
| ``` |
|
|
| ### 8. Risk Assessment + HITL (Phase 0 Governance) |
| **HITLManager.compute_risk_score()** aggregates 12 trigger conditions: |
| ```python |
| risk = hitl_manager.compute_risk_score( |
| proposal=proposal, |
| safety_verdict=verdict, |
| dqc_flag=dqc_result.quality.value, |
| ood_score=ood_result.score, |
| ensemble_disagreement=classification.ensemble_disagreement, |
| consecutive_backtracks=state.consecutive_backtracks, |
| step=state.step + 1, |
| ) |
| |
| if risk >= 0.70: |
| event = hitl_manager.queue_request(...) |
| event = hitl_manager.await_decision(event) # BLOCKS |
| state.add_hitl_event(event) |
| ``` |
|
|
| ### 9. Execute Move (Phase 2 Agent + Phase 0 Hardware) |
| If all checks pass: |
| ```python |
| translator.execute_voltage_move( |
| vg1=state.current_voltage.vg1 + safe_dv.vg1, |
| vg2=state.current_voltage.vg2 + safe_dv.vg2, |
| ) |
| state.apply_move(safe_dv) |
| ``` |
|
|
| ### 10. Governance (Phase 0) |
| **GovernanceLogger** records every action: |
| ```python |
| decision = Decision( |
| run_id=state.run_id, |
| step=state.step, |
| intent="voltage_move", |
| stage=state.stage, |
| observation_summary={...}, |
| action_summary={...}, |
| rationale="...", |
| ) |
| state.add_decision(decision) |
| governance_logger.log(decision) |
| ``` |
|
|
| ### 11. State Machine (Phase 2 Planning) |
| **StateMachine.process_result()** manages stage transitions: |
| ```python |
| result = navigation_result(target_reached=True, belief_confidence=0.85) |
| new_stage, rationale, hitl_triggered = state_machine.process_result(result) |
| |
| if new_stage != state.stage: |
| state.advance_stage(new_stage) |
| ``` |
| |
| Backtracking on failure: |
| ```python |
| if retries_exhausted: |
| event = BacktrackEvent(from_stage=NAVIGATION, to_stage=CHARGE_ID, ...) |
| state.record_backtrack(event) |
| ``` |
| |
| --- |
| |
| ## Key Integration Points |
| |
| ### BeliefState (Phase 0 stub → Phase 2 implementation) |
| |
| **Phase 0 defined the interface:** |
| ```python |
| @dataclass |
| class BeliefState: |
| charge_probs: Dict[tuple, float] = field(default_factory=dict) |
| uncertainty_map: Optional[Any] = None |
| device_params: Dict[str, float] = field(default_factory=lambda: {...}) |
| |
| def entropy(self) -> float: ... |
| def most_likely_state(self) -> Optional[tuple]: ... |
| def initialise_uniform(self, charge_states: Optional[List[tuple]] = None) -> None: ... |
| ``` |
|
|
| **Phase 2 implemented the particle filter:** |
| ```python |
| class BeliefUpdater: |
| def __init__(self, belief: BeliefState, ...): |
| self.belief = belief # Operates on Phase 0 stub directly |
| self._particles = _ParticleSet(...) # Internal engine |
| |
| def update_from_2d(self, measurement, classification): |
| # Updates self.belief.charge_probs in-place |
| self.belief.charge_probs = self._particles.to_charge_probs() |
| ``` |
|
|
| ### Classification Flow (Phase 1 → Phase 2) |
|
|
| **InspectionAgent output:** |
| ```python |
| classification = Classification( |
| measurement_id=..., |
| label=ChargeLabel.DOUBLE_DOT, |
| confidence=0.85, |
| ensemble_disagreement=0.12, |
| features={...}, |
| physics_override=False, |
| nl_summary="...", |
| ) |
| ``` |
|
|
| **Used by multiple Phase 2 components:** |
| - **BeliefUpdater:** Uses `label` and `confidence` to boost particle weights; `physics_override=True` → inflates uncertainty |
| - **MultiResBO:** Creates BOPoints from classifications; `confidence` becomes the reward signal |
| - **StateMachine:** Uses `confidence` to determine if stage success threshold is met |
| - **HITLManager:** Uses `ensemble_disagreement` in risk score computation |
|
|
| ### Safety Integration (Phase 0 → Phase 2) |
|
|
| **ExecutiveAgent always calls SafetyCritic before any move:** |
| ```python |
| proposal = bo.propose(...) # Phase 2 proposes |
| proposal = safety_critic.clip(proposal, current) # Phase 0 clips |
| verdict = safety_critic.verify(current, proposal) # Phase 0 verifies |
| |
| if verdict.all_passed: |
| translator.execute_voltage_move(...) # Phase 2 executes |
| state.apply_move(proposal.safe_delta_v) # Phase 0 records |
| else: |
| state.record_safety_violation() |
| ``` |
|
|
| No component can bypass SafetyCritic — it's architecturally enforced. |
|
|
| ### HITL Integration (Phase 0 → Phase 2) |
|
|
| **HITLManager is called at two points:** |
| 1. **Risk score computation (every voltage move):** |
| ```python |
| risk = hitl_manager.compute_risk_score(...) |
| if risk >= 0.70: |
| event = hitl_manager.queue_request(...) |
| event = hitl_manager.await_decision(event) # BLOCKS |
| ``` |
|
|
| 2. **State machine backtracking (condition 8):** |
| ```python |
| if state.consecutive_backtracks >= 2: |
| # StateMachine returns hitl_triggered=True |
| # ExecutiveAgent queues HITL event |
| ``` |
|
|
| **No timeout auto-approval** — agent blocks until human decides. |
|
|
| --- |
|
|
| ## Running the Integrated System |
|
|
| ### Without Trained Models (CI/Development) |
| ```bash |
| # Uses InspectionAgent in stub mode (untrained ensemble, no OOD) |
| pytest tests/test_integration_phase012.py -v |
| |
| # Run benchmark without checkpoints |
| python experiments/benchmark_phase2.py --fast --skip-missing-checkpoints |
| ``` |
|
|
| ### With Trained Models (Full System) |
| ```bash |
| # 1. Train Phase 1 models |
| python experiments/train_phase1.py --out experiments/checkpoints/phase1 |
| |
| # 2. Run benchmark |
| python experiments/benchmark_phase2.py --n-trials 100 --budget 2048 |
| ``` |
|
|
| ### Manual Inspection |
| ```python |
| from qdot.core.state import ExperimentState |
| from qdot.simulator.cim import CIMSimulatorAdapter |
| from qdot.agent.executive import ExecutiveAgent |
| from qdot.perception.inspector import InspectionAgent |
| from qdot.core.hitl import HITLManager, HITLOutcome |
| |
| # Setup |
| state = ExperimentState.new(device_id="manual_test") |
| adapter = CIMSimulatorAdapter(device_id="manual_test", seed=42) |
| inspector = InspectionAgent(ensemble=None, ood_detector=None) # Or load trained |
| |
| hitl = HITLManager() |
| hitl.set_test_mode(auto_outcome=HITLOutcome.APPROVED) # No blocking for demo |
| |
| # Create agent |
| agent = ExecutiveAgent( |
| state=state, |
| adapter=adapter, |
| inspection_agent=inspector, |
| hitl_manager=hitl, |
| max_steps=50, |
| measurement_budget=2048, |
| ) |
| |
| # Run |
| summary = agent.run() |
| print(f"Success: {summary['success']}") |
| print(f"Measurements: {summary['total_measurements']}") |
| print(f"Reduction: {summary['measurement_reduction']:.1%}") |
| ``` |
|
|
| --- |
|
|
| ## File Organization |
|
|
| ``` |
| qdot/ |
| ├── core/ # Phase 0 — Foundation |
| │ ├── types.py # All canonical types |
| │ ├── state.py # ExperimentState + BeliefState stub |
| │ ├── governance.py # GovernanceLogger |
| │ └── hitl.py # HITLManager |
| │ |
| ├── hardware/ # Phase 0 — Device interface |
| │ ├── adapter.py # DeviceAdapter ABC |
| │ └── safety.py # SafetyCritic |
| │ |
| ├── simulator/ # Phase 0 — CIM simulator |
| │ └── cim.py # ConstantInteractionDevice + CIMSimulatorAdapter |
| │ |
| ├── perception/ # Phase 1 — Perception pipeline |
| │ ├── dqc.py # DQCGatekeeper |
| │ ├── inspector.py # InspectionAgent |
| │ ├── classifier.py # EnsembleCNN |
| │ ├── features.py # Physics validators |
| │ ├── ood.py # MahalanobisOOD |
| │ └── dataset.py # CIMDataset for training |
| │ |
| ├── planning/ # Phase 2 — POMDP + BO |
| │ ├── belief.py # BeliefUpdater + CIMObservationModel |
| │ ├── sensing.py # ActiveSensingPolicy |
| │ ├── bayesian_opt.py # MultiResBO + GaussianProcess |
| │ └── state_machine.py # StateMachine (5 stages) |
| │ |
| └── agent/ # Phase 2 — Main loop |
| ├── executive.py # ExecutiveAgent (orchestrator) |
| └── translator.py # TranslationAgent (NL → API) |
| ``` |
|
|
| --- |
|
|
| ## Testing Strategy |
|
|
| ### Unit Tests (per module) |
| - `tests/test_types.py` — Phase 0 types |
| - `tests/test_state.py` — ExperimentState, BeliefState stub |
| - `tests/test_safety.py` — SafetyCritic + fuzz test (5000 iterations) |
| - `tests/test_simulator.py` — CIM physics |
| - `tests/test_perception.py` — DQC, CNN, OOD, InspectionAgent |
| - `tests/test_planning.py` — Belief, sensing, BO, state machine |
| - `tests/test_agent.py` — TranslationAgent, ExecutiveAgent |
|
|
| ### Integration Tests |
| - `tests/test_integration_phase012.py` — Full pipeline smoke tests |
|
|
| ### Benchmarks |
| - `experiments/train_phase1.py --fast` — Phase 1 smoke test (CI) |
| - `experiments/benchmark_phase2.py --fast` — Phase 2 quick eval (10 trials) |
| - `experiments/benchmark_phase2.py --n-trials 100` — Full benchmark |
|
|
| --- |
|
|
| ## Next Steps (Phase 3) |
|
|
| 1. **LLM Integration (IBM Granite 3-8B-Instruct)** |
| - Replace template rationales with LLM calls |
| - ONE call per stage transition + ONE per HITL trigger |
| - Budget: ~200 tokens per call |
|
|
| 2. **Disorder Learning** |
| - OOD flag → fit device-specific disorder map |
| - Inject into CIMObservationModel.device |
| - Close sim-to-real gap |
|
|
| 3. **Meta-Learning** |
| - Learn CIM parameter priors from device family |
| - Fast adaptation to new devices |
|
|
| 4. **Hardware Validation** |
| - Integrate real Si/SiGe adapter |
| - Run on QFlow hardware testbed |
| - Validate ≥50% reduction on real devices |
|
|
| --- |
|
|
| ## Troubleshooting |
|
|
| ### "No tests collected" in test_agent.py |
| **Cause:** File didn't exist or pytest can't find it. |
| **Fix:** Ensure `tests/test_agent.py` is in the repo root `tests/` directory. |
|
|
| ### "ModuleNotFoundError: No module named 'qdot.planning'" |
| **Cause:** Phase 2 modules not in Python path. |
| **Fix:** Run `pip install -e .` from repo root to install in editable mode. |
|
|
| ### InspectionAgent predictions are random |
| **Cause:** Running without trained checkpoints (ensemble=None). |
| **Fix:** Either (a) train models with `experiments/train_phase1.py`, or (b) use `--skip-missing-checkpoints` flag for testing without models. |
|
|
| ### HITL blocks forever |
| **Cause:** HITLManager not in test mode. |
| **Fix:** Call `hitl_manager.set_test_mode(auto_outcome=HITLOutcome.APPROVED)` for non-blocking testing. |
|
|
| ### SafetyCritic rejects all moves |
| **Cause:** Voltage bounds or l1_max cap too tight. |
| **Fix:** Check `state.voltage_bounds` and `state.step_caps["l1_max"]` are reasonable for your device. |
|
|
| --- |
|
|
| **Phase 0/1/2 integration complete.** All components tested individually and end-to-end. Ready for Phase 3. |
|
|
