toad-eye 2.0.0 → 2.1.0

package/dist/agent.d.ts

@@ -0,0 +1,41 @@
+import type { AgentStepInput } from "./types/index.js";
+/**
+ * Record a single agent step as a child span (ReAct pattern: think → act → observe → answer).
+ *
+ * Creates a short-lived span under the current active context. Call this inside
+ * {@link traceAgentQuery} (preferred) or any other active span (e.g. traceLLMCall).
+ *
+ * - Respects `recordContent` config — content is omitted when recording is disabled.
+ * - For `act` steps with a `toolName`, automatically increments the `agent.tool_usage` metric.
+ */
+declare function traceAgentStep(input: AgentStepInput): void;
+/**
+ * Wrap an entire agent query in a parent span, producing structured ReAct traces.
+ *
+ * The callback receives a `step` function to record individual steps.
+ * When the callback completes, the wrapper automatically records the
+ * `agent.steps_per_query` histogram metric with the total step count.
+ *
+ * Span hierarchy in Jaeger:
+ * ```
+ * [parent] agent.query "Is anything dangerous near Earth?"
+ *   ├── agent.step.think   "I need to check asteroids"
+ *   ├── agent.step.act     tool=near-earth-asteroids
+ *   ├── agent.step.observe "7 asteroids found"
+ *   └── agent.step.answer  "7 asteroids passing safely..."
+ * ```
+ *
+ * @example
+ * ```ts
+ * const result = await traceAgentQuery("Is anything dangerous near Earth?", async (step) => {
+ *   step({ type: "think", stepNumber: 1, content: "I need to check asteroids" });
+ *   const data = await callTool("near-earth-asteroids");
+ *   step({ type: "act", stepNumber: 2, toolName: "near-earth-asteroids" });
+ *   step({ type: "observe", stepNumber: 3, content: `${data.length} asteroids found` });
+ *   step({ type: "answer", stepNumber: 4, content: "7 asteroids passing safely..." });
+ *   return { answer: "7 asteroids passing safely..." };
+ * });
+ * ```
+ */
+export declare function traceAgentQuery<T>(query: string, fn: (step: (input: AgentStepInput) => void) => Promise<T>): Promise<T>;
+export { traceAgentStep };

package/dist/agent.js

