escribano 0.4.5 → 0.5.0

package/dist/utils/model-detector.js

@@ -3,6 +3,11 @@
  *
  * Detects the best available LLM model from installed Ollama models
  * based on system RAM and model quality tiers.
+ *
+ * MLX Models Note:
+ * Uses lmstudio-community Instruct-2507 models for reliable inference.
+ * These models respect think=False and produce clean output without
+ * thinking leakage, unlike older Qwen3.5 models.
  */
 import { totalmem } from 'node:os';
 export const LLM_MODEL_TIERS = [
@@ -11,6 +16,26 @@ export const LLM_MODEL_TIERS = [
     { model: 'qwen3:8b', tier: 2, minRamGB: 10, label: 'good' },
     { model: 'qwen3:4b', tier: 1, minRamGB: 6, label: 'minimum' },
 ];
+export const MLX_LLM_MODEL_TIERS = [
+    {
+        model: 'lmstudio-community/Qwen3-30B-A3B-Instruct-2507-MLX-8bit',
+        tier: 3,
+        minRamGB: 64,
+        label: 'best',
+    },
+    {
+        model: 'lmstudio-community/Qwen3-30B-A3B-Instruct-2507-MLX-4bit',
+        tier: 2,
+        minRamGB: 32,
+        label: 'good',
+    },
+    {
+        model: 'lmstudio-community/Qwen3-4B-Instruct-2507-MLX-4bit',
+        tier: 1,
+        minRamGB: 8,
+        label: 'minimum',
+    },
+];
 const OLLAMA_ENDPOINT = process.env.OLLAMA_HOST || 'http://localhost:11434';
 /**
  * Fetch installed models from Ollama
@@ -135,6 +160,84 @@ export async function selectBestLLMModel() {
         recommendation: `Install at least ${lowest.model}: ollama pull ${lowest.model}`,
     };
 }
+/**
+ * Select the best MLX LLM model based on system RAM.
+ *
+ * If ESCRIBANO_LLM_MLX_MODEL is set, uses that but still validates and warns.
+ * Otherwise, auto-selects the best available model that fits in RAM.
+ */
+export async function selectBestMLXModel() {
+    const ramGB = getSystemRamGB();
+    const envModel = process.env.ESCRIBANO_LLM_MLX_MODEL;
+    // If env var is set, use it but validate
+    if (envModel) {
+        const tier = MLX_LLM_MODEL_TIERS.find((t) => t.model.toLowerCase() === envModel.toLowerCase());
+        if (!tier) {
+            return {
+                model: envModel,
+                source: 'env',
+                tier: 0,
+                label: 'unknown',
+                ramGB,
+                warning: `${envModel} is not a recognized MLX model.`,
+                recommendation: `Consider using one of: ${MLX_LLM_MODEL_TIERS.map((t) => t.model).join(', ')}`,
+            };
+        }
+        if (tier.minRamGB > ramGB) {
+            const recommended = MLX_LLM_MODEL_TIERS.find((t) => t.minRamGB <= ramGB);
+            return {
+                model: envModel,
+                source: 'env',
+                tier: tier.tier,
+                label: tier.label,
+                ramGB,
+                warning: `${envModel} may be too large for your ${ramGB}GB RAM.`,
+                recommendation: recommended
+                    ? `Consider ${recommended.model} for stability`
+                    : undefined,
+            };
+        }
+        // Check if there's a better model available for this RAM
+        const betterTier = MLX_LLM_MODEL_TIERS.find((t) => t.tier > tier.tier && t.minRamGB <= ramGB);
+        return {
+            model: envModel,
+            source: 'env',
+            tier: tier.tier,
+            label: tier.label,
+            ramGB,
+            recommendation: betterTier
+                ? `${betterTier.model} would give better quality for your ${ramGB}GB RAM`
+                : undefined,
+        };
+    }
+    // Auto-select: find best model that fits in RAM
+    for (const tier of MLX_LLM_MODEL_TIERS) {
+        if (tier.minRamGB > ramGB)
+            continue;
+        // Check if there's a better model NOT selected
+        const betterTier = MLX_LLM_MODEL_TIERS.find((t) => t.tier > tier.tier && t.minRamGB <= ramGB);
+        return {
+            model: tier.model,
+            source: 'auto',
+            tier: tier.tier,
+            label: tier.label,
+            ramGB,
+            recommendation: betterTier
+                ? `For better quality, consider ${betterTier.model} (install via mlx-vlm)`
+                : undefined,
+        };
+    }
+    // Nothing found - return lowest tier
+    const lowest = MLX_LLM_MODEL_TIERS[MLX_LLM_MODEL_TIERS.length - 1];
+    return {
+        model: lowest.model,
+        source: 'auto',
+        tier: 0,
+        label: 'minimum',
+        ramGB,
+        warning: `Selected minimum MLX model for ${ramGB}GB RAM.`,
+    };
+}
 /**
  * Format model selection for console output
  */
@@ -145,10 +248,10 @@ export function formatModelSelection(selection) {
         : '(auto-detected)';
     lines.push(`Using ${selection.model} ${sourceLabel}`);
     if (selection.warning) {
-        lines.push(`  ⚠ ${selection.warning}`);
+        lines.push(`  ! ${selection.warning}`);
     }
     if (selection.recommendation) {
-        lines.push(`  ℹ ${selection.recommendation}`);
+        lines.push(`  i ${selection.recommendation}`);
     }
     return lines.join('\n');
 }

package/migrations/010_llm_backend_metadata.sql

@@ -0,0 +1,25 @@
+-- Migration 010: Add LLM backend tracking to existing runs
+-- 
+-- Marks all existing runs as having used Ollama backend (before MLX-LM migration).
+-- This allows benchmarking comparisons between backends.
+
+-- Update existing runs to set llm_backend in metadata
+-- Since SQLite doesn't have native JSON functions in all versions, we update the metadata text directly
+UPDATE processing_runs 
+SET metadata = CASE 
+  WHEN metadata IS NULL THEN '{"llm_backend":"ollama"}'
+  WHEN metadata LIKE '%"llm_backend"%' THEN metadata  -- Already set, don't override
+  WHEN metadata = '{}' THEN '{"llm_backend":"ollama"}'
+  ELSE REPLACE(metadata, '}', ',"llm_backend":"ollama"}')
+END
+WHERE status IN ('completed', 'failed');
+
+-- For running/other statuses that may be stale, also update them
+UPDATE processing_runs 
+SET metadata = CASE 
+  WHEN metadata IS NULL THEN '{"llm_backend":"ollama"}'
+  WHEN metadata LIKE '%"llm_backend"%' THEN metadata
+  WHEN metadata = '{}' THEN '{"llm_backend":"ollama"}'
+  ELSE REPLACE(metadata, '}', ',"llm_backend":"ollama"}')
+END
+WHERE metadata IS NULL OR metadata NOT LIKE '%"llm_backend"%';

package/migrations/011_llm_debug_log.sql

@@ -0,0 +1,19 @@
+-- Migration 011: LLM Debug Log Table
+-- Stores raw LLM inputs/outputs for debugging thinking leakage
+
+CREATE TABLE IF NOT EXISTS llm_debug_log (
+  id TEXT PRIMARY KEY,
+  recording_id TEXT,
+  artifact_id TEXT,
+  call_type TEXT NOT NULL,        -- 'subject_grouping' | 'artifact_generation'
+  prompt TEXT,                    -- raw user prompt (before apply_chat_template)
+  result TEXT,                    -- final processed response returned to caller
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  
+  -- Everything else as JSON (model, tokens, timing, raw_response diff, etc.)
+  metadata TEXT NOT NULL
+);
+
+CREATE INDEX idx_llm_debug_log_recording ON llm_debug_log(recording_id);
+CREATE INDEX idx_llm_debug_log_call_type ON llm_debug_log(call_type);
+CREATE INDEX idx_llm_debug_log_created ON llm_debug_log(created_at);

package/migrations/012_llm_debug_log_prompt_result.sql

@@ -0,0 +1,20 @@
+-- Migration 012: Rebuild llm_debug_log with prompt/result columns
+-- Drops and recreates the table to add first-class prompt + result columns.
+-- Safe: this table only contains debug data.
+
+DROP TABLE IF EXISTS llm_debug_log;
+
+CREATE TABLE IF NOT EXISTS llm_debug_log (
+  id TEXT PRIMARY KEY,
+  recording_id TEXT,
+  artifact_id TEXT,
+  call_type TEXT NOT NULL,
+  prompt TEXT,
+  result TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  metadata TEXT NOT NULL
+);
+
+CREATE INDEX idx_llm_debug_log_recording ON llm_debug_log(recording_id);
+CREATE INDEX idx_llm_debug_log_call_type ON llm_debug_log(call_type);
+CREATE INDEX idx_llm_debug_log_created ON llm_debug_log(created_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "escribano",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "AI-powered session intelligence tool — turn screen recordings into structured work summaries",
   "main": "dist/index.js",
   "type": "module",