@railtownai/railtracks-visualizer 0.0.69 → 0.0.71

package/dist/types/agenthub/components/CategoricalAggregateView.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Categorical evaluator view: one card per categorical metric, with collapsible
+ * accordions per category label listing the agent nodes that received that label.
+ * Each node exposes Session Details / Visualizer call-to-actions (see NodeActions)
+ * and an inline toggle to reveal reasoning when present.
+ *
+ * Generic over any evaluator that produces categorical metrics. The built-in
+ * JudgeEvaluator passes its own title/icon; custom Evaluators fall back to neutral
+ * categorical branding.
+ */
+import React from "react";
+import type { LucideIcon } from "lucide-react";
+import type { CategoricalMetric } from "../utils/categoricalAggregateTree";
+export interface CategoricalAggregateViewProps {
+    metrics: CategoricalMetric[];
+    /** Heading shown above the cards. Defaults to a neutral categorical title. */
+    title?: string;
+    /** Icon shown on each metric card header. Defaults to a neutral tags icon. */
+    icon?: LucideIcon;
+    /** Text shown when there are no metrics. Defaults to a neutral message. */
+    emptyLabel?: string;
+    /** Opens the run for a node in the Session Details drawer. sessionId may be undefined for legacy evaluations. */
+    onAgentNodeClick?: (sessionId: string | undefined, nodeId: string) => void;
+    /** Opens the run for a node in the full Visualizer. */
+    onOpenVisualizer?: (sessionId: string | undefined, nodeId: string) => void;
+}
+export declare const CategoricalAggregateView: React.FC<CategoricalAggregateViewProps>;

package/dist/types/agenthub/components/NumericalAggregateView.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Custom (numerical) evaluator view: one card per numerical metric, showing
+ * summary statistics (mean/min/max/median/std/runs) in the header and a collapsible
+ * list of the per-run values. Each value exposes Session Details / Visualizer
+ * call-to-actions (see NodeActions). Used for custom Evaluators that emit a
+ * `NumericalAggregate` (e.g. EndToEndLatencyEvaluator).
+ */
+import React from "react";
+import type { NumericalMetric } from "../utils/numericalAggregateTree";
+export interface NumericalAggregateViewProps {
+    metrics: NumericalMetric[];
+    /** Opens the run for a node in the Session Details drawer. sessionId may be undefined for legacy evaluations. */
+    onAgentNodeClick?: (sessionId: string | undefined, nodeId: string) => void;
+    /** Opens the run for a node in the full Visualizer. */
+    onOpenVisualizer?: (sessionId: string | undefined, nodeId: string) => void;
+}
+export declare const NumericalAggregateView: React.FC<NumericalAggregateViewProps>;

package/dist/types/agenthub/components/SessionTree.d.ts

@@ -2,6 +2,8 @@ import React from "react";
 import type { AgentRun } from "../../dto/AgentRun";
 import type { AgentRunNode } from "../../dto/AgentRunNode";
 import type { SessionListItem } from "../hooks/useSessions";
