@revealui/ai 0.1.0

package/dist/ingestion/reranker.js

@@ -0,0 +1,41 @@
+/**
+ * LLM-based Re-ranker
+ *
+ * Scores chunks 0–10 for relevance to the query using the configured LLMClient.
+ * No cross-encoder model required — uses the existing LLM.
+ */
+const RERANK_SYSTEM_PROMPT = `You are a relevance judge. Given a query and a list of passages, score each passage for relevance to the query on a scale of 0 to 10 (0=not relevant, 10=perfectly relevant). Return ONLY a JSON array of numbers, one score per passage, in the same order as the input. Example: [8, 3, 10, 1]`;
+export async function rerankChunks(query, chunks, llmClient, topK) {
+    if (chunks.length === 0)
+        return [];
+    const passageList = chunks
+        .map((r, i) => `[${i + 1}] ${r.chunk.content.slice(0, 400)}`)
+        .join('\n\n');
+    const userMessage = `Query: ${query}\n\nPassages:\n${passageList}\n\nReturn a JSON array of ${chunks.length} relevance scores (0-10).`;
+    try {
+        const response = await llmClient.chat([
+            { role: 'system', content: RERANK_SYSTEM_PROMPT },
+            { role: 'user', content: userMessage },
+        ]);
+        // Extract JSON array from response
+        const match = response.content.match(/\[[\d\s,]+\]/);
+        if (!match)
+            return chunks.slice(0, topK);
+        const scores = JSON.parse(match[0]);
+        if (!Array.isArray(scores) || scores.length !== chunks.length) {
+            return chunks.slice(0, topK);
+        }
+        const scored = chunks.map((chunk, i) => ({
+            chunk,
+            score: typeof scores[i] === 'number' ? scores[i] : 0,
+        }));
+        return scored
+            .sort((a, b) => b.score - a.score)
+            .slice(0, topK ?? chunks.length)
+            .map((s) => s.chunk);
+    }
+    catch {
+        // On LLM failure, return original order
+        return chunks.slice(0, topK);
+    }
+}