@@ -0,0 +1,91 @@
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "./types/index.js";
+import { recordAgentSteps, recordAgentToolUsage } from "./core/metrics.js";
+import { getConfig } from "./core/tracer.js";
+const tracer = trace.getTracer(INSTRUMENTATION_NAME);
+/**
+ * Record a single agent step as a child span (ReAct pattern: think → act → observe → answer).
+ *
+ * Creates a short-lived span under the current active context. Call this inside
+ * {@link traceAgentQuery} (preferred) or any other active span (e.g. traceLLMCall).
+ *
+ * - Respects `recordContent` config — content is omitted when recording is disabled.
+ * - For `act` steps with a `toolName`, automatically increments the `agent.tool_usage` metric.
+ */
+function traceAgentStep(input) {
+    const span = tracer.startSpan(`agent.step.${input.type}`);
+    const config = getConfig();
+    const recordContent = config?.recordContent !== false;
+    span.setAttributes({
+        [GEN_AI_ATTRS.AGENT_STEP_TYPE]: input.type,
+        [GEN_AI_ATTRS.AGENT_STEP_NUMBER]: input.stepNumber,
+        ...(input.toolName !== undefined && {
+            [GEN_AI_ATTRS.AGENT_TOOL_NAME]: input.toolName,
+        }),
+        ...(recordContent &&
+            input.content !== undefined && {
+            [GEN_AI_ATTRS.AGENT_STEP_CONTENT]: input.content,
+        }),
+    });
+    if (input.type === "act" && input.toolName !== undefined) {
+        recordAgentToolUsage(input.toolName);
+    }
+    span.setStatus({ code: SpanStatusCode.OK });
+    span.end();
+}
+/**
+ * Wrap an entire agent query in a parent span, producing structured ReAct traces.
+ *
+ * The callback receives a `step` function to record individual steps.
+ * When the callback completes, the wrapper automatically records the
+ * `agent.steps_per_query` histogram metric with the total step count.
+ *
+ * Span hierarchy in Jaeger:
+ * ```
+ * [parent] agent.query "Is anything dangerous near Earth?"
+ *   ├── agent.step.think   "I need to check asteroids"
+ *   ├── agent.step.act     tool=near-earth-asteroids
+ *   ├── agent.step.observe "7 asteroids found"
+ *   └── agent.step.answer  "7 asteroids passing safely..."
+ * ```
+ *
+ * @example
+ * ```ts
+ * const result = await traceAgentQuery("Is anything dangerous near Earth?", async (step) => {
+ *   step({ type: "think", stepNumber: 1, content: "I need to check asteroids" });
+ *   const data = await callTool("near-earth-asteroids");
+ *   step({ type: "act", stepNumber: 2, toolName: "near-earth-asteroids" });
+ *   step({ type: "observe", stepNumber: 3, content: `${data.length} asteroids found` });
+ *   step({ type: "answer", stepNumber: 4, content: "7 asteroids passing safely..." });
+ *   return { answer: "7 asteroids passing safely..." };
+ * });
+ * ```
+ */
+export async function traceAgentQuery(query, fn) {
+    return tracer.startActiveSpan(`agent.query`, async (span) => {
+        const config = getConfig();
+        const recordContent = config?.recordContent !== false;
+        if (recordContent) {
+            span.setAttribute(GEN_AI_ATTRS.AGENT_STEP_CONTENT, query);
+        }
+        let stepCount = 0;
+        try {
+            const result = await fn((input) => {
+                stepCount++;
+                traceAgentStep(input);
+            });
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            span.setStatus({ code: SpanStatusCode.ERROR, message });
+            throw error;
+        }
+        finally {
+            recordAgentSteps(stepCount);
+            span.end();
+        }
+    });
+}
+export { traceAgentStep };

package/dist/budget/error.d.ts

@@ -0,0 +1,10 @@
+import type { BudgetExceededInfo } from "./types.js";
+/** Thrown when onBudgetExceeded is 'block' and a budget limit is hit. */
+export declare class ToadBudgetExceededError extends Error {
+    readonly budget: BudgetExceededInfo["budget"];
+    readonly limit: number;
+    readonly current: number;
+    readonly model?: string | undefined;
+    readonly userId?: string | undefined;
+    constructor(info: BudgetExceededInfo);
+}

package/dist/budget/error.js

@@ -0,0 +1,22 @@
+/** Thrown when onBudgetExceeded is 'block' and a budget limit is hit. */
+export class ToadBudgetExceededError extends Error {
+    budget;
+    limit;
+    current;
+    model;
+    userId;
+    constructor(info) {
+        const target = info.budget === "perModel"
+            ? ` for model ${info.model}`
+            : info.budget === "perUser"
+                ? ` for user ${info.userId}`
+                : "";
+        super(`toad-eye: ${info.budget} budget exceeded${target} — limit $${info.limit}, current $${info.current.toFixed(2)}`);
+        this.name = "ToadBudgetExceededError";
+        this.budget = info.budget;
+        this.limit = info.limit;
+        this.current = info.current;
+        this.model = info.model;
+        this.userId = info.userId;
+    }
+}

package/dist/budget/index.d.ts

@@ -0,0 +1,3 @@
+export { BudgetTracker } from "./tracker.js";
+export { ToadBudgetExceededError } from "./error.js";
+export type { BudgetConfig, BudgetExceededMode, BudgetExceededInfo, BudgetState, DowngradeCallback, } from "./types.js";

package/dist/budget/index.js

@@ -0,0 +1,2 @@
+export { BudgetTracker } from "./tracker.js";
+export { ToadBudgetExceededError } from "./error.js";

package/dist/budget/tracker.d.ts

