API Reference

Component Props

A configurable time window prop is planned for v0.2 — see the roadmap. v0.1 shows the most recent ~420 samples per agent.

Helpers

Two tiny exports that cut onboarding boilerplate. Neither is required — they exist so “hello world” stays short.

createAgent(id, name, color?)

A factory for the common Agent shape. Fills in data: [], current with safe defaults, and visible: true. Default color is '#111111'.

import { createAgent } from 'agentstat';

const agent = createAgent('chat-agent', 'Chat Assistant', '#1d4ed8');
// → { id, name, color, data: [], current: { tokensRate: 0, progress: 0, status: 'active' }, visible: true }

demoAgents

A ready-made 3-agent roster (Researcher, Critic, Executor) for demos and first-run exploration. Pair with simulateData for a chart with zero wiring.

import { AgentStat, demoAgents } from 'agentstat';

export default function Demo() {
  return <AgentStat agents={demoAgents} simulateData height={400} />;
}

For real deployments, construct your own Agent array — this preset exists purely to remove friction while evaluating the component.

ThemeStyles

interface ThemeStyles {
  background?: string;  // Canvas background (hex). Determines light/dark mode.
  borderColor?: string; // Canvas border color.
  textColor?: string;   // Overlay text color.
  gridColor?: string;   // Horizontal grid line color.
}

All fields are optional. Light or dark overlays are inferred from background automatically — no extra config needed.

Imperative Ref API

Attach a ref via useRef<AgentStatRef>(null) to push live metrics and read health data imperatively:

const ref = useRef<AgentStatRef>(null);

// Push live metrics — call this as often as your data updates.
// Any status passed here takes precedence over the simulation: setting
// 'stuck' or 'hallucinating' locks the agent until you call updateAgent
// again with a non-anomalous status.
ref.current?.updateAgent(
  'agent-id',        // must match an id in the agents array
  tokensPerSecond,   // number
  progressPercent,   // 0-100
  'active'           // AgentStatus
);

// Read the last computed health score for an agent.
const health = ref.current?.getHealth('agent-id');
// → { score, tokenEfficiency, stability, hallucinationRisk, latencyTrend }

// Read the live interpolated values (updated every animation frame).
const live = ref.current?.getLiveMetrics('agent-id');
// → { tokensRate, progress, status }
//   tokensRate and progress are smoothly lerped for rendering;
//   status is the discrete last-known value.

Always use optional chaining (ref.current?.) — the ref is null until after the first render.

Core Types

type AgentStatus =
  | 'active'
  | 'thinking'
  | 'stuck'
  | 'complete'
  | 'hallucinating';

interface Agent {
  id: string;
  name: string;
  color: string;           // hex color for this agent's line
  data: AgentDataPoint[];  // pass [] — the component manages its own buffer
  current: {
    tokensRate: number;
    progress: number;      // 0-100
    status: AgentStatus;
    latencyMs?: number;    // optional: drives latencyTrend in health scoring
    confidenceScore?: number; // optional: 0-1, drives hallucinationRisk
  };
  config?: {
    expectedTokensPerSec?: [number, number]; // [min, max] for health scoring
  };
  visible: boolean;
}

interface HealthMetrics {
  score: number;             // 0-100 composite health score
  tokenEfficiency: number;   // how close tokensRate is to expected range
  stability: number;         // inverse of token rate variance over last 30 points
  hallucinationRisk: number; // 0-100, driven by status and confidenceScore
  latencyTrend: 'improving' | 'stable' | 'degrading';
}

interface AgentDataPoint {
  time: number;
  tokensRate: number;
  progress: number;
  status: AgentStatus;
  latencyMs?: number;
  confidenceScore?: number;
}

Health Score Calculation

The composite health score (0–100) is computed automatically from four components. The latency component is renormalized out when you don't provide latencyMs, so a perfectly-healthy agent with no latency data reaches 100 — not an artificial ~90 cap.

// When latencyMs is provided:
score =
  tokenEfficiency * 0.35          // rate inside expectedTokensPerSec range?
  + stability     * 0.25          // variance over last 30 samples
  + (100 - hallucinationRisk) * 0.30  // status + confidenceScore
  + latencyScore  * 0.10          // improving=100 / stable=50 / degrading=0

// When latencyMs is NOT provided (weights renormalize):
score =
  (tokenEfficiency * 0.35
    + stability * 0.25
    + (100 - hallucinationRisk) * 0.30)
  / 0.9

Set config.expectedTokensPerSec on each agent to calibrate tokenEfficiency for your specific model.