@opensaas/stack-rag 0.1.6 → 0.3.0

package/dist/providers/openai.js

@@ -6,6 +6,19 @@ const MODEL_DIMENSIONS = {
     'text-embedding-3-large': 3072,
     'text-embedding-ada-002': 1536,
 };
+/**
+ * Lazily load OpenAI to avoid requiring it at import time
+ */
+async function getOpenAI() {
+    try {
+        const module = await import('openai');
+        return module.default;
+    }
+    catch {
+        throw new Error('OpenAI package not found. Install it with: npm install openai\n' +
+            'Make sure to run: pnpm install openai');
+    }
+}
 /**
  * OpenAI embedding provider
  * Requires the `openai` package to be installed
@@ -14,30 +27,30 @@ export class OpenAIEmbeddingProvider {
     type = 'openai';
     model;
     dimensions;
-    client;
+    client = null;
     config;
+    clientPromise = null;
     constructor(config) {
         this.config = config;
         this.model = config.model || 'text-embedding-3-small';
         this.dimensions = MODEL_DIMENSIONS[this.model] || 1536;
-        // Initialize OpenAI client
-        this.client = this.initializeClient();
     }
-    initializeClient() {
-        try {
-            // eslint-disable-next-line @typescript-eslint/no-require-imports
-            const { OpenAI } = require('openai');
-            return new OpenAI({
-                apiKey: this.config.apiKey,
-                organization: this.config.organization,
-                baseURL: this.config.baseURL,
-            });
-        }
-        catch (error) {
-            throw new Error('OpenAI package not found. Install it with: npm install openai\n' +
-                'Error: ' +
-                error.message);
-        }
+    async ensureClient() {
+        if (this.client)
+            return this.client;
+        if (this.clientPromise)
+            return this.clientPromise;
+        this.clientPromise = this.initializeClient();
+        this.client = await this.clientPromise;
+        return this.client;
+    }
+    async initializeClient() {
+        const OpenAI = await getOpenAI();
+        return new OpenAI({
+            apiKey: this.config.apiKey,
+            organization: this.config.organization,
+            baseURL: this.config.baseURL,
+        });
     }
     /**
      * Generate embedding for a single text
@@ -47,7 +60,8 @@ export class OpenAIEmbeddingProvider {
             throw new Error('Cannot generate embedding for empty text');
         }
         try {
-            const response = await this.client.embeddings.create({
+            const client = await this.ensureClient();
+            const response = await client.embeddings.create({
                 model: this.model,
                 input: text,
                 encoding_format: 'float',
@@ -79,7 +93,8 @@ export class OpenAIEmbeddingProvider {
         }
         try {
             // OpenAI supports batch embedding
-            const response = await this.client.embeddings.create({
+            const client = await this.ensureClient();
+            const response = await client.embeddings.create({
                 model: this.model,
                 input: validTexts,
                 encoding_format: 'float',

package/dist/providers/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,gBAAgB,GAAyC;IAC7D,wBAAwB,EAAE,IAAI;IAC9B,wBAAwB,EAAE,IAAI;IAC9B,wBAAwB,EAAE,IAAI;CAC/B,CAAA;AAiBD;;;GAGG;AACH,MAAM,OAAO,uBAAuB;IACzB,IAAI,GAAG,QAAQ,CAAA;IACf,KAAK,CAAQ;IACb,UAAU,CAAQ;IAEnB,MAAM,CAAc;IACpB,MAAM,CAAuB;IAErC,YAAY,MAA6B;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,wBAAwB,CAAA;QACrD,IAAI,CAAC,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,KAA6B,CAAC,IAAI,IAAI,CAAA;QAE9E,2BAA2B;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAA;IACvC,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC;YACH,iEAAiE;YACjE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;YAEpC,OAAO,IAAI,MAAM,CAAC;gBAChB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;gBAC1B,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;gBACtC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;aAC7B,CAAiB,CAAA;QACpB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,iEAAiE;gBAC/D,SAAS;gBACR,KAAe,CAAC,OAAO,CAC3B,CAAA;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;QAC7D,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;gBACnD,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,IAAI;gBACX,eAAe,EAAE,OAAO;aACzB,CAAC,CAAA;YAEF,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,uCAAwC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAA;QACpF,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAO,EAAE,CAAA;QACX,CAAC;QAED,mDAAmD;QACnD,MAAM,UAAU,GAAa,EAAE,CAAA;QAC/B,MAAM,YAAY,GAAa,EAAE,CAAA;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YAC5B,IAAI,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACnC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACrB,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAC1B,CAAC;QACH,CAAC,CAAC,CAAA;QAEF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAA;QACnE,CAAC;QAED,IAAI,CAAC;YACH,kCAAkC;YAClC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC;gBACnD,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,UAAU;gBACjB,eAAe,EAAE,OAAO;aACzB,CAAC,CAAA;YAEF,wCAAwC;YACxC,MAAM,OAAO,GAAe,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;YAEnD,qCAAqC;YACrC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAA6B,EAAE,CAAS,EAAE,EAAE;gBACjE,MAAM,aAAa,GAAG,YAAY,CAAC,CAAC,CAAC,CAAA;gBACrC,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,SAAS,CAAA;YACzC,CAAC,CAAC,CAAA;YAEF,yCAAyC;YACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChB,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;gBACjD,CAAC;YACH,CAAC;YAED,OAAO,OAAO,CAAA;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,6CAA8C,KAAe,CAAC,OAAO,EAAE,CAAC,CAAA;QAC1F,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA6B;IAChE,OAAO,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAA;AAC5C,CAAC"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"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"}

package/dist/runtime/batch.test.js

@@ -200,7 +200,7 @@ describe('ProcessingQueue', () => {
         // With concurrency 3, should be faster than sequential
         // 5 items with 10ms each sequentially = 50ms
         // With concurrency 3: ceil(5/3) * 10ms = 20ms
-        expect(duration).toBeLessThan(40);
+        expect(duration).toBeLessThan(50);
     });
     it('should track queue size', async () => {
         const queue = new ProcessingQueue(async (item) => {

package/dist/runtime/build-time.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Build-time utilities for generating and managing embeddings
+ * Used by CLI tools and custom build scripts
+ */
+import type { EmbeddingProvider } from '../providers/types.js';
+import type { EmbeddingsIndex, EmbeddedDocument } from '../config/types.js';
+/**
+ * Simple character-based text chunking for build-time generation
+ *
+ * Simpler than the runtime chunking strategies, optimized for build-time batch processing.
+ * Splits text into fixed-size chunks with overlap.
+ *
+ * @param text - Text to chunk
+ * @param chunkSize - Size of each chunk in characters
+ * @param overlap - Overlap between chunks in characters
+ * @returns Array of text chunks
+ *
+ * @example
+ * ```typescript
+ * import { simpleChunkText } from '@opensaas/stack-rag/runtime'
+ *
+ * const chunks = simpleChunkText("Long document...", 500, 50)
+ * ```
+ */
+export declare function simpleChunkText(text: string, chunkSize: number, overlap: number): string[];
+/**
+ * Compute SHA256 hash of content for change detection
+ *
+ * @param content - Content to hash
+ * @returns Hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * import { hashContent } from '@opensaas/stack-rag/runtime'
+ *
+ * const hash = hashContent("document content")
+ * ```
+ */
+export declare function hashContent(content: string): string;
+/**
+ * Load existing embeddings index from file
+ *
+ * Used for differential updates - only regenerate embeddings for changed content.
+ *
+ * @param filePath - Path to embeddings JSON file
+ * @returns Loaded index or null if file doesn't exist or can't be loaded
+ *
+ * @example
+ * ```typescript
+ * import { loadExistingIndex } from '@opensaas/stack-rag/runtime'
+ *
+ * const existing = loadExistingIndex('.embeddings/docs.json')
+ * if (existing) {
+ *   console.log(`Found ${Object.keys(existing.documents).length} existing documents`)
+ * }
+ * ```
+ */
+export declare function loadExistingIndex(filePath: string): EmbeddingsIndex | null;
+/**
+ * Generate embeddings for a document with chunking
+ *
+ * Main utility for build-time embedding generation. Chunks the document,
+ * generates embeddings for each chunk, and returns a complete EmbeddedDocument.
+ *
+ * @param documentId - Unique identifier for the document
+ * @param content - Document content (plain text)
+ * @param provider - Embedding provider instance
+ * @param options - Generation options
+ * @returns Complete embedded document ready to be added to index
+ *
+ * @example
+ * ```typescript
+ * import { generateDocumentEmbeddings } from '@opensaas/stack-rag/runtime'
+ * import { createEmbeddingProvider } from '@opensaas/stack-rag/providers'
+ *
+ * const provider = createEmbeddingProvider({
+ *   type: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY
+ * })
+ *
+ * const doc = await generateDocumentEmbeddings(
+ *   'docs/getting-started',
+ *   'Document content here...',
+ *   provider,
+ *   {
+ *     title: 'Getting Started',
+ *     chunkSize: 500,
+ *     chunkOverlap: 50,
+ *     metadata: { section: 'guides' }
+ *   }
+ * )
+ * ```
+ */
+export declare function generateDocumentEmbeddings(documentId: string, content: string, provider: EmbeddingProvider, options: {
+    title?: string;
+    chunkSize: number;
+    chunkOverlap: number;
+    metadata?: Record<string, unknown>;
+}): Promise<EmbeddedDocument>;
+//# sourceMappingURL=build-time.d.ts.map

