@oqtopus-team/pi-qdash 0.1.4 → 0.1.6

package/README.md

@@ -20,7 +20,8 @@ It uses [`@oqtopus-team/qdash-client`](https://www.npmjs.com/package/@oqtopus-te
 - **Dashboards and insights**: compact dashboards, triage overviews, target-level incident reports, degradation reports, and wiring insights.
 - **Agent calibration workflow**: create agent sessions, submit and track agent actions, and commit/apply calibration candidates. Write operations are approval-gated.
 - **Figures**: fetch calibration PNG/JSON figures and render them in the interactive TUI.
-- **Forum integration**: read Forum posts and publish evidence replies built from task results.
+- **Generic timeseries comparison**: inspect and align arbitrary QDash parameters/targets with explicitly mapped local CSV sensor columns, reuse schema-validated investigation presets, and report correlations plus optional shared-period/phase evidence without hard-coded metrics or schemas.
+- **Forum integration**: read Forum posts, publish task-result evidence, and upload locally generated analysis images to replies.
 
 ## Installation
 
@@ -42,7 +43,9 @@ Or try it without installing:
 pi -e npm:@oqtopus-team/pi-qdash
 ```
 
-Requires pi v0.74.0 or later.
+Requires Node.js 20 or later and pi v0.74.0 or later. The extension tracks
+`@oqtopus-team/qdash-client` 1.9.x and uses its authenticated high-level and
+generated API clients.
 
 ## Quick Start
 

package/extensions/lib/forum-images.ts

@@ -0,0 +1,82 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname, resolve } from "node:path";
+
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_IMAGES_PER_REPLY = 8;
+const IMAGE_TYPES: Record<string, string> = {
+  ".gif": "image/gif",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+};
+
+export type LocalForumImage = {
+  path: string;
+  filename: string;
+  mimeType: string;
+  sizeBytes: number;
+  blob: Blob;
+};
+
+export type UploadedForumImage = Omit<LocalForumImage, "blob"> & { url: string };
+
+export function loadLocalForumImages(paths: string[]): LocalForumImage[] {
+  if (paths.length === 0) throw new Error("At least one image path is required");
+  if (paths.length > MAX_IMAGES_PER_REPLY) {
+    throw new Error(`A forum image reply supports at most ${MAX_IMAGES_PER_REPLY} images`);
+  }
+
+  const uniquePaths = [...new Set(paths.map((path) => resolve(path)))];
+  if (uniquePaths.length !== paths.length) throw new Error("Duplicate image paths are not allowed");
+
+  return uniquePaths.map((path) => {
+    const mimeType = IMAGE_TYPES[extname(path).toLowerCase()];
+    if (!mimeType) throw new Error(`Unsupported forum image type: ${path}`);
+    const stat = statSync(path);
+    if (!stat.isFile()) throw new Error(`Forum image path is not a file: ${path}`);
+    if (stat.size > MAX_IMAGE_BYTES) throw new Error(`Forum image exceeds 5 MB: ${path}`);
+    const bytes = readFileSync(path);
+    return {
+      path,
+      filename: basename(path),
+      mimeType,
+      sizeBytes: stat.size,
+      blob: new Blob([new Uint8Array(bytes)], { type: mimeType }),
+    };
+  });
+}
+
+export function forumImageReplyContent(
+  title: string,
+  images: Array<{ filename: string; url: string }>,
+  interpretation: string,
+): string {
+  return [
+    `## ${title}`,
+    "",
+    "分析で作成した画像を追加します。",
+    "",
+    ...images.flatMap((image) => [`![${image.filename}](${image.url})`, ""]),
+    interpretation.trim(),
+    "",
+    "— 🤖 by pi-qdash",
+  ].join("\n");
+}
+
+export function forumImageReplyPreview(
+  title: string,
+  images: Array<{ path: string; filename: string; sizeBytes: number }>,
+  interpretation: string,
+): string {
+  return [
+    `## ${title}`,
+    "",
+    "The following local images will be uploaded to QDash and embedded in a forum reply:",
+    ...images.map((image) => `- ${image.filename} (${(image.sizeBytes / 1024).toFixed(1)} KiB) — ${image.path}`),
+    "",
+    interpretation.trim(),
+    "",
+    "— 🤖 by pi-qdash",
+  ].join("\n");
+}

