@oqtopus-team/pi-qdash 0.1.0 → 0.1.2

package/README.md

@@ -24,6 +24,14 @@ It uses [`@oqtopus-team/qdash-client`](https://www.npmjs.com/package/@oqtopus-te
 
 ## Installation
 
+Install pi first if needed:
+
+```bash
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
+
+Install the published extension:
+
 ```bash
 pi install npm:@oqtopus-team/pi-qdash
 ```
@@ -47,10 +55,25 @@ In interactive pi, set up the session context first:
 
 See the documentation below for the full tool and command reference.
 
+## Developing from a Fork
+
+For local development, clone your fork, install dependencies, and run pi against the checkout:
+
+```bash
+git clone https://github.com/<your-user>/pi-qdash.git
+cd pi-qdash
+npm install
+npm run check
+pi -e .
+```
+
+See [Development Guide](./docs/DEVELOPMENT.md) for the fork workflow, local testing, PR expectations, and the extension-vs-skill design policy.
+
 ## Documentation
 
 - [Tool Reference](./docs/tools.md)
 - [Commands & Skills](./docs/commands.md)
+- [Development Guide](./docs/DEVELOPMENT.md)
 - [Contributing](./docs/CONTRIBUTING.md)
 
 ## Citation

package/extensions/qdash.ts

@@ -2062,6 +2062,102 @@ function figureComponent(details: FigureDetails, theme: Theme) {
   return textComponent(figureResultText(details).split("\n"), theme);
 }
 
+type PlotlyTrace = Record<string, unknown>;
+
+type FigureAnalysis = {
+  path: string;
+  taskId?: string;
+  traceCount: number;
+  summaries: string[];
+  warnings: string[];
+};
+
+function numericArray(value: unknown): number[] {
+  return Array.isArray(value) ? value.filter((item): item is number => typeof item === "number" && Number.isFinite(item)) : [];
+}
+
+function numericMatrix(value: unknown): number[][] {
+  return Array.isArray(value)
+    ? value.map((row) => numericArray(row)).filter((row) => row.length > 0)
+    : [];
+}
+
+function matrixValue(matrix: number[][], row: number, column: number): number | undefined {
+  return matrix[row]?.[column];
+}
+
+function compactStats(values: number[]): string {
+  if (!values.length) return "no numeric values";
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  return `n=${values.length} min=${formatNumber(min)} max=${formatNumber(max)} mean=${formatNumber(mean)}`;
+}
+
+function formatMaybeNumber(value: number | undefined): string {
+  return typeof value === "number" && Number.isFinite(value) ? formatNumber(value) : "n/a";
+}
+
+function analyzePlotlyFigure(path: string, figure: unknown, taskId?: string): FigureAnalysis {
+  const object = figure && typeof figure === "object" ? figure as Record<string, unknown> : {};
+  const traces = Array.isArray(object.data) ? object.data.filter((trace): trace is PlotlyTrace => Boolean(trace) && typeof trace === "object") : [];
+  const summaries: string[] = [];
+  const warnings: string[] = [];
+
+  traces.forEach((trace, index) => {
+    const type = typeof trace.type === "string" ? trace.type : "unknown";
+    const name = typeof trace.name === "string" ? trace.name : `trace ${index}`;
+    if (type === "scatter" || Array.isArray(trace.y)) {
+      const y = numericArray(trace.y);
+      const x = numericArray(trace.x);
+      const err = trace.error_y && typeof trace.error_y === "object" ? (trace.error_y as Record<string, unknown>).value : undefined;
+      summaries.push(`${index}: scatter ${name} y(${compactStats(y)}) first=${formatMaybeNumber(y[0])} last=${formatMaybeNumber(y[y.length - 1])}${typeof err === "number" ? ` err=${formatNumber(err)}` : ""}`);
+      if (y.length >= 5) {
+        const tail = y.slice(Math.floor(y.length / 2));
+        const tailSpan = Math.max(...tail) - Math.min(...tail);
+        if (tailSpan > 0.4) warnings.push(`scatter ${name}: late repetitions still have large span ${formatNumber(tailSpan)}; repeated-pulse response may be unstable`);
+        const firstStep = Math.abs((y[1] ?? y[0]) - y[0]);
+        if (firstStep > 0.6 && Math.abs(y[y.length - 1]) > 0.1) warnings.push(`scatter ${name}: large first-step contrast but non-zero final offset ${formatNumber(y[y.length - 1])}`);
+      }
+      if (x.length && y.length && x.length !== y.length) warnings.push(`scatter ${name}: x/y length mismatch ${x.length}/${y.length}`);
+      return;
+    }
+
+    if (type === "heatmap" || Array.isArray(trace.z)) {
+      const z = numericMatrix(trace.z);
+      const flat = z.flat();
+      summaries.push(`${index}: heatmap ${z.length}x${z[0]?.length ?? 0} z(${compactStats(flat)})`);
+      if (z.length === 4 && z.every((row) => row.length === 4)) {
+        const diag = [0, 1, 2, 3].map((i) => z[i][i]);
+        const pop10 = diag[2];
+        const coh0011Re = matrixValue(z, 0, 3);
+        summaries.push(`   4x4 diag=[${diag.map(formatNumber).join(", ")}]  z00,11=${formatMaybeNumber(coh0011Re)}`);
+        if (pop10 > 0.15) warnings.push(`4x4 heatmap: |10> population/component is high (${formatNumber(pop10)}); suspect Bell/Zx angle, phase, or cancel error`);
+      }
+      return;
+    }
+
+    summaries.push(`${index}: ${type}`);
+  });
+
+  if (!traces.length) warnings.push("no Plotly data traces found");
+  return { path, taskId, traceCount: traces.length, summaries, warnings };
+}
+
+function figureAnalysisText(analysis: FigureAnalysis): string {
+  return boxed("QDash Figure Analysis", [
+    `path ${analysis.path}`,
+    ...(analysis.taskId ? [`task ${analysis.taskId}`] : []),
+    `traces ${analysis.traceCount}`,
+    "",
+    "Summaries",
+    ...analysis.summaries.map((line) => `  - ${line}`),
+    "",
+    "Warnings",
+    ...(analysis.warnings.length ? analysis.warnings.map((line) => `  - ${line}`) : ["  - none"]),
+  ]).join("\n");
+}
+
 async function executeQuery(params: QDashQueryParams) {
   params = applyQDashContext(params);
   const client = await makeClient(params);
@@ -3150,6 +3246,41 @@ export default function qdashExtension(pi: ExtensionAPI) {
     },
   });
 
+  pi.registerTool({
+    name: "qdash_analyze_figure_json",
+    label: "QDash Analyze Figure JSON",
+    description: "Read-only helper that fetches a Plotly JSON calibration figure and summarizes numeric traces for agentic diagnosis.",
+    promptSnippet: "Analyze QDash calibration figure JSON traces without changing parameters",
+    promptGuidelines: [
+      "Use qdash_analyze_figure_json when a calibration figure has json_figure_path and you need numeric evidence from scatter or heatmap traces.",
+      "Treat the output as evidence for a skill/runbook decision; do not commit/apply parameters from this analysis alone.",
+    ],
+    parameters: Type.Object({
+      ...connectionParams,
+      path: Type.Optional(Type.String({ description: "Absolute JSON figure path. If omitted, taskId is required." })),
+      taskId: Type.Optional(Type.String({ description: "Task result ID used to select json_figure_path." })),
+      index: Type.Optional(Type.Number({ description: "JSON figure index for taskId selection. Defaults to 0." })),
+      includeData: Type.Optional(Type.Boolean({ description: "Include parsed Plotly JSON in structured data. Defaults to false." })),
+    }),
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; path?: string; taskId?: string; index?: number; includeData?: boolean }) {
+      const client = await makeClient(params);
+      let path = params.path;
+      let text = "";
+      if (path) {
+        const details = await fetchFigureDetails(client, path);
+        text = details.text ?? "";
+      } else {
+        const taskId = requireValue(params.taskId, "taskId");
+        const file: TaskResultFigureFile = await client.getTaskResultFigure(taskId, { index: params.index, preferJson: true });
+        path = file.path;
+        text = Buffer.from(file.data).toString("utf8");
+      }
+      const figure = JSON.parse(text) as unknown;
+      const analysis = analyzePlotlyFigure(path ?? "", figure, params.taskId);
+      return toTextToolResult(figureAnalysisText(analysis), { analysis, figure: params.includeData ? figure : undefined }, { tool: "qdash_analyze_figure_json", path, data: analysis });
+    },
+  });
+
   registerQueryTool({
     name: "qdash_get_provenance_stats",
     label: "QDash Provenance Stats",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oqtopus-team/pi-qdash",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pi extension for querying QDash via @oqtopus-team/qdash-client",
   "type": "module",
   "license": "Apache-2.0",

package/skills/qdash/SKILL.md

@@ -22,7 +22,7 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `qdash_list_executions`, `qdash_get_execution`
    - `qdash_list_ai_reviews`, `qdash_get_provenance_stats`
    - `qdash_list_forum_posts`, `qdash_get_forum_post`, `qdash_list_forum_replies`
-   - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`
+   - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`
    - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
 3. Use harness overview tools for status and triage:
    - `qdash_investigate` for natural-language requests to investigate or compare recent calibration, target history, figures, failures, issues, and Forum context
@@ -107,4 +107,5 @@ When the user wants to preserve an investigated observation in QDash forum/notes
 - Use `qdash_investigate` for natural-language requests to investigate, compare, or understand a target or recent calibration; it is read-only and combines recent results with target, Forum, issue, and recommendation context.
 - Use `qdash_compare_calibration` when the user asks what changed between recent calibration experiments; treat differences as evidence, not automatic approval to commit/apply parameters.
 - Use `qdash_recent_calibration_figure` when the user asks to see recent experiment images without a task ID.
+- Use `qdash_analyze_figure_json` for read-only numeric summaries of Plotly JSON calibration figures; keep domain-specific interpretation in the matching skill.
 - Prefer summarizing large responses with counts, IDs, time ranges, and notable values.

package/skills/{qdash-calibration → qdash-calibration-agent}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: qdash-calibration
-description: Guide conservative autonomous QDash calibration workflows from pi. Use when the user asks to calibrate, tune, recover failed calibration tasks, run agent calibration sessions, or decide the next calibration action for qubits/couplings.
+name: qdash-calibration-agent
+description: Guide conservative confirmation-gated QDash calibration execution workflows from pi. Use when the user asks to calibrate, tune, recover failed calibration tasks, run agent calibration sessions, or decide the next calibration action for qubits/couplings.
 license: Apache-2.0
 compatibility: pi-coding-agent >=0.74, pi-qdash extension, QDash agent-session APIs
 metadata:
@@ -9,7 +9,7 @@ metadata:
   maturity: experimental
   safety_level: operational-write-gated
   default_mode: one-target-one-action
-  source_of_truth: pi-qdash skill until QDash task-knowledge operation is finalized
+  source_of_truth: pi-qdash skills until QDash task-knowledge operation is finalized
   preferred_qubit_recovery_recipe: CheckRabi -> CheckChevron -> Configure -> CheckRabi
   requires_confirmation_for:
     - agent session creation
@@ -26,7 +26,7 @@ metadata:
 
 # QDash Calibration Agent
 
-This skill defines how pi should behave as a conservative calibration agent. It is operational guidance for the agent; long-lived physics/task knowledge may later move to QDash task-knowledge, but until that process is settled, keep practical calibration recipes here.
+This skill defines how pi should behave as a conservative, confirmation-gated calibration execution agent. It should orchestrate safe operational steps after diagnosis. Long-lived physics/task knowledge may later move to QDash task-knowledge; detailed read-only diagnosis should live in dedicated diagnosis skills.
 
 ## Core principles
 
@@ -139,6 +139,8 @@ Known failed pattern:
 
 ## Coupling / two-qubit recovery rules
 
+For detailed two-qubit quality diagnosis, use the `qdash-two-qubit-calibration-diagnosis` skill. Keep this section as the conservative operational rule set.
+
 For `ZX90InterleavedRandomizedBenchmarking` or two-qubit validation failures, do not rerun RB first. Walk back through prerequisites:
 
 1. `CheckCrossResonance`
@@ -148,6 +150,8 @@ For `ZX90InterleavedRandomizedBenchmarking` or two-qubit validation failures, do
 5. `CheckBellStateTomography`
 6. then RB validation
 
+Treat `completed` as execution status, not proof of quality. If Bell fidelity is low, IRB uncertainty is large, or coherence-limit fidelity is much higher than measured Bell/IRB fidelity, suspect ZX90 angle/phase/cancel/rotary calibration before blaming T1/T2.
+
 If CR rotation is weak, inspect qubit detuning/frequency collisions and coupling history before increasing CR amplitude.
 
 ## Session policy guidelines

package/skills/qdash-two-qubit-calibration-diagnosis/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: qdash-two-qubit-calibration-diagnosis
+description: Diagnose QDash two-qubit calibration quality from CR, ZX90, Bell-state, tomography, coherence-limit, and IRB task results. Use when a coupling calibration completes but gate fidelity, Bell fidelity, or validation quality may be poor.
+license: Apache-2.0
+compatibility: pi-coding-agent >=0.74, pi-qdash extension
+metadata:
+  domain: quantum-calibration
+  safety_level: read-only-first-write-gated
+  preferred_validation_chain: CheckCrossResonance -> CreateZX90 -> CheckZX90 -> CheckBellState -> CheckBellStateTomography -> ZX90InterleavedRandomizedBenchmarking
+---
+
+# QDash Two-Qubit Calibration Diagnosis
+
+Use this skill when investigating coupling-level calibration quality, especially when tasks are `completed` but quality may be poor.
+
+## Principles
+
+- Treat `completed` as execution status, not proof of calibration quality.
+- Diagnose from evidence before suggesting operational actions.
+- Prefer read-only tools first: `qdash_target_report`, `qdash_list_task_results`, `qdash_get_task_result`, `qdash_analyze_figure_json`, and `qdash_get_task_figures`.
+- Do not rerun RB first when validation quality is suspicious. Walk back through prerequisites.
+- Do not commit or apply candidates without explicit user confirmation, and only after downstream validation.
+
+## Standard read-only investigation
+
+For a coupling `cA-B`:
+
+1. Build context with `qdash_target_report` and recent task results for the coupling.
+2. Inspect the latest tasks in this chain:
+   - `CheckCrossResonance`
+   - `CreateZX90`
+   - `CheckZX90`
+   - `CheckBellState`
+   - `CheckBellStateTomography`
+   - `Check2QGateCoherenceLimit`
+   - `ZX90InterleavedRandomizedBenchmarking`
+3. Fetch task details and record:
+   - CR: `cr_amplitude`, `cr_phase`, `cancel_amplitude`, `cancel_phase`, `rotary_amplitude`, `zx_rotation_rate`
+   - ZX90: `zx90_gate_time`
+   - Bell tomography: `bell_state_fidelity`
+   - Coherence limit: `two_qubit_gate_coherence_limit`
+   - IRB: `zx90_gate_fidelity`, its error, `zx90_depolarizing_rate`, `n_trials`
+4. For JSON figures, use `qdash_analyze_figure_json` before manually reading raw Plotly JSON.
+5. Summarize symptoms, likely failure mode, and the next *read-only or confirmation-gated* step.
+
+## Interpretation rules
+
+### Completed but low quality
+
+Flag as suspicious when any of these hold:
+
+- Bell-state tomography fidelity is below ~0.8.
+- IRB fidelity has a large uncertainty/error bar, or `n_trials` is small.
+- Coherence-limit fidelity is high but Bell/IRB fidelity is much lower.
+- `CheckZX90` repeated-pulse traces do not show a stable/consistent response.
+- CR parameter generation succeeds but `cr_amplitude` is near saturation or `zx_rotation_rate` is very small.
+
+### Coherence limit gap
+
+If `two_qubit_gate_coherence_limit` is high but measured Bell/IRB fidelity is low, do not attribute the issue primarily to T1/T2. Suspect control/calibration issues such as:
+
+- ZX90 angle error
+- CR phase error
+- cancel-pulse amplitude/phase mismatch
+- rotary compensation mismatch
+- readout/classification contribution to validation figures
+
+### Bell tomography signals
+
+For a Bell target resembling `( |00> + |11> ) / sqrt(2)`:
+
+- Large `|10>` or `|01>` population suggests population/conditional-rotation error, not just dephasing.
+- Weak `|00><11|` coherence suggests phase, dephasing, or preparation error.
+- Large imaginary coherence can indicate phase-compensation error.
+
+Use the heatmap summaries from `qdash_analyze_figure_json` as numeric evidence. Do not overfit a single plot; correlate with `CheckZX90` and IRB.
+
+### CheckZX90 repeated-pulse signals
+
+Look for stable repeated-pulse behavior. Warnings include:
+
+- Large scatter or non-decaying erratic points after the first few repetitions.
+- Large first-step contrast followed by a non-zero offset.
+- Different qualitative behavior between control and target qubit plots.
+
+These symptoms point toward angle/phase/cancel/rotary issues and should be investigated before trusting IRB.
+
+### IRB caveats
+
+- A `completed` IRB with large error bar is weak evidence.
+- Small `n_trials` should be reported explicitly.
+- If Bell tomography is poor, do not use IRB alone as a pass signal.
+
+## Recommended action sequence
+
+When validation quality is poor:
+
+```text
+Inspect figures/results
+-> CheckCrossResonance
+-> CreateZX90
+-> CheckZX90
+-> CheckBellState
+-> CheckBellStateTomography
+-> ZX90InterleavedRandomizedBenchmarking
+```
+
+Each operational step requires explicit confirmation. Validate Bell/tomography before using IRB as the final quality signal.
+
+## Known case: mackerel 144Qv1 c48-50, 20260725-003
+
+Symptoms observed:
+
+- `CheckCrossResonance` completed with `zx_rotation_rate ~ 1.69e-3`.
+- `Check2QGateCoherenceLimit` reported ~0.978.
+- `CheckBellStateTomography` reported `bell_state_fidelity ~ 0.60`.
+- Bell tomography had high `|10>` component/population (~0.29) and non-ideal coherence.
+- `ZX90InterleavedRandomizedBenchmarking` completed with `zx90_gate_fidelity ~0.94` but large error (~0.087) and `n_trials=10`.
+- `CheckZX90` repeated-pulse traces were not clean/stable.
+
+Interpretation:
+
+- This is not primarily coherence-limited.
+- Suspect ZX90 angle/phase/cancel/rotary calibration quality.
+- Prefer walking back through `CheckCrossResonance -> CreateZX90 -> CheckZX90`, then validate with Bell tomography before trusting IRB.