@tenphi/akno-core 0.1.0

package/dist/write/remember-fallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remember-fallback.js","sourceRoot":"","sources":["../../src/write/remember-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,kBAAkB,CAAC;AACnC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAA2B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAS5C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,GAAgB,EAChB,UAAgC,aAAa,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC;IAEpE,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,YAAY,CAAC;IACxD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;IAElG,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,4DAA4D,CAAC,CAAC,GAAG,CAAC,IAAI,CAC5C,CAAC;IAC5D,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,mBAAmB,KAAK,WAAW;YACxE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,eAAe,EAAE;YACnC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,4BAA4B,EAAE,CAAC;IAC5E,CAAC;IAED,0GAA0G;IAC1G,wFAAwF;IACxF,IAAI,MAAM,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;QACxC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAC1E,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAC3B,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,IAAI,KAAK,MAAM;QACtB,MAAM,CAAC,IAAI,KAAK,WAAW;QAC3B,MAAM,CAAC,QAAQ,KAAK,WAAW;QAC/B,MAAM,CAAC,SAAS,CACnB,CAAC;IACF,OAAO,QAAQ;QACb,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE;QAC9B,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;AACrE,CAAC;AAED,KAAK,UAAU,kBAAkB,CAAC,GAAgB,EAAE,IAAY;IAC9D,KAAK,MAAM,SAAS,IAAI,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QAClD,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE;gBAAE,OAAO,IAAI,CAAC;QACpG,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;QACtE,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/write/retain.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { type ModelClient } from '../models/client.ts';
+import type { FolderCatalogEntry } from '../kb/folders.ts';
+/**
+ * `page` is nullable rather than optional, and the prompt above says "null" rather than "omit"
+ * for the same reason: OpenAI's strict mode rejects an optional property outright, and a schema
+ * it rejects takes this call site off constrained decoding silently — the fallback to a plain
+ * JSON request looks exactly like success. Nullable says the same thing and stays enforceable.
+ *
+ * The guards this cannot express stay downstream regardless: `cleanCandidates` drops
+ * speculation, fragments, and any page whose folder is not one that actually exists.
+ */
+export declare const RETAIN_SCHEMA: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        subject: z.ZodString;
+        page: z.ZodNullable<z.ZodString>;
+        origin: z.ZodEnum<{
+            user: "user";
+            assistant: "assistant";
+        }>;
+        evidence: z.ZodNullable<z.ZodString>;
+        kind: z.ZodString;
+    }, z.core.$strip>>;
+    events: z.ZodArray<z.ZodObject<{
+        date: z.ZodString;
+        summary: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export interface RetainCandidate {
+    text: string;
+    subject: string;
+    kind: string;
+    /**
+     * Where this would go if no page holds it yet. A suggestion, used only when routing finds
+     * nothing — which is the case `remember` used to have no answer for at all.
+     */
+    page?: string;
+    origin?: 'user' | 'assistant';
+    /** Exact bounded input bytes retained privately so the managed sentence can be re-verified. */
+    evidence?: string;
+}
+export interface RetainResult {
+    candidates: RetainCandidate[];
+    events: {
+        date: string;
+        summary: string;
+    }[];
+    error: string | null;
+}
+export declare function runRetain(text: string, model: ModelClient, options?: {
+    mission?: string;
+    today: string;
+    folders?: FolderCatalogEntry[];
+}): Promise<RetainResult>;
+export declare function cleanCandidates(value: unknown, options?: {
+    folders?: readonly string[];
+    pages?: readonly string[];
+    sourceText?: string;
+}): RetainCandidate[];
+//# sourceMappingURL=retain.d.ts.map

package/dist/write/retain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retain.d.ts","sourceRoot":"","sources":["../../src/write/retain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAmE3D;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;iBAYxB,CAAC;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC5C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,EAClB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAA;CAEzE,GACA,OAAO,CAAC,YAAY,CAAC,CAkCvB;AA0DD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5F,eAAe,EAAE,CAsCnB"}

package/dist/write/retain.js

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import { parseJsonLoose } from "../models/client.js";
+/**
+ * **Retain: keep only long-term facts, decisions, preferences, proven
+ * experience.**
+ *
+ * **Retain writes prose, not atomic facts** — it is a
+ * page-level curator that edits the right page, and facts are derived beneath it.
+ * So a candidate here is a sentence someone would actually write on a page, not a
+ * triple.
+ *
+ * The guardrail about missions applies: a mission string appends emphasis to a
+ * fixed system prompt and never replaces it. A replaceable prompt is how every
+ * guard gets lost.
+ */
+const SYSTEM = `You decide what from a conversation is worth writing into a long-term personal knowledge base, and phrase it as prose.
+
+Reply with JSON only:
+{
+  "candidates": [
+    { "text": "one self-contained sentence, phrased as it should appear on a page",
+      "subject": "2-5 words naming what this is about, used to find the right page",
+      "page": "folder/page-name",
+      "origin": "user or assistant — whose statement established the claim",
+      "evidence": "one exact verbatim quote from the input that supports the sentence, or null",
+      "kind": "fact" }
+  ],
+  "events": [ { "date": "YYYY-MM-DD", "summary": "what happened, one clause" } ]
+}
+
+Keep:
+- Durable values, dates, identifiers, account details, measurements.
+- Decisions, and the reason for them.
+- Stated preferences and constraints.
+- Proven experience: what was tried, what worked.
+- Findings the assistant established and stated as true: what a thing is, how it works,
+  what it costs, which options exist and how they differ. A finding is not a suggestion.
+
+Drop, always:
+- Anything true only today: what someone is doing right now, transient state, and any
+  reading that expires on its own — prices, weather, availability, rates, live status.
+- Questions, speculation, plans that were not decided.
+- Pleasantries, acknowledgements, and anything the assistant merely proposed or offered.
+- Anything already obviously recorded — do not restate.
+- Anything you inferred rather than were told. Only what the text actually says.
+
+Rules:
+- Prose, not triples. "The car insurance premium is now 33 EUR a month" — not "premium=33".
+- Resolve pronouns and relative dates against the text. Never invent a date you were not given.
+- Evidence must be copied byte-for-byte from the input, stay under 1200 characters, and contain
+  enough context to verify every durable value in the candidate. Use null when no exact quote does.
+- An "events" entry is something that happened on a date, not a value that is true.
+- "page" is a slug and nothing else: lowercase, hyphenated, no description, no punctuation beyond
+  the single "/" between folder and page. Every other field above takes prose, so its example
+  doubles as instructions — for this one that is a filename, and a model that copies the wording
+  through writes a page named after it. Observed: a whole trip route filed under
+  "ada-marlow/projects-taxonomy-branch-and-fallback-page-lowercase-and-hyphenated".
+- Always supply "page" when one of the supplied folders marked eligible=true fits. When the folder
+  is creatable, its parent must be that exact folder. When it is read-only and lists admitted_pages,
+  use only one exact listed page; never invent another page there. Never invent, rename or translate
+  a folder. If none fits, set "page" to null. A finding established by the assistant is canonical
+  knowledge with assistant provenance; it still belongs in the subject's taxonomy branch, not a
+  personal page.
+- Fewer, better. An empty candidates list is the correct answer for a conversation
+  that decided nothing, and is much better than a vague one.`;
+/**
+ * `page` is nullable rather than optional, and the prompt above says "null" rather than "omit"
+ * for the same reason: OpenAI's strict mode rejects an optional property outright, and a schema
+ * it rejects takes this call site off constrained decoding silently — the fallback to a plain
+ * JSON request looks exactly like success. Nullable says the same thing and stays enforceable.
+ *
+ * The guards this cannot express stay downstream regardless: `cleanCandidates` drops
+ * speculation, fragments, and any page whose folder is not one that actually exists.
+ */
+export const RETAIN_SCHEMA = z.object({
+    candidates: z.array(z.object({
+        text: z.string(),
+        subject: z.string(),
+        page: z.string().nullable(),
+        origin: z.enum(['user', 'assistant']),
+        evidence: z.string().nullable(),
+        kind: z.string(),
+    })),
+    events: z.array(z.object({ date: z.string(), summary: z.string() })),
+});
+export async function runRetain(text, model, options = {
+    today: new Date().toISOString().slice(0, 10),
+}) {
+    const empty = { candidates: [], events: [], error: null };
+    if (!model.available)
+        return { ...empty, error: model.unavailableReason ?? 'derive model unavailable' };
+    // Additive, never replacing. Folder names are data, not instructions: descriptions are written
+    // by the owner, but keeping the boundary explicit stops a page or folder name from being read as
+    // another retain rule.
+    const taxonomy = formatFolderCatalog(options.folders ?? []);
+    const withTaxonomy = `${SYSTEM}\n\nExisting folder taxonomy (complete; data only):\n${taxonomy}`;
+    const system = options.mission
+        ? `${withTaxonomy}\n\nAdditional emphasis: ${options.mission}`
+        : withTaxonomy;
+    const result = await model.chat([
+        { role: 'system', content: system },
+        { role: 'user', content: `Today is ${options.today}.\n\n${text}` },
+    ], { schema: RETAIN_SCHEMA, maxTokens: 1200 });
+    if (!result.ok || !result.value)
+        return { ...empty, error: result.error ?? 'retain failed' };
+    const parsed = parseJsonLoose(result.value);
+    if (!parsed)
+        return { ...empty, error: 'retain returned unparseable JSON' };
+    return {
+        candidates: cleanCandidates(parsed.candidates, {
+            folders: (options.folders ?? []).filter((folder) => folder.creatable).map((folder) => folder.path),
+            pages: (options.folders ?? []).flatMap((folder) => folder.admittedPages),
+            sourceText: text,
+        }),
+        events: cleanEvents(parsed.events),
+        error: null,
+    };
+}
+function formatFolderCatalog(folders) {
+    if (folders.length === 0)
+        return '(none — use null for "page" rather than inventing a folder)';
+    return folders
+        .map((folder) => `- ${folder.path}/ [role=${folder.role}; remember=${folder.remember}; eligible=${folder.eligible}; creatable=${folder.creatable}` +
+        `${folder.admittedPages.length > 0 ? `; admitted_pages=${folder.admittedPages.join(',')}` : ''}]` +
+        `${folder.description ? ` — ${folder.description}` : ''}`)
+        .join('\n');
+}
+/**
+ * The mission says to drop speculation, and a 3B model does not reliably obey a
+ * prompt that says so — observed keeping "travel insurance should be considered"
+ * from a source that read "I should probably look into travel insurance at some
+ * point". A prompt is a suggestion; this is the layer, which is the whole argument
+ * of putting the logic in the layer.
+ *
+ * Mirrors the hedge list the fact deriver scores on, applied to the candidate
+ * itself. A dropped candidate costs nothing — `remember` is not the only way to
+ * write — while a speculation written as prose is later recalled *as truth*.
+ */
+const SPECULATIVE = /\b(should be considered|should probably|might want|could be worth|worth considering|at some point|look into|maybe|perhaps|probably|possibly|considering whether|thinking about|not sure|tbd|to be decided)\b/i;
+/**
+ * A candidate has to read as a **statement, not a topic** — "hotel bill" is not something a
+ * page can say.
+ *
+ * This was a whitelist of forty verbs, and a whitelist is the wrong shape for this test. Every
+ * sentence built on a verb nobody thought of was dropped in silence: "the Vision framework
+ * OCRs a page in about 0.6 seconds" states a fact and contains no word on that list. The
+ * failure fell hardest on exactly the material this pass is worst at keeping — findings about
+ * the world, which are phrased with the vocabulary of whatever they are about, while a claim
+ * about a household reuses the same dozen verbs forever.
+ *
+ * So the test is structural instead. A statement has a subject and something predicated of it:
+ * at least two words before a verb-shaped token, and a verb-shaped token that is not the first
+ * word (an imperative is an instruction, not a claim). Copulas and auxiliaries are still named
+ * because they are irregular and no suffix rule reaches them.
+ */
+const COPULA = /\b(is|are|was|were|has|have|had|will|would|does|do|did|can|may|must|should)\b/i;
+const VERB_SHAPED = /\b\w{3,}(?:s|ed|es)\b/i;
+function readsAsStatement(text) {
+    const words = text.split(/\s+/);
+    if (words.length < 4)
+        return false;
+    if (COPULA.test(text))
+        return true;
+    // Past the first word: "Book the hotel" is an instruction, and an instruction on a page is
+    // read back later as something the household decided.
+    const rest = words.slice(1).join(' ');
+    return VERB_SHAPED.test(rest);
+}
+export function cleanCandidates(value, options = {}) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        const text = typeof record.text === 'string' ? record.text.trim().replace(/\s+/g, ' ') : '';
+        // A one-word "candidate" is the same fragment problem the fact deriver has:
+        // it cannot be read on the page it lands on.
+        if (text.split(/\s+/).length < 4 || text.length > 400)
+            continue;
+        // Speculation, however confidently the model phrased it.
+        if (SPECULATIVE.test(text))
+            continue;
+        if (!readsAsStatement(text))
+            continue;
+        const key = text.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const cleanedPage = typeof record.page === 'string' ? cleanSlug(record.page) : null;
+        const page = cleanedPage && pageIsAdmitted(cleanedPage, options.folders, options.pages) ? cleanedPage : null;
+        const evidence = exactCandidateEvidence(record.evidence, options.sourceText);
+        out.push({
+            text,
+            subject: typeof record.subject === 'string' && record.subject.trim().length > 0
+                ? record.subject.trim()
+                : text.slice(0, 60),
+            kind: typeof record.kind === 'string' ? record.kind : 'fact',
+            ...(record.origin === 'user' || record.origin === 'assistant' ? { origin: record.origin } : {}),
+            ...(page ? { page } : {}),
+            ...(evidence ? { evidence } : {}),
+        });
+        if (out.length >= 12)
+            break;
+    }
+    return out;
+}
+function exactCandidateEvidence(value, sourceText) {
+    if (typeof value !== 'string' || sourceText === undefined)
+        return null;
+    const evidence = value.trim();
+    if (evidence.length === 0 || evidence.length > 1200 || evidence.includes('\0'))
+        return null;
+    return sourceText.includes(evidence) ? evidence : null;
+}
+/** The immediate parent is the filing decision; every deeper segment would be an invented folder. */
+function pageIsAdmitted(page, folders, pages) {
+    if (folders === undefined && pages === undefined)
+        return true;
+    if (pages?.includes(page))
+        return true;
+    const parent = page.slice(0, page.lastIndexOf('/'));
+    return folders?.includes(parent) ?? false;
+}
+/**
+ * A model's idea of a slug, made safe to hand to `write`.
+ *
+ * Deliberately lossy rather than strict: a suggestion that cannot be cleaned into a usable
+ * slug is dropped, and routing falls back to asking. A slug is a filename, and the one thing
+ * that must not happen is a model naming a path.
+ */
+function cleanSlug(raw) {
+    const slug = raw
+        .trim()
+        .toLowerCase()
+        .replace(/\.(md|markdown)$/i, '')
+        .replace(/[^a-z0-9/\-_ ]+/g, '')
+        .replace(/\s+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .split('/')
+        .map((segment) => segment.replace(/^-+|-+$/g, ''))
+        .filter((segment) => segment.length > 0 && segment !== '.' && segment !== '..')
+        .join('/');
+    // One segment is a page at the root of the knowledge base, which is almost never what was
+    // meant and is the hardest kind of mess to tidy up later.
+    return slug.includes('/') && slug.length <= 120 ? slug : null;
+}
+function cleanEvents(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        const date = typeof record.date === 'string' ? record.date.trim() : '';
+        const summary = typeof record.summary === 'string' ? record.summary.trim().replace(/\s+/g, ' ') : '';
+        // An event with an invented or malformed date is worse than no event: it will
+        // sort into the ledger somewhere nobody expects.
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(date))
+            continue;
+        if (summary.length < 4 || summary.length > 300)
+            continue;
+        out.push({ date, summary });
+        if (out.length >= 8)
+            break;
+    }
+    return out;
+}
+//# sourceMappingURL=retain.js.map