package/extensions/lib/investigation-context.ts

@@ -0,0 +1,169 @@
+import type { CsvTimeFormat, ExternalCsvSpec, TimeseriesTransformOptions } from "./timeseries-analysis.js";
+
+export type InvestigationQDashSeries = {
+  parameter: string;
+  qid?: string;
+  tag?: string;
+  label?: string;
+  unit?: string;
+  scale?: number;
+  offset?: number;
+};
+
+export type TimeseriesInvestigationContext = {
+  name?: string;
+  startAt?: string;
+  endAt?: string;
+  timezoneOffsetMinutes?: number;
+  tag?: string;
+  qdashSeries?: InvestigationQDashSeries[];
+  csvSeries?: ExternalCsvSpec[];
+  analysis?: Omit<TimeseriesTransformOptions, "startAt" | "endAt" | "includeAlignedData">;
+};
+
+const TIME_FORMATS: CsvTimeFormat[] = ["iso", "yyyy/M/d H:mm", "yyyy-MM-dd HH:mm:ss", "unix-seconds", "unix-milliseconds"];
+
+function optionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${path} must be a non-empty string`);
+  return value.trim();
+}
+
+function requiredString(value: unknown, path: string): string {
+  const result = optionalString(value, path);
+  if (result === undefined) throw new Error(`${path} is required`);
+  return result;
+}
+
+function optionalNumber(value: unknown, path: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${path} must be a finite number`);
+  return value;
+}
+
+function validateIso(value: string | undefined, path: string): void {
+  if (value !== undefined && !Number.isFinite(Date.parse(value))) throw new Error(`${path} must be a valid ISO timestamp`);
+}
+
+function validateQDashSeries(value: unknown): InvestigationQDashSeries[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 12) throw new Error("investigation.qdashSeries must be an array with at most 12 entries");
+  return value.map((item, index) => {
+    if (!item || typeof item !== "object") throw new Error(`investigation.qdashSeries[${index}] must be an object`);
+    const input = item as Record<string, unknown>;
+    return {
+      parameter: requiredString(input.parameter, `investigation.qdashSeries[${index}].parameter`),
+      qid: optionalString(input.qid, `investigation.qdashSeries[${index}].qid`),
+      tag: optionalString(input.tag, `investigation.qdashSeries[${index}].tag`),
+      label: optionalString(input.label, `investigation.qdashSeries[${index}].label`),
+      unit: optionalString(input.unit, `investigation.qdashSeries[${index}].unit`),
+      scale: optionalNumber(input.scale, `investigation.qdashSeries[${index}].scale`),
+      offset: optionalNumber(input.offset, `investigation.qdashSeries[${index}].offset`),
+    };
+  });
+}
+
+function validateCsvSeries(value: unknown): ExternalCsvSpec[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length > 8) throw new Error("investigation.csvSeries must be an array with at most 8 entries");
+  return value.map((item, index) => {
+    if (!item || typeof item !== "object") throw new Error(`investigation.csvSeries[${index}] must be an object`);
+    const input = item as Record<string, unknown>;
+    if (!Array.isArray(input.valueColumns) || input.valueColumns.length < 1 || input.valueColumns.length > 12) {
+      throw new Error(`investigation.csvSeries[${index}].valueColumns must contain 1 to 12 entries`);
+    }
+    const timeFormat = optionalString(input.timeFormat, `investigation.csvSeries[${index}].timeFormat`) as CsvTimeFormat | undefined;
+    if (timeFormat && !TIME_FORMATS.includes(timeFormat)) throw new Error(`Unsupported investigation.csvSeries[${index}].timeFormat: ${timeFormat}`);
+    const filters = input.filters === undefined ? undefined : input.filters;
+    if (filters !== undefined && (!filters || typeof filters !== "object" || Array.isArray(filters))) {
+      throw new Error(`investigation.csvSeries[${index}].filters must be an object of string arrays`);
+    }
+    const validatedFilters = filters === undefined ? undefined : Object.fromEntries(Object.entries(filters as Record<string, unknown>).map(([column, accepted]) => {
+      if (!Array.isArray(accepted) || !accepted.every((entry) => typeof entry === "string")) throw new Error(`investigation.csvSeries[${index}].filters.${column} must be a string array`);
+      return [column, accepted];
+    }));
+    return {
+      path: requiredString(input.path, `investigation.csvSeries[${index}].path`),
+      timeColumn: requiredString(input.timeColumn, `investigation.csvSeries[${index}].timeColumn`),
+      timeFormat,
+      timezoneOffsetMinutes: optionalNumber(input.timezoneOffsetMinutes, `investigation.csvSeries[${index}].timezoneOffsetMinutes`),
+      delimiter: optionalString(input.delimiter, `investigation.csvSeries[${index}].delimiter`),
+      skipRows: optionalNumber(input.skipRows, `investigation.csvSeries[${index}].skipRows`),
+      filters: validatedFilters,
+      valueColumns: input.valueColumns.map((entry, columnIndex) => {
+        if (!entry || typeof entry !== "object") throw new Error(`investigation.csvSeries[${index}].valueColumns[${columnIndex}] must be an object`);
+        const column = entry as Record<string, unknown>;
+        return {
+          column: requiredString(column.column, `investigation.csvSeries[${index}].valueColumns[${columnIndex}].column`),
+          label: optionalString(column.label, `investigation.csvSeries[${index}].valueColumns[${columnIndex}].label`),
+          unit: optionalString(column.unit, `investigation.csvSeries[${index}].valueColumns[${columnIndex}].unit`),
+          scale: optionalNumber(column.scale, `investigation.csvSeries[${index}].valueColumns[${columnIndex}].scale`),
+          offset: optionalNumber(column.offset, `investigation.csvSeries[${index}].valueColumns[${columnIndex}].offset`),
+        };
+      }),
+    };
+  });
+}
+
+function validateAnalysis(value: unknown): TimeseriesInvestigationContext["analysis"] {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("investigation.analysis must be an object");
+  const input = value as Record<string, unknown>;
+  const detrend = optionalString(input.detrend, "investigation.analysis.detrend");
+  const normalize = optionalString(input.normalize, "investigation.analysis.normalize");
+  if (detrend && detrend !== "none" && detrend !== "linear") throw new Error("investigation.analysis.detrend must be none or linear");
+  if (normalize && normalize !== "none" && normalize !== "zscore") throw new Error("investigation.analysis.normalize must be none or zscore");
+  let periodSearch: { minMinutes: number; maxMinutes: number; stepMinutes?: number } | undefined;
+  if (input.periodSearch !== undefined) {
+    if (!input.periodSearch || typeof input.periodSearch !== "object" || Array.isArray(input.periodSearch)) throw new Error("investigation.analysis.periodSearch must be an object");
+    const period = input.periodSearch as Record<string, unknown>;
+    const minMinutes = optionalNumber(period.minMinutes, "investigation.analysis.periodSearch.minMinutes");
+    const maxMinutes = optionalNumber(period.maxMinutes, "investigation.analysis.periodSearch.maxMinutes");
+    if (minMinutes === undefined || maxMinutes === undefined || minMinutes <= 0 || maxMinutes <= minMinutes) throw new Error("investigation.analysis.periodSearch requires 0 < minMinutes < maxMinutes");
+    periodSearch = { minMinutes, maxMinutes, stepMinutes: optionalNumber(period.stepMinutes, "investigation.analysis.periodSearch.stepMinutes") };
+  }
+  const analysis: TimeseriesInvestigationContext["analysis"] = {
+    resampleMinutes: optionalNumber(input.resampleMinutes, "investigation.analysis.resampleMinutes"),
+    smoothingWindowMinutes: optionalNumber(input.smoothingWindowMinutes, "investigation.analysis.smoothingWindowMinutes"),
+    detrend: detrend as "none" | "linear" | undefined,
+    normalize: normalize as "none" | "zscore" | undefined,
+    maxInterpolationGapMinutes: optionalNumber(input.maxInterpolationGapMinutes, "investigation.analysis.maxInterpolationGapMinutes"),
+    periodSearch,
+  };
+  if (analysis.resampleMinutes !== undefined && analysis.resampleMinutes <= 0) throw new Error("investigation.analysis.resampleMinutes must be greater than zero");
+  if (analysis.smoothingWindowMinutes !== undefined && analysis.smoothingWindowMinutes < 0) throw new Error("investigation.analysis.smoothingWindowMinutes must not be negative");
+  if (analysis.maxInterpolationGapMinutes !== undefined && analysis.maxInterpolationGapMinutes <= 0) throw new Error("investigation.analysis.maxInterpolationGapMinutes must be greater than zero");
+  if (analysis.periodSearch?.stepMinutes !== undefined && analysis.periodSearch.stepMinutes <= 0) throw new Error("investigation.analysis.periodSearch.stepMinutes must be greater than zero");
+  return analysis;
+}
+
+export function validateInvestigationContext(value: unknown): TimeseriesInvestigationContext {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("investigation context must be a JSON object");
+  const input = value as Record<string, unknown>;
+  const context: TimeseriesInvestigationContext = {
+    name: optionalString(input.name, "investigation.name"),
+    startAt: optionalString(input.startAt, "investigation.startAt"),
+    endAt: optionalString(input.endAt, "investigation.endAt"),
+    timezoneOffsetMinutes: optionalNumber(input.timezoneOffsetMinutes, "investigation.timezoneOffsetMinutes"),
+    tag: optionalString(input.tag, "investigation.tag"),
+    qdashSeries: validateQDashSeries(input.qdashSeries),
+    csvSeries: validateCsvSeries(input.csvSeries),
+    analysis: validateAnalysis(input.analysis),
+  };
+  validateIso(context.startAt, "investigation.startAt");
+  validateIso(context.endAt, "investigation.endAt");
+  if (context.startAt && context.endAt && Date.parse(context.startAt) >= Date.parse(context.endAt)) throw new Error("investigation.startAt must be before endAt");
+  if (context.timezoneOffsetMinutes !== undefined && (!Number.isInteger(context.timezoneOffsetMinutes) || Math.abs(context.timezoneOffsetMinutes) > 14 * 60)) {
+    throw new Error("investigation.timezoneOffsetMinutes must be an integer from -840 to 840");
+  }
+  if ((context.qdashSeries?.length ?? 0) + (context.csvSeries?.flatMap((series) => series.valueColumns).length ?? 0) < 2) {
+    throw new Error("investigation context must define at least two QDash/CSV value series");
+  }
+  return context;
+}
+
+export function investigationContextSummary(context: TimeseriesInvestigationContext): string {
+  const qdashCount = context.qdashSeries?.length ?? 0;
+  const csvCount = context.csvSeries?.reduce((sum, series) => sum + series.valueColumns.length, 0) ?? 0;
+  return `${context.name ?? "unnamed"}: ${qdashCount + csvCount} series, ${context.startAt ?? "auto-start"} → ${context.endAt ?? "auto-end"}${context.tag ? `, tag ${context.tag}` : ""}`;
+}