open-standards/wai/quantum-studio/README.md

Quantum Studio

An editor for OpenQASM programs, with three places to run them:

• this browser, through the quantum job service's engine compiled to WebAssembly, in a worker;
• this computer, through the same engine built natively, in the desktop app;
• the job service, over HTTP.

Every place returns the same job: the request, the method and why it was chosen, the result, and its receipt. The Studio shows them the same way and checks every receipt on the machine it runs on. The same request with the same seed gives the same counts in each place.

The editor:

• highlights OpenQASM;
• completes the standard gates and the program's own registers;
• marks the engine's diagnostics on their lines;
• draws the circuit and shows the plan as you type.

Ctrl+Enter (⌘+Enter on macOS) runs the program, and Escape cancels a run. The program and the history of runs are kept on the device. "Copy link" puts the program in a URL fragment, which no server sees.

The assistant

The Assistant pane talks to a language model on this machine: any server with the chat-completions interface and tool calls, such as the JouleClaw runtime or a llama.cpp server. The address goes under "Model…" and is http://127.0.0.1:8080/v1 by default. Nothing leaves the machine unless the address points elsewhere. In the desktop app the app makes the call itself, so no browser origin rule stands in the way.

The engine is the model's tool, not an afterthought:

• Its tools are the Studio's engine: read the program, lint, draw, plan and run. Its first turn must call one of them, so every answer starts from the engine.
• Every program it proposes is checked before it is offered. The engine reads it here. One that does not parse goes back to the model once, with the engine's reason, to be corrected. One that parses is run, with the settings the model used, so the counts it quoted are the counts shown. Then "Apply" puts it in the editor.
• It may state only figures the engine returned. A figure in its prose that no tool returned is marked "Not from a run".
• Answers are plain text. LaTeX a model writes anyway is shown as Unicode.

node test/assistant-live.mjs URL drives the assistant against a real model server and prints what it did. It is not part of CI, which has no model.

Hosting it

Build it with npm ci && node build.mjs. That writes dist/:

File	What it is
studio.js	the interface, bundled
worker.js	the engine's worker
studio.css	the Studio's styles
tokens.css	the site's design tokens, for when it stands alone
index.html	the page that stands alone

A host mounts the Studio on an element:

<div id="studio"
     data-engine-pkg="/quantum-ide/pkg/wai_quantum_ide.js"
     data-worker="/quantum-studio/worker.js"
     data-service="/quantum-jobs"></div>
<script type="module" src="/quantum-studio/studio.js"></script>

data-embedded tells the Studio the host page has its own heading, so the Studio's name is not a second h1. data-engine-pkg names the engine's browser package: wai-web built with the feature quantum_engine. node build.mjs --pkg DIR copies such a package into dist/pkg/ for index.html. On the desktop, window.__TAURI__ is present and the Studio uses the native engine instead.

Testing it

node build.mjs --pkg PATH/TO/PKG && node test/studio.test.mjs

The test runs the Studio in the installed browser:

• lint, draw and plan as the program is typed;
• a run in the browser, with its receipt checked there;
• an error marked on its line;
• a rotation run on the state vector;
• the same job on the live service giving the counts run here, shot for shot;
• Ctrl+Enter;
• the program and the history surviving a reload;
• the assistant, against a scripted model server: a tool call run on the engine, a proposal the engine cannot read sent back with its reason, the corrected one checked and run before it is offered, and Apply;
• the layout at a phone's width.

STUDIO_SKIP_SERVICE=1 leaves the service step out. It saves screenshots of both colour schemes in test/screenshots/.