package/dist/write/retain.js.map

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@tenphi/akno-core",
+  "version": "0.1.0",
+  "description": "Akno — the memory layer itself: index, ops, watcher, models",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "config",
+    "swift"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^12.4.1",
+    "sqlite-vec": "^0.1.9",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3",
+    "@tenphi/akno-protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12"
+  },
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tenphi/akno.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/tenphi/akno#readme",
+  "bugs": {
+    "url": "https://github.com/tenphi/akno/issues"
+  },
+  "author": "Andrey Yamanov",
+  "scripts": {}
+}

package/swift/extract.swift

@@ -0,0 +1,232 @@
+// Akno's text extractor, built on what macOS already has.
+//
+// Extraction happens on arrival, always — text layer first, OCR for scans. The
+// usual way to get that is `brew install poppler tesseract`, which makes a memory
+// layer's first-run experience depend on two unrelated projects being installed and
+// on their CLI flags not changing.
+//
+// macOS ships both capabilities: PDFKit reads a text layer, and Vision does OCR that
+// is faster and more accurate than tesseract, hardware-accelerated, and offline.
+// Since Akno is macOS-only on purpose (see README), using the platform's own
+// frameworks is the honest choice rather than a shortcut.
+//
+// Compiled on first use and cached in the state directory. Output is JSON on stdout
+// so the caller never parses prose.
+
+import Foundation
+import PDFKit
+import Vision
+import CoreGraphics
+import ImageIO
+
+/// One page's worth of text, so a citation can name the page it came from.
+///
+/// A card points at the page, the document, **and the page number within it**.
+/// One joined blob cannot support that last part, and a quote from page 9 of a contract
+/// attributed to no page is a citation a reader cannot check.
+struct Section: Encodable {
+    var page: Int
+    var text: String
+}
+
+struct Result: Encodable {
+    var text: String
+    var pages: Int
+    var ocr: Bool
+    /// Vision's own mean confidence over recognised lines, 0..1. Absent for a text
+    /// layer, where there is nothing to be unsure about.
+    var confidence: Double?
+    var sections: [Section]?
+    var error: String?
+}
+
+func emit(_ result: Result) -> Never {
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = []
+    if let data = try? encoder.encode(result), let json = String(data: data, encoding: .utf8) {
+        print(json)
+    } else {
+        print("{\"text\":\"\",\"pages\":0,\"ocr\":false,\"error\":\"could not encode result\"}")
+    }
+    exit(0)
+}
+
+func fail(_ message: String) -> Never {
+    emit(Result(text: "", pages: 0, ocr: false, confidence: nil, sections: nil, error: message))
+}
+
+/// Vision text recognition over one image. `accurate` rather than `fast`: this runs
+/// once per document ever, and a wrong character in a policy number is permanent.
+func recognise(_ image: CGImage) -> (String, Double)? {
+    let request = VNRecognizeTextRequest()
+    request.recognitionLevel = .accurate
+    request.usesLanguageCorrection = true
+    // Documents in this knowledge base are mixed-language; leaving the list broad
+    // costs nothing measurable and stops a Dutch contract being read as English.
+    if #available(macOS 13.0, *) {
+        request.revision = VNRecognizeTextRequestRevision3
+    }
+    request.recognitionLanguages = ["en-US", "nl-NL", "de-DE", "fr-FR", "es-ES", "ru-RU"]
+
+    let handler = VNImageRequestHandler(cgImage: image, options: [:])
+    do {
+        try handler.perform([request])
+    } catch {
+        return nil
+    }
+
+    guard let observations = request.results, !observations.isEmpty else { return ("", 0) }
+
+    var lines: [String] = []
+    var total = 0.0
+    for observation in observations {
+        guard let candidate = observation.topCandidates(1).first else { continue }
+        lines.append(candidate.string)
+        total += Double(candidate.confidence)
+    }
+    let mean = observations.isEmpty ? 0 : total / Double(observations.count)
+    return (lines.joined(separator: "\n"), mean)
+}
+
+func loadImage(_ path: String) -> CGImage? {
+    guard let source = CGImageSourceCreateWithURL(URL(fileURLWithPath: path) as CFURL, nil) else {
+        return nil
+    }
+    return CGImageSourceCreateImageAtIndex(source, 0, nil)
+}
+
+/// Renders a PDF page for OCR. 2x is the sweet spot: enough resolution for Vision to
+/// read small print, without the memory cost of rendering a 300dpi bitmap per page.
+func render(_ page: PDFPage, scale: CGFloat = 2.0) -> CGImage? {
+    let bounds = page.bounds(for: .mediaBox)
+    let width = Int(bounds.width * scale)
+    let height = Int(bounds.height * scale)
+    guard width > 0, height > 0, width * height < 40_000_000 else { return nil }
+
+    guard
+        let context = CGContext(
+            data: nil,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: 0,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue
+        )
+    else { return nil }
+
+    context.setFillColor(CGColor(red: 1, green: 1, blue: 1, alpha: 1))
+    context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    context.scaleBy(x: scale, y: scale)
+    page.draw(with: .mediaBox, to: context)
+    return context.makeImage()
+}
+
+// ─── Entry ──────────────────────────────────────────────────────────────────
+
+let arguments = CommandLine.arguments
+guard arguments.count >= 3 else {
+    fail("usage: akno-extract <pdf|image> <path> [--ocr-pages N] [--force-ocr]")
+}
+
+let mode = arguments[1]
+let path = arguments[2]
+var maxOcrPages = 12
+var forceOcr = false
+var index = 3
+while index < arguments.count {
+    if arguments[index] == "--ocr-pages", index + 1 < arguments.count {
+        maxOcrPages = Int(arguments[index + 1]) ?? maxOcrPages
+        index += 2
+    } else if arguments[index] == "--force-ocr" {
+        forceOcr = true
+        index += 1
+    } else {
+        index += 1
+    }
+}
+
+guard FileManager.default.fileExists(atPath: path) else { fail("no such file: \(path)") }
+
+switch mode {
+case "image":
+    guard let image = loadImage(path) else { fail("could not decode the image") }
+    guard let (text, confidence) = recognise(image) else { fail("Vision could not run") }
+    emit(
+        Result(
+            text: text,
+            pages: 1,
+            ocr: true,
+            confidence: confidence,
+            sections: [Section(page: 1, text: text)],
+            error: nil
+        )
+    )
+
+case "pdf":
+    guard let document = PDFDocument(url: URL(fileURLWithPath: path)) else {
+        fail("could not open the PDF")
+    }
+    let pageCount = document.pageCount
+
+    // Text layer first, and that order is not arbitrary: a real text layer is exact,
+    // while OCR of the same page is a guess that happens to be usually right.
+    if !forceOcr, let layer = document.string {
+        let trimmed = layer.trimmingCharacters(in: .whitespacesAndNewlines)
+        // A scanned PDF often carries a few stray characters — a stamp, a page
+        // number — which is not a text layer. Judged per page so a 40-page scan
+        // with one typed cover sheet still gets OCR'd.
+        let perPage = pageCount > 0 ? trimmed.count / pageCount : trimmed.count
+        if perPage >= 40 {
+            // Page by page as well as joined: the join is what a summary reads, the
+            // sections are what a citation points into.
+            var sections: [Section] = []
+            for pageIndex in 0..<pageCount {
+                guard let page = document.page(at: pageIndex), let pageText = page.string else { continue }
+                let pageTrimmed = pageText.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !pageTrimmed.isEmpty { sections.append(Section(page: pageIndex + 1, text: pageTrimmed)) }
+            }
+            emit(
+                Result(
+                    text: trimmed,
+                    pages: pageCount,
+                    ocr: false,
+                    confidence: nil,
+                    sections: sections.isEmpty ? nil : sections,
+                    error: nil
+                )
+            )
+        }
+    }
+
+    // No usable text layer: it is a scan. OCR a bounded number of pages — a 200-page
+    // contract does not need every page to be searchable to be findable, and the
+    // caller is told how many were read.
+    var sections: [Section] = []
+    var confidenceTotal = 0.0
+    var read = 0
+    for pageIndex in 0..<min(pageCount, maxOcrPages) {
+        guard let page = document.page(at: pageIndex), let image = render(page) else { continue }
+        guard let (text, confidence) = recognise(image) else { continue }
+        if !text.isEmpty {
+            sections.append(Section(page: pageIndex + 1, text: text))
+            confidenceTotal += confidence
+            read += 1
+        }
+    }
+
+    let mean = read > 0 ? confidenceTotal / Double(read) : 0
+    emit(
+        Result(
+            text: sections.map(\.text).joined(separator: "\n\n"),
+            pages: pageCount,
+            ocr: true,
+            confidence: mean,
+            sections: sections.isEmpty ? nil : sections,
+            error: nil
+        )
+    )
+
+default:
+    fail("unknown mode: \(mode)")
+}