@kaleidorg/mind 0.0.1 → 0.2.0

package/dist/knowledge/wallet.js

@@ -0,0 +1,63 @@
+/**
+ * Personal wallet knowledge — turn a user's transaction history + contacts into
+ * `RagDocument[]` so the agent can answer "what did I spend on coffee last
+ * month?", "who did I pay 50k sats to?", "summarise my swaps" — all on-device,
+ * nothing leaving the phone.
+ *
+ * Pure transforms over minimal, generic shapes (hosts map their own types in).
+ * No deps, no PII leaves: the host decides what to ingest.
+ */
+function isoDate(ts) {
+    if (!ts)
+        return 'an unknown date';
+    // Avoid Date formatting differences — just YYYY-MM-DD from the ISO string.
+    try {
+        return new Date(ts).toISOString().slice(0, 10);
+    }
+    catch {
+        return 'an unknown date';
+    }
+}
+/** One short, searchable sentence per transaction. */
+export function walletHistoryToDocuments(txs) {
+    return txs.map((tx, i) => {
+        const date = isoDate(tx.timestamp);
+        const asset = tx.asset ?? 'sats';
+        const amount = tx.amountSats != null ? `${tx.amountSats} ${asset === 'BTC' ? 'sats' : asset}` : 'an amount';
+        const verb = tx.type === 'receive' || tx.type === 'deposit'
+            ? 'received'
+            : tx.type === 'swap'
+                ? 'swapped'
+                : tx.type === 'withdraw'
+                    ? 'withdrew'
+                    : 'sent';
+        const who = tx.counterparty ? ` ${verb === 'received' ? 'from' : 'to'} ${tx.counterparty}` : '';
+        const memo = tx.memo ? ` — "${tx.memo}"` : '';
+        const status = tx.status && tx.status !== 'complete' ? ` (${tx.status})` : '';
+        return {
+            id: tx.id ?? `tx_${i}`,
+            text: `On ${date} you ${verb} ${amount}${who}${memo}${status}.`,
+            metadata: { kind: 'transaction', type: tx.type, asset: tx.asset, timestamp: tx.timestamp },
+        };
+    });
+}
+/** One doc per contact, so "who is Bob?" / "pay my friend" can resolve. */
+export function contactsToDocuments(contacts) {
+    return contacts
+        .filter((c) => c.name || c.lightningAddress || c.npub)
+        .map((c, i) => {
+        const parts = [];
+        if (c.lightningAddress)
+            parts.push(`Lightning address ${c.lightningAddress}`);
+        if (c.npub)
+            parts.push(`Nostr ${c.npub}`);
+        if (c.note)
+            parts.push(c.note);
+        return {
+            id: `contact_${c.name ?? c.lightningAddress ?? i}`,
+            text: `Contact: ${c.name ?? 'unnamed'}${parts.length ? ` — ${parts.join(', ')}` : ''}.`,
+            metadata: { kind: 'contact', name: c.name },
+        };
+    });
+}
+//# sourceMappingURL=wallet.js.map

package/dist/knowledge/wallet.js.map

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

