knowy 1.0.0

package/README.md

@@ -0,0 +1,108 @@
+# Knowy
+
+A local-first, zero-config knowledge base engine with semantic vector search. Built on LanceDB and Hugging Face Transformers.
+
+## Features
+
+- 🔍 **Semantic Search** - Find relevant content using natural language queries
+- 💾 **Local-First** - All data stored locally using LanceDB (no cloud required)
+- 🧠 **Built-in Embeddings** - Uses Qwen3-Embedding-0.6B-ONNX for high-quality vectors
+- 📚 **Knowledge Base Organization** - Group data into named knowledge bases
+- ❓ **Q&A Support** - Store question-answer pairs or free text documents
+- 🚀 **Zero Configuration** - Works out of the box with sensible defaults
+
+## Installation
+
+```bash
+npm install knowy
+```
+
+## Quick Start
+
+```javascript
+import { knowy } from 'knowy';
+
+// Initialize the engine
+const kbs = await knowy('./my_database');
+
+// Create or access a knowledge base
+const docs = kbs('documentation');
+
+// Add Q&A pairs
+await docs.addQA('getting-started', 'How do I install?', 'Run npm install knowy');
+
+// Or add free text
+await docs.addText('api-reference', 'The API supports vector search with cosine similarity...');
+
+// Search across your knowledge base
+const results = await docs.search('how to install this package?', { limit: 5 });
+console.log(results);
+```
+
+## API Reference
+
+### `knowy(dbPath)`
+
+Initialize the Knowy engine.
+
+- `dbPath` (string): Path to the LanceDB database directory (default: `\"./knowy_database\"`)
+
+Returns a `kbs` function with attached methods.
+
+### `kbs(kbName)`
+
+Get or create a knowledge base.
+
+Returns a knowledge base object with methods:
+- `addQA(topic, question, answer)` - Add a Q&A pair
+- `addText(topic, text)` - Add free text content
+- `search(query, options)` - Search within this KB
+- `delete()` - Delete this knowledge base
+
+### `kbs.search(query, options)`
+
+Search across all knowledge bases.
+
+- `query` (string): Search query
+- `options.kbs` (string|string[]): Filter by specific knowledge base(s)
+- `options.limit` (number): Max results (default: 10)
+
+Returns array of results with `kb`, `topic`, `type`, `content`, and `score` (0-1).
+
+### `kbs.list()`
+
+List all knowledge bases.
+
+## Example: Multi-KB Setup
+
+```javascript
+const kbs = await knowy();
+
+// Separate KBs for different domains
+const codeKB = kbs('code-snippets');
+const docsKB = kbs('documentation');
+const supportKB = kbs('support-tickets');
+
+// Add content to each...
+await codeKB.addText('auth', 'JWT authentication implementation...');
+await docsKB.addQA('setup', 'Node version?', 'Requires Node 18+');
+await supportKB.addQA('billing', 'How to cancel?', 'Go to settings > billing...');
+
+// Search everything
+const allResults = await kbs.search('authentication', { limit: 10 });
+
+// Search specific KBs only
+const codeOnly = await kbs.search('authentication', { kbs: 'code-snippets' });
+```
+
+## Search Scoring
+
+Results include a `score` from 0 to 1, where 1 is a perfect match. The score is calculated using cosine similarity between the query embedding and stored vectors.
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## License
+
+MIT © littlejustnode

package/knowy.js

