@team-semicolon/semo-cli 3.14.1 → 4.0.0

package/dist/kb.js

@@ -0,0 +1,627 @@
+"use strict";
+/**
+ * SEMO KB/Ontology Module
+ *
+ * Knowledge Base and Ontology management for SEMO bot ecosystem.
+ * Uses the team's core PostgreSQL database as Single Source of Truth.
+ *
+ * v3.15.0: Initial implementation
+ * v3.15.1: pgvector embedding integration
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateEmbedding = generateEmbedding;
+exports.generateEmbeddings = generateEmbeddings;
+exports.kbPull = kbPull;
+exports.kbPush = kbPush;
+exports.kbStatus = kbStatus;
+exports.kbList = kbList;
+exports.kbDiff = kbDiff;
+exports.kbSearch = kbSearch;
+exports.ontoList = ontoList;
+exports.ontoShow = ontoShow;
+exports.ontoValidate = ontoValidate;
+exports.ontoPullToLocal = ontoPullToLocal;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ============================================================
+// Embedding
+// ============================================================
+const EMBEDDING_MODEL = "voyage-3";
+const EMBEDDING_DIMENSIONS = 1024;
+/**
+ * Generate embedding vector for text using OpenAI API
+ * Requires OPENAI_API_KEY environment variable
+ */
+async function generateEmbedding(text) {
+    const apiKey = process.env.VOYAGE_API_KEY;
+    if (!apiKey)
+        return null;
+    try {
+        const response = await fetch("https://api.voyageai.com/v1/embeddings", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: EMBEDDING_MODEL,
+                input: text.substring(0, 8000), // truncate to avoid token limit
+                dimensions: EMBEDDING_DIMENSIONS,
+            }),
+        });
+        if (!response.ok) {
+            const err = await response.text();
+            console.error(`Embedding API error: ${response.status} ${err}`);
+            return null;
+        }
+        const data = await response.json();
+        return data.data?.[0]?.embedding || null;
+    }
+    catch (err) {
+        console.error(`Embedding error: ${err}`);
+        return null;
+    }
+}
+/**
+ * Generate embeddings for multiple texts (batched)
+ */
+async function generateEmbeddings(texts) {
+    const apiKey = process.env.VOYAGE_API_KEY;
+    if (!apiKey)
+        return texts.map(() => null);
+    try {
+        const response = await fetch("https://api.voyageai.com/v1/embeddings", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model: EMBEDDING_MODEL,
+                input: texts.map(t => t.substring(0, 16000)),
+                output_dimension: EMBEDDING_DIMENSIONS,
+            }),
+        });
+        if (!response.ok)
+            return texts.map(() => null);
+        const data = await response.json();
+        return data.data?.map((d) => d.embedding) || texts.map(() => null);
+    }
+    catch {
+        return texts.map(() => null);
+    }
+}
+// ============================================================
+// KB Directory Management
+// ============================================================
+const KB_DIR = ".kb";
+const SYNC_STATE_FILE = ".sync-state.json";
+function getKBDir(cwd) {
+    return path.join(cwd, KB_DIR);
+}
+function ensureKBDir(cwd) {
+    const kbDir = getKBDir(cwd);
+    if (!fs.existsSync(kbDir)) {
+        fs.mkdirSync(kbDir, { recursive: true });
+    }
+    const ontoDir = path.join(kbDir, "ontology");
+    if (!fs.existsSync(ontoDir)) {
+        fs.mkdirSync(ontoDir, { recursive: true });
+    }
+    return kbDir;
+}
+function readSyncState(cwd) {
+    const statePath = path.join(getKBDir(cwd), SYNC_STATE_FILE);
+    if (fs.existsSync(statePath)) {
+        try {
+            return JSON.parse(fs.readFileSync(statePath, "utf-8"));
+        }
+        catch {
+            // corrupted file
+        }
+    }
+    return { botId: "", lastPull: null, lastPush: null, sharedCount: 0, botCount: 0 };
+}
+function writeSyncState(cwd, state) {
+    const kbDir = ensureKBDir(cwd);
+    fs.writeFileSync(path.join(kbDir, SYNC_STATE_FILE), JSON.stringify(state, null, 2));
+}
+function writeKBFile(cwd, filename, data) {
+    const kbDir = ensureKBDir(cwd);
+    fs.writeFileSync(path.join(kbDir, filename), JSON.stringify(data, null, 2));
+}
+function readKBFile(cwd, filename) {
+    const filePath = path.join(getKBDir(cwd), filename);
+    if (!fs.existsSync(filePath))
+        return [];
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+// ============================================================
+// Database Operations
+// ============================================================
+/**
+ * Get shared KB entries from semo.knowledge_base
+ */
+async function kbPull(pool, botId, domain, cwd) {
+    const client = await pool.connect();
+    try {
+        // Shared KB
+        let sharedQuery = `
+      SELECT domain, key, content, metadata, created_by, version,
+             created_at::text, updated_at::text
+      FROM semo.knowledge_base
+    `;
+        const sharedParams = [];
+        if (domain) {
+            sharedQuery += " WHERE domain = $1";
+            sharedParams.push(domain);
+        }
+        sharedQuery += " ORDER BY domain, key";
+        const sharedResult = await client.query(sharedQuery, sharedParams);
+        const shared = sharedResult.rows;
+        // Bot-specific KB
+        let botQuery = `
+      SELECT bot_id, domain, key, content, metadata, version,
+             synced_at::text, created_at::text, updated_at::text
+      FROM semo.bot_knowledge
+      WHERE bot_id = $1
+    `;
+        const botParams = [botId];
+        if (domain) {
+            botQuery += " AND domain = $2";
+            botParams.push(domain);
+        }
+        botQuery += " ORDER BY domain, key";
+        const botResult = await client.query(botQuery, botParams);
+        const bot = botResult.rows;
+        // Write to local files if cwd provided
+        if (cwd) {
+            writeKBFile(cwd, "team.json", shared);
+            writeKBFile(cwd, "bot.json", bot);
+            const state = readSyncState(cwd);
+            state.botId = botId;
+            state.lastPull = new Date().toISOString();
+            state.sharedCount = shared.length;
+            state.botCount = bot.length;
+            writeSyncState(cwd, state);
+        }
+        return { shared, bot };
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Push local KB entries to database
+ */
+async function kbPush(pool, botId, entries, target = "bot", cwd) {
+    const client = await pool.connect();
+    let upserted = 0;
+    const errors = [];
+    try {
+        await client.query("BEGIN");
+        for (const entry of entries) {
+            try {
+                // Generate embedding for content
+                const embedding = await generateEmbedding(`${entry.key}: ${entry.content}`);
+                const embeddingStr = embedding ? `[${embedding.join(",")}]` : null;
+                if (target === "shared") {
+                    await client.query(`INSERT INTO semo.knowledge_base (domain, key, content, metadata, created_by, embedding)
+             VALUES ($1, $2, $3, $4, $5, $6::vector)
+             ON CONFLICT (domain, key) DO UPDATE SET
+               content = EXCLUDED.content,
+               metadata = EXCLUDED.metadata,
+               embedding = EXCLUDED.embedding`, [entry.domain, entry.key, entry.content, JSON.stringify(entry.metadata || {}), entry.created_by || botId, embeddingStr]);
+                }
+                else {
+                    await client.query(`INSERT INTO semo.bot_knowledge (bot_id, domain, key, content, metadata, synced_at, embedding)
+             VALUES ($1, $2, $3, $4, $5, NOW(), $6::vector)
+             ON CONFLICT (bot_id, domain, key) DO UPDATE SET
+               content = EXCLUDED.content,
+               metadata = EXCLUDED.metadata,
+               synced_at = NOW(),
+               embedding = EXCLUDED.embedding`, [botId, entry.domain, entry.key, entry.content, JSON.stringify(entry.metadata || {}), embeddingStr]);
+                }
+                upserted++;
+            }
+            catch (err) {
+                errors.push(`${entry.domain}/${entry.key}: ${err}`);
+            }
+        }
+        await client.query("COMMIT");
+        if (cwd) {
+            const state = readSyncState(cwd);
+            state.botId = botId;
+            state.lastPush = new Date().toISOString();
+            writeSyncState(cwd, state);
+        }
+    }
+    catch (err) {
+        await client.query("ROLLBACK");
+        errors.push(`Transaction failed: ${err}`);
+    }
+    finally {
+        client.release();
+    }
+    return { upserted, errors };
+}
+/**
+ * Get KB status for a bot
+ */
+async function kbStatus(pool, botId) {
+    const client = await pool.connect();
+    try {
+        // Shared KB stats
+        const sharedStats = await client.query(`
+      SELECT domain, COUNT(*)::int as count
+      FROM semo.knowledge_base
+      GROUP BY domain ORDER BY domain
+    `);
+        const sharedTotal = await client.query(`SELECT COUNT(*)::int as total FROM semo.knowledge_base`);
+        const sharedLastUpdated = await client.query(`SELECT MAX(updated_at)::text as last FROM semo.knowledge_base`);
+        const sharedDomains = {};
+        for (const row of sharedStats.rows) {
+            sharedDomains[row.domain] = row.count;
+        }
+        // Bot KB stats
+        const botStats = await client.query(`
+      SELECT domain, COUNT(*)::int as count
+      FROM semo.bot_knowledge WHERE bot_id = $1
+      GROUP BY domain ORDER BY domain
+    `, [botId]);
+        const botTotal = await client.query(`SELECT COUNT(*)::int as total FROM semo.bot_knowledge WHERE bot_id = $1`, [botId]);
+        const botLastUpdated = await client.query(`SELECT MAX(updated_at)::text as last FROM semo.bot_knowledge WHERE bot_id = $1`, [botId]);
+        const botLastSynced = await client.query(`SELECT MAX(synced_at)::text as last FROM semo.bot_knowledge WHERE bot_id = $1`, [botId]);
+        const botDomains = {};
+        for (const row of botStats.rows) {
+            botDomains[row.domain] = row.count;
+        }
+        return {
+            shared: {
+                total: sharedTotal.rows[0]?.total || 0,
+                domains: sharedDomains,
+                lastUpdated: sharedLastUpdated.rows[0]?.last || null,
+            },
+            bot: {
+                total: botTotal.rows[0]?.total || 0,
+                domains: botDomains,
+                lastUpdated: botLastUpdated.rows[0]?.last || null,
+                lastSynced: botLastSynced.rows[0]?.last || null,
+            },
+        };
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * List KB entries with optional filters
+ */
+async function kbList(pool, options) {
+    const client = await pool.connect();
+    const limit = options.limit || 50;
+    const offset = options.offset || 0;
+    try {
+        // Shared
+        let sharedQuery = "SELECT domain, key, content, metadata, created_by, version, updated_at::text FROM semo.knowledge_base";
+        const sharedParams = [];
+        let paramIdx = 1;
+        if (options.domain) {
+            sharedQuery += ` WHERE domain = $${paramIdx++}`;
+            sharedParams.push(options.domain);
+        }
+        sharedQuery += ` ORDER BY domain, key LIMIT $${paramIdx++} OFFSET $${paramIdx++}`;
+        sharedParams.push(limit, offset);
+        const sharedResult = await client.query(sharedQuery, sharedParams);
+        // Bot
+        let bot = [];
+        if (options.botId) {
+            let botQuery = "SELECT bot_id, domain, key, content, metadata, version, synced_at::text, updated_at::text FROM semo.bot_knowledge WHERE bot_id = $1";
+            const botParams = [options.botId];
+            let bParamIdx = 2;
+            if (options.domain) {
+                botQuery += ` AND domain = $${bParamIdx++}`;
+                botParams.push(options.domain);
+            }
+            botQuery += ` ORDER BY domain, key LIMIT $${bParamIdx++} OFFSET $${bParamIdx++}`;
+            botParams.push(limit, offset);
+            const botResult = await client.query(botQuery, botParams);
+            bot = botResult.rows;
+        }
+        return { shared: sharedResult.rows, bot };
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Diff local KB files against database
+ */
+async function kbDiff(pool, botId, cwd) {
+    const localShared = readKBFile(cwd, "team.json");
+    const localBot = readKBFile(cwd, "bot.json");
+    const localAll = [...localShared, ...localBot];
+    const { shared: remoteShared, bot: remoteBot } = await kbPull(pool, botId);
+    const remoteAll = [...remoteShared, ...remoteBot];
+    const localMap = new Map(localAll.map(e => [`${e.domain}/${e.key}`, e]));
+    const remoteMap = new Map(remoteAll.map(e => [`${e.domain}/${e.key}`, e]));
+    const added = [];
+    const removed = [];
+    const modified = [];
+    let unchanged = 0;
+    // Remote entries not in local → added
+    for (const [k, v] of remoteMap) {
+        if (!localMap.has(k)) {
+            added.push(v);
+        }
+    }
+    // Local entries not in remote → removed
+    for (const [k, v] of localMap) {
+        if (!remoteMap.has(k)) {
+            removed.push(v);
+        }
+    }
+    // Both exist → check content
+    for (const [k, local] of localMap) {
+        const remote = remoteMap.get(k);
+        if (remote) {
+            if (local.content !== remote.content || JSON.stringify(local.metadata) !== JSON.stringify(remote.metadata)) {
+                modified.push({ local, remote });
+            }
+            else {
+                unchanged++;
+            }
+        }
+    }
+    return { added, removed, modified, unchanged };
+}
+/**
+ * Search KB — hybrid: vector similarity (if embedding available) + text fallback
+ */
+async function kbSearch(pool, query, options) {
+    const client = await pool.connect();
+    const limit = options.limit || 10;
+    const mode = options.mode || "hybrid";
+    try {
+        let results = [];
+        // Try semantic search first (if mode allows and embedding API available)
+        if (mode !== "text") {
+            const queryEmbedding = await generateEmbedding(query);
+            if (queryEmbedding) {
+                const embeddingStr = `[${queryEmbedding.join(",")}]`;
+                // Vector search on shared KB
+                let sql = `
+          SELECT domain, key, content, metadata, created_by, version, updated_at::text,
+                 1 - (embedding <=> $1::vector) as score
+          FROM semo.knowledge_base
+          WHERE embedding IS NOT NULL
+        `;
+                const params = [embeddingStr];
+                let paramIdx = 2;
+                if (options.domain) {
+                    sql += ` AND domain = $${paramIdx++}`;
+                    params.push(options.domain);
+                }
+                sql += ` ORDER BY embedding <=> $1::vector LIMIT $${paramIdx++}`;
+                params.push(limit);
+                const sharedResult = await client.query(sql, params);
+                results = sharedResult.rows;
+                // Also search bot_knowledge if botId specified
+                if (options.botId) {
+                    let botSql = `
+            SELECT bot_id, domain, key, content, metadata, version, updated_at::text,
+                   1 - (embedding <=> $1::vector) as score
+            FROM semo.bot_knowledge
+            WHERE bot_id = $2 AND embedding IS NOT NULL
+          `;
+                    const botParams = [embeddingStr, options.botId];
+                    let bIdx = 3;
+                    if (options.domain) {
+                        botSql += ` AND domain = $${bIdx++}`;
+                        botParams.push(options.domain);
+                    }
+                    botSql += ` ORDER BY embedding <=> $1::vector LIMIT $${bIdx++}`;
+                    botParams.push(limit);
+                    const botResult = await client.query(botSql, botParams);
+                    results = [...results, ...botResult.rows]
+                        .sort((a, b) => (b.score || 0) - (a.score || 0))
+                        .slice(0, limit);
+                }
+                // If we got results from semantic search and mode is not hybrid, return
+                if (results.length > 0 && mode === "semantic") {
+                    return results;
+                }
+            }
+        }
+        // Text search (fallback or hybrid supplement)
+        if (mode !== "semantic" || results.length === 0) {
+            let textSql = `
+        SELECT domain, key, content, metadata, created_by, version, updated_at::text,
+               0.0 as score
+        FROM semo.knowledge_base
+        WHERE content ILIKE $1 OR key ILIKE $1
+      `;
+            const textParams = [`%${query}%`];
+            let tIdx = 2;
+            if (options.domain) {
+                textSql += ` AND domain = $${tIdx++}`;
+                textParams.push(options.domain);
+            }
+            textSql += ` ORDER BY updated_at DESC LIMIT $${tIdx++}`;
+            textParams.push(limit);
+            const textResult = await client.query(textSql, textParams);
+            // Merge: deduplicate by domain/key, prefer semantic results
+            const seen = new Set(results.map((r) => `${r.domain}/${r.key}`));
+            for (const row of textResult.rows) {
+                const k = `${row.domain}/${row.key}`;
+                if (!seen.has(k)) {
+                    results.push(row);
+                    seen.add(k);
+                }
+            }
+        }
+        return results.slice(0, limit);
+    }
+    catch {
+        // Ultimate fallback: simple ILIKE
+        let sql = `
+      SELECT domain, key, content, metadata, created_by, version, updated_at::text
+      FROM semo.knowledge_base
+      WHERE content ILIKE $1 OR key ILIKE $1
+    `;
+        const params = [`%${query}%`];
+        let paramIdx = 2;
+        if (options.domain) {
+            sql += ` AND domain = $${paramIdx++}`;
+            params.push(options.domain);
+        }
+        sql += ` ORDER BY updated_at DESC LIMIT $${paramIdx++}`;
+        params.push(limit);
+        const result = await client.query(sql, params);
+        return result.rows;
+    }
+    finally {
+        client.release();
+    }
+}
+// ============================================================
+// Ontology Operations
+// ============================================================
+/**
+ * List all ontology domains
+ */
+async function ontoList(pool) {
+    const client = await pool.connect();
+    try {
+        const result = await client.query(`
+      SELECT domain, schema, description, version, updated_at::text
+      FROM semo.ontology ORDER BY domain
+    `);
+        return result.rows;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Show ontology detail for a domain
+ */
+async function ontoShow(pool, domain) {
+    const client = await pool.connect();
+    try {
+        const result = await client.query(`SELECT domain, schema, description, version, updated_at::text FROM semo.ontology WHERE domain = $1`, [domain]);
+        return result.rows[0] || null;
+    }
+    finally {
+        client.release();
+    }
+}
+/**
+ * Validate KB entries against ontology schema (basic JSON Schema validation)
+ */
+async function ontoValidate(pool, domain, entries) {
+    const onto = await ontoShow(pool, domain);
+    if (!onto) {
+        return { valid: 0, invalid: [{ key: "*", errors: [`Ontology domain '${domain}' not found`] }] };
+    }
+    // If no entries provided, fetch from DB
+    if (!entries) {
+        const client = await pool.connect();
+        try {
+            const result = await client.query(`SELECT domain, key, content, metadata FROM semo.knowledge_base WHERE domain = $1`, [domain]);
+            entries = result.rows;
+        }
+        finally {
+            client.release();
+        }
+    }
+    const schema = onto.schema;
+    const required = schema.required || [];
+    let valid = 0;
+    const invalid = [];
+    for (const entry of entries) {
+        const errors = [];
+        // Check required fields
+        for (const field of required) {
+            if (!entry[field] && entry[field] !== "") {
+                errors.push(`Missing required field: ${field}`);
+            }
+        }
+        // Check metadata schema if defined
+        if (schema.properties?.metadata?.properties && entry.metadata) {
+            const metaSchema = schema.properties.metadata.properties;
+            for (const [propKey, propDef] of Object.entries(metaSchema)) {
+                const def = propDef;
+                const val = entry.metadata[propKey];
+                if (val !== undefined) {
+                    if (def.enum && !def.enum.includes(val)) {
+                        errors.push(`metadata.${propKey}: '${val}' not in allowed values [${def.enum.join(", ")}]`);
+                    }
+                    if (def.type === "string" && typeof val !== "string") {
+                        errors.push(`metadata.${propKey}: expected string, got ${typeof val}`);
+                    }
+                    if (def.type === "array" && !Array.isArray(val)) {
+                        errors.push(`metadata.${propKey}: expected array, got ${typeof val}`);
+                    }
+                }
+            }
+        }
+        if (errors.length > 0) {
+            invalid.push({ key: entry.key, errors });
+        }
+        else {
+            valid++;
+        }
+    }
+    return { valid, invalid };
+}
+/**
+ * Write ontology schemas to local cache
+ */
+async function ontoPullToLocal(pool, cwd) {
+    const domains = await ontoList(pool);
+    const kbDir = ensureKBDir(cwd);
+    const ontoDir = path.join(kbDir, "ontology");
+    for (const d of domains) {
+        fs.writeFileSync(path.join(ontoDir, `${d.domain}.json`), JSON.stringify(d, null, 2));
+    }
+    return domains.length;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-semicolon/semo-cli",
-  "version": "3.14.1",
+  "version": "4.0.0",
   "description": "SEMO CLI - AI Agent Orchestration Framework Installer",
   "main": "dist/index.js",
   "bin": {