@hugpy/video-intelligence-ui 0.1.1 → 0.3.0

package/src/video/jobClock.ts

@@ -0,0 +1,104 @@
+/**
+ * k117 — the feed's clock, told honestly.
+ *
+ * THE BUG the operator reported: the Active-Processes feed showed jobs at 875+
+ * minutes in "loading", 25h in "awaiting_capacity", and DONE rows whose timers
+ * kept ticking under a stale stage label ("archiving"). Keeper triage found the
+ * server rows were CORRECT — the "done · 946m · archiving" row had really run
+ * 9.4 seconds. Two client-side lies produced that display:
+ *
+ *   1. The row rendered `elapsedSince(createdAt)` — i.e. `now - created`, a
+ *      ticking AGE — as if it were runtime. For a terminal row that number keeps
+ *      counting for ever; for a live row it conflates a 25h queue wait with a
+ *      9s render.
+ *   2. The row rendered `current_stage` — the last IN-FLIGHT stage — on terminal
+ *      rows, so a finished render was labelled "archiving" permanently.
+ *
+ * The server (video_intel/job_lifecycle.py) now sends the facts this file needs:
+ * FROZEN `run_s`/`queue_wait_s`/`total_s`/`terminal_at` + the true
+ * `terminal_stage` on terminal rows, and `elapsed_in_stage_s` +
+ * `last_progress_at` (with queue wait kept separate) on live ones. Nothing here
+ * derives a duration from `Date.now()` — that is the entire point.
+ *
+ * A row from an older server (or the demo fixtures) carries none of these, so
+ * every helper degrades to the honest fallback: it says AGE, and labels it age,
+ * rather than passing an age off as a runtime.
+ */
+import type { MediaJob } from "./useMediaJobs";
+
+/** Seconds as "9.4s" / "3m 4s" / "1h 02m" — compact, never lossy about scale. */
+export function fmtDuration(secs: number | null): string {
+  if (secs == null || !isFinite(secs) || secs < 0) return "";
+  if (secs < 10) return `${secs.toFixed(1)}s`;
+  const s = Math.floor(secs);
+  if (s < 60) return `${s}s`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ${s % 60}s`;
+  const h = Math.floor(s / 3600);
+  return `${h}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
+}
+
+/**
+ * The stage label for a row. A TERMINAL row says what it ended as ("done",
+ * "failed", "cancelled") — never the stage it happened to be in when it ended.
+ * That stage is still available (`atStage`) and the expanded timeline shows it;
+ * it is simply no longer allowed to masquerade as a current stage.
+ */
+export function jobStageLabel(job: MediaJob): string {
+  const raw = job.terminal ? job.terminalStage ?? job.status : job.stage;
+  return raw ? raw.replace(/_/g, " ") : "";
+}
+
+/**
+ * The stage a TERMINAL job was in when it ended, for the secondary "(in
+ * archiving)" note — empty when it adds nothing (a job that ended in no stage,
+ * or whose last stage is the outcome itself).
+ */
+export function terminalAtStage(job: MediaJob): string {
+  if (!job.terminal) return "";
+  const at = job.atStage;
+  if (!at || at === job.terminalStage || at === job.status) return "";
+  return at.replace(/_/g, " ");
+}
+
+/**
+ * The clock chips for one row, in display order.
+ *
+ * TERMINAL: exactly one FROZEN duration — how long it actually ran — plus the
+ * queue wait when there was a meaningful one. Nothing ticks.
+ *
+ * LIVE: the two clocks kept APART, which is the whole fix: time in the CURRENT
+ * stage, and the queue wait, as separate facts. A 9s render that waited 25h
+ * reads as "queued 25h" + "in generating 9s", never as "875m".
+ */
+export function jobClockParts(job: MediaJob): string[] {
+  const out: string[] = [];
+  if (job.terminal) {
+    if (job.runS != null) {
+      out.push(`ran ${fmtDuration(job.runS)}`);
+      // Only worth showing when the wait was a real part of the story.
+      if (job.queueWaitS != null && job.queueWaitS >= 5)
+        out.push(`queued ${fmtDuration(job.queueWaitS)}`);
+      return out;
+    }
+    // No recorded start (a pre-k117 row whose runner wrote no stage entries):
+    // the total span is known, the queue/run split is not. Say "took", which is
+    // true of the whole span, rather than inventing a runtime.
+    if (job.totalS != null) return [`took ${fmtDuration(job.totalS)}`];
+    // Older server / demo fixture: say AGE, and say that it is age.
+    const age = ageSeconds(job.createdAt);
+    return age == null ? [] : [`${fmtDuration(age)} ago`];
+  }
+  if (job.elapsedInStageS != null && job.stage)
+    out.push(`in ${job.stage.replace(/_/g, " ")} ${fmtDuration(job.elapsedInStageS)}`);
+  if (job.queueWaitS != null && job.queueWaitS >= 1)
+    out.push(`queued ${fmtDuration(job.queueWaitS)}`);
+  if (job.runS != null && job.runS >= 1) out.push(`running ${fmtDuration(job.runS)}`);
+  if (out.length) return out;
+  const age = ageSeconds(job.createdAt);
+  return age == null ? [] : [`${fmtDuration(age)} ago`];
+}
+
+function ageSeconds(createdAt: number | null): number | null {
+  if (createdAt == null) return null;
+  return Math.max(0, Date.now() / 1000 - createdAt);
+}