@@ -0,0 +1,35 @@
+import type { BudgetConfig, BudgetExceededMode, BudgetState, BudgetExceededInfo, DowngradeCallback } from "./types.js";
+export declare class BudgetTracker {
+    private readonly config;
+    private readonly mode;
+    private readonly downgrade?;
+    private state;
+    constructor(config: BudgetConfig, mode: BudgetExceededMode, downgrade?: DowngradeCallback);
+    /** Reset counters if the day has changed. */
+    private resetIfNewDay;
+    /**
+     * Check budget BEFORE making an LLM call.
+     * Returns modified provider/model if downgrade mode triggers,
+     * throws ToadBudgetExceededError if block mode triggers,
+     * returns null if no action needed.
+     */
+    checkBefore(provider: string, model: string, userId?: string): {
+        provider: string;
+        model: string;
+    } | null;
+    /** Record cost AFTER a successful LLM call. Returns exceeded info if budget was just crossed. */
+    recordCost(cost: number, model: string, userId?: string): BudgetExceededInfo | null;
+    /** Find which budget (if any) is exceeded. */
+    private findExceeded;
+    /** Get current budget usage as percentage (0-100+). */
+    getUsagePercent(): number;
+    /** Get current state snapshot (for persistence or debugging). */
+    getState(): Readonly<BudgetState>;
+    /** Restore state from persistence (e.g., on startup). */
+    restoreState(saved: {
+        date: string;
+        totalCost: number;
+        perUser: Record<string, number>;
+        perModel: Record<string, number>;
+    }): void;
+}

package/dist/budget/tracker.js

@@ -0,0 +1,121 @@
+import { ToadBudgetExceededError } from "./error.js";
+function todayUTC() {
+    return new Date().toISOString().slice(0, 10);
+}
+export class BudgetTracker {
+    config;
+    mode;
+    downgrade;
+    state;
+    constructor(config, mode, downgrade) {
+        this.config = config;
+        this.mode = mode;
+        this.downgrade = downgrade;
+        this.state = {
+            date: todayUTC(),
+            totalCost: 0,
+            perUser: new Map(),
+            perModel: new Map(),
+        };
+    }
+    /** Reset counters if the day has changed. */
+    resetIfNewDay() {
+        const today = todayUTC();
+        if (this.state.date !== today) {
+            this.state = {
+                date: today,
+                totalCost: 0,
+                perUser: new Map(),
+                perModel: new Map(),
+            };
+        }
+    }
+    /**
+     * Check budget BEFORE making an LLM call.
+     * Returns modified provider/model if downgrade mode triggers,
+     * throws ToadBudgetExceededError if block mode triggers,
+     * returns null if no action needed.
+     */
+    checkBefore(provider, model, userId) {
+        this.resetIfNewDay();
+        const exceeded = this.findExceeded(model, userId);
+        if (!exceeded)
+            return null;
+        if (this.mode === "block") {
+            throw new ToadBudgetExceededError(exceeded);
+        }
+        if (this.mode === "downgrade" && this.downgrade) {
+            return this.downgrade({ provider, model });
+        }
+        // 'warn' mode — continue, warning emitted after call
+        return null;
+    }
+    /** Record cost AFTER a successful LLM call. Returns exceeded info if budget was just crossed. */
+    recordCost(cost, model, userId) {
+        this.resetIfNewDay();
+        this.state.totalCost += cost;
+        this.state.perModel.set(model, (this.state.perModel.get(model) ?? 0) + cost);
+        if (userId) {
+            this.state.perUser.set(userId, (this.state.perUser.get(userId) ?? 0) + cost);
+        }
+        return this.findExceeded(model, userId);
+    }
+    /** Find which budget (if any) is exceeded. */
+    findExceeded(model, userId) {
+        if (this.config.daily !== undefined &&
+            this.state.totalCost >= this.config.daily) {
+            return {
+                budget: "daily",
+                limit: this.config.daily,
+                current: this.state.totalCost,
+            };
+        }
+        const modelLimit = this.config.perModel?.[model];
+        if (modelLimit !== undefined) {
+            const modelCost = this.state.perModel.get(model) ?? 0;
+            if (modelCost >= modelLimit) {
+                return {
+                    budget: "perModel",
+                    limit: modelLimit,
+                    current: modelCost,
+                    model,
+                };
+            }
+        }
+        if (this.config.perUser !== undefined && userId) {
+            const userCost = this.state.perUser.get(userId) ?? 0;
+            if (userCost >= this.config.perUser) {
+                return {
+                    budget: "perUser",
+                    limit: this.config.perUser,
+                    current: userCost,
+                    userId,
+                };
+            }
+        }
+        return null;
+    }
+    /** Get current budget usage as percentage (0-100+). */
+    getUsagePercent() {
+        if (this.config.daily === undefined || this.config.daily === 0)
+            return 0;
+        this.resetIfNewDay();
+        return (this.state.totalCost / this.config.daily) * 100;
+    }
+    /** Get current state snapshot (for persistence or debugging). */
+    getState() {
+        this.resetIfNewDay();
+        return this.state;
+    }
+    /** Restore state from persistence (e.g., on startup). */
+    restoreState(saved) {
+        if (saved.date !== todayUTC())
+            return; // stale state, ignore
+        this.state = {
+            date: saved.date,
+            totalCost: saved.totalCost,
+            perUser: new Map(Object.entries(saved.perUser)),
+            perModel: new Map(Object.entries(saved.perModel)),
+        };
+    }
+}

