@railtownai/railtracks-visualizer 0.0.22 → 0.0.24

package/dist/types/components/ErrorBoundary.d.ts

@@ -0,0 +1,17 @@
+import React, { Component, ErrorInfo, ReactNode } from "react";
+interface Props {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error?: Error;
+    errorInfo?: ErrorInfo;
+}
+declare class ErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | React.JSX.Element | null | undefined;
+}
+export default ErrorBoundary;

package/dist/types/components/icons/RailTracksIcon.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+interface RailTracksIconProps {
+    width?: string | number;
+    height?: string | number;
+}
+export declare const RailTracksIcon: React.FC<RailTracksIconProps>;
+export default RailTracksIcon;

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

@@ -1,8 +1,9 @@
 import React from "react";
+import { LLMDetails, NodeDetails } from "../../dto/AgentRunNode";
 interface NodeData {
     label: string;
     nodeType?: "Tool" | "Agent" | "Coordinator";
-    details?: any;
+    details?: NodeDetails;
     id?: string;
     edges?: any[];
     edgeDetails?: {
@@ -18,5 +19,9 @@ interface AgentNodeProps {
     id: string;
     onInspect?: (nodeData: NodeData) => void;
 }
+export declare const getOverviewLlmDetails: (llmDetails: LLMDetails[]) => LLMDetails | null;
+export declare const sumTotalCost: (llmDetails: LLMDetails[]) => number;
+export declare const sumTotalInputTokens: (llmDetails: LLMDetails[]) => number;
+export declare const sumTotalOutputTokens: (llmDetails: LLMDetails[]) => number;
 export declare const AgentNode: React.FC<AgentNodeProps>;
 export {};

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

@@ -0,0 +1,7 @@
+import React from "react";
+interface CodeBlockProps {
+    content: string;
+    language?: string;
+}
+export declare const CodeBlock: React.FC<CodeBlockProps>;
+export {};

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

@@ -0,0 +1,9 @@
+import React from "react";
+interface OutputRendererProps {
+    data: {
+        role: string;
+        content: any;
+    };
+}
+export declare const OutputRenderer: React.FC<OutputRendererProps>;
+export {};

package/dist/types/components/ui/header.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+import { JsonFile } from "../../hooks/useApi";
+interface AgentRun {
+    id: number;
+    name: string;
+    runId: string;
+    sessionId: string;
+}
+interface HeaderProps {
+    availableFiles: JsonFile[];
+    currentFile: string | null;
+    onFileSelect: (filename: string) => void;
+    onRefresh: () => void;
+    loading: boolean;
+    isMultipleAgentRuns: boolean;
+    agentRuns: AgentRun[];
+    selectedAgentRun: number;
+    onAgentRunSelect: (runIndex: number) => void;
+    showTimeline: boolean;
+    onTimelineToggle: (checked: boolean) => void;
+}
+export declare const Header: React.FC<HeaderProps>;
+export {};

package/dist/types/components/ui/json-tree.d.ts

@@ -3,8 +3,10 @@ interface JsonTreeViewerProps {
     data: any;
     maxDepth?: number;
     initialExpanded?: boolean;
+    expanded?: boolean;
     className?: string;
     priorityKeys?: string[];
+    excludeKeys?: string[];
 }
 declare const JsonTreeViewer: React.FC<JsonTreeViewerProps>;
 export { JsonTreeViewer };

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

@@ -1,19 +1,42 @@
 import { AgentRunNode } from "./AgentRunNode";
 import { AgentRunEdge } from "./AgentRunEdge";
+import { AgentRunStamp } from "./AgentRunStamp";
+import { AgentRunStep } from "./AgentRunStep";
+/**
+ * Represents a complete agent execution run with its nodes, edges, and metadata
+ *
+ * This interface defines the structure for agent flow data that can be visualized
+ * in the RailTracks UI. It contains the execution graph (nodes and edges) along
+ * with timing information and session metadata.
+ *
+ * @example
+ * ```typescript
+ * const agentRun: AgentRun = {
+ *   session_id: "session_123",
+ *   name: "Customer Support Agent",
+ *   run_id: "run_456",
+ *   nodes: [...],
+ *   edges: [...],
+ *   stamps: [
+ *     { step: 1, time: 1640995200, identifier: "start" },
+ *     { step: 2, time: 1640995201, identifier: "user_input" }
+ *   ]
+ * };
+ * ```
+ */
 export interface AgentRun {
+    /** Unique identifier for the agent session this run belongs to */
     session_id: string;
+    /** Human-readable name for this agent run */
     name: string;
+    /** Unique identifier for this specific agent run */
     run_id: string;
+    /** Array of nodes representing the agent's execution steps */
     nodes: AgentRunNode[];
+    /** Optional array of edges connecting the nodes in the execution flow */
     edges?: AgentRunEdge[];
-    stamps?: Array<{
-        step: number;
-        time: number;
-        identifier: string;
-    }>;
-    steps?: Array<{
-        step: number;
-        time: number;
-        identifier: string;
-    }>;
+    /** Optional array of timestamped events that occurred during the run */
+    stamps?: AgentRunStamp[];
+    /** Optional array of execution steps with timing information */
+    steps?: AgentRunStep[];
 }

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

@@ -1,18 +1,67 @@
+/**
+ * Represents a timestamped event for an edge
+ */
+export interface EdgeStamp {
+    /** The sequential step number in the agent execution */
+    step: number;
+    /** Unix timestamp when this event occurred */
+    time: number;
+    /** Unique identifier for this stamp */
+    identifier: string;
+}
+/**
+ * Represents detailed information about an edge
+ */
+export interface EdgeDetails {
+    /** Optional status information for the edge */
+    status?: string;
+    /** Optional array of input arguments passed to the target node */
+    input_args?: any[];
+    /** Optional object of input keyword arguments passed to the target node */
+    input_kwargs?: any;
+    /** Optional output data from the source node */
+    output?: any;
+}
+/**
+ * Represents an edge connecting nodes in the agent execution flow
+ *
+ * This interface defines the structure for connections between nodes in an agent run.
+ * Edges represent the flow of data and control between different execution steps,
+ * with timing information and optional execution details.
+ *
+ * @example
+ * ```typescript
+ * const edge: AgentRunEdge = {
+ *   identifier: "edge_123",
+ *   source: "node_1",
+ *   target: "node_2",
+ *   stamp: {
+ *     step: 2,
+ *     time: 1640995201,
+ *     identifier: "edge_1_to_2"
+ *   },
+ *   details: {
+ *     state: "completed",
+ *     status: "success",
+ *     input_args: ["Hello world"],
+ *     input_kwargs: { temperature: 0.7 },
+ *     output: { response: "Hi there!" }
+ *   },
+ *   parent: null
+ * };
+ * ```
+ */
 export interface AgentRunEdge {
+    /** Unique identifier for this edge */
     identifier: string;
+    /** Identifier of the source node, or null if this is an entry edge */
     source: string | null;
+    /** Identifier of the target node this edge connects to */
     target: string;
-    stamp: {
-        step: number;
-        time: number;
-        identifier: string;
-    };
-    details: {
-        state?: string;
-        status?: string;
-        input_args?: any[];
-        input_kwargs?: any;
-        output?: any;
-    };
+    /** Timestamp information for when this edge was traversed */
+    stamp: EdgeStamp;
+    /** Detailed information about the edge's execution */
+    details: EdgeDetails;
+    /** Reference to the parent edge, or null if this is a root edge */
     parent: AgentRunEdge | null;
 }

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

@@ -1,34 +1,141 @@
+/**
+ * Represents a timestamped event for a node
+ */
+export interface NodeStamp {
+    /** The sequential step number in the agent execution */
+    step: number;
+    /** Unix timestamp when this event occurred */
+    time: number;
+    /** Unique identifier for this stamp */
+    identifier: string;
+}
+/**
+ * Represents input/output content for LLM interactions
+ */
+export interface LLMContent {
+    /** Role of the message sender (e.g., "user", "assistant", "system") */
+    role: string;
+    /** The actual content of the message */
+    content: any;
+}
+/**
+ * Represents detailed information about an LLM interaction
+ */
+export interface LLMDetails {
+    /** Name of the language model used */
+    model_name: string;
+    /** Provider of the language model (e.g., "openai", "anthropic") */
+    model_provider: string;
+    /** Array of input messages sent to the LLM */
+    input: LLMContent[];
+    /** Output message received from the LLM */
+    output: LLMContent;
+    /** Number of tokens in the input (null if not available) */
+    input_tokens: number | null;
+    /** Number of tokens in the output (null if not available) */
+    output_tokens: number | null;
+    /** Total cost of the LLM interaction (null if not available) */
+    total_cost: number | null;
+    /** System fingerprint for the model (null if not available) */
+    system_fingerprint: string | null;
+}
+/**
+ * Represents latency information for a node execution
+ */
+export interface NodeLatency {
+    /** Total time taken for the node to execute in milliseconds */
+    total_time: number;
+}
+/**
+ * Represents internal execution details for a node
+ */
+export interface NodeInternals {
+    /** Optional array of LLM interaction details */
+    llm_details?: LLMDetails[];
+    /** Optional latency information for the node execution */
+    latency?: NodeLatency;
+}
+/**
+ * Represents detailed information about a node
+ */
+export interface NodeDetails {
+    /** Optional internal execution details */
+    internals?: NodeInternals;
+}
+/**
+ * Represents a node in the agent execution flow
+ *
+ * This interface defines the structure for individual execution steps in an agent run.
+ * Each node represents a discrete action or decision point in the agent's workflow,
+ * with timing information, execution details, and optional LLM interaction data.
+ *
+ * @example
+ * ```typescript
+ * const node: AgentRunNode = {
+ *   identifier: "node_123",
+ *   node_type: "llm_call",
+ *   name: "Generate Response",
+ *   stamp: {
+ *     step: 1,
+ *     time: 1640995200,
+ *     identifier: "llm_call_1"
+ *   },
+ *   details: {
+ *     internals: {
+ *       llm_details: [{
+ *         model_name: "gpt-4",
+ *         model_provider: "openai",
+ *         input: [{ role: "user", content: "Hello" }],
+ *         output: { role: "assistant", content: "Hi there!" },
+ *         input_tokens: 5,
+ *         output_tokens: 3,
+ *         total_cost: 0.0001,
+ *         system_fingerprint: "fp_123"
+ *       }],
+ *       latency: { total_time: 1500 }
+ *     }
+ *   },
+ *   parent: null
+ * };
+ * ```
+ */
 export interface AgentRunNode {
+    /** Unique identifier for this node */
     identifier: string;
+    /** Type of node (e.g., "llm_call", "tool_call", "decision") */
     node_type: string;
+    /** Optional human-readable name for this node */
     name?: string;
-    stamp: {
-        step: number;
-        time: number;
-        identifier: string;
-    };
-    details: {
-        internals?: {
-            llm_details?: Array<{
-                model_name: string;
-                model_provider: string;
-                input: Array<{
-                    role: string;
-                    content: any;
-                }>;
-                output: {
-                    role: string;
-                    content: any;
-                };
-                input_tokens: number | null;
-                output_tokens: number | null;
-                total_cost: number | null;
-                system_fingerprint: string | null;
-            }>;
-            latency?: {
-                total_time: number;
-            };
-        };
-    };
+    /** Timestamp information for when this node was executed */
+    stamp: NodeStamp;
+    /** Detailed information about the node's execution */
+    details: NodeDetails;
+    /** Reference to the parent node, or null if this is a root node */
     parent: AgentRunNode | null;
 }
+/**
+ * Represents a tool call with identifier, name, and arguments
+ */
+export interface ToolCall {
+    /** Unique identifier for this tool call */
+    identifier: string;
+    /** Name of the tool being called */
+    name: string;
+    /** Arguments passed to the tool */
+    arguments: Record<string, any>;
+}
+/**
+ * Represents a tool response with identifier, name, and result
+ */
+export interface ToolResponse {
+    /** Unique identifier for this tool response */
+    identifier: string;
+    /** Name of the tool that generated this response */
+    name: string;
+    /** The result of the tool call */
+    result: any;
+}
+/**
+ * Union type for different content types that can be rendered
+ */
+export type Content = string | ToolCall[] | ToolResponse | any;

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

@@ -0,0 +1,23 @@
+/**
+ * Represents a timestamped event in an agent run
+ *
+ * This interface defines the structure for tracking when specific events
+ * occurred during an agent's execution, with step ordering and timing information.
+ *
+ * @example
+ * ```typescript
+ * const stamp: AgentRunStamp = {
+ *   step: 1,
+ *   time: 1640995200,
+ *   identifier: "user_input_received"
+ * };
+ * ```
+ */
+export interface AgentRunStamp {
+    /** The sequential step number in the agent execution */
+    step: number;
+    /** Unix timestamp when this event occurred */
+    time: number;
+    /** Unique identifier for this stamp */
+    identifier: string;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Represents a step in the agent execution flow
+ *
+ * This interface defines the structure for individual execution steps
+ * in an agent run, with timing and identification information.
+ *
+ * @example
+ * ```typescript
+ * const step: AgentRunStep = {
+ *   step: 2,
+ *   time: 1640995201,
+ *   identifier: "llm_generation"
+ * };
+ * ```
+ */
+export interface AgentRunStep {
+    /** The sequential step number in the agent execution */
+    step: number;
+    /** Unix timestamp when this step occurred */
+    time: number;
+    /** Unique identifier for this step */
+    identifier: string;
+}

package/dist/types/lib/utils.d.ts

@@ -1,4 +1,5 @@
 import { type ClassValue } from "clsx";
+import { ToolCall } from "../dto/AgentRunNode";
 export declare function cn(...inputs: ClassValue[]): string;
 /**
  * Converts a string to title case
@@ -77,3 +78,14 @@ export declare function getSafeThemeValue(theme: any, path: string, fallback: an
  * @returns A safe theme object with fallbacks
  */
 export declare function createSafeTheme(theme?: any): any;
+/**
+ * Detects the type of content for rendering
+ */
+export declare const detectContentType: (output: {
+    role: string;
+    content: any;
+}) => "string" | "toolResponse" | "toolCallList" | "other";
+/**
+ * Formats tool calls for display in a code block
+ */
+export declare const formatToolCalls: (toolCalls: ToolCall[]) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@railtownai/railtracks-visualizer",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "license": "Apache-2.0",
   "author": "Railtown AI",
   "description": "A visualizer for RailTracks agentic flows",
@@ -37,13 +37,16 @@
     "react-dom": "^18.3.1"
   },
   "dependencies": {
+    "@ant-design/plots": "2.6.3",
     "@emotion/react": "11.14.0",
     "@emotion/styled": "11.14.1",
     "@radix-ui/react-checkbox": "1.3.3",
     "@radix-ui/react-dialog": "1.1.15",
     "@radix-ui/react-select": "2.2.6",
+    "@railtownai/railtracks-timeline": "0.0.3",
     "@xyflow/react": "12.8.4",
     "lucide-react": "0.525.0",
+    "moment": "2.30.1",
     "react-countup": "6.5.3",
     "vaul": "1.1.2"
   },
@@ -54,7 +57,7 @@
     "build:size": "npm pack --dry-run",
     "build": "npm run build:types && npm run build:lib && npm run build:spa",
     "clean": "rm -rf dist build test-results .railtracks/ui/*",
-    "dev:spa": "vite build && rm -rf .railtracks/ui/* && cp -r build/* .railtracks/ui",
+    "dev": "rm -rf .railtracks/ui/* && vite build && cp -r build/* .railtracks/ui",
     "lint:fix": "prettier --write \"src/**/*.{js,jsx,ts,tsx,json,css,md}\"",
     "lint": "prettier --check \"src/**/*.{js,jsx,ts,tsx,json,css,md}\"",
     "start": "storybook dev -p 6006",