@radaros/core 0.1.0

package/src/vector/pgvector.ts

@@ -0,0 +1,169 @@
+import { createRequire } from "node:module";
+import { BaseVectorStore } from "./base.js";
+import type {
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+  EmbeddingProvider,
+} from "./types.js";
+
+const _require = createRequire(import.meta.url);
+
+export interface PgVectorConfig {
+  connectionString: string;
+  dimensions?: number;
+}
+
+export class PgVectorStore extends BaseVectorStore {
+  private pool: any;
+  private dimensions: number;
+  private initializedCollections = new Set<string>();
+
+  constructor(config: PgVectorConfig, embedder?: EmbeddingProvider) {
+    super(embedder);
+    this.dimensions = config.dimensions ?? embedder?.dimensions ?? 1536;
+    try {
+      const { Pool } = _require("pg");
+      this.pool = new Pool({ connectionString: config.connectionString });
+    } catch {
+      throw new Error(
+        "pg is required for PgVectorStore. Install it: npm install pg"
+      );
+    }
+  }
+
+  async initialize(): Promise<void> {
+    await this.pool.query("CREATE EXTENSION IF NOT EXISTS vector");
+  }
+
+  private async ensureCollection(collection: string): Promise<void> {
+    if (this.initializedCollections.has(collection)) return;
+    const table = this.sanitize(collection);
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS ${table} (
+        id TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        embedding vector(${this.dimensions}),
+        metadata JSONB DEFAULT '{}'::jsonb,
+        created_at TIMESTAMPTZ DEFAULT NOW()
+      )
+    `);
+    await this.pool.query(`
+      CREATE INDEX IF NOT EXISTS ${table}_embedding_idx
+      ON ${table} USING ivfflat (embedding vector_cosine_ops)
+      WITH (lists = 100)
+    `).catch(() => {
+      // IVFFlat index needs enough rows; hnsw fallback
+    });
+    this.initializedCollections.add(collection);
+  }
+
+  private sanitize(name: string): string {
+    return name.replace(/[^a-zA-Z0-9_]/g, "_");
+  }
+
+  private toSql(vec: number[]): string {
+    return `[${vec.join(",")}]`;
+  }
+
+  async upsert(collection: string, doc: VectorDocument): Promise<void> {
+    await this.ensureCollection(collection);
+    const embedding = await this.ensureEmbedding(doc);
+    const table = this.sanitize(collection);
+    await this.pool.query(
+      `INSERT INTO ${table} (id, content, embedding, metadata)
+       VALUES ($1, $2, $3::vector, $4::jsonb)
+       ON CONFLICT (id)
+       DO UPDATE SET content = EXCLUDED.content,
+                     embedding = EXCLUDED.embedding,
+                     metadata = EXCLUDED.metadata`,
+      [doc.id, doc.content, this.toSql(embedding), JSON.stringify(doc.metadata ?? {})]
+    );
+  }
+
+  async upsertBatch(collection: string, docs: VectorDocument[]): Promise<void> {
+    for (const doc of docs) {
+      await this.upsert(collection, doc);
+    }
+  }
+
+  async search(
+    collection: string,
+    query: number[] | string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    await this.ensureCollection(collection);
+    const vec = await this.ensureQueryVector(query);
+    const topK = options?.topK ?? 10;
+    const table = this.sanitize(collection);
+
+    let filterClause = "";
+    const params: unknown[] = [this.toSql(vec), topK];
+
+    if (options?.filter) {
+      const conditions = Object.entries(options.filter).map(([k, v], i) => {
+        params.push(JSON.stringify(v));
+        return `metadata->>'${k.replace(/'/g, "''")}' = $${i + 3}`;
+      });
+      if (conditions.length > 0) {
+        filterClause = `WHERE ${conditions.join(" AND ")}`;
+      }
+    }
+
+    const result = await this.pool.query(
+      `SELECT id, content, metadata,
+              1 - (embedding <=> $1::vector) AS score
+       FROM ${table}
+       ${filterClause}
+       ORDER BY embedding <=> $1::vector
+       LIMIT $2`,
+      params
+    );
+
+    let rows = result.rows as Array<{
+      id: string;
+      content: string;
+      score: number;
+      metadata: Record<string, unknown>;
+    }>;
+
+    if (options?.minScore != null) {
+      rows = rows.filter((r) => r.score >= options.minScore!);
+    }
+
+    return rows.map((r) => ({
+      id: r.id,
+      content: r.content,
+      score: r.score,
+      metadata: r.metadata,
+    }));
+  }
+
+  async delete(collection: string, id: string): Promise<void> {
+    await this.ensureCollection(collection);
+    const table = this.sanitize(collection);
+    await this.pool.query(`DELETE FROM ${table} WHERE id = $1`, [id]);
+  }
+
+  async get(collection: string, id: string): Promise<VectorDocument | null> {
+    await this.ensureCollection(collection);
+    const table = this.sanitize(collection);
+    const result = await this.pool.query(
+      `SELECT id, content, metadata FROM ${table} WHERE id = $1`,
+      [id]
+    );
+    if (result.rows.length === 0) return null;
+    const row = result.rows[0];
+    return { id: row.id, content: row.content, metadata: row.metadata };
+  }
+
+  async dropCollection(collection: string): Promise<void> {
+    const table = this.sanitize(collection);
+    await this.pool.query(`DROP TABLE IF EXISTS ${table}`);
+    this.initializedCollections.delete(collection);
+  }
+
+  async close(): Promise<void> {
+    await this.pool.end();
+  }
+}