package/dist/runtime/build-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-time.d.ts","sourceRoot":"","sources":["../../src/runtime/build-time.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAkB,MAAM,oBAAoB,CAAA;AAE3F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAW1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAY1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE;IACP,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GACA,OAAO,CAAC,gBAAgB,CAAC,CAgF3B"}

package/dist/runtime/build-time.js

@@ -0,0 +1,185 @@
+/**
+ * Build-time utilities for generating and managing embeddings
+ * Used by CLI tools and custom build scripts
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+/**
+ * Simple character-based text chunking for build-time generation
+ *
+ * Simpler than the runtime chunking strategies, optimized for build-time batch processing.
+ * Splits text into fixed-size chunks with overlap.
+ *
+ * @param text - Text to chunk
+ * @param chunkSize - Size of each chunk in characters
+ * @param overlap - Overlap between chunks in characters
+ * @returns Array of text chunks
+ *
+ * @example
+ * ```typescript
+ * import { simpleChunkText } from '@opensaas/stack-rag/runtime'
+ *
+ * const chunks = simpleChunkText("Long document...", 500, 50)
+ * ```
+ */
+export function simpleChunkText(text, chunkSize, overlap) {
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        const end = Math.min(start + chunkSize, text.length);
+        chunks.push(text.slice(start, end));
+        start += chunkSize - overlap;
+    }
+    return chunks;
+}
+/**
+ * Compute SHA256 hash of content for change detection
+ *
+ * @param content - Content to hash
+ * @returns Hexadecimal hash string
+ *
+ * @example
+ * ```typescript
+ * import { hashContent } from '@opensaas/stack-rag/runtime'
+ *
+ * const hash = hashContent("document content")
+ * ```
+ */
+export function hashContent(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Load existing embeddings index from file
+ *
+ * Used for differential updates - only regenerate embeddings for changed content.
+ *
+ * @param filePath - Path to embeddings JSON file
+ * @returns Loaded index or null if file doesn't exist or can't be loaded
+ *
+ * @example
+ * ```typescript
+ * import { loadExistingIndex } from '@opensaas/stack-rag/runtime'
+ *
+ * const existing = loadExistingIndex('.embeddings/docs.json')
+ * if (existing) {
+ *   console.log(`Found ${Object.keys(existing.documents).length} existing documents`)
+ * }
+ * ```
+ */
+export function loadExistingIndex(filePath) {
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        console.warn(`Warning: Could not load existing embeddings from ${filePath}`);
+        return null;
+    }
+}
+/**
+ * Generate embeddings for a document with chunking
+ *
+ * Main utility for build-time embedding generation. Chunks the document,
+ * generates embeddings for each chunk, and returns a complete EmbeddedDocument.
+ *
+ * @param documentId - Unique identifier for the document
+ * @param content - Document content (plain text)
+ * @param provider - Embedding provider instance
+ * @param options - Generation options
+ * @returns Complete embedded document ready to be added to index
+ *
+ * @example
+ * ```typescript
+ * import { generateDocumentEmbeddings } from '@opensaas/stack-rag/runtime'
+ * import { createEmbeddingProvider } from '@opensaas/stack-rag/providers'
+ *
+ * const provider = createEmbeddingProvider({
+ *   type: 'openai',
+ *   apiKey: process.env.OPENAI_API_KEY
+ * })
+ *
+ * const doc = await generateDocumentEmbeddings(
+ *   'docs/getting-started',
+ *   'Document content here...',
+ *   provider,
+ *   {
+ *     title: 'Getting Started',
+ *     chunkSize: 500,
+ *     chunkOverlap: 50,
+ *     metadata: { section: 'guides' }
+ *   }
+ * )
+ * ```
+ */
+export async function generateDocumentEmbeddings(documentId, content, provider, options) {
+    const { title, chunkSize, chunkOverlap, metadata = {} } = options;
+    // Hash content for differential updates
+    const contentHash = hashContent(content);
+    // Prepare all text chunks to embed
+    const allTextChunks = [];
+    const chunkTypes = [];
+    // Add title chunk first if title exists
+    if (title) {
+        allTextChunks.push(title);
+        chunkTypes.push('title');
+    }
+    // Chunk the content
+    const contentChunks = simpleChunkText(content, chunkSize, chunkOverlap);
+    allTextChunks.push(...contentChunks);
+    contentChunks.forEach(() => chunkTypes.push('content'));
+    // Generate embeddings in batch for all chunks
+    const allEmbeddings = await provider.embedBatch(allTextChunks);
+    // Build chunks with embeddings
+    const chunks = [];
+    let embeddingIndex = 0;
+    let contentChunkIndex = 0;
+    for (let i = 0; i < chunkTypes.length; i++) {
+        const type = chunkTypes[i];
+        if (type === 'title') {
+            // Title chunk
+            chunks.push({
+                text: allTextChunks[embeddingIndex],
+                embedding: allEmbeddings[embeddingIndex],
+                metadata: {
+                    chunkIndex: -1, // Special index for title
+                    startOffset: 0,
+                    endOffset: 0,
+                    isTitle: true,
+                    ...metadata,
+                },
+            });
+        }
+        else {
+            // Content chunk
+            chunks.push({
+                text: allTextChunks[embeddingIndex],
+                embedding: allEmbeddings[embeddingIndex],
+                metadata: {
+                    chunkIndex: contentChunkIndex,
+                    startOffset: contentChunkIndex * (chunkSize - chunkOverlap),
+                    endOffset: Math.min((contentChunkIndex + 1) * chunkSize - contentChunkIndex * chunkOverlap, content.length),
+                    ...metadata,
+                },
+            });
+            contentChunkIndex++;
+        }
+        embeddingIndex++;
+    }
+    return {
+        id: documentId,
+        title,
+        chunks,
+        embeddingMetadata: {
+            model: provider.model,
+            provider: provider.type,
+            dimensions: provider.dimensions,
+            generatedAt: new Date().toISOString(),
+        },
+        generatedAt: new Date().toISOString(),
+        contentHash,
+    };
+}
+//# sourceMappingURL=build-time.js.map

