@knolo/cli 3.1.3 → 3.2.2

package/README.md

@@ -12,7 +12,7 @@ Global:
 
 ```bash
 npm install -g @knolo/cli
-````
+```
 
 Or use via npx:
 
@@ -112,6 +112,14 @@ This ensures:
 
 ---
 
+## ClaimGraph section compatibility
+
+New `.knolo` packs may include an optional trailing **ClaimGraph** JSON section.
+This section is deterministic, offline-safe, and additive; runtimes that ignore trailing sections remain backward compatible.
+
+---
+
 ## 📄 License
 
-MIT
+MIT
+

package/bin/knolo.mjs

@@ -27,7 +27,7 @@ const DEFAULT_CONFIG = {
 };
 const SUPPORTED_EXTENSIONS = new Set(['.md', '.txt', '.json']);
 const SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
-const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'dev']);
+const SUBCOMMANDS = new Set(['init', 'add', 'build', 'query', 'dev', 'semantic:index', 'semantic:inspect', 'semantic:validate']);
 
 function createError(message) {
   return new Error(message);
@@ -47,7 +47,10 @@ async function tryImport(filePath) {
 }
 
 async function loadCore() {
-  const candidates = ['@knolo/core', path.resolve(__dirname, '../../core/dist/index.js')];
+  const candidates = [
+    path.resolve(__dirname, '../../core/dist/index.js'),
+    '@knolo/core',
+  ];
   for (const candidate of candidates) {
     const mod = await tryImport(candidate);
     if (mod?.buildPack && mod?.mountPack && mod?.query) return mod;
@@ -84,6 +87,9 @@ function printCommandHelp(command) {
     build: 'Usage: knolo build',
     query: 'Usage: knolo query <question> [--pack <path>] [--k <number>] [--json]',
     dev: 'Usage: knolo dev',
+    'semantic:index': 'Usage: knolo semantic:index --pack <path> [--out <path>] [--model <id>] [--endpoint <url>]',
+    'semantic:inspect': 'Usage: knolo semantic:inspect --sidecar <path>',
+    'semantic:validate': 'Usage: knolo semantic:validate --pack <path> --sidecar <path> --model <id>',
   };
   console.log(help[command] ?? 'Unknown command.');
 }
@@ -278,7 +284,9 @@ async function cmdQuery(core, args) {
   const topK = opts.k !== undefined ? Number(opts.k) : (config.query?.topK ?? 5);
   if (!Number.isInteger(topK) || topK <= 0) throw createError('--k must be a positive integer.');
 
-  const kb = await core.mountPack({ src: packPath });
+  const packBuffer = readFileSync(packPath);
+  const bytes = Uint8Array.from(packBuffer);
+  const kb = await mountPackFromBytes(core, bytes);
   const hits = core.query(kb, question, { topK }).map((hit) => ({
     title: kb.headings?.[hit.blockId] || hit.source || `Block ${hit.blockId}`,
     source: hit.source || kb.docIds?.[hit.blockId] || 'unknown',
@@ -308,6 +316,87 @@ async function cmdQuery(core, args) {
   });
 }
 
+function parseKeyValueArgs(args) {
+  const out = {};
+  for (let i = 0; i < args.length; i++) {
+    const key = args[i];
+    if (!key.startsWith('--')) throw createError(`Unexpected argument: ${key}`);
+    out[key.slice(2)] = args[++i];
+  }
+  return out;
+}
+
+async function loadOllamaProvider() {
+  const mod = await tryImport(path.resolve(__dirname, '../../semantic-ollama/dist/index.js'));
+  if (mod?.OllamaEmbeddingProvider) return mod.OllamaEmbeddingProvider;
+  const pkg = await tryImport('@knolo/semantic-ollama');
+  if (pkg?.OllamaEmbeddingProvider) return pkg.OllamaEmbeddingProvider;
+  throw createError('Could not load @knolo/semantic-ollama. Build packages/semantic-ollama first.');
+}
+
+async function cmdSemanticIndex(core, args) {
+  const flags = parseKeyValueArgs(args);
+  const packPath = path.resolve(process.cwd(), flags.pack || 'dist/knowledge.knolo');
+  const outPath = path.resolve(process.cwd(), flags.out || `${packPath}.semantic.json`);
+  const modelId = flags.model || 'qwen3-embedding:4b';
+  const endpoint = flags.endpoint || 'http://localhost:11434';
+  if (!existsSync(packPath)) throw createError(`Pack file not found at ${path.relative(process.cwd(), packPath)}.`);
+
+  const bytes = Uint8Array.from(readFileSync(packPath));
+  const pack = await mountPackFromBytes(core, bytes);
+  const OllamaEmbeddingProvider = await loadOllamaProvider();
+  const provider = new OllamaEmbeddingProvider({ modelId, endpoint });
+  const vectors = await provider.embedTexts(pack.blocks);
+  const sidecar = {
+    version: 1,
+    packFingerprint: core.createPackFingerprint(pack),
+    modelId: provider.modelId,
+    dimension: vectors[0]?.length ?? 0,
+    metric: 'cosine',
+    createdAt: new Date().toISOString(),
+    blocks: vectors.map((vector, blockId) => ({ blockId, vector: Array.from(core.normalizeVector(vector)) })),
+  };
+  writeFileSync(outPath, core.serializeSidecar(sidecar));
+  console.log(`✔ wrote ${path.relative(process.cwd(), outPath)}`);
+}
+
+async function cmdSemanticInspect(core, args) {
+  const flags = parseKeyValueArgs(args);
+  const sidecarPath = path.resolve(process.cwd(), flags.sidecar);
+  const sidecar = core.parseSidecar(readFileSync(sidecarPath, 'utf8'));
+  console.log(JSON.stringify({
+    version: sidecar.version,
+    packFingerprint: sidecar.packFingerprint,
+    modelId: sidecar.modelId,
+    dimension: sidecar.dimension,
+    metric: sidecar.metric,
+    createdAt: sidecar.createdAt,
+    blocks: sidecar.blocks.length,
+  }, null, 2));
+}
+
+async function cmdSemanticValidate(core, args) {
+  const flags = parseKeyValueArgs(args);
+  const packPath = path.resolve(process.cwd(), flags.pack || 'dist/knowledge.knolo');
+  const sidecarPath = path.resolve(process.cwd(), flags.sidecar);
+  const modelId = flags.model;
+  if (!modelId) throw createError('semantic:validate requires --model <id>.');
+  const pack = await mountPackFromBytes(core, Uint8Array.from(readFileSync(packPath)));
+  const sidecar = core.parseSidecar(readFileSync(sidecarPath, 'utf8'));
+  core.validateSidecarForPack({ sidecar, pack, modelId });
+  if (sidecar.blocks.length !== pack.blocks.length) throw createError(`Semantic block count mismatch: sidecar=${sidecar.blocks.length}, pack=${pack.blocks.length}`);
+  if (sidecar.dimension <= 0) throw createError('Semantic sidecar dimension must be > 0.');
+  console.log('✔ semantic sidecar validation passed');
+}
+
+async function mountPackFromBytes(core, bytes) {
+  try {
+    return await core.mountPack({ bytes });
+  } catch {
+    return await core.mountPack({ src: bytes });
+  }
+}
+
 function listDirectoriesRecursively(root) {
   const dirs = [root];
   for (let i = 0; i < dirs.length; i++) {
@@ -585,6 +674,9 @@ async function main() {
       if (command === 'build') return await cmdBuild(core);
       if (command === 'query') return await cmdQuery(core, commandArgs);
       if (command === 'dev') return await cmdDev(core);
+      if (command === 'semantic:index') return await cmdSemanticIndex(core, commandArgs);
+      if (command === 'semantic:inspect') return await cmdSemanticInspect(core, commandArgs);
+      if (command === 'semantic:validate') return await cmdSemanticValidate(core, commandArgs);
     }
 
     if (command.startsWith('-')) throw createError(`Unknown option: ${command}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knolo/cli",
-  "version": "3.1.3",
+  "version": "3.2.2",
   "type": "module",
   "bin": {
     "knolo": "bin/knolo.mjs"
@@ -13,7 +13,7 @@
     "test": "npm run build --prefix ../core && node --test test/cli.test.mjs"
   },
   "dependencies": {
-    "@knolo/core": "^3.1.2"
+    "@knolo/core": "^3.2.0"
   },
   "private": false
 }