package/src/vector/qdrant.ts

@@ -0,0 +1,203 @@
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import { BaseVectorStore } from "./base.js";
+import type {
+  VectorDocument,
+  VectorSearchResult,
+  VectorSearchOptions,
+  EmbeddingProvider,
+} from "./types.js";
+
+const _require = createRequire(import.meta.url);
+
+export interface QdrantConfig {
+  url?: string;
+  apiKey?: string;
+  dimensions?: number;
+  checkCompatibility?: boolean;
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Deterministic UUID from an arbitrary string.
+ * Qdrant only accepts UUIDs or unsigned ints as point IDs,
+ * so we hash arbitrary strings into valid UUID v4 format
+ * and store the original ID in the payload under `_originalId`.
+ */
+function stringToUUID(str: string): string {
+  const hex = createHash("md5").update(str).digest("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    "4" + hex.slice(13, 16),
+    "8" + hex.slice(17, 20),
+    hex.slice(20, 32),
+  ].join("-");
+}
+
+function toQdrantId(id: string): string | number {
+  if (/^\d+$/.test(id)) return Number(id);
+  if (UUID_RE.test(id)) return id;
+  return stringToUUID(id);
+}
+
+export class QdrantVectorStore extends BaseVectorStore {
+  private client: any;
+  private dimensions: number;
+  private initializedCollections = new Set<string>();
+
+  constructor(config: QdrantConfig = {}, embedder?: EmbeddingProvider) {
+    super(embedder);
+    this.dimensions = config.dimensions ?? embedder?.dimensions ?? 1536;
+    try {
+      const { QdrantClient } = _require("@qdrant/js-client-rest");
+      this.client = new QdrantClient({
+        url: config.url ?? "http://localhost:6333",
+        apiKey: config.apiKey,
+        checkCompatibility: config.checkCompatibility ?? false,
+      });
+    } catch {
+      throw new Error(
+        "@qdrant/js-client-rest is required for QdrantVectorStore. Install it: npm install @qdrant/js-client-rest"
+      );
+    }
+  }
+
+  async initialize(): Promise<void> {}
+
+  private async ensureCollection(collection: string): Promise<void> {
+    if (this.initializedCollections.has(collection)) return;
+    try {
+      await this.client.getCollection(collection);
+    } catch {
+      await this.client.createCollection(collection, {
+        vectors: {
+          size: this.dimensions,
+          distance: "Cosine",
+        },
+      });
+    }
+    this.initializedCollections.add(collection);
+  }
+
+  async upsert(collection: string, doc: VectorDocument): Promise<void> {
+    await this.ensureCollection(collection);
+    const embedding = await this.ensureEmbedding(doc);
+    await this.client.upsert(collection, {
+      wait: true,
+      points: [
+        {
+          id: toQdrantId(doc.id),
+          vector: embedding,
+          payload: {
+            _originalId: doc.id,
+            content: doc.content,
+            ...(doc.metadata ?? {}),
+          },
+        },
+      ],
+    });
+  }
+
+  async upsertBatch(collection: string, docs: VectorDocument[]): Promise<void> {
+    await this.ensureCollection(collection);
+    const points = await Promise.all(
+      docs.map(async (doc) => {
+        const embedding = await this.ensureEmbedding(doc);
+        return {
+          id: toQdrantId(doc.id),
+          vector: embedding,
+          payload: {
+            _originalId: doc.id,
+            content: doc.content,
+            ...(doc.metadata ?? {}),
+          },
+        };
+      })
+    );
+    await this.client.upsert(collection, { wait: true, points });
+  }
+
+  async search(
+    collection: string,
+    query: number[] | string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]> {
+    await this.ensureCollection(collection);
+    const vec = await this.ensureQueryVector(query);
+    const topK = options?.topK ?? 10;
+
+    const searchParams: Record<string, unknown> = {
+      vector: vec,
+      limit: topK,
+      with_payload: true,
+    };
+
+    if (options?.filter) {
+      searchParams.filter = {
+        must: Object.entries(options.filter).map(([key, value]) => ({
+          key,
+          match: { value },
+        })),
+      };
+    }
+
+    if (options?.minScore != null) {
+      searchParams.score_threshold = options.minScore;
+    }
+
+    const results = await this.client.search(collection, searchParams);
+
+    return results.map((r: any) => {
+      const { _originalId, content, ...rest } = r.payload ?? {};
+      return {
+        id: _originalId ?? String(r.id),
+        content: content ?? "",
+        score: r.score,
+        metadata: rest,
+      };
+    });
+  }
+
+  async delete(collection: string, id: string): Promise<void> {
+    await this.ensureCollection(collection);
+    await this.client.delete(collection, {
+      wait: true,
+      points: [toQdrantId(id)],
+    });
+  }
+
+  async get(collection: string, id: string): Promise<VectorDocument | null> {
+    await this.ensureCollection(collection);
+    try {
+      const results = await this.client.retrieve(collection, {
+        ids: [toQdrantId(id)],
+        with_payload: true,
+      });
+      if (!results || results.length === 0) return null;
+      const point = results[0];
+      const { _originalId, content, ...rest } = point.payload ?? {};
+      return {
+        id: _originalId ?? String(point.id),
+        content: content ?? "",
+        metadata: rest,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  async dropCollection(collection: string): Promise<void> {
+    try {
+      await this.client.deleteCollection(collection);
+    } catch {
+      // collection may not exist
+    }
+    this.initializedCollections.delete(collection);
+  }
+
+  async close(): Promise<void> {
+    // Qdrant JS client doesn't require explicit close
+  }
+}

package/src/vector/types.ts

@@ -0,0 +1,55 @@
+export interface VectorDocument {
+  id: string;
+  content: string;
+  embedding?: number[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface VectorSearchResult {
+  id: string;
+  content: string;
+  score: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface VectorSearchOptions {
+  topK?: number;
+  filter?: Record<string, unknown>;
+  minScore?: number;
+}
+
+export interface EmbeddingProvider {
+  readonly dimensions: number;
+  embed(text: string): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+}
+
+export interface VectorStore {
+  /** Initialize collections/indexes. Call once before use. */
+  initialize(): Promise<void>;
+
+  /** Upsert a single document (embedding computed if not provided). */
+  upsert(collection: string, doc: VectorDocument): Promise<void>;
+
+  /** Upsert multiple documents in batch. */
+  upsertBatch(collection: string, docs: VectorDocument[]): Promise<void>;
+
+  /** Similarity search by vector or text query. */
+  search(
+    collection: string,
+    query: number[] | string,
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]>;
+
+  /** Delete a document by ID. */
+  delete(collection: string, id: string): Promise<void>;
+
+  /** Get a document by ID. */
+  get(collection: string, id: string): Promise<VectorDocument | null>;
+
+  /** Drop an entire collection. */
+  dropCollection(collection: string): Promise<void>;
+
+  /** Close connections. */
+  close(): Promise<void>;
+}