package/dist/runtime/build-time.js.map

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

package/dist/runtime/index.d.ts

@@ -11,4 +11,7 @@ export { chunkText, estimateTokenCount, mergeSmallChunks, type ChunkingStrategy,
 export { generateEmbedding, generateEmbeddings, shouldRegenerateEmbedding, hashText, validateEmbeddingDimensions, mergeEmbeddings, type GenerateEmbeddingOptions, type GenerateEmbeddingsOptions, type ChunkedEmbedding, } from './embeddings.js';
 export { semanticSearch, findSimilar, type SemanticSearchOptions, type FindSimilarOptions, } from './search.js';
 export { batchProcess, RateLimiter, ProcessingQueue, type BatchProcessOptions, type BatchProgress, type BatchError, type BatchProcessResult, } from './batch.js';
+export { simpleChunkText, hashContent, loadExistingIndex, generateDocumentEmbeddings, } from './build-time.js';
+export { stripMarkdown, extractMarkdownText } from './markdown.js';
+export { createProviderFromEnv, getProviderConfigFromEnv, type ProviderType, } from './provider-helpers.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,QAAQ,EACR,2BAA2B,EAC3B,eAAe,EACf,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EACL,cAAc,EACd,WAAW,EACX,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,QAAQ,EACR,2BAA2B,EAC3B,eAAe,EACf,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EACL,cAAc,EACd,WAAW,EACX,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAA;AAGnB,OAAO,EACL,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAGlE,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAA"}

package/dist/runtime/index.js

@@ -15,4 +15,10 @@ export { generateEmbedding, generateEmbeddings, shouldRegenerateEmbedding, hashT
 export { semanticSearch, findSimilar, } from './search.js';
 // Batch processing
 export { batchProcess, RateLimiter, ProcessingQueue, } from './batch.js';
+// Build-time utilities
+export { simpleChunkText, hashContent, loadExistingIndex, generateDocumentEmbeddings, } from './build-time.js';
+// Markdown processing
+export { stripMarkdown, extractMarkdownText } from './markdown.js';
+// Provider helpers
+export { createProviderFromEnv, getProviderConfigFromEnv, } from './provider-helpers.js';
 //# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gBAAgB;AAChB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,eAAe,CAAA;AAEtB,uBAAuB;AACvB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,QAAQ,EACR,2BAA2B,EAC3B,eAAe,GAIhB,MAAM,iBAAiB,CAAA;AAExB,kBAAkB;AAClB,OAAO,EACL,cAAc,EACd,WAAW,GAGZ,MAAM,aAAa,CAAA;AAEpB,mBAAmB;AACnB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,eAAe,GAKhB,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gBAAgB;AAChB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,gBAAgB,GAIjB,MAAM,eAAe,CAAA;AAEtB,uBAAuB;AACvB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,QAAQ,EACR,2BAA2B,EAC3B,eAAe,GAIhB,MAAM,iBAAiB,CAAA;AAExB,kBAAkB;AAClB,OAAO,EACL,cAAc,EACd,WAAW,GAGZ,MAAM,aAAa,CAAA;AAEpB,mBAAmB;AACnB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,eAAe,GAKhB,MAAM,YAAY,CAAA;AAEnB,uBAAuB;AACvB,OAAO,EACL,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,iBAAiB,CAAA;AAExB,sBAAsB;AACtB,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAElE,mBAAmB;AACnB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GAEzB,MAAM,uBAAuB,CAAA"}

package/dist/runtime/markdown.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Markdown processing utilities for content preparation
+ */
+/**
+ * Strip markdown formatting for cleaner text suitable for embeddings
+ *
+ * Removes code blocks, formatting markers, links, images, and HTML tags
+ * while preserving the actual content.
+ *
+ * @param markdown - Markdown text to process
+ * @returns Plain text with markdown removed
+ *
+ * @example
+ * ```typescript
+ * import { stripMarkdown } from '@opensaas/stack-rag/runtime'
+ *
+ * const markdown = '# Hello\n\nThis is **bold** text with a [link](url).'
+ * const plain = stripMarkdown(markdown)
+ * // Returns: 'Hello\n\nThis is bold text with a link.'
+ * ```
+ */
+export declare function stripMarkdown(markdown: string): string;
+/**
+ * Extract text content from common markdown structures
+ *
+ * More aggressive than stripMarkdown - extracts only text content,
+ * removes all structural elements.
+ *
+ * @param markdown - Markdown text
+ * @returns Extracted plain text
+ */
+export declare function extractMarkdownText(markdown: string): string;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/runtime/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/runtime/markdown.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8BtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuD5D"}

package/dist/runtime/markdown.js

@@ -0,0 +1,94 @@
+/**
+ * Markdown processing utilities for content preparation
+ */
+/**
+ * Strip markdown formatting for cleaner text suitable for embeddings
+ *
+ * Removes code blocks, formatting markers, links, images, and HTML tags
+ * while preserving the actual content.
+ *
+ * @param markdown - Markdown text to process
+ * @returns Plain text with markdown removed
+ *
+ * @example
+ * ```typescript
+ * import { stripMarkdown } from '@opensaas/stack-rag/runtime'
+ *
+ * const markdown = '# Hello\n\nThis is **bold** text with a [link](url).'
+ * const plain = stripMarkdown(markdown)
+ * // Returns: 'Hello\n\nThis is bold text with a link.'
+ * ```
+ */
+export function stripMarkdown(markdown) {
+    let text = markdown;
+    // Remove code blocks
+    text = text.replace(/```[\s\S]*?```/g, '');
+    text = text.replace(/`[^`]+`/g, '');
+    // Remove headings markers but keep text
+    text = text.replace(/^#+\s+/gm, '');
+    // Remove bold/italic markers
+    text = text.replace(/\*\*([^*]+)\*\*/g, '$1');
+    text = text.replace(/\*([^*]+)\*/g, '$1');
+    text = text.replace(/__([^_]+)__/g, '$1');
+    text = text.replace(/_([^_]+)_/g, '$1');
+    // Remove links but keep text
+    text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+    // Remove images
+    text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, '');
+    // Remove HTML tags
+    text = text.replace(/<[^>]+>/g, '');
+    // Normalize whitespace
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text.replace(/[ \t]+/g, ' ');
+    return text.trim();
+}
+/**
+ * Extract text content from common markdown structures
+ *
+ * More aggressive than stripMarkdown - extracts only text content,
+ * removes all structural elements.
+ *
+ * @param markdown - Markdown text
+ * @returns Extracted plain text
+ */
+export function extractMarkdownText(markdown) {
+    let text = markdown;
+    // Remove YAML frontmatter
+    text = text.replace(/^---[\s\S]*?---\n/m, '');
+    // Remove code blocks entirely (including content)
+    text = text.replace(/```[\s\S]*?```/g, '');
+    // Remove inline code
+    text = text.replace(/`[^`]+`/g, '');
+    // Remove horizontal rules
+    text = text.replace(/^[-*_]{3,}$/gm, '');
+    // Remove blockquotes markers
+    text = text.replace(/^>\s+/gm, '');
+    // Remove list markers
+    text = text.replace(/^[\s]*[-*+]\s+/gm, '');
+    text = text.replace(/^[\s]*\d+\.\s+/gm, '');
+    // Remove headings markers
+    text = text.replace(/^#+\s+/gm, '');
+    // Remove emphasis markers
+    text = text.replace(/\*\*([^*]+)\*\*/g, '$1');
+    text = text.replace(/\*([^*]+)\*/g, '$1');
+    text = text.replace(/__([^_]+)__/g, '$1');
+    text = text.replace(/_([^_]+)_/g, '$1');
+    // Remove strikethrough
+    text = text.replace(/~~([^~]+)~~/g, '$1');
+    // Remove links but keep text
+    text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+    // Remove reference-style links
+    text = text.replace(/\[([^\]]+)\]\[[^\]]*\]/g, '$1');
+    // Remove images
+    text = text.replace(/!\[([^\]]*)\]\([^)]+\)/g, '');
+    // Remove HTML tags
+    text = text.replace(/<[^>]+>/g, '');
+    // Remove HTML entities
+    text = text.replace(/&[a-z]+;/gi, '');
+    // Normalize whitespace
+    text = text.replace(/\n{3,}/g, '\n\n');
+    text = text.replace(/[ \t]+/g, ' ');
+    text = text.replace(/^\s+|\s+$/gm, '');
+    return text.trim();
+}
+//# sourceMappingURL=markdown.js.map

