hazo_llm_api 1.2.13 → 1.3.0

package/README.md

@@ -19,13 +19,18 @@ A wrapper package for calling different LLMs with built-in prompt management and
 | `hazo_llm_dynamic_data_extract` | Initial Prompt | Merged Results | Dynamic chain where next prompt is determined by JSON output |
 
 **Features:**
-- **Multi-Provider Support**: Use Gemini, Qwen, or add your own LLM providers
+- **Multi-Provider Support**: Use Gemini, Qwen, Anthropic, OpenAI, DeepSeek, or add your own LLM providers
+- **Cascade Fallback**: Automatically retry across providers on failure with configurable cascade
+- **Observability**: Per-call usage metrics (tokens, cost, latency) with automatic log table and query API
+- **Cost Cap**: Opt-in per-session spend limit with block or warn modes
+- **Embeddings**: Single and batch text embeddings via OpenAI with LRU/persistent cache
+- **Admin UI**: `LLMCostDashboard` and `LLMCallInspector` React components for spend monitoring
 - **Prompt Management**: Store and retrieve prompts from a SQLite database with LRU caching
 - **Variable Substitution**: Replace `$variables` in prompts with dynamic values
-- **Multi-modal Support**: Handle text and images seamlessly
+- **Multi-modal Support**: Handle text, images, and documents (PDFs) seamlessly
 - **Extensible Architecture**: Provider-based design with simple registration system
 - **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- **Auto-Initialization**: Database initializes automatically on import
+- **Auto-Initialization**: Database and log table initialize automatically on first call
 - **Flexible Logging**: Pass any compatible logger (e.g., `hazo_logs`, Winston, or custom)
 - **Lifecycle Hooks**: Monitor, log, and analyze LLM calls with beforeRequest, afterResponse, and onError hooks
 - **Streaming Support**: Real-time streaming responses for text generation
