@opensaas/stack-rag 0.1.6

package/dist/storage/types.d.ts

@@ -0,0 +1,79 @@
+import type { SearchResult } from '../config/types.js';
+/**
+ * Vector storage backend interface
+ * All storage backends must implement this interface
+ */
+export interface VectorStorage {
+    /**
+     * Storage backend type
+     */
+    readonly type: string;
+    /**
+     * Search for similar vectors
+     *
+     * @param listKey - The list name (e.g., 'Post', 'Article')
+     * @param fieldName - The field name containing embeddings
+     * @param queryVector - The query embedding vector
+     * @param options - Search options
+     * @returns Array of search results with items and scores
+     */
+    search<T = unknown>(listKey: string, fieldName: string, queryVector: number[], options: SearchOptions): Promise<SearchResult<T>[]>;
+    /**
+     * Calculate cosine similarity between two vectors
+     * Utility function for scoring results
+     *
+     * @param a - First vector
+     * @param b - Second vector
+     * @returns Similarity score (0-1, higher is more similar)
+     */
+    cosineSimilarity(a: number[], b: number[]): number;
+}
+/**
+ * Options for vector search
+ */
+export type SearchOptions = {
+    /**
+     * Maximum number of results to return
+     * @default 10
+     */
+    limit?: number;
+    /**
+     * Minimum similarity score (0-1)
+     * Results below this threshold will be filtered out
+     * @default 0.0
+     */
+    minScore?: number;
+    /**
+     * Access context for enforcing access control
+     * Required to ensure users only see items they have access to
+     */
+    context: import('@opensaas/stack-core').AccessContext;
+    /**
+     * Additional Prisma where clause to filter results
+     * This is merged with access control filters
+     */
+    where?: Record<string, unknown>;
+};
+/**
+ * Distance functions for vector similarity
+ */
+export type DistanceFunction = 'cosine' | 'l2' | 'inner_product';
+/**
+ * Normalize a vector to unit length
+ * Required for cosine similarity
+ */
+export declare function normalizeVector(vector: number[]): number[];
+/**
+ * Calculate dot product of two vectors
+ */
+export declare function dotProduct(a: number[], b: number[]): number;
+/**
+ * Calculate L2 (Euclidean) distance between two vectors
+ */
+export declare function l2Distance(a: number[], b: number[]): number;
+/**
+ * Calculate cosine similarity between two vectors
+ * Returns a value between 0 and 1 (higher is more similar)
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAE7B;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;CACnD;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAA;IAErD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,IAAI,GAAG,eAAe,CAAA;AAEhE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAK3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAS3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAajE"}

package/dist/storage/types.js

@@ -0,0 +1,49 @@
+/**
+ * Normalize a vector to unit length
+ * Required for cosine similarity
+ */
+export function normalizeVector(vector) {
+    const magnitude = Math.sqrt(vector.reduce((sum, val) => sum + val * val, 0));
+    if (magnitude === 0)
+        return vector;
+    return vector.map((val) => val / magnitude);
+}
+/**
+ * Calculate dot product of two vectors
+ */
+export function dotProduct(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    return a.reduce((sum, val, i) => sum + val * b[i], 0);
+}
+/**
+ * Calculate L2 (Euclidean) distance between two vectors
+ */
+export function l2Distance(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    const sumSquaredDiff = a.reduce((sum, val, i) => {
+        const diff = val - b[i];
+        return sum + diff * diff;
+    }, 0);
+    return Math.sqrt(sumSquaredDiff);
+}
+/**
+ * Calculate cosine similarity between two vectors
+ * Returns a value between 0 and 1 (higher is more similar)
+ */
+export function cosineSimilarity(a, b) {
+    const dotProd = dotProduct(a, b);
+    const magnitudeA = Math.sqrt(dotProduct(a, a));
+    const magnitudeB = Math.sqrt(dotProduct(b, b));
+    if (magnitudeA === 0 || magnitudeB === 0) {
+        return 0;
+    }
+    // Cosine similarity ranges from -1 to 1
+    // We normalize to 0-1 for consistency
+    const similarity = dotProd / (magnitudeA * magnitudeB);
+    return (similarity + 1) / 2;
+}
+//# sourceMappingURL=types.js.map