package/dist/ingestion/text-splitter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Recursive Character Text Splitter
+ *
+ * Splits text into chunks using a hierarchy of separators:
+ *   double-newline → single-newline → period+space → space
+ * Token count is estimated as Math.ceil(length / 4) — sufficient for chunking.
+ */
+export interface Chunk {
+    content: string;
+    tokenCount: number;
+    index: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SplitOptions {
+    chunkSize?: number;
+    overlap?: number;
+    metadata?: Record<string, unknown>;
+}
+export declare class RecursiveCharacterSplitter {
+    private chunkSize;
+    private overlap;
+    constructor(options?: SplitOptions);
+    split(text: string, options?: SplitOptions): Chunk[];
+}
+//# sourceMappingURL=text-splitter.d.ts.map

package/dist/ingestion/text-splitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-splitter.d.ts","sourceRoot":"","sources":["../../src/ingestion/text-splitter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AA4ED,qBAAa,0BAA0B;IACrC,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAQ;gBAEX,OAAO,GAAE,YAAiB;IAKtC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,KAAK,EAAE;CAoCzD"}

package/dist/ingestion/text-splitter.js

@@ -0,0 +1,119 @@
+/**
+ * Recursive Character Text Splitter
+ *
+ * Splits text into chunks using a hierarchy of separators:
+ *   double-newline → single-newline → period+space → space
+ * Token count is estimated as Math.ceil(length / 4) — sufficient for chunking.
+ */
+const SEPARATORS = ['\n\n', '\n', '. ', ' '];
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+function splitOnSeparator(text, separator) {
+    if (!text.includes(separator))
+        return [text];
+    // Split and re-attach separator to previous segment (keep context)
+    const parts = text.split(separator);
+    const result = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === undefined)
+            continue;
+        if (i < parts.length - 1) {
+            result.push(part + separator);
+        }
+        else if (part.length > 0) {
+            result.push(part);
+        }
+    }
+    return result;
+}
+function mergeSegments(segments, chunkSize) {
+    const chunks = [];
+    let current = '';
+    for (const seg of segments) {
+        if (current.length + seg.length <= chunkSize) {
+            current += seg;
+        }
+        else {
+            if (current.length > 0)
+                chunks.push(current.trimEnd());
+            // If single segment is larger than chunkSize, keep it as-is (will be handled by recursion)
+            current = seg;
+        }
+    }
+    if (current.trim().length > 0)
+        chunks.push(current.trimEnd());
+    return chunks;
+}
+function recursiveSplit(text, chunkSize, sepIndex = 0) {
+    if (text.length <= chunkSize)
+        return [text];
+    const separator = SEPARATORS[sepIndex];
+    if (separator === undefined) {
+        // No separator left — hard-split at chunkSize
+        const chunks = [];
+        for (let i = 0; i < text.length; i += chunkSize) {
+            chunks.push(text.slice(i, i + chunkSize));
+        }
+        return chunks;
+    }
+    const segments = splitOnSeparator(text, separator);
+    if (segments.length <= 1) {
+        // Separator not found, try next
+        return recursiveSplit(text, chunkSize, sepIndex + 1);
+    }
+    // Merge small segments back together up to chunkSize
+    const merged = mergeSegments(segments, chunkSize);
+    // Recursively split any chunk that is still too large
+    const result = [];
+    for (const chunk of merged) {
+        if (chunk.length > chunkSize) {
+            result.push(...recursiveSplit(chunk, chunkSize, sepIndex + 1));
+        }
+        else {
+            result.push(chunk);
+        }
+    }
+    return result;
+}
+export class RecursiveCharacterSplitter {
+    chunkSize;
+    overlap;
+    constructor(options = {}) {
+        this.chunkSize = options.chunkSize ?? 512;
+        this.overlap = options.overlap ?? 64;
+    }
+    split(text, options = {}) {
+        const chunkSize = options.chunkSize ?? this.chunkSize;
+        const overlap = options.overlap ?? this.overlap;
+        const metadata = options.metadata ?? {};
+        if (!text || text.trim().length === 0)
+            return [];
+        const rawChunks = recursiveSplit(text.trim(), chunkSize * 4); // chars, not tokens
+        const chunks = [];
+        for (let i = 0; i < rawChunks.length; i++) {
+            const rawChunk = rawChunks[i];
+            if (!rawChunk)
+                continue;
+            let content = rawChunk.trim();
+            // Add overlap from previous chunk
+            if (i > 0 && overlap > 0) {
+                const prev = rawChunks[i - 1];
+                if (prev) {
+                    const overlapText = prev.slice(Math.max(0, prev.length - overlap * 4));
+                    content = `${overlapText.trim()} ${content}`;
+                }
+            }
+            if (content.length === 0)
+                continue;
+            chunks.push({
+                content,
+                tokenCount: estimateTokens(content),
+                index: i,
+                metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+            });
+        }
+        return chunks;
+    }
+}

