@kaleidorg/mind 0.1.0 → 0.3.0

package/src/rag/rag.test.ts

@@ -0,0 +1,85 @@
+/** RAG tests — vector store, chunking, retriever + tool with a fake embedder. */
+
+import { describe, it, expect } from 'vitest';
+import { cosineSimilarity, InMemoryVectorStore } from './vector-store.js';
+import { Retriever, chunkText } from './retriever.js';
+import { createRagToolSource } from './tool.js';
+import type { EmbeddingProvider } from './types.js';
+
+// Deterministic bag-of-words embedder over a tiny vocab.
+const VOCAB = ['btc', 'lightning', 'channel', 'swap', 'balance', 'rgb', 'price', 'esim'];
+const fakeEmbeddings: EmbeddingProvider = {
+  dimension: VOCAB.length,
+  async embed(texts) {
+    return texts.map((t) => {
+      const lower = t.toLowerCase();
+      return VOCAB.map((w) => (lower.match(new RegExp(w, 'g'))?.length ?? 0));
+    });
+  },
+};
+
+describe('cosineSimilarity', () => {
+  it('is 1 for identical, 0 for orthogonal / degenerate', () => {
+    expect(cosineSimilarity([1, 2, 3], [1, 2, 3])).toBeCloseTo(1);
+    expect(cosineSimilarity([1, 0], [0, 1])).toBe(0);
+    expect(cosineSimilarity([0, 0], [1, 1])).toBe(0);
+  });
+});
+
+describe('chunkText', () => {
+  it('returns one chunk when short', () => {
+    expect(chunkText('hello world', 800)).toEqual(['hello world']);
+  });
+  it('splits long text with overlap on boundaries', () => {
+    const text = Array.from({ length: 50 }, (_, i) => `Sentence number ${i}.`).join(' ');
+    const chunks = chunkText(text, 120, 20);
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(chunks.every((c) => c.length <= 140)).toBe(true);
+  });
+});
+
+describe('InMemoryVectorStore', () => {
+  it('upserts (dedup by id) and queries by similarity', async () => {
+    const store = new InMemoryVectorStore();
+    await store.upsert([
+      { id: 'a', text: 'about balance', embedding: [0, 0, 0, 0, 1, 0, 0, 0] },
+      { id: 'b', text: 'about price', embedding: [0, 0, 0, 0, 0, 0, 1, 0] },
+    ]);
+    await store.upsert([{ id: 'a', text: 'about balance v2', embedding: [0, 0, 0, 0, 1, 0, 0, 0] }]);
+    expect(await store.size()).toBe(2); // 'a' replaced, not duplicated
+
+    const hits = await store.query([0, 0, 0, 0, 1, 0, 0, 0], 1);
+    expect(hits[0].text).toBe('about balance v2');
+    expect(hits[0].score).toBeCloseTo(1);
+  });
+});
+
+describe('Retriever + RAG tool', () => {
+  it('ingests, then retrieves the most relevant chunk', async () => {
+    const retriever = new Retriever({ embeddings: fakeEmbeddings });
+    const n = await retriever.ingest([
+      { id: 'd1', text: 'How to open a lightning channel and manage balance.' },
+      { id: 'd2', text: 'eSIM data plans and price comparison.' },
+    ]);
+    expect(n).toBeGreaterThanOrEqual(2);
+
+    const hits = await retriever.search('what is my balance on lightning', 1);
+    expect(hits[0].text).toMatch(/lightning channel/i);
+  });
+
+  it('search_knowledge tool returns formatted snippets', async () => {
+    const retriever = new Retriever({ embeddings: fakeEmbeddings });
+    await retriever.ingest([{ id: 'd', text: 'BTC swap and channel fees explained.' }]);
+    const src = createRagToolSource(retriever, { k: 2 });
+    expect(src.has('search_knowledge')).toBe(true);
+    const out = await src.execute('search_knowledge', { query: 'swap channel' });
+    expect(String(out)).toMatch(/swap and channel/i);
+  });
+
+  it('returns a friendly message when nothing matches', async () => {
+    const retriever = new Retriever({ embeddings: fakeEmbeddings });
+    const src = createRagToolSource(retriever);
+    const out = await src.execute('search_knowledge', { query: 'anything' });
+    expect(String(out)).toMatch(/No relevant passages/);
+  });
+});

package/src/rag/retriever.ts

