lazlo-ai 1.0.0

package/.env.example

@@ -0,0 +1,9 @@
+# OpenAI API Key (required for OpenAI provider)
+OPENAI_API_KEY=sk-your-openai-key-here
+
+# Keiro Search API (optional - for web search tool)
+KEIRO_API_KEY=your-keiro-key
+
+# Custom model pricing (optional)
+# Format: LAZLO_PRICING_model_name=input_cost,output_cost
+# LAZLO_PRICING_gpt4=2.5,10

package/README.md

@@ -0,0 +1,278 @@
+# Lazlo JS
+
+The Anti-Framework for JavaScript/TypeScript - A production-grade AI framework that prioritizes performance, transparency, and simplicity.
+
+## Why Lazlo?
+
+- **No Black Magic**: When you use a tool, you see the JSON being parsed. Debugging is straightforward JavaScript.
+- **Zero Bloat**: Core Lazlo uses just `axios` and `zod`. Everything else is optional.
+- **Production Built-In**: Caching, routing, and tracing are built directly into Lazlo, locally and securely.
+- **Protocols over Inheritance**: Duck typing works out of the box. If your class implements `invoke()`, it's an LLM.
+- **Full RAG Pipeline**: Document loaders, embeddings, vector stores, and retrievers built-in.
+
+## Installation
+
+```bash
+npm install lazlo
+```
+
+## Environment Setup
+
+Create a `.env` file in your project root:
+
+```bash
+# Required for OpenAI provider
+OPENAI_API_KEY=sk-your-openai-key-here
+
+# Required for Google embeddings/Gemini
+GEMINI_API_KEY=your-gemini-key
+
+# Required for Ollama (local models)
+# No API key needed - runs locally
+
+# Optional: Keiro Search API
+KEIRO_API_KEY=your-keiro-key
+```
+
+## Quick Start
+
+```typescript
+import { OpenAI, LLMChain, PromptTemplate } from 'lazlo';
+
+// Create an LLM - key from OPENAI_API_KEY env var
+const llm = new OpenAI();
+
+// Create a chain
+const chain = new LLMChain({
+  llm,
+  prompt: new PromptTemplate('What is {topic}?'),
+});
+
+// Run it
+const result = await chain.invoke({ topic: 'quantum computing' });
+console.log(result.text);
+```
+
+## Full Feature List
+
+### Providers
+- **OpenAI** - GPT-4, GPT-4o, GPT-4o-mini, etc.
+- **Ollama** - Local LLMs (Llama3.2, Mistral, etc.)
+
+### Embeddings
+- **OpenAIEmbeddings** - OpenAI text embeddings
+- **GoogleEmbeddings** - Google Gemini embeddings
+- **LocalEmbeddings** - Zero-cost offline embeddings
+
+### Vector Stores
+- **InMemoryVectorStore** - Fast prototyping
+- **ChromaVectorStore** - Production disk persistence
+- **SQLiteVectorStore** - Zero-infrastructure, single file
+
+### Document Loaders
+- **TextLoader** - .txt, .md files
+- **CSVLoader** - CSV with custom delimiters
+- **JSONLoader** - JSON with key extraction
+- Auto-detection of file types
+
+### Chains
+- **LLMChain** - Basic prompt → LLM → output
+- **SequentialChain** - Multi-step pipelines
+- **RetrievalQAChain** - RAG with context
+
+### Smart Routing
+- Auto-route simple queries to cheap models
+- Complex queries to smart models
+
+### Caching
+- **SemanticCache** - Cosine similarity cache hits
+
+### Memory
+- **BufferMemory** - Conversation history
+- **TokenBudgetMemory** - Auto-summarization at limit
+
+### Tools
+- **@tool decorator** - Custom function tools
+- **calculator** - Math expression evaluator
+- **search** - Web search (via Keiro)
+- **weather** - Weather data
+
+### Tracing
+- Built-in observability, no SaaS needed
+
+### Evals
+- **LLMJudge** - Automated response evaluation
+
+### Output Parsers
+- **JSONOutputParser** - Parse JSON from text
+- **XMLOutputParser** - Extract XML tags
+- **CommaSeparatedListParser** - Split lists
+- **MarkdownCodeBlockParser** - Extract code blocks
+
+### Prompt Registry
+- Load prompts from YAML files
+- Version support (@v1, @v2)
+
+### Retrievers
+- **ContextualCompressionRetriever** - Compress docs by context
+- **ParentDocumentRetriever** - Get full docs from chunks
+- **EnsembleRetriever** - Combine multiple retrievers
+- **createVectorStoreRetriever** - Easy vector RAG
+
+## Example: Full RAG Pipeline
+
+```typescript
+import { 
+  OpenAI, 
+  InMemoryVectorStore,
+  TextLoader,
+  CharacterTextSplitter,
+  LLMChain,
+  PromptTemplate,
+  createVectorStoreRetriever
+} from 'lazlo';
+
+// 1. Load documents
+const loader = new TextLoader('./docs.txt');
+const docs = await loader.load();
+
+// 2. Split into chunks
+const splitter = new CharacterTextSplitter({ chunkSize: 1000 });
+const chunks = await splitter.splitDocuments(docs);
+
+// 3. Create vector store
+const embeddings = new OpenAI(); // Uses OpenAI embeddings
+const vectorStore = new InMemoryVectorStore(embeddings);
+await vectorStore.addDocuments(chunks);
+
+// 4. Create retriever
+const retriever = createVectorStoreRetriever(vectorStore);
+
+// 5. Create RAG chain
+const ragChain = new LLMChain({
+  llm: new OpenAI(),
+  prompt: new PromptTemplate('Context: {context}\nQuestion: {question}\nAnswer:'),
+});
+
+// 6. Run with retrieval
+const retrievedDocs = await retriever.getRelevantDocuments('What is Lazlo?');
+const context = retrievedDocs.map(d => d.pageContent).join('\n');
+const result = await ragChain.invoke({ question: 'What is Lazlo?', context });
+```
+
+## Example: Prompt Registry
+
+```typescript
+import { PromptRegistry } from 'lazlo';
+
+const registry = new PromptRegistry('./prompts');
+
+// Register a prompt
+registry.register('rag_qa', {
+  template: 'Context: {context}\nQuestion: {question}',
+  description: 'RAG QA prompt',
+  version: '1.0.0',
+  variables: ['context', 'question'],
+});
+
+// Load with version
+const template = registry.load('rag_qa@v1');
+const formatted = registry.format(template, { context: '...', question: '...' });
+```
+
+## Example: Output Parsing
+
+```typescript
+import { JSONOutputParser } from 'lazlo';
+
+const parser = new JSONOutputParser();
+const result = await parser.parse('{"name": "John", "age": 30}');
+// Returns: { name: "John", age: 30 }
+```
+
+## Example: Ensemble Retrieval
+
+```typescript
+import { 
+  EnsembleRetriever,
+  createVectorStoreRetriever,
+  InMemoryVectorStore 
+} from 'lazlo';
+
+const embeddings = new OpenAI();
+const store1 = new InMemoryVectorStore(embeddings);
+const store2 = new InMemoryVectorStore(embeddings);
+
+// ... add different docs to each store ...
+
+const retriever = new EnsembleRetriever([
+  { retriever: createVectorStoreRetriever(store1), weight: 0.7 },
+  { retriever: createVectorStoreRetriever(store2), weight: 0.3 },
+]);
+```
+
+## Cost Estimation
+
+```typescript
+import { LLMChain, PromptTemplate, OpenAI } from 'lazlo';
+
+const chain = new LLMChain({
+  llm: new OpenAI('gpt-4o'),
+  prompt: new PromptTemplate('Write about {topic}'),
+});
+
+const estimate = chain.estimateCost({ topic: 'AI' });
+console.log(`Estimated cost: $${estimate.estimatedCostUsd}`);
+```
+
+## API Reference
+
+### OpenAI
+
+```typescript
+new OpenAI(apiKey?: string, defaultModel?: string, options?: {
+  temperature?: number,
+  maxTokens?: number,
+  topP?: number,
+})
+```
+
+### Ollama
+
+```typescript
+new Ollama(options?: {
+  model?: string,
+  baseUrl?: string,
+  temperature?: number,
+  numCtx?: number,
+})
+```
+
+### Vector Stores
+
+```typescript
+new InMemoryVectorStore(embeddings)
+new ChromaVectorStore({ embeddings, collectionName?: string })
+new SQLiteVectorStore({ embeddings, dbPath?: string })
+```
+
+### Document Loaders
+
+```typescript
+new TextLoader(filePath: string)
+new CSVLoader(filePath: string, options?: { delimiter?: string })
+new JSONLoader(filePath: string, options?: { key?: string })
+loadDocument(filePath: string): Promise<Document[]>
+```
+
+### Embeddings
+
+```typescript
+new OpenAIEmbeddings(options?: { apiKey?: string, model?: string })
+new GoogleEmbeddings(options?: { apiKey?: string, model?: string })
+new LocalEmbeddings(options?: { dimensions?: number })
+```
+
+## License
+
+MIT

