@opensaas/stack-rag 0.1.7 → 0.3.0

package/dist/config/types.d.ts

@@ -130,6 +130,37 @@ export type CustomStorageConfig = {
  * Vector storage configuration union
  */
 export type VectorStorageConfig = PgVectorStorageConfig | SqliteVssStorageConfig | JsonStorageConfig | CustomStorageConfig;
+/**
+ * Build-time embedding generation configuration
+ */
+export type BuildTimeConfig = {
+    /**
+     * Enable build-time embedding generation
+     */
+    enabled: boolean;
+    /**
+     * Output path for embeddings JSON file
+     * Relative to project root
+     * @default '.embeddings/embeddings.json'
+     */
+    outputPath?: string;
+    /**
+     * Chunk size for text splitting (in characters)
+     * @default 500
+     */
+    chunkSize?: number;
+    /**
+     * Overlap between chunks (in characters)
+     * @default 50
+     */
+    chunkOverlap?: number;
+    /**
+     * Whether to enable differential updates
+     * Only regenerate embeddings for changed content
+     * @default true
+     */
+    differential?: boolean;
+};
 /**
  * Main RAG configuration
  */
@@ -162,6 +193,12 @@ export type RAGConfig = {
      * Can be overridden per field
      */
     chunking?: ChunkingConfig;
+    /**
+     * Build-time embedding generation configuration
+     * When enabled, embeddings are generated at build time and stored in a JSON file
+     * instead of being generated at runtime via hooks
+     */
+    buildTime?: BuildTimeConfig;
     /**
      * Whether to enable MCP tools for semantic search
      * Requires MCP to be enabled in main config
@@ -187,6 +224,7 @@ export type NormalizedRAGConfig = {
     providers: Record<string, EmbeddingProviderConfig>;
     storage: VectorStorageConfig;
     chunking: Required<ChunkingConfig>;
+    buildTime: Required<BuildTimeConfig> | null;
     enableMcpTools: boolean;
     batchSize: number;
     rateLimit: number;
@@ -297,4 +335,101 @@ export type SearchableMetadata = {
      */
     chunking?: ChunkingConfig;
 };
+/**
+ * A chunk of text with its embedding
+ * Used in build-time generation output
+ */
+export type EmbeddingChunk = {
+    /**
+     * The text content of this chunk
+     */
+    text: string;
+    /**
+     * The embedding vector for this chunk
+     */
+    embedding: number[];
+    /**
+     * Metadata about the chunk
+     */
+    metadata: {
+        /**
+         * Index of this chunk within the document
+         */
+        chunkIndex: number;
+        /**
+         * Start character position in original text
+         */
+        startOffset: number;
+        /**
+         * End character position in original text
+         */
+        endOffset: number;
+        /**
+         * Whether this chunk represents a document title
+         * Title chunks receive boosted scoring during search
+         */
+        isTitle?: boolean;
+        /**
+         * Additional custom metadata
+         */
+        [key: string]: unknown;
+    };
+};
+/**
+ * Document with embeddings
+ * Used in build-time generation output
+ */
+export type EmbeddedDocument = {
+    /**
+     * Document ID or slug
+     */
+    id: string;
+    /**
+     * Document title
+     */
+    title?: string;
+    /**
+     * The chunks of this document with embeddings
+     */
+    chunks: EmbeddingChunk[];
+    /**
+     * Embedding metadata
+     */
+    embeddingMetadata: EmbeddingMetadata;
+    /**
+     * When the embeddings were generated
+     */
+    generatedAt: string;
+    /**
+     * Hash of the source content (for differential updates)
+     */
+    contentHash: string;
+};
+/**
+ * Build-time embeddings index file format
+ */
+export type EmbeddingsIndex = {
+    /**
+     * Version of the embeddings format
+     */
+    version: string;
+    /**
+     * Embedding configuration used to generate these embeddings
+     */
+    config: {
+        provider: string;
+        model: string;
+        dimensions: number;
+        chunkSize: number;
+        chunkOverlap: number;
+    };
+    /**
+     * Documents with embeddings
+     */
+    documents: Record<string, EmbeddedDocument>;
+    /**
+     * When the index was generated
+     */
+    generatedAt: string;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

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

package/dist/index.d.ts

@@ -4,5 +4,6 @@
  */
 export { openaiEmbeddings, ollamaEmbeddings, pgvectorStorage, sqliteVssStorage, jsonStorage, } from './config/index.js';
 export { ragPlugin } from './config/plugin.js';
-export type { RAGConfig, NormalizedRAGConfig, EmbeddingProviderConfig, OpenAIEmbeddingConfig, OllamaEmbeddingConfig, VectorStorageConfig, PgVectorStorageConfig, SqliteVssStorageConfig, JsonStorageConfig, ChunkingConfig, ChunkingStrategy, EmbeddingMetadata, StoredEmbedding, SearchResult, } from './config/types.js';
+export type { RAGRuntimeServices } from './runtime/types.js';
+export type { RAGConfig, NormalizedRAGConfig, EmbeddingProviderConfig, OpenAIEmbeddingConfig, OllamaEmbeddingConfig, VectorStorageConfig, PgVectorStorageConfig, SqliteVssStorageConfig, JsonStorageConfig, ChunkingConfig, ChunkingStrategy, EmbeddingMetadata, StoredEmbedding, SearchResult, EmbeddingsIndex, EmbeddedDocument, EmbeddingChunk, } from './config/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,WAAW,GACZ,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,YAAY,GACb,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,WAAW,GACZ,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAG9C,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,YAAY,EACV,SAAS,EACT,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,mBAAmB,CAAA"}

package/dist/providers/openai.js

@@ -14,7 +14,7 @@ async function getOpenAI() {
         const module = await import('openai');
         return module.default;
     }
-    catch (error) {
+    catch {
         throw new Error('OpenAI package not found. Install it with: npm install openai\n' +
             'Make sure to run: pnpm install openai');
     }

package/dist/providers/openai.js.map

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

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"}