@knolo/core 3.1.2

package/dist/routing_profile.js

@@ -0,0 +1,102 @@
+const MAX_DISCOVERABILITY_ITEMS = 20;
+export function getAgentRoutingProfileV1(agent) {
+    const metadata = agent.metadata ?? {};
+    const heading = getStringMetadata(metadata, 'heading');
+    const namespace = getPrimaryNamespace(agent);
+    return {
+        agentId: agent.id,
+        namespace,
+        heading,
+        description: agent.description,
+        tags: parseDiscoverabilityList(metadata.tags),
+        examples: parseDiscoverabilityList(metadata.examples),
+        capabilities: parseDiscoverabilityList(metadata.capabilities),
+        toolPolicy: agent.toolPolicy,
+        toolPolicySummary: summarizeToolPolicy(agent.toolPolicy),
+    };
+}
+export function getPackRoutingProfilesV1(pack) {
+    const agents = pack.meta.agents?.agents ?? [];
+    return agents.map((agent) => getAgentRoutingProfileV1(agent));
+}
+function getPrimaryNamespace(agent) {
+    const first = agent.retrievalDefaults.namespace[0];
+    if (typeof first === 'string' && first.trim()) {
+        return first;
+    }
+    return undefined;
+}
+function getStringMetadata(metadata, key) {
+    const value = metadata[key];
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim();
+    return normalized ? normalized : undefined;
+}
+function parseDiscoverabilityList(value) {
+    if (typeof value !== 'string')
+        return [];
+    const raw = value.trim();
+    if (!raw)
+        return [];
+    let parsed;
+    if (raw.startsWith('[')) {
+        parsed = parseJsonArrayString(raw);
+    }
+    else if (raw.includes('\n')) {
+        parsed = raw.split('\n');
+    }
+    else {
+        parsed = raw.split(',');
+    }
+    const deduped = [];
+    const seen = new Set();
+    for (const item of parsed) {
+        const normalized = item.trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        deduped.push(normalized);
+        if (deduped.length >= MAX_DISCOVERABILITY_ITEMS)
+            break;
+    }
+    return deduped;
+}
+function parseJsonArrayString(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((item) => typeof item === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+function summarizeToolPolicy(policy) {
+    if (!policy) {
+        return {
+            mode: 'allow_all',
+        };
+    }
+    if (!Array.isArray(policy.tools)) {
+        return {
+            mode: 'unknown',
+        };
+    }
+    if (policy.mode === 'allow') {
+        return {
+            mode: 'mixed',
+            allowed: policy.tools,
+        };
+    }
+    if (policy.mode === 'deny') {
+        return {
+            mode: 'mixed',
+            denied: policy.tools,
+        };
+    }
+    return {
+        mode: 'unknown',
+    };
+}

package/dist/semantic.d.ts

@@ -0,0 +1,7 @@
+export type QuantizedVector = {
+    q: Int8Array;
+    scale: number;
+};
+export declare function quantizeEmbeddingInt8L2Norm(embedding: Float32Array): QuantizedVector;
+export declare function encodeScaleF16(scale: number): number;
+export declare function decodeScaleF16(encoded: number): number;

package/dist/semantic.js

@@ -0,0 +1,98 @@
+export function quantizeEmbeddingInt8L2Norm(embedding) {
+    const dims = embedding.length;
+    const normalized = new Float32Array(dims);
+    let normSq = 0;
+    for (let i = 0; i < dims; i++)
+        normSq += embedding[i] * embedding[i];
+    const norm = Math.sqrt(normSq);
+    if (norm === 0) {
+        return { q: new Int8Array(dims), scale: 0 };
+    }
+    let maxAbs = 0;
+    for (let i = 0; i < dims; i++) {
+        const value = embedding[i] / norm;
+        normalized[i] = value;
+        const abs = Math.abs(value);
+        if (abs > maxAbs)
+            maxAbs = abs;
+    }
+    const scale = maxAbs / 127;
+    if (scale === 0) {
+        return { q: new Int8Array(dims), scale: 0 };
+    }
+    const q = new Int8Array(dims);
+    for (let i = 0; i < dims; i++) {
+        const quantized = Math.round(normalized[i] / scale);
+        q[i] = clampInt8(quantized);
+    }
+    return { q, scale };
+}
+export function encodeScaleF16(scale) {
+    return float32ToFloat16(scale);
+}
+export function decodeScaleF16(encoded) {
+    return float16ToFloat32(encoded);
+}
+function clampInt8(value) {
+    if (value > 127)
+        return 127;
+    if (value < -127)
+        return -127;
+    return value;
+}
+function float32ToFloat16(value) {
+    if (Number.isNaN(value))
+        return 0x7e00;
+    if (value === Infinity)
+        return 0x7c00;
+    if (value === -Infinity)
+        return 0xfc00;
+    const f32 = new Float32Array(1);
+    const u32 = new Uint32Array(f32.buffer);
+    f32[0] = value;
+    const bits = u32[0];
+    const sign = (bits >>> 16) & 0x8000;
+    let exp = (bits >>> 23) & 0xff;
+    let mantissa = bits & 0x7fffff;
+    if (exp === 0xff) {
+        return sign | (mantissa ? 0x7e00 : 0x7c00);
+    }
+    const halfExp = exp - 127 + 15;
+    if (halfExp >= 0x1f) {
+        return sign | 0x7c00;
+    }
+    if (halfExp <= 0) {
+        if (halfExp < -10)
+            return sign;
+        mantissa = (mantissa | 0x800000) >>> (1 - halfExp);
+        if (mantissa & 0x1000)
+            mantissa += 0x2000;
+        return sign | (mantissa >>> 13);
+    }
+    if (mantissa & 0x1000) {
+        mantissa += 0x2000;
+        if (mantissa & 0x800000) {
+            mantissa = 0;
+            exp += 1;
+            if (exp > 142)
+                return sign | 0x7c00;
+        }
+    }
+    return sign | (halfExp << 10) | (mantissa >>> 13);
+}
+function float16ToFloat32(bits) {
+    const sign = (bits & 0x8000) ? -1 : 1;
+    const exp = (bits >>> 10) & 0x1f;
+    const frac = bits & 0x03ff;
+    if (exp === 0) {
+        if (frac === 0)
+            return sign * 0;
+        return sign * Math.pow(2, -14) * (frac / 1024);
+    }
+    if (exp === 0x1f) {
+        if (frac === 0)
+            return sign * Infinity;
+        return NaN;
+    }
+    return sign * Math.pow(2, exp - 15) * (1 + frac / 1024);
+}

package/dist/tokenize.d.ts

@@ -0,0 +1,24 @@
+export type Token = {
+    term: string;
+    pos: number;
+};
+/** Normalize a string by:
+ *  - Applying NFKD Unicode normalization
+ *  - Stripping combining diacritics
+ *  - Converting to lowercase
+ *  - Replacing non‑alphanumeric characters (except hyphen and space) with space
+ *
+ * This normalization ensures that accents and case do not affect matching.
+ */
+export declare function normalize(s: string): string;
+/** Split a piece of text into tokens with positional information. Each token
+ * contains the normalized term and its position in the sequence. Positions
+ * increment only on actual tokens, ignoring multiple whitespace separators.
+ */
+export declare function tokenize(text: string): Token[];
+/** Parse quoted phrases in a query string. A phrase is a sequence of words
+ * enclosed in double quotes. Returns an array of term arrays representing
+ * each phrase. Single words outside quotes are ignored here and handled
+ * separately by tokenize().
+ */
+export declare function parsePhrases(q: string): string[][];

package/dist/tokenize.js

@@ -0,0 +1,53 @@
+/*
+ * tokenize.ts
+ *
+ * Provides functions for normalizing strings and splitting them into tokens
+ * suitable for indexing and querying. This module deliberately avoids any
+ * language‑specific stemming or lemmatization to keep the core simple and
+ * deterministic across platforms. Basic Unicode normalization and diacritic
+ * stripping are applied to ensure consistent matches.
+ */
+/** Normalize a string by:
+ *  - Applying NFKD Unicode normalization
+ *  - Stripping combining diacritics
+ *  - Converting to lowercase
+ *  - Replacing non‑alphanumeric characters (except hyphen and space) with space
+ *
+ * This normalization ensures that accents and case do not affect matching.
+ */
+export function normalize(s) {
+    return s
+        .normalize('NFKD')
+        .replace(/\p{M}+/gu, '')
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s-]/gu, ' ');
+}
+/** Split a piece of text into tokens with positional information. Each token
+ * contains the normalized term and its position in the sequence. Positions
+ * increment only on actual tokens, ignoring multiple whitespace separators.
+ */
+export function tokenize(text) {
+    const norm = normalize(text);
+    const out = [];
+    let pos = 0;
+    for (const w of norm.split(/\s+/).filter(Boolean)) {
+        out.push({ term: w, pos: pos++ });
+    }
+    return out;
+}
+/** Parse quoted phrases in a query string. A phrase is a sequence of words
+ * enclosed in double quotes. Returns an array of term arrays representing
+ * each phrase. Single words outside quotes are ignored here and handled
+ * separately by tokenize().
+ */
+export function parsePhrases(q) {
+    const parts = [];
+    const regex = /["“”]([^"“”]+)["“”]/g;
+    let match;
+    while ((match = regex.exec(q)) !== null) {
+        const phrase = match[1].trim().split(/\s+/);
+        if (phrase.length > 0)
+            parts.push(phrase);
+    }
+    return parts;
+}

