@oqtopus-team/pi-qdash 0.1.3 → 0.1.5

package/skills/qdash/SKILL.md

@@ -15,15 +15,16 @@ Use the pi-qdash tools instead of scraping the UI or hand-writing auth headers.
    - `qdash_get_chip_metrics`, `qdash_list_chip_qubits`, `qdash_list_chip_couplings`
    - `qdash_list_cryostats`, `qdash_list_cooldowns`
    - `qdash_get_cooldown_wiring`, `qdash_wiring_insights`, `qdash_list_cooldown_wiring_events`
-   - `qdash_get_timeseries`, `qdash_plot_timeseries`
+   - `qdash_get_timeseries`, `qdash_plot_timeseries`, `qdash_inspect_timeseries_csv`, `qdash_compare_timeseries`
    - `qdash_list_task_results`, `qdash_get_task_result`
    - `qdash_list_issues`
    - `qdash_list_flows`, `qdash_get_flow`
    - `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_analyze_figure_json`
+   - `qdash_get_figure`, `qdash_get_task_figures`, `qdash_recent_calibration_figure`, `qdash_analyze_figure_json`, `qdash_build_qcal_evidence`
    - `qdash_create_forum_evidence_reply` for confirmed evidence curation replies with visible task figures
+   - `qdash_preview_forum_image_reply`, then `qdash_create_forum_image_reply` for confirmed uploads of locally generated analysis images
 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
    - `qdash_compare_calibration` for read-only before/after comparison of repeated target calibration results
@@ -64,6 +65,8 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 /qdash-use-chip [chip_id]
 /qdash-use-target qid <qid> | coupling <coupling_id>
 /qdash-use-agent-session <session_id>
+/qdash-investigation-setup [json]
+/qdash-clear-investigation
 /qdash-context
 /qdash-dashboard [limit]
 /qdash-wiring-insights
@@ -73,6 +76,29 @@ Use these commands to make pi behave like a QDash-specific harness with persiste
 
 Prefer the current context when the user has already selected a profile/chip/session. Tools use that context when parameters are omitted.
 
+## Generic timeseries comparison
+
+Use `qdash_compare_timeseries` when the investigation needs to align multiple
+QDash metrics/targets, local CSV sensor logs, or both. For repeated calls, use
+`/qdash-investigation-setup` to store the arbitrary series mappings, window,
+timezone, and transform defaults; explicit tool arguments override the preset.
+Do not assume a specific
+CSV layout, metric name, target, unit, timestamp format, or timezone:
+
+1. Inspect unknown CSV headers, numeric coverage, and optional time cadence with
+   `qdash_inspect_timeseries_csv` first.
+2. Supply `timeColumn`, one or more `valueColumns`, and optional exact-match
+   `filters`; use `scale`/`offset` only for explicit unit conversion.
+3. For timestamps without a zone, require an explicit
+   `timezoneOffsetMinutes` (JST is `540`) rather than relying on the host clock.
+4. Start with raw/no-transform comparison, then state any smoothing,
+   interpolation, detrending, normalization, and period-search settings.
+5. Report overlap duration, source point counts, aligned point count, number of
+   observed cycles, correlations, phases, and explained fractions together.
+6. Treat correlation and shared periodicity as evidence of association. Do not
+   claim direct causality without intervention, longer observation, or evidence
+   that excludes a common driver.
+
 For cryostat wiring requests, start with `qdash_get_cooldown_wiring`. Pass `cooldownId` when the user names one; otherwise pass `cryoId`, or omit both to resolve the active/newest cooldown from the current/default chip. Prefer the compact `wiring.markdown`; request raw blocks only when structural or embedded BlockNote data is necessary, and request history when investigating wiring changes. Set `includeInsights` or call `qdash_wiring_insights` when the user asks what is characteristic, unusual, or worth checking in attenuation; summarize control/readout totals and affected qubits/MUXes instead of dumping the raw table.
 
 ## Configuration
@@ -94,10 +120,11 @@ When the user wants to preserve an investigated observation in QDash forum/notes
 2. Summarize the observation as evidence, not as an automatic calibration decision.
 3. Prefer replying to an existing target/coupling forum thread when one exists.
 4. Use `qdash_create_forum_evidence_reply` for task-result evidence so figures are embedded as QDash UI image blocks (`/api/executions/figure?path=...`) and visible in the forum.
-5. Include task and execution QDash Web URLs in the reply.
-6. When mentioning history or trends, include links to representative historical task results.
-7. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
-8. Ask for confirmation before creating/updating the forum post.
+5. For locally generated analysis images, call `qdash_preview_forum_image_reply` first, show the exact paths and reply text, then use `qdash_create_forum_image_reply` only after explicit confirmation. Supported images are PNG, JPEG, GIF, and WebP up to 5 MB each.
+6. Include task and execution QDash Web URLs in the reply when applicable.
+7. When mentioning history or trends, include links to representative historical task results.
+8. Mark agent-authored evidence with a footer such as `— 🤖 by pi-qdash`.
+9. Ask for confirmation before uploading images or creating/updating the forum post.
 
 ## Safety
 
@@ -108,4 +135,5 @@ When the user wants to preserve an investigated observation in QDash forum/notes
 - 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.
+- Use `qdash_build_qcal_evidence` when the user wants to evaluate a QDash calibration task with pi-qcal. It only converts QDash data into provider-neutral `CalibrationEvidence`; pass `details.evidence` to `qcal_evaluate_bundle` for the actual evaluation.
 - Prefer summarizing large responses with counts, IDs, time ranges, and notable values.

