escribano 0.1.0

package/dist/batch-context.js

@@ -0,0 +1,329 @@
+/**
+ * Batch Processing Context
+ *
+ * Provides reusable initialization and video processing functions
+ * for batch operations (e.g., quality testing multiple recordings).
+ *
+ * Key Design Decisions:
+ * - Adapters initialized ONCE and reused across recordings
+ * - MLX bridge spawns once, reused for all videos (no socket conflicts)
+ * - Filesystem capture source created per-video (hardcoded to file input)
+ * - Results returned as objects (never throws) for reliable batch processing
+ */
+import { execSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { generateArtifactV3, } from './actions/generate-artifact-v3.js';
+import { updateGlobalIndex } from './actions/outline-index.js';
+import { processRecordingV3 } from './actions/process-recording-v3.js';
+import { hasContentChanged, publishSummaryV3, updateRecordingOutlineMetadata, } from './actions/publish-summary-v3.js';
+import { createSileroPreprocessor } from './adapters/audio.silero.adapter.js';
+import { createFilesystemCaptureSource } from './adapters/capture.filesystem.adapter.js';
+import { cleanupMlxBridge, createMlxIntelligenceService, } from './adapters/intelligence.mlx.adapter.js';
+import { createOllamaIntelligenceService } from './adapters/intelligence.ollama.adapter.js';
+import { createOutlinePublishingService } from './adapters/publishing.outline.adapter.js';
+import { createWhisperTranscriptionService } from './adapters/transcription.whisper.adapter.js';
+import { createFfmpegVideoService } from './adapters/video.ffmpeg.adapter.js';
+import { getDbPath, getRepositories } from './db/index.js';
+import { log, setResourceTracker, step, withPipeline, } from './pipeline/context.js';
+import { ResourceTracker, setupStatsObserver, } from './stats/index.js';
+import { formatModelSelection, selectBestLLMModel, } from './utils/model-detector.js';
+const MODELS_DIR = path.join(homedir(), '.escribano', 'models');
+const MODEL_FILE = 'ggml-large-v3.bin';
+const MODEL_PATH = path.join(MODELS_DIR, MODEL_FILE);
+/**
+ * Initialize system components for batch processing.
+ * All adapters are created ONCE and reused across recordings.
+ */
+export async function initializeSystem() {
+    console.log('Initializing database...');
+    const repos = getRepositories();
+    console.log(`Database ready: ${getDbPath()}`);
+    console.log('');
+    // Setup stats observer to capture pipeline events
+    setupStatsObserver(repos.stats);
+    // Detect best LLM model
+    const modelSelection = await selectBestLLMModel();
+    console.log(formatModelSelection(modelSelection));
+    console.log('');
+    // Initialize adapters ONCE
+    console.log('[VLM] Using MLX-VLM for image processing');
+    const vlm = createMlxIntelligenceService();
+    console.log('[LLM] Using Ollama for text generation');
+    const llm = createOllamaIntelligenceService();
+    const video = createFfmpegVideoService();
+    const preprocessor = createSileroPreprocessor();
+    const transcription = createWhisperTranscriptionService({
+        binaryPath: 'whisper-cli',
+        model: MODEL_PATH,
+        cwd: MODELS_DIR,
+        outputFormat: 'json',
+    });
+    // Setup resource tracking
+    const resourceTracker = new ResourceTracker();
+    resourceTracker.register(vlm);
+    resourceTracker.register(video);
+    resourceTracker.register(preprocessor);
+    // Ollama runs as a daemon - special case
+    resourceTracker.register({
+        getResourceName: () => 'ollama',
+        getPid: () => {
+            try {
+                const output = execSync('pgrep -f "ollama serve"').toString().trim();
+                const pid = parseInt(output.split('\n')[0] ?? '0', 10);
+                return pid > 0 ? pid : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    });
+    setResourceTracker(resourceTracker);
+    const outlineConfig = getOutlineConfig();
+    return {
+        repos,
+        adapters: { vlm, llm, video, preprocessor, transcription },
+        resourceTracker,
+        outlineConfig,
+    };
+}
+/**
+ * Process a single video file.
+ *
+ * Note: Uses FilesystemCaptureSource (hardcoded for file input, not Cap recordings).
+ * The video adapter is from context, but capture source is created per-call.
+ */
+export async function processVideo(videoPath, ctx, options = {}) {
+    const startTime = Date.now();
+    const { force = false, skipSummary = false, micAudioPath, systemAudioPath, format = 'card', includePersonal = false, copyToClipboard = false, printToStdout = false, } = options;
+    const { repos, adapters, outlineConfig } = ctx;
+    const { vlm, llm, video, preprocessor, transcription } = adapters;
+    try {
+        // Create capture source for this specific file
+        // Note: Hardcoded to filesystem source, not Cap recordings
+        const captureSource = createFilesystemCaptureSource({ videoPath, micAudioPath, systemAudioPath }, video);
+        // Get recording metadata
+        const recording = await captureSource.getLatestRecording();
+        if (!recording) {
+            return {
+                success: false,
+                recordingId: '',
+                videoPath,
+                error: `Failed to load video file: ${videoPath}`,
+                duration: (Date.now() - startTime) / 1000,
+            };
+        }
+        console.log(`\nProcessing recording: ${recording.id}`);
+        console.log(`Duration: ${Math.round(recording.duration / 60)} minutes`);
+        // Check/create DB recording
+        const dbRec = repos.recordings.findById(recording.id);
+        if (!dbRec) {
+            repos.recordings.save({
+                id: recording.id,
+                video_path: recording.videoPath,
+                audio_mic_path: recording.audioMicPath,
+                audio_system_path: recording.audioSystemPath,
+                duration: recording.duration,
+                captured_at: recording.capturedAt.toISOString(),
+                status: 'raw',
+                processing_step: null,
+                source_type: recording.source.type,
+                source_metadata: JSON.stringify(recording.source),
+                error_message: null,
+            });
+            console.log('Created database entry');
+        }
+        else if (force) {
+            console.log('Force flag set: clearing existing data');
+            repos.observations.deleteByRecording(recording.id);
+            repos.topicBlocks.deleteByRecording(recording.id);
+            repos.subjects.deleteByRecording(recording.id);
+            repos.recordings.updateStatus(recording.id, 'raw', null, null);
+        }
+        else if (dbRec.status === 'published' || dbRec.status === 'processed') {
+            console.log(`Recording already ${dbRec.status}. Regenerating artifact...`);
+        }
+        // Run VLM pipeline (skip if already processed or published)
+        const skipProcessing = dbRec &&
+            (dbRec.status === 'processed' || dbRec.status === 'published') &&
+            !force;
+        if (!skipProcessing) {
+            const runType = force
+                ? 'force'
+                : dbRec?.processing_step
+                    ? 'resume'
+                    : 'initial';
+            const runMetadata = collectRunMetadata(ctx.resourceTracker);
+            await withPipeline(recording.id, runType, runMetadata, async () => {
+                await processRecordingV3(recording.id, repos, { preprocessor, transcription, video, intelligence: vlm }, { force });
+            });
+        }
+        // Generate artifact and publish (unless skipped), tracked as a pipeline run
+        let artifact = null;
+        let outlineUrl;
+        if (!skipSummary) {
+            const artifactRunMetadata = collectRunMetadata(ctx.resourceTracker);
+            const pipelineResult = await withPipeline(recording.id, 'artifact', artifactRunMetadata, async () => {
+                console.log(`\nGenerating ${format} artifact...`);
+                const generatedArtifact = await generateArtifactV3(recording.id, repos, llm, {
+                    recordingId: recording.id,
+                    format,
+                    includePersonal,
+                    copyToClipboard,
+                    printToStdout,
+                });
+                console.log(`Artifact saved: ${generatedArtifact.filePath}`);
+                if (generatedArtifact.workDuration > 0) {
+                    const workMins = Math.round(generatedArtifact.workDuration / 60);
+                    console.log(`Work time: ${workMins} minutes`);
+                }
+                if (generatedArtifact.personalDuration > 0 && !includePersonal) {
+                    const personalMins = Math.round(generatedArtifact.personalDuration / 60);
+                    console.log(`Personal time: ${personalMins} minutes (filtered)`);
+                }
+                // Publish to Outline (unless no config)
+                let publishedUrl;
+                if (outlineConfig) {
+                    try {
+                        await step('outline publish', async () => {
+                            console.log('\nPublishing to Outline...');
+                            const publishing = createOutlinePublishingService(outlineConfig);
+                            const topicBlocks = repos.topicBlocks.findByRecording(recording.id);
+                            const dbRecording = repos.recordings.findById(recording.id);
+                            if (dbRecording &&
+                                !hasContentChanged(dbRecording, generatedArtifact.content, format)) {
+                                console.log('Content unchanged, skipping publish.');
+                            }
+                            else {
+                                const published = await publishSummaryV3(recording.id, generatedArtifact.content, topicBlocks, repos, publishing, { collectionName: outlineConfig.collectionName, format });
+                                const outlineInfo = {
+                                    url: published.url,
+                                    documentId: published.documentId,
+                                    collectionId: published.collectionId,
+                                    publishedAt: new Date().toISOString(),
+                                    contentHash: published.contentHash,
+                                };
+                                updateRecordingOutlineMetadata(recording.id, outlineInfo, repos, format);
+                                console.log(`Published to Outline: ${published.url}`);
+                                publishedUrl = published.url;
+                            }
+                            // Update status BEFORE rebuilding index so findByStatus('published') includes this recording
+                            repos.recordings.updateStatus(recording.id, 'published', null, null);
+                            log('info', `[Outline] Recording ${recording.id} status updated to 'published'`);
+                            // Update global index (after status update so this recording is included)
+                            if (publishedUrl) {
+                                const indexResult = await updateGlobalIndex(repos, publishing, {
+                                    collectionName: outlineConfig.collectionName,
+                                });
+                                console.log(`Updated index: ${indexResult.url}`);
+                            }
+                        });
+                    }
+                    catch (error) {
+                        const errorMessage = error.message;
+                        console.warn(`Warning: Failed to publish to Outline: ${errorMessage}`);
+                        log('warn', `[Outline] Publishing failed: ${errorMessage}`);
+                        // Store error in metadata
+                        try {
+                            const dbRecording = repos.recordings.findById(recording.id);
+                            const currentMetadata = dbRecording?.source_metadata
+                                ? JSON.parse(dbRecording.source_metadata)
+                                : {};
+                            const existingOutline = currentMetadata.outline || {};
+                            const updatedMetadata = {
+                                ...currentMetadata,
+                                outline: {
+                                    ...existingOutline,
+                                    error: errorMessage,
+                                    failedAt: new Date().toISOString(),
+                                },
+                            };
+                            repos.recordings.updateMetadata(recording.id, JSON.stringify(updatedMetadata));
+                        }
+                        catch (metaError) {
+                            log('error', `[Outline] Failed to store error metadata: ${metaError.message}`);
+                        }
+                    }
+                }
+                else {
+                    console.log('No Outline configuration found. Marking as complete locally.');
+                    repos.recordings.updateStatus(recording.id, 'published', null, null);
+                }
+                return { artifact: generatedArtifact, outlineUrl: publishedUrl };
+            });
+            artifact = pipelineResult.artifact;
+            outlineUrl = pipelineResult.outlineUrl;
+        }
+        console.log('\n✓ Complete!');
+        return {
+            success: true,
+            recordingId: recording.id,
+            videoPath,
+            artifactPath: artifact?.filePath,
+            outlineUrl,
+            duration: (Date.now() - startTime) / 1000,
+            format: artifact?.format,
+            workDuration: artifact?.workDuration,
+            personalDuration: artifact?.personalDuration,
+        };
+    }
+    catch (error) {
+        const errorMessage = error.message;
+        console.error(`\n✗ Failed: ${errorMessage}`);
+        return {
+            success: false,
+            recordingId: '',
+            videoPath,
+            error: errorMessage,
+            duration: (Date.now() - startTime) / 1000,
+        };
+    }
+}
+/**
+ * Get Outline configuration from environment if available.
+ */
+function getOutlineConfig() {
+    const url = process.env.ESCRIBANO_OUTLINE_URL;
+    const token = process.env.ESCRIBANO_OUTLINE_TOKEN;
+    if (!url || !token) {
+        return null;
+    }
+    return {
+        url,
+        token,
+        collectionName: process.env.ESCRIBANO_OUTLINE_COLLECTION ?? 'Escribano Sessions',
+    };
+}
+/**
+ * Collect metadata about the current run.
+ */
+function collectRunMetadata(resourceTracker) {
+    let commitHash = 'unknown';
+    try {
+        commitHash = execSync('git rev-parse --short HEAD', {
+            encoding: 'utf-8',
+        }).trim();
+    }
+    catch {
+        // Not in a git repo
+    }
+    const metadata = {
+        vlm_model: process.env.ESCRIBANO_VLM_MODEL ??
+            'mlx-community/Qwen3-VL-2B-Instruct-bf16',
+        llm_model: process.env.ESCRIBANO_LLM_MODEL ?? 'auto-detected',
+        commit_hash: commitHash,
+        node_version: process.version,
+        platform: process.platform,
+        arch: process.arch,
+        env: {
+            ESCRIBANO_SAMPLE_INTERVAL: process.env.ESCRIBANO_SAMPLE_INTERVAL,
+            ESCRIBANO_VLM_BATCH_SIZE: process.env.ESCRIBANO_VLM_BATCH_SIZE,
+            ESCRIBANO_VERBOSE: process.env.ESCRIBANO_VERBOSE,
+        },
+    };
+    if (resourceTracker) {
+        metadata.system = resourceTracker.getSystemInfo();
+    }
+    return metadata;
+}
+export { cleanupMlxBridge };

package/dist/db/helpers.js

@@ -0,0 +1,50 @@
+/**
+ * Database Helpers
+ *
+ * Utilities for ID generation, embedding conversion, etc.
+ */
+import { uuidv7 } from 'uuidv7';
+/**
+ * Generate a time-sortable unique ID (UUIDv7)
+ */
+export function generateId() {
+    return uuidv7();
+}
+/**
+ * Convert Float32Array embedding to Buffer for SQLite BLOB storage
+ */
+export function embeddingToBlob(embedding) {
+    const float32 = new Float32Array(embedding);
+    return Buffer.from(float32.buffer);
+}
+/**
+ * Convert SQLite BLOB back to number array
+ */
+export function blobToEmbedding(blob) {
+    const float32 = new Float32Array(blob.buffer, blob.byteOffset, blob.length / 4);
+    return Array.from(float32);
+}
+/**
+ * Compute cosine similarity between two embeddings
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Embedding dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dotProduct / denominator;
+}
+/**
+ * Get current ISO8601 timestamp for SQLite
+ */
+export function nowISO() {
+    return new Date().toISOString();
+}

package/dist/db/index.js

@@ -0,0 +1,95 @@
+/**
+ * Database Connection
+ *
+ * Singleton database connection with lazy initialization.
+ * Location: ~/.escribano/escribano.db
+ */
+import { mkdirSync } from 'node:fs';
+import os from 'node:os';
+import { dirname, join } from 'node:path';
+import Database from 'better-sqlite3';
+import { createStatsRepository } from '../stats/repository.js';
+import { runMigrations } from './migrate.js';
+import { createSqliteArtifactRepository, createSqliteClusterRepository, createSqliteContextRepository, createSqliteObservationRepository, createSqliteRecordingRepository, createSqliteSubjectRepository, createSqliteTopicBlockRepository, } from './repositories/index.js';
+const DB_PATH = join(os.homedir(), '.escribano', 'escribano.db');
+let db = null;
+let repositories = null;
+/**
+ * Get database connection (internal)
+ */
+function _getDb() {
+    if (db)
+        return db;
+    // Ensure directory exists
+    mkdirSync(dirname(DB_PATH), { recursive: true });
+    // Open database
+    db = new Database(DB_PATH);
+    // Configure pragmas for performance and safety
+    db.pragma('journal_mode = WAL');
+    db.pragma('synchronous = NORMAL');
+    db.pragma('foreign_keys = ON');
+    db.pragma('busy_timeout = 5000');
+    // Run migrations
+    runMigrations(db);
+    return db;
+}
+/**
+ * Ensure database is initialized
+ */
+export function ensureDb() {
+    _getDb();
+}
+/**
+ * Get all repositories
+ */
+export function getRepositories() {
+    if (repositories)
+        return repositories;
+    const dbInstance = _getDb();
+    repositories = {
+        recordings: createSqliteRecordingRepository(dbInstance),
+        observations: createSqliteObservationRepository(dbInstance),
+        contexts: createSqliteContextRepository(dbInstance),
+        topicBlocks: createSqliteTopicBlockRepository(dbInstance),
+        artifacts: createSqliteArtifactRepository(dbInstance),
+        clusters: createSqliteClusterRepository(dbInstance),
+        subjects: createSqliteSubjectRepository(dbInstance),
+        stats: createStatsRepository(dbInstance),
+    };
+    return repositories;
+}
+/**
+ * Create a fresh set of repositories for testing (using in-memory DB)
+ */
+export function createTestRepositories() {
+    const testDb = new Database(':memory:');
+    testDb.pragma('foreign_keys = ON');
+    runMigrations(testDb);
+    return {
+        recordings: createSqliteRecordingRepository(testDb),
+        observations: createSqliteObservationRepository(testDb),
+        contexts: createSqliteContextRepository(testDb),
+        topicBlocks: createSqliteTopicBlockRepository(testDb),
+        artifacts: createSqliteArtifactRepository(testDb),
+        clusters: createSqliteClusterRepository(testDb),
+        subjects: createSqliteSubjectRepository(testDb),
+        stats: createStatsRepository(testDb),
+        cleanup: () => testDb.close(),
+    };
+}
+/**
+ * Close database connection
+ */
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+        repositories = null;
+    }
+}
+/**
+ * Get database path (useful for tests)
+ */
+export function getDbPath() {
+    return DB_PATH;
+}

package/dist/db/migrate.js

@@ -0,0 +1,80 @@
+/**
+ * Database Migration Runner
+ *
+ * Executes SQL migration files from /migrations directory.
+ * Tracks applied versions in _schema_version table.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const MIGRATIONS_DIR = join(__dirname, '..', '..', 'migrations');
+/**
+ * Get current schema version from database
+ */
+function getCurrentVersion(db) {
+    try {
+        const row = db
+            .prepare('SELECT MAX(version) as version FROM _schema_version')
+            .get();
+        const version = row?.version;
+        return typeof version === 'number' ? version : 0;
+    }
+    catch {
+        // Table doesn't exist yet
+        return 0;
+    }
+}
+/**
+ * Load all migration files from /migrations directory
+ */
+function loadMigrations() {
+    try {
+        const files = readdirSync(MIGRATIONS_DIR)
+            .filter((f) => f.endsWith('.sql'))
+            .sort();
+        return files.map((filename) => {
+            const match = filename.match(/^(\d+)_.+\.sql$/);
+            if (!match) {
+                throw new Error(`Invalid migration filename: ${filename}. Expected format: NNN_description.sql`);
+            }
+            const version = parseInt(match[1], 10);
+            const sql = readFileSync(join(MIGRATIONS_DIR, filename), 'utf-8');
+            return { version, filename, sql };
+        });
+    }
+    catch (error) {
+        console.error(`[db] Failed to load migrations from ${MIGRATIONS_DIR}:`, error);
+        return [];
+    }
+}
+/**
+ * Run all pending migrations
+ */
+export function runMigrations(db) {
+    const currentVersion = getCurrentVersion(db);
+    const migrations = loadMigrations();
+    const pending = migrations.filter((m) => m.version > currentVersion);
+    if (pending.length === 0) {
+        console.log(`[db] Database is up to date (version ${currentVersion})`);
+        return { applied: [], currentVersion };
+    }
+    console.log(`[db] Found ${pending.length} pending migrations. Starting update...`);
+    const applied = [];
+    for (const migration of pending) {
+        console.log(`[db] Applying migration: ${migration.filename}`);
+        // Split migration into individual statements (simple split by ;)
+        // NOTE: This might fail if ; is inside a string, but for simple schemas it's fine.
+        // better-sqlite3 exec() can handle multiple statements.
+        db.exec(migration.sql);
+        // Update schema version
+        db.prepare('INSERT INTO _schema_version (version) VALUES (?)').run(migration.version);
+        applied.push(migration.filename);
+    }
+    const finalVersion = getCurrentVersion(db);
+    if (applied.length > 0) {
+        console.log(`[db] Migrations complete. Schema version: ${finalVersion}`);
+    }
+    return { applied, currentVersion: finalVersion };
+}

package/dist/db/repositories/artifact.sqlite.js

@@ -0,0 +1,77 @@
+/**
+ * Artifact Repository - SQLite Implementation
+ */
+import { nowISO } from '../helpers.js';
+export function createSqliteArtifactRepository(db) {
+    const stmts = {
+        findById: db.prepare('SELECT * FROM artifacts WHERE id = ?'),
+        findByType: db.prepare('SELECT * FROM artifacts WHERE type = ? ORDER BY created_at DESC'),
+        findByBlock: db.prepare(`
+      SELECT * FROM artifacts 
+      WHERE source_block_ids LIKE ?
+      ORDER BY created_at DESC
+    `),
+        findByContext: db.prepare(`
+      SELECT * FROM artifacts 
+      WHERE source_context_ids LIKE ?
+      ORDER BY created_at DESC
+    `),
+        findByRecording: db.prepare(`
+      SELECT * FROM artifacts 
+      WHERE recording_id = ?
+      ORDER BY created_at DESC
+    `),
+        insert: db.prepare(`
+      INSERT INTO artifacts (
+        id, recording_id, type, content, format, source_block_ids, source_context_ids, created_at, updated_at
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `),
+        update: db.prepare(`
+      UPDATE artifacts SET content = ?, updated_at = ? WHERE id = ?
+    `),
+        delete: db.prepare('DELETE FROM artifacts WHERE id = ?'),
+        deleteByRecording: db.prepare('DELETE FROM artifacts WHERE recording_id = ?'),
+        linkSubject: db.prepare('INSERT OR IGNORE INTO artifact_subjects (artifact_id, subject_id) VALUES (?, ?)'),
+        findSubjectsByArtifact: db.prepare('SELECT * FROM artifact_subjects WHERE artifact_id = ?'),
+    };
+    return {
+        findById(id) {
+            const row = stmts.findById.get(id);
+            return row ?? null;
+        },
+        findByType(type) {
+            return stmts.findByType.all(type);
+        },
+        findByBlock(blockId) {
+            return stmts.findByBlock.all(`%${blockId}%`);
+        },
+        findByContext(contextId) {
+            return stmts.findByContext.all(`%${contextId}%`);
+        },
+        findByRecording(recordingId) {
+            return stmts.findByRecording.all(recordingId);
+        },
+        save(artifact) {
+            const now = nowISO();
+            stmts.insert.run(artifact.id, artifact.recording_id ?? null, artifact.type, artifact.content, artifact.format, artifact.source_block_ids, artifact.source_context_ids, now, now);
+        },
+        update(id, content) {
+            stmts.update.run(content, nowISO(), id);
+        },
+        delete(id) {
+            stmts.delete.run(id);
+        },
+        deleteByRecording(recordingId) {
+            stmts.deleteByRecording.run(recordingId);
+        },
+        linkSubjects(artifactId, subjectIds) {
+            for (const subjectId of subjectIds) {
+                stmts.linkSubject.run(artifactId, subjectId);
+            }
+        },
+        findSubjectsByArtifact(artifactId) {
+            return stmts.findSubjectsByArtifact.all(artifactId);
+        },
+    };
+}