package/dist/tool_gate.d.ts

@@ -0,0 +1,3 @@
+import { type AgentDefinitionV1 } from './agent.js';
+import { type ToolCallV1 } from './tools.js';
+export declare function assertToolCallAllowed(agent: AgentDefinitionV1, call: ToolCallV1): void;

package/dist/tool_gate.js

@@ -0,0 +1,8 @@
+import { assertToolAllowed } from './agent.js';
+import { isToolCallV1 } from './tools.js';
+export function assertToolCallAllowed(agent, call) {
+    if (!isToolCallV1(call)) {
+        throw new Error('tool call must be a valid ToolCallV1 object.');
+    }
+    assertToolAllowed(agent, call.tool);
+}

package/dist/tool_parse.d.ts

@@ -0,0 +1,2 @@
+import { type ToolCallV1 } from './tools.js';
+export declare function parseToolCallV1FromText(text: string): ToolCallV1 | null;

package/dist/tool_parse.js

@@ -0,0 +1,102 @@
+import { isToolCallV1 } from './tools.js';
+function tryParseJson(input) {
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return null;
+    }
+}
+function findBalancedJsonObject(text) {
+    let depth = 0;
+    let start = -1;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === '\\') {
+                escaped = true;
+                continue;
+            }
+            if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === '{') {
+            if (depth === 0)
+                start = i;
+            depth += 1;
+            continue;
+        }
+        if (char === '}') {
+            if (depth === 0)
+                continue;
+            depth -= 1;
+            if (depth === 0 && start >= 0) {
+                return text.slice(start, i + 1);
+            }
+        }
+    }
+    return null;
+}
+function parseToolCallCandidate(candidate) {
+    const value = tryParseJson(candidate);
+    return isToolCallV1(value) ? value : null;
+}
+function parseFromFencedBlock(text) {
+    const fencedRegex = /```(?:json)?\s*([\s\S]*?)```/gi;
+    let match;
+    while ((match = fencedRegex.exec(text)) !== null) {
+        const parsed = parseToolCallCandidate(match[1].trim());
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function parseFromMarkerLine(text) {
+    const lines = text.split(/\r?\n/);
+    for (const line of lines) {
+        const markerIndex = line.indexOf('TOOL_CALL:');
+        if (markerIndex === -1)
+            continue;
+        const tail = line.slice(markerIndex + 'TOOL_CALL:'.length).trim();
+        if (!tail)
+            continue;
+        const objectText = findBalancedJsonObject(tail) ?? tail;
+        const parsed = parseToolCallCandidate(objectText);
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function parseFirstJsonObject(text) {
+    const objectText = findBalancedJsonObject(text);
+    if (!objectText)
+        return null;
+    return tryParseJson(objectText);
+}
+export function parseToolCallV1FromText(text) {
+    if (typeof text !== 'string' || !text.trim())
+        return null;
+    const whole = parseToolCallCandidate(text.trim());
+    if (whole)
+        return whole;
+    const fenced = parseFromFencedBlock(text);
+    if (fenced)
+        return fenced;
+    const marker = parseFromMarkerLine(text);
+    if (marker)
+        return marker;
+    const firstObject = parseFirstJsonObject(text);
+    return isToolCallV1(firstObject) ? firstObject : null;
+}

package/dist/tools.d.ts

@@ -0,0 +1,27 @@
+export type ToolId = string;
+export interface ToolCallV1 {
+    type: 'tool_call';
+    callId: string;
+    tool: ToolId;
+    args: Record<string, unknown>;
+}
+export interface ToolResultErrorV1 {
+    message: string;
+    code?: string;
+    details?: unknown;
+}
+export interface ToolResultV1 {
+    type: 'tool_result';
+    callId: string;
+    tool: ToolId;
+    ok: boolean;
+    output?: unknown;
+    error?: ToolResultErrorV1;
+}
+export interface ToolSpecV1 {
+    id: ToolId;
+    description?: string;
+    jsonSchema?: unknown;
+}
+export declare function isToolCallV1(x: unknown): x is ToolCallV1;
+export declare function isToolResultV1(x: unknown): x is ToolResultV1;

package/dist/tools.js

@@ -0,0 +1,34 @@
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function isToolCallV1(x) {
+    if (!isPlainObject(x))
+        return false;
+    return (x.type === 'tool_call' &&
+        typeof x.callId === 'string' &&
+        x.callId.trim().length > 0 &&
+        typeof x.tool === 'string' &&
+        x.tool.trim().length > 0 &&
+        isPlainObject(x.args));
+}
+export function isToolResultV1(x) {
+    if (!isPlainObject(x))
+        return false;
+    if (x.type !== 'tool_result' ||
+        typeof x.callId !== 'string' ||
+        x.callId.trim().length === 0 ||
+        typeof x.tool !== 'string' ||
+        x.tool.trim().length === 0 ||
+        typeof x.ok !== 'boolean') {
+        return false;
+    }
+    if (x.ok) {
+        return x.error === undefined;
+    }
+    return (isPlainObject(x.error) &&
+        typeof x.error.message === 'string' &&
+        x.error.message.trim().length > 0);
+}

package/dist/trace.d.ts

@@ -0,0 +1,45 @@
+import type { ToolCallV1, ToolResultV1 } from './tools.js';
+import type { RouteDecisionV1 } from './router.js';
+export type TraceEventV1 = {
+    type: 'route.requested';
+    ts: string;
+    text: string;
+    agentCount: number;
+} | {
+    type: 'route.decided';
+    ts: string;
+    decision: RouteDecisionV1;
+    selectedAgentId: string;
+} | {
+    type: 'agent.selected';
+    ts: string;
+    agentId: string;
+    namespace?: string;
+} | {
+    type: 'prompt.resolved';
+    ts: string;
+    agentId: string;
+    promptHash?: string;
+    patchKeys?: string[];
+} | {
+    type: 'tool.requested';
+    ts: string;
+    agentId: string;
+    call: ToolCallV1;
+} | {
+    type: 'tool.executed';
+    ts: string;
+    agentId: string;
+    result: ToolResultV1;
+    durationMs?: number;
+} | {
+    type: 'run.completed';
+    ts: string;
+    agentId: string;
+    status: 'ok' | 'error';
+};
+export declare function nowIso(): string;
+export declare function createTrace(): {
+    events: TraceEventV1[];
+    push(e: TraceEventV1): void;
+};

package/dist/trace.js

@@ -0,0 +1,12 @@
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function createTrace() {
+    const events = [];
+    return {
+        events,
+        push(e) {
+            events.push(e);
+        },
+    };
+}

package/dist/utils/utf8.d.ts

@@ -0,0 +1,8 @@
+export type TextDecoderLike = {
+    decode: (u8: Uint8Array) => string;
+};
+export type TextEncoderLike = {
+    encode: (s: string) => Uint8Array;
+};
+export declare function getTextDecoder(): TextDecoderLike;
+export declare function getTextEncoder(): TextEncoderLike;

package/dist/utils/utf8.js

@@ -0,0 +1,72 @@
+// src/utils/utf8.ts
+// Small, dependency-free UTF-8 encoder/decoder that works in RN/Hermes.
+export function getTextDecoder() {
+    try {
+        // eslint-disable-next-line no-new
+        const td = new TextDecoder();
+        return td;
+    }
+    catch {
+        return {
+            decode: (u8) => {
+                let out = '';
+                for (let i = 0; i < u8.length;) {
+                    const a = u8[i++];
+                    if (a < 0x80) {
+                        out += String.fromCharCode(a);
+                    }
+                    else if ((a & 0xe0) === 0xc0) {
+                        const b = u8[i++] & 0x3f;
+                        const cp = ((a & 0x1f) << 6) | b;
+                        out += String.fromCharCode(cp);
+                    }
+                    else if ((a & 0xf0) === 0xe0) {
+                        const b = u8[i++] & 0x3f;
+                        const c = u8[i++] & 0x3f;
+                        const cp = ((a & 0x0f) << 12) | (b << 6) | c;
+                        out += String.fromCharCode(cp);
+                    }
+                    else {
+                        const b = u8[i++] & 0x3f;
+                        const c = u8[i++] & 0x3f;
+                        const d = u8[i++] & 0x3f;
+                        let cp = ((a & 0x07) << 18) | (b << 12) | (c << 6) | d;
+                        cp -= 0x10000;
+                        out += String.fromCharCode(0xd800 + (cp >> 10), 0xdc00 + (cp & 0x3ff));
+                    }
+                }
+                return out;
+            },
+        };
+    }
+}
+export function getTextEncoder() {
+    try {
+        // eslint-disable-next-line no-new
+        const te = new TextEncoder();
+        return te;
+    }
+    catch {
+        return {
+            encode: (s) => {
+                const out = [];
+                for (let i = 0; i < s.length; i++) {
+                    let cp = s.charCodeAt(i);
+                    if (cp >= 0xd800 && cp <= 0xdbff && i + 1 < s.length) {
+                        const next = s.charCodeAt(++i);
+                        cp = 0x10000 + ((cp - 0xd800) << 10) + (next - 0xdc00);
+                    }
+                    if (cp < 0x80)
+                        out.push(cp);
+                    else if (cp < 0x800)
+                        out.push(0xc0 | (cp >> 6), 0x80 | (cp & 0x3f));
+                    else if (cp < 0x10000)
+                        out.push(0xe0 | (cp >> 12), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+                    else
+                        out.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 0x3f), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+                }
+                return new Uint8Array(out);
+            },
+        };
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@knolo/core",
+  "version": "3.1.2",
+  "type": "module",
+  "description": "Local-first knowledge packs for small LLMs.",
+  "keywords": [
+    "llm",
+    "knowledge-base",
+    "rag",
+    "local",
+    "expo"
+  ],
+  "author": "Sam Paniagua",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "smoke": "node scripts/smoke.mjs",
+    "test": "npm run build && node scripts/test.mjs",
+    "format": "prettier --write src/agent.ts src/pack.ts src/builder.ts src/index.ts scripts/test.mjs ../../README.md",
+    "format:check": "prettier --check src/agent.ts src/pack.ts src/builder.ts src/index.ts scripts/test.mjs ../../README.md"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.5.0"
+  }
+}