lazlo-ai 1.0.0

package/src/cache/semantic.ts

@@ -0,0 +1,175 @@
+/**
+ * Semantic Cache - Cache LLM responses with semantic similarity
+ */
+
+import { logger } from '../utils/logger.js';
+
+// Simple in-memory embeddings for cosine similarity
+// In production, you'd use sentence-transformers or an embedding API
+type Embedding = number[];
+
+interface CacheEntry {
+  prompt: string;
+  response: string;
+  embedding: Embedding;
+}
+
+// ============================================================================
+// Cosine Similarity
+// ============================================================================
+
+function cosineSimilarity(v1: Embedding, v2: Embedding): number {
+  const dot = v1.reduce((sum, a, i) => sum + a * v2[i], 0);
+  const norm1 = Math.sqrt(v1.reduce((sum, a) => sum + a * a, 0));
+  const norm2 = Math.sqrt(v2.reduce((sum, b) => sum + b * b, 0));
+  
+  if (norm1 === 0 || norm2 === 0) return 0;
+  return dot / (norm1 * norm2);
+}
+
+// Simple hash-based embedding (for demo - in production use real embeddings)
+// This creates a deterministic "embedding" from the text
+function simpleEmbedding(text: string): Embedding {
+  const hash = new Map<string, number>();
+  const words = text.toLowerCase().split(/\s+/);
+  
+  // Create a simple bag-of-words embedding
+  for (let i = 0; i < 384; i++) {
+    hash.set(String(i), 0);
+  }
+  
+  words.forEach((word, idx) => {
+    const hash1 = (word.charCodeAt(0) * 31 + idx) % 384;
+    const hash2 = (word.length * 17 + idx) % 384;
+    hash.set(String(hash1), (hash.get(String(hash1)) ?? 0) + 1);
+    hash.set(String(hash2), (hash.get(String(hash2)) ?? 0) + 0.5);
+  });
+  
+  // Normalize
+  const embedding: Embedding = [];
+  let norm = 0;
+  for (let i = 0; i < 384; i++) {
+    const val = hash.get(String(i)) ?? 0;
+    embedding.push(val);
+    norm += val * val;
+  }
+  norm = Math.sqrt(norm);
+  return embedding.map(v => v / (norm || 1));
+}
+
+// ============================================================================
+// Semantic Cache
+// ============================================================================
+
+export interface SemanticCacheOptions {
+  threshold?: number;  // Cosine similarity threshold (default: 0.92)
+}
+
+export class SemanticCache {
+  private store: CacheEntry[] = [];
+  private threshold: number;
+  private hits = 0;
+  private misses = 0;
+  private tokensSaved = 0;
+  
+  constructor(options: SemanticCacheOptions = {}) {
+    this.threshold = options.threshold ?? 0.92;
+    logger.info(`SemanticCache ready. Threshold: ${this.threshold}`);
+  }
+  
+  /**
+   * Look up a cached response
+   */
+  lookup(prompt: string): string | null {
+    if (this.store.length === 0) {
+      return null;
+    }
+    
+    const queryEmbedding = simpleEmbedding(prompt);
+    let bestScore = 0;
+    let bestResponse: string | null = null;
+    
+    for (const entry of this.store) {
+      const score = cosineSimilarity(queryEmbedding, entry.embedding);
+      if (score > bestScore) {
+        bestScore = score;
+        bestResponse = entry.response;
+      }
+    }
+    
+    if (bestScore >= this.threshold) {
+      logger.info(`[SemanticCache] CACHE HIT (similarity=${bestScore.toFixed(3)}). Skipping LLM call.`);
+      this.hits++;
+      this.tokensSaved += bestResponse!.length / 4;
+      return bestResponse;
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Store a response in the cache
+   */
+  put(prompt: string, response: string): void {
+    const embedding = simpleEmbedding(prompt);
+    this.store.push({ prompt, response, embedding });
+    logger.debug(`[SemanticCache] Stored response for: ${prompt.slice(0, 50)}...`);
+  }
+  
+  /**
+   * Wrap an LLM to use caching
+   */
+  wrap<T extends { invoke(prompt: string): Promise<any> }>(llm: T): T & { invoke(prompt: string): Promise<any> } {
+    const cache = this;
+    
+    const cachedInvoke = async function(prompt: string) {
+      const cached = cache.lookup(prompt);
+      if (cached !== null) {
+        return cached;
+      }
+      
+      cache.misses++;
+      logger.debug('[SemanticCache] CACHE MISS. Calling LLM.');
+      
+      const response = await llm.invoke(prompt);
+      const responseStr = typeof response === 'string' ? response : response.content ?? '';
+      cache.put(prompt, responseStr);
+      
+      return response;
+    };
+    
+    return Object.assign(cachedInvoke, llm);
+  }
+  
+  /**
+   * Print cache statistics
+   */
+  printStats(): void {
+    const total = this.hits + this.misses;
+    const hitRate = total > 0 ? (this.hits / total * 100).toFixed(1) : '0.0';
+    const costSaved = (this.tokensSaved / 1000 * 0.002).toFixed(4);
+    
+    console.log(`
+${'='.repeat(50)}
+  Lazlo SemanticCache Stats
+${'='.repeat(50)}
+  Total calls : ${total}
+  Cache hits  : ${this.hits} (${hitRate}%)
+  Cache misses: ${this.misses}
+  Est. tokens saved : ~${this.tokensSaved.toLocaleString()}
+  Est. cost avoided : ~$${costSaved}
+${'='.repeat(50)}
+`);
+  }
+  
+  /**
+   * Clear the cache
+   */
+  clear(): void {
+    this.store = [];
+    this.hits = 0;
+    this.misses = 0;
+    this.tokensSaved = 0;
+    logger.info('SemanticCache cleared.');
+  }
+}

package/src/chains/llmchain.ts

@@ -0,0 +1,194 @@
+/**
+ * LLMChain - Simple prompt chaining
+ */
+
+import { BaseChatModel, Message, ChainInputs, ChainOutputs, ToolDefinition } from '../core/types.js';
+import { logger } from '../utils/logger.js';
+import { getPricing, estimateTokens, calculateCost } from '../utils/pricing.js';
+
+// ============================================================================
+// Prompt Template
+// ============================================================================
+
+export class PromptTemplate {
+  private template: string;
+  private inputVariables: string[];
+  
+  constructor(template: string) {
+    this.template = template;
+    // Extract variables from {variable} patterns
+    const regex = /\{([^}]+)\}/g;
+    const matches = template.match(regex);
+    this.inputVariables = matches ? matches.map(m => m.slice(1, -1)) : [];
+  }
+  
+  format(values: Record<string, unknown>): string {
+    // Check for missing variables
+    const missing = this.inputVariables.filter(v => !(v in values));
+    if (missing.length > 0) {
+      throw new Error(`Missing required variables: ${missing.join(', ')}`);
+    }
+    
+    let result = this.template;
+    for (const [key, value] of Object.entries(values)) {
+      result = result.replace(new RegExp(`\\{${key}\\}`, 'g'), String(value));
+    }
+    return result;
+  }
+  
+  get inputVars(): string[] {
+    return this.inputVariables;
+  }
+}
+
+// ============================================================================
+// LLM Chain
+// ============================================================================
+
+export interface LLMChainOptions {
+  llm: BaseChatModel;
+  prompt: PromptTemplate;
+  outputKey?: string;
+}
+
+export interface CostEstimate {
+  estimatedTokensIn: number;
+  estimatedTokensOut: number;
+  estimatedCostUsd: number;
+  estimatedLatencyMs: number;
+  model: string;
+  pricing: { input: number; output: number };
+}
+
+export class LLMChain {
+  private llm: BaseChatModel;
+  private prompt: PromptTemplate;
+  private outputKey: string;
+  
+  constructor(options: LLMChainOptions) {
+    this.llm = options.llm;
+    this.prompt = options.prompt;
+    this.outputKey = options.outputKey ?? 'text';
+  }
+  
+  /**
+   * Estimate cost before running
+   */
+  estimateCost(inputs: ChainInputs, model?: string): CostEstimate {
+    const modelName = model ?? (this.llm as any).defaultModel ?? 'default';
+    const formattedPrompt = this.prompt.format(inputs);
+    const estimatedTokensIn = estimateTokens(formattedPrompt);
+    const estimatedTokensOut = Math.max(1, Math.floor(estimatedTokensIn / 4));
+    
+    const pricing = getPricing(modelName);
+    const estimatedCost = 
+      (estimatedTokensIn / 1_000_000 * pricing.input) +
+      (estimatedTokensOut / 1_000_000 * pricing.output);
+    
+    // Rough latency: 100ms per 1K input + 50ms per 1K output
+    const estimatedLatency = Math.floor(estimatedTokensIn * 0.1 + estimatedTokensOut * 0.05);
+    
+    return {
+      estimatedTokensIn,
+      estimatedTokensOut,
+      estimatedCostUsd: Math.round(estimatedCost * 1_000_000) / 1_000_000,
+      estimatedLatencyMs: estimatedLatency,
+      model: modelName,
+      pricing,
+    };
+  }
+  
+  /**
+   * Invoke the chain synchronously
+   */
+  async invoke(inputs: ChainInputs): Promise<ChainOutputs> {
+    const formattedPrompt = this.prompt.format(inputs);
+    logger.debug(`[Chain] Prompt: ${formattedPrompt.slice(0, 100)}...`);
+    
+    const messages: Message[] = [{ role: 'user', content: formattedPrompt }];
+    const response = await this.llm.invoke(messages);
+    
+    const outputs: ChainOutputs = {
+      [this.outputKey]: response.content,
+    };
+    
+    // Include usage info if available
+    if (response.usage) {
+      (outputs as any).usage = response.usage;
+      (outputs as any).cost = calculateCost(
+        response.model ?? 'default',
+        response.usage.prompt_tokens,
+        response.usage.completion_tokens
+      );
+    }
+    
+    return outputs;
+  }
+  
+  /**
+   * Stream the response
+   */
+  async *stream(inputs: ChainInputs): AsyncGenerator<string> {
+    const formattedPrompt = this.prompt.format(inputs);
+    logger.debug(`[Chain Stream] Prompt: ${formattedPrompt.slice(0, 100)}...`);
+    
+    const messages: Message[] = [{ role: 'user', content: formattedPrompt }];
+    
+    for await (const chunk of this.llm.stream?.(messages) ?? []) {
+      yield chunk.delta;
+    }
+  }
+  
+  /**
+   * Async invoke
+   */
+  async ainvoke(inputs: ChainInputs): Promise<ChainOutputs> {
+    return this.invoke(inputs);
+  }
+  
+  /**
+   * Async stream
+   */
+  async *astream(inputs: ChainInputs): AsyncGenerator<string> {
+    yield* this.stream(inputs);
+  }
+}
+
+// ============================================================================
+// Sequential Chain
+// ============================================================================
+
+export class SequentialChain {
+  private chains: LLMChain[];
+  private inputVariables: string[];
+  private outputVariables: string[];
+  
+  constructor(options: {
+    chains: LLMChain[];
+    inputVariables: string[];
+    outputVariables: string[];
+  }) {
+    this.chains = options.chains;
+    this.inputVariables = options.inputVariables;
+    this.outputVariables = options.outputVariables;
+  }
+  
+  async invoke(inputs: ChainInputs): Promise<ChainOutputs> {
+    let currentState = { ...inputs };
+    
+    for (let i = 0; i < this.chains.length; i++) {
+      logger.debug(`[SequentialChain] Executing Chain ${i + 1}/${this.chains.length}`);
+      const chainOutput = await this.chains[i].invoke(currentState);
+      currentState = { ...currentState, ...chainOutput };
+    }
+    
+    // Return only the requested output variables
+    const result: ChainOutputs = {};
+    for (const key of this.outputVariables) {
+      if (key in currentState) {
+        result[key] = currentState[key];
+      }
+    }
+    return result;
+  }
+}

package/src/chains/rag.ts

@@ -0,0 +1,65 @@
+/**
+ * RAG Chain - Retrieval-Augmented Generation
+ */
+
+import { BaseChatModel, BaseRetriever, Document } from '../core/types.js';
+import { logger } from '../utils/logger.js';
+
+const DEFAULT_PROMPT = `You are a helpful assistant. Use the following context to answer the query.
+
+Context:
+{context}
+
+Query: {query}
+
+Answer:`;
+
+export class RetrievalQAChain {
+  private llm: BaseChatModel;
+  private retriever: BaseRetriever;
+  private promptTemplate: string;
+  
+  constructor(options: {
+    llm: BaseChatModel;
+    retriever: BaseRetriever;
+    promptTemplate?: string;
+  }) {
+    this.llm = options.llm;
+    this.retriever = options.retriever;
+    this.promptTemplate = options.promptTemplate ?? DEFAULT_PROMPT;
+  }
+  
+  async invoke(query: string): Promise<{ text: string; documents: Document[] }> {
+    const docs = await this.retriever.getRelevantDocuments(query);
+    
+    // Combine documents into context
+    const contextParts = docs.map(doc => doc.pageContent);
+    const context = contextParts.join('\n\n---\n\n');
+    
+    // Format prompt
+    const prompt = this.promptTemplate
+      .replace('{context}', context)
+      .replace('{query}', query);
+    
+    logger.debug(`[RetrievalQAChain] Retrieved ${docs.length} documents. Invoking LLM.`);
+    
+    const response = await this.llm.invoke([
+      { role: 'user', content: prompt }
+    ]);
+    
+    return {
+      text: response.content,
+      documents: docs,
+    };
+  }
+}
+
+/**
+ * Factory function for RAG chain
+ */
+export function createRetrievalChain(
+  llm: BaseChatModel,
+  retriever: BaseRetriever
+): RetrievalQAChain {
+  return new RetrievalQAChain({ llm, retriever });
+}

package/src/core/types.ts

@@ -0,0 +1,178 @@
+/**
+ * Lazlo Core Types & Protocols
+ * 
+ * The foundation of Lazlo - protocol definitions that any LLM, tool, or memory
+ * implementation must satisfy. No massive base classes, just duck typing.
+ */
+
+// ============================================================================
+// Message Types
+// ============================================================================
+
+export interface Message {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  name?: string;
+  tool_call_id?: string;
+}
+
+export interface ToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string | Record<string, unknown>;
+  };
+}
+
+export interface ChatResponse {
+  content: string;
+  tool_calls?: ToolCall[];
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+  model?: string;
+  finish_reason?: 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+}
+
+export interface StreamChunk {
+  delta: string;
+  finish_reason?: string;
+  index?: number;
+}
+
+// ============================================================================
+// Protocol Interfaces (Duck Typing Support)
+// ============================================================================
+
+export interface BaseLLM {
+  invoke(prompt: string, options?: LLMInvokeOptions): Promise<string>;
+  ainvoke(prompt: string, options?: LLMInvokeOptions): Promise<string>;
+  stream?(prompt: string, options?: LLMInvokeOptions): AsyncGenerator<string>;
+  astream?(prompt: string, options?: LLMInvokeOptions): AsyncGenerator<string>;
+}
+
+export interface BaseChatModel {
+  readonly supportsTools: boolean;
+  readonly supportsStructuredOutput: boolean;
+  
+  invoke(messages: Message[], options?: ChatInvokeOptions): Promise<ChatResponse>;
+  ainvoke?(messages: Message[], options?: ChatInvokeOptions): Promise<ChatResponse>;
+  
+  stream?(messages: Message[], options?: ChatInvokeOptions): AsyncGenerator<StreamChunk>;
+  astream?(messages: Message[], options?: ChatInvokeOptions): AsyncGenerator<StreamChunk>;
+}
+
+export interface BaseTool {
+  name: string;
+  description: string;
+  argsSchema?: Record<string, unknown>;
+  
+  invoke(input: string | Record<string, unknown>): Promise<string>;
+  ainvoke?(input: string | Record<string, unknown>): Promise<string>;
+}
+
+export interface BaseMemory {
+  loadMemoryVariables(inputs: Record<string, unknown>): Promise<Record<string, unknown>>;
+  saveContext(inputs: Record<string, unknown>, outputs: Record<string, string>): Promise<void>;
+  clear(): Promise<void>;
+}
+
+export interface BaseRetriever {
+  getRelevantDocuments(query: string): Promise<Document[]>;
+}
+
+export interface BaseVectorStore {
+  addTexts(texts: string[], metadatas?: Record<string, unknown>[]): Promise<string[]>;
+  similaritySearch(query: string, k?: number): Promise<Document[]>;
+  addDocuments?(documents: Document[]): Promise<string[]>;
+}
+
+export interface BaseEmbeddings {
+  embedQuery(text: string): Promise<number[]>;
+  embedDocuments(texts: string[]): Promise<number[][]>;
+}
+
+// ============================================================================
+// Document Types
+// ============================================================================
+
+export interface Document {
+  pageContent: string;
+  metadata: Record<string, unknown>;
+}
+
+// ============================================================================
+// Options Types
+// ============================================================================
+
+export interface LLMInvokeOptions {
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  frequencyPenalty?: number;
+  presencePenalty?: number;
+  stop?: string | string[];
+  [key: string]: unknown;
+}
+
+export interface ChatInvokeOptions extends LLMInvokeOptions {
+  tools?: ToolDefinition[];
+  responseFormat?: ResponseFormat;
+}
+
+export interface ToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
+export interface ResponseFormat {
+  type: 'text' | 'json_object' | 'json_schema';
+  json_schema?: {
+    name: string;
+    schema: Record<string, unknown>;
+    strict?: boolean;
+  };
+}
+
+// ============================================================================
+// Chain Types
+// ============================================================================
+
+export interface ChainInputs {
+  [key: string]: unknown;
+}
+
+export interface ChainOutputs {
+  [key: string]: unknown;
+}
+
+export interface Chain {
+  invoke(inputs: ChainInputs): Promise<ChainOutputs>;
+  ainvoke?(inputs: ChainInputs): Promise<ChainOutputs>;
+}
+
+// ============================================================================
+// Pricing Types
+// ============================================================================
+
+export interface ModelPricing {
+  input: number;  // per 1M tokens
+  output: number; // per 1M tokens
+}
+
+// ============================================================================
+// Cached Types
+// ============================================================================
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export interface JsonObject { [key: string]: JsonValue; }
+export interface JsonArray extends Array<JsonValue> {}