muxmind-ai 2.1.1

package/src/router.js

@@ -0,0 +1,317 @@
+/**
+ * MuxMind AI — Smart Router & Failover Engine
+ *
+ * SMART ROUTING:
+ * - Scores each available (provider, model) pair on: tier/power fit for the
+ *   task, provider priority in the fallback chain, and a live penalty
+ *   accumulated from failures during this request.
+ * - Picks the single best-scoring candidate and uses it for the ENTIRE
+ *   reply. A reply is never split across multiple models mid-answer —
+ *   that was the source of the "answers mixing up" bug in earlier builds:
+ *   the old engine re-ranked and potentially swapped providers on every
+ *   ~48-token fragment, so one answer could be stitched together out of
+ *   several different models' voices/styles/facts.
+ * - Failover to the next-best candidate only happens if the CURRENT
+ *   candidate's request fails outright (network error, 4xx/5xx) before
+ *   producing any output. Once a model has started streaming a reply, we
+ *   stay with it for the rest of that reply.
+ * - "Smart Token Saver" only ever considers vault entries the caller has
+ *   already proven live (status === 'active' client-side, and provider is
+ *   a recognized id server-side) — a candidate is never invented here.
+ * - Hard failures (401/403/404) permanently drop that candidate for the
+ *   rest of the request; soft failures (timeouts, 429, 5xx) apply a
+ *   smaller penalty and can still be retried once other options are
+ *   exhausted.
+ */
+
+'use strict';
+
+const { PROVIDERS, FALLBACK_CHAIN, COMPRESSION_LEVELS, MODEL_HINTS } = require('./config');
+
+function resolveCompression(level) {
+  const keys = Object.keys(COMPRESSION_LEVELS).map(Number).sort((a, b) => a - b);
+  let chosen = keys[0];
+  for (const k of keys) if (level >= k) chosen = k;
+  return COMPRESSION_LEVELS[chosen];
+}
+
+function classifyModel(modelId) {
+  for (const hint of MODEL_HINTS) {
+    if (hint.pattern.test(modelId)) return { tier: hint.tier, power: hint.power };
+  }
+  return { tier: 'balanced', power: 2 };
+}
+
+/**
+ * Rough task-complexity estimate from the live conversation, used to bias
+ * candidate scoring toward a stronger or lighter model tier.
+ */
+function estimateTaskComplexity(messages) {
+  const lastUser = [...messages].reverse().find((m) => m.role === 'user');
+  const text = lastUser?.content || '';
+  const len = text.length;
+  const heavySignals = /\b(code|debug|explain|architecture|analy[sz]e|proof|algorithm|refactor|design|compare)\b/i.test(text);
+  const codeBlock = /```/.test(text);
+
+  if (len > 800 || codeBlock) return 3;
+  if (len > 200 || heavySignals) return 2;
+  return 1;
+}
+
+/**
+ * Score a candidate (provider+model) for the current request.
+ * Higher is better. Combines: tier-match to task, provider priority in
+ * fallback chain, and a live penalty accumulated from failures this run.
+ */
+function scoreCandidate(candidate, taskComplexity, penalties) {
+  const { power } = classifyModel(candidate.model);
+  const tierFit = 3 - Math.abs(power - taskComplexity); // closer match = higher score
+  const chainIndex = FALLBACK_CHAIN.indexOf(candidate.providerId);
+  const chainBonus = chainIndex === -1 ? 0 : (FALLBACK_CHAIN.length - chainIndex) * 0.3;
+  const penalty = penalties.get(`${candidate.providerId}::${candidate.model}`) || 0;
+
+  return tierFit + chainBonus - penalty;
+}
+
+function rankCandidates(vault, taskComplexity, penalties) {
+  return [...vault]
+    .filter((c) => c && c.providerId && c.model && PROVIDERS[c.providerId])
+    .map((c) => ({ ...c, _score: scoreCandidate(c, taskComplexity, penalties) }))
+    .sort((a, b) => b._score - a._score);
+}
+
+function buildRequestPayload(providerId, model, messages, maxTokens, stream) {
+  const cleanMessages = messages
+    .filter((m) => m.role !== 'system')
+    .map((m) => ({ role: m.role, content: m.content }));
+
+  if (providerId === 'anthropic') {
+    return {
+      model,
+      max_tokens: maxTokens,
+      messages: cleanMessages,
+      system: messages.find((m) => m.role === 'system')?.content || undefined,
+      stream: !!stream,
+    };
+  }
+  if (providerId === 'gemini') {
+    return {
+      contents: cleanMessages.map((m) => ({ role: m.role === 'assistant' ? 'model' : 'user', parts: [{ text: m.content }] })),
+      generationConfig: { maxOutputTokens: maxTokens },
+    };
+  }
+  return { model, messages: cleanMessages, max_tokens: maxTokens, stream: !!stream };
+}
+
+function buildUrl(provider, model, apiKey) {
+  let path = provider.chatEndpoint.replace('{model}', model);
+  let url = `${provider.baseUrl}${path}`;
+  if (provider.authQuery) url += `?${provider.authQuery(apiKey)}`;
+  return url;
+}
+
+function extractText(providerId, data) {
+  try {
+    if (providerId === 'anthropic') return (data.content || []).map((b) => b.text || '').join('');
+    if (providerId === 'gemini') return (data.candidates?.[0]?.content?.parts || []).map((p) => p.text || '').join('');
+    return data.choices?.[0]?.message?.content || '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Non-streaming fallback path (used for providers without a simple SSE
+ * shape here, e.g. Gemini). Returns the full text in one shot.
+ */
+async function requestFull({ providerId, apiKey, model, messages, maxTokens }) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) throw new Error(`Unknown provider: ${providerId}`);
+
+  const url = buildUrl(provider, model, apiKey);
+  const headers = { 'Content-Type': 'application/json', ...provider.authHeader(apiKey) };
+  const payload = buildRequestPayload(providerId, model, messages, maxTokens, false);
+
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => res.statusText);
+    const err = new Error(`${provider.label} error (HTTP ${res.status}): ${errText.slice(0, 200)}`);
+    err.httpStatus = res.status;
+    throw err;
+  }
+  const data = await res.json();
+  return extractText(providerId, data);
+}
+
+/**
+ * Streaming path for OpenAI-compatible SSE APIs (OpenAI, Groq, Mistral,
+ * DeepSeek, OpenRouter, xAI, Together, Cerebras, Perplexity) and
+ * Anthropic's own SSE format. Emits text via onDelta as it arrives.
+ */
+async function requestStreaming({ providerId, apiKey, model, messages, maxTokens, onDelta, abortSignal }) {
+  const provider = PROVIDERS[providerId];
+  if (!provider) throw new Error(`Unknown provider: ${providerId}`);
+
+  const url = buildUrl(provider, model, apiKey);
+  const headers = { 'Content-Type': 'application/json', ...provider.authHeader(apiKey) };
+  const payload = buildRequestPayload(providerId, model, messages, maxTokens, true);
+
+  const res = await fetch(url, { method: 'POST', headers, body: JSON.stringify(payload) });
+
+  if (!res.ok) {
+    const errText = await res.text().catch(() => res.statusText);
+    const err = new Error(`${provider.label} error (HTTP ${res.status}): ${errText.slice(0, 200)}`);
+    err.httpStatus = res.status;
+    throw err;
+  }
+  if (!res.body) {
+    // Some environments/providers won't give a readable stream; fall back.
+    const data = await res.json();
+    const text = extractText(providerId, data);
+    if (text) onDelta(text);
+    return;
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let gotAny = false;
+
+  while (true) {
+    if (abortSignal?.aborted) { try { await reader.cancel(); } catch {} break; }
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    const lines = buffer.split('\n');
+    buffer = lines.pop();
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('data:')) continue;
+      const dataStr = trimmed.slice(5).trim();
+      if (dataStr === '[DONE]') continue;
+      let json;
+      try { json = JSON.parse(dataStr); } catch { continue; }
+
+      let delta = '';
+      if (providerId === 'anthropic') {
+        if (json.type === 'content_block_delta' && json.delta?.text) delta = json.delta.text;
+      } else {
+        delta = json.choices?.[0]?.delta?.content || '';
+      }
+      if (delta) { gotAny = true; onDelta(delta); }
+    }
+  }
+
+  if (!gotAny) {
+    // Nothing streamed (e.g. provider ignored `stream:true`) — surface a
+    // soft failure so the caller can fail over instead of returning empty.
+    const err = new Error(`${provider.label} returned no streamed content.`);
+    err.httpStatus = 0;
+    throw err;
+  }
+}
+
+/**
+ * Core smart routing loop: pick the single best candidate for THIS whole
+ * reply, stream it end-to-end, and only fail over to the next-best
+ * candidate if the current one errors before/while producing output.
+ */
+async function staggeredMultiModelStream({
+  vault,
+  messages,
+  compressionLevel = 50,
+  onChunk,
+  onProviderSwitch,
+  abortSignal,
+}) {
+  if (!Array.isArray(vault) || vault.length === 0) {
+    throw new Error('No configured providers available in vault for this request.');
+  }
+
+  const compression = resolveCompression(compressionLevel);
+  // maxTokensFactor scales a base budget — this only affects verbosity of
+  // the *single* chosen model's answer, it does not fragment the reply
+  // across multiple models.
+  const baseBudget = 2048;
+  const maxTokens = Math.max(64, Math.round(baseBudget * (compression.maxTokensFactor ?? 1)));
+  const taskComplexity = estimateTaskComplexity(messages);
+
+  const penalties = new Map();
+  const hardFailCounts = new Map();
+
+  let fullText = '';
+  let attempts = 0;
+  const maxAttempts = Math.min(vault.length + 2, 6);
+
+  while (attempts < maxAttempts) {
+    if (abortSignal?.aborted) break;
+    attempts += 1;
+
+    const ranked = rankCandidates(vault, taskComplexity, penalties)
+      .filter((c) => (hardFailCounts.get(`${c.providerId}::${c.model}`) || 0) < 2);
+
+    if (ranked.length === 0) {
+      if (fullText) break; // we already streamed something usable before the rest died
+      throw new Error('All configured providers failed for this request.');
+    }
+
+    const entry = ranked[0];
+    const key = `${entry.providerId}::${entry.model}`;
+
+    if (onProviderSwitch) onProviderSwitch(entry.providerId, entry.model);
+
+    try {
+      let streamed = '';
+      await requestStreaming({
+        providerId: entry.providerId,
+        apiKey: entry.apiKey,
+        model: entry.model,
+        messages,
+        maxTokens,
+        abortSignal,
+        onDelta: (delta) => {
+          streamed += delta;
+          fullText += delta;
+          if (onChunk) onChunk(delta, { provider: entry.providerId, model: entry.model });
+        },
+      });
+
+      // Success — this one model produced the whole reply. Done.
+      return fullText;
+    } catch (err) {
+      // If we'd already streamed partial text for THIS attempt before it
+      // died, keep that text but stop (don't silently continue writing
+      // with a different model into the same paragraph — surface it as
+      // done so the UI doesn't show a hybrid answer).
+      if (fullText) {
+        return fullText;
+      }
+      if (err.httpStatus === 401 || err.httpStatus === 403 || err.httpStatus === 404) {
+        hardFailCounts.set(key, (hardFailCounts.get(key) || 0) + 1);
+        penalties.set(key, (penalties.get(key) || 0) + 5);
+      } else {
+        penalties.set(key, (penalties.get(key) || 0) + 1.5);
+      }
+      // No output produced yet — safe to fail over to the next candidate
+      // for a clean, single-model attempt at the full reply.
+      continue;
+    }
+  }
+
+  if (!fullText) {
+    throw new Error('All configured providers failed for this request.');
+  }
+  return fullText;
+}
+
+module.exports = {
+  staggeredMultiModelStream,
+  resolveCompression,
+  requestFull,
+  requestStreaming,
+  estimateTaskComplexity,
+  classifyModel,
+};

package/src/tts-engine.js

@@ -0,0 +1,88 @@
+/**
+ * MuxMind AI — Text-To-Speech Controller
+ * Server-side helper for sanitizing/segmenting text before it is sent to
+ * the browser's Web Speech API (SpeechSynthesis) for actual audio output.
+ * Real synthesis happens client-side (index.html/ui-render.js) since that
+ * is zero-cost and requires no API key; this module prepares clean text
+ * chunks and language hints.
+ */
+
+'use strict';
+
+const { TTS_CONFIG } = require('./config');
+
+const ARABIC_RANGE = /[\u0600-\u06FF\u0750-\u077F]/;
+
+/**
+ * Guess whether a string of text is primarily Arabic or English so the
+ * client picks the right SpeechSynthesisVoice/lang.
+ */
+function detectLanguage(text) {
+  if (!text) return 'en';
+  const arabicChars = (text.match(new RegExp(ARABIC_RANGE, 'g')) || []).length;
+  const ratio = arabicChars / Math.max(text.length, 1);
+  return ratio > 0.15 ? 'ar' : 'en';
+}
+
+/**
+ * Strip markdown/code fences and other non-speakable artifacts so TTS
+ * doesn't read out "hashtag hashtag" or raw code syntax.
+ */
+function sanitizeForSpeech(text) {
+  if (!text) return '';
+  return text
+    .replace(/```[\s\S]*?```/g, ' code block omitted ')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/[*_#>~-]{1,3}/g, '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+}
+
+/**
+ * Split long text into speech-friendly sentence chunks so the browser's
+ * speechSynthesis queue doesn't choke on very long utterances.
+ */
+function segmentForSpeech(text, maxLen = 220) {
+  const clean = sanitizeForSpeech(text);
+  const sentences = clean.split(/(?<=[.!?؟۔])\s+/);
+  const segments = [];
+  let current = '';
+
+  for (const sentence of sentences) {
+    if ((current + ' ' + sentence).trim().length > maxLen && current) {
+      segments.push(current.trim());
+      current = sentence;
+    } else {
+      current = (current + ' ' + sentence).trim();
+    }
+  }
+  if (current) segments.push(current.trim());
+  return segments;
+}
+
+/**
+ * Build the full TTS job descriptor the client will consume to drive
+ * window.speechSynthesis.
+ */
+function buildSpeechJob(text, forcedLang = null) {
+  const lang = forcedLang || detectLanguage(text);
+  const langMeta = TTS_CONFIG.languages[lang] || TTS_CONFIG.languages.en;
+  const segments = segmentForSpeech(text);
+
+  return {
+    lang: langMeta.code,
+    langKey: lang,
+    label: langMeta.label,
+    rate: TTS_CONFIG.defaultRate,
+    pitch: TTS_CONFIG.defaultPitch,
+    segments,
+  };
+}
+
+module.exports = {
+  detectLanguage,
+  sanitizeForSpeech,
+  segmentForSpeech,
+  buildSpeechJob,
+};

package/src/ui-render.js

@@ -0,0 +1,91 @@
+/**
+ * MuxMind AI — Dynamic SVG Renderer, Task Tracker & Chat UI helpers
+ * Server-side utilities that prepare structured render instructions.
+ * The actual DOM/SVG painting happens client-side in index.html, but the
+ * shapes/schemas below are shared so client and server agree on format.
+ */
+
+'use strict';
+
+/**
+ * Build a task-tracker state object representing the lifecycle of one
+ * user request as it moves through the router (queued -> streaming ->
+ * provider-switch events -> complete/error).
+ */
+function createTaskTracker(taskId) {
+  return {
+    id: taskId,
+    status: 'queued', // queued | streaming | complete | error | aborted
+    startedAt: Date.now(),
+    completedAt: null,
+    providerTimeline: [], // [{ provider, model, turn, at }]
+    tokensApprox: 0,
+    error: null,
+  };
+}
+
+function recordProviderTurn(tracker, provider, model, turn) {
+  tracker.status = 'streaming';
+  tracker.providerTimeline.push({ provider, model, turn, at: Date.now() });
+  return tracker;
+}
+
+function completeTask(tracker, fullText) {
+  tracker.status = 'complete';
+  tracker.completedAt = Date.now();
+  tracker.tokensApprox = Math.ceil((fullText || '').length / 4);
+  return tracker;
+}
+
+function failTask(tracker, errorMessage) {
+  tracker.status = 'error';
+  tracker.completedAt = Date.now();
+  tracker.error = errorMessage;
+  return tracker;
+}
+
+/**
+ * Compute a rough "savings" percentage for the status badge, comparing
+ * the actual tokens spent against an estimated single-shot baseline.
+ */
+function computeSavingsBadge(tracker, baselineTokensEstimate) {
+  if (!baselineTokensEstimate || baselineTokensEstimate <= 0) return { savingsPct: 0 };
+  const used = tracker.tokensApprox || 0;
+  const savings = Math.max(0, Math.min(99, Math.round((1 - used / baselineTokensEstimate) * 100)));
+  return {
+    savingsPct: savings,
+    used,
+    baseline: baselineTokensEstimate,
+    providersInvolved: [...new Set(tracker.providerTimeline.map((t) => t.provider))],
+  };
+}
+
+/**
+ * Generate a small inline SVG spinner/status icon string used by the
+ * status badge in the toolbar (isolated, no external deps).
+ */
+function renderStatusIconSVG(status) {
+  const colors = {
+    queued: '#8892a0',
+    streaming: '#00f2fe',
+    complete: '#2ee6a6',
+    error: '#ff4d6d',
+    aborted: '#ffb020',
+  };
+  const color = colors[status] || colors.queued;
+  return `<svg viewBox="0 0 24 24" width="14" height="14" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="12" cy="12" r="8" fill="none" stroke="${color}" stroke-width="3"
+    stroke-dasharray="${status === 'streaming' ? '12 6' : '50 0'}">
+    ${status === 'streaming' ? '<animateTransform attributeName="transform" type="rotate" from="0 12 12" to="360 12 12" dur="1s" repeatCount="indefinite"/>' : ''}
+  </circle>
+</svg>`;
+}
+
+module.exports = {
+  createTaskTracker,
+  recordProviderTurn,
+  completeTask,
+  failTask,
+  computeSavingsBadge,
+  renderStatusIconSVG,
+};