package/dist/memory/store.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MemoryStore implementation — in-memory, with optional injected persistence
+ * and optional semantic ranking. Pure TS, zero deps.
+ *
+ *   const store = new InMemoryMemoryStore();                // ephemeral
+ *   const store = new InMemoryMemoryStore({ io });          // persisted (RN/Node)
+ *   const store = new InMemoryMemoryStore({ io, embed });   // + semantic recall
+ */
+import type { MemoryIO, MemoryItem, MemoryQuery, MemoryStore, NewMemory } from './types.js';
+export interface MemoryStoreOptions {
+    /** Persistence (load on first use, save on writes). Omit for ephemeral memory. */
+    io?: MemoryIO;
+    /** Embed text for semantic recall. Omit to fall back to substring matching. */
+    embed?: (text: string) => Promise<number[]>;
+    /** Clock — injectable for deterministic tests. */
+    now?: () => number;
+}
+export declare class InMemoryMemoryStore implements MemoryStore {
+    private items;
+    private hydrated;
+    private counter;
+    private readonly io?;
+    private readonly embed?;
+    private readonly now;
+    constructor(opts?: MemoryStoreOptions);
+    private hydrate;
+    private persist;
+    add(item: NewMemory): Promise<MemoryItem>;
+    all(): Promise<MemoryItem[]>;
+    search(query: MemoryQuery): Promise<MemoryItem[]>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/memory/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/memory/store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,WAAW,EACX,WAAW,EACX,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,EAAE,CAAC,EAAE,QAAQ,CAAC;IACd,+EAA+E;IAC/E,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAW;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEvB,IAAI,GAAE,kBAAuB;YAM3B,OAAO;YAaP,OAAO;IAIf,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBzC,GAAG,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAK5B,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCjD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7B"}

package/dist/memory/store.js

@@ -0,0 +1,103 @@
+/**
+ * MemoryStore implementation — in-memory, with optional injected persistence
+ * and optional semantic ranking. Pure TS, zero deps.
+ *
+ *   const store = new InMemoryMemoryStore();                // ephemeral
+ *   const store = new InMemoryMemoryStore({ io });          // persisted (RN/Node)
+ *   const store = new InMemoryMemoryStore({ io, embed });   // + semantic recall
+ */
+import { cosineSimilarity } from '../rag/vector-store.js';
+export class InMemoryMemoryStore {
+    items = [];
+    hydrated = false;
+    counter = 0;
+    io;
+    embed;
+    now;
+    constructor(opts = {}) {
+        this.io = opts.io;
+        this.embed = opts.embed;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    async hydrate() {
+        if (this.hydrated)
+            return;
+        this.hydrated = true;
+        if (this.io) {
+            try {
+                this.items = await this.io.load();
+                this.counter = this.items.length;
+            }
+            catch {
+                this.items = [];
+            }
+        }
+    }
+    async persist() {
+        if (this.io)
+            await this.io.save(this.items);
+    }
+    async add(item) {
+        await this.hydrate();
+        const embedding = item.embedding ?? (this.embed ? await this.embed(item.text).catch(() => undefined) : undefined);
+        const full = {
+            id: item.id ?? `mem_${this.now()}_${++this.counter}`,
+            text: item.text,
+            kind: item.kind,
+            tags: item.tags,
+            createdAt: item.createdAt ?? this.now(),
+            ...(embedding ? { embedding } : {}),
+        };
+        this.items.push(full);
+        await this.persist();
+        return full;
+    }
+    async all() {
+        await this.hydrate();
+        return [...this.items];
+    }
+    async search(query) {
+        await this.hydrate();
+        const limit = query.limit ?? 5;
+        let pool = this.items;
+        if (query.kind)
+            pool = pool.filter((m) => m.kind === query.kind);
+        if (query.tags?.length) {
+            pool = pool.filter((m) => query.tags.every((t) => m.tags?.includes(t)));
+        }
+        const text = query.text?.trim();
+        if (!text) {
+            // No query text → most recent first.
+            return [...pool].sort((a, b) => b.createdAt - a.createdAt).slice(0, limit);
+        }
+        // Semantic ranking when both the query and items are embedded.
+        if (this.embed && pool.some((m) => m.embedding)) {
+            const qv = await this.embed(text).catch(() => null);
+            if (qv) {
+                return [...pool]
+                    .map((m) => ({ m, score: m.embedding ? cosineSimilarity(qv, m.embedding) : -1 }))
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, limit)
+                    .map((x) => x.m);
+            }
+        }
+        // Fallback: substring score + recency.
+        const q = text.toLowerCase();
+        return [...pool]
+            .map((m) => ({ m, hit: m.text.toLowerCase().includes(q) ? 1 : 0 }))
+            .sort((a, b) => b.hit - a.hit || b.m.createdAt - a.m.createdAt)
+            .slice(0, limit)
+            .map((x) => x.m);
+    }
+    async remove(id) {
+        await this.hydrate();
+        this.items = this.items.filter((m) => m.id !== id);
+        await this.persist();
+    }
+    async clear() {
+        await this.hydrate();
+        this.items = [];
+        await this.persist();
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/memory/store.js.map

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

package/dist/memory/tool.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Memory tool source — lets the agent persist and recall things across
+ * sessions (`remember`, `recall`). Pairs with auto-recall in the
+ * ContextBuilder; this is the explicit, agent-driven side.
+ */
+import type { ToolSource } from '../tools/source.js';
+import type { MemoryStore } from './types.js';
+export declare function createMemoryToolSource(store: MemoryStore): ToolSource;
+//# sourceMappingURL=tool.d.ts.map

package/dist/memory/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/memory/tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,YAAY,CAAC;AAM1D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,WAAW,GAAG,UAAU,CA6DrE"}

package/dist/memory/tool.js

@@ -0,0 +1,70 @@
+/**
+ * Memory tool source — lets the agent persist and recall things across
+ * sessions (`remember`, `recall`). Pairs with auto-recall in the
+ * ContextBuilder; this is the explicit, agent-driven side.
+ */
+const REMEMBER = 'remember';
+const RECALL = 'recall';
+const KINDS = ['fact', 'preference', 'event', 'note'];
+export function createMemoryToolSource(store) {
+    const tools = [
+        {
+            name: REMEMBER,
+            description: 'Save something to long-term memory so you recall it in future sessions ' +
+                '— a user preference, a fact, or an event. Use sparingly for durable info.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    text: { type: 'string', description: 'What to remember (a short sentence)' },
+                    kind: { type: 'string', enum: KINDS, description: 'fact | preference | event | note' },
+                    tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags' },
+                },
+                required: ['text'],
+            },
+        },
+        {
+            name: RECALL,
+            description: 'Search your long-term memory for what you know about something before answering.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'What to recall' },
+                    limit: { type: 'number', description: 'Max items (default 5)' },
+                },
+                required: ['query'],
+            },
+        },
+    ];
+    async function execute(name, args) {
+        if (name === REMEMBER) {
+            const text = String(args.text ?? '').trim();
+            if (!text)
+                throw new Error('remember: text is required');
+            const kind = KINDS.includes(String(args.kind))
+                ? args.kind
+                : 'note';
+            const tags = Array.isArray(args.tags) ? args.tags.map(String) : undefined;
+            const item = await store.add({ text, kind, tags });
+            return `Remembered (${item.kind}): ${item.text}`;
+        }
+        if (name === RECALL) {
+            const query = String(args.query ?? '').trim();
+            if (!query)
+                throw new Error('recall: query is required');
+            const limit = Number(args.limit) > 0 ? Number(args.limit) : 5;
+            const items = await store.search({ text: query, limit });
+            if (items.length === 0)
+                return 'Nothing relevant in memory.';
+            return items.map((m) => `- (${m.kind}) ${m.text}`).join('\n');
+        }
+        throw new Error(`memory: unknown tool ${name}`);
+    }
+    const names = new Set([REMEMBER, RECALL]);
+    return {
+        id: 'memory',
+        listTools: () => tools,
+        has: (name) => names.has(name),
+        execute,
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/memory/tool.js.map

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

package/dist/memory/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Memory — the agent's persistent identity + what it has learned.
+ *
+ * Two layers, mirroring how nanobot splits SOUL.md / AGENTS.md / memory:
+ *   - AgentProfile  — static identity ("who am I, how do I behave"). Injected.
+ *   - MemoryStore   — durable, growing facts/preferences/events the agent
+ *                     remembers across sessions. Pluggable storage.
+ *
+ * Pure data + interfaces — no storage or embedding deps. The host injects
+ * persistence (AsyncStorage on RN, fs/SQLite on Node) and, optionally, an
+ * EmbeddingProvider for semantic recall.
+ */
+/** Static agent identity, composed into the system prompt every turn. */
+export interface AgentProfile {
+    /** Display name, e.g. "KaleidoMind". */
+    name: string;
+    /** Persona / identity — the "soul". Who the agent is, its voice, its values. */
+    soul: string;
+    /** Operating instructions / house rules (optional). */
+    instructions?: string;
+}
+export type MemoryKind = 'fact' | 'preference' | 'event' | 'note';
+export interface MemoryItem {
+    id: string;
+    text: string;
+    kind: MemoryKind;
+    /** Epoch ms. */
+    createdAt: number;
+    tags?: string[];
+    /** Optional embedding for semantic recall (set when an embedder is wired). */
+    embedding?: number[];
+}
+/** What to add — id/createdAt/embedding are filled in by the store. */
+export type NewMemory = Omit<MemoryItem, 'id' | 'createdAt' | 'embedding'> & Partial<Pick<MemoryItem, 'id' | 'createdAt' | 'embedding'>>;
+export interface MemoryQuery {
+    /** Free text to match (semantic if embeddings are available, else substring). */
+    text?: string;
+    kind?: MemoryKind;
+    tags?: string[];
+    /** Max items to return (default 5). */
+    limit?: number;
+}
+export interface MemoryStore {
+    add(item: NewMemory): Promise<MemoryItem>;
+    all(): Promise<MemoryItem[]>;
+    /** Best-matching items for the query (recency-ranked, or semantic if embedded). */
+    search(query: MemoryQuery): Promise<MemoryItem[]>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Injected persistence — load once, save on every mutation. RN/Node provide it. */
+export interface MemoryIO {
+    load(): Promise<MemoryItem[]>;
+    save(items: MemoryItem[]): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GACxE,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,GAAG,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7B,mFAAmF;IACnF,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAClD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,oFAAoF;AACpF,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C"}

package/dist/memory/types.js

@@ -0,0 +1,14 @@
+/**
+ * Memory — the agent's persistent identity + what it has learned.
+ *
+ * Two layers, mirroring how nanobot splits SOUL.md / AGENTS.md / memory:
+ *   - AgentProfile  — static identity ("who am I, how do I behave"). Injected.
+ *   - MemoryStore   — durable, growing facts/preferences/events the agent
+ *                     remembers across sessions. Pluggable storage.
+ *
+ * Pure data + interfaces — no storage or embedding deps. The host injects
+ * persistence (AsyncStorage on RN, fs/SQLite on Node) and, optionally, an
+ * EmbeddingProvider for semantic recall.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/rag/retriever.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Retriever — ties an injected EmbeddingProvider to a VectorStore: ingest
+ * documents (chunk → embed → upsert) and search (embed query → top-k). Pure
+ * TS; the embedding model is the host's (QVAC `embed()` on device).
+ */
+import type { EmbeddingProvider, RagDocument, RetrievedChunk, VectorStore } from './types.js';
+export interface RetrieverOptions {
+    embeddings: EmbeddingProvider;
+    /** Vector index (defaults to a fresh in-memory cosine store). */
+    store?: VectorStore;
+    /** Approx chars per chunk (default 800 ≈ 200 tokens). */
+    chunkSize?: number;
+    /** Chars of overlap between chunks (default 100). */
+    chunkOverlap?: number;
+}
+/** Split text into overlapping chunks, preferring paragraph/sentence breaks. */
+export declare function chunkText(text: string, size?: number, overlap?: number): string[];
+export declare class Retriever {
+    private readonly embeddings;
+    private readonly store;
+    private readonly chunkSize;
+    private readonly chunkOverlap;
+    constructor(opts: RetrieverOptions);
+    /** Chunk, embed, and index documents. Returns the number of chunks stored. */
+    ingest(docs: RagDocument[]): Promise<number>;
+    /** Embed the query and return the top-k most similar chunks. */
+    search(query: string, k?: number): Promise<RetrievedChunk[]>;
+    vectorStore(): VectorStore;
+}
+//# sourceMappingURL=retriever.d.ts.map

package/dist/rag/retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.d.ts","sourceRoot":"","sources":["../../src/rag/retriever.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,iEAAiE;IACjE,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAM,EAAE,OAAO,SAAM,GAAG,MAAM,EAAE,CAwB3E;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAE1B,IAAI,EAAE,gBAAgB;IAOlC,8EAA8E;IACxE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBlD,gEAAgE;IAC1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,SAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAO7D,WAAW,IAAI,WAAW;CAG3B"}

package/dist/rag/retriever.js

@@ -0,0 +1,72 @@
+/**
+ * Retriever — ties an injected EmbeddingProvider to a VectorStore: ingest
+ * documents (chunk → embed → upsert) and search (embed query → top-k). Pure
+ * TS; the embedding model is the host's (QVAC `embed()` on device).
+ */
+import { InMemoryVectorStore } from './vector-store.js';
+/** Split text into overlapping chunks, preferring paragraph/sentence breaks. */
+export function chunkText(text, size = 800, overlap = 100) {
+    const clean = text.replace(/\r\n/g, '\n').trim();
+    if (clean.length <= size)
+        return clean ? [clean] : [];
+    const chunks = [];
+    let start = 0;
+    while (start < clean.length) {
+        let end = Math.min(start + size, clean.length);
+        if (end < clean.length) {
+            // Back up to the nearest paragraph/sentence/space boundary.
+            const slice = clean.slice(start, end);
+            const brk = Math.max(slice.lastIndexOf('\n\n'), slice.lastIndexOf('\n'), slice.lastIndexOf('. '), slice.lastIndexOf(' '));
+            if (brk > size * 0.5)
+                end = start + brk + 1;
+        }
+        const piece = clean.slice(start, end).trim();
+        if (piece)
+            chunks.push(piece);
+        if (end >= clean.length)
+            break;
+        start = Math.max(end - overlap, start + 1);
+    }
+    return chunks;
+}
+export class Retriever {
+    embeddings;
+    store;
+    chunkSize;
+    chunkOverlap;
+    constructor(opts) {
+        this.embeddings = opts.embeddings;
+        this.store = opts.store ?? new InMemoryVectorStore();
+        this.chunkSize = opts.chunkSize ?? 800;
+        this.chunkOverlap = opts.chunkOverlap ?? 100;
+    }
+    /** Chunk, embed, and index documents. Returns the number of chunks stored. */
+    async ingest(docs) {
+        const pending = [];
+        for (const doc of docs) {
+            const pieces = chunkText(doc.text, this.chunkSize, this.chunkOverlap);
+            pieces.forEach((text, i) => {
+                const baseId = doc.id ?? `doc_${pending.length}`;
+                pending.push({ id: `${baseId}#${i}`, text, metadata: doc.metadata });
+            });
+        }
+        if (pending.length === 0)
+            return 0;
+        const vectors = await this.embeddings.embed(pending.map((p) => p.text));
+        await this.store.upsert(pending.map((p, i) => ({ ...p, embedding: vectors[i] })));
+        return pending.length;
+    }
+    /** Embed the query and return the top-k most similar chunks. */
+    async search(query, k = 4) {
+        if (!query.trim())
+            return [];
+        const [qv] = await this.embeddings.embed([query]);
+        if (!qv)
+            return [];
+        return this.store.query(qv, k);
+    }
+    vectorStore() {
+        return this.store;
+    }
+}
+//# sourceMappingURL=retriever.js.map

package/dist/rag/retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../src/rag/retriever.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAkBxD,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,IAAI,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG;IAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACjD,IAAI,KAAK,CAAC,MAAM,IAAI,IAAI;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/C,IAAI,GAAG,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACvB,4DAA4D;YAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAClB,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,EACzB,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EACvB,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EACvB,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CACvB,CAAC;YACF,IAAI,GAAG,GAAG,IAAI,GAAG,GAAG;gBAAE,GAAG,GAAG,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7C,IAAI,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM;YAAE,MAAM;QAC/B,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,OAAO,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,OAAO,SAAS;IACH,UAAU,CAAoB;IAC9B,KAAK,CAAc;IACnB,SAAS,CAAS;IAClB,YAAY,CAAS;IAEtC,YAAY,IAAsB;QAChC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,mBAAmB,EAAE,CAAC;QACrD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC;QACvC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,GAAG,CAAC;IAC/C,CAAC;IAED,8EAA8E;IAC9E,KAAK,CAAC,MAAM,CAAC,IAAmB;QAC9B,MAAM,OAAO,GAAuE,EAAE,CAAC;QACvF,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;YACtE,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;gBACzB,MAAM,MAAM,GAAG,GAAG,CAAC,EAAE,IAAI,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC;gBACjD,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;YACvE,CAAC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACxE,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CACrB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CACzD,CAAC;QACF,OAAO,OAAO,CAAC,MAAM,CAAC;IACxB,CAAC;IAED,gEAAgE;IAChE,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,CAAC,GAAG,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,OAAO,EAAE,CAAC;QAC7B,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IACjC,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}

package/dist/rag/tool.d.ts

@@ -0,0 +1,15 @@
+/**
+ * RAG tool source — exposes `search_knowledge` so the model can pull in
+ * relevant context on demand (agentic RAG). Preferred over always-injecting
+ * retrieved text, which burns the small-model context window.
+ */
+import type { ToolSource } from '../tools/source.js';
+import type { Retriever } from './retriever.js';
+export interface RagToolOptions {
+    /** Chunks to return (default 4). */
+    k?: number;
+    /** Override the tool description for your corpus, e.g. "Search the docs." */
+    description?: string;
+}
+export declare function createRagToolSource(retriever: Retriever, opts?: RagToolOptions): ToolSource;
+//# sourceMappingURL=tool.d.ts.map

package/dist/rag/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/rag/tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE,cAAmB,GAAG,UAAU,CAmC/F"}

package/dist/rag/tool.js

@@ -0,0 +1,42 @@
+/**
+ * RAG tool source — exposes `search_knowledge` so the model can pull in
+ * relevant context on demand (agentic RAG). Preferred over always-injecting
+ * retrieved text, which burns the small-model context window.
+ */
+const SEARCH = 'search_knowledge';
+export function createRagToolSource(retriever, opts = {}) {
+    const tool = {
+        name: SEARCH,
+        description: opts.description ??
+            'Search the knowledge base for passages relevant to a question and return ' +
+                'the best matches. Use this before answering when the answer might be in ' +
+                'ingested documents.',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'What to look up' },
+                k: { type: 'number', description: 'How many passages (default 4)' },
+            },
+            required: ['query'],
+        },
+    };
+    async function execute(_name, args) {
+        const query = String(args.query ?? '').trim();
+        if (!query)
+            throw new Error('search_knowledge: query is required');
+        const k = Number(args.k) > 0 ? Number(args.k) : (opts.k ?? 4);
+        const hits = await retriever.search(query, k);
+        if (hits.length === 0)
+            return 'No relevant passages found.';
+        return hits
+            .map((h, i) => `[${i + 1}] (score ${h.score.toFixed(2)}) ${h.text}`)
+            .join('\n\n');
+    }
+    return {
+        id: 'rag',
+        listTools: () => [tool],
+        has: (name) => name === SEARCH,
+        execute,
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/rag/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/rag/tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,MAAM,GAAG,kBAAkB,CAAC;AASlC,MAAM,UAAU,mBAAmB,CAAC,SAAoB,EAAE,OAAuB,EAAE;IACjF,MAAM,IAAI,GAAY;QACpB,IAAI,EAAE,MAAM;QACZ,WAAW,EACT,IAAI,CAAC,WAAW;YAChB,2EAA2E;gBACzE,0EAA0E;gBAC1E,qBAAqB;QACzB,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE;gBACzD,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+BAA+B,EAAE;aACpE;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF,CAAC;IAEF,KAAK,UAAU,OAAO,CAAC,KAAa,EAAE,IAA6B;QACjE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACnE,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,6BAA6B,CAAC;QAC5D,OAAO,IAAI;aACR,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;aACnE,IAAI,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED,OAAO;QACL,EAAE,EAAE,KAAK;QACT,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,IAAI,CAAC;QACvB,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,MAAM;QAC9B,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/rag/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * RAG types — retrieval-augmented generation primitives.
+ *
+ * The heavy parts (the embedding model, the vector index) are interfaces the
+ * host injects. On QVAC the EmbeddingProvider wraps the SDK `embed()` API
+ * (on-device); a server host could inject a remote embedder. The default
+ * VectorStore is a pure-JS in-memory cosine index (good for thousands of
+ * chunks); a host can swap in SQLite/native for more.
+ */
+/** Turns text into vectors. Injected — QVAC `embed()` on device, etc. */
+export interface EmbeddingProvider {
+    embed(texts: string[]): Promise<number[][]>;
+    /** Vector dimension, when known (informational). */
+    dimension?: number;
+}
+export interface Chunk {
+    id: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+    embedding?: number[];
+}
+export interface RetrievedChunk extends Chunk {
+    /** Similarity score in [-1, 1] (cosine). */
+    score: number;
+}
+/** A document to ingest; chunked + embedded by the Retriever. */
+export interface RagDocument {
+    id?: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+export interface VectorStore {
+    upsert(chunks: Chunk[]): Promise<void>;
+    /** Top-k by cosine similarity to `embedding`. */
+    query(embedding: number[], k: number): Promise<RetrievedChunk[]>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+}
+/** Injected persistence for the vector store (optional). */
+export interface VectorStoreIO {
+    load(): Promise<Chunk[]>;
+    save(chunks: Chunk[]): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rag/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rag/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,cAAe,SAAQ,KAAK;IAC3C,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,iDAAiD;IACjD,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IACjE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC"}

package/dist/rag/types.js

@@ -0,0 +1,11 @@
+/**
+ * RAG types — retrieval-augmented generation primitives.
+ *
+ * The heavy parts (the embedding model, the vector index) are interfaces the
+ * host injects. On QVAC the EmbeddingProvider wraps the SDK `embed()` API
+ * (on-device); a server host could inject a remote embedder. The default
+ * VectorStore is a pure-JS in-memory cosine index (good for thousands of
+ * chunks); a host can swap in SQLite/native for more.
+ */
+export {};
+//# sourceMappingURL=types.js.map