@o-lang/semantic-doc-search 1.0.27 → 1.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@o-lang/semantic-doc-search",
-  "version": "1.0.27",
+  "version": "1.0.29",
   "description": "O-lang Semantic Document Search Resolver with hybrid search, embeddings, rerank, and streaming.",
   "main": "src/index.js",
   "type": "commonjs",

package/src/adapters/VectorAdapter.js

@@ -1,31 +1,11 @@
-/**
- * Base Vector Adapter
- * All vector backends must extend this class.
- *
- * Responsibilities:
- * - dimension validation
- * - capability exposure
- * - ingestion guards
- */
-
 class VectorAdapter {
   constructor(config = {}) {
     this.backend = config.backend || "unknown";
     this.dimension = config.dimension || null;
-
-    // Optional but recommended
-    this.capabilities = config.capabilities || [];
-    this.supportsHybrid = config.supportsHybrid ?? false;
-    this.requiresIdempotentInsert = config.requiresIdempotentInsert ?? false;
   }
 
-  /* ---------------- VALIDATION ---------------- */
-
   validateVector(vector) {
-    if (!Array.isArray(vector)) {
-      throw new Error("Vector must be an array");
-    }
-
+    if (!Array.isArray(vector)) throw new Error("Vector must be an array");
     if (this.dimension && vector.length !== this.dimension) {
       throw new Error(
         `Vector dimension mismatch: expected ${this.dimension}, got ${vector.length}`
@@ -33,49 +13,16 @@ class VectorAdapter {
     }
   }
 
-  ensureCapability(capability) {
-    if (!this.capabilities.includes(capability)) {
-      throw new Error(
-        `Backend "${this.backend}" does not support capability: ${capability}`
-      );
-    }
-  }
-
-  /* ---------------- INGESTION GUARDS ---------------- */
-
-  /**
-   * Optional hook for hybrid-safe ingestion.
-   * Adapters that require idempotent inserts SHOULD override this.
-   */
-  async ensureNotIndexed(/* fingerprint */) {
-    if (this.requiresIdempotentInsert) {
-      throw new Error(
-        `ensureNotIndexed() must be implemented for backend "${this.backend}"`
-      );
-    }
-  }
-
-  /* ---------------- CORE OPS ---------------- */
-
-  async upsert() {
-    throw new Error("upsert() not implemented");
-  }
-
-  async query() {
-    throw new Error("query() not implemented");
-  }
-
-  /* ---------------- HEALTH ---------------- */
+  async upsert() { throw new Error("upsert() not implemented"); }
+  async query() { throw new Error("query() not implemented"); }
+  async health() { return { backend: this.backend, status: "unknown" }; }
+  async close() {}
 
-  async health() {
-    return {
-      backend: this.backend,
-      status: "unknown",
-      hybrid: this.supportsHybrid
-    };
+  /** ✅ Checks if backend supports a capability */
+  supports(capability) {
+    const caps = this.constructor.capabilities?.()?.capabilities || [];
+    return caps.includes(capability);
   }
-
-  async close() {}
 }
 
 module.exports = VectorAdapter;

package/src/adapters/inMemoryAdapter.js

@@ -1,45 +1,23 @@
 const VectorAdapter = require("./VectorAdapter");
-const vectorCapabilities = require("./vectorCapabilities");
+const capabilities = require("./vectorCapabilities");
 
-/**
- * In-memory vector adapter
- * - Non-persistent
- * - Offline-safe
- * - No hybrid ingestion risk
- */
 class InMemoryAdapter extends VectorAdapter {
   constructor(config = {}) {
-    super({
-      ...config,
-      backend: "memory",
-      capabilities: vectorCapabilities.memory.capabilities,
-      supportsHybrid: false,
-      requiresIdempotentInsert: false
-    });
-
+    super({ ...config, backend: "memory" });
     this.dimension = config.dimension || 384;
     this.store = [];
   }
 
-  /* ---------------- INGEST ---------------- */
+  static capabilities() {
+    return capabilities.memory;
+  }
 
   async upsert({ id, vector, content, source, metadata = {} }) {
-    this.ensureCapability("vector.insert");
     this.validateVector(vector);
-
-    this.store.push({
-      id,
-      vector,
-      content,
-      source,
-      metadata
-    });
+    this.store.push({ id, vector, content, source, metadata });
   }
 
-  /* ---------------- SEARCH ---------------- */
-
-  async query(vector, { topK = 5, minScore = 0 } = {}) {
-    this.ensureCapability("vector.search");
+  async query(vector, { topK = 5 } = {}) {
     this.validateVector(vector);
 
     return this.store
@@ -47,36 +25,18 @@ class InMemoryAdapter extends VectorAdapter {
         ...doc,
         score: cosineSimilarity(vector, doc.vector)
       }))
-      .filter(doc => doc.score >= minScore)
       .sort((a, b) => b.score - a.score)
       .slice(0, topK);
   }
-
-  /* ---------------- HEALTH ---------------- */
-
-  async health() {
-    return {
-      backend: this.backend,
-      status: "ok",
-      vectors: this.store.length,
-      offline: true
-    };
-  }
 }
 
-/* ---------------- UTIL ---------------- */
-
 function cosineSimilarity(a, b) {
-  let dot = 0;
-  let na = 0;
-  let nb = 0;
-
+  let dot = 0, na = 0, nb = 0;
   for (let i = 0; i < a.length; i++) {
     dot += a[i] * b[i];
     na += a[i] ** 2;
     nb += b[i] ** 2;
   }
-
   return dot / (Math.sqrt(na) * Math.sqrt(nb));
 }
 

package/src/adapters/pgvectorAdapter.js

@@ -1,25 +1,14 @@
 const { Pool } = require("pg");
 const VectorAdapter = require("./VectorAdapter");
-const vectorCapabilities = require("./vectorCapabilities");
-
-/* ---------------- UTIL ---------------- */
+const capabilities = require("./vectorCapabilities");
 
 function toPgVectorLiteral(vector) {
   return `[${vector.join(",")}]`;
 }
 
-/* ---------------- ADAPTER ---------------- */
-
 class PgVectorAdapter extends VectorAdapter {
   constructor(config = {}) {
-    super({
-      ...config,
-      backend: "pgvector",
-      capabilities: vectorCapabilities.pgvector.capabilities,
-      supportsHybrid: true,
-      requiresIdempotentInsert: true
-    });
-
+    super({ ...config, backend: "pgvector" });
     this.dimension = config.dimension || 384;
 
     this.pool = new Pool({
@@ -27,77 +16,43 @@ class PgVectorAdapter extends VectorAdapter {
     });
   }
 
-  /* ---------------- INGEST ---------------- */
+  static capabilities() {
+    return capabilities.pgvector;
+  }
 
   async upsert({ id, vector, content, source, metadata = {} }) {
-    this.ensureCapability("vector.insert");
     this.validateVector(vector);
-
     const pgVector = toPgVectorLiteral(vector);
 
     await this.pool.query(
-      `
-      INSERT INTO doc_embeddings (id, embedding, content, source, metadata)
-      VALUES ($1, $2::vector, $3, $4, $5::jsonb)
-      ON CONFLICT (id) DO UPDATE
-      SET embedding = EXCLUDED.embedding,
-          content   = EXCLUDED.content,
-          source    = EXCLUDED.source,
-          metadata  = EXCLUDED.metadata,
-          updated_at = NOW()
-      `,
+      `INSERT INTO doc_embeddings (id, embedding, content, source, metadata)
+       VALUES ($1, $2::vector, $3, $4, $5::jsonb)
+       ON CONFLICT (id) DO UPDATE
+       SET embedding = $2::vector,
+           content = $3,
+           source = $4,
+           metadata = $5::jsonb,
+           updated_at = NOW()`,
       [id, pgVector, content, source, JSON.stringify(metadata)]
     );
   }
 
-  /* ---------------- SEARCH ---------------- */
-
-  async query(vector, { topK = 5, minScore = 0 } = {}) {
-    this.ensureCapability("vector.search");
+  async query(vector, { topK = 5 } = {}) {
     this.validateVector(vector);
-
     const pgVector = toPgVectorLiteral(vector);
 
     const res = await this.pool.query(
-      `
-      SELECT id,
-             content,
-             source,
-             metadata,
-             1 - (embedding <=> $1::vector) AS score
-      FROM doc_embeddings
-      WHERE 1 - (embedding <=> $1::vector) >= $2
-      ORDER BY embedding <=> $1::vector
-      LIMIT $3
-      `,
-      [pgVector, minScore, topK]
+      `SELECT id, content, source, metadata,
+              1 - (embedding <=> $1::vector) AS score
+       FROM doc_embeddings
+       ORDER BY embedding <=> $1::vector
+       LIMIT $2`,
+      [pgVector, topK]
     );
 
     return res.rows;
   }
 
-  /* ---------------- HEALTH ---------------- */
-
-  async health() {
-    try {
-      await this.pool.query("SELECT 1");
-      return {
-        backend: this.backend,
-        status: "ok",
-        offline: false,
-        hybrid: true
-      };
-    } catch (err) {
-      return {
-        backend: this.backend,
-        status: "error",
-        error: err.message
-      };
-    }
-  }
-
-  /* ---------------- CLEANUP ---------------- */
-
   async close() {
     await this.pool.end();
   }

package/src/adapters/pineconeAdapter.js

@@ -1,101 +1,40 @@
-/**
- * Pinecone Vector Store Adapter
- *
- * Requirements:
- *   npm install @pinecone-database/pinecone
- *
- * Env:
- *   PINECONE_API_KEY
- *   PINECONE_INDEX=olang-docs
- */
+let Pinecone;
 
-const { Pinecone } = require("@pinecone-database/pinecone");
-const VectorAdapter = require("./VectorAdapter");
-const vectorCapabilities = require("./vectorCapabilities");
-
-class PineconeAdapter extends VectorAdapter {
+class PineconeAdapter {
   constructor(config = {}) {
-    super({
-      ...config,
-      backend: "pinecone",
-      capabilities: vectorCapabilities.pinecone.capabilities,
-      supportsHybrid: true,
-      requiresIdempotentInsert: true
-    });
-
-    this.dimension = config.dimension || 1536;
-    this.indexName = config.PINECONE_INDEX || process.env.PINECONE_INDEX || "olang-docs";
+    if (!Pinecone) {
+      try {
+        Pinecone = require("@pinecone-database/pinecone");
+      } catch (err) {
+        throw new Error(
+          "Pinecone adapter requires '@pinecone-database/pinecone'. Please install it via npm."
+        );
+      }
+    }
 
-    const apiKey = config.PINECONE_API_KEY || process.env.PINECONE_API_KEY;
-    if (!apiKey) throw new Error("Missing PINECONE_API_KEY");
+    this.apiKey = process.env.PINECONE_API_KEY;
+    if (!this.apiKey) throw new Error("Missing PINECONE_API_KEY");
 
-    this.client = new Pinecone({ apiKey });
-    this.index = this.client.index(this.indexName);
+    const indexName = process.env.PINECONE_INDEX || "olang-docs";
+    this.client = new Pinecone({ apiKey: this.apiKey });
+    this.indexName = indexName;
   }
 
-  /* ---------------- INGEST ---------------- */
-
-  async upsert({ id, vector, content, source, metadata = {} }) {
-    this.ensureCapability("vector.insert");
-    this.validateVector(vector);
-
-    await this.index.upsert([
-      {
-        id: id.toString(),
-        values: vector,
-        metadata: {
-          content,
-          source,
-          ...metadata
-        }
-      }
-    ]);
+  static capabilities() {
+    return { persistent: true, offline: false, distance: "cosine", maxDimension: 1536, capabilities: ["vector.insert", "vector.search"] };
   }
 
-  /* ---------------- SEARCH ---------------- */
-
-  async query(vector, { topK = 5, minScore = 0 } = {}) {
-    this.ensureCapability("vector.search");
-    this.validateVector(vector);
-
-    const res = await this.index.query({
-      vector,
-      topK,
-      includeMetadata: true
-    });
-
-    return res.matches
-      .filter(m => m.score >= minScore)
-      .map(m => ({
-        id: m.id,
-        score: m.score,
-        content: m.metadata?.content,
-        source: m.metadata?.source,
-        metadata: m.metadata
-      }));
+  async init() {
+    // ... your init logic here
   }
 
-  /* ---------------- HEALTH ---------------- */
-
-  async health() {
-    try {
-      await this.client.listIndexes();
-      return {
-        backend: this.backend,
-        status: "ok",
-        offline: false,
-        hybrid: true
-      };
-    } catch (err) {
-      return {
-        backend: this.backend,
-        status: "error",
-        error: err.message
-      };
-    }
+  async upsert(id, vector, metadata) {
+    // ...
   }
 
-  async close() {}
+  async search(queryVector, limit = 5) {
+    // ...
+  }
 }
 
 module.exports = PineconeAdapter;

package/src/adapters/vectorRouter.js

@@ -1,3 +1,12 @@
+const InMemoryAdapter = require("./inMemoryAdapter");
+const PgVectorAdapter = require("./pgvectorAdapter");
+const RedisAdapter = require("./redisAdapter");
+const PineconeAdapter = require("./pineconeAdapter");
+
+/**
+ * VectorRouter
+ * Dynamically selects vector backend at runtime
+ */
 class VectorRouter {
   static create(config = {}) {
     // 1. Explicit backend override (advanced users only)
@@ -7,36 +16,26 @@ class VectorRouter {
 
     // 2. Auto-detect pgvector (DEFAULT)
     if (config.POSTGRES_URL) {
-      const PgVectorAdapter = require("./pgvectorAdapter");
       return new PgVectorAdapter(config);
     }
 
     // 3. Fallback to in-memory (safe default)
-    const InMemoryAdapter = require("./inMemoryAdapter");
     return new InMemoryAdapter(config);
   }
 
   static _createExplicitBackend(backend, config) {
-    switch (backend) {
-      case "pgvector": {
-        const PgVectorAdapter = require("./pgvectorAdapter");
+    switch (backend.toLowerCase()) {
+      case "pgvector":
         return new PgVectorAdapter(config);
-      }
 
-      case "memory": {
-        const InMemoryAdapter = require("./inMemoryAdapter");
+      case "memory":
         return new InMemoryAdapter(config);
-      }
 
-      case "redis": {
-        const RedisAdapter = require("./redisAdapter");
+      case "redis":
         return new RedisAdapter(config);
-      }
 
-      case "pinecone": {
-        const PineconeAdapter = require("./pineconeAdapter");
+      case "pinecone":
         return new PineconeAdapter(config);
-      }
 
       default:
         throw new Error(`Unknown vector backend: ${backend}`);