package/src/video/spreadAssist.ts

@@ -43,11 +43,25 @@ export interface IdentityContextWire {
   do_not_invent?: string[];
 }
 
+/**
+ * k93 §C — ONE reference media the assist is given as PRETEXT. The backend
+ * samples ≤ 4 frames of a video (one description for an image), describes them
+ * with a vision model and prepends a "Reference video: …" paragraph to the
+ * assist prompt. `uri` is the library uri; `mime` "video/mp4" | "image/*".
+ */
+export interface AssistMediaWire {
+  uri: string;
+  mime: string;
+  label?: string;
+}
+
 /** The typed `context` object shared by detail/generate/negative/spread. */
 export interface AssistContextWire {
   kind?: "image" | "scene" | "movie";
   /** FREE-FORM user text only — structured row state rides the typed fields (§1c). */
   hint?: string;
+  /** Optional reference media described server-side as pretext (k93 §C). */
+  media?: AssistMediaWire;
   segment?: SegmentRefWire;
   previous_segment?: SegmentRefWire;
   next_segment?: SegmentRefWire;
@@ -75,6 +89,10 @@ export interface SpreadSegmentResult {
   continuity_note: string;
   directions_used: unknown[];
   warnings: string[];
+  /** k121: the knob values the coordination review APPLIED to this row
+      (joint_mode / parent_segment_id / branch_frame / seed / frames /
+      reference_images). Mechanics only — never prose (invariant 9). */
+  knobs: Record<string, unknown>;
 }
 
 /** The parsed 200 body of a spread call. */
@@ -89,6 +107,9 @@ export interface SpreadResult {
   model: string | null;
   model_requested: string | null;
   model_resolved: string | null;
+  /** k121: the words-vs-knobs review of the whole set. Read it with
+      `readCoordinationReport` (video/coordinationReport.ts). */
+  coordination: unknown;
 }
 
 // ── intent routing (§1d) ────────────────────────────────────────────────────
@@ -300,6 +321,10 @@ export function readSpreadResult(value: unknown): SpreadResult | null {
       continuity_note: str(r.continuity_note).trim(),
       directions_used: Array.isArray(r.directions_used) ? r.directions_used : [],
       warnings: strArray(r.warnings),
+      knobs:
+        r.knobs != null && typeof r.knobs === "object" && !Array.isArray(r.knobs)
+          ? (r.knobs as Record<string, unknown>)
+          : {},
     });
   }
   const seed = v.steering_seed;
@@ -316,6 +341,7 @@ export function readSpreadResult(value: unknown): SpreadResult | null {
     model: typeof v.model === "string" ? v.model : null,
     model_requested: typeof v.model_requested === "string" ? v.model_requested : null,
     model_resolved: typeof v.model_resolved === "string" ? v.model_resolved : null,
+    coordination: v.coordination ?? null,
   };
 }
 

package/src/video/useMediaJobs.ts

