@tenphi/akno-core 0.1.0

package/dist/bench.js

@@ -0,0 +1,167 @@
+import { performance } from 'node:perf_hooks';
+import { runMixedRetrievalBench } from "./bench/mixed-retrieval.js";
+export async function runBench(akno, options = {}) {
+    const health = await akno.doctor({ probeModels: false });
+    const iterations = options.iterations !== undefined && Number.isFinite(options.iterations) && options.iterations > 0
+        ? Math.floor(options.iterations)
+        : 12;
+    const notes = [];
+    const queries = [
+        'car insurance renewal',
+        'when does the lease end?',
+        'passport expiry',
+        'anything about the apartment?',
+    ];
+    let queryIndex = 0;
+    const nextQuery = () => queries[queryIndex++ % queries.length];
+    const emptyIndex = () => (health.counts.chunks === 0 ? 'index is empty' : null);
+    const cases = [
+        {
+            // A cold open plus the first query — but with the model stack out
+            // of the path, because this budget is about the database and the assembly.
+            name: 'first query, index path only',
+            budgetMs: 50,
+            iterations: Math.min(iterations, 6),
+            run: () => (options.lexical ?? akno).recall({ query: nextQuery(), mode: 'lookup', budget: 4000 }),
+            skip: () => options.lexical
+                ? emptyIndex()
+                : 'needs a models-off handle — pass `lexical` to measure the index path alone',
+        },
+        {
+            name: 'recall, lexical only',
+            budgetMs: 20,
+            iterations,
+            run: () => (options.lexical ?? akno).recall({ query: nextQuery(), mode: 'lookup', budget: 4000, limit: 5 }),
+            skip: () => options.lexical
+                ? emptyIndex()
+                : 'needs a models-off handle; a configured model makes this not lexical',
+        },
+        {
+            name: 'point lookup by slug',
+            budgetMs: 10,
+            iterations,
+            run: async () => {
+                const listed = await akno.list({ kind: 'pages', limit: 1 });
+                const slug = listed.pages?.[0]?.slug;
+                return slug ? akno.read({ slug }) : null;
+            },
+            skip: () => (health.counts.pages === 0 ? 'index is empty' : null),
+        },
+        {
+            name: 'timeline, 6 month window',
+            budgetMs: 20,
+            iterations,
+            run: () => akno.timeline({ since: '2026-01', limit: 100 }),
+        },
+        {
+            // The stat sweep with no model work: the claim that a restart is not a re-index. Needs the write handle, and says so when it does not have one.
+            name: 'restart -> serving again, nothing changed',
+            budgetMs: 50,
+            iterations: Math.min(iterations, 5),
+            run: () => options.writable.index({ structuralOnly: true }),
+            // Guessing between "someone else has the lock" and "you did not ask for it" sends
+            // the reader looking for a process that may not exist. The handle knows which it is.
+            skip: () => {
+                if (!options.writable)
+                    return 'not measured without a writable handle — rerun with `--write`';
+                if (options.writable.writable)
+                    return null;
+                return options.writable.lockHeldBy !== null
+                    ? `pid ${options.writable.lockHeldBy} holds the write handle`
+                    : 'the write handle could not be taken — check the permissions on the state directory';
+            },
+        },
+        // ── Reported, not asserted: these include a model round trip ──────────────
+        {
+            name: 'recall, hybrid + rerank (includes model time)',
+            budgetMs: null,
+            iterations: Math.min(iterations, 6),
+            modelPath: true,
+            run: () => akno.recall({ query: nextQuery(), mode: 'question', budget: 8000 }),
+            skip: () => (health.counts.chunksEmbedded === 0 ? 'no embeddings in the index' : null),
+        },
+    ];
+    const results = [];
+    for (const benchCase of cases) {
+        const skipped = benchCase.skip?.() ?? null;
+        if (skipped) {
+            results.push({
+                name: benchCase.name,
+                budgetMs: benchCase.budgetMs,
+                p50Ms: 0,
+                p95Ms: 0,
+                samples: 0,
+                // A skipped case is not a pass and not a failure. It is a gap, and the
+                // caller is told which one.
+                passed: true,
+                skipped,
+                ...(benchCase.modelPath ? { modelPath: true } : {}),
+            });
+            continue;
+        }
+        const samples = [];
+        let failures = 0;
+        // One untimed warm-up: the first call pays for statement preparation, and a
+        // budget that includes it measures SQLite's compiler, not the query.
+        await benchCase.run().catch(() => failures++);
+        for (let i = 0; i < benchCase.iterations; i++) {
+            const started = performance.now();
+            // A case whose op throws every time must not report a fast, green row.
+            await benchCase.run().catch(() => failures++);
+            samples.push(performance.now() - started);
+        }
+        if (failures > benchCase.iterations / 2) {
+            results.push({
+                name: benchCase.name,
+                budgetMs: benchCase.budgetMs,
+                p50Ms: 0,
+                p95Ms: 0,
+                samples: 0,
+                passed: false,
+                skipped: `the operation failed ${failures} times — the timing would be meaningless`,
+                ...(benchCase.modelPath ? { modelPath: true } : {}),
+            });
+            continue;
+        }
+        samples.sort((a, b) => a - b);
+        const p50 = percentile(samples, 0.5);
+        results.push({
+            name: benchCase.name,
+            budgetMs: benchCase.budgetMs,
+            p50Ms: round(p50),
+            p95Ms: round(percentile(samples, 0.95)),
+            samples: samples.length,
+            passed: benchCase.budgetMs === null || p50 <= benchCase.budgetMs,
+            ...(benchCase.modelPath ? { modelPath: true } : {}),
+        });
+    }
+    const modelPath = results.find((result) => result.modelPath && result.samples > 0);
+    const indexPath = results.find((result) => result.name === 'recall, lexical only' && result.samples > 0);
+    if (modelPath && indexPath) {
+        notes.push(`the model stack accounts for about ${round(modelPath.p50Ms - indexPath.p50Ms)}ms of the ` +
+            `${modelPath.p50Ms}ms hybrid path — which is why it is reported and not budgeted`);
+    }
+    for (const skippedCase of results.filter((result) => result.skipped)) {
+        notes.push(`${skippedCase.name}: ${skippedCase.skipped}`);
+    }
+    const retrieval = await runMixedRetrievalBench({ iterations });
+    return {
+        results,
+        retrieval,
+        // Asserted index budgets and fixed-corpus quality decide the verdict. A slow
+        // configured model is still only reported, because it is not this code.
+        passed: results.every((result) => result.budgetMs === null || result.passed) && retrieval.passed,
+        pages: health.counts.pages,
+        chunks: health.counts.chunks,
+        notes,
+    };
+}
+function percentile(sorted, fraction) {
+    if (sorted.length === 0)
+        return 0;
+    return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * fraction))];
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}
+//# sourceMappingURL=bench.js.map

