@oqtopus-team/pi-qdash 0.1.11-beta.19 → 0.1.11-beta.20

package/extensions/lib/qcal-evidence.ts

@@ -0,0 +1,164 @@
+/**
+ * Evidence text for pi-qcaleval's `qcal_evaluate`: what a task result's
+ * measurement settings were, read from the run parameters QDash records.
+ *
+ * The evaluation model is meant to read the plot, so the context names the
+ * task, the target and the sweep (what was varied, over which range, in how
+ * many points), not the fitted results. The numbers come from the recorded
+ * parameters, so they are exact and need no hand-written summary.
+ */
+
+/** One parameter as QDash records it on a task result. */
+export interface RecordedParameter {
+  value: unknown;
+  unit: string;
+  value_type: string;
+  description: string;
+}
+
+/** A swept parameter: the axis a plot was taken along. */
+export interface Sweep {
+  name: string;
+  unit: string;
+  description: string;
+  /** How the points are spaced. */
+  spacing: "linear" | "log" | "list";
+  /** First and last point, in the parameter's unit. */
+  start: number;
+  stop: number;
+  points: number;
+  /** Spacing between points for a linear sweep. */
+  step?: number;
+}
+
+/** The recorded parameters of a task result, as a name → record map. */
+export function recordedParameters(value: unknown): Record<string, RecordedParameter> {
+  const output: Record<string, RecordedParameter> = {};
+  const input = value && typeof value === "object" ? (value as Record<string, unknown>) : {};
+  for (const [name, raw] of Object.entries(input)) {
+    if (raw && typeof raw === "object" && "value" in raw) {
+      const record = raw as Record<string, unknown>;
+      output[name] = {
+        value: record.value,
+        unit: typeof record.unit === "string" ? record.unit : "",
+        value_type: typeof record.value_type === "string" ? record.value_type : "",
+        description: typeof record.description === "string" ? record.description : "",
+      };
+    } else if (typeof raw === "number" || typeof raw === "string" || typeof raw === "boolean" || Array.isArray(raw)) {
+      output[name] = { value: raw, unit: "", value_type: Array.isArray(raw) ? "list" : typeof raw, description: "" };
+    }
+  }
+  return output;
+}
+
+function numbers(value: unknown): number[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const list = value.map((item) => (typeof item === "number" ? item : typeof item === "string" ? Number(item) : Number.NaN));
+  return list.length > 0 && list.every((item) => Number.isFinite(item)) ? list : undefined;
+}
+
+/**
+ * The sweeps among the recorded parameters, in record order, read the way
+ * QDash's `get_value` expands them: `range` / `np.arange` as (start, stop,
+ * step), `np.linspace` as (start, stop, num), `np.logspace` as (log10 start,
+ * log10 stop, num), and `list` as the points themselves.
+ */
+export function sweepsOf(parameters: Record<string, RecordedParameter>): Sweep[] {
+  const sweeps: Sweep[] = [];
+  for (const [name, parameter] of Object.entries(parameters)) {
+    const values = numbers(parameter.value);
+    if (!values) continue;
+    const base = { name, unit: parameter.unit, description: parameter.description };
+    const type = parameter.value_type;
+    if ((type === "range" || type === "np.arange") && values.length === 3) {
+      const [start, stop, step] = values as [number, number, number];
+      if (step === 0 || (stop - start) / step <= 0) continue;
+      const points = Math.ceil((stop - start) / step - 1e-9);
+      sweeps.push({ ...base, spacing: "linear", start, stop: start + (points - 1) * step, points, step });
+    } else if (type === "np.linspace" && values.length === 3) {
+      const [start, stop, num] = values as [number, number, number];
+      const points = Math.max(1, Math.round(num));
+      sweeps.push({ ...base, spacing: "linear", start, stop, points, ...(points > 1 ? { step: (stop - start) / (points - 1) } : {}) });
+    } else if (type === "np.logspace" && values.length === 3) {
+      const [start, stop, num] = values as [number, number, number];
+      sweeps.push({ ...base, spacing: "log", start: 10 ** start, stop: 10 ** stop, points: Math.max(1, Math.round(num)) });
+    } else if (type === "list" || type === "" || values.length !== 3) {
+      if (values.length < 2) continue;
+      sweeps.push({ ...base, spacing: "list", start: Math.min(...values), stop: Math.max(...values), points: values.length });
+    }
+  }
+  return sweeps;
+}
+
+/** A number for the model: up to four significant digits, no trailing zeros. */
+export function formatNumber(value: number): string {
+  if (!Number.isFinite(value)) return String(value);
+  if (Number.isInteger(value) && Math.abs(value) < 1e15) return String(value);
+  const text = Math.abs(value) >= 1e6 || Math.abs(value) < 1e-4 ? value.toExponential(3) : value.toPrecision(4);
+  return text.includes("e") ? text.replace(/\.?0+e/, "e") : text.replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");
+}
+
+function withUnit(value: number, unit: string): string {
+  const text = formatNumber(value);
+  return unit && unit !== "a.u." ? `${text} ${unit}` : text;
+}
+
+/** One sweep as text, e.g. "time_range 0 to 400 ns in steps of 8 ns (51 points)". */
+export function formatSweep(sweep: Sweep): string {
+  const range = `${sweep.name} ${formatNumber(sweep.start)} to ${withUnit(sweep.stop, sweep.unit)}`;
+  if (sweep.spacing === "log") return `${range}, ${sweep.points} points log-spaced`;
+  if (sweep.spacing === "list") return `${range}, ${sweep.points} points`;
+  return sweep.step === undefined ? `${range}, ${sweep.points} points` : `${range} in steps of ${withUnit(sweep.step, sweep.unit)} (${sweep.points} points)`;
+}
+
+/** Scalar settings as "name value unit" items, numbers and short strings only. */
+export function formatSettings(parameters: Record<string, RecordedParameter>, skip: ReadonlySet<string> = new Set()): string[] {
+  const items: string[] = [];
+  for (const [name, parameter] of Object.entries(parameters)) {
+    if (skip.has(name)) continue;
+    const value = parameter.value;
+    if (typeof value === "number") items.push(`${name} ${withUnit(value, parameter.unit)}`);
+    else if (typeof value === "boolean") items.push(`${name} ${value}`);
+    else if (typeof value === "string" && value.length <= 40) items.push(`${name} ${value}`);
+  }
+  return items;
+}
+
+export interface QcalContext {
+  taskName?: string;
+  status?: string;
+  targetKind?: string;
+  targetId?: string;
+  chipId?: string;
+  runParameters: Record<string, RecordedParameter>;
+  /** Calibration inputs (previous values), shown only on request. */
+  inputParameters?: Record<string, RecordedParameter>;
+  /** Fitted results, shown only on request. */
+  metrics?: Record<string, RecordedParameter>;
+  message?: string;
+}
+
+/**
+ * The context for `qcal_evaluate`: the task and target, then the sweep and
+ * the other run settings. Inputs and fitted results are added only when the
+ * caller asks, since the model is meant to read the plot.
+ */
+export function qcalContextText(context: QcalContext): string {
+  let head = `Task ${context.taskName ?? "unknown"}`;
+  if (context.targetId) {
+    head += ` on ${context.targetKind && context.targetKind !== "system" ? `${context.targetKind} ${context.targetId}` : context.targetId}`;
+  }
+  if (context.chipId) head += ` (chip ${context.chipId})`;
+  if (context.status) head += `, status ${context.status}`;
+  const lines = [`${head}.`];
+  const sweeps = sweepsOf(context.runParameters);
+  if (sweeps.length > 0) lines.push(`Sweep: ${sweeps.map(formatSweep).join("; ")}.`);
+  const settings = formatSettings(context.runParameters, new Set(sweeps.map((sweep) => sweep.name)));
+  if (settings.length > 0) lines.push(`Settings: ${settings.join("; ")}.`);
+  const inputs = context.inputParameters ? formatSettings(context.inputParameters) : [];
+  if (inputs.length > 0) lines.push(`Calibration inputs: ${inputs.join("; ")}.`);
+  const metrics = context.metrics ? formatSettings(context.metrics) : [];
+  if (metrics.length > 0) lines.push(`Fitted results: ${metrics.join("; ")}.`);
+  if (context.message?.trim()) lines.push(`Task message: ${context.message.trim()}`);
+  return lines.join("\n");
+}