@@ -68,6 +68,22 @@ export interface MediaJob {
   failure: JobFailure | null;
   terminal: boolean; // done | failed | cancelled (only present with the history filter)
   progressedAt: number | null; // last REAL movement (the stall/stale basis)
+  // ---- k117 LIFECYCLE CLOCK (video_intel/job_lifecycle.py) ----------------
+  // The feed used to render `now - created` as if it were runtime, so a 9.4s
+  // render created 946 minutes ago read as "946m · archiving". These are the
+  // server's own facts, computed ONCE at the terminal transition and therefore
+  // FROZEN: nothing below is a function of the browser's clock. Null on a row
+  // from an older server (or a demo fixture) — see video/jobClock.ts for the
+  // honest fallback.
+  terminalAt: number | null; // when it ended (epoch seconds); null while live
+  terminalStage: string | null; // the TRUE outcome: done | failed | cancelled
+  atStage: string | null; // the live stage it was in when it ended ("archiving")
+  startedAt: number | null; // when the run actually began
+  queueWaitS: number | null; // time spent waiting, kept SEPARATE from runtime
+  runS: number | null; // frozen runtime when terminal; time-so-far while running
+  totalS: number | null; // queue + run, terminal only
+  elapsedInStageS: number | null; // time in the CURRENT stage (live rows only)
+  lastProgressAt: number | null; // last reported progress (epoch seconds)
 }
 
 function str(v: unknown): string | null {
@@ -170,6 +186,16 @@ function parseJobs(raw: unknown, includeTerminal: boolean): MediaJob[] {
       failure: parseFailure(row.failure),
       terminal,
       progressedAt: num(row.progressed_at) ?? num(row.last_movement_ts),
+      // k117 — read verbatim; never derived here (deriving is what lied).
+      terminalAt: num(row.terminal_at),
+      terminalStage: str(row.terminal_stage),
+      atStage: str(row.at_stage),
+      startedAt: num(row.started_at),
+      queueWaitS: num(row.queue_wait_s),
+      runS: num(row.run_s),
+      totalS: num(row.total_s),
+      elapsedInStageS: num(row.elapsed_in_stage_s),
+      lastProgressAt: num(row.last_progress_at) ?? num(row.progressed_at),
     });
   }
   return out;

package/src/video/useOperatorHistory.ts

@@ -90,6 +90,11 @@ export function useOperatorHistory(): void {
             genKind: (j.name === "generate_studio_movie"
               ? "generate_movie"
               : j.name) as LibraryGenKind,
+            // groupId = the producing job: each historical run groups as its own
+            // work (like live pushes) instead of one giant shared "history" pile
+            // whose identical key collided ACROSS the type sections (expanding
+            // Videos/history also expanded Images/history).
+            groupId: id,
           });
         }
       }

package/src/video/useToks.ts

