@opensaas/stack-rag 0.1.6

package/dist/config/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * RAG (Retrieval-Augmented Generation) configuration types
+ */
+/**
+ * Text chunking strategies for splitting documents
+ */
+export type ChunkingStrategy = 'none' | 'recursive' | 'sentence' | 'sliding-window';
+/**
+ * Chunking configuration options
+ */
+export type ChunkingConfig = {
+    /**
+     * Chunking strategy to use
+     * @default 'recursive'
+     */
+    strategy?: ChunkingStrategy;
+    /**
+     * Maximum tokens per chunk
+     * @default 500
+     */
+    maxTokens?: number;
+    /**
+     * Overlap between chunks (tokens)
+     * Only applies to 'recursive' and 'sliding-window' strategies
+     * @default 50
+     */
+    overlap?: number;
+};
+/**
+ * Embedding provider names
+ */
+export type EmbeddingProviderName = 'openai' | 'ollama' | string;
+/**
+ * OpenAI embedding model options
+ */
+export type OpenAIEmbeddingModel = 'text-embedding-3-small' | 'text-embedding-3-large' | 'text-embedding-ada-002';
+/**
+ * OpenAI embedding provider configuration
+ */
+export type OpenAIEmbeddingConfig = {
+    type: 'openai';
+    /**
+     * OpenAI API key
+     */
+    apiKey: string;
+    /**
+     * Model to use for embeddings
+     * @default 'text-embedding-3-small'
+     */
+    model?: OpenAIEmbeddingModel;
+    /**
+     * Organization ID (optional)
+     */
+    organization?: string;
+    /**
+     * Base URL for API requests (optional, for Azure or custom endpoints)
+     */
+    baseURL?: string;
+};
+/**
+ * Ollama embedding provider configuration
+ */
+export type OllamaEmbeddingConfig = {
+    type: 'ollama';
+    /**
+     * Ollama API endpoint
+     * @default 'http://localhost:11434'
+     */
+    baseURL?: string;
+    /**
+     * Model to use for embeddings
+     * @default 'nomic-embed-text'
+     */
+    model?: string;
+};
+/**
+ * Generic embedding provider configuration
+ * For custom or third-party providers
+ */
+export type CustomEmbeddingConfig = {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Embedding provider configuration union
+ */
+export type EmbeddingProviderConfig = OpenAIEmbeddingConfig | OllamaEmbeddingConfig | CustomEmbeddingConfig;
+/**
+ * Vector storage backend types
+ */
+export type VectorStorageBackend = 'pgvector' | 'sqlite-vss' | 'json' | string;
+/**
+ * pgvector storage configuration
+ */
+export type PgVectorStorageConfig = {
+    type: 'pgvector';
+    /**
+     * Distance function for similarity search
+     * @default 'cosine'
+     */
+    distanceFunction?: 'cosine' | 'l2' | 'inner_product';
+};
+/**
+ * SQLite VSS storage configuration
+ */
+export type SqliteVssStorageConfig = {
+    type: 'sqlite-vss';
+    /**
+     * Distance function for similarity search
+     * @default 'cosine'
+     */
+    distanceFunction?: 'cosine' | 'l2';
+};
+/**
+ * JSON-based storage (in-memory search)
+ * Stores vectors as JSON and uses JavaScript for similarity search
+ * Good for development and small datasets
+ */
+export type JsonStorageConfig = {
+    type: 'json';
+};
+/**
+ * Generic storage configuration for custom backends
+ */
+export type CustomStorageConfig = {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Vector storage configuration union
+ */
+export type VectorStorageConfig = PgVectorStorageConfig | SqliteVssStorageConfig | JsonStorageConfig | CustomStorageConfig;
+/**
+ * Main RAG configuration
+ */
+export type RAGConfig = {
+    /**
+     * Default embedding provider
+     * Can be overridden per field
+     */
+    provider?: EmbeddingProviderConfig;
+    /**
+     * Named embedding providers
+     * Allows using different providers for different fields
+     *
+     * @example
+     * ```typescript
+     * providers: {
+     *   openai: openaiEmbeddings({ apiKey: '...' }),
+     *   ollama: ollamaEmbeddings({ model: 'nomic-embed-text' })
+     * }
+     * ```
+     */
+    providers?: Record<string, EmbeddingProviderConfig>;
+    /**
+     * Vector storage backend
+     * @default { type: 'json' }
+     */
+    storage?: VectorStorageConfig;
+    /**
+     * Default chunking configuration
+     * Can be overridden per field
+     */
+    chunking?: ChunkingConfig;
+    /**
+     * Whether to enable MCP tools for semantic search
+     * Requires MCP to be enabled in main config
+     * @default true
+     */
+    enableMcpTools?: boolean;
+    /**
+     * Batch size for embedding generation
+     * @default 10
+     */
+    batchSize?: number;
+    /**
+     * Rate limit (requests per minute) for embedding API calls
+     * @default 100
+     */
+    rateLimit?: number;
+};
+/**
+ * Normalized RAG configuration with defaults applied
+ */
+export type NormalizedRAGConfig = {
+    provider: EmbeddingProviderConfig | null;
+    providers: Record<string, EmbeddingProviderConfig>;
+    storage: VectorStorageConfig;
+    chunking: Required<ChunkingConfig>;
+    enableMcpTools: boolean;
+    batchSize: number;
+    rateLimit: number;
+};
+/**
+ * Embedding metadata stored alongside vectors
+ */
+export type EmbeddingMetadata = {
+    /**
+     * Embedding model used
+     */
+    model: string;
+    /**
+     * Provider type (openai, ollama, etc.)
+     */
+    provider: string;
+    /**
+     * Vector dimensions
+     */
+    dimensions: number;
+    /**
+     * When the embedding was generated
+     */
+    generatedAt: string;
+    /**
+     * Hash of source text (for detecting changes)
+     */
+    sourceHash?: string;
+};
+/**
+ * Stored embedding with vector and metadata
+ */
+export type StoredEmbedding = {
+    /**
+     * The embedding vector
+     */
+    vector: number[];
+    /**
+     * Metadata about the embedding
+     */
+    metadata: EmbeddingMetadata;
+};
+/**
+ * Semantic search result
+ */
+export type SearchResult<T = unknown> = {
+    /**
+     * The matching item
+     */
+    item: T;
+    /**
+     * Similarity score (0-1, higher is more similar)
+     */
+    score: number;
+    /**
+     * Distance metric (depends on storage backend)
+     */
+    distance: number;
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/config/types.js

@@ -0,0 +1,5 @@
+/**
+ * RAG (Retrieval-Augmented Generation) configuration types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/fields/embedding.d.ts

@@ -0,0 +1,85 @@
+import type { BaseFieldConfig } from '@opensaas/stack-core';
+import type { StoredEmbedding, EmbeddingProviderName, ChunkingConfig } from '../config/types.js';
+/**
+ * Embedding field configuration
+ * Stores vector embeddings as JSON with metadata
+ */
+export type EmbeddingField = BaseFieldConfig<StoredEmbedding | null, StoredEmbedding | null> & {
+    type: 'embedding';
+    /**
+     * Source field name to generate embeddings from
+     * When this field changes, embeddings will be automatically regenerated
+     *
+     * @example 'content' or 'title'
+     */
+    sourceField?: string;
+    /**
+     * Embedding provider to use
+     * References a provider name from RAG config
+     * Falls back to default provider if not specified
+     *
+     * @example 'openai' or 'ollama'
+     */
+    provider?: EmbeddingProviderName;
+    /**
+     * Vector dimensions
+     * Must match the provider's output dimensions
+     * @default 1536 (OpenAI text-embedding-3-small)
+     */
+    dimensions?: number;
+    /**
+     * Chunking configuration for long texts
+     * Only applies if sourceField is set
+     */
+    chunking?: ChunkingConfig;
+    /**
+     * Whether to automatically generate embeddings
+     * @default true if sourceField is set
+     */
+    autoGenerate?: boolean;
+    /**
+     * UI configuration
+     */
+    ui?: {
+        /**
+         * Whether to show the embedding vector in the UI
+         * @default false (usually too large to display)
+         */
+        showVector?: boolean;
+        /**
+         * Whether to show embedding metadata
+         * @default true
+         */
+        showMetadata?: boolean;
+    };
+};
+/**
+ * Embedding field builder
+ * Creates a field that stores vector embeddings with metadata
+ *
+ * @example
+ * ```typescript
+ * import { embedding } from '@opensaas/stack-rag/fields'
+ *
+ * // Manual embedding storage
+ * fields: {
+ *   embedding: embedding({
+ *     dimensions: 1536,
+ *     provider: 'openai'
+ *   })
+ * }
+ *
+ * // Automatic embedding generation from source field
+ * fields: {
+ *   content: text(),
+ *   contentEmbedding: embedding({
+ *     sourceField: 'content',
+ *     provider: 'openai',
+ *     dimensions: 1536,
+ *     autoGenerate: true
+ *   })
+ * }
+ * ```
+ */
+export declare function embedding(options?: Omit<EmbeddingField, 'type'>): EmbeddingField;
+//# sourceMappingURL=embedding.d.ts.map

package/dist/fields/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../src/fields/embedding.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAEhG;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC,eAAe,GAAG,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC,GAAG;IAC7F,IAAI,EAAE,WAAW,CAAA;IAEjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAA;IAEhC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;IAEzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IAEtB;;OAEG;IACH,EAAE,CAAC,EAAE;QACH;;;WAGG;QACH,UAAU,CAAC,EAAE,OAAO,CAAA;QAEpB;;;WAGG;QACH,YAAY,CAAC,EAAE,OAAO,CAAA;KACvB,CAAA;CACF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,cAAc,CAwDhF"}

package/dist/fields/embedding.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+/**
+ * Embedding field builder
+ * Creates a field that stores vector embeddings with metadata
+ *
+ * @example
+ * ```typescript
+ * import { embedding } from '@opensaas/stack-rag/fields'
+ *
+ * // Manual embedding storage
+ * fields: {
+ *   embedding: embedding({
+ *     dimensions: 1536,
+ *     provider: 'openai'
+ *   })
+ * }
+ *
+ * // Automatic embedding generation from source field
+ * fields: {
+ *   content: text(),
+ *   contentEmbedding: embedding({
+ *     sourceField: 'content',
+ *     provider: 'openai',
+ *     dimensions: 1536,
+ *     autoGenerate: true
+ *   })
+ * }
+ * ```
+ */
+export function embedding(options) {
+    const dimensions = options?.dimensions || 1536;
+    const autoGenerate = options?.autoGenerate ?? options?.sourceField != null;
+    return {
+        type: 'embedding',
+        ...options,
+        dimensions,
+        autoGenerate,
+        getZodSchema: (_fieldName, _operation) => {
+            // Embedding schema validation
+            const embeddingSchema = z.object({
+                vector: z.array(z.number()).length(dimensions, {
+                    message: `Embedding vector must have exactly ${dimensions} dimensions`,
+                }),
+                metadata: z.object({
+                    model: z.string(),
+                    provider: z.string(),
+                    dimensions: z.number(),
+                    generatedAt: z.string(),
+                    sourceHash: z.string().optional(),
+                }),
+            });
+            // Embeddings are always optional in input
+            // They are generated automatically via hooks if sourceField is set
+            return embeddingSchema.nullable().optional();
+        },
+        getPrismaType: (_fieldName) => {
+            // Store as JSON in database
+            // For pgvector, we could use vector() type, but JSON is more portable
+            return {
+                type: 'Json',
+                modifiers: '?', // Always optional
+            };
+        },
+        getTypeScriptType: () => {
+            return {
+                type: 'StoredEmbedding | null',
+                optional: true,
+            };
+        },
+        getTypeScriptImports: () => {
+            return [
+                {
+                    names: ['StoredEmbedding'],
+                    from: '@opensaas/stack-rag',
+                    typeOnly: true,
+                },
+            ];
+        },
+    };
+}
+//# sourceMappingURL=embedding.js.map

package/dist/fields/embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/fields/embedding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAiEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,SAAS,CAAC,OAAsC;IAC9D,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,IAAI,CAAA;IAC9C,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,OAAO,EAAE,WAAW,IAAI,IAAI,CAAA;IAE1E,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,GAAG,OAAO;QACV,UAAU;QACV,YAAY;QAEZ,YAAY,EAAE,CAAC,UAAkB,EAAE,UAA+B,EAAE,EAAE;YACpE,8BAA8B;YAC9B,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;gBAC/B,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE;oBAC7C,OAAO,EAAE,sCAAsC,UAAU,aAAa;iBACvE,CAAC;gBACF,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;oBACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;oBACjB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;oBACpB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;oBACtB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;oBACvB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;iBAClC,CAAC;aACH,CAAC,CAAA;YAEF,0CAA0C;YAC1C,mEAAmE;YACnE,OAAO,eAAe,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAA6B,CAAA;QACzE,CAAC;QAED,aAAa,EAAE,CAAC,UAAkB,EAAE,EAAE;YACpC,4BAA4B;YAC5B,sEAAsE;YACtE,OAAO;gBACL,IAAI,EAAE,MAAM;gBACZ,SAAS,EAAE,GAAG,EAAE,kBAAkB;aACnC,CAAA;QACH,CAAC;QAED,iBAAiB,EAAE,GAAG,EAAE;YACtB,OAAO;gBACL,IAAI,EAAE,wBAAwB;gBAC9B,QAAQ,EAAE,IAAI;aACf,CAAA;QACH,CAAC;QAED,oBAAoB,EAAE,GAAG,EAAE;YACzB,OAAO;gBACL;oBACE,KAAK,EAAE,CAAC,iBAAiB,CAAC;oBAC1B,IAAI,EAAE,qBAAqB;oBAC3B,QAAQ,EAAE,IAAI;iBACf;aACF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/fields/embedding.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=embedding.test.d.ts.map

package/dist/fields/embedding.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.test.d.ts","sourceRoot":"","sources":["../../src/fields/embedding.test.ts"],"names":[],"mappings":""}