package/dist/runtime/markdown.js.map

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

package/dist/runtime/provider-helpers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Helper utilities for working with embedding providers
+ * Simplifies provider creation from environment variables
+ */
+import type { EmbeddingProvider } from '../providers/types.js';
+import type { EmbeddingProviderConfig } from '../config/types.js';
+import 'dotenv/config';
+/**
+ * Provider type from environment or configuration
+ */
+export type ProviderType = 'openai' | 'ollama';
+/**
+ * Create an embedding provider from environment variables
+ *
+ * Reads configuration from environment variables:
+ * - EMBEDDING_PROVIDER: 'openai' or 'ollama' (default: 'openai')
+ * - OPENAI_API_KEY: Required if using OpenAI
+ * - OLLAMA_BASE_URL: Ollama endpoint (default: 'http://localhost:11434')
+ *
+ * @param overrides - Optional overrides for environment config
+ * @returns Configured embedding provider
+ *
+ * @example
+ * ```typescript
+ * import { createProviderFromEnv } from '@opensaas/stack-rag/runtime'
+ *
+ * // Uses EMBEDDING_PROVIDER and OPENAI_API_KEY from env
+ * const provider = createProviderFromEnv()
+ *
+ * // Override provider type
+ * const ollamaProvider = createProviderFromEnv({ provider: 'ollama' })
+ * ```
+ */
+export declare function createProviderFromEnv(overrides?: {
+    provider?: ProviderType;
+    openaiApiKey?: string;
+    ollamaBaseUrl?: string;
+    model?: string;
+}): EmbeddingProvider;
+/**
+ * Get provider configuration from environment
+ *
+ * Useful for inspecting what provider would be used without creating it.
+ *
+ * @returns Provider configuration object
+ *
+ * @example
+ * ```typescript
+ * import { getProviderConfigFromEnv } from '@opensaas/stack-rag/runtime'
+ *
+ * const config = getProviderConfigFromEnv()
+ * console.log(`Using ${config.type} provider`)
+ * ```
+ */
+export declare function getProviderConfigFromEnv(): EmbeddingProviderConfig;
+//# sourceMappingURL=provider-helpers.d.ts.map

package/dist/runtime/provider-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-helpers.d.ts","sourceRoot":"","sources":["../../src/runtime/provider-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,eAAe,CAAA;AAEtB;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE;IAChD,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,GAAG,iBAAiB,CA+BpB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,IAAI,uBAAuB,CAwBlE"}