package/extensions/qdash.ts

@@ -25,6 +25,7 @@ import { toFigureToolResult, toTextToolResult, toToolResult } from "./lib/result
 import { ansi, boxLinesToWidth, boxed, formatNumber, textComponent } from "./lib/render.js";
 import { plotSeriesLines, timeseriesPlotComponent, timeseriesPoints } from "./lib/timeseries-plot.js";
 import { installQDashWriteGate } from "./lib/write-gate.js";
+import { qcalContextText, recordedParameters, sweepsOf, type RecordedParameter, type Sweep } from "./lib/qcal-evidence.js";
 import { registerCalibrationPipelineTools } from "./tools/calibration-pipeline.js";
 import { registerTaskKnowledgeTool } from "./tools/task-knowledge.js";
 import { registerTimeseriesComparisonTool } from "./tools/timeseries.js";
@@ -405,6 +406,14 @@ type CalibrationEvidence = {
   task?: Record<string, unknown>;
   metrics?: Record<string, number | string | boolean | null>;
   parameters?: Record<string, number | string | boolean | null>;
+  /** The run parameters as recorded, with units and value types. */
+  runParameters?: Record<string, RecordedParameter>;
+  /** The calibration inputs as recorded (previous values), with units. */
+  inputParameters?: Record<string, RecordedParameter>;
+  /** The output parameters as recorded (fitted results), with units. */
+  metricRecords?: Record<string, RecordedParameter>;
+  /** The swept parameters among them: the axes the plot was taken along. */
+  sweeps?: Sweep[];
   resultJson?: unknown;
   figures?: Array<Record<string, unknown>>;
   logs?: string[];
@@ -431,23 +440,24 @@ function firstStringField(object: Record<string, unknown>, keys: string[]): stri
   return undefined;
 }
 