package/dist/cache/semantic.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Semantic Cache - Cache LLM responses with semantic similarity
+ */
+export interface SemanticCacheOptions {
+    threshold?: number;
+}
+export declare class SemanticCache {
+    private store;
+    private threshold;
+    private hits;
+    private misses;
+    private tokensSaved;
+    constructor(options?: SemanticCacheOptions);
+    /**
+     * Look up a cached response
+     */
+    lookup(prompt: string): string | null;
+    /**
+     * Store a response in the cache
+     */
+    put(prompt: string, response: string): void;
+    /**
+     * Wrap an LLM to use caching
+     */
+    wrap<T extends {
+        invoke(prompt: string): Promise<any>;
+    }>(llm: T): T & {
+        invoke(prompt: string): Promise<any>;
+    };
+    /**
+     * Print cache statistics
+     */
+    printStats(): void;
+    /**
+     * Clear the cache
+     */
+    clear(): void;
+}
+//# sourceMappingURL=semantic.d.ts.map

package/dist/cache/semantic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/cache/semantic.ts"],"names":[],"mappings":"AAAA;;GAEG;AA6DH,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,WAAW,CAAK;gBAEZ,OAAO,GAAE,oBAAyB;IAK9C;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA2BrC;;OAEG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM3C;;OAEG;IACH,IAAI,CAAC,CAAC,SAAS;QAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG;QAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;KAAE;IAsB9G;;OAEG;IACH,UAAU,IAAI,IAAI;IAkBlB;;OAEG;IACH,KAAK,IAAI,IAAI;CAOd"}

