@absolutejs/absolute-rag-sqlite 0.0.1

package/README.md

@@ -0,0 +1,90 @@
+# @absolutejs/absolute-rag-sqlite
+
+SQLite adapter package for AbsoluteJS RAG workflows.
+
+This package is not the RAG feature itself. Core `@absolutejs/absolute` owns the
+workflow model, hooks, plugin protocol, and fallback behavior. This package owns
+SQLite-specific backend ergonomics and optional native sqlite-vec acceleration.
+
+## Install
+
+```bash
+bun add @absolutejs/absolute-rag-sqlite
+```
+
+## Supported native targets
+
+The optional native sqlite-vec path currently vendors upstream binaries for:
+
+- macOS arm64
+- macOS x64
+- Linux arm64
+- Linux x64
+- Windows x64
+
+Unsupported targets stay on the owned fallback path until a backend package adds
+support for them.
+
+## What it gives you
+
+- `createSQLiteRAGStore(...)`: SQLite-backed RAG store
+- `createSQLiteRAGCollection(...)`: convenience wrapper that creates the store and collection together
+- `createSQLiteRAGBackend(...)`: one-shot backend bundle with `store`, `collection`, and native support helpers
+- `getSQLiteRAGNativeSupport()`: inspect whether the platform sqlite vec package is available
+- `summarizeSQLiteRAGSupport(...)`: turn store diagnostics into an actionable backend summary
+
+## Basic usage
+
+```ts
+import { createSQLiteRAGBackend, ragPlugin } from "@absolutejs/absolute-rag-sqlite";
+
+const backend = createSQLiteRAGBackend({
+  storeOptions: {
+    path: "./rag.sqlite",
+    native: {
+      mode: "vec0"
+    }
+  }
+});
+
+app.use(
+  ragPlugin({
+    path: "/rag",
+    collection: backend.collection
+  })
+);
+```
+
+## Native vec0 behavior
+
+`sqlite-vec` is treated as an optional accelerator.
+
+- If the platform package is available and `native.mode` is set to `"vec0"`, the store can activate native vec0 search.
+- If it is unavailable, AbsoluteJS falls back to the owned JSON/sqlite-table path.
+- Your application code does not need to hardcode native library paths in the normal case.
+
+You can inspect what happened at runtime:
+
+```ts
+const support = backend.getNativeSupport();
+console.log(support.actionableMessage);
+```
+
+## Release flow
+
+```bash
+bun run vendor:binaries
+bun run check
+bun run publish:all
+```
+
+The vendoring script verifies upstream checksums before copying binaries into the
+platform package directories.
+
+## Scope
+
+This package should stay replaceable.
+
+- SQLite is one backend path.
+- Core AbsoluteJS must continue to work without it.
+- Future backends such as `@absolutejs/absolute-rag-pgvector` should fit the same adapter contract.

package/index.d.ts

@@ -0,0 +1,69 @@
+import type {
+  RAGBackendCapabilities,
+  RAGCollection,
+  RAGVectorStore,
+  RAGVectorStoreStatus,
+  SQLiteRAGStoreOptions,
+  SQLiteVecResolution
+} from '@absolutejs/absolute/ai';
+import {
+  createRAGCollection,
+  createSQLiteRAGStore as createCoreSQLiteRAGStore,
+  ragPlugin,
+  resolveAbsoluteSQLiteVec,
+  resolveAbsoluteSQLiteVecExtensionPath
+} from '@absolutejs/absolute/ai';
+
+export declare const ABSOLUTE_SQLITE_RAG_PACKAGE_NAME = "@absolutejs/absolute-rag-sqlite";
+
+export type SQLiteRAGCollectionOptions = {
+  store?: RAGVectorStore;
+  storeOptions?: SQLiteRAGStoreOptions;
+};
+
+export type SQLiteRAGBackendOptions = {
+  store?: RAGVectorStore;
+  collection?: RAGCollection;
+  storeOptions?: SQLiteRAGStoreOptions;
+};
+
+export type SQLiteRAGSupportSummary = {
+  backendPackageName: typeof ABSOLUTE_SQLITE_RAG_PACKAGE_NAME;
+  recommendedInstallCommand: string;
+  resolution: SQLiteVecResolution;
+  status?: RAGVectorStoreStatus;
+  capabilities?: RAGBackendCapabilities;
+  nativeRequested: boolean;
+  nativeActive: boolean;
+  actionableMessage: string;
+};
+
+export type SQLiteRAGBackend = {
+  store: RAGVectorStore;
+  collection: RAGCollection;
+  getStatus: () => RAGVectorStoreStatus | undefined;
+  getCapabilities: () => RAGBackendCapabilities | undefined;
+  getNativeSupport: () => SQLiteRAGSupportSummary;
+};
+
+export declare const createSQLiteRAGStore: typeof createCoreSQLiteRAGStore;
+export declare const createSQLiteRAGCollection: (options?: SQLiteRAGCollectionOptions) => RAGCollection;
+export declare const createSQLiteRAGBackend: (options?: SQLiteRAGBackendOptions) => SQLiteRAGBackend;
+export declare const getSQLiteRAGNativeSupport: typeof resolveAbsoluteSQLiteVec;
+export declare const summarizeSQLiteRAGSupport: (target?: Pick<RAGCollection, 'getStatus' | 'getCapabilities'> | Pick<RAGVectorStore, 'getStatus' | 'getCapabilities'>) => SQLiteRAGSupportSummary;
+
+export {
+  createRAGCollection,
+  ragPlugin,
+  resolveAbsoluteSQLiteVec,
+  resolveAbsoluteSQLiteVecExtensionPath
+};
+
+export type {
+  RAGBackendCapabilities,
+  RAGCollection,
+  RAGVectorStore,
+  RAGVectorStoreStatus,
+  SQLiteRAGStoreOptions,
+  SQLiteVecResolution
+};

