toad-eye 2.0.0 → 2.1.1

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 });
+}

package/dist/{spans.d.ts → core/spans.d.ts}

@@ -1,10 +1,12 @@
-import type { LLMSpanAttributes } from "./types/index.js";
+import type { LLMSpanAttributes } from "../types/index.js";
 /** Input for traceLLMCall — what the user knows before calling the LLM */
 export interface LLMCallInput {
     readonly provider: LLMSpanAttributes["provider"];
     readonly model: string;
     readonly prompt: string;
     readonly temperature?: number | undefined;
+    /** Per-request FinOps attributes (team, userId, feature, etc). Merged with global attributes. */
+    readonly attributes?: Readonly<Record<string, string>> | undefined;
 }
 /** Output from the LLM call — what comes back */
 export interface LLMCallOutput {

package/dist/core/spans.js

@@ -0,0 +1,143 @@
+import { createHash } from "node:crypto";
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { GEN_AI_ATTRS, INSTRUMENTATION_NAME } from "../types/index.js";
+import { recordRequestDuration, recordRequestCost, recordTokens, recordRequest, recordError, recordBudgetExceeded, recordBudgetBlocked, recordBudgetDowngraded, } from "./metrics.js";
+import { getConfig, getBudgetTracker } from "./tracer.js";
+import { GEN_AI_ATTRS as ATTRS } from "../types/index.js";
+const tracer = trace.getTracer(INSTRUMENTATION_NAME);
+function sha256(text) {
+    const salt = getConfig()?.salt ?? "";
+    return createHash("sha256")
+        .update(salt + text)
+        .digest("hex");
+}
+function processContent(text) {
+    const config = getConfig();
+    if (config?.recordContent === false)
+        return undefined;
+    let processed = text;
+    if (config?.redactPatterns?.length) {
+        for (const pattern of config.redactPatterns) {
+            processed = processed.replace(pattern, "[REDACTED]");
+        }
+    }
+    if (config?.hashContent) {
+        return `sha256:${sha256(processed)}`;
+    }
+    return processed;
+}
+function resolveSessionId() {
+    const config = getConfig();
+    return config?.sessionExtractor?.() ?? config?.sessionId;
+}
+/** Merge global config attributes with per-request attributes (per-request wins). */
+function resolveAttributes(input) {
+    const global = getConfig()?.attributes;
+    const local = input.attributes;
+    if (!global && !local)
+        return undefined;
+    return { ...global, ...local };
+}
+function setBaseAttributes(span, input) {
+    const prompt = processContent(input.prompt);
+    const sessionId = resolveSessionId();
+    const attrs = resolveAttributes(input);
+    span.setAttributes({
+        [GEN_AI_ATTRS.PROVIDER]: input.provider,
+        [GEN_AI_ATTRS.REQUEST_MODEL]: input.model,
+        [GEN_AI_ATTRS.TEMPERATURE]: input.temperature ?? 1.0,
+        [GEN_AI_ATTRS.OPERATION]: "chat",
+        ...(prompt !== undefined && { [GEN_AI_ATTRS.PROMPT]: prompt }),
+        ...(sessionId !== undefined && { [GEN_AI_ATTRS.SESSION_ID]: sessionId }),
+        ...attrs,
+    });
+}
+function recordBaseMetrics(duration, provider, model, attrs) {
+    recordRequest(provider, model, attrs);
+    recordRequestDuration(duration, provider, model, attrs);
+}
+function setSuccessAttributes(span, input, output) {
+    const completion = processContent(output.completion);
+    span.setAttributes({
+        ...(completion !== undefined && { [GEN_AI_ATTRS.COMPLETION]: completion }),
+        [GEN_AI_ATTRS.RESPONSE_MODEL]: input.model,
+        [GEN_AI_ATTRS.INPUT_TOKENS]: output.inputTokens,
+        [GEN_AI_ATTRS.OUTPUT_TOKENS]: output.outputTokens,
+        [GEN_AI_ATTRS.COST]: output.cost,
+        [GEN_AI_ATTRS.STATUS]: "success",
+        [GEN_AI_ATTRS.FINISH_REASONS]: ["stop"],
+    });
+    span.setStatus({ code: SpanStatusCode.OK });
+}
+function setErrorAttributes(span, message) {
+    const sanitized = processContent(message);
+    span.setAttributes({
+        [GEN_AI_ATTRS.INPUT_TOKENS]: 0,
+        [GEN_AI_ATTRS.OUTPUT_TOKENS]: 0,
+        [GEN_AI_ATTRS.COST]: 0,
+        [GEN_AI_ATTRS.STATUS]: "error",
+        ...(sanitized !== undefined && { [GEN_AI_ATTRS.ERROR]: sanitized }),
+    });
+    span.setStatus({
+        code: SpanStatusCode.ERROR,
+        ...(sanitized !== undefined && { message: sanitized }),
+    });
+}
+export async function traceLLMCall(input, fn) {
+    const budget = getBudgetTracker();
+    let effectiveInput = input;
+    // Budget check BEFORE the LLM call
+    if (budget) {
+        const userId = input.attributes?.[ATTRS.USER_ID];
+        const override = budget.checkBefore(input.provider, input.model, userId);
+        if (override) {
+            // Downgrade mode — use modified provider/model
+            effectiveInput = {
+                ...input,
+                provider: override.provider,
+                model: override.model,
+            };
+            recordBudgetDowngraded("daily");
+        }
+    }
+    return tracer.startActiveSpan(`gen_ai.${effectiveInput.provider}.${effectiveInput.model}`, async (span) => {
+        const start = performance.now();
+        setBaseAttributes(span, effectiveInput);
+        try {
+            const output = await fn();
+            const duration = performance.now() - start;
+            const attrs = resolveAttributes(effectiveInput);
+            setSuccessAttributes(span, effectiveInput, output);
+            recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
+            recordRequestCost(output.cost, effectiveInput.provider, effectiveInput.model, attrs);
+            recordTokens(output.inputTokens + output.outputTokens, effectiveInput.provider, effectiveInput.model, attrs);
+            // Budget recording AFTER the call
+            if (budget) {
+                const userId = effectiveInput.attributes?.[ATTRS.USER_ID];
+                const exceeded = budget.recordCost(output.cost, effectiveInput.model, userId);
+                if (exceeded) {
+                    recordBudgetExceeded(exceeded.budget);
+                    console.warn(`toad-eye: ${exceeded.budget} budget exceeded — limit $${exceeded.limit}, current $${exceeded.current.toFixed(2)}`);
+                }
+            }
+            return output;
+        }
+        catch (error) {
+            const duration = performance.now() - start;
+            const message = error instanceof Error ? error.message : String(error);
+            const attrs = resolveAttributes(effectiveInput);
+            setErrorAttributes(span, message);
+            recordBaseMetrics(duration, effectiveInput.provider, effectiveInput.model, attrs);
+            recordError(effectiveInput.provider, effectiveInput.model, attrs);
+            // If this was a budget block, record the metric
+            if (error instanceof Error &&
+                error.name === "ToadBudgetExceededError") {
+                recordBudgetBlocked("daily");
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}

package/dist/core/tracer.d.ts

@@ -0,0 +1,9 @@
+import type { ToadEyeConfig } from "../types/index.js";
+import { BudgetTracker } from "../budget/index.js";
+import "../instrumentations/openai.js";
+import "../instrumentations/anthropic.js";
+import "../instrumentations/gemini.js";
+export declare function getConfig(): ToadEyeConfig | null;
+export declare function getBudgetTracker(): BudgetTracker | null;
+export declare function initObservability(config: ToadEyeConfig): void;
+export declare function shutdown(): Promise<void>;