lazlo-ai 1.0.0

package/src/tracing/tracer.ts

@@ -0,0 +1,178 @@
+/**
+ * Tracing - Built-in observability without SaaS
+ */
+
+import { logger } from '../utils/logger.js';
+
+// ============================================================================
+// Span
+// ============================================================================
+
+export interface SpanData {
+  name: string;
+  type: string;
+  durationMs: number;
+  tokensIn: number;
+  tokensOut: number;
+  costUsd: number;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+class Span {
+  name: string;
+  type: string;
+  startTime: number;
+  endTime?: number;
+  tokensIn = 0;
+  tokensOut = 0;
+  metadata: Record<string, unknown> = {};
+  error?: string;
+  
+  constructor(name: string, type: string = 'llm') {
+    this.name = name;
+    this.type = type;
+    this.startTime = Date.now();
+  }
+  
+  finish(): void {
+    this.endTime = Date.now();
+  }
+  
+  get durationMs(): number {
+    if (!this.endTime) return 0;
+    return this.endTime - this.startTime;
+  }
+  
+  get costUsd(): number {
+    const rate = this.type === 'llm' ? 0.002 : 0;
+    return ((this.tokensIn + this.tokensOut) / 1000) * rate;
+  }
+  
+  toDict(): SpanData {
+    return {
+      name: this.name,
+      type: this.type,
+      durationMs: this.durationMs,
+      tokensIn: this.tokensIn,
+      tokensOut: this.tokensOut,
+      costUsd: this.costUsd,
+      error: this.error,
+      metadata: this.metadata,
+    };
+  }
+}
+
+// ============================================================================
+// Tracer
+// ============================================================================
+
+interface Run {
+  name: string;
+  correlationId: string;
+  totalDurationMs: number;
+  totalTokens: number;
+  totalCostUsd: number;
+  spans: SpanData[];
+}
+
+export class Tracer {
+  private runs: Run[] = [];
+  private currentRunName?: string;
+  private currentSpans: Span[] = [];
+  
+  /**
+   * Start a trace context
+   */
+  trace(runName: string): { tracer: Tracer; span: (name: string, type?: string) => Span; end: () => void } {
+    this.currentRunName = runName;
+    this.currentSpans = [];
+    const runStart = Date.now();
+    
+    logger.info(`[Tracer] Run '${runName}' started.`);
+    
+    return {
+      tracer: this,
+      span: (name: string, type: string = 'llm') => {
+        const s = new Span(name, type);
+        this.currentSpans.push(s);
+        return s;
+      },
+      end: () => {
+        const runEnd = Date.now();
+        const runDuration = runEnd - runStart;
+        const totalCost = this.currentSpans.reduce((sum, s) => sum + s.costUsd, 0);
+        const totalTokens = this.currentSpans.reduce((sum, s) => sum + s.tokensIn + s.tokensOut, 0);
+        
+        this.runs.push({
+          name: runName,
+          correlationId: Math.random().toString(36).slice(2, 10),
+          totalDurationMs: runDuration,
+          totalTokens,
+          totalCostUsd: totalCost,
+          spans: this.currentSpans.map(s => s.toDict()),
+        });
+        
+        logger.info(`[Tracer] Run '${runName}' finished in ${runDuration}ms. Est. cost: $${totalCost.toFixed(5)}`);
+      },
+    };
+  }
+  
+  /**
+   * Record an event/span
+   */
+  event(
+    name: string, 
+    type: string = 'llm',
+    tokensIn: number = 0,
+    tokensOut: number = 0,
+    metadata?: Record<string, unknown>
+  ): void {
+    const span = new Span(name, type);
+    span.tokensIn = tokensIn;
+    span.tokensOut = tokensOut;
+    span.metadata = metadata ?? {};
+    span.finish();
+    this.currentSpans.push(span);
+  }
+  
+  /**
+   * Print trace summary
+   */
+  printSummary(): void {
+    if (this.runs.length === 0) {
+      console.log('No traces recorded yet.');
+      return;
+    }
+    
+    for (const run of this.runs) {
+      console.log(`\n${'='.repeat(70)}`);
+      console.log(`  Lazlo Trace: ${run.name}`);
+      console.log(`  Total: ${run.totalDurationMs}ms | ~${run.totalTokens.toLocaleString()} tokens | Est. $${run.totalCostUsd.toFixed(5)}`);
+      console.log(`${'='.repeat(70)}`);
+      console.log(`  ${'Step'.padEnd(28)} ${'Type'.padEnd(12)} ${'ms'.padStart(8)} ${'Tok-In'.padStart(8)} ${'Tok-Out'.padStart(8)} ${'Cost'.padStart(10)}`);
+      console.log(`  ${'-'.repeat(68)}`);
+      
+      for (const s of run.spans) {
+        const status = s.error ? '❌' : '✓';
+        console.log(
+          `  ${status} ${s.name.slice(0, 26).padEnd(28)} ${s.type.padEnd(12)} ` +
+          `${s.durationMs.toString().padStart(7)}ms ${s.tokensIn.toString().padStart(8)} ` +
+          `${s.tokensOut.toString().padStart(8)} $${s.costUsd.toFixed(5).padStart(9)}`
+        );
+      }
+      console.log(`${'='.repeat(70)}\n`);
+    }
+  }
+  
+  /**
+   * Clear all traces
+   */
+  clear(): void {
+    this.runs = [];
+    this.currentSpans = [];
+  }
+}
+
+// Singleton instance
+export const tracer = new Tracer();

package/src/utils/logger.ts

@@ -0,0 +1,62 @@
+/**
+ * Lazlo Logger - Simple, structured logging
+ */
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+}
+
+const LEVEL_NAMES = ['DEBUG', 'INFO', 'WARN', 'ERROR'];
+
+class Logger {
+  private level: LogLevel = LogLevel.INFO;
+  private prefix: string = '';
+
+  constructor(prefix: string = '') {
+    this.prefix = prefix;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  setPrefix(prefix: string): void {
+    this.prefix = prefix;
+  }
+
+  private log(level: LogLevel, ...args: unknown[]): void {
+    if (level < this.level) return;
+    
+    const timestamp = new Date().toISOString();
+    const levelName = LEVEL_NAMES[level];
+    const prefix = this.prefix ? `[${this.prefix}] ` : '';
+    
+    console.log(`\x1b[90m${timestamp}\x1b[0m ${levelName} ${prefix}`, ...args);
+  }
+
+  debug(...args: unknown[]): void {
+    this.log(LogLevel.DEBUG, ...args);
+  }
+
+  info(...args: unknown[]): void {
+    this.log(LogLevel.INFO, ...args);
+  }
+
+  warn(...args: unknown[]): void {
+    this.log(LogLevel.WARN, ...args);
+  }
+
+  error(...args: unknown[]): void {
+    this.log(LogLevel.ERROR, ...args);
+  }
+}
+
+export const logger = new Logger('Lazlo');
+
+// Factory for child loggers
+export function createLogger(prefix: string): Logger {
+  return new Logger(prefix);
+}

package/src/utils/pricing.ts

@@ -0,0 +1,133 @@
+/**
+ * Lazlo Pricing - Model pricing lookup and cost calculation
+ */
+
+import { ModelPricing } from '../core/types.js';
+
+// Default pricing for common models (per 1M tokens)
+const DEFAULT_PRICING: Record<string, ModelPricing> = {
+  // OpenAI
+  'gpt-4o': { input: 2.50, output: 10.00 },
+  'gpt-4o-mini': { input: 0.15, output: 0.60 },
+  'gpt-4-turbo': { input: 10.00, output: 30.00 },
+  'gpt-3.5-turbo': { input: 0.50, output: 1.50 },
+  'gpt-4': { input: 30.00, output: 60.00 },
+  
+  // Anthropic
+  'claude-3-5-sonnet': { input: 3.00, output: 15.00 },
+  'claude-3-5-sonnet-20241022': { input: 3.00, output: 15.00 },
+  'claude-3-opus': { input: 15.00, output: 75.00 },
+  'claude-3-sonnet': { input: 3.00, output: 15.00 },
+  'claude-3-haiku': { input: 0.25, output: 1.25 },
+  
+  // Google
+  'gemini-1.5-flash': { input: 0.075, output: 0.30 },
+  'gemini-1.5-pro': { input: 1.25, output: 5.00 },
+  'gemini-2.0-flash': { input: 0.00, output: 0.00 },
+  'gemini-2.0-flash-001': { input: 0.00, output: 0.00 },
+  'gemini-2.0-pro': { input: 1.25, output: 5.00 },
+  
+  // DeepSeek
+  'deepseek-chat': { input: 0.14, output: 0.28 },
+  'deepseek-coder': { input: 0.14, output: 0.28 },
+  
+  // Meta Llama
+  'llama-3.1-70b': { input: 0.00, output: 0.00 },
+  'llama-3.1-8b': { input: 0.00, output: 0.00 },
+  'llama-3-70b': { input: 0.00, output: 0.00 },
+  'llama-3-8b': { input: 0.00, output: 0.00 },
+};
+
+// Custom pricing set by user
+const customPricing: Map<string, ModelPricing> = new Map();
+
+/**
+ * Get pricing for a model
+ */
+export function getPricing(model: string): ModelPricing {
+  // Check custom pricing first
+  if (customPricing.has(model)) {
+    return customPricing.get(model)!;
+  }
+  
+  // Try exact match
+  if (DEFAULT_PRICING[model]) {
+    return DEFAULT_PRICING[model];
+  }
+  
+  // Try partial match
+  const modelLower = model.toLowerCase();
+  for (const [key, pricing] of Object.entries(DEFAULT_PRICING)) {
+    if (modelLower.includes(key.toLowerCase()) || key.toLowerCase().includes(modelLower)) {
+      return pricing;
+    }
+  }
+  
+  // Return placeholder - user needs to set pricing
+  return { input: 0, output: 0 };
+}
+
+/**
+ * Set custom pricing for a model
+ */
+export function setPricing(model: string, input: number, output: number): void {
+  customPricing.set(model, { input, output });
+}
+
+/**
+ * Calculate cost in USD
+ */
+export function calculateCost(
+  model: string,
+  tokensIn: number,
+  tokensOut: number
+): number {
+  const pricing = getPricing(model);
+  return (tokensIn / 1_000_000 * pricing.input) + (tokensOut / 1_000_000 * pricing.output);
+}
+
+/**
+ * Estimate tokens from text (rough approximation)
+ */
+export function estimateTokens(text: string): number {
+  // Rough estimate: ~4 characters per token on average
+  return Math.max(1, Math.ceil(text.length / 4));
+}
+
+/**
+ * Estimate cost from text
+ */
+export function estimateCost(
+  model: string,
+  textIn: string,
+  textOut: string
+): number {
+  const tokensIn = estimateTokens(textIn);
+  const tokensOut = estimateTokens(textOut);
+  return calculateCost(model, tokensIn, tokensOut);
+}
+
+/**
+ * Load pricing from environment variables
+ * Call this after setting process.env if needed
+ * Format: LAZLO_PRICING_model_name=input,output
+ */
+export function loadEnvPricing(env?: Record<string, string | undefined>): void {
+  const environment = env ?? (typeof globalThis !== 'undefined' ? (globalThis as any).process?.env : {});
+  
+  for (const [key, value] of Object.entries(environment)) {
+    if (key.startsWith('LAZLO_PRICING_')) {
+      const modelName = key.replace('LAZLO_PRICING_', '').toLowerCase();
+      if (typeof value === 'string') {
+        const parts = value.split(',');
+        if (parts.length === 2) {
+          const input = parseFloat(parts[0]);
+          const output = parseFloat(parts[1]);
+          if (!isNaN(input) && !isNaN(output)) {
+            setPricing(modelName, input, output);
+          }
+        }
+      }
+    }
+  }
+}

package/src/vectorstores/index.ts

@@ -0,0 +1,338 @@
+/**
+ * Vector Stores
+ * 
+ * In-Memory, Chroma, and SQLite-Vector stores for document retrieval
+ */
+
+import { logger } from '../utils/logger.js';
+
+export interface Document {
+  pageContent: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface BaseEmbeddings {
+  embedQuery(text: string): Promise<number[]>;
+  embedDocuments(texts: string[]): Promise<number[][]>;
+}
+
+// ============================================================================
+// Cosine Similarity
+// ============================================================================
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  const dot = a.reduce((sum, v, i) => sum + v * b[i], 0);
+  const normA = Math.sqrt(a.reduce((sum, v) => sum + v * v, 0));
+  const normB = Math.sqrt(b.reduce((sum, v) => sum + v * v, 0));
+  
+  if (normA === 0 || normB === 0) return 0;
+  return dot / (normA * normB);
+}
+
+// ============================================================================
+// In-Memory Vector Store
+// ============================================================================
+
+interface StoredDoc {
+  pageContent: string;
+  metadata: Record<string, unknown>;
+  embedding: number[];
+}
+
+export class InMemoryVectorStore {
+  private embeddingModel?: BaseEmbeddings;
+  private store: StoredDoc[] = [];
+  
+  constructor(embeddingModel?: BaseEmbeddings) {
+    this.embeddingModel = embeddingModel;
+    logger.info('[Lazlo] InMemoryVectorStore ready.');
+  }
+  
+  async addDocuments(documents: Document[]): Promise<void> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const texts = documents.map(d => d.pageContent);
+    const metadatas = documents.map(d => d.metadata);
+    const embeddings = await this.embeddingModel.embedDocuments(texts);
+    
+    documents.forEach((doc, i) => {
+      this.store.push({
+        pageContent: doc.pageContent,
+        metadata: doc.metadata,
+        embedding: embeddings[i],
+      });
+    });
+  }
+  
+  async similaritySearch(query: string, k: number = 4): Promise<Document[]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const queryEmbedding = await this.embeddingModel.embedQuery(query);
+    
+    // Score all documents
+    const scored = this.store.map(doc => ({
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding),
+    }));
+    
+    // Sort by score descending
+    scored.sort((a, b) => b.score - a.score);
+    
+    // Return top k
+    return scored.slice(0, k).map(s => ({
+      pageContent: s.doc.pageContent,
+      metadata: s.doc.metadata,
+    }));
+  }
+  
+  async similaritySearchWithScore(query: string, k: number = 4): Promise<[Document, number][]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const queryEmbedding = await this.embeddingModel.embedQuery(query);
+    
+    const scored = this.store.map(doc => ({
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding),
+    }));
+    
+    scored.sort((a, b) => b.score - a.score);
+    
+    return scored.slice(0, k).map(s => [
+      { pageContent: s.doc.pageContent, metadata: s.doc.metadata },
+      s.score,
+    ]);
+  }
+  
+  delete(): void {
+    this.store = [];
+  }
+}
+
+// ============================================================================
+// Chroma Vector Store (Client-side implementation)
+// ============================================================================
+
+export class ChromaVectorStore {
+  private embeddingModel?: BaseEmbeddings;
+  private collectionName: string;
+  private documents: Map<string, StoredDoc> = new Map();
+  
+  constructor(options: {
+    embeddingModel?: BaseEmbeddings;
+    collectionName?: string;
+  } = {}) {
+    this.embeddingModel = options.embeddingModel;
+    this.collectionName = options.collectionName || 'lazlo-collection';
+    logger.info(`[Lazlo] ChromaVectorStore ready. Collection: ${this.collectionName}`);
+  }
+  
+  async addDocuments(documents: Document[]): Promise<string[]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const texts = documents.map(d => d.pageContent);
+    const embeddings = await this.embeddingModel.embedDocuments(texts);
+    const ids: string[] = [];
+    
+    documents.forEach((doc, i) => {
+      const id = crypto.randomUUID();
+      this.documents.set(id, {
+        pageContent: doc.pageContent,
+        metadata: doc.metadata,
+        embedding: embeddings[i],
+      });
+      ids.push(id);
+    });
+    
+    return ids;
+  }
+  
+  async similaritySearch(query: string, k: number = 4): Promise<Document[]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const queryEmbedding = await this.embeddingModel.embedQuery(query);
+    
+    const scored = Array.from(this.documents.entries()).map(([id, doc]) => ({
+      id,
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding),
+    }));
+    
+    scored.sort((a, b) => b.score - a.score);
+    
+    return scored.slice(0, k).map(s => ({
+      pageContent: s.doc.pageContent,
+      metadata: s.doc.metadata,
+    }));
+  }
+  
+  async similaritySearchWithScore(query: string, k: number = 4): Promise<[Document, number][]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const queryEmbedding = await this.embeddingModel.embedQuery(query);
+    
+    const scored = Array.from(this.documents.entries()).map(([id, doc]) => ({
+      id,
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding),
+    }));
+    
+    scored.sort((a, b) => b.score - a.score);
+    
+    return scored.slice(0, k).map(s => [
+      { pageContent: s.doc.pageContent, metadata: s.doc.metadata },
+      s.score,
+    ]);
+  }
+  
+  async delete(ids: string[]): Promise<void> {
+    for (const id of ids) {
+      this.documents.delete(id);
+    }
+  }
+  
+  async get(ids: string[]): Promise<Document[]> {
+    return ids
+      .map(id => this.documents.get(id))
+      .filter((d): d is StoredDoc => d !== undefined)
+      .map(d => ({ pageContent: d.pageContent, metadata: d.metadata }));
+  }
+}
+
+// ============================================================================
+// SQLite-Vector Store (using better-sqlite3 if available)
+// ============================================================================
+
+export class SQLiteVectorStore {
+  private embeddingModel?: BaseEmbeddings;
+  private dbPath: string;
+  private documents: Map<string, StoredDoc> = new Map();
+  private db: any = null;
+  
+  constructor(options: {
+    embeddingModel?: BaseEmbeddings;
+    dbPath?: string;
+  } = {}) {
+    this.embeddingModel = options.embeddingModel;
+    this.dbPath = options.dbPath || ':memory:';
+    logger.info(`[Lazlo] SQLiteVectorStore ready. Path: ${this.dbPath}`);
+    
+    // Initialize in-memory storage (full SQLite-Vector requires native module)
+    this.initialize();
+  }
+  
+  private initialize(): void {
+    // In-memory storage as fallback (actual sqlite-vec requires native module)
+    logger.debug('[SQLiteVectorStore] Using in-memory storage (install better-sqlite3 for full SQLite-Vector support)');
+  }
+  
+  async addDocuments(documents: Document[]): Promise<string[]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const texts = documents.map(d => d.pageContent);
+    const embeddings = await this.embeddingModel.embedDocuments(texts);
+    const ids: string[] = [];
+    
+    documents.forEach((doc, i) => {
+      const id = crypto.randomUUID();
+      this.documents.set(id, {
+        pageContent: doc.pageContent,
+        metadata: doc.metadata,
+        embedding: embeddings[i],
+      });
+      ids.push(id);
+    });
+    
+    return ids;
+  }
+  
+  async similaritySearch(query: string, k: number = 4): Promise<Document[]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const queryEmbedding = await this.embeddingModel.embedQuery(query);
+    
+    const scored = Array.from(this.documents.entries()).map(([id, doc]) => ({
+      id,
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding),
+    }));
+    
+    scored.sort((a, b) => b.score - a.score);
+    
+    return scored.slice(0, k).map(s => ({
+      pageContent: s.doc.pageContent,
+      metadata: s.doc.metadata,
+    }));
+  }
+  
+  async similaritySearchWithScore(query: string, k: number = 4): Promise<[Document, number][]> {
+    if (!this.embeddingModel) {
+      throw new Error('No embedding model provided');
+    }
+    
+    const queryEmbedding = await this.embeddingModel.embedQuery(query);
+    
+    const scored = Array.from(this.documents.entries()).map(([id, doc]) => ({
+      id,
+      doc,
+      score: cosineSimilarity(queryEmbedding, doc.embedding),
+    }));
+    
+    scored.sort((a, b) => b.score - a.score);
+    
+    return scored.slice(0, k).map(s => [
+      { pageContent: s.doc.pageContent, metadata: s.doc.metadata },
+      s.score,
+    ]);
+  }
+  
+  async delete(ids: string[]): Promise<void> {
+    for (const id of ids) {
+      this.documents.delete(id);
+    }
+  }
+  
+  async get(ids: string[]): Promise<Document[]> {
+    return ids
+      .map(id => this.documents.get(id))
+      .filter((d): d is StoredDoc => d !== undefined)
+      .map(d => ({ pageContent: d.pageContent, metadata: d.metadata }));
+  }
+}
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+export function createVectorStore(embeddingModel?: BaseEmbeddings): InMemoryVectorStore {
+  return new InMemoryVectorStore(embeddingModel);
+}
+
+export function createChromaVectorStore(options?: {
+  embeddingModel?: BaseEmbeddings;
+  collectionName?: string;
+}): ChromaVectorStore {
+  return new ChromaVectorStore(options);
+}
+
+export function createSQLiteVectorStore(options?: {
+  embeddingModel?: BaseEmbeddings;
+  dbPath?: string;
+}): SQLiteVectorStore {
+  return new SQLiteVectorStore(options);
+}