@@ -0,0 +1,193 @@
+// LIVE tok/s telemetry for the generate workbench's Toks panel. Polls TWO
+// same-origin `/api` endpoints together every 2s, MOUNT-GATED exactly like
+// `useMediaJobs` (mount → immediate fetch + 2s interval; unmount → interval
+// cleared and a mounted-ref flipped so a late response never setStates). A fetch
+// error keeps the last-good data rather than flashing empty, and every field is
+// guarded — the server side is being built in parallel, so missing/extra fields
+// must never throw.
+//
+//   • GET /api/llm/toks/recent?limit=100 → { entries:[{ ts, worker_id,
+//     worker_name, model_key, tok_s, ttft_s, completion_tokens, config_key, ok }] }
+//     newest-first — the live tail + the per-worker strip.
+//   • GET /api/llm/toks/report → { groups:[{ worker_name, model_key, config_key,
+//     n, mean_tok_s, p50_tok_s, p95_tok_s }] } sorted best mean first — the
+//     best-config leaderboard.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { hugpyConfig } from "../config";
+import { request, okValue } from "../transport/client";
+
+const POLL_MS = 2000;
+const RECENT_LIMIT = 100;
+
+/** One recent inference sample (omit-when-unset tolerated on the wire). */
+export interface TokEntry {
+  ts: number | null; // epoch seconds when the sample was recorded
+  workerId: string | null;
+  workerName: string | null;
+  modelKey: string | null;
+  tokS: number | null; // tokens/second
+  ttftS: number | null; // time-to-first-token, seconds
+  completionTokens: number | null;
+  configKey: string | null;
+  ok: boolean | null;
+}
+
+/** One best-config rollup row from /report. */
+export interface TokGroup {
+  workerName: string | null;
+  modelKey: string | null;
+  configKey: string | null;
+  n: number | null;
+  meanTokS: number | null;
+  p50TokS: number | null;
+  p95TokS: number | null;
+}
+
+function str(v: unknown): string | null {
+  return typeof v === "string" && v.trim() ? v : null;
+}
+function num(v: unknown): number | null {
+  return typeof v === "number" && isFinite(v) ? v : null;
+}
+function bool(v: unknown): boolean | null {
+  return typeof v === "boolean" ? v : null;
+}
+
+function parseEntries(raw: unknown): TokEntry[] {
+  const entries = (raw as { entries?: unknown } | null)?.entries;
+  if (!Array.isArray(entries)) return [];
+  const out: TokEntry[] = [];
+  for (const e of entries) {
+    if (!e || typeof e !== "object") continue;
+    const r = e as Record<string, unknown>;
+    out.push({
+      ts: num(r.ts),
+      workerId: str(r.worker_id),
+      workerName: str(r.worker_name),
+      modelKey: str(r.model_key),
+      tokS: num(r.tok_s),
+      ttftS: num(r.ttft_s),
+      completionTokens: num(r.completion_tokens),
+      configKey: str(r.config_key),
+      ok: bool(r.ok),
+    });
+  }
+  return out;
+}
+
+function parseGroups(raw: unknown): TokGroup[] {
+  const groups = (raw as { groups?: unknown } | null)?.groups;
+  if (!Array.isArray(groups)) return [];
+  const out: TokGroup[] = [];
+  for (const g of groups) {
+    if (!g || typeof g !== "object") continue;
+    const r = g as Record<string, unknown>;
+    out.push({
+      workerName: str(r.worker_name),
+      modelKey: str(r.model_key),
+      configKey: str(r.config_key),
+      n: num(r.n),
+      meanTokS: num(r.mean_tok_s),
+      p50TokS: num(r.p50_tok_s),
+      p95TokS: num(r.p95_tok_s),
+    });
+  }
+  return out;
+}
+
+/**
+ * The live tok/s feed: recent samples (newest-first) + the best-config report,
+ * refreshed together every 2s while a consumer is mounted. `live` reports whether
+ * the last poll cycle succeeded, so the panel can show a live/paused dot.
+ */
+export function useToks(): {
+  entries: TokEntry[];
+  groups: TokGroup[];
+  live: boolean;
+} {
+  const [entries, setEntries] = useState<TokEntry[]>([]);
+  const [groups, setGroups] = useState<TokGroup[]>([]);
+  const [live, setLive] = useState(false);
+  const mounted = useRef(true);
+
+  const load = useCallback(async () => {
+    // Both endpoints in parallel; each is independent, so one failing keeps the
+    // other's last-good data instead of blanking the whole panel.
+    const [recent, report] = await Promise.all([
+      request<unknown>(`${hugpyConfig.toksRecentUrl}?limit=${RECENT_LIMIT}`, {
+        meta: { specKey: "llm", operation: "llm.toks.recent" },
+      }),
+      request<unknown>(hugpyConfig.toksReportUrl, {
+        meta: { specKey: "llm", operation: "llm.toks.report" },
+      }),
+    ]);
+    if (!mounted.current) return;
+    if (recent.ok) setEntries(parseEntries(okValue(recent)));
+    if (report.ok) setGroups(parseGroups(okValue(report)));
+    setLive(recent.ok || report.ok);
+  }, []);
+
+  useEffect(() => {
+    mounted.current = true;
+    void load();
+    const id = window.setInterval(() => void load(), POLL_MS);
+    return () => {
+      mounted.current = false;
+      window.clearInterval(id);
+    };
+  }, [load]);
+
+  return { entries, groups, live };
+}
+
+/** The poll cadence, exported so the panel header can label it ("every 2s"). */
+export const TOKS_POLL_MS = POLL_MS;
+
+/** "12s ago" / "3m ago" from an epoch-seconds ts, "" when unknown. */
+export function tokAgo(ts: number | null, nowMs: number): string {
+  if (ts == null) return "";
+  const secs = Math.max(0, Math.floor(nowMs / 1000 - ts));
+  if (secs < 60) return `${secs}s ago`;
+  if (secs < 3600) return `${Math.floor(secs / 60)}m ago`;
+  return `${Math.floor(secs / 3600)}h ago`;
+}
+
+/** Group recent entries by worker → { last tok/s, avg tok/s over the window }. */
+export interface WorkerRollup {
+  workerId: string;
+  workerName: string;
+  modelKey: string | null;
+  lastTokS: number | null;
+  avgTokS: number | null;
+  n: number;
+}
+
+export function rollupByWorker(entries: TokEntry[]): WorkerRollup[] {
+  const byWorker = new Map<string, TokEntry[]>();
+  for (const e of entries) {
+    const key = e.workerId ?? e.workerName;
+    if (!key) continue;
+    const list = byWorker.get(key);
+    if (list) list.push(e);
+    else byWorker.set(key, [e]);
+  }
+  const out: WorkerRollup[] = [];
+  for (const [key, list] of byWorker) {
+    // Entries arrive newest-first, so the first tok_s we see is the latest.
+    const samples = list.map((e) => e.tokS).filter((v): v is number => v != null);
+    const avg =
+      samples.length > 0
+        ? samples.reduce((a, b) => a + b, 0) / samples.length
+        : null;
+    const first = list[0];
+    out.push({
+      workerId: key,
+      workerName: first?.workerName ?? key,
+      modelKey: first?.modelKey ?? null,
+      lastTokS: samples.length > 0 ? samples[0] : null,
+      avgTokS: avg,
+      n: list.length,
+    });
+  }
+  return out;
+}