+/** Wall-clock elapsed time across a node and all descendants (unix stamp times). */
+export declare const getSubtreeWallClockSeconds: (nodeId: string, childrenMap: Map<string, string[]>, nodeMap: Map<string, AgentRunNode>) => number;
 /** Tool/agent failure is carried on the incoming edge's details.status (e.g. Failed), same as flow edges and session I/O. */
 export declare function isNodeFailureFromIncomingEdge(run: AgentRun, nodeId: string): boolean;
 export interface SelectedNodeInfo {

package/dist/types/agenthub/utils/categoricalAggregateTree.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Builds the categorical evaluator view model from aggregate_results.
+ *
+ * Generic over any evaluator that emits a CategoricalAggregate — the built-in
+ * JudgeEvaluator is the common case, but custom Evaluators that produce
+ * categorical metrics share the exact same shape and render through this path.
+ *
+ * Shape of the data (see sample.json -> JudgeEvaluator):
+ *  - aggregate_results.roots -> CategoricalAggregate nodes (one per metric) with
+ *    `categories`, `counts`, `most_common_label`, `least_common_label`, and `children`.
+ *  - Each child id resolves (in aggregate_results.nodes) to a Base leaf result whose
+ *    `value` is the category label string and `agent_data_id[0]` is the agent node id.
+ *  - Judge reasoning (a Judge-specific enrichment) lives separately in metric_results
+ *    as Base results named `JudgeReasoning/<metric>`, paired to a node by
+ *    `agent_data_id[0]` + metric name. Custom evaluators have none; reasoning is then
+ *    simply absent.
+ */
+import type { EvaluationResultItem, EvaluationAgent } from "../../dto/Evaluation";
+/** A single evaluated agent node under a category label. */
+export interface CategoricalNodeRef {
+    nodeId: string;
+    /** Session that owns the node, when the evaluation carries session context. */
+    sessionId?: string;
+    /** Reasoning text for this node + metric, when available (Judge only). */
+    reasoning?: string;
+}
+/** One category label within a metric, with the nodes that received it. */
+export interface CategoricalLabel {
+    labelName: string;
+    count: number;
+    nodes: CategoricalNodeRef[];
+}
+/** One categorical metric evaluated across all runs. */
+export interface CategoricalMetric {
+    key: string;
+    metricName: string;
+    description?: string;
+    mostCommon?: string;
+    leastCommon?: string;
+    total: number;
+    labels: CategoricalLabel[];
+}
+type NodeMap = Record<string, unknown>;
+type AgentLike = Pick<EvaluationAgent, "agent_name" | "agent_node_ids"> | {
+    agent_name: string;
+    agent_node_ids?: string[] | {
+        session_id: string;
+        agent_node_id: string;
+    }[];
+};
+export interface BuildCategoricalMetricsInput {
+    roots: string[];
+    nodes: NodeMap;
+    agents?: AgentLike[];
+    /** Full evaluator results (metric_results + aggregates) used to resolve reasoning. */
+    rawResults?: EvaluationResultItem[];
+}
+/** Build the categorical view model: one entry per categorical metric. */
+export declare function buildCategoricalMetricsFromAggregate(input: BuildCategoricalMetricsInput): CategoricalMetric[];
+export {};

package/dist/types/agenthub/utils/numericalAggregateTree.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Builds the custom (numerical) evaluator view model from aggregate_results.
+ *
+ * Custom Evaluators (anything that isn't the built-in Judge/ToolUse/LLMInference)
+ * emit a `Numerical` metric and a `NumericalAggregate` aggregate node. Shape of the
+ * data (see custom_sample.json -> EndToEndLatencyEvaluator):
+ *  - aggregate_results.roots -> NumericalAggregate nodes (one per metric) with
+ *    `mean`, `minimum`, `maximum`, `median`, `std`, `values`, and `children`.
+ *  - Each child id resolves (in aggregate_results.nodes) to a Base leaf result whose
+ *    `value` is the per-run number and `agent_data_id[0]` is the agent node id.
+ *
+ * NOTE: this only handles the aggregate-tree shape. A custom evaluator that emits
+ * only `metric_results` with no `aggregate_results` is not yet rendered (deferred).
+ */
+import type { EvaluationResultItem, EvaluationAgent } from "../../dto/Evaluation";
+/** A single per-run leaf value for a numerical metric. */
+export interface NumericalNodeRef {
+    nodeId: string;
+    /** Session that owns the node, when the evaluation carries session context. */
+    sessionId?: string;
+    value: number;
+}
+/** One numerical metric aggregated across all runs. */
+export interface NumericalMetric {
+    key: string;
+    metricName: string;
+    description?: string;
+    mean?: number;
+    minimum?: number;
+    maximum?: number;
+    median?: number;
+    std?: number;
+    count: number;
+    nodes: NumericalNodeRef[];
+}
+type NodeMap = Record<string, unknown>;
+type AgentLike = Pick<EvaluationAgent, "agent_name" | "agent_node_ids"> | {
+    agent_name: string;
+    agent_node_ids?: string[] | {
+        session_id: string;
+        agent_node_id: string;
+    }[];
+};
+export interface BuildNumericalMetricsInput {
+    roots: string[];
+    nodes: NodeMap;
+    agents?: AgentLike[];
+    /** Full evaluator results (metric_results + aggregates), used as a leaf-value fallback. */
+    rawResults?: EvaluationResultItem[];
+}
+/** Build the custom (numerical) evaluator view model: one entry per numerical metric. */
+export declare function buildNumericalMetricsFromAggregate(input: BuildNumericalMetricsInput): NumericalMetric[];
+export {};

package/dist/types/components/nodes/ErrorOutput.d.ts

@@ -0,0 +1,26 @@
+import React from "react";
+/** Error envelope produced by the Railtracks backend for a failed node/tool. */
+export interface ToolErrorOutput {
+    /** Exception class name, e.g. "ValueError". */
+    type?: string;
+    /** Human-readable exception message. */
+    message?: string;
+    /** Full Python traceback string. */
+    traceback?: string;
+}
+/**
+ * Detect whether a tool/node output is an error envelope rather than a regular
+ * return value. Failed nodes serialize as `{ type, message, traceback }`; a
+ * traceback alone, or a `type` + `message` pair, is enough to treat it as an
+ * error. Returns the parsed error (with only string fields kept) or null.
+ */
+export declare function parseErrorOutput(output: unknown): ToolErrorOutput | null;
+export interface ErrorOutputProps {
+    error: ToolErrorOutput;
+}
+/**
+ * Renders a failed node/tool output distinctly from a regular returned object:
+ * a destructive-tinted surface with the exception type, message, and a
+ * collapsible traceback.
+ */
+export declare const ErrorOutput: React.FC<ErrorOutputProps>;

package/dist/types/dto/Evaluation.d.ts

@@ -1,10 +1,10 @@
 /**
  * DTOs for evaluation data from .railtracks/data/evaluations/*.json
  */
-/** Numeric metric definition (LLMMetric or ToolMetric) */
+/** Numeric metric definition (LLMMetric, ToolMetric, or Numerical for custom evaluators) */
 export type EvaluationNumericMetricDefinition = {
     name: string;
-    metric_type: "LLMMetric" | "ToolMetric";
+    metric_type: "LLMMetric" | "ToolMetric" | "Numerical";
     identifier: string;
     description: string | null;
     min_value: number | null;
@@ -58,7 +58,7 @@ export type EvaluationMetricReference = {
     identifier: string;
     min_value?: number;
     max_value?: number | null;
-    metric_type?: "LLMMetric" | "ToolMetric" | "Categorical";
+    metric_type?: "LLMMetric" | "ToolMetric" | "Categorical" | "Numerical";
     description?: string | null;
     categories?: string[];
 };
@@ -111,8 +111,23 @@ export type EvaluationCategoricalAggregate = {
     counts: Record<string, number>;
     children?: string[];
 };
+/** Numerical aggregate (mean/median/etc for a custom evaluator's numerical metric) */
+export type EvaluationNumericalAggregate = {
+    type: "NumericalAggregate";
+    identifier?: string;
+    name?: string;
+    metric: EvaluationMetricReference;
+    values: number[];
+    mean: number;
+    minimum: number;
+    maximum: number;
+    median: number;
+    std: number;
+    mode: number;
+    children?: string[];
+};
 /** Union of possible items in evaluator results array */
-export type EvaluationResultItem = EvaluationLLMResult | EvaluationToolResult | EvaluationBaseResult | EvaluationLLMInferenceAggregate | EvaluationToolAggregate | EvaluationCategoricalAggregate;
+export type EvaluationResultItem = EvaluationLLMResult | EvaluationToolResult | EvaluationBaseResult | EvaluationLLMInferenceAggregate | EvaluationToolAggregate | EvaluationCategoricalAggregate | EvaluationNumericalAggregate;
 /** Type guard for LLM result */
 export declare function isLLMResult(item: EvaluationResultItem): item is EvaluationLLMResult;
 /** Type guard for Tool result */
@@ -125,8 +140,10 @@ export declare function isLLMInferenceAggregate(item: EvaluationResultItem): ite
 export declare function isToolAggregate(item: EvaluationResultItem): item is EvaluationToolAggregate;
 /** Type guard for CategoricalAggregate */
 export declare function isAggregateCategorical(item: EvaluationResultItem): item is EvaluationCategoricalAggregate;
-/** Type guard for aggregated stats (numeric - LLMInferenceAggregate or ToolAggregate) */
-export declare function isAggregatedStats(item: EvaluationResultItem): item is EvaluationLLMInferenceAggregate | EvaluationToolAggregate;
+/** Type guard for NumericalAggregate (custom evaluator numeric aggregate) */
+export declare function isNumericalAggregate(item: EvaluationResultItem): item is EvaluationNumericalAggregate;
+/** Type guard for aggregated stats (numeric - LLMInferenceAggregate, ToolAggregate, or NumericalAggregate) */
+export declare function isAggregatedStats(item: EvaluationResultItem): item is EvaluationLLMInferenceAggregate | EvaluationToolAggregate | EvaluationNumericalAggregate;
 /** Aggregate results tree (roots + nodes by identifier) */
 export type EvaluationAggregateResults = {
     roots: string[];
@@ -138,7 +155,7 @@ export type EvaluationEvaluatorResult = {
     evaluator_id: string;
     /** Per-metric results (LLM, Tool, Base) */
     metric_results: EvaluationResultItem[];
-    /** Aggregate tree (roots + nodes with ToolAggregate, LLMInferenceAggregate, CategoricalAggregate) */
+    /** Aggregate tree (roots + nodes with ToolAggregate, LLMInferenceAggregate, CategoricalAggregate, NumericalAggregate) */
     aggregate_results?: EvaluationAggregateResults;
 };
 /** New format: agent node with session context */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@railtownai/railtracks-visualizer",
-  "version": "0.0.69",
+  "version": "0.0.71",
   "license": "MIT",
   "author": "Railtown AI",
   "description": "A visualizer for Railtracks agentic flows",

package/dist/types/agenthub/components/JudgeAggregateView.d.ts

@@ -1,16 +0,0 @@
-/**
- * Judge (LLM-as-judge) evaluator view: one card per categorical metric, with
- * collapsible accordions per category label listing the agent nodes that received
- * that label. Each node exposes Session Details / Visualizer call-to-actions
- * (see NodeActions) and an inline toggle to reveal the judge's reasoning when present.
- */
-import React from "react";
-import type { JudgeMetric } from "../utils/judgeAggregateTree";
-export interface JudgeAggregateViewProps {
-    metrics: JudgeMetric[];
-    /** Opens the run for a judged node in the Session Details drawer. sessionId may be undefined for legacy evaluations. */
-    onAgentNodeClick?: (sessionId: string | undefined, nodeId: string) => void;
-    /** Opens the run for a judged node in the full Visualizer. */
-    onOpenVisualizer?: (sessionId: string | undefined, nodeId: string) => void;
-}
-export declare const JudgeAggregateView: React.FC<JudgeAggregateViewProps>;

package/dist/types/agenthub/utils/judgeAggregateTree.d.ts

@@ -1,55 +0,0 @@
-/**
- * Builds the Judge (categorical) evaluator view model from aggregate_results.
- *
- * Shape of the data (see sample.json -> JudgeEvaluator):
- *  - aggregate_results.roots -> CategoricalAggregate nodes (one per metric) with
- *    `categories`, `counts`, `most_common_label`, `least_common_label`, and `children`.
- *  - Each child id resolves (in aggregate_results.nodes) to a Base leaf result whose
- *    `result_name` is `JudgeResult/<metric>`, `value` is the category label string, and
- *    `agent_data_id[0]` is the agent node id that was judged.
- *  - Reasoning lives separately in metric_results as Base results named
- *    `JudgeReasoning/<metric>`, paired to a node by `agent_data_id[0]` + metric name.
- */
-import type { EvaluationResultItem, EvaluationAgent } from "../../dto/Evaluation";
-/** A single judged agent node under a category label. */
-export interface JudgeNodeRef {
-    nodeId: string;
-    /** Session that owns the node, when the evaluation carries session context. */
-    sessionId?: string;
-    /** Judge reasoning text for this node + metric, when available. */
-    reasoning?: string;
-}
-/** One category label within a metric, with the nodes that received it. */
-export interface JudgeLabel {
-    labelName: string;
-    count: number;
-    nodes: JudgeNodeRef[];
-}
-/** One categorical metric judged across all runs. */
-export interface JudgeMetric {
-    key: string;
-    metricName: string;
-    description?: string;
-    mostCommon?: string;
-    leastCommon?: string;
-    total: number;
-    labels: JudgeLabel[];
-}
-type NodeMap = Record<string, unknown>;
-type AgentLike = Pick<EvaluationAgent, "agent_name" | "agent_node_ids"> | {
-    agent_name: string;
-    agent_node_ids?: string[] | {
-        session_id: string;
-        agent_node_id: string;
-    }[];
-};
-export interface BuildJudgeMetricsInput {
-    roots: string[];
-    nodes: NodeMap;
-    agents?: AgentLike[];
-    /** Full evaluator results (metric_results + aggregates) used to resolve reasoning. */
-    rawResults?: EvaluationResultItem[];
-}
-/** Build the Judge view model: one entry per categorical metric. */
-export declare function buildJudgeMetricsFromAggregate(input: BuildJudgeMetricsInput): JudgeMetric[];
-export {};