package/index.js

@@ -0,0 +1,84 @@
+import {
+  createRAGCollection,
+  createSQLiteRAGStore as createCoreSQLiteRAGStore,
+  ragPlugin,
+  resolveAbsoluteSQLiteVec,
+  resolveAbsoluteSQLiteVecExtensionPath
+} from '@absolutejs/absolute/ai';
+
+export const ABSOLUTE_SQLITE_RAG_PACKAGE_NAME = '@absolutejs/absolute-rag-sqlite';
+
+const nativeMessageFromResolution = (resolution) => {
+  switch (resolution?.status) {
+    case 'resolved':
+      return 'Native sqlite vec support is installed and can be activated with native.mode="vec0".';
+    case 'package_not_installed':
+      return `Install ${ABSOLUTE_SQLITE_RAG_PACKAGE_NAME} and restart to let AbsoluteJS resolve the platform sqlite vec package automatically.`;
+    case 'binary_missing':
+      return 'The platform sqlite vec package was resolved but its native library file is missing.';
+    case 'unsupported_platform':
+      return `No sqlite vec platform package is defined for ${resolution.platformKey}. JSON fallback remains available.`;
+    case 'package_invalid':
+      return 'The installed sqlite vec package is invalid. Reinstall the backend package and restart.';
+    case 'not_configured':
+    default:
+      return 'Native sqlite vec support is not configured. JSON fallback remains available.';
+  }
+};
+
+export const createSQLiteRAGStore = (options = {}) =>
+  createCoreSQLiteRAGStore(options);
+
+export const createSQLiteRAGCollection = (options = {}) => {
+  const store = options.store ?? createSQLiteRAGStore(options.storeOptions ?? {});
+  return createRAGCollection({ store });
+};
+
+export const createSQLiteRAGBackend = (options = {}) => {
+  const store = options.store ?? createSQLiteRAGStore(options.storeOptions ?? {});
+  const collection = options.collection ?? createRAGCollection({ store });
+
+  return {
+    store,
+    collection,
+    getStatus: () => collection.getStatus?.() ?? store.getStatus?.(),
+    getCapabilities: () => collection.getCapabilities?.() ?? store.getCapabilities?.(),
+    getNativeSupport: () => summarizeSQLiteRAGSupport(collection)
+  };
+};
+
+export const getSQLiteRAGNativeSupport = () => resolveAbsoluteSQLiteVec();
+
+export const summarizeSQLiteRAGSupport = (target) => {
+  const status = target?.getStatus?.();
+  const capabilities = target?.getCapabilities?.();
+  const resolution = status?.native?.resolution ?? resolveAbsoluteSQLiteVec();
+  const nativeRequested = status?.native?.requested ?? false;
+  const nativeActive = status?.native?.active ?? false;
+
+  let actionableMessage = nativeMessageFromResolution(resolution);
+
+  if (nativeActive) {
+    actionableMessage = 'Native sqlite vec0 is active for this store.';
+  } else if (resolution?.status === 'resolved' && nativeRequested) {
+    actionableMessage = 'Native sqlite vec is installed, but this store is still running in fallback mode. Check the store diagnostics for load or query errors.';
+  }
+
+  return {
+    backendPackageName: ABSOLUTE_SQLITE_RAG_PACKAGE_NAME,
+    recommendedInstallCommand: `bun add ${ABSOLUTE_SQLITE_RAG_PACKAGE_NAME}`,
+    resolution,
+    status,
+    capabilities,
+    nativeRequested,
+    nativeActive,
+    actionableMessage
+  };
+};
+
+export {
+  createRAGCollection,
+  ragPlugin,
+  resolveAbsoluteSQLiteVec,
+  resolveAbsoluteSQLiteVecExtensionPath
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@absolutejs/absolute-rag-sqlite",
+  "version": "0.0.1",
+  "description": "SQLite adapter package for AbsoluteJS RAG workflows with optional native vec0 acceleration",
+  "license": "BSL-1.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "README.md",
+    "index.js",
+    "index.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "scripts": {
+    "check": "node ./scripts/check-release.mjs",
+    "vendor:binaries": "node ./scripts/vendor-sqlite-vec.mjs",
+    "pack": "bun pm pack",
+    "publish:all": "node ./scripts/publish-all.mjs",
+    "release:package": "bun publish --access public"
+  },
+  "peerDependencies": {
+    "@absolutejs/absolute": ">=0.19.0-beta.394 <0.20.0"
+  },
+  "optionalDependencies": {
+    "@absolutejs/absolute-rag-sqlite-darwin-arm64": "0.0.1",
+    "@absolutejs/absolute-rag-sqlite-darwin-x64": "0.0.1",
+    "@absolutejs/absolute-rag-sqlite-linux-arm64": "0.0.1",
+    "@absolutejs/absolute-rag-sqlite-linux-x64": "0.0.1",
+    "@absolutejs/absolute-rag-sqlite-windows-x64": "0.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/absolutejs/absolute-rag-sqlite.git"
+  },
+  "keywords": [
+    "absolutejs",
+    "rag",
+    "sqlite",
+    "vector",
+    "sqlite-vec"
+  ],
+  "sqliteVec": {
+    "version": "0.1.9"
+  }
+}