docs/architecture.md

Architecture - Qubit-Medic

The system has three concentric layers, each behind a clean contract.

+-------------------------------------------------------------+
|                       LLM trainer                          |
|                  (TRL GRPOTrainer + Unsloth)                |
|                                                             |
|   for each step:                                            |
|     prompts = sample(prompt_pool)                          |
|     completions = model.generate(prompts, n=4)             |
|     for c in completions:                                   |
|         rewards = env_client.step(c).info["rewards"]       |
+----------------------------+--------------------------------+
                             | HTTP (or in-process)
                             v
+-------------------------------------------------------------+
|              FastAPI server: qubit_medic.server.app         |
|                                                             |
|   POST /reset    -> DecoderObservation                      |
|   POST /step     -> StepResult (reward + info breakdown)    |
|   GET  /health   -> liveness + curriculum stats             |
|   POST /decode   -> baseline PyMatching prediction          |
+----------------------------+--------------------------------+
                             |
                             v
+-------------------------------------------------------------+
|         DecoderEnvironment (qubit_medic.server.environment) |
|                                                             |
|   reset():                                                  |
|     1. CurriculumScheduler.sample()                         |
|     2. cached: stim.Circuit + DEM + pymatching.Matching     |
|     3. compile_detector_sampler().sample(1) -> syndrome     |
|     4. build_prompt(...)  -> DecoderObservation             |
|                                                             |
|   step(raw_response):                                       |
|     1. parse_action()  ->  ParseResult (X/Z error sets)     |
|     2. layout.llm_to_stim()  remap to Stim qubit IDs        |
|     3. compute_all_rewards():                               |
|        - logical_correction (Stim ground truth)             |
|        - syndrome_consistency (final-round detectors)       |
|        - hamming_overlap (vs PyMatching reference frame)    |
|        - format_compliance (parser output)                  |
|        - pymatching_beat (LLM right & PM wrong)             |
|     4. CurriculumScheduler.update(level, logical_correct)   |
|     5. return StepResult                                    |
+-------------------------------------------------------------+

Trust boundaries

+-----------+     prompt + syndrome      +--------------+
|    LLM    | <-------------------------- | Observation  |
+-----------+                             +--------------+
      |
      v raw text
+-----------+     parse + remap          +-----------+
|  Action   | --> [LLM ID space] -----> | Stim ID    |
+-----------+                            +-----------+
                                              |
                                              v scoring
                                        +-----------+
                                        |   State   |
                                        | (server)  |
                                        +-----------+

The DecoderState (server-side) holds the ground-truth observable flip, the true error pattern (PyMatching reference frame), and the seed used for sampling. None of this is ever returned to the LLM. This is the participant guide's "avoid unrestricted global state" discipline made concrete by Pydantic schemas.

Why a terminal Pauli frame, and what it costs

The LLM emits two integer lists: which data qubits suffered an X error and which suffered a Z error, at the moment of final measurement (a terminal Pauli frame). For the rotated memory_z task this is sufficient for the logical observable - the destructive Z measurement is exactly the Z observable, and an X error on a data qubit in the observable's support flips its measurement outcome.

The trade-off is that an end-of-circuit Pauli frame only constrains the final-round detectors (the ones that incorporate the destructive Z measurement results). Earlier-round detectors fire only in response to errors that propagate through the stabilizer rounds, and a terminal frame cannot say anything about them. Reward 2 (syndrome consistency) explicitly grades only the final-round detector bits, which matches the representation's expressive power. The remaining detector bits are implicitly available in the prompt for the LLM to reason about, but unscored.

Why five rewards instead of one

The participant guide is emphatic: "use multiple independent reward functions, not just one." Each of our five rewards is independently verifiable in well under a millisecond and disagrees with at least one other on degenerate inputs:

• All-zeros agent on a syndrome with a logical-but-undetectable error: logical_correction = 0 but syndrome_consistency = 1. The R2 - R1 disagreement exposes the failure case.
• Random-qubit agent that lands on the right observable parity by luck: logical_correction = 1 but syndrome_consistency and hamming_overlap are both low. R1 alone over-rewards; the others expose the lack of understanding.

This decomposition is what the guide calls "hard to game by construction."