hazo_llm_api 1.2.12 → 1.3.0

package/dist/components/llm_cost_dashboard/llm_cost_dashboard.js

@@ -0,0 +1,154 @@
+/**
+ * LLMCostDashboard Component
+ *
+ * Displays aggregated LLM usage and cost data.
+ * Framework-agnostic: accepts a fetch_summary prop instead of accessing
+ * the database directly.
+ */
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState, useEffect, useCallback } from 'react';
+import { cn } from '../../lib/utils.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function fmt_cost(value) {
+    if (value == null)
+        return '$0.0000';
+    return `$${Number(value).toFixed(4)}`;
+}
+function fmt_latency(value) {
+    if (value == null)
+        return '—';
+    return `${Math.round(Number(value))} ms`;
+}
+function fmt_number(value) {
+    if (value == null)
+        return '—';
+    return Number(value).toLocaleString();
+}
+/** Return today's date as YYYY-MM-DD */
+function today_str() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Return the date 30 days ago as YYYY-MM-DD */
+function thirty_days_ago_str() {
+    const d = new Date();
+    d.setDate(d.getDate() - 30);
+    return d.toISOString().slice(0, 10);
+}
+// ---------------------------------------------------------------------------
+// Group-by options shown in the select control
+// ---------------------------------------------------------------------------
+const GROUP_BY_OPTIONS = [
+    { value: 'date', label: 'Date' },
+    { value: 'provider', label: 'Provider' },
+    { value: 'model', label: 'Model' },
+    { value: 'service_type', label: 'Service Type' },
+];
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+export function LLMCostDashboard({ fetch_summary, className }) {
+    const [loading, set_loading] = useState(false);
+    const [error, set_error] = useState(null);
+    const [response, set_response] = useState(null);
+    // Filter state
+    const [group_by, set_group_by] = useState('date');
+    const [from, set_from] = useState(thirty_days_ago_str);
+    const [to, set_to] = useState(today_str);
+    // Pending filter state (used before "Apply Filters" is clicked)
+    const [pending_group_by, set_pending_group_by] = useState('date');
+    const [pending_from, set_pending_from] = useState(thirty_days_ago_str);
+    const [pending_to, set_pending_to] = useState(today_str);
+    const fetch_data = useCallback(async (opts) => {
+        set_loading(true);
+        set_error(null);
+        try {
+            const result = await fetch_summary({
+                from: opts.from,
+                to: opts.to,
+                group_by: [opts.group_by],
+            });
+            set_response(result);
+        }
+        catch (err) {
+            set_error(err instanceof Error ? err.message : 'Failed to fetch data');
+        }
+        finally {
+            set_loading(false);
+        }
+    }, [fetch_summary]);
+    // Auto-fetch on mount
+    useEffect(() => {
+        fetch_data({ from, to, group_by });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fetch_data]); // fetch_data is memoized via useCallback; re-runs only if fetch_summary changes
+    function handle_apply() {
+        set_from(pending_from);
+        set_to(pending_to);
+        set_group_by(pending_group_by);
+        fetch_data({ from: pending_from, to: pending_to, group_by: pending_group_by });
+    }
+    function handle_refresh() {
+        fetch_data({ from, to, group_by });
+    }
+    // ---------------------------------------------------------------------------
+    // Chart (only when group_by === 'date')
+    // ---------------------------------------------------------------------------
+    const show_chart = group_by === 'date' && response !== null && response.rows.length > 0;
+    // Build simple inline SVG line chart — hazo_ui LineChart is a peer dep we
+    // cannot guarantee is available at this layer, so we render a minimal inline
+    // chart to avoid import errors at build time.
+    function render_inline_chart() {
+        if (!show_chart || !response)
+            return null;
+        const rows = response.rows;
+        const values = rows.map((r) => Number(r['total_cost_usd']) || 0);
+        const max_val = Math.max(...values, 0.0001);
+        const width = 600;
+        const height = 160;
+        const pad = 32;
+        const inner_w = width - pad * 2;
+        const inner_h = height - pad * 2;
+        const step = values.length > 1 ? inner_w / (values.length - 1) : inner_w;
+        const points = values.map((v, i) => {
+            const x = pad + (values.length > 1 ? i * step : inner_w / 2);
+            const y = pad + inner_h - (v / max_val) * inner_h;
+            return `${x},${y}`;
+        });
+        return (_jsxs("div", { className: "cls_cost_chart_wrapper mb-6 rounded-lg border border-gray-200 bg-white p-4", children: [_jsx("p", { className: "cls_chart_label mb-2 text-sm font-medium text-gray-600", children: "Total Cost (USD)" }), _jsxs("svg", { viewBox: `0 0 ${width} ${height}`, className: "cls_chart_svg w-full", style: { height: height }, "aria-label": "Total cost over time", role: "img", children: [[0, 0.25, 0.5, 0.75, 1].map((frac) => {
+                            const y = pad + frac * inner_h;
+                            return (_jsx("line", { x1: pad, y1: y, x2: pad + inner_w, y2: y, stroke: "#e5e7eb", strokeWidth: "1" }, frac));
+                        }), values.length > 1 && (_jsx("polyline", { points: points.join(' '), fill: "none", stroke: "#6366f1", strokeWidth: "2", strokeLinejoin: "round", strokeLinecap: "round" })), points.map((pt, i) => {
+                            const [x, y] = pt.split(',').map(Number);
+                            return (_jsx("circle", { cx: x, cy: y, r: "3", fill: "#6366f1" }, i));
+                        })] })] }));
+    }
+    // ---------------------------------------------------------------------------
+    // Table column definitions
+    // ---------------------------------------------------------------------------
+    function get_group_col_label() {
+        switch (group_by) {
+            case 'date': return 'Date';
+            case 'provider': return 'Provider';
+            case 'model': return 'Model';
+            case 'service_type': return 'Service Type';
+            case 'session_id': return 'Session ID';
+            case 'reference': return 'Reference';
+            default: return String(group_by);
+        }
+    }
+    function get_group_col_key() {
+        return group_by;
+    }
+    // ---------------------------------------------------------------------------
+    // Render
+    // ---------------------------------------------------------------------------
+    const rows = response?.rows ?? [];
+    const totals = response?.totals;
+    return (_jsxs("div", { className: cn('cls_llm_cost_dashboard', className), children: [_jsxs("div", { className: "cls_dashboard_header mb-4 flex items-center justify-between", children: [_jsx("h2", { className: "text-xl font-semibold text-gray-900", children: "LLM Cost Dashboard" }), _jsx("button", { type: "button", onClick: handle_refresh, disabled: loading, className: "cls_refresh_btn inline-flex items-center rounded-md border border-gray-300 bg-white px-3 py-1.5 text-sm font-medium text-gray-700 shadow-sm hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50", children: loading ? 'Loading...' : 'Refresh' })] }), _jsxs("div", { className: "cls_filter_bar mb-6 flex flex-wrap items-center gap-3 rounded-lg border border-gray-200 bg-gray-50 px-4 py-3", children: [_jsxs("div", { className: "cls_filter_dates flex items-center gap-2", children: [_jsx("label", { className: "text-sm text-gray-600", htmlFor: "cls_from_date", children: "From" }), _jsx("input", { id: "cls_from_date", type: "date", value: pending_from, onChange: (e) => set_pending_from(e.target.value), className: "cls_date_input rounded border border-gray-300 px-2 py-1 text-sm" }), _jsx("label", { className: "text-sm text-gray-600", htmlFor: "cls_to_date", children: "To" }), _jsx("input", { id: "cls_to_date", type: "date", value: pending_to, onChange: (e) => set_pending_to(e.target.value), className: "cls_date_input rounded border border-gray-300 px-2 py-1 text-sm" })] }), _jsxs("div", { className: "cls_filter_groupby flex items-center gap-2", children: [_jsx("label", { className: "text-sm text-gray-600", htmlFor: "cls_group_by_select", children: "Group by" }), _jsx("select", { id: "cls_group_by_select", value: pending_group_by, onChange: (e) => set_pending_group_by(e.target.value), className: "cls_groupby_select rounded border border-gray-300 px-2 py-1 text-sm", children: GROUP_BY_OPTIONS.map((opt) => (_jsx("option", { value: opt.value, children: opt.label }, opt.value))) })] }), _jsx("button", { type: "button", onClick: handle_apply, disabled: loading, className: "cls_apply_btn rounded-md bg-indigo-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-indigo-700 disabled:cursor-not-allowed disabled:opacity-50", children: "Apply Filters" })] }), error && (_jsx("div", { className: "cls_error_msg mb-4 rounded-md border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700", children: error })), loading && (_jsx("div", { className: "cls_loading_msg py-8 text-center text-sm text-gray-500", children: "Loading..." })), !loading && response !== null && (_jsxs(_Fragment, { children: [render_inline_chart(), rows.length === 0 ? (_jsx("div", { className: "cls_empty_msg py-8 text-center text-sm text-gray-500", children: "No data" })) : (
+                    /* Summary table */
+                    _jsx("div", { className: "cls_summary_table_wrapper overflow-x-auto rounded-lg border border-gray-200", children: _jsxs("table", { className: "cls_summary_table w-full text-sm", children: [_jsx("thead", { children: _jsxs("tr", { className: "border-b border-gray-200 bg-gray-50", children: [_jsx("th", { className: "cls_th px-4 py-3 text-left font-medium text-gray-700", children: get_group_col_label() }), _jsx("th", { className: "cls_th px-4 py-3 text-right font-medium text-gray-700", children: "Count" }), _jsx("th", { className: "cls_th px-4 py-3 text-right font-medium text-gray-700", children: "Total Cost (USD)" }), _jsx("th", { className: "cls_th px-4 py-3 text-right font-medium text-gray-700", children: "Input Tokens" }), _jsx("th", { className: "cls_th px-4 py-3 text-right font-medium text-gray-700", children: "Output Tokens" }), _jsx("th", { className: "cls_th px-4 py-3 text-right font-medium text-gray-700", children: "Avg Latency" })] }) }), _jsx("tbody", { children: rows.map((row, idx) => (_jsxs("tr", { className: cn('cls_data_row border-b border-gray-100', idx % 2 === 0 ? 'bg-white' : 'bg-gray-50/50'), children: [_jsx("td", { className: "cls_td px-4 py-2.5 text-gray-900", children: String(row[get_group_col_key()] ?? '—') }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-700", children: fmt_number(row['count']) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-700", children: fmt_cost(row['total_cost_usd']) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-700", children: fmt_number(row['total_tokens_input']) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-700", children: fmt_number(row['total_tokens_output']) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-700", children: fmt_latency(row['avg_latency_ms']) })] }, idx))) }), totals && (_jsx("tfoot", { children: _jsxs("tr", { className: "cls_totals_row border-t-2 border-gray-300 bg-gray-100 font-medium", children: [_jsx("td", { className: "cls_td px-4 py-2.5 text-gray-900", children: "Totals" }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-900", children: fmt_number(totals.count) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-900", children: fmt_cost(totals.total_cost_usd) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-900", children: fmt_number(totals.total_tokens_input) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right tabular-nums text-gray-900", children: fmt_number(totals.total_tokens_output) }), _jsx("td", { className: "cls_td px-4 py-2.5 text-right text-gray-400", children: "\u2014" })] }) }))] }) }))] }))] }));
+}
+//# sourceMappingURL=llm_cost_dashboard.js.map

package/dist/components/llm_cost_dashboard/llm_cost_dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_cost_dashboard.js","sourceRoot":"","sources":["../../../src/components/llm_cost_dashboard/llm_cost_dashboard.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -13,5 +13,6 @@ export { LLM_PROVIDERS, SERVICE_TYPES } from './lib/providers/types.js';
 export type { ProviderName, ServiceType } from './lib/providers/types.js';
 export { LLM_ERROR_CODES } from './lib/llm_api/types.js';
 export type { LLMErrorCode, LLMError } from './lib/llm_api/types.js';
-export type { LLMApiConfig, LLMApiClient, CallLLMParams, LLMResponse, Logger, PromptVariable, PromptVariables, Base64Data, PromptTextMode, PromptRecord, } from './lib/llm_api/types.js';
+export type { LLMApiConfig, LLMApiClient, CallLLMParams, LLMResponse, Logger, PromptVariable, PromptVariables, Base64Data, PromptTextMode, PromptRecord, EmbedParams, EmbedResponse, EmbedKeyv, PromptPart, } from './lib/llm_api/types.js';
+export type { FetchSummaryFn, FetchDetailFn, UsageSummaryOptions, UsageSummaryResponse, UsageSummaryRow, UsageSummaryGroupBy, ApiLogRow, } from './lib/observability/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,cAAc,uBAAuB,CAAC;AAMtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAK1E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAKrE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,MAAM,EACN,cAAc,EACd,eAAe,EACf,UAAU,EACV,cAAc,EACd,YAAY,GACb,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,cAAc,uBAAuB,CAAC;AAMtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,uBAAuB,EACvB,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACxE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAK1E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAKrE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,WAAW,EACX,MAAM,EACN,cAAc,EACd,eAAe,EACf,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,UAAU,GACX,MAAM,wBAAwB,CAAC;AAKhC,YAAY,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,SAAS,GACV,MAAM,8BAA8B,CAAC"}

package/dist/lib/cascade/cascade_runner.d.ts

@@ -0,0 +1,50 @@
+import type { LLMProvider } from '../providers/types.js';
+import type { LLMResponse, Logger } from '../llm_api/types.js';
+import type { CascadeConfig } from './types.js';
+import type { UsageAttempt } from '../pricing/types.js';
+export interface CascadeRunOptions {
+    /** Resolved provider instances to try in order */
+    providers: LLMProvider[];
+    /** Bound call function (params already captured by closure) */
+    call_fn: (provider: LLMProvider) => Promise<LLMResponse>;
+    /** Error codes that allow cascade to next provider */
+    cascade_on_codes?: string[];
+    /** Per-attempt timeout in milliseconds (no timeout if absent) */
+    timeout_ms_per_attempt?: number;
+    /** Logger */
+    logger: Logger;
+}
+export interface CascadeRunResult {
+    response: LLMResponse;
+    /**
+     * Failed attempts before the final result. Empty array when the first
+     * provider succeeded (no cascade fired).
+     */
+    attempts: UsageAttempt[];
+}
+export interface ResolveProvidersOptions {
+    per_call?: string[];
+    init_cascade?: CascadeConfig;
+    single_llm?: string;
+    primary_llm: string;
+}
+/**
+ * Determine the ordered list of provider names to use.
+ * Precedence: per-call providers > init cascade providers > single_llm arg > primary_llm.
+ * An empty per_call array is treated as "not set" (falls through).
+ */
+export declare function resolve_providers(opts: ResolveProvidersOptions): string[];
+/**
+ * Try each provider in order, returning the first successful response.
+ *
+ * Rules:
+ * - Success on first try → `attempts` is empty (no cascade record).
+ * - Cascadable error (RATE_LIMITED, NETWORK_ERROR, TIMEOUT, API_ERROR by default) →
+ *   record attempt, try next provider.
+ * - Non-cascadable error (config errors: PROVIDER_NOT_FOUND, API_KEY_MISSING, etc.) →
+ *   return immediately without trying more providers.
+ * - Timeout → treated as TIMEOUT error code, always cascadable.
+ * - All providers exhausted → return last error with all attempts recorded.
+ */
+export declare function run_with_cascade(opts: CascadeRunOptions): Promise<CascadeRunResult>;
+//# sourceMappingURL=cascade_runner.d.ts.map

package/dist/lib/cascade/cascade_runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade_runner.d.ts","sourceRoot":"","sources":["../../../src/lib/cascade/cascade_runner.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAMxD,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,+DAA+D;IAC/D,OAAO,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IACzD,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,iEAAiE;IACjE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,aAAa;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,YAAY,CAAC,EAAE,aAAa,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,uBAAuB,GAAG,MAAM,EAAE,CAazE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgFzF"}

package/dist/lib/cascade/cascade_runner.js

@@ -0,0 +1,115 @@
+// file_description: Cascade runner — tries LLM providers in order until one succeeds
+import { LLM_ERROR_CODES } from '../llm_api/types.js';
+import { DEFAULT_CASCADE_ON_CODES } from './types.js';
+// =============================================================================
+// resolve_providers
+// =============================================================================
+/**
+ * Determine the ordered list of provider names to use.
+ * Precedence: per-call providers > init cascade providers > single_llm arg > primary_llm.
+ * An empty per_call array is treated as "not set" (falls through).
+ */
+export function resolve_providers(opts) {
+    const { per_call, init_cascade, single_llm, primary_llm } = opts;
+    if (per_call && per_call.length > 0) {
+        return per_call;
+    }
+    if (init_cascade?.providers && init_cascade.providers.length > 0) {
+        return init_cascade.providers;
+    }
+    if (single_llm) {
+        return [single_llm];
+    }
+    return [primary_llm];
+}
+// =============================================================================
+// run_with_cascade
+// =============================================================================
+/**
+ * Try each provider in order, returning the first successful response.
+ *
+ * Rules:
+ * - Success on first try → `attempts` is empty (no cascade record).
+ * - Cascadable error (RATE_LIMITED, NETWORK_ERROR, TIMEOUT, API_ERROR by default) →
+ *   record attempt, try next provider.
+ * - Non-cascadable error (config errors: PROVIDER_NOT_FOUND, API_KEY_MISSING, etc.) →
+ *   return immediately without trying more providers.
+ * - Timeout → treated as TIMEOUT error code, always cascadable.
+ * - All providers exhausted → return last error with all attempts recorded.
+ */
+export async function run_with_cascade(opts) {
+    const { providers, call_fn, cascade_on_codes = DEFAULT_CASCADE_ON_CODES, timeout_ms_per_attempt, logger, } = opts;
+    const attempts = [];
+    for (let i = 0; i < providers.length; i++) {
+        const provider = providers[i];
+        const provider_name = provider.get_name();
+        const is_last = i === providers.length - 1;
+        const t0 = Date.now();
+        let response;
+        try {
+            if (timeout_ms_per_attempt) {
+                response = await Promise.race([
+                    call_fn(provider),
+                    make_timeout_promise(timeout_ms_per_attempt, provider_name),
+                ]);
+            }
+            else {
+                response = await call_fn(provider);
+            }
+        }
+        catch (err) {
+            // Thrown exception: timeout or unhandled provider throw
+            const latency_ms = Date.now() - t0;
+            const error_code = err instanceof TimeoutError
+                ? LLM_ERROR_CODES.TIMEOUT
+                : LLM_ERROR_CODES.NETWORK_ERROR;
+            const error_msg = err instanceof Error ? err.message : String(err);
+            const attempt = { provider: provider_name, success: false, error_code, latency_ms };
+            if (!is_last && cascade_on_codes.includes(error_code)) {
+                logger.warn(`[cascade] ${provider_name} threw ${error_code} — trying next`, { provider: provider_name, error_code, latency_ms });
+                attempts.push(attempt);
+                continue;
+            }
+            return {
+                response: {
+                    success: false,
+                    error: error_msg,
+                    error_info: { code: error_code, message: error_msg, retryable: true },
+                },
+                attempts: [...attempts, attempt],
+            };
+        }
+        const latency_ms = Date.now() - t0;
+        if (response.success) {
+            return { response, attempts };
+        }
+        // Failed response
+        const error_code = response.error_info?.code ?? LLM_ERROR_CODES.UNKNOWN;
+        const is_cascadable = cascade_on_codes.includes(error_code);
+        if (!is_last && is_cascadable) {
+            logger.warn(`[cascade] ${provider_name} returned ${error_code} — trying next`, { provider: provider_name, error_code, latency_ms });
+            attempts.push({ provider: provider_name, success: false, error_code, latency_ms });
+            continue;
+        }
+        // Either last provider or non-cascadable error — return now
+        const final_attempts = is_last && attempts.length > 0
+            ? [...attempts, { provider: provider_name, success: false, error_code, latency_ms }]
+            : attempts;
+        return { response, attempts: final_attempts };
+    }
+    // Unreachable — loop always returns
+    return { response: { success: false, error: 'cascade: no providers' }, attempts };
+}
+// =============================================================================
+// Timeout helper
+// =============================================================================
+class TimeoutError extends Error {
+    constructor(provider, ms) {
+        super(`[cascade] provider "${provider}" timed out after ${ms}ms`);
+        this.name = 'TimeoutError';
+    }
+}
+function make_timeout_promise(ms, provider) {
+    return new Promise((_, reject) => setTimeout(() => reject(new TimeoutError(provider, ms)), ms));
+}
+//# sourceMappingURL=cascade_runner.js.map

package/dist/lib/cascade/cascade_runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade_runner.js","sourceRoot":"","sources":["../../../src/lib/cascade/cascade_runner.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAIrF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAoCtD,gFAAgF;AAChF,oBAAoB;AACpB,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA6B;IAC7D,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAEjE,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,IAAI,YAAY,EAAE,SAAS,IAAI,YAAY,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjE,OAAO,YAAY,CAAC,SAAS,CAAC;IAChC,CAAC;IACD,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,WAAW,CAAC,CAAC;AACvB,CAAC;AAED,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAuB;IAC5D,MAAM,EACJ,SAAS,EACT,OAAO,EACP,gBAAgB,GAAG,wBAAoC,EACvD,sBAAsB,EACtB,MAAM,GACP,GAAG,IAAI,CAAC;IAET,MAAM,QAAQ,GAAmB,EAAE,CAAC;IAEpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,aAAa,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,CAAC,KAAK,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3C,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEtB,IAAI,QAAqB,CAAC;QAE1B,IAAI,CAAC;YACH,IAAI,sBAAsB,EAAE,CAAC;gBAC3B,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;oBAC5B,OAAO,CAAC,QAAQ,CAAC;oBACjB,oBAAoB,CAAC,sBAAsB,EAAE,aAAa,CAAC;iBAC5D,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,QAAQ,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wDAAwD;YACxD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;YACnC,MAAM,UAAU,GAAG,GAAG,YAAY,YAAY;gBAC5C,CAAC,CAAC,eAAe,CAAC,OAAO;gBACzB,CAAC,CAAC,eAAe,CAAC,aAAa,CAAC;YAClC,MAAM,SAAS,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAEnE,MAAM,OAAO,GAAiB,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;YAElG,IAAI,CAAC,OAAO,IAAK,gBAA6B,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBACpE,MAAM,CAAC,IAAI,CAAC,aAAa,aAAa,UAAU,UAAU,gBAAgB,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;gBACjI,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACvB,SAAS;YACX,CAAC;YAED,OAAO;gBACL,QAAQ,EAAE;oBACR,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,SAAS;oBAChB,UAAU,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE;iBACtE;gBACD,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC;aACjC,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;QAEnC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACrB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;QAChC,CAAC;QAED,kBAAkB;QAClB,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,IAAI,IAAI,eAAe,CAAC,OAAO,CAAC;QACxE,MAAM,aAAa,GAAI,gBAA6B,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAE1E,IAAI,CAAC,OAAO,IAAI,aAAa,EAAE,CAAC;YAC9B,MAAM,CAAC,IAAI,CAAC,aAAa,aAAa,aAAa,UAAU,gBAAgB,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;YACpI,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;YACnF,SAAS;QACX,CAAC;QAED,4DAA4D;QAC5D,MAAM,cAAc,GAAG,OAAO,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YACnD,CAAC,CAAC,CAAC,GAAG,QAAQ,EAAE,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;YACpF,CAAC,CAAC,QAAQ,CAAC;QAEb,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAChD,CAAC;IAED,oCAAoC;IACpC,OAAO,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,EAAE,EAAE,QAAQ,EAAE,CAAC;AACpF,CAAC;AAED,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF,MAAM,YAAa,SAAQ,KAAK;IAC9B,YAAY,QAAgB,EAAE,EAAU;QACtC,KAAK,CAAC,uBAAuB,QAAQ,qBAAqB,EAAE,IAAI,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,SAAS,oBAAoB,CAAC,EAAU,EAAE,QAAgB;IACxD,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAC7D,CAAC;AACJ,CAAC"}

package/dist/lib/cascade/index.d.ts

@@ -0,0 +1,5 @@
+export type { CascadeConfig } from './types.js';
+export { DEFAULT_CASCADE_ON_CODES } from './types.js';
+export { run_with_cascade, resolve_providers } from './cascade_runner.js';
+export type { CascadeRunOptions, CascadeRunResult, ResolveProvidersOptions } from './cascade_runner.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/cascade/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/cascade/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/lib/cascade/index.js

@@ -0,0 +1,4 @@
+// file_description: Cascade module exports
+export { DEFAULT_CASCADE_ON_CODES } from './types.js';
+export { run_with_cascade, resolve_providers } from './cascade_runner.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/cascade/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/cascade/index.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAG3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,35 @@
+import type { LLMErrorCode } from '../llm_api/types.js';
+/**
+ * Cascade configuration — controls provider failover behavior.
+ *
+ * Precedence (highest to lowest):
+ *   1. per-call `params.providers`
+ *   2. `initialize_llm_api({ cascade })` config
+ *   3. `[llm_cascade]` ini section
+ *   4. no cascade (single primary provider)
+ */
+export interface CascadeConfig {
+    /**
+     * Ordered list of provider names to try. First is attempted first.
+     * If empty or unset, no cascade — uses primary provider.
+     */
+    providers?: string[];
+    /**
+     * Timeout per individual provider attempt in milliseconds.
+     * No timeout if not set.
+     */
+    timeout_ms_per_attempt?: number;
+    /**
+     * Error codes that permit cascade to the next provider.
+     * Defaults to: RATE_LIMITED, NETWORK_ERROR, TIMEOUT, API_ERROR.
+     */
+    cascade_on_codes?: LLMErrorCode[];
+}
+/**
+ * Default error codes that trigger cascade to the next provider.
+ * Only transient / server-side errors are included.
+ * Configuration errors (PROVIDER_NOT_FOUND, CAPABILITY_NOT_SUPPORTED, API_KEY_MISSING)
+ * are intentionally excluded — they won't succeed on retry.
+ */
+export declare const DEFAULT_CASCADE_ON_CODES: LLMErrorCode[];
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/cascade/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/cascade/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,YAAY,EAAE,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,YAAY,EAKlD,CAAC"}

package/dist/lib/cascade/types.js

@@ -0,0 +1,14 @@
+// file_description: Cascade configuration and runner types for hazo_llm_api
+/**
+ * Default error codes that trigger cascade to the next provider.
+ * Only transient / server-side errors are included.
+ * Configuration errors (PROVIDER_NOT_FOUND, CAPABILITY_NOT_SUPPORTED, API_KEY_MISSING)
+ * are intentionally excluded — they won't succeed on retry.
+ */
+export const DEFAULT_CASCADE_ON_CODES = [
+    'RATE_LIMITED',
+    'NETWORK_ERROR',
+    'TIMEOUT',
+    'API_ERROR',
+];
+//# sourceMappingURL=types.js.map

package/dist/lib/cascade/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/cascade/types.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAiC5E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAmB;IACtD,cAAc;IACd,eAAe;IACf,SAAS;IACT,WAAW;CACZ,CAAC"}

package/dist/lib/cost_cap/cost_cap.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cost Cap Gate
+ *
+ * Pre-call gate that checks the accumulated cost for the current session
+ * against a configured cap. Returns a COST_LIMIT_EXCEEDED error response
+ * when the cap is reached (block mode) or fires a warn hook and proceeds
+ * (warn mode).
+ *
+ * Requires:
+ * - hazo_llm_api_log table to exist (ensure_api_log_table must be called first)
+ * - A session_id available via hazo_logs ALS (safe_get_log_context)
+ * - cost_cap.enabled = true in LLMApiConfig
+ */
+import type { Logger, LLMResponse, CostCapConfig } from '../llm_api/types.js';
+import type { HazoConnect } from '../hazo_connect/types.js';
+/**
+ * Ensure the session_id + created_at composite index exists on hazo_llm_api_log.
+ * Idempotent — safe to call on every initialization.
+ * Errors are swallowed to avoid crashing initialization.
+ */
+export declare function ensure_cost_cap_index(connect: HazoConnect, logger: Logger): Promise<void>;
+/**
+ * Query the total cost_usd accumulated for a session within the given window.
+ *
+ * Returns 0 if connect has no raw_sql, if there are no matching rows, or if
+ * any DB error occurs (errors are swallowed).
+ */
+export declare function query_session_cost(connect: HazoConnect, session_id: string, window_start: string, logger: Logger): Promise<number>;
+/**
+ * Pre-call cost cap gate.
+ *
+ * Returns:
+ * - `null`         if the gate should not block (cap disabled, no session, current < cap, or warn mode)
+ * - `LLMResponse`  if the call should be blocked (block mode, cap exceeded)
+ *
+ * In warn mode the `cost_cap_exceeded` hook is called (errors swallowed) and null is returned
+ * so the call proceeds.
+ */
+export declare function check_cost_cap_gate(connect: HazoConnect | null, cap_config: CostCapConfig | undefined, logger: Logger): Promise<LLMResponse | null>;
+//# sourceMappingURL=cost_cap.d.ts.map

package/dist/lib/cost_cap/cost_cap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost_cap.d.ts","sourceRoot":"","sources":["../../../src/lib/cost_cap/cost_cap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AA+B5D;;;;GAIG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,WAAW,EACpB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,UAAU,EAAE,aAAa,GAAG,SAAS,EACrC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAoE7B"}