@@ -643,7 +648,24 @@ interface LLMResponse {
   image_b64?: string;         // Generated image (base64)
   image_mime_type?: string;   // MIME type of generated image
   error?: string;             // Error message if failed
+  error_info?: LLMError;      // Structured error (code, message, retryable)
+  error_code?: LLMErrorCode;  // Shorthand alias for error_info.code
   raw_response?: unknown;     // Raw API response
+  usage?: UsageInfo;          // Tokens, cost, latency, model, finish_reason, attempts
+}
+```
+
+`UsageInfo` includes:
+```typescript
+interface UsageInfo {
+  input_tokens?: number;
+  output_tokens?: number;
+  cost_usd?: number;
+  latency_ms?: number;
+  finish_reason?: FinishReason;
+  model?: string;
+  provider?: string;
+  attempts?: UsageAttempt[];  // Failed cascade attempts before success
 }
 ```
 
@@ -692,11 +714,43 @@ text_temperature=0.8
 
 ### Supported Providers
 
-| Provider | Capabilities | Configuration Required |
-|----------|-------------|------------------------|
-| Gemini | text_text, image_text, text_image, image_image | GEMINI_API_KEY in .env.local |
-| Qwen | text_text, image_text, text_image, image_image | QWEN_API_KEY in .env.local |
-| Custom | Define your own | Implement LLMProvider interface |
+| Provider | Capabilities | Config Section | Env Var |
+|----------|-------------|----------------|---------|
+| Gemini | text_text, image_text, text_image, image_image, document_text | `[llm_gemini]` | `GEMINI_API_KEY` |
+| Qwen | text_text, image_text, text_image, image_image | `[llm_qwen]` | `QWEN_API_KEY` |
+| Anthropic | text_text, image_text, document_text, text_text_stream | `[llm_anthropic]` | `ANTHROPIC_API_KEY` |
+| OpenAI | text_text, image_text, text_image, text_text_stream, embed | `[llm_openai]` | `OPENAI_API_KEY` |
+| DeepSeek | text_text, text_text_stream | `[llm_deepseek]` | `DEEPSEEK_API_KEY` |
+| Custom | Define your own | — | Implement LLMProvider interface |
+
+**Provider config example** — add each enabled provider to your `config/hazo_llm_api_config.ini`:
+
+```ini
+[llm]
+enabled_llms=["gemini", "anthropic", "openai", "deepseek"]
+primary_llm=anthropic
+
+[llm_anthropic]
+api_url=https://api.anthropic.com/v1/messages
+api_version=2023-06-01
+model_text_text=claude-sonnet-4-6
+model_image_text=claude-sonnet-4-6
+model_document_text=claude-sonnet-4-6
+text_max_tokens=8192
+
+[llm_openai]
+api_url=https://api.openai.com/v1/chat/completions
+api_url_image=https://api.openai.com/v1/images/generations
+api_url_embed=https://api.openai.com/v1/embeddings
+model_text_text=gpt-4o
+model_image_text=gpt-4o
+model_text_image=gpt-image-1
+model_embed=text-embedding-3-small
+
+[llm_deepseek]
+api_url=https://api.deepseek.com/v1/chat/completions
+model_text_text=deepseek-chat
+```
 
 See `TECHDOC.md` for instructions on adding custom providers.
 
@@ -1438,6 +1492,265 @@ The PromptEditor component now displays:
 
 No code changes are required if you're using the `PromptEditor` component - it automatically supports the new structure.
 
+## Observability
+
+Every LLM call automatically writes one row to `hazo_llm_api_log` (SQLite or PostgreSQL — created on first call, no manual migration needed). The row contains provider, model, service_type, token counts, `cost_usd`, `latency_ms`, `session_id`, `reference`, `error_code`, and a `context_json` blob.
+
+### Response Usage
+
+```typescript
+const response = await hazo_llm_text_text({ prompt: 'Hello' });
+
+if (response.usage) {
+  console.log(`Cost: $${response.usage.cost_usd?.toFixed(6)}`);
+  console.log(`Tokens: ${response.usage.input_tokens}in / ${response.usage.output_tokens}out`);
+  console.log(`Latency: ${response.usage.latency_ms}ms`);
+}
+```
+
+### Querying the Log
+
+```typescript
+import { get_llm_usage_summary, get_llm_call_detail } from 'hazo_llm_api/server';
+
+// Aggregate stats — group by provider over the last 7 days
+const summary = await get_llm_usage_summary({
+  from: '2026-05-18',
+  to: '2026-05-25',
+  group_by: 'provider',
+  limit: 100,
+});
+
+// Single call drill-down
+const detail = await get_llm_call_detail('some-uuid-here');
+```
+
+### Pricing Overrides and Retroactive Recalculation
+
+```typescript
+import { update_pricing, recompute_costs } from 'hazo_llm_api/server';
+
+// Override pricing at runtime
+update_pricing('anthropic/claude-sonnet-4-6', {
+  kind: 'text',
+  input_per_1m: 3.0,
+  output_per_1m: 15.0,
+});
+
+// Retroactively recalculate costs after a pricing correction
+const result = await recompute_costs({
+  from: '2026-05-01',
+  to: '2026-05-25',
+  models: ['claude-sonnet-4-6'],
+  dry_run: false,  // Set true to preview without writing
+});
+console.log(`Updated ${result.updated_count} rows`);
+```
+
+### Disabling the Log Writer
+
+```typescript
+await initialize_llm_api({
+  logger,
+  api_log: { enabled: false },  // No rows written to hazo_llm_api_log
+});
+```
+
+### hazo_logs Integration
+
+If `hazo_logs ^1.1.0` is installed, `session_id` and `reference` are read automatically from the async local storage context — no extra configuration required.
+
+---
+
+## Cascade Fallback
+
+Pass `providers` on any call to define an ordered fallback list. The call tries each provider in sequence, stopping on the first success. Failed attempts are recorded in `response.usage.attempts`.
+
+```typescript
+// Try Anthropic first, fall back to OpenAI, then Gemini
+const response = await hazo_llm_text_text(
+  { prompt: 'Hello', providers: ['anthropic', 'openai', 'gemini'] },
+);
+```
+
+### Default Cascade Config
+
+Set a default cascade for all calls at init time:
+
+```typescript
+import { DEFAULT_CASCADE_ON_CODES } from 'hazo_llm_api/server';
+
+await initialize_llm_api({
+  logger,
+  cascade: {
+    providers: ['anthropic', 'openai'],
+    on_codes: DEFAULT_CASCADE_ON_CODES, // RATE_LIMITED, NETWORK_ERROR, TIMEOUT
+    timeout_ms_per_attempt: 30000,
+  },
+});
+```
+
+Per-call `providers` always overrides the init-time cascade config.
+
+---
+
+## Embeddings
+
+Generate single or batch text embeddings (requires OpenAI provider):
+
+```typescript
+import { hazo_llm_embed } from 'hazo_llm_api/server';
+
+// Single text
+const result = await hazo_llm_embed({ text: 'Hello world' });
+if (result.success) {
+  console.log(result.vectors![0]);  // number[]
+  console.log(`Dimensions: ${result.dimensions}`);
+}
+
+// Batch
+const batch = await hazo_llm_embed({
+  text: ['First sentence', 'Second sentence', 'Third sentence'],
+  model: 'text-embedding-3-large',  // optional override
+});
+```
+
+Repeated calls with the same text are served from an in-memory LRU cache. For persistent caching, provide a `Keyv` instance at init time:
+
+```typescript
+import Keyv from 'keyv';
+import KeyvSqlite from '@keyv/sqlite';
+
+await initialize_llm_api({
+  logger,
+  embed_cache: {
+    max_size: 5000,
+    keyv: new Keyv({ store: new KeyvSqlite('sqlite://embed_cache.sqlite') }),
+  },
+});
+```
+
+---
+
+## Prompt Caching (Anthropic)
+
+Pass `prompt_parts` instead of `prompt` to hint which parts should be cached at the provider level. Anthropic supports prompt caching via `cache_control`. Other providers concatenate parts as plain text.
+
+```typescript
+const response = await hazo_llm_text_text({
+  prompt_parts: [
+    { text: long_system_context, cache: true },   // Cached by Anthropic
+    { text: user_message },                        // Not cached
+  ],
+});
+```
+
+---
+
+## Cost Cap
+
+Prevent runaway spend by configuring a per-session cost cap. The gate reads `SUM(cost_usd)` from `hazo_llm_api_log` before each call.
+
+```typescript
+await initialize_llm_api({
+  logger,
+  cost_cap: {
+    enabled: true,
+    window: 'session',          // 'session' | 'day' | 'hour'
+    on_exceeded: 'block',       // 'block' | 'warn'
+    get_user_cap: async ({ session_id }) => {
+      // Return the USD cap for this session
+      return await db.getUserSpendLimit(session_id);
+    },
+    cost_cap_exceeded: async ({ session_id, current_usd, cap_usd }) => {
+      // Called only in 'warn' mode
+      console.warn(`Session ${session_id} exceeded cap: $${current_usd} of $${cap_usd}`);
+    },
+  },
+});
+```
+
+In `block` mode, calls that would exceed the cap return immediately with `error_code: 'COST_LIMIT_EXCEEDED'`. In `warn` mode, the `cost_cap_exceeded` hook fires and the call proceeds.
+
+Requires `hazo_logs ^1.1.0` for `session_id` ALS propagation.
+
+---
+
+## Admin UI Components
+
+Import dashboard components for monitoring spend and inspecting individual calls. Requires `hazo_ui ^2.17.0`.
+
+### LLMCostDashboard
+
+```typescript
+import { LLMCostDashboard } from 'hazo_llm_api';
+import type { FetchSummaryFn } from 'hazo_llm_api';
+
+// Build the fetch function using your framework's API routes
+const fetch_summary: FetchSummaryFn = async (opts) => {
+  const params = new URLSearchParams({ ...opts });
+  const res = await fetch(`/api/llm-summary?${params}`);
+  return res.json();
+};
+
+function MonitoringPage() {
+  return <LLMCostDashboard fetch_summary={fetch_summary} />;
+}
+```
+
+The component provides date-range filters, group-by selector (`date` / `provider` / `model` / `service_type`), an SVG time-series chart (when `group_by=date`), and a summary table with totals.
+
+### LLMCallInspector
+
+```typescript
+import { LLMCallInspector } from 'hazo_llm_api';
+import type { FetchDetailFn } from 'hazo_llm_api';
+
+const fetch_detail: FetchDetailFn = async (id) => {
+  const res = await fetch(`/api/llm-call-detail?id=${id}`);
+  return res.json();
+};
+
+function CallDetailPage({ call_id }: { call_id: string }) {
+  return <LLMCallInspector callId={call_id} fetch_detail={fetch_detail} />;
+}
+```
+
+---
+
+## Maintenance
+
+Register the log purge job with `hazo_jobs` to automatically delete old log rows:
+
+```typescript
+import { llm_api_purge_log_job } from 'hazo_llm_api/server';
+import { register_job } from 'hazo_jobs/server';
+
+// Register the job — hazo_jobs scheduler calls it on your configured schedule
+register_job(llm_api_purge_log_job);
+
+// Payload when triggering the job
+// { retention_days: 90 }  — rows older than 90 days are deleted
+```
+
+The job requires `hazo_jobs ^0.10.0` as a peer dependency.
+
+---
+
+## Environment Variables
+
+| Variable | Provider | Required |
+|----------|----------|----------|
+| `GEMINI_API_KEY` | Gemini | When `gemini` is in `enabled_llms` |
+| `QWEN_API_KEY` | Qwen | When `qwen` is in `enabled_llms` |
+| `ANTHROPIC_API_KEY` | Anthropic | When `anthropic` is in `enabled_llms` |
+| `OPENAI_API_KEY` | OpenAI | When `openai` is in `enabled_llms` |
+| `DEEPSEEK_API_KEY` | DeepSeek | When `deepseek` is in `enabled_llms` |
+
+All keys go in `.env.local` (never committed to git).
+
+---
+
 ## Support
 
 For issues and questions, please visit the [GitHub Issues](https://github.com/pub12/hazo_llm_api/issues) page.

package/config/hazo_llm_api_config.ini

@@ -215,6 +215,39 @@ capabilities=["text_text", "image_text", "text_image", "image_image"]
 # Generation stops when any of these sequences is encountered
 ; image_stop=["###END"]
 
+[llm_anthropic]
+; Anthropic API configuration
+; Set ANTHROPIC_API_KEY in .env.local
+; api_key_env = ANTHROPIC_API_KEY
+api_url = https://api.anthropic.com/v1/messages
+api_version = 2023-06-01
+model_text_text = claude-sonnet-4-6
+model_image_text = claude-sonnet-4-6
+model_document_text = claude-sonnet-4-6
+text_max_tokens = 8192
+; capabilities = text_text, image_text, document_text, text_text_stream
+
+[llm_openai]
+; OpenAI API configuration
+; Set OPENAI_API_KEY in .env.local
+; api_key_env = OPENAI_API_KEY
+api_url = https://api.openai.com/v1/chat/completions
+api_url_image = https://api.openai.com/v1/images/generations
+api_url_embed = https://api.openai.com/v1/embeddings
+model_text_text = gpt-4o
+model_image_text = gpt-4o
+model_text_image = gpt-image-1
+model_embed = text-embedding-3-small
+; capabilities = text_text, image_text, text_image, text_text_stream, embed
+
+[llm_deepseek]
+; DeepSeek API configuration
+; Set DEEPSEEK_API_KEY in .env.local
+; api_key_env = DEEPSEEK_API_KEY
+api_url = https://api.deepseek.com/v1/chat/completions
+model_text_text = deepseek-chat
+; capabilities = text_text, text_text_stream
+
 [database]
 # Database configuration
 # Enable WAL mode for better SQLite performance

package/dist/components/index.d.ts

@@ -5,4 +5,6 @@
  */
 export * from './layout/index.js';
 export * from './prompt_editor/index.js';
+export * from './llm_cost_dashboard/index.js';
+export * from './llm_call_inspector/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC"}

package/dist/components/index.js

@@ -5,4 +5,6 @@
  */
 export * from './layout/index.js';
 export * from './prompt_editor/index.js';
+export * from './llm_cost_dashboard/index.js';
+export * from './llm_call_inspector/index.js';
 //# sourceMappingURL=index.js.map

package/dist/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC"}

package/dist/components/llm_call_inspector/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LLMCallInspector — re-export
+ */
+export { LLMCallInspector } from './llm_call_inspector.js';
+export type { LLMCallInspectorProps } from './llm_call_inspector.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/llm_call_inspector/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/llm_call_inspector/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/components/llm_call_inspector/index.js

@@ -0,0 +1,5 @@
+/**
+ * LLMCallInspector — re-export
+ */
+export { LLMCallInspector } from './llm_call_inspector.js';
+//# sourceMappingURL=index.js.map

package/dist/components/llm_call_inspector/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/llm_call_inspector/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/components/llm_call_inspector/llm_call_inspector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * LLMCallInspector Component
+ *
+ * Displays detailed information about a single LLM API call log row.
+ * Framework-agnostic: accepts a fetch_detail prop instead of accessing
+ * the database directly.
+ */
+import type { FetchDetailFn } from '../../lib/observability/types.js';
+export interface LLMCallInspectorProps {
+    /** ID of the call to inspect. null = show placeholder. */
+    call_id: string | null;
+    /** Async function to fetch call detail */
+    fetch_detail: FetchDetailFn;
+    /** Optional CSS class */
+    className?: string;
+}
+export declare function LLMCallInspector({ call_id, fetch_detail, className }: LLMCallInspectorProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=llm_call_inspector.d.ts.map

package/dist/components/llm_call_inspector/llm_call_inspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_call_inspector.d.ts","sourceRoot":"","sources":["../../../src/components/llm_call_inspector/llm_call_inspector.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,kCAAkC,CAAC;AAMjF,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,0CAA0C;IAC1C,YAAY,EAAE,aAAa,CAAC;IAC5B,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4CD,wBAAgB,gBAAgB,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,EAAE,qBAAqB,2CAsN3F"}

package/dist/components/llm_call_inspector/llm_call_inspector.js

@@ -0,0 +1,103 @@
+/**
+ * LLMCallInspector Component
+ *
+ * Displays detailed information about a single LLM API call log row.
+ * Framework-agnostic: accepts a fetch_detail prop instead of accessing
+ * the database directly.
+ */
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState, useEffect } 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_id_short(id) {
+    if (id.length <= 15)
+        return id;
+    return `${id.slice(0, 12)}...`;
+}
+function is_success(row) {
+    return row.success === 1 || row.success === true;
+}
+function DlRow({ label, value }) {
+    return (_jsxs(_Fragment, { children: [_jsx("dt", { className: "cls_dt text-xs font-medium uppercase tracking-wide text-gray-500", children: label }), _jsx("dd", { className: "cls_dd text-sm text-gray-900", children: value })] }));
+}
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+export function LLMCallInspector({ call_id, fetch_detail, className }) {
+    const [loading, set_loading] = useState(false);
+    const [error, set_error] = useState(null);
+    const [row, set_row] = useState(null);
+    useEffect(() => {
+        if (!call_id) {
+            set_row(null);
+            set_error(null);
+            return;
+        }
+        let cancelled = false;
+        async function load() {
+            set_loading(true);
+            set_error(null);
+            try {
+                const result = await fetch_detail(call_id);
+                if (!cancelled) {
+                    set_row(result);
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    set_error(err instanceof Error ? err.message : 'Failed to load call details');
+                }
+            }
+            finally {
+                if (!cancelled) {
+                    set_loading(false);
+                }
+            }
+        }
+        load();
+        return () => {
+            cancelled = true;
+        };
+        // fetch_detail intentionally omitted — callers should pass a stable reference (useCallback)
+    }, [call_id]);
+    // ---------------------------------------------------------------------------
+    // Placeholder
+    // ---------------------------------------------------------------------------
+    if (!call_id) {
+        return (_jsx("div", { className: cn('cls_llm_call_inspector flex items-center justify-center rounded-lg border border-dashed border-gray-300 bg-gray-50 px-8 py-16', className), children: _jsx("p", { className: "text-sm text-gray-400", children: "Select a call to inspect" }) }));
+    }
+    // ---------------------------------------------------------------------------
+    // Loading state
+    // ---------------------------------------------------------------------------
+    if (loading) {
+        return (_jsx("div", { className: cn('cls_llm_call_inspector flex items-center justify-center rounded-lg border border-gray-200 bg-white px-8 py-16', className), children: _jsx("p", { className: "text-sm text-gray-500", children: "Loading call details..." }) }));
+    }
+    // ---------------------------------------------------------------------------
+    // Error state
+    // ---------------------------------------------------------------------------
+    if (error) {
+        return (_jsxs("div", { className: cn('cls_llm_call_inspector rounded-lg border border-red-200 bg-red-50 px-4 py-6', className), children: [_jsx("p", { className: "text-sm text-red-700", children: "Failed to load call details" }), _jsx("p", { className: "mt-1 text-xs text-red-500", children: error })] }));
+    }
+    // ---------------------------------------------------------------------------
+    // Not found state (fetch returned null)
+    // ---------------------------------------------------------------------------
+    if (!row) {
+        return (_jsx("div", { className: cn('cls_llm_call_inspector flex items-center justify-center rounded-lg border border-gray-200 bg-white px-8 py-16', className), children: _jsx("p", { className: "text-sm text-gray-400", children: "Call not found" }) }));
+    }
+    const success = is_success(row);
+    // ---------------------------------------------------------------------------
+    // Full detail view
+    // ---------------------------------------------------------------------------
+    return (_jsxs("div", { className: cn('cls_llm_call_inspector space-y-4 rounded-lg border border-gray-200 bg-white p-5', className), children: [_jsxs("div", { className: "cls_inspector_header flex items-center gap-3", children: [_jsx("code", { className: "cls_call_id rounded bg-gray-100 px-2 py-1 font-mono text-sm text-gray-800", children: fmt_id_short(row.id) }), _jsx("span", { className: cn('cls_status_badge inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium', success
+                            ? 'bg-green-100 text-green-800'
+                            : 'bg-red-100 text-red-800'), children: success ? 'Success' : 'Failed' }), row.created_at && (_jsx("span", { className: "ml-auto text-xs text-gray-400", children: row.created_at }))] }), _jsx("div", { className: "cls_metrics_grid", children: _jsxs("dl", { className: "grid grid-cols-2 gap-x-4 gap-y-2", children: [_jsx(DlRow, { label: "Provider", value: row.provider || '—' }), _jsx(DlRow, { label: "Model", value: row.model || '—' }), _jsx(DlRow, { label: "Service Type", value: row.service_type || '—' }), _jsx(DlRow, { label: "Cost", value: fmt_cost(row.cost_usd) }), _jsx(DlRow, { label: "Latency", value: row.latency_ms != null ? `${row.latency_ms} ms` : '—' })] }) }), _jsxs("div", { className: "cls_tokens_section", children: [_jsx("h3", { className: "mb-2 text-xs font-semibold uppercase tracking-wide text-gray-500", children: "Tokens" }), _jsxs("dl", { className: "grid grid-cols-2 gap-x-4 gap-y-1.5 sm:grid-cols-4", children: [row.tokens_input != null && (_jsx(DlRow, { label: "Input", value: row.tokens_input.toLocaleString() })), row.tokens_output != null && (_jsx(DlRow, { label: "Output", value: row.tokens_output.toLocaleString() })), row.tokens_cached_input != null && (_jsx(DlRow, { label: "Cached Input", value: row.tokens_cached_input.toLocaleString() })), row.tokens_total != null && (_jsx(DlRow, { label: "Total", value: row.tokens_total.toLocaleString() }))] })] }), row.error_code && (_jsxs("div", { className: "cls_error_section rounded-md border border-red-200 bg-red-50 px-4 py-3", children: [_jsx("p", { className: "text-sm font-medium text-red-800", children: row.error_code }), row.error_message && (_jsx("p", { className: "mt-0.5 text-sm text-red-700", children: row.error_message }))] })), (row.session_id || row.reference || row.prompt_area || row.prompt_key) && (_jsxs("div", { className: "cls_context_section", children: [_jsx("h3", { className: "mb-2 text-xs font-semibold uppercase tracking-wide text-gray-500", children: "Context" }), _jsxs("dl", { className: "grid grid-cols-2 gap-x-4 gap-y-1.5", children: [row.session_id && _jsx(DlRow, { label: "Session ID", value: row.session_id }), row.reference && _jsx(DlRow, { label: "Reference", value: row.reference }), row.prompt_area && _jsx(DlRow, { label: "Prompt Area", value: row.prompt_area }), row.prompt_key && _jsx(DlRow, { label: "Prompt Key", value: row.prompt_key })] })] })), _jsxs("p", { className: "cls_attempts text-xs text-gray-500", children: [row.attempts_count ?? 0, " attempt", (row.attempts_count ?? 0) === 1 ? '' : 's'] }), _jsxs("details", { className: "cls_raw_json_details rounded border border-gray-200", children: [_jsx("summary", { className: "cursor-pointer px-3 py-2 text-xs font-medium text-gray-600 hover:bg-gray-50", children: "Raw JSON" }), _jsx("pre", { className: "cls_raw_json_pre overflow-x-auto px-3 py-2 text-xs text-gray-700", children: JSON.stringify(row, null, 2) })] })] }));
+}
+//# sourceMappingURL=llm_call_inspector.js.map

package/dist/components/llm_call_inspector/llm_call_inspector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_call_inspector.js","sourceRoot":"","sources":["../../../src/components/llm_call_inspector/llm_call_inspector.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,CAAC;;AAEb,OAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,MAAM,oBAAoB,CAAC;AAgBxC,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,SAAS,QAAQ,CAAC,KAAgC;IAChD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACpC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,YAAY,CAAC,EAAU;IAC9B,IAAI,EAAE,CAAC,MAAM,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC;IAC/B,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC;AACjC,CAAC;AAED,SAAS,UAAU,CAAC,GAAc;IAChC,OAAO,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC;AACnD,CAAC;AAWD,SAAS,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAc;IACzC,OAAO,CACL,8BACE,aAAI,SAAS,EAAC,kEAAkE,YAC7E,KAAK,GACH,EACL,aAAI,SAAS,EAAC,8BAA8B,YAAE,KAAK,GAAM,IACxD,CACJ,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,UAAU,gBAAgB,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAyB;IAC1F,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/C,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAgB,IAAI,CAAC,CAAC;IACzD,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAmB,IAAI,CAAC,CAAC;IAExD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,CAAC;YACd,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QAED,IAAI,SAAS,GAAG,KAAK,CAAC;QAEtB,KAAK,UAAU,IAAI;YACjB,WAAW,CAAC,IAAI,CAAC,CAAC;YAClB,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,OAAiB,CAAC,CAAC;gBACrD,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,OAAO,CAAC,MAAM,CAAC,CAAC;gBAClB,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,SAAS,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC;gBAChF,CAAC;YACH,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,WAAW,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,EAAE,CAAC;QAEP,OAAO,GAAG,EAAE;YACV,SAAS,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC;QACJ,4FAA4F;IAC5F,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAEd,8EAA8E;IAC9E,cAAc;IACd,8EAA8E;IAC9E,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CACL,cACE,SAAS,EAAE,EAAE,CACX,+HAA+H,EAC/H,SAAS,CACV,YAED,YAAG,SAAS,EAAC,uBAAuB,yCAA6B,GAC7D,CACP,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,gBAAgB;IAChB,8EAA8E;IAC9E,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CACL,cACE,SAAS,EAAE,EAAE,CACX,+GAA+G,EAC/G,SAAS,CACV,YAED,YAAG,SAAS,EAAC,uBAAuB,wCAA4B,GAC5D,CACP,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,cAAc;IACd,8EAA8E;IAC9E,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CACL,eACE,SAAS,EAAE,EAAE,CACX,6EAA6E,EAC7E,SAAS,CACV,aAED,YAAG,SAAS,EAAC,sBAAsB,4CAAgC,EACnE,YAAG,SAAS,EAAC,2BAA2B,YAAE,KAAK,GAAK,IAChD,CACP,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,wCAAwC;IACxC,8EAA8E;IAC9E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,CACL,cACE,SAAS,EAAE,EAAE,CACX,+GAA+G,EAC/G,SAAS,CACV,YAED,YAAG,SAAS,EAAC,uBAAuB,+BAAmB,GACnD,CACP,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAEhC,8EAA8E;IAC9E,mBAAmB;IACnB,8EAA8E;IAC9E,OAAO,CACL,eACE,SAAS,EAAE,EAAE,CACX,iFAAiF,EACjF,SAAS,CACV,aAGD,eAAK,SAAS,EAAC,8CAA8C,aAC3D,eAAM,SAAS,EAAC,2EAA2E,YACxF,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,GAChB,EACP,eACE,SAAS,EAAE,EAAE,CACX,0FAA0F,EAC1F,OAAO;4BACL,CAAC,CAAC,6BAA6B;4BAC/B,CAAC,CAAC,yBAAyB,CAC9B,YAEA,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,GAC1B,EACN,GAAG,CAAC,UAAU,IAAI,CACjB,eAAM,SAAS,EAAC,+BAA+B,YAAE,GAAG,CAAC,UAAU,GAAQ,CACxE,IACG,EAGN,cAAK,SAAS,EAAC,kBAAkB,YAC/B,cAAI,SAAS,EAAC,kCAAkC,aAC9C,KAAC,KAAK,IAAC,KAAK,EAAC,UAAU,EAAC,KAAK,EAAE,GAAG,CAAC,QAAQ,IAAI,GAAG,GAAI,EACtD,KAAC,KAAK,IAAC,KAAK,EAAC,OAAO,EAAC,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,GAAI,EAChD,KAAC,KAAK,IAAC,KAAK,EAAC,cAAc,EAAC,KAAK,EAAE,GAAG,CAAC,YAAY,IAAI,GAAG,GAAI,EAC9D,KAAC,KAAK,IAAC,KAAK,EAAC,MAAM,EAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAI,EACrD,KAAC,KAAK,IACJ,KAAK,EAAC,SAAS,EACf,KAAK,EAAE,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,GAAG,GAC5D,IACC,GACD,EAGN,eAAK,SAAS,EAAC,oBAAoB,aACjC,aAAI,SAAS,EAAC,kEAAkE,uBAE3E,EACL,cAAI,SAAS,EAAC,mDAAmD,aAC9D,GAAG,CAAC,YAAY,IAAI,IAAI,IAAI,CAC3B,KAAC,KAAK,IAAC,KAAK,EAAC,OAAO,EAAC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,cAAc,EAAE,GAAI,CAClE,EACA,GAAG,CAAC,aAAa,IAAI,IAAI,IAAI,CAC5B,KAAC,KAAK,IAAC,KAAK,EAAC,QAAQ,EAAC,KAAK,EAAE,GAAG,CAAC,aAAa,CAAC,cAAc,EAAE,GAAI,CACpE,EACA,GAAG,CAAC,mBAAmB,IAAI,IAAI,IAAI,CAClC,KAAC,KAAK,IAAC,KAAK,EAAC,cAAc,EAAC,KAAK,EAAE,GAAG,CAAC,mBAAmB,CAAC,cAAc,EAAE,GAAI,CAChF,EACA,GAAG,CAAC,YAAY,IAAI,IAAI,IAAI,CAC3B,KAAC,KAAK,IAAC,KAAK,EAAC,OAAO,EAAC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,cAAc,EAAE,GAAI,CAClE,IACE,IACD,EAGL,GAAG,CAAC,UAAU,IAAI,CACjB,eAAK,SAAS,EAAC,wEAAwE,aACrF,YAAG,SAAS,EAAC,kCAAkC,YAAE,GAAG,CAAC,UAAU,GAAK,EACnE,GAAG,CAAC,aAAa,IAAI,CACpB,YAAG,SAAS,EAAC,6BAA6B,YAAE,GAAG,CAAC,aAAa,GAAK,CACnE,IACG,CACP,EAGA,CAAC,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,SAAS,IAAI,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CACzE,eAAK,SAAS,EAAC,qBAAqB,aAClC,aAAI,SAAS,EAAC,kEAAkE,wBAE3E,EACL,cAAI,SAAS,EAAC,oCAAoC,aAC/C,GAAG,CAAC,UAAU,IAAI,KAAC,KAAK,IAAC,KAAK,EAAC,YAAY,EAAC,KAAK,EAAE,GAAG,CAAC,UAAU,GAAI,EACrE,GAAG,CAAC,SAAS,IAAI,KAAC,KAAK,IAAC,KAAK,EAAC,WAAW,EAAC,KAAK,EAAE,GAAG,CAAC,SAAS,GAAI,EAClE,GAAG,CAAC,WAAW,IAAI,KAAC,KAAK,IAAC,KAAK,EAAC,aAAa,EAAC,KAAK,EAAE,GAAG,CAAC,WAAW,GAAI,EACxE,GAAG,CAAC,UAAU,IAAI,KAAC,KAAK,IAAC,KAAK,EAAC,YAAY,EAAC,KAAK,EAAE,GAAG,CAAC,UAAU,GAAI,IACnE,IACD,CACP,EAGD,aAAG,SAAS,EAAC,oCAAoC,aAC9C,GAAG,CAAC,cAAc,IAAI,CAAC,cAAU,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,IAC1E,EAGJ,mBAAS,SAAS,EAAC,qDAAqD,aACtE,kBAAS,SAAS,EAAC,6EAA6E,yBAEtF,EACV,cAAK,SAAS,EAAC,kEAAkE,YAC9E,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GACzB,IACE,IACN,CACP,CAAC;AACJ,CAAC"}

package/dist/components/llm_cost_dashboard/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LLMCostDashboard — re-export
+ */
+export { LLMCostDashboard } from './llm_cost_dashboard.js';
+export type { LLMCostDashboardProps } from './llm_cost_dashboard.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/llm_cost_dashboard/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/llm_cost_dashboard/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/components/llm_cost_dashboard/index.js

@@ -0,0 +1,5 @@
+/**
+ * LLMCostDashboard — re-export
+ */
+export { LLMCostDashboard } from './llm_cost_dashboard.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/llm_cost_dashboard/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/components/llm_cost_dashboard/llm_cost_dashboard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * LLMCostDashboard Component
+ *
+ * Displays aggregated LLM usage and cost data.
+ * Framework-agnostic: accepts a fetch_summary prop instead of accessing
+ * the database directly.
+ */
+import type { FetchSummaryFn } from '../../lib/observability/types.js';
+export interface LLMCostDashboardProps {
+    /** Async function to fetch usage summary data */
+    fetch_summary: FetchSummaryFn;
+    /** Optional CSS class */
+    className?: string;
+}
+export declare function LLMCostDashboard({ fetch_summary, className }: LLMCostDashboardProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=llm_cost_dashboard.d.ts.map

package/dist/components/llm_cost_dashboard/llm_cost_dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_cost_dashboard.d.ts","sourceRoot":"","sources":["../../../src/components/llm_cost_dashboard/llm_cost_dashboard.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,kCAAkC,CAAC;AAM1C,MAAM,WAAW,qBAAqB;IACpC,iDAAiD;IACjD,aAAa,EAAE,cAAc,CAAC;IAC9B,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAgDD,wBAAgB,gBAAgB,CAAC,EAAE,aAAa,EAAE,SAAS,EAAE,EAAE,qBAAqB,2CA0UnF"}