package/dist/llm/cache-utils.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Prompt Caching Utilities
+ *
+ * Helper functions for optimizing Anthropic prompt caching usage.
+ * Cache hits provide up to 90% cost reduction on input tokens.
+ *
+ * Cache TTL: 5 minutes
+ * Minimum cacheable content: ~1024 tokens (~300 words)
+ *
+ * Best practices:
+ * - Cache stable content that repeats across requests
+ * - Place cached content at message boundaries
+ * - Cache system prompts, tools, and large context documents
+ * - Order matters: place most stable content first
+ *
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ */
+import type { Message } from './providers/base.js';
+/**
+ * Mark a message for caching
+ * Use this for system prompts, tool definitions, or large context that repeats
+ */
+export declare function withCache(message: Message): Message;
+/**
+ * Create a cacheable system prompt message
+ *
+ * @example
+ * ```ts
+ * const systemPrompt = cacheableSystemPrompt(
+ *   'You are a helpful AI assistant with expertise in TypeScript and React.'
+ * )
+ * ```
+ */
+export declare function cacheableSystemPrompt(content: string): Message;
+/**
+ * Calculate potential cost savings from caching
+ *
+ * @param inputTokens - Total input tokens
+ * @param cacheHitRate - Percentage of requests that hit cache (0-1)
+ * @param cachedTokenPercentage - Percentage of input that's cached (0-1)
+ * @returns Estimated cost reduction percentage
+ *
+ * @example
+ * ```ts
+ * // If 50% of requests hit cache and 70% of input is cached content
+ * const savings = estimateCacheSavings(10000, 0.5, 0.7)
+ * console.log(`${savings}% cost reduction`) // ~31.5%
+ * ```
+ */
+export declare function estimateCacheSavings(inputTokens: number, cacheHitRate: number, cachedTokenPercentage: number): number;
+/**
+ * Format cache statistics from response
+ *
+ * @example
+ * ```ts
+ * const response = await client.chat(messages, { enableCache: true })
+ * const stats = formatCacheStats(response.usage)
+ * console.log(stats)
+ * // "Cache: 45% read (2,500 tokens), 10% created (500 tokens)"
+ * ```
+ */
+export declare function formatCacheStats(usage: {
+    promptTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}): string | null;
+/**
+ * Check if caching is beneficial for the given content
+ * Anthropic recommends caching content >1024 tokens
+ */
+export declare function shouldCache(content: string, minTokens?: number): boolean;
+/**
+ * Create a conversation with optimal caching structure
+ *
+ * @example
+ * ```ts
+ * const conversation = createCachedConversation({
+ *   systemPrompt: 'You are a helpful assistant...',
+ *   tools: [...], // Large tool definitions
+ *   contextDocs: ['# Documentation\n...'], // Large context documents
+ *   messages: [
+ *     { role: 'user', content: 'What is TypeScript?' },
+ *   ],
+ * })
+ *
+ * const response = await client.chat(conversation, { enableCache: true })
+ * ```
+ */
+export declare function createCachedConversation(config: {
+    systemPrompt?: string;
+    contextDocs?: string[];
+    messages: Message[];
+}): Message[];
+/**
+ * Pricing information for Anthropic Claude models (as of 2024)
+ * Prices are per million tokens
+ */
+export declare const ANTHROPIC_PRICING: {
+    readonly 'claude-3-5-sonnet-20241022': {
+        readonly input: 3;
+        readonly output: 15;
+        readonly cacheWrite: 3.75;
+        readonly cacheRead: 0.3;
+    };
+    readonly 'claude-3-5-haiku-20241022': {
+        readonly input: 1;
+        readonly output: 5;
+        readonly cacheWrite: 1.25;
+        readonly cacheRead: 0.1;
+    };
+    readonly 'claude-3-opus-20240229': {
+        readonly input: 15;
+        readonly output: 75;
+        readonly cacheWrite: 18.75;
+        readonly cacheRead: 1.5;
+    };
+};
+/**
+ * Calculate actual cost of a request with caching
+ *
+ * @example
+ * ```ts
+ * const cost = calculateCacheCost({
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   promptTokens: 10000,
+ *   completionTokens: 500,
+ *   cacheCreationTokens: 3000,
+ *   cacheReadTokens: 5000,
+ * })
+ *
+ * console.log(`Request cost: $${cost.toFixed(4)}`)
+ * console.log(`Savings vs no cache: $${cost.savings.toFixed(4)}`)
+ * ```
+ */
+export declare function calculateCacheCost(usage: {
+    model: keyof typeof ANTHROPIC_PRICING;
+    promptTokens: number;
+    completionTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}): {
+    total: number;
+    breakdown: Record<string, number>;
+    savings: number;
+};
+//# sourceMappingURL=cache-utils.d.ts.map

package/dist/llm/cache-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-utils.d.ts","sourceRoot":"","sources":["../../src/llm/cache-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAKnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,qBAAqB,EAAE,MAAM,GAC5B,MAAM,CAeR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,YAAY,EAAE,MAAM,CAAA;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,MAAM,GAAG,IAAI,CAqBhB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAItE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,QAAQ,EAAE,OAAO,EAAE,CAAA;CACpB,GAAG,OAAO,EAAE,CAwBZ;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;CAmBpB,CAAA;AAEV;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,KAAK,EAAE,MAAM,OAAO,iBAAiB,CAAA;IACrC,YAAY,EAAE,MAAM,CAAA;IACpB,gBAAgB,EAAE,MAAM,CAAA;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAwBxE"}

package/dist/llm/cache-utils.js