package/dist/budget/types.d.ts

@@ -0,0 +1,34 @@
+/** Budget configuration for initObservability(). */
+export interface BudgetConfig {
+    /** Max daily spend in USD for the entire application. */
+    readonly daily?: number | undefined;
+    /** Max daily spend in USD per user. Requires userId in traceLLMCall attributes. */
+    readonly perUser?: number | undefined;
+    /** Max daily spend in USD per model. */
+    readonly perModel?: Readonly<Record<string, number>> | undefined;
+}
+/** What happens when a budget is exceeded. */
+export type BudgetExceededMode = "warn" | "block" | "downgrade";
+/** Callback for 'downgrade' mode — receives original input, returns modified input. */
+export type DowngradeCallback = (original: {
+    readonly provider: string;
+    readonly model: string;
+}) => {
+    readonly provider: string;
+    readonly model: string;
+};
+/** Internal state tracking daily spend. */
+export interface BudgetState {
+    date: string;
+    totalCost: number;
+    perUser: Map<string, number>;
+    perModel: Map<string, number>;
+}
+/** Info about which budget was exceeded. */
+export interface BudgetExceededInfo {
+    readonly budget: "daily" | "perUser" | "perModel";
+    readonly limit: number;
+    readonly current: number;
+    readonly model?: string | undefined;
+    readonly userId?: string | undefined;
+}