package/dist/cache/semantic.js

@@ -0,0 +1,134 @@
+/**
+ * Semantic Cache - Cache LLM responses with semantic similarity
+ */
+import { logger } from '../utils/logger.js';
+// ============================================================================
+// Cosine Similarity
+// ============================================================================
+function cosineSimilarity(v1, v2) {
+    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) {
+    const hash = new Map();
+    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 = [];
+    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));
+}
+export class SemanticCache {
+    store = [];
+    threshold;
+    hits = 0;
+    misses = 0;
+    tokensSaved = 0;
+    constructor(options = {}) {
+        this.threshold = options.threshold ?? 0.92;
+        logger.info(`SemanticCache ready. Threshold: ${this.threshold}`);
+    }
+    /**
+     * Look up a cached response
+     */
+    lookup(prompt) {
+        if (this.store.length === 0) {
+            return null;
+        }
+        const queryEmbedding = simpleEmbedding(prompt);
+        let bestScore = 0;
+        let bestResponse = 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, response) {
+        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(llm) {
+        const cache = this;
+        const cachedInvoke = async function (prompt) {
+            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() {
+        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() {
+        this.store = [];
+        this.hits = 0;
+        this.misses = 0;
+        this.tokensSaved = 0;
+        logger.info('SemanticCache cleared.');
+    }
+}
+//# sourceMappingURL=semantic.js.map

package/dist/cache/semantic.js.map

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

package/dist/chains/llmchain.d.ts

@@ -0,0 +1,65 @@
+/**
+ * LLMChain - Simple prompt chaining
+ */
+import { BaseChatModel, ChainInputs, ChainOutputs } from '../core/types.js';
+export declare class PromptTemplate {
+    private template;
+    private inputVariables;
+    constructor(template: string);
+    format(values: Record<string, unknown>): string;
+    get inputVars(): string[];
+}
+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 declare class LLMChain {
+    private llm;
+    private prompt;
+    private outputKey;
+    constructor(options: LLMChainOptions);
+    /**
+     * Estimate cost before running
+     */
+    estimateCost(inputs: ChainInputs, model?: string): CostEstimate;
+    /**
+     * Invoke the chain synchronously
+     */
+    invoke(inputs: ChainInputs): Promise<ChainOutputs>;
+    /**
+     * Stream the response
+     */
+    stream(inputs: ChainInputs): AsyncGenerator<string>;
+    /**
+     * Async invoke
+     */
+    ainvoke(inputs: ChainInputs): Promise<ChainOutputs>;
+    /**
+     * Async stream
+     */
+    astream(inputs: ChainInputs): AsyncGenerator<string>;
+}
+export declare class SequentialChain {
+    private chains;
+    private inputVariables;
+    private outputVariables;
+    constructor(options: {
+        chains: LLMChain[];
+        inputVariables: string[];
+        outputVariables: string[];
+    });
+    invoke(inputs: ChainInputs): Promise<ChainOutputs>;
+}
+//# sourceMappingURL=llmchain.d.ts.map

package/dist/chains/llmchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmchain.d.ts","sourceRoot":"","sources":["../../src/chains/llmchain.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAW,WAAW,EAAE,YAAY,EAAkB,MAAM,kBAAkB,CAAC;AAQrG,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,cAAc,CAAW;gBAErB,QAAQ,EAAE,MAAM;IAQ5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM;IAc/C,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;CACF;AAMD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,aAAa,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,EAAE,eAAe;IAMpC;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY;IAwB/D;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBxD;;OAEG;IACI,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC;IAW1D;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;IAIzD;;OAEG;IACI,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC;CAG5D;AAMD,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,cAAc,CAAW;IACjC,OAAO,CAAC,eAAe,CAAW;gBAEtB,OAAO,EAAE;QACnB,MAAM,EAAE,QAAQ,EAAE,CAAC;QACnB,cAAc,EAAE,MAAM,EAAE,CAAC;QACzB,eAAe,EAAE,MAAM,EAAE,CAAC;KAC3B;IAMK,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC;CAkBzD"}

package/dist/chains/llmchain.js

@@ -0,0 +1,137 @@
+/**
+ * LLMChain - Simple prompt chaining
+ */
+import { logger } from '../utils/logger.js';
+import { getPricing, estimateTokens, calculateCost } from '../utils/pricing.js';
+// ============================================================================
+// Prompt Template
+// ============================================================================
+export class PromptTemplate {
+    template;
+    inputVariables;
+    constructor(template) {
+        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) {
+        // 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() {
+        return this.inputVariables;
+    }
+}
+export class LLMChain {
+    llm;
+    prompt;
+    outputKey;
+    constructor(options) {
+        this.llm = options.llm;
+        this.prompt = options.prompt;
+        this.outputKey = options.outputKey ?? 'text';
+    }
+    /**
+     * Estimate cost before running
+     */
+    estimateCost(inputs, model) {
+        const modelName = model ?? this.llm.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) {
+        const formattedPrompt = this.prompt.format(inputs);
+        logger.debug(`[Chain] Prompt: ${formattedPrompt.slice(0, 100)}...`);
+        const messages = [{ role: 'user', content: formattedPrompt }];
+        const response = await this.llm.invoke(messages);
+        const outputs = {
+            [this.outputKey]: response.content,
+        };
+        // Include usage info if available
+        if (response.usage) {
+            outputs.usage = response.usage;
+            outputs.cost = calculateCost(response.model ?? 'default', response.usage.prompt_tokens, response.usage.completion_tokens);
+        }
+        return outputs;
+    }
+    /**
+     * Stream the response
+     */
+    async *stream(inputs) {
+        const formattedPrompt = this.prompt.format(inputs);
+        logger.debug(`[Chain Stream] Prompt: ${formattedPrompt.slice(0, 100)}...`);
+        const messages = [{ role: 'user', content: formattedPrompt }];
+        for await (const chunk of this.llm.stream?.(messages) ?? []) {
+            yield chunk.delta;
+        }
+    }
+    /**
+     * Async invoke
+     */
+    async ainvoke(inputs) {
+        return this.invoke(inputs);
+    }
+    /**
+     * Async stream
+     */
+    async *astream(inputs) {
+        yield* this.stream(inputs);
+    }
+}
+// ============================================================================
+// Sequential Chain
+// ============================================================================
+export class SequentialChain {
+    chains;
+    inputVariables;
+    outputVariables;
+    constructor(options) {
+        this.chains = options.chains;
+        this.inputVariables = options.inputVariables;
+        this.outputVariables = options.outputVariables;
+    }
+    async invoke(inputs) {
+        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 = {};
+        for (const key of this.outputVariables) {
+            if (key in currentState) {
+                result[key] = currentState[key];
+            }
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=llmchain.js.map

package/dist/chains/llmchain.js.map

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