package/dist/bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench.js","sourceRoot":"","sources":["../src/bench.ts"],"names":[],"mappings":"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"}

package/dist/config/jsonc.d.ts

@@ -0,0 +1,8 @@
+export declare function parseJsonc<T = unknown>(content: string, label?: string): T;
+/**
+ * Returns null when the file is absent, and throws when it exists but is
+ * malformed. A config file that silently reverts to defaults because of a
+ * missing brace is a very expensive kind of quiet.
+ */
+export declare function readJsoncFile<T = unknown>(filePath: string): T | null;
+//# sourceMappingURL=jsonc.d.ts.map

package/dist/config/jsonc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonc.d.ts","sourceRoot":"","sources":["../../src/config/jsonc.ts"],"names":[],"mappings":"AA8DA,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,CAAC,CAU9E;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CASrE"}

package/dist/config/jsonc.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+/**
+ * Minimal JSONC reader: strips `//` and block comments, then JSON.parse.
+ * Comments matter here — the committed default config is documentation as much
+ * as configuration, and a format that cannot hold a comment forces that
+ * explanation somewhere the reader will not be looking.
+ */
+function stripJsonComments(input) {
+    let out = '';
+    let i = 0;
+    const len = input.length;
+    while (i < len) {
+        const ch = input[i];
+        const next = input[i + 1];
+        if (ch === '"') {
+            out += ch;
+            i++;
+            while (i < len) {
+                const c = input[i];
+                out += c;
+                if (c === '\\' && i + 1 < len) {
+                    out += input[i + 1];
+                    i += 2;
+                    continue;
+                }
+                if (c === '"') {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+        if (ch === '/' && next === '/') {
+            i += 2;
+            while (i < len && input[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            i += 2;
+            while (i < len - 1 && !(input[i] === '*' && input[i + 1] === '/'))
+                i++;
+            i += 2;
+            continue;
+        }
+        out += ch;
+        i++;
+    }
+    return out;
+}
+/** Trailing commas are legal in JSONC and a constant nuisance in a hand-edited file. */
+function stripTrailingCommas(input) {
+    return input.replace(/,(\s*[}\]])/g, '$1');
+}
+export function parseJsonc(content, label = '<string>') {
+    try {
+        return JSON.parse(stripTrailingCommas(stripJsonComments(content)));
+    }
+    catch (err) {
+        throw new Error(`${label} is not valid JSON/JSONC: ${err instanceof Error ? err.message : String(err)}`, {
+            // The original carries the offset of the offending character, which is the
+            // only part of a JSON syntax error worth having.
+            cause: err,
+        });
+    }
+}
+/**
+ * Returns null when the file is absent, and throws when it exists but is
+ * malformed. A config file that silently reverts to defaults because of a
+ * missing brace is a very expensive kind of quiet.
+ */
+export function readJsoncFile(filePath) {
+    let content;
+    try {
+        content = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    return parseJsonc(content, filePath);
+}
+//# sourceMappingURL=jsonc.js.map

package/dist/config/jsonc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonc.js","sourceRoot":"","sources":["../../src/config/jsonc.ts"],"names":[],"mappings":"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"}

package/dist/config/load.d.ts

@@ -0,0 +1,43 @@
+import { ConfigDoc, type AknoConfig } from './schema.ts';
+/**
+ * The rules file that travels with the notes. Named here rather than inline because
+ * the indexer has to know to skip it: it lives *inside* the knowledge base but is Akno's
+ * own configuration, and indexing it files the taxonomy as a memory object.
+ */
+export declare const KB_RULES_FILE = "akno.jsonc";
+/** Keep every whole-tree reader on the indexer's exact configured file scope. */
+export declare function indexScanIgnore(configured: readonly string[]): string[];
+export interface LoadOptions {
+    /** Wins over every file, for `open({ aknoPath })` and `--akno-path`. */
+    aknoPath?: string;
+    stateDir?: string;
+    /**
+     * Skip `config/local.jsonc` and `~/.akno/config.json`, leaving committed
+     * defaults plus env. Also settable with `AKNO_ISOLATED=1`, which is how CI
+     * keeps a developer's local overlay out of a test run.
+     */
+    isolated?: boolean;
+    /** Extra overlay applied last, above env. Used by tests and one-shot CLI flags. */
+    overrides?: ConfigDoc;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Config is assembled from four layers, lowest precedence first — which is also what the
+ * repo's gitignore strategy is built around:
+ *
+ *   1. `config/default.jsonc`       committed, machine-independent, every key
+ *   2. `~/.akno/config.json`      the installed machine's own config
+ *   3. `config/local.jsonc`         gitignored dev overlay for this checkout
+ *   4. `AKNO_*` environment       for containers and CI
+ *
+ * Secrets are the one thing no config layer holds. A config file names the variable that carries a
+ * credential, never the credential, so it stays safe to read, diff and paste. The variables
+ * themselves come from the environment, or from a gitignored `.env` beside the config — loaded
+ * here rather than by a launcher, because a service started by launchd inherits almost nothing and
+ * "put it in .env" has to be true for the person who read that in `.env.example`.
+ *
+ * Rules are a fifth, narrower layer: `<akno_path>/akno.jsonc` wins over all
+ * of the above for `folders`, so rules can travel with the notes.
+ */
+export declare function loadConfig(options?: LoadOptions): AknoConfig;
+//# sourceMappingURL=load.d.ts.map

package/dist/config/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,SAAS,EAET,KAAK,UAAU,EAOhB,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,eAAO,MAAM,aAAa,eAAe,CAAC;AAG1C,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAEvE;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mFAAmF;IACnF,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CAqEhE"}