package/dist/budget/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 import { execSync, spawn } from "node:child_process";
-import { cpSync, existsSync, mkdirSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { initObservability, traceLLMCall, shutdown, calculateCost, } from "./index.js";
 const INFRA_DIR = "infra/toad-eye";
+const DEMO_DELAY_MIN_MS = 200;
+const DEMO_DELAY_MAX_MS = 2000;
+const DEMO_ERROR_RATE = 0.1;
+const DEMO_TICK_INTERVAL_MS = 2000;
+const DEMO_TOKEN_INPUT_RANGE = [50, 500];
+const DEMO_TOKEN_OUTPUT_RANGE = [20, 300];
 const SERVICES = [
     { name: "Grafana", url: "http://localhost:3100", login: "admin / admin" },
     { name: "Jaeger UI", url: "http://localhost:16686" },
@@ -19,6 +25,14 @@ function getTemplatesDir() {
 function getComposeFile() {
     return join(process.cwd(), INFRA_DIR, "docker-compose.yml");
 }
+function requireInfra(message = `Run \`npx toad-eye init\` first.`) {
+    const composeFile = getComposeFile();
+    if (!existsSync(composeFile)) {
+        console.error(`\u274c ${INFRA_DIR}/ not found. ${message}`);
+        process.exit(1);
+    }
+    return composeFile;
+}
 function init() {
     const dest = join(process.cwd(), INFRA_DIR);
     if (existsSync(dest)) {
@@ -39,32 +53,20 @@ function init() {
     console.log("  npx toad-eye status  Check running services");
 }
 function up() {
-    const composeFile = getComposeFile();
-    if (!existsSync(composeFile)) {
-        console.error(`\u274c ${INFRA_DIR}/ not found. Run \`npx toad-eye init\` first.`);
-        process.exit(1);
-    }
+    const composeFile = requireInfra();
     console.log("\u{1f438} Starting observability stack...");
     execSync(`docker compose -f ${composeFile} up -d`, { stdio: "inherit" });
     console.log();
     status();
 }
 function down() {
-    const composeFile = getComposeFile();
-    if (!existsSync(composeFile)) {
-        console.error(`\u274c ${INFRA_DIR}/ not found. Nothing to stop.`);
-        process.exit(1);
-    }
+    const composeFile = requireInfra("Nothing to stop.");
     console.log("\u{1f44b} Stopping observability stack...");
     execSync(`docker compose -f ${composeFile} down`, { stdio: "inherit" });
     console.log("\u2705 Stack stopped.");
 }
 function status() {
-    const composeFile = getComposeFile();
-    if (!existsSync(composeFile)) {
-        console.error(`\u274c ${INFRA_DIR}/ not found. Run \`npx toad-eye init\` first.`);
-        process.exit(1);
-    }
+    const composeFile = requireInfra();
     try {
         const output = execSync(`docker compose -f ${composeFile} ps --format json`, {
             encoding: "utf-8",
@@ -104,12 +106,12 @@ function pickRandom(arr) {
     return arr[randomBetween(0, arr.length - 1)];
 }
 async function simulateLLMCall(provider, model, prompt) {
-    await new Promise((r) => setTimeout(r, randomBetween(200, 2000)));
-    if (Math.random() < 0.1) {
+    await new Promise((r) => setTimeout(r, randomBetween(DEMO_DELAY_MIN_MS, DEMO_DELAY_MAX_MS)));
+    if (Math.random() < DEMO_ERROR_RATE) {
         throw new Error(`${provider} API error: rate limit exceeded`);
     }
-    const inputTokens = randomBetween(50, 500);
-    const outputTokens = randomBetween(20, 300);
+    const inputTokens = randomBetween(...DEMO_TOKEN_INPUT_RANGE);
+    const outputTokens = randomBetween(...DEMO_TOKEN_OUTPUT_RANGE);
     return {
         completion: `Mock response for: "${prompt}"`,
         inputTokens,
@@ -118,11 +120,7 @@ async function simulateLLMCall(provider, model, prompt) {
     };
 }
 async function demo() {
-    const composeFile = getComposeFile();
-    if (!existsSync(composeFile)) {
-        console.error(`\u274c ${INFRA_DIR}/ not found. Run \`npx toad-eye init\` first.`);
-        process.exit(1);
-    }
+    requireInfra();
     initObservability({
         serviceName: "toad-eye-demo",
         endpoint: "http://localhost:4318",
@@ -147,10 +145,46 @@ async function demo() {
         }
     };
     const run = () => {
-        tick().then(() => setTimeout(run, 2000));
+        tick().then(() => setTimeout(run, DEMO_TICK_INTERVAL_MS));
     };
     run();
 }
+async function exportTraceCommand() {
+    const traceId = process.argv[3];
+    if (!traceId) {
+        console.error("✗ Usage: npx toad-eye export-trace <trace_id> [--output dir] [--jaeger-url url]");
+        process.exit(1);
+    }
+    const args = process.argv.slice(4);
+    let outputDir = process.cwd();
+    let jaegerUrl;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--output" && args[i + 1]) {
+            outputDir = resolve(args[i + 1]);
+            i++;
+        }
+        else if (args[i] === "--jaeger-url" && args[i + 1]) {
+            jaegerUrl = args[i + 1];
+            i++;
+        }
+    }
+    const { exportTrace } = await import("./export.js");
+    try {
+        const yaml = await exportTrace(traceId, { jaegerUrl });
+        const filename = `trace-${traceId.slice(0, 8)}.eval.yaml`;
+        const filepath = join(outputDir, filename);
+        if (!existsSync(outputDir)) {
+            mkdirSync(outputDir, { recursive: true });
+        }
+        writeFileSync(filepath, yaml, "utf-8");
+        console.log(`✅ Exported trace ${traceId} → ${filepath}`);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.error(`✗ ${msg}`);
+        process.exit(1);
+    }
+}
 function help() {
     console.log(`
 \u{1f438} toad-eye CLI — observability stack for LLM services
@@ -160,8 +194,9 @@ Commands:
   up       Start the stack (OTel Collector + Prometheus + Jaeger + Grafana)
   down     Stop the stack
   status   Show running services and URLs
-  demo     Send mock LLM traffic to see data in Grafana
-  help     Show this message
+  demo           Send mock LLM traffic to see data in Grafana
+  export-trace   Export a Jaeger trace to toad-eval YAML
+  help           Show this message
 `);
 }
 const command = process.argv[2];
@@ -181,6 +216,9 @@ switch (command) {
     case "demo":
         demo();
         break;
+    case "export-trace":
+        exportTraceCommand();
+        break;
     case "help":
     case "--help":
     case "-h":

package/dist/core/metrics.d.ts

@@ -0,0 +1,14 @@
+export declare function initMetrics(): void;
+export declare function recordRequestDuration(ms: number, provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordRequestCost(usd: number, provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordTokens(count: number, provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordRequest(provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordError(provider: string, model: string, attrs?: Record<string, string>): void;
+export declare function recordAgentSteps(stepCount: number): void;
+export declare function recordAgentToolUsage(toolName: string): void;
+export declare function recordGuardEvaluation(ruleName: string): void;
+export declare function recordGuardWouldBlock(ruleName: string): void;
+export declare function recordSemanticDrift(drift: number, provider: string, model: string): void;
+export declare function recordBudgetExceeded(budgetType: string): void;
+export declare function recordBudgetBlocked(budgetType: string): void;
+export declare function recordBudgetDowngraded(budgetType: string): void;

package/dist/core/metrics.js

@@ -0,0 +1,119 @@
+import { metrics } from "@opentelemetry/api";
+import { GEN_AI_ATTRS, GEN_AI_METRICS, INSTRUMENTATION_NAME, } from "../types/index.js";
+let requestDuration;
+let requestCost;
+let tokenUsage;
+let requestsTotal;
+let errorsTotal;
+let agentStepsPerQuery;
+let agentToolUsage;
+let guardEvaluations;
+let guardWouldBlock;
+let semanticDrift;
+let budgetExceeded;
+let budgetBlocked;
+let budgetDowngraded;
+let initialized = false;
+export function initMetrics() {
+    if (initialized)
+        return;
+    const meter = metrics.getMeter(INSTRUMENTATION_NAME);
+    requestDuration = meter.createHistogram(GEN_AI_METRICS.REQUEST_DURATION, {
+        description: "GenAI operation duration in milliseconds",
+        unit: "ms",
+    });
+    requestCost = meter.createHistogram(GEN_AI_METRICS.REQUEST_COST, {
+        description: "GenAI request cost in USD",
+        unit: "USD",
+    });
+    tokenUsage = meter.createCounter(GEN_AI_METRICS.TOKEN_USAGE, {
+        description: "Total tokens consumed",
+    });
+    requestsTotal = meter.createCounter(GEN_AI_METRICS.REQUESTS, {
+        description: "Total GenAI requests",
+    });
+    errorsTotal = meter.createCounter(GEN_AI_METRICS.ERRORS, {
+        description: "Total failed GenAI requests",
+    });
+    agentStepsPerQuery = meter.createHistogram(GEN_AI_METRICS.AGENT_STEPS_PER_QUERY, {
+        description: "Number of agent steps per query",
+    });
+    agentToolUsage = meter.createCounter(GEN_AI_METRICS.AGENT_TOOL_USAGE, {
+        description: "Agent tool invocations by tool name",
+    });
+    guardEvaluations = meter.createCounter(GEN_AI_METRICS.GUARD_EVALUATIONS, {
+        description: "Total guard evaluations (shadow + enforce)",
+    });
+    guardWouldBlock = meter.createCounter(GEN_AI_METRICS.GUARD_WOULD_BLOCK, {
+        description: "Guard evaluations that would have blocked the response",
+    });
+    semanticDrift = meter.createHistogram(GEN_AI_METRICS.SEMANTIC_DRIFT, {
+        description: "Semantic drift from baseline (0 = identical, 1 = completely different)",
+    });
+    budgetExceeded = meter.createCounter(GEN_AI_METRICS.BUDGET_EXCEEDED, {
+        description: "Number of times a budget limit was exceeded",
+    });
+    budgetBlocked = meter.createCounter(GEN_AI_METRICS.BUDGET_BLOCKED, {
+        description: "Number of LLM calls blocked due to budget limits",
+    });
+    budgetDowngraded = meter.createCounter(GEN_AI_METRICS.BUDGET_DOWNGRADED, {
+        description: "Number of LLM calls downgraded due to budget limits",
+    });
+    initialized = true;
+}
+/** Build metric labels: provider + model + optional FinOps attributes. */
+function baseLabels(provider, model, attrs) {
+    return {
+        [GEN_AI_ATTRS.PROVIDER]: provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+        ...attrs,
+    };
+}
+export function recordRequestDuration(ms, provider, model, attrs) {
+    requestDuration.record(ms, baseLabels(provider, model, attrs));
+}
+export function recordRequestCost(usd, provider, model, attrs) {
+    requestCost.record(usd, baseLabels(provider, model, attrs));
+}
+export function recordTokens(count, provider, model, attrs) {
+    tokenUsage.add(count, baseLabels(provider, model, attrs));
+}
+export function recordRequest(provider, model, attrs) {
+    requestsTotal.add(1, baseLabels(provider, model, attrs));
+}
+export function recordError(provider, model, attrs) {
+    errorsTotal.add(1, baseLabels(provider, model, attrs));
+}
+export function recordAgentSteps(stepCount) {
+    agentStepsPerQuery.record(stepCount);
+}
+export function recordAgentToolUsage(toolName) {
+    agentToolUsage.add(1, {
+        [GEN_AI_ATTRS.AGENT_TOOL_NAME]: toolName,
+    });
+}
+export function recordGuardEvaluation(ruleName) {
+    guardEvaluations.add(1, {
+        [GEN_AI_ATTRS.GUARD_RULE_NAME]: ruleName,
+    });
+}
+export function recordGuardWouldBlock(ruleName) {
+    guardWouldBlock.add(1, {
+        [GEN_AI_ATTRS.GUARD_RULE_NAME]: ruleName,
+    });
+}
+export function recordSemanticDrift(drift, provider, model) {
+    semanticDrift.record(drift, {
+        [GEN_AI_ATTRS.PROVIDER]: provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: model,
+    });
+}
+export function recordBudgetExceeded(budgetType) {
+    budgetExceeded.add(1, { budget_type: budgetType });
+}
+export function recordBudgetBlocked(budgetType) {
+    budgetBlocked.add(1, { budget_type: budgetType });
+}
+export function recordBudgetDowngraded(budgetType) {
+    budgetDowngraded.add(1, { budget_type: budgetType });
+}