-function qcalEvidenceText(evidence: CalibrationEvidence): string {
-  const metrics = Object.entries(evidence.metrics ?? {}).slice(0, 8).map(([key, value]) => `  - ${key}: ${String(value)}`);
-  const figures = evidence.figures ?? [];
-  return boxed("QDash QCal Evidence", [
-    `id ${evidence.id ?? "n/a"}`,
-    `source ${evidence.source}`,
-    `target ${evidence.target?.id ?? evidence.target?.couplingId ?? evidence.target?.qids ?? "n/a"}`,
-    `task ${evidence.task?.name ?? "n/a"} (${evidence.task?.status ?? "unknown"})`,
-    "",
-    "Metrics",
-    ...(metrics.length ? metrics : ["  - none"]),
-    "",
-    `Figures ${figures.length}`,
-    ...figures.map((figure, index) => `  - #${index + 1} ${String(figure.role ?? "plot")} ${String(figure.path ?? figure.url ?? "")}`),
-    "",
-    "Pass this summary as the context of qcal_evaluate; the embedded figure is the measured result to judge.",
-  ]).join("\n");
+/**
+ * The evidence text, used as the context of `qcal_evaluate`: the task, the
+ * target, the sweep and the run settings. Fitted results and calibration
+ * inputs are left out unless asked for, since the evaluation model is meant
+ * to read them off the plot.
+ */
+function qcalEvidenceText(evidence: CalibrationEvidence, include: { inputs?: boolean; metrics?: boolean } = {}): string {
+  return qcalContextText({
+    taskName: typeof evidence.task?.name === "string" ? evidence.task.name : undefined,
+    status: typeof evidence.task?.status === "string" ? evidence.task.status : undefined,
+    targetKind: typeof evidence.target?.kind === "string" ? evidence.target.kind : undefined,
+    targetId: typeof evidence.target?.id === "string" ? evidence.target.id : undefined,
+    chipId: typeof evidence.target?.chipId === "string" ? evidence.target.chipId : undefined,
+    runParameters: evidence.runParameters ?? {},
+    ...(include.inputs ? { inputParameters: recordedParameters(evidence.inputParameters) } : {}),
+    ...(include.metrics ? { metrics: recordedParameters(evidence.metricRecords) } : {}),
+    message: typeof evidence.task?.message === "string" ? evidence.task.message : undefined,
+  });
 }
 
 function cleanQuery(values: Record<string, unknown> = {}): Record<string, unknown> {
@@ -2574,7 +2584,7 @@ export default function qdashExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "qdash_build_qcal_evidence",
     label: "QDash Build QCal Evidence",
-    description: "Summarize a QDash task result (target, parameters, metrics, figure analysis) as evidence for pi-qcaleval's qcal_evaluate, returning the task figure as image content.",
+    description: "Summarize a QDash task result (target, sweep and run settings) as evidence for pi-qcaleval's qcal_evaluate, returning the task figure as image content. Fitted results are left out unless includeMetrics is set.",
     promptSnippet: "Summarize a QDash calibration task result as evidence for qcal_evaluate",
     promptGuidelines: [
       "Use qdash_build_qcal_evidence before qcal_evaluate when the user asks to evaluate a QDash calibration task with pi-qcaleval; pass the returned summary as the context of qcal_evaluate.",
@@ -2588,8 +2598,10 @@ export default function qdashExtension(pi: ExtensionAPI) {
       includeFigureAnalysis: Type.Optional(Type.Boolean({ description: "Analyze Plotly JSON figures and include summaries/warnings in notes. Defaults to true." })),
       maxFigures: Type.Optional(Type.Number({ description: "Maximum image figures to embed. Defaults to 1." })),
       includeRawTaskResult: Type.Optional(Type.Boolean({ description: "Include the full raw task result in resultJson. Defaults to false." })),
+      includeInputs: Type.Optional(Type.Boolean({ description: "Add the calibration inputs (previous values) to the evidence text. Defaults to false: the evaluation model reads the plot." })),
+      includeMetrics: Type.Optional(Type.Boolean({ description: "Add the fitted output parameters to the evidence text. Defaults to false: the evaluation model reads the plot." })),
     }),
-    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; taskId: string; includeFigures?: boolean; includeFigureAnalysis?: boolean; maxFigures?: number; includeRawTaskResult?: boolean }) {
+    async execute(_toolCallId, params: { profile?: string; configPath?: string; useEnv?: boolean; taskId: string; includeFigures?: boolean; includeFigureAnalysis?: boolean; maxFigures?: number; includeRawTaskResult?: boolean; includeInputs?: boolean; includeMetrics?: boolean }) {
       const client = await makeClient(params);
       const task = await client.getTaskResult(params.taskId) as unknown as Record<string, unknown>;
       const figures: Array<Record<string, unknown>> = [];
@@ -2634,6 +2646,7 @@ export default function qdashExtension(pi: ExtensionAPI) {
 
       const couplingId = firstStringField(task, ["coupling_id", "couplingId", "qid"]);
       const qid = firstStringField(task, ["qid"]);
+      const runParameters = recordedParameters(task.run_parameters);
       const evidence: CalibrationEvidence = {
         id: params.taskId,
         source: "external",
@@ -2651,9 +2664,14 @@ export default function qdashExtension(pi: ExtensionAPI) {
           startedAt: firstStringField(task, ["start_at", "startAt"]),
           completedAt: firstStringField(task, ["end_at", "endAt"]),
           status: firstStringField(task, ["status"]),
+          message: typeof task.message === "string" && task.message.trim() ? task.message.trim() : undefined,
         },
         metrics: parameterValueRecord(task.output_parameters),
         parameters: { ...parameterValueRecord(task.input_parameters), ...parameterValueRecord(task.run_parameters) },
+        runParameters,
+        sweeps: sweepsOf(runParameters),
+        inputParameters: recordedParameters(task.input_parameters),
+        metricRecords: recordedParameters(task.output_parameters),
         figures: figures.length ? figures : undefined,
         notes: [
           typeof task.message === "string" ? `Task message: ${task.message}` : undefined,
@@ -2669,7 +2687,11 @@ export default function qdashExtension(pi: ExtensionAPI) {
         },
       };
 
-      const result = toTextToolResult(qcalEvidenceText(evidence), { evidence }, { tool: "qdash_build_qcal_evidence", taskId: params.taskId, evidence });
+      const result = toTextToolResult(
+        qcalEvidenceText(evidence, { inputs: params.includeInputs === true, metrics: params.includeMetrics === true }),
+        { evidence },
+        { tool: "qdash_build_qcal_evidence", taskId: params.taskId, evidence },
+      );
       return { ...result, content: [...result.content, ...images] };
     },
   });

package/package.json

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