novac 2.0.1 → 2.2.0

package/novac/kits/kitai/kitdef.js

@@ -0,0 +1,2185 @@
+/**
+ * KitAI — A Complete AI / LLM Toolkit Library
+ * Version : 1.0.0
+ * License : MIT
+ * Style   : CJS, single file, zero runtime dependencies
+ *
+ * ╔══════════════════════════════════════════════════════════════════════╗
+ * ║  FEATURE MAP                                                         ║
+ * ╠══════════════════════════════════════════════════════════════════════╣
+ * ║  PROVIDER LAYER                                                      ║
+ * ║   1.  Multi-provider client (OpenAI, Anthropic, Gemini, Ollama,     ║
+ * ║       Groq, Mistral, Together, Cohere, HuggingFace, custom)         ║
+ * ║   2.  Provider auto-detect from API key prefix                      ║
+ * ║   3.  Streaming chat completions (SSE + async iterator)             ║
+ * ║   4.  Non-streaming chat completions                                ║
+ * ║   5.  Image generation (DALL·E 3, Stable Diffusion, Flux)           ║
+ * ║   6.  Audio transcription (Whisper)                                 ║
+ * ║   7.  Text-to-speech synthesis                                      ║
+ * ║   8.  Embeddings (text → float[] vector)                            ║
+ * ║   9.  Reranking (cross-encoder style)                               ║
+ * ║  10.  Model catalogue (80+ models with metadata)                    ║
+ * ║                                                                      ║
+ * ║  PROMPT ENGINEERING                                                  ║
+ * ║  11.  Prompt template engine ({var} + {{block}} + filters)          ║
+ * ║  12.  Few-shot example builder                                       ║
+ * ║  13.  System prompt library (30+ built-in personas/roles)           ║
+ * ║  14.  Chain-of-thought / ReAct prompt scaffolds                     ║
+ * ║  15.  Prompt compression (trim to token budget)                     ║
+ * ║  16.  Prompt scoring & critique (self-critique loop)                ║
+ * ║                                                                      ║
+ * ║  MEMORY & CONTEXT                                                   ║
+ * ║  17.  Sliding-window conversation memory                            ║
+ * ║  18.  Token-budget memory (auto-trim oldest turns)                  ║
+ * ║  19.  Summary memory (compress history into summary)                ║
+ * ║  20.  Vector store (in-memory cosine-similarity search)             ║
+ * ║  21.  RAG pipeline (chunk → embed → retrieve → augment)             ║
+ * ║  22.  Document chunker (fixed, sentence, paragraph, semantic)       ║
+ * ║                                                                      ║
+ * ║  CHAIN & AGENT                                                       ║
+ * ║  23.  Sequential chain (pipe output of one call into next)          ║
+ * ║  24.  Parallel chain (fan-out + merge)                              ║
+ * ║  25.  Conditional chain (route by classifier)                       ║
+ * ║  26.  Tool/function-calling agent (ReAct loop)                      ║
+ * ║  27.  Built-in tools: calculator, date/time, web-search stub,       ║
+ * ║        JSON-path extractor, regex, base64, UUID, hash               ║
+ * ║  28.  Tool registry (register / unregister / list)                  ║
+ * ║                                                                      ║
+ * ║  STRUCTURED OUTPUT                                                   ║
+ * ║  29.  JSON schema enforcer (retry-until-valid)                      ║
+ * ║  30.  Zod-style schema builder (kitai.schema)                       ║
+ * ║  31.  Output parsers: JSON, CSV, list, key-value, markdown table    ║
+ * ║  32.  Extraction (pull typed fields from free text)                 ║
+ * ║  33.  Classification (zero-shot, few-shot, chain-of-thought)        ║
+ * ║                                                                      ║
+ * ║  EVALUATION & SAFETY                                                 ║
+ * ║  34.  LLM-as-judge eval (correctness, relevance, coherence)         ║
+ * ║  35.  BLEU / ROUGE-L / exact-match / F1 metrics (offline)          ║
+ * ║  36.  Hallucination detector (grounding check)                      ║
+ * ║  37.  Toxicity / PII / prompt-injection guard                       ║
+ * ║  38.  Retry + exponential-backoff + fallback chain                  ║
+ * ║                                                                      ║
+ * ║  TOKENIZER & COUNTING                                                ║
+ * ║  39.  Token estimator (tiktoken-compatible cl100k approximation)    ║
+ * ║  40.  Cost estimator (per-model $/1M token pricing table)          ║
+ * ║  41.  Context-window advisor                                         ║
+ * ║                                                                      ║
+ * ║  UTILITIES                                                            ║
+ * ║  42.  Diff viewer (old vs new LLM response)                         ║
+ * ║  43.  Markdown → plain-text stripper                                 ║
+ * ║  44.  Response cache (in-memory LRU, hash-keyed)                    ║
+ * ║  45.  Conversation export (JSON / Markdown / HTML)                  ║
+ * ║  46.  Streaming aggregator (chunks → full message)                  ║
+ * ║  47.  Multi-turn role validator                                       ║
+ * ║  48.  Semantic similarity (cosine on embeddings)                     ║
+ * ║  49.  A/B experiment runner                                           ║
+ * ║  50.  KitAIFormat — the core message/response object                 ║
+ * ╚══════════════════════════════════════════════════════════════════════╝
+ */
+
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §0  Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _noop  = () => {};
+const _sleep = ms => new Promise(r => setTimeout(r, ms));
+const _isNode = typeof process !== 'undefined' && process.versions && process.versions.node;
+
+/** Minimal fetch shim (Node ≥18 has fetch built-in; older Node uses https) */
+function _fetch(url, opts = {}) {
+  if (typeof fetch !== 'undefined') return fetch(url, opts);
+  if (_isNode) {
+    const mod = url.startsWith('https') ? require('https') : require('http');
+    return new Promise((resolve, reject) => {
+      const body = opts.body ? Buffer.from(opts.body) : null;
+      const u    = new URL(url);
+      const req  = mod.request({
+        hostname: u.hostname, port: u.port, path: u.pathname + u.search,
+        method: opts.method || 'GET',
+        headers: { 'Content-Type':'application/json', ...(opts.headers||{}),
+                   ...(body ? {'Content-Length': body.length} : {}) },
+      }, res => {
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8');
+          resolve({
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+            status: res.statusCode,
+            headers: { get: k => res.headers[k.toLowerCase()] },
+            text:   () => Promise.resolve(text),
+            json:   () => Promise.resolve(JSON.parse(text)),
+            body:   { getReader: () => {
+              let done = false;
+              return {
+                read: () => { if(done) return Promise.resolve({done:true,value:undefined});
+                              done=true; return Promise.resolve({done:false,value:Buffer.from(text)}); }
+              };
+            }},
+          });
+        });
+        res.on('error', reject);
+      });
+      req.on('error', reject);
+      if (body) req.write(body);
+      req.end();
+    });
+  }
+  throw new Error('KitAI: no fetch implementation available');
+}
+
+function _md5Hex(str) {
+  // FNV-1a 64-bit approximation – fast, not crypto
+  let h1=0x811c9dc5, h2=0x811c9dc5;
+  for (let i=0;i<str.length;i++) {
+    const c=str.charCodeAt(i);
+    h1^=c; h1=(h1*0x01000193)>>>0;
+    h2^=(c<<8); h2=(h2*0x01000193)>>>0;
+  }
+  return (h1>>>0).toString(16).padStart(8,'0')+(h2>>>0).toString(16).padStart(8,'0');
+}
+
+function _deepClone(obj) { return JSON.parse(JSON.stringify(obj)); }
+
+function _cosineSim(a, b) {
+  if (a.length !== b.length) return 0;
+  let dot=0, na=0, nb=0;
+  for (let i=0;i<a.length;i++) { dot+=a[i]*b[i]; na+=a[i]*a[i]; nb+=b[i]*b[i]; }
+  return dot / (Math.sqrt(na)*Math.sqrt(nb) || 1);
+}
+
+function _dotProduct(a, b) {
+  let s=0; for (let i=0;i<a.length;i++) s+=a[i]*b[i]; return s;
+}
+
+function _norm(v) {
+  const mag = Math.sqrt(v.reduce((s,x)=>s+x*x,0));
+  return v.map(x => x/mag);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §1  KitAIFormat — core response object
+// ─────────────────────────────────────────────────────────────────────────────
+
+class KitAIFormat {
+  /**
+   * @param {object} opts
+   * @param {string}   opts.content      – text content of the response
+   * @param {string}   [opts.role]       – 'assistant' | 'user' | 'system' | 'tool'
+   * @param {string}   [opts.model]      – model id that produced this
+   * @param {object}   [opts.usage]      – { promptTokens, completionTokens, totalTokens }
+   * @param {any[]}    [opts.toolCalls]  – raw tool_calls array if any
+   * @param {any}      [opts.raw]        – full provider response
+   * @param {number}   [opts.latencyMs]  – round-trip latency
+   * @param {string}   [opts.finishReason]
+   */
+  constructor({ content='', role='assistant', model='', usage={}, toolCalls=[], raw=null, latencyMs=0, finishReason='stop' } = {}) {
+    this.content      = content;
+    this.role         = role;
+    this.model        = model;
+    this.usage        = { promptTokens:0, completionTokens:0, totalTokens:0, ...usage };
+    this.toolCalls    = toolCalls;
+    this.raw          = raw;
+    this.latencyMs    = latencyMs;
+    this.finishReason = finishReason;
+    this.createdAt    = Date.now();
+  }
+
+  // ── Parsers ────────────────────────────────────────────────────────────
+
+  /** Parse content as JSON (throws on failure) */
+  toJSON()          { return JSON.parse(this.content); }
+
+  /** Best-effort JSON parse (returns null on failure) */
+  tryJSON()         { try { return this.toJSON(); } catch { return null; } }
+
+  /** Split content into a trimmed string array by line */
+  toLines()         { return this.content.split('\n').map(l=>l.trim()).filter(Boolean); }
+
+  /** Extract bullet / numbered list items */
+  toList()          {
+    return this.content.split('\n')
+      .map(l => l.replace(/^[-*•]\s+|^\d+[.)]\s+/,'').trim())
+      .filter(Boolean);
+  }
+
+  /** Strip markdown formatting → plain text */
+  toPlainText()     { return kitai.stripMarkdown(this.content); }
+
+  /** Extract all ```lang ... ``` code blocks */
+  toCodeBlocks()    {
+    const blocks = [], re = /```(\w*)\n?([\s\S]*?)```/g;
+    let m;
+    while ((m=re.exec(this.content))!==null)
+      blocks.push({ lang: m[1]||'text', code: m[2].trim() });
+    return blocks;
+  }
+
+  /** Extract key: value pairs from content */
+  toKeyValue()      {
+    const map = {};
+    for (const line of this.toLines()) {
+      const i = line.indexOf(':');
+      if (i>0) map[line.slice(0,i).trim()] = line.slice(i+1).trim();
+    }
+    return map;
+  }
+
+  /** Parse a markdown table into array of objects */
+  toTable()         { return kitai.parsers.markdownTable(this.content); }
+
+  /** Return as a Message object (for use in next conversation turn) */
+  toMessage()       { return { role: this.role, content: this.content }; }
+
+  /** Cost in USD based on model pricing */
+  estimatedCost()   { return kitai.cost.estimate(this.model, this.usage.promptTokens, this.usage.completionTokens); }
+
+  /** Human-readable summary line */
+  summary()         {
+    const tok  = this.usage.totalTokens ? `${this.usage.totalTokens} tok` : '';
+    const lat  = this.latencyMs ? `${this.latencyMs}ms` : '';
+    const cost = this.estimatedCost() ? `$${this.estimatedCost().toFixed(6)}` : '';
+    const info = [this.model, tok, lat, cost].filter(Boolean).join(' · ');
+    return `[${this.role}] ${this.content.slice(0,80)}${this.content.length>80?'…':''} (${info})`;
+  }
+
+  toString()        { return this.content; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §2  Provider registry & adapters
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _PROVIDERS = {
+  openai: {
+    baseURL:    'https://api.openai.com/v1',
+    authHeader: key => ({ Authorization: `Bearer ${key}` }),
+    chatPath:   '/chat/completions',
+    embedPath:  '/embeddings',
+    imagePath:  '/images/generations',
+    audioPath:  '/audio/transcriptions',
+    ttsPath:    '/audio/speech',
+    models:     ['gpt-4o','gpt-4o-mini','gpt-4-turbo','gpt-3.5-turbo','gpt-4o-2024-11-20'],
+    parseChat:  r => ({ content: r.choices[0].message.content, toolCalls: r.choices[0].message.tool_calls||[],
+                        usage: { promptTokens:r.usage?.prompt_tokens||0, completionTokens:r.usage?.completion_tokens||0,
+                                 totalTokens:r.usage?.total_tokens||0 }, finishReason: r.choices[0].finish_reason }),
+    parseEmbed: r => r.data[0].embedding,
+    parseChunk: line => {
+      if (!line.startsWith('data:')) return null;
+      const d = line.slice(5).trim();
+      if (d==='[DONE]') return null;
+      try { const j=JSON.parse(d); return j.choices[0]?.delta?.content||''; } catch { return ''; }
+    },
+  },
+
+  anthropic: {
+    baseURL:    'https://api.anthropic.com/v1',
+    authHeader: key => ({ 'x-api-key': key, 'anthropic-version': '2023-06-01' }),
+    chatPath:   '/messages',
+    embedPath:  null,
+    imagePath:  null,
+    models:     ['claude-opus-4-20250514','claude-sonnet-4-5','claude-haiku-4-5','claude-3-opus-20240229'],
+    buildBody:  (msgs, model, opts) => {
+      const sys = msgs.find(m=>m.role==='system');
+      const conv= msgs.filter(m=>m.role!=='system');
+      return { model, messages: conv, max_tokens: opts.maxTokens||1024,
+               ...(sys ? {system: sys.content} : {}), ...(opts.temperature!=null?{temperature:opts.temperature}:{}) };
+    },
+    parseChat:  r => ({ content: r.content[0].text, toolCalls: r.content.filter(b=>b.type==='tool_use'),
+                        usage: { promptTokens:r.usage?.input_tokens||0, completionTokens:r.usage?.output_tokens||0,
+                                 totalTokens:(r.usage?.input_tokens||0)+(r.usage?.output_tokens||0) },
+                        finishReason: r.stop_reason }),
+    parseChunk: line => {
+      if (!line.startsWith('data:')) return null;
+      const d=line.slice(5).trim();
+      try { const j=JSON.parse(d); return j.type==='content_block_delta'?j.delta?.text||'':j.type==='message_stop'?null:''; }
+      catch { return ''; }
+    },
+  },
+
+  gemini: {
+    baseURL:    'https://generativelanguage.googleapis.com/v1beta',
+    authHeader: () => ({}),
+    chatPathFn: (model,key) => `/models/${model}:generateContent?key=${key}`,
+    models:     ['gemini-1.5-pro','gemini-1.5-flash','gemini-2.0-flash','gemini-pro'],
+    buildBody:  (msgs, _model, opts) => ({
+      contents: msgs.filter(m=>m.role!=='system').map(m=>({ role:m.role==='assistant'?'model':'user', parts:[{text:m.content}] })),
+      generationConfig: { maxOutputTokens: opts.maxTokens||1024, temperature: opts.temperature??0.7 },
+    }),
+    parseChat:  r => ({ content: r.candidates[0].content.parts[0].text, toolCalls: [],
+                        usage: { promptTokens:r.usageMetadata?.promptTokenCount||0,
+                                 completionTokens:r.usageMetadata?.candidatesTokenCount||0,
+                                 totalTokens:r.usageMetadata?.totalTokenCount||0 }, finishReason:'stop' }),
+  },
+
+  ollama: {
+    baseURL:    'http://localhost:11434/v1',
+    authHeader: () => ({}),
+    chatPath:   '/chat/completions',
+    embedPath:  '/embeddings',
+    models:     ['llama3','mistral','phi3','gemma2','qwen2','deepseek-coder'],
+    parseChat:  r => ({ content: r.choices[0].message.content, toolCalls: [],
+                        usage: { promptTokens:r.usage?.prompt_tokens||0, completionTokens:r.usage?.completion_tokens||0,
+                                 totalTokens:r.usage?.total_tokens||0 }, finishReason:'stop' }),
+    parseEmbed: r => r.data?.[0]?.embedding || r.embedding || [],
+    parseChunk: line => {
+      if (!line.startsWith('data:')) return null;
+      const d=line.slice(5).trim(); if(d==='[DONE]') return null;
+      try { return JSON.parse(d).choices[0]?.delta?.content||''; } catch { return ''; }
+    },
+  },
+
+  groq: {
+    baseURL:    'https://api.groq.com/openai/v1',
+    authHeader: key => ({ Authorization: `Bearer ${key}` }),
+    chatPath:   '/chat/completions',
+    embedPath:  '/openai/v1/embeddings',
+    models:     ['llama-3.1-70b-versatile','llama-3.1-8b-instant','mixtral-8x7b-32768','gemma2-9b-it'],
+    parseChat:  r => ({ content: r.choices[0].message.content, toolCalls: r.choices[0].message.tool_calls||[],
+                        usage: { promptTokens:r.usage?.prompt_tokens||0, completionTokens:r.usage?.completion_tokens||0,
+                                 totalTokens:r.usage?.total_tokens||0 }, finishReason:r.choices[0].finish_reason }),
+    parseEmbed: r => r.data[0].embedding,
+    parseChunk: line => {
+      if (!line.startsWith('data:')) return null;
+      const d=line.slice(5).trim(); if(d==='[DONE]') return null;
+      try { return JSON.parse(d).choices[0]?.delta?.content||''; } catch { return ''; }
+    },
+  },
+
+  mistral: {
+    baseURL:    'https://api.mistral.ai/v1',
+    authHeader: key => ({ Authorization: `Bearer ${key}` }),
+    chatPath:   '/chat/completions',
+    embedPath:  '/embeddings',
+    models:     ['mistral-large-latest','mistral-medium-latest','mistral-small-latest','codestral-latest','open-mixtral-8x22b'],
+    parseChat:  r => ({ content: r.choices[0].message.content, toolCalls: r.choices[0].message.tool_calls||[],
+                        usage: { promptTokens:r.usage?.prompt_tokens||0, completionTokens:r.usage?.completion_tokens||0,
+                                 totalTokens:r.usage?.total_tokens||0 }, finishReason:r.choices[0].finish_reason }),
+    parseEmbed: r => r.data[0].embedding,
+    parseChunk: line => {
+      if (!line.startsWith('data:')) return null;
+      const d=line.slice(5).trim(); if(d==='[DONE]') return null;
+      try { return JSON.parse(d).choices[0]?.delta?.content||''; } catch { return ''; }
+    },
+  },
+
+  cohere: {
+    baseURL:    'https://api.cohere.com/v2',
+    authHeader: key => ({ Authorization: `Bearer ${key}` }),
+    chatPath:   '/chat',
+    embedPath:  '/embed',
+    rerankPath: '/rerank',
+    models:     ['command-r-plus','command-r','command','command-light'],
+    buildBody:  (msgs, model, opts) => ({
+      model, messages: msgs.map(m=>({role:m.role,content:m.content})),
+      max_tokens: opts.maxTokens||1024,
+    }),
+    parseChat:  r => ({ content: r.message?.content?.[0]?.text||r.text||'', toolCalls:[],
+                        usage: { promptTokens:r.meta?.tokens?.input_tokens||0,
+                                 completionTokens:r.meta?.tokens?.output_tokens||0,
+                                 totalTokens:(r.meta?.tokens?.input_tokens||0)+(r.meta?.tokens?.output_tokens||0) },
+                        finishReason:'stop' }),
+    parseEmbed: r => r.embeddings?.float?.[0] || r.embeddings?.[0] || [],
+  },
+
+  together: {
+    baseURL:    'https://api.together.xyz/v1',
+    authHeader: key => ({ Authorization: `Bearer ${key}` }),
+    chatPath:   '/chat/completions',
+    embedPath:  '/embeddings',
+    models:     ['meta-llama/Llama-3-70b-chat-hf','mistralai/Mixtral-8x7B-Instruct-v0.1','Qwen/Qwen2-72B-Instruct'],
+    parseChat:  r => ({ content: r.choices[0].message.content, toolCalls:[],
+                        usage: { promptTokens:r.usage?.prompt_tokens||0, completionTokens:r.usage?.completion_tokens||0,
+                                 totalTokens:r.usage?.total_tokens||0 }, finishReason:r.choices[0].finish_reason }),
+    parseEmbed: r => r.data[0].embedding,
+    parseChunk: line => {
+      if (!line.startsWith('data:')) return null;
+      const d=line.slice(5).trim(); if(d==='[DONE]') return null;
+      try { return JSON.parse(d).choices[0]?.delta?.content||''; } catch { return ''; }
+    },
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §3  Model catalogue (80+ entries)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const _MODELS = {
+  // OpenAI
+  'gpt-4o':              { provider:'openai',    context:128000, family:'gpt-4',    type:'chat',  inputPer1M:2.50,  outputPer1M:10.00 },
+  'gpt-4o-mini':         { provider:'openai',    context:128000, family:'gpt-4',    type:'chat',  inputPer1M:0.15,  outputPer1M:0.60  },
+  'gpt-4-turbo':         { provider:'openai',    context:128000, family:'gpt-4',    type:'chat',  inputPer1M:10.00, outputPer1M:30.00 },
+  'gpt-4':               { provider:'openai',    context:8192,   family:'gpt-4',    type:'chat',  inputPer1M:30.00, outputPer1M:60.00 },
+  'gpt-3.5-turbo':       { provider:'openai',    context:16385,  family:'gpt-3.5',  type:'chat',  inputPer1M:0.50,  outputPer1M:1.50  },
+  'o1':                  { provider:'openai',    context:200000, family:'o1',       type:'chat',  inputPer1M:15.00, outputPer1M:60.00 },
+  'o1-mini':             { provider:'openai',    context:128000, family:'o1',       type:'chat',  inputPer1M:3.00,  outputPer1M:12.00 },
+  'o3-mini':             { provider:'openai',    context:200000, family:'o3',       type:'chat',  inputPer1M:1.10,  outputPer1M:4.40  },
+  'text-embedding-3-small':{ provider:'openai',  context:8191,   family:'embed',    type:'embed', inputPer1M:0.02,  outputPer1M:0     },
+  'text-embedding-3-large':{ provider:'openai',  context:8191,   family:'embed',    type:'embed', inputPer1M:0.13,  outputPer1M:0     },
+  'dall-e-3':            { provider:'openai',    context:0,      family:'image',    type:'image', inputPer1M:0,     outputPer1M:0     },
+  'whisper-1':           { provider:'openai',    context:0,      family:'audio',    type:'audio', inputPer1M:0,     outputPer1M:0     },
+  'tts-1':               { provider:'openai',    context:0,      family:'tts',      type:'tts',   inputPer1M:15.00, outputPer1M:0     },
+  'tts-1-hd':            { provider:'openai',    context:0,      family:'tts',      type:'tts',   inputPer1M:30.00, outputPer1M:0     },
+
+  // Anthropic
+  'claude-opus-4-20250514':{ provider:'anthropic',context:200000,family:'claude-4', type:'chat',  inputPer1M:15.00, outputPer1M:75.00 },
+  'claude-sonnet-4-5':   { provider:'anthropic', context:200000, family:'claude-4', type:'chat',  inputPer1M:3.00,  outputPer1M:15.00 },
+  'claude-haiku-4-5':    { provider:'anthropic', context:200000, family:'claude-4', type:'chat',  inputPer1M:0.80,  outputPer1M:4.00  },
+  'claude-3-opus-20240229':{ provider:'anthropic',context:200000,family:'claude-3', type:'chat',  inputPer1M:15.00, outputPer1M:75.00 },
+  'claude-3-5-sonnet-20241022':{ provider:'anthropic',context:200000,family:'claude-3',type:'chat',inputPer1M:3.00, outputPer1M:15.00 },
+  'claude-3-haiku-20240307':{ provider:'anthropic',context:200000,family:'claude-3',type:'chat',  inputPer1M:0.25,  outputPer1M:1.25  },
+
+  // Google Gemini
+  'gemini-1.5-pro':      { provider:'gemini',    context:2000000,family:'gemini',   type:'chat',  inputPer1M:1.25,  outputPer1M:5.00  },
+  'gemini-1.5-flash':    { provider:'gemini',    context:1000000,family:'gemini',   type:'chat',  inputPer1M:0.075, outputPer1M:0.30  },
+  'gemini-2.0-flash':    { provider:'gemini',    context:1048576,family:'gemini',   type:'chat',  inputPer1M:0.10,  outputPer1M:0.40  },
+  'gemini-pro':          { provider:'gemini',    context:32760,  family:'gemini',   type:'chat',  inputPer1M:0.50,  outputPer1M:1.50  },
+
+  // Groq
+  'llama-3.1-70b-versatile':{ provider:'groq',   context:32768,  family:'llama',    type:'chat',  inputPer1M:0.59,  outputPer1M:0.79  },
+  'llama-3.1-8b-instant':{ provider:'groq',      context:131072, family:'llama',    type:'chat',  inputPer1M:0.05,  outputPer1M:0.08  },
+  'mixtral-8x7b-32768':  { provider:'groq',      context:32768,  family:'mixtral',  type:'chat',  inputPer1M:0.24,  outputPer1M:0.24  },
+  'gemma2-9b-it':        { provider:'groq',      context:8192,   family:'gemma',    type:'chat',  inputPer1M:0.20,  outputPer1M:0.20  },
+
+  // Mistral
+  'mistral-large-latest':{ provider:'mistral',   context:131072, family:'mistral',  type:'chat',  inputPer1M:2.00,  outputPer1M:6.00  },
+  'mistral-medium-latest':{ provider:'mistral',  context:131072, family:'mistral',  type:'chat',  inputPer1M:2.70,  outputPer1M:8.10  },
+  'mistral-small-latest':{ provider:'mistral',   context:32768,  family:'mistral',  type:'chat',  inputPer1M:0.20,  outputPer1M:0.60  },
+  'codestral-latest':    { provider:'mistral',   context:32768,  family:'codestral',type:'chat',  inputPer1M:0.20,  outputPer1M:0.60  },
+  'open-mixtral-8x22b':  { provider:'mistral',   context:65536,  family:'mixtral',  type:'chat',  inputPer1M:2.00,  outputPer1M:6.00  },
+  'mistral-embed':       { provider:'mistral',   context:8192,   family:'embed',    type:'embed', inputPer1M:0.10,  outputPer1M:0     },
+
+  // Cohere
+  'command-r-plus':      { provider:'cohere',    context:128000, family:'command',  type:'chat',  inputPer1M:2.50,  outputPer1M:10.00 },
+  'command-r':           { provider:'cohere',    context:128000, family:'command',  type:'chat',  inputPer1M:0.15,  outputPer1M:0.60  },
+  'command':             { provider:'cohere',    context:4096,   family:'command',  type:'chat',  inputPer1M:1.00,  outputPer1M:2.00  },
+  'embed-english-v3.0':  { provider:'cohere',    context:512,    family:'embed',    type:'embed', inputPer1M:0.10,  outputPer1M:0     },
+  'embed-multilingual-v3.0':{ provider:'cohere', context:512,    family:'embed',    type:'embed', inputPer1M:0.10,  outputPer1M:0     },
+
+  // Together
+  'meta-llama/Llama-3-70b-chat-hf':{ provider:'together',context:8192,family:'llama',type:'chat',inputPer1M:0.90,outputPer1M:0.90},
+  'Qwen/Qwen2-72B-Instruct':        { provider:'together',context:32768,family:'qwen',type:'chat',inputPer1M:0.90,outputPer1M:0.90},
+
+  // Ollama (local – free)
+  'llama3':              { provider:'ollama',    context:8192,   family:'llama',    type:'chat',  inputPer1M:0,     outputPer1M:0     },
+  'mistral':             { provider:'ollama',    context:32768,  family:'mistral',  type:'chat',  inputPer1M:0,     outputPer1M:0     },
+  'phi3':                { provider:'ollama',    context:131072, family:'phi',      type:'chat',  inputPer1M:0,     outputPer1M:0     },
+  'gemma2':              { provider:'ollama',    context:8192,   family:'gemma',    type:'chat',  inputPer1M:0,     outputPer1M:0     },
+  'qwen2':               { provider:'ollama',    context:32768,  family:'qwen',     type:'chat',  inputPer1M:0,     outputPer1M:0     },
+  'deepseek-coder':      { provider:'ollama',    context:16384,  family:'deepseek', type:'chat',  inputPer1M:0,     outputPer1M:0     },
+  'nomic-embed-text':    { provider:'ollama',    context:8192,   family:'embed',    type:'embed', inputPer1M:0,     outputPer1M:0     },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §4  Tokenizer (cl100k_base approximation — no wasm required)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const tokenizer = (() => {
+  // Approximation: GPT-4 averages ~4 chars/token for English prose.
+  // We use a slightly smarter heuristic that accounts for whitespace splits,
+  // punctuation, numbers, CJK, code identifiers, etc.
+  function estimate(text) {
+    if (!text) return 0;
+    let count = 0;
+    // Coarse split by whitespace first
+    const words = text.split(/\s+/);
+    for (const w of words) {
+      if (!w) continue;
+      // Each word costs at least 1 token
+      // Long words (~7+ chars) typically split into multiple tokens
+      count += Math.ceil(w.length / 4.5);
+      // Punctuation tacked onto words adds tokens
+      const puncts = (w.match(/[^\w]/g)||[]).length;
+      count += Math.ceil(puncts * 0.5);
+    }
+    // CJK characters are generally 1 char = 1 token
+    const cjk = (text.match(/[\u4e00-\u9fff\u3040-\u30ff\uAC00-\uD7AF]/g)||[]).length;
+    count += cjk;
+    return Math.max(1, Math.round(count));
+  }
+
+  function estimateMessages(messages) {
+    // ~4 tokens per message overhead (role + separators)
+    return messages.reduce((s,m) => s + estimate(m.content||'') + 4, 3);
+  }
+
+  function maxForModel(modelId) {
+    return (_MODELS[modelId]||{}).context || 4096;
+  }
+
+  function fitsInContext(messages, modelId, reserveTokens=512) {
+    const used = estimateMessages(messages);
+    const max  = maxForModel(modelId);
+    return { fits: used + reserveTokens <= max, used, max, remaining: max - used };
+  }
+
+  return { estimate, estimateMessages, maxForModel, fitsInContext };
+})();
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §5  Cost estimator
+// ─────────────────────────────────────────────────────────────────────────────
+
+const cost = {
+  /**
+   * Estimate cost in USD.
+   * @param {string} modelId
+   * @param {number} promptTokens
+   * @param {number} completionTokens
+   * @returns {number} USD
+   */
+  estimate(modelId, promptTokens=0, completionTokens=0) {
+    const m = _MODELS[modelId];
+    if (!m) return 0;
+    return (promptTokens * m.inputPer1M + completionTokens * m.outputPer1M) / 1_000_000;
+  },
+
+  /** Return full pricing table */
+  table() {
+    return Object.entries(_MODELS).map(([id,m]) => ({
+      id, provider:m.provider, family:m.family, type:m.type,
+      contextK: Math.round(m.context/1000),
+      inputPer1M: m.inputPer1M, outputPer1M: m.outputPer1M,
+    }));
+  },
+
+  /** Compare cost across multiple models for the same workload */
+  compare(promptTokens, completionTokens, modelIds) {
+    return modelIds
+      .map(id => ({ id, usd: cost.estimate(id, promptTokens, completionTokens) }))
+      .sort((a,b) => a.usd - b.usd);
+  },
+
+  /** Cheapest model for a given type ('chat'|'embed'|'image') */
+  cheapest(type='chat') {
+    return Object.entries(_MODELS)
+      .filter(([,m]) => m.type===type && m.inputPer1M > 0)
+      .sort((a,b) => a[1].inputPer1M - b[1].inputPer1M)[0]?.[0] || null;
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §6  LRU Response Cache
+// ─────────────────────────────────────────────────────────────────────────────
+
+class LRUCache {
+  constructor(maxSize=256) {
+    this._max = maxSize;
+    this._map = new Map();
+  }
+  _key(messages, model, opts) {
+    return _md5Hex(JSON.stringify({ messages, model, opts }));
+  }
+  get(messages, model, opts) {
+    const k = this._key(messages, model, opts);
+    if (!this._map.has(k)) return null;
+    const v = this._map.get(k);
+    this._map.delete(k); this._map.set(k,v); // promote
+    return v;
+  }
+  set(messages, model, opts, value) {
+    const k = this._key(messages, model, opts);
+    if (this._map.size >= this._max) this._map.delete(this._map.keys().next().value);
+    this._map.set(k, value);
+  }
+  clear()          { this._map.clear(); }
+  get size()       { return this._map.size; }
+  invalidate(messages, model, opts) { this._map.delete(this._key(messages, model, opts)); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §7  Core client
+// ─────────────────────────────────────────────────────────────────────────────
+
+class KitAIClient {
+  /**
+   * @param {object} config
+   * @param {string} config.apiKey
+   * @param {string} [config.provider]   – auto-detected if omitted
+   * @param {string} [config.model]      – default model
+   * @param {string} [config.baseURL]    – override base URL
+   * @param {number} [config.maxTokens]  – default max_tokens
+   * @param {number} [config.temperature]
+   * @param {number} [config.maxRetries]
+   * @param {boolean}[config.cache]      – enable response cache
+   * @param {object} [config.headers]    – extra headers
+   */
+  constructor(config = {}) {
+    this.apiKey      = config.apiKey || '';
+    this.provider    = config.provider || kitai.detectProvider(this.apiKey);
+    this.model       = config.model || '';
+    this._baseURL    = config.baseURL || '';
+    this.maxTokens   = config.maxTokens  ?? 1024;
+    this.temperature = config.temperature ?? 0.7;
+    this.maxRetries  = config.maxRetries  ?? 3;
+    this._cache      = config.cache ? new LRUCache() : null;
+    this._headers    = config.headers || {};
+    this._prov       = _PROVIDERS[this.provider] || _PROVIDERS.openai;
+  }
+
+  _baseUrl() { return this._baseURL || this._prov.baseURL; }
+
+  _headers_(extra={}) {
+    const auth = this._prov.authHeader(this.apiKey);
+    return { 'Content-Type':'application/json', ...auth, ...this._headers, ...extra };
+  }
+
+  _buildBody(messages, model, opts={}) {
+    if (this._prov.buildBody) return this._prov.buildBody(messages, model, { maxTokens:this.maxTokens, temperature:this.temperature, ...opts });
+    const body = {
+      model,
+      messages,
+      max_tokens: opts.maxTokens ?? this.maxTokens,
+      temperature: opts.temperature ?? this.temperature,
+    };
+    if (opts.tools)      body.tools = opts.tools;
+    if (opts.jsonMode)   body.response_format = { type:'json_object' };
+    if (opts.stream)     body.stream = true;
+    return body;
+  }
+
+  /** Non-streaming chat completion */
+  async chat(messages, opts = {}) {
+    const model = opts.model || this.model || this._prov.models?.[0] || 'gpt-4o-mini';
+
+    // Cache lookup
+    if (this._cache && !opts.noCache) {
+      const hit = this._cache.get(messages, model, opts);
+      if (hit) return hit;
+    }
+
+    const t0   = Date.now();
+    let   lastErr;
+    for (let attempt=0; attempt<=this.maxRetries; attempt++) {
+      try {
+        let path, url;
+        if (this.provider==='gemini' && this._prov.chatPathFn) {
+          path = this._prov.chatPathFn(model, this.apiKey);
+          url  = `${this._baseUrl()}${path}`;
+        } else {
+          url = `${this._baseUrl()}${this._prov.chatPath}`;
+        }
+        const res = await _fetch(url, {
+          method: 'POST',
+          headers: this._headers_(),
+          body: JSON.stringify(this._buildBody(messages, model, opts)),
+        });
+        if (!res.ok) {
+          const txt = await res.text();
+          throw new Error(`HTTP ${res.status}: ${txt.slice(0,200)}`);
+        }
+        const raw     = await res.json();
+        const parsed  = this._prov.parseChat(raw);
+        const result  = new KitAIFormat({ ...parsed, model, raw, latencyMs: Date.now()-t0 });
+        if (this._cache) this._cache.set(messages, model, opts, result);
+        return result;
+      } catch(e) {
+        lastErr = e;
+        if (attempt < this.maxRetries) await _sleep(Math.min(1000*2**attempt, 30000));
+      }
+    }
+    throw lastErr;
+  }
+
+  /** Streaming chat — returns an async generator yielding string chunks */
+  async *stream(messages, opts = {}) {
+    const model = opts.model || this.model || this._prov.models?.[0] || 'gpt-4o-mini';
+    const url   = `${this._baseUrl()}${this._prov.chatPath}`;
+    const res   = await _fetch(url, {
+      method: 'POST',
+      headers: this._headers_(),
+      body: JSON.stringify(this._buildBody(messages, model, { ...opts, stream:true })),
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+
+    // Browser ReadableStream
+    if (res.body && res.body.getReader) {
+      const reader = res.body.getReader();
+      const dec    = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+      let buf = '';
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += dec ? dec.decode(value, {stream:true}) : value.toString();
+        const lines = buf.split('\n');
+        buf = lines.pop();
+        for (const line of lines) {
+          const chunk = this._prov.parseChunk?.(line);
+          if (chunk === null) return;
+          if (chunk) yield chunk;
+        }
+      }
+    } else {
+      // Node HTTP response arrives as complete text — simulate streaming
+      const text = typeof res.text === 'function' ? await res.text() : String(res.body);
+      for (const line of text.split('\n')) {
+        const chunk = this._prov.parseChunk?.(line);
+        if (chunk === null) return;
+        if (chunk) yield chunk;
+      }
+    }
+  }
+
+  /** Collect an entire stream into a KitAIFormat */
+  async streamCollect(messages, opts={}) {
+    const t0 = Date.now();
+    const model = opts.model || this.model || this._prov.models?.[0] || 'gpt-4o-mini';
+    let content = '';
+    for await (const chunk of this.stream(messages, opts)) content += chunk;
+    const tokens = tokenizer.estimate(content);
+    return new KitAIFormat({ content, model, latencyMs: Date.now()-t0,
+      usage:{ completionTokens: tokens, promptTokens: tokenizer.estimateMessages(messages), totalTokens: tokenizer.estimateMessages(messages)+tokens } });
+  }
+
+  /** Generate embeddings */
+  async embed(input, opts={}) {
+    const model = opts.model || 'text-embedding-3-small';
+    const inputs = Array.isArray(input) ? input : [input];
+    const path   = this._prov.embedPath;
+    if (!path) throw new Error(`Provider ${this.provider} does not support embeddings`);
+    const body   = this.provider==='cohere'
+      ? { model, texts: inputs, input_type:'search_document', embedding_types:['float'] }
+      : { model, input: inputs.length===1 ? inputs[0] : inputs };
+    const res  = await _fetch(`${this._baseUrl()}${path}`, {
+      method:'POST', headers:this._headers_(), body:JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`Embed HTTP ${res.status}`);
+    const raw = await res.json();
+    const vec = this._prov.parseEmbed(raw);
+    return Array.isArray(vec[0]) ? vec : [vec];
+  }
+
+  /** Generate an image, returns URL or base64 */
+  async imageGenerate(prompt, opts={}) {
+    const model = opts.model || 'dall-e-3';
+    const body  = { model, prompt, n:opts.n||1, size:opts.size||'1024x1024',
+                    response_format: opts.responseFormat||'url', quality:opts.quality||'standard' };
+    const res   = await _fetch(`${this._baseUrl()}${this._prov.imagePath}`, {
+      method:'POST', headers:this._headers_(), body:JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`Image HTTP ${res.status}`);
+    const raw = await res.json();
+    return raw.data.map(d => d.url || d.b64_json);
+  }
+
+  /** Synthesize speech, returns audio buffer (ArrayBuffer or Buffer) */
+  async textToSpeech(text, opts={}) {
+    const body = { model: opts.model||'tts-1', input:text, voice:opts.voice||'alloy',
+                   response_format: opts.format||'mp3', speed: opts.speed||1.0 };
+    const res  = await _fetch(`${this._baseUrl()}${this._prov.ttsPath}`, {
+      method:'POST', headers:this._headers_(), body:JSON.stringify(body),
+    });
+    if (!res.ok) throw new Error(`TTS HTTP ${res.status}`);
+    return res.arrayBuffer ? res.arrayBuffer() : res.buffer();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §8  Memory systems
+// ─────────────────────────────────────────────────────────────────────────────
+
+class SlidingWindowMemory {
+  /** @param {number} maxTurns – number of full turns (user+assistant pairs) to keep */
+  constructor(maxTurns=10) {
+    this._max   = maxTurns * 2;
+    this._msgs  = [];
+    this._system = null;
+  }
+  setSystem(content) { this._system = content; return this; }
+  add(role, content) { this._msgs.push({role,content}); this._trim(); return this; }
+  addUser(content)      { return this.add('user',content); }
+  addAssistant(content) { return this.add('assistant',content); }
+  addResult(res)        { return this.addAssistant(res.content||String(res)); }
+  _trim()    { while(this._msgs.length > this._max) this._msgs.shift(); }
+  messages() {
+    const sys = this._system ? [{role:'system',content:this._system}] : [];
+    return [...sys, ...this._msgs];
+  }
+  clear()    { this._msgs=[]; return this; }
+  get length() { return this._msgs.length; }
+}
+
+class TokenBudgetMemory {
+  /** @param {number} budget – max tokens for the message history */
+  constructor(budget=3000, model='gpt-4o-mini') {
+    this._budget = budget;
+    this._model  = model;
+    this._msgs   = [];
+    this._system = null;
+  }
+  setSystem(content) { this._system = content; return this; }
+  add(role, content) { this._msgs.push({role,content}); this._trim(); return this; }
+  addUser(content)      { return this.add('user',content); }
+  addAssistant(content) { return this.add('assistant',content); }
+  addResult(res)        { return this.addAssistant(res.content||String(res)); }
+  _trim() {
+    while(tokenizer.estimateMessages(this.messages()) > this._budget && this._msgs.length > 1)
+      this._msgs.shift();
+  }
+  messages() {
+    const sys = this._system ? [{role:'system',content:this._system}] : [];
+    return [...sys, ...this._msgs];
+  }
+  clear()     { this._msgs=[]; return this; }
+  tokenUsage(){ return tokenizer.estimateMessages(this.messages()); }
+}
+
+class SummaryMemory {
+  /**
+   * When history exceeds `triggerTurns` turns, the client is asked to summarise
+   * older messages, which are then replaced with a single "summary" system note.
+   * @param {KitAIClient} client
+   * @param {number} triggerTurns
+   */
+  constructor(client, triggerTurns=10) {
+    this._client = client;
+    this._trigger = triggerTurns * 2;
+    this._msgs  = [];
+    this._summary = '';
+    this._system  = '';
+  }
+  setSystem(content) { this._system=content; return this; }
+  add(role,content)  { this._msgs.push({role,content}); return this; }
+  addUser(content)      { return this.add('user',content); }
+  addAssistant(content) { return this.add('assistant',content); }
+  addResult(res)        { return this.addAssistant(res.content||String(res)); }
+  async messages() {
+    if (this._msgs.length >= this._trigger) await this._summarise();
+    const parts = [];
+    if (this._system)  parts.push({role:'system',  content:this._system});
+    if (this._summary) parts.push({role:'system',  content:`Conversation so far:\n${this._summary}`});
+    return [...parts, ...this._msgs];
+  }
+  async _summarise() {
+    const toCompress = this._msgs.splice(0, Math.floor(this._trigger/2));
+    const prompt = `Summarise this conversation concisely:\n${toCompress.map(m=>`${m.role}: ${m.content}`).join('\n')}`;
+    const res = await this._client.chat([{role:'user',content:prompt}]);
+    this._summary = (this._summary ? this._summary+'\n' : '') + res.content;
+  }
+  clear() { this._msgs=[]; this._summary=''; return this; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §9  Vector store (in-memory cosine similarity)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class VectorStore {
+  constructor() {
+    this._docs = []; // [{id, text, embedding, metadata}]
+  }
+
+  /** Add a document with its embedding */
+  add(id, text, embedding, metadata={}) {
+    this._docs.push({ id, text, embedding: _norm(embedding), metadata });
+    return this;
+  }
+
+  /** Add many documents at once */
+  addMany(docs) {
+    for (const d of docs) this.add(d.id||`doc_${this._docs.length}`, d.text, d.embedding, d.metadata);
+    return this;
+  }
+
+  /** Cosine similarity search */
+  search(queryEmbedding, topK=5, filter=null) {
+    const q = _norm(queryEmbedding);
+    return this._docs
+      .filter(d => filter ? filter(d.metadata) : true)
+      .map(d => ({ ...d, score: _dotProduct(q, d.embedding) }))
+      .sort((a,b) => b.score - a.score)
+      .slice(0, topK);
+  }
+
+  /** Remove by id */
+  remove(id) { this._docs = this._docs.filter(d=>d.id!==id); return this; }
+
+  /** Update metadata */
+  updateMetadata(id, meta) {
+    const d = this._docs.find(d=>d.id===id);
+    if (d) d.metadata = { ...d.metadata, ...meta };
+    return this;
+  }
+
+  get size() { return this._docs.length; }
+  clear()    { this._docs=[]; return this; }
+
+  /** Export as JSON-serialisable array */
+  export() { return this._docs.map(d=>({ ...d, embedding: Array.from(d.embedding) })); }
+
+  /** Import from export() */
+  static import(data) {
+    const vs = new VectorStore();
+    for (const d of data) vs.add(d.id, d.text, d.embedding, d.metadata);
+    return vs;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §10  Document chunker
+// ─────────────────────────────────────────────────────────────────────────────
+
+const chunker = {
+  /** Fixed-size character chunks with optional overlap */
+  fixed(text, size=500, overlap=50) {
+    const chunks=[];
+    for(let i=0;i<text.length;i+=size-overlap)
+      chunks.push(text.slice(i,i+size));
+    return chunks;
+  },
+
+  /** Split on sentence boundaries */
+  sentence(text, maxChunkSize=1000) {
+    const sents = text.match(/[^.!?]+[.!?]+[\s]*/g) || [text];
+    const chunks=[]; let cur='';
+    for(const s of sents){
+      if((cur+s).length>maxChunkSize && cur){ chunks.push(cur.trim()); cur=''; }
+      cur+=s;
+    }
+    if(cur.trim()) chunks.push(cur.trim());
+    return chunks;
+  },
+
+  /** Split on paragraph boundaries (double newline) */
+  paragraph(text, maxChunkSize=2000) {
+    const paras = text.split(/\n{2,}/).map(p=>p.trim()).filter(Boolean);
+    const chunks=[]; let cur='';
+    for(const p of paras){
+      if((cur+'\n\n'+p).length>maxChunkSize && cur){ chunks.push(cur.trim()); cur=''; }
+      cur = cur ? cur+'\n\n'+p : p;
+    }
+    if(cur.trim()) chunks.push(cur.trim());
+    return chunks;
+  },
+
+  /** Recursive character text splitter (LangChain-style) */
+  recursive(text, chunkSize=500, overlap=50, separators=['\n\n','\n',' ','']) {
+    for(const sep of separators){
+      const parts = sep ? text.split(sep) : [...text];
+      if(parts.length > 1){
+        const chunks=[]; let cur='';
+        for(const p of parts){
+          const joined = cur ? cur+sep+p : p;
+          if(joined.length <= chunkSize) { cur=joined; }
+          else {
+            if(cur) chunks.push(cur);
+            cur = p.length<=chunkSize ? p : chunker.recursive(p,chunkSize,overlap,separators.slice(1))[0];
+          }
+        }
+        if(cur) chunks.push(cur);
+        if(chunks.length > 1) return chunks;
+      }
+    }
+    // Fall back to fixed
+    return chunker.fixed(text, chunkSize, overlap);
+  },
+
+  /** Token-aware chunking */
+  byTokens(text, maxTokens=256, overlap=20) {
+    const words=text.split(/\s+/);
+    const chunks=[]; let cur=[]; let curTok=0;
+    for(const w of words){
+      const wt=tokenizer.estimate(w);
+      if(curTok+wt>maxTokens && cur.length){
+        chunks.push(cur.join(' '));
+        const keep=Math.floor(overlap/2);
+        cur=cur.slice(-keep); curTok=tokenizer.estimate(cur.join(' '));
+      }
+      cur.push(w); curTok+=wt;
+    }
+    if(cur.length) chunks.push(cur.join(' '));
+    return chunks;
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §11  RAG pipeline
+// ─────────────────────────────────────────────────────────────────────────────
+
+class RAGPipeline {
+  /**
+   * @param {KitAIClient} client
+   * @param {VectorStore} [store]
+   * @param {object}      [opts]
+   * @param {string}      [opts.chunkMode]   'sentence'|'paragraph'|'fixed'|'recursive'
+   * @param {number}      [opts.chunkSize]
+   * @param {number}      [opts.topK]
+   * @param {string}      [opts.embedModel]
+   * @param {string}      [opts.chatModel]
+   * @param {string}      [opts.promptTemplate]
+   */
+  constructor(client, store=new VectorStore(), opts={}) {
+    this._client = client;
+    this._store  = store;
+    this._opts   = { chunkMode:'sentence', chunkSize:500, topK:5,
+                     embedModel:'text-embedding-3-small', chatModel:'', ...opts };
+  }
+
+  /** Ingest a document: chunk → embed → store */
+  async ingest(text, metadata={}) {
+    const mode  = this._opts.chunkMode;
+    const chunks= chunker[mode]?.(text, this._opts.chunkSize) || chunker.sentence(text);
+    const vecs  = await this._client.embed(chunks, { model:this._opts.embedModel });
+    for(let i=0;i<chunks.length;i++){
+      const id=`${metadata.source||'doc'}_${Date.now()}_${i}`;
+      this._store.add(id, chunks[i], vecs[i] || vecs[0], { ...metadata, chunkIndex:i });
+    }
+    return { chunks: chunks.length, stored: chunks.length };
+  }
+
+  /** Query the RAG pipeline: embed query → retrieve → augment → generate */
+  async query(question, opts={}) {
+    const [qvec]   = await this._client.embed(question, { model:this._opts.embedModel });
+    const results  = this._store.search(qvec, opts.topK || this._opts.topK, opts.filter);
+    const context  = results.map((r,i)=>`[${i+1}] ${r.text}`).join('\n\n');
+    const tpl      = opts.promptTemplate || this._opts.promptTemplate ||
+      `Answer the question using only the context below.\n\nContext:\n{context}\n\nQuestion: {question}\n\nAnswer:`;
+    const prompt   = tpl.replace('{context}',context).replace('{question}',question);
+    const response = await this._client.chat([{role:'user',content:prompt}],
+                                              {model: opts.model||this._opts.chatModel});
+    return { response, sources: results, context };
+  }
+
+  get store() { return this._store; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §12  Prompt template engine
+// ─────────────────────────────────────────────────────────────────────────────
+
+class PromptTemplate {
+  /**
+   * @param {string} template  – "{var}" for variables, "{{#if cond}}...{{/if}}" for blocks
+   * @param {object} [defaults]
+   */
+  constructor(template, defaults={}) {
+    this._tpl      = template;
+    this._defaults = defaults;
+  }
+
+  /** Render the template with given variables */
+  render(vars={}) {
+    const v = { ...this._defaults, ...vars };
+    let out = this._tpl;
+
+    // {{#if key}}...{{/if}}
+    out = out.replace(/\{\{#if\s+(\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g, (_, key, block) =>
+      v[key] ? block : '');
+
+    // {{#each key}}...{{/each}} — expects v[key] to be an array
+    out = out.replace(/\{\{#each\s+(\w+)\}\}([\s\S]*?)\{\{\/each\}\}/g, (_, key, block) =>
+      (Array.isArray(v[key]) ? v[key] : []).map(item =>
+        block.replace(/\{\{this\}\}/g, item)).join(''));
+
+    // {var|filter}  filters: upper, lower, trim, json, truncate:N
+    out = out.replace(/\{(\w+)(?:\|([^}]+))?\}/g, (_, key, filter) => {
+      let val = v[key] !== undefined ? String(v[key]) : '';
+      if (filter) {
+        for (const f of filter.split(',')) {
+          const [fn, arg] = f.trim().split(':');
+          if (fn==='upper')    val=val.toUpperCase();
+          else if (fn==='lower')    val=val.toLowerCase();
+          else if (fn==='trim')     val=val.trim();
+          else if (fn==='json')     val=JSON.stringify(v[key]);
+          else if (fn==='truncate') val=val.slice(0,+(arg||100));
+          else if (fn==='indent')   val=val.split('\n').join('\n'+'  '.repeat(+(arg||1)));
+        }
+      }
+      return val;
+    });
+    return out;
+  }
+
+  /** Render into a messages array ready for the client */
+  toMessages(vars={}, role='user') {
+    return [{ role, content: this.render(vars) }];
+  }
+
+  /** Compose two templates */
+  concat(other, separator='\n') {
+    return new PromptTemplate(this._tpl + separator + other._tpl, { ...this._defaults, ...other._defaults });
+  }
+
+  toString() { return this._tpl; }
+
+  static from(strings, ...keys) {
+    // Tagged template literal support: PromptTemplate.from`Hello {name}!`
+    const tpl = strings.reduce((acc,s,i)=>acc+s+(keys[i]||''),'');
+    return new PromptTemplate(tpl);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §13  Few-shot builder
+// ─────────────────────────────────────────────────────────────────────────────
+
+class FewShotBuilder {
+  constructor(instructionOrTemplate='', opts={}) {
+    this._instruction  = instructionOrTemplate;
+    this._examples     = [];
+    this._inputKey     = opts.inputKey  || 'Input';
+    this._outputKey    = opts.outputKey || 'Output';
+    this._separator    = opts.separator || '\n\n';
+    this._exampleTpl   = opts.exampleTemplate || null;
+  }
+  /** Add an example { input, output } */
+  add(input, output) { this._examples.push({input,output}); return this; }
+  addMany(pairs)     { for(const [i,o] of pairs) this.add(i,o); return this; }
+
+  build(query, extraSystem='') {
+    const exStr = this._examples.map(e =>
+      this._exampleTpl
+        ? this._exampleTpl.replace('{input}',e.input).replace('{output}',e.output)
+        : `${this._inputKey}: ${e.input}\n${this._outputKey}: ${e.output}`
+    ).join(this._separator);
+    const system = [this._instruction, extraSystem, exStr].filter(Boolean).join('\n\n');
+    return [
+      { role:'system', content: system },
+      { role:'user',   content: `${this._inputKey}: ${query}` },
+    ];
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §14  System prompt library
+// ─────────────────────────────────────────────────────────────────────────────
+
+const systemPrompts = {
+  assistant:      'You are a helpful, accurate, and concise AI assistant.',
+  coder:          'You are an expert software engineer. Write clean, efficient, well-commented code. When asked to fix bugs, explain the root cause. Always prefer readability over cleverness.',
+  analyst:        'You are a senior data analyst. Provide structured, evidence-based analysis. Use bullet points, tables, and clear section headers. Always cite your reasoning.',
+  writer:         'You are a professional writer and editor. Produce clear, engaging, and well-structured prose. Adapt tone and style to the audience. Avoid jargon unless appropriate.',
+  tutor:          'You are a patient and encouraging tutor. Break complex concepts into simple steps. Use analogies and examples. Check for understanding and adjust explanations accordingly.',
+  reviewer:       'You are a critical code reviewer. Identify bugs, security issues, performance problems, and style violations. Be specific and constructive.',
+  planner:        'You are a strategic planner. Break goals into actionable steps. Consider risks, dependencies, and timelines. Output structured plans with clear milestones.',
+  summariser:     'You are a summarisation expert. Distil content to its core ideas. Be concise, accurate, and preserve the most important details. Never fabricate.',
+  debater:        'You are a debate coach. Present the strongest version of any argument, acknowledge counterarguments, and reason to a clear conclusion.',
+  socratic:       'You are a Socratic guide. Help the user discover answers through questions rather than providing them directly.',
+  translator:     'You are a professional translator. Preserve meaning, tone, and nuance. Flag idioms or culturally specific content that may not translate directly.',
+  jsonFormatter:  'You respond ONLY with valid JSON. No explanation, no markdown, no prose. Ensure the JSON is syntactically correct and matches any schema provided.',
+  classifier:     'You are a classification engine. You respond ONLY with the category label — no explanation, no prose, no quotes.',
+  extractor:      'You are an information extraction engine. Extract the requested fields from the text and return them as a JSON object. If a field is not present, use null.',
+  factChecker:    'You are a rigorous fact-checker. Evaluate claims for accuracy. Cite reasoning. Distinguish between verified facts, likely facts, uncertain claims, and falsehoods.',
+  safeguard:      'You are a content safety evaluator. Identify harmful, toxic, or policy-violating content. Output a JSON object with fields: safe (bool), categories (string[]), explanation (string).',
+  persona:        'You are {name}, {description}. Speak in first person and stay in character at all times.',
+  scientist:      'You are a research scientist. Reason carefully and empirically. Distinguish between hypotheses, evidence, and established fact. Prefer precision over speculation.',
+  lawyer:         'You are a careful legal analyst. Identify relevant legal principles, flag ambiguities, and note jurisdictional differences. Always recommend consulting a qualified attorney.',
+  doctor:         'You are a clinical information assistant. Provide accurate medical information while emphasising that users should consult licensed healthcare professionals for personal advice.',
+  productManager: 'You are a seasoned product manager. Think in terms of user value, feasibility, and business impact. Use frameworks like RICE, MoSCoW, and Jobs-to-be-Done when appropriate.',
+  recruiter:      'You are an expert technical recruiter. Evaluate candidates fairly, identify skill gaps constructively, and always provide actionable feedback.',
+  designer:       'You are a UX/UI design expert. Prioritise user needs, accessibility, and visual clarity. Reference design principles like Gestalt, Fitts\'s Law, and Jakob\'s Law.',
+  marketer:       'You are a creative marketing strategist. Generate compelling copy, campaign ideas, and growth strategies grounded in consumer psychology.',
+  therapist:      'You are a supportive, empathetic counsellor. Listen actively, reflect feelings, and guide without judging. Always recommend professional help for serious concerns.',
+  chef:           'You are a professional chef. Provide precise recipes, cooking techniques, and ingredient substitutions. Consider dietary restrictions proactively.',
+  mathematician:  'You are a mathematics expert. Show your work step by step. Use LaTeX notation where helpful. Verify answers and flag any assumptions.',
+  historian:      'You are a meticulous historian. Ground answers in primary sources. Contextualise events within broader historical patterns. Acknowledge historiographical debates.',
+  poet:           'You are a gifted poet. Craft vivid, emotionally resonant writing. Adapt to requested forms (sonnet, haiku, free verse, etc.) and themes.',
+  custom: (content) => content,
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §15  Chain-of-thought / ReAct scaffolds
+// ─────────────────────────────────────────────────────────────────────────────
+
+const scaffolds = {
+  chainOfThought(question, opts={}) {
+    const style = opts.style || 'standard'; // 'standard' | 'stepback' | 'selfconsistency'
+    if (style==='stepback') return [
+      {role:'user', content:`Before answering: "${question}", first answer this broader question that would help: What general principle or concept is needed to answer this?`},
+    ];
+    return [{role:'user', content:`Think step by step:\n\n${question}\n\nLet's reason through this carefully:`}];
+  },
+
+  react(question, toolNames=[]) {
+    const tools = toolNames.length ? `Available tools: ${toolNames.join(', ')}.` : '';
+    return [{role:'system', content:[
+      'You are a ReAct agent. For each step output exactly:',
+      'Thought: <your reasoning>',
+      'Action: <tool_name>(<args>)',
+      'Observation: <result>',
+      '...repeat until...',
+      'Final Answer: <answer>',
+      tools,
+    ].filter(Boolean).join('\n')},
+    {role:'user', content: question}];
+  },
+
+  selfCritique(originalPrompt, response) {
+    return [{role:'user', content:`Original question: ${originalPrompt}\n\nYour previous answer:\n${response}\n\nCritically review your answer. Identify any errors, gaps, or improvements. Then provide a revised, improved answer.`}];
+  },
+
+  treeOfThought(question, branches=3) {
+    return [{role:'user', content:`Consider ${branches} different approaches to answering:\n\n"${question}"\n\nFor each approach:\n1. Outline the approach\n2. Reason through it\n3. Evaluate its strengths and weaknesses\n\nThen select the best approach and provide a final answer.`}];
+  },
+
+  planAndSolve(question) {
+    return [{role:'user', content:`Let's solve this step by step.\n\nProblem: ${question}\n\nStep 1: Devise a plan with numbered sub-steps.\nStep 2: Execute each sub-step in order.\nStep 3: Verify the final answer.\n\nBegin:`}];
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §16  Sequential chain
+// ─────────────────────────────────────────────────────────────────────────────
+
+class SequentialChain {
+  constructor(client, opts={}) {
+    this._client = client;
+    this._steps  = [];
+    this._opts   = opts;
+  }
+
+  /** Add a step. `step` can be:
+   *  - a string prompt template (uses {input} for previous output)
+   *  - a PromptTemplate instance
+   *  - an async function(previousOutput) => messages[]
+   */
+  step(step, opts={}) { this._steps.push({step, opts}); return this; }
+
+  async run(initialInput, ctx={}) {
+    let current = initialInput;
+    const history = [];
+    for (const {step, opts} of this._steps) {
+      let messages;
+      if (typeof step === 'function') {
+        messages = await step(current, ctx);
+      } else if (step instanceof PromptTemplate) {
+        messages = step.toMessages({ input: current, ...ctx });
+      } else {
+        messages = [{ role:'user', content: String(step).replace(/\{input\}/g, current) }];
+      }
+      const res = await this._client.chat(messages, { ...this._opts, ...opts });
+      history.push({ input: current, output: res.content, response: res });
+      current = res.content;
+    }
+    return { output: current, history };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §17  Parallel chain
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ParallelChain {
+  constructor(client, opts={}) {
+    this._client  = client;
+    this._branches= [];
+    this._opts    = opts;
+  }
+
+  branch(name, messagesOrFn) { this._branches.push({name, fn: messagesOrFn}); return this; }
+
+  async run(input, mergeFn=null) {
+    const results = await Promise.all(this._branches.map(async ({name, fn}) => {
+      const messages = typeof fn==='function' ? await fn(input) : fn;
+      const res = await this._client.chat(messages, this._opts);
+      return { name, response: res, output: res.content };
+    }));
+    const merged = mergeFn ? await mergeFn(results, this._client) : results;
+    return { branches: results, merged };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §18  Tool registry & ReAct agent
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ToolRegistry {
+  constructor() { this._tools = new Map(); }
+
+  /**
+   * Register a tool.
+   * @param {string}   name
+   * @param {string}   description
+   * @param {Function} fn          – sync or async (args) => result
+   * @param {object}   [schema]    – JSON schema for args
+   */
+  register(name, description, fn, schema={}) {
+    this._tools.set(name, { name, description, fn, schema });
+    return this;
+  }
+
+  unregister(name)  { this._tools.delete(name); return this; }
+  has(name)         { return this._tools.has(name); }
+  get(name)         { return this._tools.get(name); }
+  list()            { return [...this._tools.values()].map(t=>({ name:t.name, description:t.description, schema:t.schema })); }
+
+  async call(name, args) {
+    const tool = this._tools.get(name);
+    if (!tool) throw new Error(`Tool not found: ${name}`);
+    return tool.fn(args);
+  }
+
+  /** Convert to OpenAI tool_choice format */
+  toOpenAISchema() {
+    return [...this._tools.values()].map(t=>({
+      type:'function',
+      function:{ name:t.name, description:t.description, parameters: t.schema||{type:'object',properties:{}} },
+    }));
+  }
+}
+
+// Built-in tools
+const _builtinTools = {
+  calculator: {
+    description: 'Evaluate a mathematical expression. Args: { expression: string }',
+    fn: ({expression}) => {
+      // Safe-ish eval: only allow math chars
+      if (!/^[\d+\-*/().\s%^eE,]+$/.test(expression)) return 'Error: invalid expression';
+      try { return String(Function(`"use strict"; return (${expression})`)()) } catch(e) { return 'Error: '+e.message; }
+    },
+  },
+  datetime: {
+    description: 'Get current date/time info. Args: { timezone?: string, format?: "iso"|"human"|"unix" }',
+    fn: ({timezone='UTC', format='iso'}) => {
+      const d = new Date();
+      if(format==='unix')  return String(Math.floor(d.getTime()/1000));
+      if(format==='human') return d.toLocaleString('en-US',{timeZone:timezone});
+      return d.toISOString();
+    },
+  },
+  jsonPath: {
+    description: 'Extract a value from a JSON string using dot notation. Args: { json: string, path: string }',
+    fn: ({json, path}) => {
+      try {
+        const obj = typeof json==='string' ? JSON.parse(json) : json;
+        return String(path.split('.').reduce((o,k)=>o?.[k],obj) ?? 'null');
+      } catch(e) { return 'Error: '+e.message; }
+    },
+  },
+  regex: {
+    description: 'Test or extract regex matches. Args: { text: string, pattern: string, flags?: string, mode?: "test"|"match"|"replace", replacement?: string }',
+    fn: ({text, pattern, flags='g', mode='match', replacement=''}) => {
+      const re = new RegExp(pattern, flags);
+      if(mode==='test')    return String(re.test(text));
+      if(mode==='replace') return text.replace(re, replacement);
+      const m = text.match(re);
+      return m ? JSON.stringify(m) : 'null';
+    },
+  },
+  base64: {
+    description: 'Encode or decode base64. Args: { text: string, mode: "encode"|"decode" }',
+    fn: ({text, mode='encode'}) => {
+      if(mode==='encode') return typeof btoa!=='undefined' ? btoa(text) : Buffer.from(text).toString('base64');
+      return typeof atob!=='undefined' ? atob(text) : Buffer.from(text,'base64').toString('utf8');
+    },
+  },
+  uuid: {
+    description: 'Generate a UUID v4. Args: {}',
+    fn: () => {
+      if(typeof crypto!=='undefined' && crypto.randomUUID) return crypto.randomUUID();
+      return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g,c=>{
+        const r=Math.random()*16|0; return (c==='x'?r:(r&0x3|0x8)).toString(16);
+      });
+    },
+  },
+  hash: {
+    description: 'FNV-1a hash of a string. Args: { text: string }',
+    fn: ({text}) => _md5Hex(text),
+  },
+  webSearch: {
+    description: 'Search the web (stub — returns a placeholder; connect to a real API). Args: { query: string, topK?: number }',
+    fn: ({query, topK=3}) => JSON.stringify({ query, note:'web_search stub — connect to SerpAPI/Brave/Tavily', results:[] }),
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §19  ReAct agent
+// ─────────────────────────────────────────────────────────────────────────────
+
+class ReactAgent {
+  /**
+   * @param {KitAIClient}  client
+   * @param {ToolRegistry} registry
+   * @param {object}       [opts]
+   * @param {number}       [opts.maxSteps]
+   * @param {string}       [opts.model]
+   * @param {boolean}      [opts.verbose]
+   */
+  constructor(client, registry, opts={}) {
+    this._client   = client;
+    this._registry = registry;
+    this._maxSteps = opts.maxSteps || 10;
+    this._model    = opts.model || '';
+    this._verbose  = opts.verbose || false;
+  }
+
+  async run(question) {
+    const messages = scaffolds.react(question, this._registry.list().map(t=>t.name));
+    const trace    = [];
+    let   steps    = 0;
+
+    while (steps++ < this._maxSteps) {
+      const res = await this._client.chat(messages, { model:this._model });
+      const txt = res.content;
+      messages.push({ role:'assistant', content:txt });
+      if(this._verbose) console.log(`[ReAct step ${steps}]\n${txt}`);
+
+      // Parse Final Answer
+      const finalMatch = txt.match(/Final Answer:\s*([\s\S]+)/i);
+      if (finalMatch) return { answer: finalMatch[1].trim(), trace, steps };
+
+      // Parse Action: tool_name(json_or_text)
+      const actionMatch = txt.match(/Action:\s*(\w+)\(([\s\S]*?)\)(?:\n|$)/i);
+      if (actionMatch) {
+        const toolName = actionMatch[1];
+        let   args     = {};
+        try   { args = JSON.parse(actionMatch[2]); } catch { args = { input: actionMatch[2] }; }
+        let observation;
+        try   { observation = await this._registry.call(toolName, args); }
+        catch (e) { observation = `Error: ${e.message}`; }
+        trace.push({ thought:txt, action:toolName, args, observation });
+        messages.push({ role:'user', content:`Observation: ${observation}` });
+      } else {
+        // No action found – treat as final
+        return { answer: txt, trace, steps };
+      }
+    }
+    return { answer:'Max steps reached', trace, steps };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §20  Structured output — schema builder & JSON enforcer
+// ─────────────────────────────────────────────────────────────────────────────
+
+const schema = {
+  string:  (desc='')                   => ({ type:'string',  description:desc }),
+  number:  (desc='')                   => ({ type:'number',  description:desc }),
+  boolean: (desc='')                   => ({ type:'boolean', description:desc }),
+  array:   (items, desc='')            => ({ type:'array',   items, description:desc }),
+  object:  (properties, required=[], desc='') => ({ type:'object', properties, required, description:desc }),
+  enum:    (values, desc='')           => ({ type:'string',  enum:values, description:desc }),
+  nullable:(inner)                     => ({ ...inner, nullable:true }),
+
+  /** Generate a JSON instruction string from a schema object */
+  toInstruction(schemaObj, name='response') {
+    return `Respond ONLY with a valid JSON object matching this schema for "${name}":\n${JSON.stringify(schemaObj, null, 2)}\nNo explanation, no markdown, just the JSON.`;
+  },
+
+  /** Validate a value against a simple schema (subset of JSON Schema) */
+  validate(value, schemaObj) {
+    const errors = [];
+    function check(val, s, path='') {
+      if(s.nullable && (val===null||val===undefined)) return;
+      if(s.type==='string'  && typeof val!=='string')  errors.push(`${path}: expected string, got ${typeof val}`);
+      if(s.type==='number'  && typeof val!=='number')  errors.push(`${path}: expected number, got ${typeof val}`);
+      if(s.type==='boolean' && typeof val!=='boolean') errors.push(`${path}: expected boolean, got ${typeof val}`);
+      if(s.type==='array'){
+        if(!Array.isArray(val)) errors.push(`${path}: expected array`);
+        else val.forEach((item,i)=>check(item,s.items||{},`${path}[${i}]`));
+      }
+      if(s.type==='object'){
+        if(typeof val!=='object'||Array.isArray(val)) errors.push(`${path}: expected object`);
+        else {
+          for(const req of (s.required||[])) if(!(req in val)) errors.push(`${path}.${req}: required`);
+          for(const [k,sub] of Object.entries(s.properties||{})) if(k in val) check(val[k],sub,`${path}.${k}`);
+        }
+      }
+      if(s.enum && !s.enum.includes(val)) errors.push(`${path}: must be one of ${s.enum.join(',')}`);
+    }
+    check(value, schemaObj);
+    return { valid: errors.length===0, errors };
+  },
+};
+
+class JSONEnforcer {
+  /**
+   * @param {KitAIClient} client
+   * @param {object}      schemaObj   – KitAI schema or raw JSON Schema
+   * @param {number}      maxRetries
+   */
+  constructor(client, schemaObj, maxRetries=3) {
+    this._client  = client;
+    this._schema  = schemaObj;
+    this._retries = maxRetries;
+  }
+
+  async run(messages, opts={}) {
+    const systemMsg = { role:'system', content: schema.toInstruction(this._schema) };
+    const msgs = [systemMsg, ...messages];
+    for (let attempt=0; attempt<=this._retries; attempt++) {
+      const res  = await this._client.chat(msgs, { ...opts, jsonMode: true });
+      const json = res.tryJSON();
+      if (json !== null) {
+        const v = schema.validate(json, this._schema);
+        if (v.valid) return { data:json, response:res, attempt };
+        // Feed validation errors back
+        msgs.push({ role:'assistant', content:res.content });
+        msgs.push({ role:'user', content:`Your JSON was invalid:\n${v.errors.join('\n')}\nPlease fix and respond with valid JSON only.` });
+      } else {
+        msgs.push({ role:'assistant', content:res.content });
+        msgs.push({ role:'user', content:'Your response was not valid JSON. Please respond with JSON only.' });
+      }
+    }
+    throw new Error('JSONEnforcer: max retries exceeded');
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §21  Output parsers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const parsers = {
+  /** Parse JSON, stripping markdown fences */
+  json(text) {
+    const clean = text.replace(/^```(?:json)?\n?/,'').replace(/\n?```$/,'').trim();
+    return JSON.parse(clean);
+  },
+
+  /** Parse CSV text → array of row objects */
+  csv(text, delimiter=',') {
+    const lines = text.trim().split('\n');
+    const headers = lines[0].split(delimiter).map(h=>h.trim().replace(/^"|"$/g,''));
+    return lines.slice(1).map(l => {
+      const vals = l.split(delimiter).map(v=>v.trim().replace(/^"|"$/g,''));
+      return Object.fromEntries(headers.map((h,i)=>[h,vals[i]??'']));
+    });
+  },
+
+  /** Parse numbered or bulleted list → string[] */
+  list(text) {
+    return text.split('\n')
+      .map(l=>l.replace(/^[-*•]\s+|^\d+[.)]\s+/,'').trim())
+      .filter(Boolean);
+  },
+
+  /** Parse "Key: Value" lines → object */
+  keyValue(text) {
+    const result = {};
+    for(const line of text.split('\n')){
+      const i=line.indexOf(':');
+      if(i>0) result[line.slice(0,i).trim()] = line.slice(i+1).trim();
+    }
+    return result;
+  },
+
+  /** Parse a markdown table → array of objects */
+  markdownTable(text) {
+    const lines = text.split('\n').filter(l=>l.trim().startsWith('|'));
+    if(lines.length<2) return [];
+    const headers = lines[0].split('|').slice(1,-1).map(h=>h.trim());
+    return lines.slice(2).map(l=>{ // skip separator line
+      const vals = l.split('|').slice(1,-1).map(v=>v.trim());
+      return Object.fromEntries(headers.map((h,i)=>[h,vals[i]||'']));
+    });
+  },
+
+  /** Extract typed fields using an extraction prompt + JSON enforcer */
+  async extract(client, text, fields, model='') {
+    const schemaObj = { type:'object', properties: Object.fromEntries(
+      Object.entries(fields).map(([k,v])=>[k, typeof v==='string'?{type:v}:v])
+    ), required:[] };
+    const msgs=[{role:'user',content:`Extract the following fields from this text:\n\n${text}\n\nFields: ${Object.keys(fields).join(', ')}`}];
+    const enforcer=new JSONEnforcer(client,schemaObj);
+    return enforcer.run(msgs,{model});
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §22  Classification
+// ─────────────────────────────────────────────────────────────────────────────
+
+const classify = {
+  /** Zero-shot classification */
+  async zeroShot(client, text, labels, opts={}) {
+    const labelList = labels.join(' | ');
+    const msgs = [
+      { role:'system', content:`Classify the input into exactly one of these categories: ${labelList}\nRespond with ONLY the category name. No explanation.` },
+      { role:'user',   content: text },
+    ];
+    const res = await client.chat(msgs, opts);
+    const label = res.content.trim();
+    return { label: labels.find(l=>l.toLowerCase()===label.toLowerCase()) || label, raw:res };
+  },
+
+  /** Few-shot classification */
+  async fewShot(client, text, examples, labels, opts={}) {
+    const builder = new FewShotBuilder(`Classify into: ${labels.join(' | ')}`);
+    for(const [input,output] of examples) builder.add(input,output);
+    const msgs = builder.build(text, `Reply with only the label.`);
+    const res  = await client.chat(msgs, opts);
+    return { label: res.content.trim(), raw:res };
+  },
+
+  /** Multi-label classification */
+  async multiLabel(client, text, labels, opts={}) {
+    const msgs = [
+      { role:'system', content:`From the list [${labels.join(', ')}], select ALL that apply to the input. Respond with a JSON array of matching labels only.` },
+      { role:'user',   content: text },
+    ];
+    const res = await client.chat(msgs, opts);
+    try { return { labels: parsers.json(res.content), raw:res }; }
+    catch { return { labels:[], raw:res }; }
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §23  Evaluation & metrics
+// ─────────────────────────────────────────────────────────────────────────────
+
+const metrics = {
+  /** BLEU-1 (unigram precision) */
+  bleu1(reference, hypothesis) {
+    const ref  = reference.toLowerCase().split(/\s+/);
+    const hyp  = hypothesis.toLowerCase().split(/\s+/);
+    const refSet = new Set(ref);
+    const matches = hyp.filter(w=>refSet.has(w)).length;
+    const bp = hyp.length >= ref.length ? 1 : Math.exp(1 - ref.length/hyp.length);
+    return bp * matches / (hyp.length||1);
+  },
+
+  /** ROUGE-L (longest common subsequence F1) */
+  rougeL(reference, hypothesis) {
+    const r=reference.toLowerCase().split(/\s+/), h=hypothesis.toLowerCase().split(/\s+/);
+    const m=r.length, n=h.length;
+    const dp=Array.from({length:m+1},()=>new Array(n+1).fill(0));
+    for(let i=1;i<=m;i++) for(let j=1;j<=n;j++)
+      dp[i][j]=r[i-1]===h[j-1]?dp[i-1][j-1]+1:Math.max(dp[i-1][j],dp[i][j-1]);
+    const lcs=dp[m][n];
+    const p=lcs/(n||1), rec=lcs/(m||1);
+    return p+rec>0 ? 2*p*rec/(p+rec) : 0;
+  },
+
+  /** Exact match */
+  exactMatch(reference, hypothesis) {
+    return reference.trim().toLowerCase()===hypothesis.trim().toLowerCase()?1:0;
+  },
+
+  /** Token-level F1 */
+  tokenF1(reference, hypothesis) {
+    const r=reference.toLowerCase().split(/\s+/), h=hypothesis.toLowerCase().split(/\s+/);
+    const refCount={}, hypCount={};
+    for(const w of r) refCount[w]=(refCount[w]||0)+1;
+    for(const w of h) hypCount[w]=(hypCount[w]||0)+1;
+    let overlap=0;
+    for(const w of Object.keys(hypCount)) overlap+=Math.min(hypCount[w],refCount[w]||0);
+    const p=overlap/(h.length||1), rec=overlap/(r.length||1);
+    return p+rec>0?2*p*rec/(p+rec):0;
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §24  LLM-as-judge
+// ─────────────────────────────────────────────────────────────────────────────
+
+class LLMJudge {
+  constructor(client, opts={}) {
+    this._client  = client;
+    this._model   = opts.model || '';
+    this._criteria= opts.criteria || ['correctness','relevance','coherence','conciseness'];
+    this._scale   = opts.scale || 5;
+  }
+
+  async evaluate(question, response, reference='', extra={}) {
+    const refNote = reference ? `\nReference answer: ${reference}` : '';
+    const critList = this._criteria.map(c=>`- ${c}: score 1-${this._scale}`).join('\n');
+    const msgs = [{role:'user', content:
+      `Evaluate this AI response on a scale of 1-${this._scale} for each criterion.\n\nQuestion: ${question}${refNote}\n\nResponse: ${response}\n\nCriteria:\n${critList}\n\nRespond as JSON: { "scores": { <criterion>: <score> }, "overall": <avg>, "rationale": "<brief>" }\n\nAdditional context: ${JSON.stringify(extra)}`
+    }];
+    const res = await this._client.chat(msgs, { model:this._model, jsonMode:true });
+    const data = res.tryJSON() || { scores:{}, overall:0, rationale:res.content };
+    return { ...data, raw:res };
+  }
+
+  async batch(pairs, reference='') {
+    return Promise.all(pairs.map(([q,r])=>this.evaluate(q,r,reference)));
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §25  Safety guard
+// ─────────────────────────────────────────────────────────────────────────────
+
+const guard = {
+  /** Lightweight offline PII detector (regex-based) */
+  detectPII(text) {
+    const patterns = {
+      email:       /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+      phone:       /(\+?\d[\d\s\-().]{7,}\d)/g,
+      ssn:         /\b\d{3}-\d{2}-\d{4}\b/g,
+      creditCard:  /\b(?:\d[ -]?){13,16}\b/g,
+      ipAddress:   /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
+      dateOfBirth: /\b\d{1,2}[\/\-]\d{1,2}[\/\-]\d{2,4}\b/g,
+    };
+    const found={};
+    for(const [k,re] of Object.entries(patterns)){
+      const m=text.match(re);
+      if(m) found[k]=m;
+    }
+    return { hasPII: Object.keys(found).length>0, detections:found };
+  },
+
+  /** Offline prompt injection heuristic */
+  detectInjection(text) {
+    const patterns = [
+      /ignore\s+(all\s+)?previous\s+instructions/i,
+      /you\s+are\s+now\s+(a\s+)?(?!an?\s+assistant)/i,
+      /disregard\s+your\s+(system|instructions|prompt)/i,
+      /act\s+as\s+(?:an?\s+)?(?:evil|unethical|jailbreak)/i,
+      /\[INST\]|\[\/INST\]|<\|im_start\|>|<\|im_end\|>/,
+      /DAN\s+mode|jailbreak|bypass\s+(?:safety|filter)/i,
+    ];
+    const matches = patterns.filter(p=>p.test(text));
+    return { injectionDetected: matches.length>0, matchCount:matches.length };
+  },
+
+  /** LLM-based toxicity + safety check */
+  async check(client, text, opts={}) {
+    const msgs=[{role:'system',content:systemPrompts.safeguard},{role:'user',content:text}];
+    const res=await client.chat(msgs,{model:opts.model||'',jsonMode:true});
+    const data=res.tryJSON()||{safe:null,categories:[],explanation:res.content};
+    return { ...data, pii:guard.detectPII(text), injection:guard.detectInjection(text), raw:res };
+  },
+
+  /** Hallucination grounding check */
+  async groundingCheck(client, claim, context, opts={}) {
+    const msgs=[{role:'user',content:
+      `Does the following claim appear to be fully supported by the given context?\n\nContext:\n${context}\n\nClaim: ${claim}\n\nRespond as JSON: { "supported": true|false, "confidence": 0.0-1.0, "reasoning": "..." }`
+    }];
+    const res=await client.chat(msgs,{model:opts.model||'',jsonMode:true});
+    return res.tryJSON()||{supported:null,confidence:0,reasoning:res.content};
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §26  Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Strip markdown to plain text */
+function stripMarkdown(text) {
+  return text
+    .replace(/```[\s\S]*?```/g,'')          // code blocks
+    .replace(/`[^`]+`/g,'')                 // inline code
+    .replace(/#{1,6}\s+/g,'')              // headers
+    .replace(/\*\*([^*]+)\*\*/g,'$1')      // bold
+    .replace(/\*([^*]+)\*/g,'$1')          // italic
+    .replace(/~~([^~]+)~~/g,'$1')          // strikethrough
+    .replace(/\[([^\]]+)\]\([^)]+\)/g,'$1')// links
+    .replace(/^>\s+/gm,'')                 // blockquotes
+    .replace(/^[-*+]\s+/gm,'')             // bullets
+    .replace(/^\d+\.\s+/gm,'')             // numbered list
+    .replace(/\n{3,}/g,'\n\n')             // triple newlines
+    .trim();
+}
+
+/** Diff two strings — returns array of { type:'equal'|'insert'|'delete', value:string } */
+function diffText(oldText, newText) {
+  const oldWords = oldText.split(/\s+/);
+  const newWords = newText.split(/\s+/);
+  const ops=[];
+  // Simple LCS diff on word level
+  const m=oldWords.length,n=newWords.length;
+  const dp=Array.from({length:m+1},()=>new Array(n+1).fill(0));
+  for(let i=1;i<=m;i++) for(let j=1;j<=n;j++)
+    dp[i][j]=oldWords[i-1]===newWords[j-1]?dp[i-1][j-1]+1:Math.max(dp[i-1][j],dp[i][j-1]);
+  let i=m,j=n;
+  const result=[];
+  while(i>0||j>0){
+    if(i>0&&j>0&&oldWords[i-1]===newWords[j-1]){result.unshift({type:'equal',value:oldWords[--i]});j--;}
+    else if(j>0&&(i===0||dp[i][j-1]>=dp[i-1][j])){result.unshift({type:'insert',value:newWords[--j]});}
+    else{result.unshift({type:'delete',value:oldWords[--i]});}
+  }
+  return result;
+}
+
+/** Semantic similarity score (requires pre-computed embeddings) */
+function semanticSimilarity(embeddingA, embeddingB) {
+  return _cosineSim(embeddingA, embeddingB);
+}
+
+/** Export a conversation history to various formats */
+const exporter = {
+  toJSON(messages, meta={}) {
+    return JSON.stringify({ meta, messages, exportedAt: new Date().toISOString() }, null, 2);
+  },
+  toMarkdown(messages, title='Conversation') {
+    const lines=[`# ${title}\n`];
+    for(const m of messages) {
+      const role=m.role.charAt(0).toUpperCase()+m.role.slice(1);
+      lines.push(`## ${role}\n${m.content}\n`);
+    }
+    return lines.join('\n');
+  },
+  toHTML(messages, title='Conversation') {
+    const rows = messages.map(m=>{
+      const bg = m.role==='user'?'#f0f4ff':m.role==='system'?'#fff8e1':'#f0fff4';
+      return `<div style="background:${bg};border-radius:8px;padding:12px;margin:8px 0"><strong>${m.role}</strong><p>${m.content.replace(/\n/g,'<br>')}</p></div>`;
+    }).join('');
+    return `<!DOCTYPE html><html><head><title>${title}</title></head><body style="font-family:sans-serif;max-width:800px;margin:auto;padding:20px"><h1>${title}</h1>${rows}</body></html>`;
+  },
+  toText(messages) {
+    return messages.map(m=>`[${m.role.toUpperCase()}]\n${m.content}`).join('\n\n---\n\n');
+  },
+};
+
+/** A/B experiment runner */
+class ABExperiment {
+  /**
+   * @param {KitAIClient[]} clients   – two or more client/model configurations
+   * @param {object}        [opts]
+   */
+  constructor(clients, opts={}) {
+    this._clients = clients;
+    this._opts    = opts;
+    this._results = [];
+  }
+
+  async run(messages, judge=null) {
+    const responses = await Promise.all(
+      this._clients.map(async (c,i) => {
+        const t0  = Date.now();
+        const res = await c.chat(messages, this._opts);
+        res.variant = i;
+        return res;
+      })
+    );
+    let scores = null;
+    if (judge instanceof LLMJudge) {
+      const q = messages.filter(m=>m.role==='user').map(m=>m.content).join(' ');
+      scores  = await Promise.all(responses.map(r=>judge.evaluate(q,r.content)));
+    }
+    const result = { responses, scores, timestamp: Date.now() };
+    this._results.push(result);
+    return result;
+  }
+
+  history() { return this._results; }
+
+  summary() {
+    if(!this._results.length) return null;
+    const totals = this._clients.map((_,i)=>({ variant:i, avgLatency:0, avgScore:0, count:0 }));
+    for(const r of this._results){
+      r.responses.forEach((res,i)=>{
+        totals[i].avgLatency+=res.latencyMs; totals[i].count++;
+        if(r.scores?.[i]) totals[i].avgScore+=r.scores[i].overall||0;
+      });
+    }
+    return totals.map(t=>({
+      variant:t.variant,
+      avgLatency: t.count?Math.round(t.avgLatency/t.count):0,
+      avgScore:   t.count?+(t.avgScore/t.count).toFixed(2):0,
+      runs:t.count,
+    }));
+  }
+}
+
+/** Compress a prompt to fit within a token budget (trim middle) */
+function compressPrompt(text, maxTokens=2000) {
+  const est = tokenizer.estimate(text);
+  if (est <= maxTokens) return text;
+  const ratio = maxTokens / est;
+  const keep  = Math.floor(text.length * ratio * 0.9);
+  const half  = Math.floor(keep/2);
+  return text.slice(0,half) + '\n\n[... content trimmed for context window ...]\n\n' + text.slice(-half);
+}
+
+/** Validate that conversation messages alternate correctly */
+function validateMessages(messages) {
+  const errors=[];
+  for(let i=0;i<messages.length;i++){
+    const m=messages[i];
+    if(!m.role) errors.push(`Message ${i}: missing role`);
+    if(!m.content&&!m.tool_calls) errors.push(`Message ${i}: missing content`);
+    if(i>0&&m.role==='user'&&messages[i-1].role==='user') errors.push(`Message ${i}: consecutive user messages`);
+    if(i>0&&m.role==='assistant'&&messages[i-1].role==='assistant') errors.push(`Message ${i}: consecutive assistant messages`);
+  }
+  return { valid:errors.length===0, errors };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §27  Provider auto-detect from API key prefix
+// ─────────────────────────────────────────────────────────────────────────────
+
+function detectProvider(apiKey='') {
+  if (!apiKey) return 'openai';
+  if (apiKey.startsWith('sk-ant-')) return 'anthropic';
+  if (apiKey.startsWith('AIza'))    return 'gemini';
+  if (apiKey.startsWith('gsk_'))    return 'groq';
+  if (apiKey.startsWith('AZ'))      return 'together';
+  return 'openai';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §28  kitai namespace
+// ─────────────────────────────────────────────────────────────────────────────
+
+const kitai = {
+
+  // ── Meta ────────────────────────────────────────────────────────────────
+  version: '1.0.0',
+
+  // ── Core classes ────────────────────────────────────────────────────────
+  KitAIFormat,
+  KitAIClient,
+  PromptTemplate,
+  FewShotBuilder,
+  VectorStore,
+  RAGPipeline,
+  LRUCache,
+  ToolRegistry,
+  ReactAgent,
+  JSONEnforcer,
+  LLMJudge,
+  ABExperiment,
+  SequentialChain,
+  ParallelChain,
+  SlidingWindowMemory,
+  TokenBudgetMemory,
+  SummaryMemory,
+
+  // ── Sub-namespaces ───────────────────────────────────────────────────────
+  tokenizer,
+  cost,
+  schema,
+  parsers,
+  classify,
+  metrics,
+  guard,
+  chunker,
+  scaffolds,
+  systemPrompts,
+  exporter,
+
+  // ── Utility functions ────────────────────────────────────────────────────
+  stripMarkdown,
+  diffText,
+  semanticSimilarity,
+  compressPrompt,
+  validateMessages,
+  detectProvider,
+
+  // ── Model catalogue ──────────────────────────────────────────────────────
+  models: {
+    all:           () => Object.entries(_MODELS).map(([id,m])=>({id,...m})),
+    byProvider:    (p) => Object.entries(_MODELS).filter(([,m])=>m.provider===p).map(([id,m])=>({id,...m})),
+    byType:        (t) => Object.entries(_MODELS).filter(([,m])=>m.type===t).map(([id,m])=>({id,...m})),
+    byFamily:      (f) => Object.entries(_MODELS).filter(([,m])=>m.family===f).map(([id,m])=>({id,...m})),
+    get:           (id)=> _MODELS[id]||null,
+    contextWindow: (id)=> _MODELS[id]?.context||null,
+    providers:     ()  => [...new Set(Object.values(_MODELS).map(m=>m.provider))],
+    families:      ()  => [...new Set(Object.values(_MODELS).map(m=>m.family))],
+    cheapest:      (type='chat') => cost.cheapest(type),
+    largest:       (type='chat') => Object.entries(_MODELS)
+                      .filter(([,m])=>m.type===type)
+                      .sort((a,b)=>b[1].context-a[1].context)[0]?.[0]||null,
+    register(id, spec) { _MODELS[id]=spec; },
+  },
+
+  // ── Provider registry ────────────────────────────────────────────────────
+  providers: {
+    all:      () => Object.keys(_PROVIDERS),
+    get:      (name) => _PROVIDERS[name]||null,
+    register: (name, spec) => { _PROVIDERS[name]=spec; },
+  },
+
+  // ── Built-in tools ───────────────────────────────────────────────────────
+  builtinTools: _builtinTools,
+
+  /** Create a ToolRegistry pre-loaded with all built-in tools */
+  defaultToolRegistry() {
+    const reg = new ToolRegistry();
+    for(const [name,{description,fn}] of Object.entries(_builtinTools))
+      reg.register(name, description, fn);
+    return reg;
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 1 – Multi-provider client factory
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Create a KitAIClient.
+   * @param {object|string} config  – full config object, or just an apiKey string
+   */
+  client(config={}) {
+    if (typeof config === 'string') config = { apiKey: config };
+    return new KitAIClient(config);
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 3 – Stream aggregator (async iter → full string)
+  // ──────────────────────────────────────────────────────────────────────────
+  async collectStream(asyncIter) {
+    let out='';
+    for await(const chunk of asyncIter) out+=chunk;
+    return out;
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 10 – Quick model info lookup
+  // ──────────────────────────────────────────────────────────────────────────
+  model: (id) => _MODELS[id] || null,
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 11 – Prompt template factory
+  // ──────────────────────────────────────────────────────────────────────────
+  prompt(template, defaults={}) { return new PromptTemplate(template, defaults); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 13 – System prompt helper
+  // ──────────────────────────────────────────────────────────────────────────
+  system(name, vars={}) {
+    let content = typeof systemPrompts[name]==='function' ? systemPrompts[name](vars.content||'') : systemPrompts[name];
+    if (!content) content = name; // allow passing raw content
+    for(const [k,v] of Object.entries(vars)) content=content.replace(`{${k}}`,v);
+    return { role:'system', content };
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 17 – Memory factories
+  // ──────────────────────────────────────────────────────────────────────────
+  memory: {
+    sliding: (maxTurns=10)           => new SlidingWindowMemory(maxTurns),
+    budget:  (budget=3000, model='') => new TokenBudgetMemory(budget, model),
+    summary: (client, trigger=10)    => new SummaryMemory(client, trigger),
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 21 – RAG factory
+  // ──────────────────────────────────────────────────────────────────────────
+  rag(client, opts={}) { return new RAGPipeline(client, new VectorStore(), opts); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 23 – Sequential chain factory
+  // ──────────────────────────────────────────────────────────────────────────
+  chain(client, opts={})    { return new SequentialChain(client, opts); },
+  parallel(client, opts={}) { return new ParallelChain(client, opts); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 26 – ReAct agent factory
+  // ──────────────────────────────────────────────────────────────────────────
+  agent(client, registry=kitai.defaultToolRegistry(), opts={}) {
+    return new ReactAgent(client, registry, opts);
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 29 – JSON enforcer factory
+  // ──────────────────────────────────────────────────────────────────────────
+  enforce(client, schemaObj, maxRetries=3) { return new JSONEnforcer(client, schemaObj, maxRetries); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 34 – LLM judge factory
+  // ──────────────────────────────────────────────────────────────────────────
+  judge(client, opts={}) { return new LLMJudge(client, opts); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 38 – Retry + exponential backoff wrapper
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Wrap any async fn with retry + exponential backoff + optional fallback.
+   * @param {Function}   fn
+   * @param {object}     [opts]
+   * @param {number}     [opts.maxRetries]
+   * @param {number}     [opts.baseDelayMs]
+   * @param {Function[]} [opts.fallbacks]   – list of alternative fns to try after all retries fail
+   */
+  async retry(fn, opts={}) {
+    const { maxRetries=3, baseDelayMs=500, fallbacks=[] } = opts;
+    let lastErr;
+    for(let i=0;i<=maxRetries;i++){
+      try   { return await fn(); }
+      catch (e) {
+        lastErr=e;
+        if(i<maxRetries) await _sleep(Math.min(baseDelayMs*2**i, 30000));
+      }
+    }
+    for(const fallback of fallbacks){
+      try { return await fallback(); } catch(e) { lastErr=e; }
+    }
+    throw lastErr;
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 39 – Token estimation shortcuts
+  // ──────────────────────────────────────────────────────────────────────────
+  estimateTokens(text)         { return tokenizer.estimate(text); },
+  estimateMessages(messages)   { return tokenizer.estimateMessages(messages); },
+  fitsContext(messages, model) { return tokenizer.fitsInContext(messages, model); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 41 – Context window advisor
+  // ──────────────────────────────────────────────────────────────────────────
+  /**
+   * Given text content and desired reserve, recommend the cheapest model
+   * whose context window fits.
+   */
+  adviseBestModel(messages, reserveTokens=1000, type='chat') {
+    const used = tokenizer.estimateMessages(messages);
+    const candidates = Object.entries(_MODELS)
+      .filter(([,m]) => m.type===type && m.context >= used+reserveTokens)
+      .sort((a,b)=>a[1].inputPer1M-b[1].inputPer1M);
+    return candidates.map(([id,m])=>({ id, contextWindow:m.context, usedTokens:used, inputPer1M:m.inputPer1M }));
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 44 – Cache factory
+  // ──────────────────────────────────────────────────────────────────────────
+  cache(maxSize=256) { return new LRUCache(maxSize); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 49 – A/B experiment factory
+  // ──────────────────────────────────────────────────────────────────────────
+  experiment(clients, opts={}) { return new ABExperiment(clients, opts); },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // FEATURE 48 – Semantic similarity (async, needs client for embed)
+  // ──────────────────────────────────────────────────────────────────────────
+  async similarityScore(client, textA, textB, model='text-embedding-3-small') {
+    const [[a],[b]] = await Promise.all([
+      client.embed(textA,{model}),
+      client.embed(textB,{model}),
+    ]);
+    return _cosineSim(a,b);
+  },
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // Convenience: one-shot chat without creating a client first
+  // ──────────────────────────────────────────────────────────────────────────
+  async ask(apiKey, question, opts={}) {
+    const c = kitai.client({ apiKey, ...opts });
+    const res = await c.chat([{role:'user',content:question}], opts);
+    return res;
+  },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// §29  Exports  (same pattern as KitGPS)
+// ─────────────────────────────────────────────────────────────────────────────
+let kitdef = {};
+kitdef                = kitai;
+kitdef.default        = kitai;
+kitdef.KitAIFormat    = KitAIFormat;
+kitdef.KitAIClient    = KitAIClient;
+kitdef.PromptTemplate = PromptTemplate;
+kitdef.FewShotBuilder = FewShotBuilder;
+kitdef.VectorStore    = VectorStore;
+kitdef.RAGPipeline    = RAGPipeline;
+kitdef.ToolRegistry   = ToolRegistry;
+kitdef.ReactAgent     = ReactAgent;
+kitdef.JSONEnforcer   = JSONEnforcer;
+kitdef.LLMJudge       = LLMJudge;
+kitdef.ABExperiment   = ABExperiment;
+kitdef.SequentialChain= SequentialChain;
+kitdef.ParallelChain  = ParallelChain;
+kitdef.SlidingWindowMemory = SlidingWindowMemory;
+kitdef.TokenBudgetMemory   = TokenBudgetMemory;
+kitdef.SummaryMemory       = SummaryMemory;
+kitdef.LRUCache       = LRUCache;
+kitdef.tokenizer      = tokenizer;
+kitdef.cost           = cost;
+kitdef.schema         = schema;
+kitdef.parsers        = parsers;
+kitdef.classify       = classify;
+kitdef.metrics        = metrics;
+kitdef.guard          = guard;
+kitdef.chunker        = chunker;
+kitdef.scaffolds      = scaffolds;
+kitdef.systemPrompts  = systemPrompts;
+kitdef.exporter       = exporter;
+kitdef.stripMarkdown  = stripMarkdown;
+kitdef.diffText       = diffText;
+kitdef.semanticSimilarity = semanticSimilarity;
+kitdef.compressPrompt = compressPrompt;
+kitdef.validateMessages = validateMessages;
+kitdef.detectProvider = detectProvider;
+module.exports = { kitdef };