@@ -0,0 +1,204 @@
+/**
+ * Prompt Caching Utilities
+ *
+ * Helper functions for optimizing Anthropic prompt caching usage.
+ * Cache hits provide up to 90% cost reduction on input tokens.
+ *
+ * Cache TTL: 5 minutes
+ * Minimum cacheable content: ~1024 tokens (~300 words)
+ *
+ * Best practices:
+ * - Cache stable content that repeats across requests
+ * - Place cached content at message boundaries
+ * - Cache system prompts, tools, and large context documents
+ * - Order matters: place most stable content first
+ *
+ * @see https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+ */
+/**
+ * Mark a message for caching
+ * Use this for system prompts, tool definitions, or large context that repeats
+ */
+export function withCache(message) {
+    return {
+        ...message,
+        cacheControl: { type: 'ephemeral' },
+    };
+}
+/**
+ * Create a cacheable system prompt message
+ *
+ * @example
+ * ```ts
+ * const systemPrompt = cacheableSystemPrompt(
+ *   'You are a helpful AI assistant with expertise in TypeScript and React.'
+ * )
+ * ```
+ */
+export function cacheableSystemPrompt(content) {
+    return withCache({
+        role: 'system',
+        content,
+    });
+}
+/**
+ * Calculate potential cost savings from caching
+ *
+ * @param inputTokens - Total input tokens
+ * @param cacheHitRate - Percentage of requests that hit cache (0-1)
+ * @param cachedTokenPercentage - Percentage of input that's cached (0-1)
+ * @returns Estimated cost reduction percentage
+ *
+ * @example
+ * ```ts
+ * // If 50% of requests hit cache and 70% of input is cached content
+ * const savings = estimateCacheSavings(10000, 0.5, 0.7)
+ * console.log(`${savings}% cost reduction`) // ~31.5%
+ * ```
+ */
+export function estimateCacheSavings(inputTokens, cacheHitRate, cachedTokenPercentage) {
+    const cachedTokens = inputTokens * cachedTokenPercentage;
+    const uncachedTokens = inputTokens - cachedTokens;
+    // Cache creation cost: full price
+    const firstRequestCost = inputTokens;
+    // Cache hit cost: 10% for cached tokens + full price for uncached
+    const cachedRequestCost = cachedTokens * 0.1 + uncachedTokens;
+    // Average cost considering hit rate
+    const avgCost = firstRequestCost * (1 - cacheHitRate) + cachedRequestCost * cacheHitRate;
+    // Savings percentage
+    return ((inputTokens - avgCost) / inputTokens) * 100;
+}
+/**
+ * Format cache statistics from response
+ *
+ * @example
+ * ```ts
+ * const response = await client.chat(messages, { enableCache: true })
+ * const stats = formatCacheStats(response.usage)
+ * console.log(stats)
+ * // "Cache: 45% read (2,500 tokens), 10% created (500 tokens)"
+ * ```
+ */
+export function formatCacheStats(usage) {
+    const { promptTokens, cacheCreationTokens = 0, cacheReadTokens = 0 } = usage;
+    if (cacheCreationTokens === 0 && cacheReadTokens === 0) {
+        return null;
+    }
+    const readPct = ((cacheReadTokens / promptTokens) * 100).toFixed(0);
+    const createdPct = ((cacheCreationTokens / promptTokens) * 100).toFixed(0);
+    const parts = [];
+    if (cacheReadTokens > 0) {
+        parts.push(`${readPct}% read (${cacheReadTokens.toLocaleString()} tokens)`);
+    }
+    if (cacheCreationTokens > 0) {
+        parts.push(`${createdPct}% created (${cacheCreationTokens.toLocaleString()} tokens)`);
+    }
+    return `Cache: ${parts.join(', ')}`;
+}
+/**
+ * Check if caching is beneficial for the given content
+ * Anthropic recommends caching content >1024 tokens
+ */
+export function shouldCache(content, minTokens = 1024) {
+    // Rough estimation: ~4 chars per token
+    const estimatedTokens = content.length / 4;
+    return estimatedTokens >= minTokens;
+}
+/**
+ * Create a conversation with optimal caching structure
+ *
+ * @example
+ * ```ts
+ * const conversation = createCachedConversation({
+ *   systemPrompt: 'You are a helpful assistant...',
+ *   tools: [...], // Large tool definitions
+ *   contextDocs: ['# Documentation\n...'], // Large context documents
+ *   messages: [
+ *     { role: 'user', content: 'What is TypeScript?' },
+ *   ],
+ * })
+ *
+ * const response = await client.chat(conversation, { enableCache: true })
+ * ```
+ */
+export function createCachedConversation(config) {
+    const result = [];
+    // System prompt (always cached if present)
+    if (config.systemPrompt) {
+        result.push(cacheableSystemPrompt(config.systemPrompt));
+    }
+    // Context documents as system messages (cache last one)
+    if (config.contextDocs && config.contextDocs.length > 0) {
+        config.contextDocs.forEach((doc, index) => {
+            const isLast = index === (config.contextDocs?.length ?? 0) - 1;
+            result.push({
+                role: 'system',
+                content: doc,
+                ...(isLast ? { cacheControl: { type: 'ephemeral' } } : {}),
+            });
+        });
+    }
+    // User/assistant messages (not cached by default)
+    result.push(...config.messages);
+    return result;
+}
+/**
+ * Pricing information for Anthropic Claude models (as of 2024)
+ * Prices are per million tokens
+ */
+export const ANTHROPIC_PRICING = {
+    'claude-3-5-sonnet-20241022': {
+        input: 3.0,
+        output: 15.0,
+        cacheWrite: 3.75, // 25% markup for cache creation
+        cacheRead: 0.3, // 90% discount for cache hits
+    },
+    'claude-3-5-haiku-20241022': {
+        input: 1.0,
+        output: 5.0,
+        cacheWrite: 1.25,
+        cacheRead: 0.1,
+    },
+    'claude-3-opus-20240229': {
+        input: 15.0,
+        output: 75.0,
+        cacheWrite: 18.75,
+        cacheRead: 1.5,
+    },
+};
+/**
+ * Calculate actual cost of a request with caching
+ *
+ * @example
+ * ```ts
+ * const cost = calculateCacheCost({
+ *   model: 'claude-3-5-sonnet-20241022',
+ *   promptTokens: 10000,
+ *   completionTokens: 500,
+ *   cacheCreationTokens: 3000,
+ *   cacheReadTokens: 5000,
+ * })
+ *
+ * console.log(`Request cost: $${cost.toFixed(4)}`)
+ * console.log(`Savings vs no cache: $${cost.savings.toFixed(4)}`)
+ * ```
+ */
+export function calculateCacheCost(usage) {
+    const pricing = ANTHROPIC_PRICING[usage.model];
+    const uncachedTokens = usage.promptTokens - (usage.cacheCreationTokens || 0) - (usage.cacheReadTokens || 0);
+    const costs = {
+        input: (uncachedTokens / 1_000_000) * pricing.input,
+        output: (usage.completionTokens / 1_000_000) * pricing.output,
+        cacheWrite: ((usage.cacheCreationTokens || 0) / 1_000_000) * pricing.cacheWrite,
+        cacheRead: ((usage.cacheReadTokens || 0) / 1_000_000) * pricing.cacheRead,
+    };
+    const total = costs.input + costs.output + costs.cacheWrite + costs.cacheRead;
+    // Calculate savings vs no caching
+    const noCacheCost = (usage.promptTokens / 1_000_000) * pricing.input +
+        (usage.completionTokens / 1_000_000) * pricing.output;
+    return {
+        total,
+        breakdown: costs,
+        savings: noCacheCost - total,
+    };
+}