@@ -0,0 +1,94 @@
+/**
+ * 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';
+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 function chunkText(text: string, size = 800, overlap = 100): string[] {
+  const clean = text.replace(/\r\n/g, '\n').trim();
+  if (clean.length <= size) return clean ? [clean] : [];
+  const chunks: string[] = [];
+  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 {
+  private readonly embeddings: EmbeddingProvider;
+  private readonly store: VectorStore;
+  private readonly chunkSize: number;
+  private readonly chunkOverlap: number;
+
+  constructor(opts: RetrieverOptions) {
+    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: RagDocument[]): Promise<number> {
+    const pending: { id: string; text: string; metadata?: Record<string, unknown> }[] = [];
+    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: string, k = 4): Promise<RetrievedChunk[]> {
+    if (!query.trim()) return [];
+    const [qv] = await this.embeddings.embed([query]);
+    if (!qv) return [];
+    return this.store.query(qv, k);
+  }
+
+  vectorStore(): VectorStore {
+    return this.store;
+  }
+}

package/src/rag/tool.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { ToolDef } from '../types.js';
+import type { ToolSource } from '../tools/source.js';
+import type { Retriever } from './retriever.js';
+
+const SEARCH = 'search_knowledge';
+
+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 function createRagToolSource(retriever: Retriever, opts: RagToolOptions = {}): ToolSource {
+  const tool: ToolDef = {
+    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: string, args: Record<string, unknown>): Promise<unknown> {
+    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,
+  };
+}

package/src/rag/types.ts

@@ -0,0 +1,49 @@
+/**
+ * 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>;
+}

package/src/rag/vector-store.ts

@@ -0,0 +1,78 @@
+/**
+ * In-memory vector store — pure-JS cosine similarity index. Zero deps, so it
+ * bundles in Bare/RN. Good for thousands of chunks; swap in a native/SQLite
+ * store via the VectorStore interface for larger corpora.
+ */
+
+import type { Chunk, RetrievedChunk, VectorStore, VectorStoreIO } from './types.js';
+
+/** Cosine similarity of two equal-length vectors. Returns 0 on degenerate input. */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  const n = Math.min(a.length, b.length);
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < n; i++) {
+    dot += a[i]! * b[i]!;
+    na += a[i]! * a[i]!;
+    nb += b[i]! * b[i]!;
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+export interface InMemoryVectorStoreOptions {
+  io?: VectorStoreIO;
+}
+
+export class InMemoryVectorStore implements VectorStore {
+  private chunks: Chunk[] = [];
+  private hydrated = false;
+  private readonly io?: VectorStoreIO;
+
+  constructor(opts: InMemoryVectorStoreOptions = {}) {
+    this.io = opts.io;
+  }
+
+  private async hydrate(): Promise<void> {
+    if (this.hydrated) return;
+    this.hydrated = true;
+    if (this.io) {
+      try {
+        this.chunks = await this.io.load();
+      } catch {
+        this.chunks = [];
+      }
+    }
+  }
+
+  async upsert(chunks: Chunk[]): Promise<void> {
+    await this.hydrate();
+    for (const c of chunks) {
+      const i = this.chunks.findIndex((x) => x.id === c.id);
+      if (i >= 0) this.chunks[i] = c;
+      else this.chunks.push(c);
+    }
+    if (this.io) await this.io.save(this.chunks);
+  }
+
+  async query(embedding: number[], k: number): Promise<RetrievedChunk[]> {
+    await this.hydrate();
+    return this.chunks
+      .filter((c) => c.embedding && c.embedding.length > 0)
+      .map((c) => ({ ...c, score: cosineSimilarity(embedding, c.embedding!) }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, k);
+  }
+
+  async size(): Promise<number> {
+    await this.hydrate();
+    return this.chunks.length;
+  }
+
+  async clear(): Promise<void> {
+    await this.hydrate();
+    this.chunks = [];
+    if (this.io) await this.io.save(this.chunks);
+  }
+}

package/src/recipe/asset-send.ts

@@ -0,0 +1,79 @@
+/**
+ * Built-in "send an RGB asset" recipe — distinct from the BTC payments recipe
+ * because an asset amount must NOT be treated as fiat.
+ *
+ *   "send 10 USDT to bob"     → resolve_contact → rln_send_asset 🔒
+ *   "pay alice 5 XAUT"        → resolve_contact → rln_send_asset 🔒
+ *
+ * Fixes the bug where the payments recipe parsed "USDT" as a fiat currency and
+ * ran fiat_to_sats. Payments now excludes RGB assets; this recipe owns them.
+ */
+
+import type { Recipe, RecipeContext } from './types.js';
+
+const RGB_ASSET = /\b(usdt|tether|xaut|gold)\b/i;
+const isOnchainOrInvoice = (s: string) => /^(ln(bc|tb|bcrt)|bc1|tb1|lnurl|rgb:|[a-z0-9._-]+@)/i.test(s.trim());
+
+function normAsset(a?: string): string | undefined {
+  if (!a) return undefined;
+  const x = a.toLowerCase();
+  if (/usdt|tether/.test(x)) return 'USDT';
+  if (/xaut|gold/.test(x)) return 'XAUT';
+  return a.toUpperCase();
+}
+function parseAmount(t: string): number | undefined {
+  const m = t.match(/(\d[\d.,]*)\s*([km])?\b/i);
+  if (!m) return undefined;
+  let n = Number(m[1]!.replace(/,/g, ''));
+  if (m[2]) n *= m[2].toLowerCase() === 'k' ? 1_000 : 1_000_000;
+  return Number.isNaN(n) ? undefined : n;
+}
+
+/** "send 10 USDT to bob" / "pay alice 5 xaut". */
+export function extractAssetSend(text: string): Record<string, unknown> | null {
+  const t = text.trim();
+  if (!/\b(send|pay|transfer)\b/i.test(t)) return null;
+  const asset = normAsset(t.match(RGB_ASSET)?.[1]);
+  if (!asset) return null; // not an asset send → let the payments recipe handle it
+  const amount = parseAmount(t);
+  let recipient = t.match(/\bto\s+([^\s,]+)/i)?.[1];
+  if (!recipient) {
+    const after = t.match(/\b(?:pay|send|transfer)\s+([^\s,]+)/i)?.[1];
+    if (after && !/^\d/.test(after) && !RGB_ASSET.test(after)) recipient = after;
+  }
+  if (!recipient && amount == null) return null;
+  return { recipient, asset, amount };
+}
+
+export const assetSendRecipe: Recipe = {
+  name: 'pay-asset',
+  description: 'Send an RGB asset (USDT, XAUT) to a contact or address — resolves the contact, then sends (with confirmation).',
+  match: (t) => /\b(send|pay|transfer)\b/i.test(t) && RGB_ASSET.test(t) && !/\b(invoice|receive|swap|buy|sell|for)\b/i.test(t),
+  triggers: ['send', 'pay', 'transfer'],
+  slots: [
+    { name: 'recipient', type: 'string', description: 'Contact name, address, or RGB invoice', required: true },
+    { name: 'asset', type: 'string', description: 'RGB asset: USDT or XAUT', required: true },
+    { name: 'amount', type: 'number', description: 'Asset amount' },
+  ],
+  extract: extractAssetSend,
+  confident: (s) => !!s.recipient && !!s.asset,
+  steps: [
+    {
+      tool: 'resolve_contact',
+      as: 'contact',
+      args: (ctx) => ({ name: ctx.slots.recipient }),
+      skipIf: (ctx) => !ctx.slots.recipient || isOnchainOrInvoice(String(ctx.slots.recipient)),
+    },
+  ],
+  final: {
+    tool: 'rln_send_asset',
+    args: (ctx: RecipeContext) => {
+      const contact = ctx.results.contact as { ln_address?: string } | undefined;
+      return { asset: ctx.slots.asset, amount: ctx.slots.amount, to: contact?.ln_address ?? ctx.slots.recipient };
+    },
+  },
+  summary: (ctx) => {
+    const to = (ctx.results.contact as { name?: string } | undefined)?.name ?? ctx.slots.recipient;
+    return `Sent ${ctx.slots.amount} ${ctx.slots.asset} to ${to}.`;
+  },
+};

package/src/recipe/kaleidoswap-atomic.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it } from 'vitest';
+import { ToolRegistry } from '../tools/registry.js';
+import { InProcessToolSource } from '../tools/in-process.js';
+import type { LLMProvider } from '../providers/types.js';
+import { runRecipe } from './runner.js';
+import { kaleidoswapAtomicRecipe } from './kaleidoswap-atomic.js';
+
+// LLM provider that should never be called when slots are extracted deterministically.
+const refusingProvider: LLMProvider = {
+  name: 'refusing',
+  runTurn: async () => {
+    throw new Error('provider should NOT be called when extractSwap succeeds');
+  },
+};
+
+// Stub tools that record every call so we can assert the chain ran end-to-end.
+function buildStubs(captured: { name: string; args: any }[]) {
+  const tool = (name: string, response: any, spend = false) => ({
+    name,
+    description: '',
+    parameters: { type: 'object', properties: {} },
+    requiresConfirmation: spend,
+    handler: async (a: any) => {
+      captured.push({ name, args: a });
+      return typeof response === 'function' ? response(a) : response;
+    },
+  });
+  return new ToolRegistry([
+    new InProcessToolSource('kaleidoswap', [
+      tool('kaleidoswap_get_quote', { quote_id: 'q-1', receive_amount: 100, fees: 250 }),
+      tool('kaleidoswap_atomic_init', { atomic_id: 'a-1', maker_invoice: 'lnbc1maker' }, /* spend */ true),
+      tool('kaleidoswap_atomic_execute', { status: 'completed' }, /* spend */ true),
+    ]),
+    new InProcessToolSource('rln', [
+      tool('rln_create_rgb_invoice', { invoice: 'rgb:invoice:USDT:100' }),
+      tool('rln_create_ln_invoice', { invoice: 'lnbc1user' }),
+      tool('rln_pay_invoice', { status: 'SUCCESS', payment_hash: 'h' }, /* spend */ true),
+    ]),
+  ]);
+}
+
+describe('kaleidoswapAtomicRecipe — selection (match + triggers)', () => {
+  it('triggers on explicit atomic-swap phrasings', () => {
+    expect(kaleidoswapAtomicRecipe.match!('atomic swap 100000 sats for usdt')).toBe(true);
+    expect(kaleidoswapAtomicRecipe.match!('trustless swap btc to usdt')).toBe(true);
+    expect(kaleidoswapAtomicRecipe.match!('htlc swap 1000 sats to USDT')).toBe(true);
+  });
+
+  it('does NOT fire on a plain swap (those go to swapRecipe)', () => {
+    expect(kaleidoswapAtomicRecipe.match!('swap 10 usdt for btc')).toBe(false);
+    expect(kaleidoswapAtomicRecipe.match!('exchange 1000 sats for usdt')).toBe(false);
+  });
+});
+
+describe('kaleidoswapAtomicRecipe — RGB receive leg', () => {
+  it('runs quote → rgb_invoice → atomic_init → pay → atomic_execute (one inference)', async () => {
+    const captured: { name: string; args: any }[] = [];
+    const tools = buildStubs(captured);
+
+    const res = await runRecipe(kaleidoswapAtomicRecipe, 'atomic swap 100000 sats for usdt', {
+      provider: refusingProvider,
+      tools,
+      onConfirm: async () => ({ approved: true }),
+    });
+
+    expect(res.status).toBe('done');
+    expect(res.inferences).toBe(0); // extractSwap handled it deterministically
+
+    // The chain: quote → rgb_invoice → atomic_init → pay → atomic_execute (5 calls).
+    expect(captured.map((c) => c.name)).toEqual([
+      'kaleidoswap_get_quote',
+      'rln_create_rgb_invoice',
+      'kaleidoswap_atomic_init',
+      'rln_pay_invoice',
+      'kaleidoswap_atomic_execute',
+    ]);
+
+    // RGB invoice fed into atomic_init.
+    const init = captured.find((c) => c.name === 'kaleidoswap_atomic_init')!;
+    expect(init.args).toEqual({ quote_id: 'q-1', receive_invoice: 'rgb:invoice:USDT:100' });
+
+    // Maker invoice fed into pay step.
+    const pay = captured.find((c) => c.name === 'rln_pay_invoice')!;
+    expect(pay.args).toEqual({ invoice: 'lnbc1maker' });
+
+    // Final execute carried the atomic id.
+    const exe = captured.find((c) => c.name === 'kaleidoswap_atomic_execute')!;
+    expect(exe.args).toEqual({ atomic_id: 'a-1' });
+  });
+});
+
+describe('kaleidoswapAtomicRecipe — BTC receive leg', () => {
+  it('uses rln_create_ln_invoice (not rgb) when to_asset is BTC', async () => {
+    const captured: { name: string; args: any }[] = [];
+    const tools = buildStubs(captured);
+
+    const res = await runRecipe(kaleidoswapAtomicRecipe, 'atomic swap 100 usdt for btc', {
+      provider: refusingProvider,
+      tools,
+      onConfirm: async () => ({ approved: true }),
+    });
+
+    expect(res.status).toBe('done');
+    expect(captured.map((c) => c.name)).toEqual([
+      'kaleidoswap_get_quote',
+      'rln_create_ln_invoice',
+      'kaleidoswap_atomic_init',
+      'rln_pay_invoice',
+      'kaleidoswap_atomic_execute',
+    ]);
+    const init = captured.find((c) => c.name === 'kaleidoswap_atomic_init')!;
+    expect(init.args.receive_invoice).toBe('lnbc1user');
+  });
+});
+
+describe('kaleidoswapAtomicRecipe — confirmation gate', () => {
+  it('cancels the chain when the user declines a spend gate', async () => {
+    const captured: { name: string; args: any }[] = [];
+    const tools = buildStubs(captured);
+    let firstSpendSeen = false;
+
+    const res = await runRecipe(kaleidoswapAtomicRecipe, 'atomic swap 100000 sats for usdt', {
+      provider: refusingProvider,
+      tools,
+      onConfirm: async () => {
+        if (firstSpendSeen) return { approved: true };
+        firstSpendSeen = true;
+        return { approved: false, reason: 'user said no' };
+      },
+    });
+
+    expect(res.status).not.toBe('done');
+    // The first spend tool (atomic_init) should NOT have completed successfully —
+    // the chain stops before pay/execute.
+    expect(captured.some((c) => c.name === 'rln_pay_invoice')).toBe(false);
+    expect(captured.some((c) => c.name === 'kaleidoswap_atomic_execute')).toBe(false);
+  });
+});