package/skills/qdash-timeseries-diagnosis/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: qdash-timeseries-diagnosis
+description: Diagnose common-mode drift, shared periodicity, phase relationships, and possible environmental coupling across arbitrary QDash metrics and external sensor CSV logs. Use when calibration metrics oscillate, drift together, appear delayed or anti-correlated, or may be influenced by cryostat/environmental cycles.
+---
+
+# QDash Timeseries Diagnosis
+
+Use this skill for evidence-based multi-timeseries investigation. Keep the
+measurement schema and physical interpretation separate: the comparison tool
+extracts mechanical evidence, while this skill guides conclusions and next
+checks.
+
+## Principles
+
+- Do not hard-code metric names, targets, sensors, units, CSV columns, periods,
+  or timezone assumptions.
+- Preserve both raw and transformed results. A visually clean transformed plot
+  must not replace the raw evidence.
+- Correlation, shared periodicity, and phase alignment establish association,
+  not causal direction.
+- Consider a shared driver when multiple targets and an environmental sensor
+  move together. The sensor itself may be a proxy for an unmeasured actuator,
+  vibration, electrical noise, magnetic noise, or control cycle.
+- Count observed cycles, not raw sample points, when judging periodic evidence.
+
+## Workflow
+
+### 1. Fix the investigation scope
+
+Record the reusable scope with `/qdash-investigation-setup` when multiple
+comparison passes are expected. The JSON context accepts arbitrary QDash
+series, CSV mappings, window/timezone, and transform defaults. Record:
+
+- QDash profile and chip
+- metrics and target IDs
+- tags
+- start/end timestamps
+- timezone for every source
+- expected cadence and units
+- local CSV path, time column, value columns, and any row filters
+
+For timestamps without an explicit zone, require a declared offset. Never infer
+a timezone from the host machine.
+
+### 2. Inspect source integrity
+
+Before comparing, use `qdash_inspect_timeseries_csv` for local files whose
+schema or time encoding is not already established. Then:
+
+- verify first/last timestamps and overlap
+- check source point counts and cadence
+- identify duplicate timestamps, missing intervals, and long gaps
+- verify scale and offset conversions
+- ensure labels are unique
+
+Do not bridge long outages. Set `maxInterpolationGapMinutes` explicitly when the
+default is unsuitable for the slowest source.
+
+### 3. Establish a raw baseline
+
+Call `qdash_compare_timeseries` first with:
+
+- no smoothing
+- no detrending
+- no normalization
+- no period search unless a period was specified independently
+
+Report ranges, units, overlap, and raw correlation. Different units are fine for
+correlation, but do not visually overlay incomparable scales without separate
+axes or normalization.
+
+### 4. Compare oscillatory components
+
+When looking for common cycles, rerun with explicit settings such as:
+
+- a smoothing window justified by source cadence
+- `detrend: linear` when slow drift would dominate
+- `normalize: zscore` for shape/phase comparison
+- a period-search range chosen from prior evidence or a broad physically
+  plausible interval
+
+Report all transform settings with the result. Compare:
+
+- full transformed correlation
+- selected shared period
+- per-series periodic explained fraction
+- pairwise phase differences
+- observed cycle count
+
+A near-0° phase difference indicates in-phase periodic components. A near-180°
+difference indicates anti-phase components. Intermediate phase may represent a
+delay, but phase alone does not identify response direction.
+
+### 5. Grade the evidence conservatively
+
+Use qualitative language:
+
+- **weak**: unstable period/phase, low explained fraction, or fewer than about
+  three observed cycles
+- **suggestive**: similar periods with plausible phase but short observation or
+  substantial residual variation
+- **strong association**: repeated common period and stable phase across
+  multiple targets/sensors, with substantial explained fractions
+- **causal evidence**: requires intervention, independently controlled input,
+  repeated response, or evidence excluding plausible shared drivers
+
+These are reasoning categories, not fixed acceptance thresholds. Explain which
+facts support the chosen category.
+
+### 6. Test alternatives
+
+For apparent environmental or cryostat coupling, distinguish:
+
+1. the measured sensor variable directly affecting the metric
+2. a controller/refrigerator cycle affecting both
+3. periodic measurement or scheduling artifacts
+4. timestamp offset or resampling artifacts
+5. target-local behavior coincidentally near the same frequency
+
+Check additional targets in different control/readout groups and, when
+available, actuator state, compressor/pulse-tube, vibration, rack temperature,
+magnetic field, pressure, and control-system logs.
+
+### 7. Recommend discriminating measurements
+
+Prefer measurements that separate hypotheses:
+
+- extend observation to cover at least 8–10 candidate cycles
+- preserve the same cadence and synchronized clocks
+- record actuator/controller state in addition to sensor output
+- test multiple targets and control/readout groups
+- perform a safe controlled setpoint or operating-state change when authorized
+- compare lag/phase stability across independent runs
+
+Do not initiate operational changes without an explicit plan and user
+confirmation.
+
+## Reporting template
+
+Include:
+
+1. sources and exact time window
+2. timezone and unit conversions
+3. raw-data integrity and overlap
+4. transformation settings
+5. raw/transformed correlations
+6. shared period, phase, explained fraction, and observed cycles
+7. strongest association statement
+8. causal alternatives still open
+9. next measurement that best discriminates those alternatives