@@ -0,0 +1,116 @@
+import { pipeline } from '@huggingface/transformers';
+import * as lancedb from "@lancedb/lancedb";
+import crypto from "crypto";
+
+class KnowyEngine {
+  constructor(dbPath) {
+    this.dbPath = dbPath;
+    this.modelId = 'onnx-community/Qwen3-Embedding-0.6B-ONNX';
+    this.tableName = "all_knowledge_records";
+    this.extractor = null;
+    this.db = null;
+    this.table = null;
+  }
+
+  async init() {
+    this.extractor = await pipeline('feature-extraction', this.modelId, { dtype: 'fp32' });
+    this.db = await lancedb.connect(this.dbPath);
+    const tableNames = await this.db.tableNames();
+    if (tableNames.includes(this.tableName)) {
+      this.table = await this.db.openTable(this.tableName);
+    }
+    return this;
+  }
+
+  async _getEmbedding(text) {
+    const output = await this.extractor(text, { pooling: 'last_token', normalize: true });
+    return Array.from(output.data);
+  }
+
+  async _upsert(record) {
+    if (!this.table) {
+      this.table = await this.db.createTable(this.tableName, [record]);
+    } else {
+      await this.table.add([record]);
+    }
+  }
+
+  getKB(kbName) {
+    return {
+      name: kbName,
+      addQA: (topic, q, a) => this.addQA(kbName, topic, q, a),
+      addText: (topic, text) => this.addText(kbName, topic, text),
+      search: (query, options = {}) => this.search(query, { ...options, kbs: kbName }),
+      delete: () => this.deleteKB(kbName)
+    };
+  }
+
+  async addQA(kbName, topic, question, answer) {
+    const vector = await this._getEmbedding(question);
+    await this._upsert({
+      id: crypto.randomUUID(),
+      vector, kb_name: kbName, topic, type: 'qa',
+      question, answer, text: "", created_at: new Date().toISOString()
+    });
+  }
+
+  async addText(kbName, topic, text) {
+    const vector = await this._getEmbedding(text);
+    await this._upsert({
+      id: crypto.randomUUID(),
+      vector, kb_name: kbName, topic, type: 'text',
+      question: "", answer: "", text, created_at: new Date().toISOString()
+    });
+  }
+
+  async search(query, options = {}) {
+    if (!this.table) return [];
+    const { kbs, limit = 10 } = options;
+    const queryVector = await this._getEmbedding(query);
+    let request = this.table.vectorSearch(queryVector);
+	request.metricType = "cosine";
+
+    if (kbs) {
+      const filter = Array.isArray(kbs) 
+        ? `kb_name IN (${kbs.map(n => `"${n}"`).join(",")})` 
+        : `kb_name = "${kbs}"`;
+      request = request.where(filter);
+    }
+
+    const results = await request.limit(limit).toArray();
+    return results.map(r => ({
+      kb: r.kb_name,
+      topic: r.topic,
+      type: r.type,
+      content: r.type === 'qa' ? { q: r.question, a: r.answer } : { text: r.text },
+      score: 1-(r._distance/2)
+    }));
+  }
+
+  async deleteKB(kbName) {
+    if (this.table) await this.table.delete(`kb_name = "${kbName}"`);
+  }
+
+  async listKBs() {
+    if (!this.table) return [];
+    const all = await this.table.query().select(["kb_name"]).toArray();
+    return [...new Set(all.map(i => i.kb_name))];
+  }
+}
+
+/**
+ * Main export: initializes engine and returns the kbs function.
+ */
+export const knowy = async (dbPath = "./knowy_database") => {
+  const engine = new KnowyEngine(dbPath);
+  await engine.init();
+
+  // The kbs function
+  const kbs = (kbName) => engine.getKB(kbName);
+
+  // Attached methods
+  kbs.search = (query, options) => engine.search(query, options);
+  kbs.list = () => engine.listKBs();
+
+  return kbs;
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "knowy",
+  "version": "1.0.0",
+  "description": "A local-first knowledge base engine with vector search using LanceDB and Hugging Face embeddings",
+  "main": "knowy.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "knowledge-base",
+    "vector-search",
+    "embeddings",
+    "lancedb",
+    "huggingface",
+    "semantic-search",
+    "qa",
+    "ai",
+	"knowy",
+    "local-first"
+  ],
+  "author": "littlejustnode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/littlejustnode/knowy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/littlejustnode/knowy/issues"
+  },
+  "homepage": "https://github.com/littlejustnode/knowy#readme",
+  "dependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "@lancedb/lancedb": "^0.15.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}