package/dist/llm/client.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Unified LLM Client
+ *
+ * Single interface for all LLM providers with fallback and rate limiting
+ */
+/**
+ * Redact sensitive fields before passing an object to a logger.
+ * Replaces API keys, tokens, and authorization headers with `[REDACTED]`.
+ * Recurses into nested plain objects; leaves arrays and primitives as-is.
+ */
+export declare function redactSensitiveFields(obj: Record<string, unknown>): Record<string, unknown>;
+import type { Database } from '@revealui/db/client';
+import type { AuditStore } from '../audit/store.js';
+import type { ProviderHealthMonitor } from './provider-health.js';
+import type { Embedding, LLMChatOptions, LLMChunk, LLMEmbedOptions, LLMResponse, LLMStreamOptions, Message } from './providers/base.js';
+import { type CacheStats, type ResponseCacheOptions } from './response-cache.js';
+import { type SemanticCacheOptions, type SemanticCacheStats } from './semantic-cache.js';
+export type LLMProviderType = 'openai' | 'anthropic' | 'vultr' | 'groq' | 'ollama' | 'huggingface';
+export interface LLMClientConfig {
+    provider: LLMProviderType;
+    apiKey: string;
+    /**
+     * Dynamic API key resolver — called before every LLM request.
+     * When set, the resolved key replaces `apiKey` on each call.
+     * Use this for OAuth tokens or any credential that expires between requests.
+     */
+    apiKeyFn?: () => Promise<string>;
+    baseURL?: string;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    fallbackProvider?: LLMProviderType;
+    rateLimit?: {
+        requestsPerMinute?: number;
+        requestsPerDay?: number;
+    };
+    /** Enable Anthropic prompt caching by default (90% cost reduction on cache hits) */
+    enableCacheByDefault?: boolean;
+    /** Enable response caching (100% cost savings on duplicate requests) */
+    enableResponseCache?: boolean;
+    /** Response cache options */
+    responseCacheOptions?: ResponseCacheOptions;
+    /** Enable semantic caching (73% cost reduction, 65% hit rate) */
+    enableSemanticCache?: boolean;
+    /** Semantic cache options */
+    semanticCacheOptions?: SemanticCacheOptions;
+    /** Optional health monitor — records latency + error rate per provider */
+    healthMonitor?: ProviderHealthMonitor;
+}
+export declare class LLMClient {
+    private provider;
+    private fallbackProvider?;
+    private config;
+    private rateLimitState;
+    private responseCache?;
+    private semanticCache?;
+    private healthMonitor?;
+    /** Tracks the last resolved API key so we only recreate the provider when it changes */
+    private currentApiKey;
+    constructor(config: LLMClientConfig);
+    private createProvider;
+    /**
+     * Re-resolve the API key via apiKeyFn (if configured) and recreate the provider
+     * when the key has changed. No-op if apiKeyFn is not set.
+     */
+    private refreshProviderIfNeeded;
+    private checkRateLimit;
+    private recordRequest;
+    chat(messages: Message[], options?: LLMChatOptions): Promise<LLMResponse>;
+    embed(text: string | string[], options?: LLMEmbedOptions): Promise<Embedding | Embedding[]>;
+    stream(messages: Message[], options?: LLMStreamOptions): AsyncIterable<LLMChunk>;
+    /**
+     * Estimate token count and cost for a set of messages using the configured model.
+     * Uses a heuristic (~4 chars/token). Useful for pre-flight cost checks.
+     */
+    estimateRequest(messages: Message[]): {
+        tokens: number;
+        estimatedCostUsd: number;
+    };
+    /**
+     * Get the provider health monitor if one was configured.
+     */
+    getHealthMonitor(): ProviderHealthMonitor | undefined;
+    /**
+     * Get response cache statistics
+     *
+     * @returns Cache stats or undefined if caching is disabled
+     */
+    getResponseCacheStats(): CacheStats | undefined;
+    /**
+     * Clear response cache
+     */
+    clearResponseCache(): void;
+    /**
+     * Get semantic cache statistics
+     *
+     * @returns Semantic cache stats or undefined if caching is disabled
+     */
+    getSemanticCacheStats(): SemanticCacheStats | undefined;
+    /**
+     * Clear semantic cache
+     */
+    clearSemanticCache(): void;
+}
+/**
+ * Create an LLM client from environment variables.
+ *
+ * When LLM_PROVIDER is not set, auto-detects the provider by checking env vars
+ * in priority order: GROQ_API_KEY → OLLAMA_BASE_URL → ANTHROPIC_API_KEY.
+ *
+ * GROQ and Ollama are preferred — they are free-tier and BYOK-friendly.
+ * OpenAI is not in the auto-detection chain (no revenue yet — see LLM provider policy).
+ * To use OpenAI, set LLM_PROVIDER=openai explicitly.
+ *
+ * Provider defaults:
+ *   groq   → llama-3.3-70b-versatile
+ *   ollama → llama3.2:3b
+ */
+export declare function createLLMClientFromEnv(): LLMClient;
+/**
+ * Create an LLM client using a user's stored BYOK API key.
+ *
+ * Looks up the user's preferred provider from `tenant_provider_configs`
+ * (falling back to the first key in `user_api_keys`), decrypts the key
+ * with AES-256-GCM, and returns a configured LLMClient.
+ *
+ * Returns `null` if the user has no stored keys (callers should fall back
+ * to `createLLMClientFromEnv()` or return a 402/feature-unavailable error).
+ *
+ * @param userId - The user's ID from the `users` table
+ * @param db - A Drizzle NeonDB client instance
+ */
+export declare function createLLMClientForUser(userId: string, db: Database, auditStore?: AuditStore): Promise<LLMClient | null>;
+//# sourceMappingURL=client.d.ts.map

package/dist/llm/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/llm/client.ts"],"names":[],"mappings":"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"}