package/dist/storage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AA0EA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAC5E,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,MAAM,CAAA;IAClC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,CAAC,CAAA;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAW,EAAE,CAAW;IACjD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAW,EAAE,CAAW;IACjD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACvB,OAAO,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;IAC1B,CAAC,EAAE,CAAC,CAAC,CAAA;IACL,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAChC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAE9C,IAAI,UAAU,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,CAAA;IACV,CAAC;IAED,wCAAwC;IACxC,sCAAsC;IACtC,MAAM,UAAU,GAAG,OAAO,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC,CAAA;IACtD,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@opensaas/stack-rag",
+  "version": "0.1.6",
+  "description": "RAG and AI embeddings integration for OpenSaas Stack",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./fields": {
+      "types": "./dist/fields/index.d.ts",
+      "default": "./dist/fields/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "default": "./dist/providers/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "default": "./dist/storage/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "default": "./dist/runtime/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "default": "./dist/mcp/index.js"
+    }
+  },
+  "keywords": [
+    "opensaas",
+    "rag",
+    "embeddings",
+    "vector-search",
+    "ai",
+    "semantic-search"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OpenSaasAU/stack.git",
+    "directory": "packages/rag"
+  },
+  "homepage": "https://stack.opensaas.au",
+  "bugs": {
+    "url": "https://github.com/OpenSaasAU/stack/issues"
+  },
+  "peerDependencies": {
+    "openai": "^6.8.0",
+    "@opensaas/stack-core": "0.1.6"
+  },
+  "peerDependenciesMeta": {
+    "openai": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.7.2",
+    "@vitest/coverage-v8": "^4.0.4",
+    "@vitest/ui": "^4.0.0",
+    "openai": "^6.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0",
+    "@opensaas/stack-core": "0.1.6"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf .turbo dist tsconfig.tsbuildinfo",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,116 @@
+import type {
+  RAGConfig,
+  NormalizedRAGConfig,
+  VectorStorageConfig,
+  OpenAIEmbeddingConfig,
+  OllamaEmbeddingConfig,
+} from './types.js'
+
+/**
+ * Normalize RAG configuration with defaults
+ */
+export function normalizeRAGConfig(config: RAGConfig): NormalizedRAGConfig {
+  return {
+    provider: config.provider || null,
+    providers: config.providers || {},
+    storage: config.storage || { type: 'json' },
+    chunking: {
+      strategy: config.chunking?.strategy || 'recursive',
+      maxTokens: config.chunking?.maxTokens || 500,
+      overlap: config.chunking?.overlap || 50,
+    },
+    enableMcpTools: config.enableMcpTools ?? true,
+    batchSize: config.batchSize || 10,
+    rateLimit: config.rateLimit || 100,
+  }
+}
+
+/**
+ * Helper to create OpenAI embedding provider configuration
+ *
+ * @example
+ * ```typescript
+ * const provider = openaiEmbeddings({
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   model: 'text-embedding-3-small'
+ * })
+ * ```
+ */
+export function openaiEmbeddings(
+  config: Omit<OpenAIEmbeddingConfig, 'type'>,
+): OpenAIEmbeddingConfig {
+  return {
+    type: 'openai',
+    ...config,
+  }
+}
+
+/**
+ * Helper to create Ollama embedding provider configuration
+ *
+ * @example
+ * ```typescript
+ * const provider = ollamaEmbeddings({
+ *   baseURL: 'http://localhost:11434',
+ *   model: 'nomic-embed-text'
+ * })
+ * ```
+ */
+export function ollamaEmbeddings(
+  config?: Omit<OllamaEmbeddingConfig, 'type'>,
+): OllamaEmbeddingConfig {
+  return {
+    type: 'ollama',
+    baseURL: config?.baseURL || 'http://localhost:11434',
+    model: config?.model || 'nomic-embed-text',
+  }
+}
+
+/**
+ * Helper to create pgvector storage configuration
+ *
+ * @example
+ * ```typescript
+ * const storage = pgvectorStorage({ distanceFunction: 'cosine' })
+ * ```
+ */
+export function pgvectorStorage(config?: {
+  distanceFunction?: 'cosine' | 'l2' | 'inner_product'
+}): VectorStorageConfig {
+  return {
+    type: 'pgvector',
+    distanceFunction: config?.distanceFunction || 'cosine',
+  }
+}
+
+/**
+ * Helper to create SQLite VSS storage configuration
+ *
+ * @example
+ * ```typescript
+ * const storage = sqliteVssStorage({ distanceFunction: 'cosine' })
+ * ```
+ */
+export function sqliteVssStorage(config?: {
+  distanceFunction?: 'cosine' | 'l2'
+}): VectorStorageConfig {
+  return {
+    type: 'sqlite-vss',
+    distanceFunction: config?.distanceFunction || 'cosine',
+  }
+}
+
+/**
+ * Helper to create JSON-based storage configuration
+ *
+ * @example
+ * ```typescript
+ * const storage = jsonStorage()
+ * ```
+ */
+export function jsonStorage(): VectorStorageConfig {
+  return { type: 'json' }
+}
+
+export type { RAGConfig, NormalizedRAGConfig }
+export * from './types.js'