escribano 0.1.0

package/dist/domain/segment.js

@@ -0,0 +1,93 @@
+/**
+ * Escribano - Segment Value Object
+ */
+import { TimeRange } from './time-range.js';
+import { Transcript } from './transcript.js';
+// Minimal Context logic previously in context.ts
+const Context = {
+    extractFromOCR: (text) => {
+        // This is a stub to keep V1 compiling.
+        // V2 uses signal-extraction.ts instead.
+        return [];
+    },
+    unique: (contexts) => contexts,
+};
+export const Segment = {
+    /**
+     * Factory: Create segments from visual clusters
+     */
+    fromVisualClusters: (clusters, frames, transcripts) => {
+        if (clusters.length === 0)
+            return [];
+        // Sort clusters chronologically just in case
+        const sortedClusters = [...clusters].sort((a, b) => a.timeRange[0] - b.timeRange[0]);
+        const segments = [];
+        // Group adjacent clusters with the same heuristic label
+        let currentGroup = [sortedClusters[0]];
+        for (let i = 1; i < sortedClusters.length; i++) {
+            const prev = currentGroup[currentGroup.length - 1];
+            const curr = sortedClusters[i];
+            // Primitives for merging:
+            // 1. Same heuristic label
+            // 2. Overlapping or very close in time (< 5s gap)
+            const sameLabel = curr.heuristicLabel === prev.heuristicLabel;
+            const smallGap = curr.timeRange[0] - prev.timeRange[1] < 5;
+            if (sameLabel && smallGap) {
+                currentGroup.push(curr);
+            }
+            else {
+                segments.push(Segment.createFromClusterGroup(currentGroup, frames, transcripts));
+                currentGroup = [curr];
+            }
+        }
+        // Add last group
+        if (currentGroup.length > 0) {
+            segments.push(Segment.createFromClusterGroup(currentGroup, frames, transcripts));
+        }
+        return segments;
+    },
+    /**
+     * Helper: Create a segment from a group of clusters
+     */
+    createFromClusterGroup: (group, frames, transcripts) => {
+        const startTime = Math.min(...group.map((c) => c.timeRange[0]));
+        const endTime = Math.max(...group.map((c) => c.timeRange[1]));
+        const timeRange = [startTime, endTime];
+        const clusterIds = group.map((c) => c.id);
+        // Collect OCR text from all frames belonging to these clusters
+        const segmentFrames = frames.filter((f) => clusterIds.includes(f.clusterId));
+        const allOcrText = segmentFrames.map((f) => f.ocrText).join('\n');
+        // Extract contexts
+        const contexts = Context.unique(Context.extractFromOCR(allOcrText));
+        // Slice transcripts
+        const transcriptSlice = Transcript.sliceTagged(transcripts, timeRange);
+        const segment = {
+            id: `seg-${startTime.toFixed(0)}`,
+            timeRange,
+            visualClusterIds: clusterIds,
+            contexts,
+            transcriptSlice: transcriptSlice.length > 0 ? transcriptSlice[0] : null, // Simplify to primary for now
+            classification: null,
+            isNoise: false, // Will be set by isNoise() check
+        };
+        segment.isNoise = Segment.isNoise(segment);
+        return segment;
+    },
+    duration: (segment) => {
+        return TimeRange.duration(segment.timeRange);
+    },
+    hasAudio: (segment) => {
+        return (segment.transcriptSlice !== null &&
+            !Transcript.isEmpty(segment.transcriptSlice.transcript));
+    },
+    isNoise: (segment) => {
+        // 1. Check contexts for noise apps
+        const noiseApps = ['Spotify', 'YouTube Music'];
+        if (segment.contexts.some((c) => c.type === 'app' && noiseApps.includes(c.value))) {
+            return true;
+        }
+        // 2. Check for "idle" indicator in heuristic label
+        // Note: Python script might label things as "idle" (future)
+        return false;
+    },
+};

package/dist/domain/session.js

@@ -0,0 +1,93 @@
+/**
+ * Escribano - Session Entity Module
+ */
+import { Classification } from './classification.js';
+import { Segment } from './segment.js';
+export const Session = {
+    /**
+     * Factory: Create a new session from a recording
+     */
+    create: (recording) => {
+        const now = new Date();
+        return {
+            id: recording.id,
+            recording,
+            transcripts: [],
+            visualLogs: [],
+            segments: [],
+            status: 'raw',
+            classification: null,
+            metadata: null,
+            artifacts: [],
+            createdAt: now,
+            updatedAt: now,
+        };
+    },
+    /**
+     * Transformation: Add transcripts to session
+     */
+    withTranscripts: (session, transcripts) => ({
+        ...session,
+        transcripts,
+        status: 'transcribed',
+        updatedAt: new Date(),
+    }),
+    /**
+     * Transformation: Add visual index and generate segments
+     */
+    withVisualIndex: (session, visualIndex) => {
+        const segments = Segment.fromVisualClusters(visualIndex.clusters, visualIndex.frames, session.transcripts);
+        return {
+            ...session,
+            segments,
+            status: 'visual-logged',
+            updatedAt: new Date(),
+        };
+    },
+    /**
+     * Query: Get aggregated activity breakdown from segments
+     */
+    getActivityBreakdown: (session) => {
+        if (session.segments.length === 0)
+            return {};
+        const classifications = session.segments
+            .filter((s) => s.classification !== null)
+            .map((s) => ({
+            classification: s.classification,
+            weight: Segment.duration(s),
+        }));
+        if (classifications.length === 0)
+            return {};
+        return Classification.aggregate(classifications);
+    },
+    /**
+     * Query: Get recommended artifacts based on aggregated classification
+     */
+    getRecommendedArtifacts: (session) => {
+        const breakdown = Session.getActivityBreakdown(session);
+        if (!breakdown || Object.keys(breakdown).length === 0)
+            return ['summary'];
+        const recommendations = ['summary'];
+        if ((breakdown.meeting || 0) > 50)
+            recommendations.push('action-items');
+        if ((breakdown.debugging || 0) > 50)
+            recommendations.push('runbook');
+        if ((breakdown.tutorial || 0) > 50)
+            recommendations.push('step-by-step');
+        if ((breakdown.learning || 0) > 50)
+            recommendations.push('notes', 'blog-research');
+        if ((breakdown.working || 0) > 50)
+            recommendations.push('code-snippets');
+        return [...new Set(recommendations)]; // Unique
+    },
+    /**
+     * Query: Get segments needing VLM description
+     */
+    getSegmentsNeedingVLM: (session) => {
+        return session.segments.filter((s) => {
+            // Logic: No audio overlap AND (low OCR density OR specific media indicators)
+            // For now, simple rule: No audio = needs VLM
+            return !Segment.hasAudio(s) && !s.isNoise;
+        });
+    },
+};

package/dist/domain/time-range.js

@@ -0,0 +1,38 @@
+/**
+ * Escribano - TimeRange Value Object
+ */
+import { z } from 'zod';
+export const timeRangeSchema = z.tuple([z.number(), z.number()]);
+export const TimeRange = {
+    create: (start, end) => {
+        if (start < 0 || end < 0) {
+            throw new Error(`Invalid time range: [${start}, ${end}]. Values must be non-negative.`);
+        }
+        if (end < start) {
+            throw new Error(`Invalid time range: [${start}, ${end}]. End must be greater than or equal to start.`);
+        }
+        return [start, end];
+    },
+    duration: (range) => range[1] - range[0],
+    overlaps: (a, b) => {
+        return a[0] < b[1] && b[0] < a[1];
+    },
+    overlapDuration: (a, b) => {
+        if (!TimeRange.overlaps(a, b))
+            return 0;
+        const start = Math.max(a[0], b[0]);
+        const end = Math.min(a[1], b[1]);
+        return end - start;
+    },
+    format: (range) => {
+        const fmt = (s) => {
+            const mins = Math.floor(s / 60);
+            const secs = Math.floor(s % 60);
+            return `${mins}:${secs.toString().padStart(2, '0')}`;
+        };
+        return `${fmt(range[0])} → ${fmt(range[1])}`;
+    },
+    contains: (range, timestamp) => {
+        return timestamp >= range[0] && timestamp <= range[1];
+    },
+};

package/dist/domain/transcript.js

@@ -0,0 +1,79 @@
+/**
+ * Escribano - Transcript Domain Module
+ */
+export const Transcript = {
+    isEmpty: (transcript) => {
+        return !transcript.fullText.trim() || transcript.segments.length === 0;
+    },
+    /**
+     * Slice a transcript by a time range
+     */
+    sliceByTime: (transcript, timeRange) => {
+        const [start, end] = timeRange;
+        const filteredSegments = transcript.segments.filter((seg) => seg.start < end && seg.end > start);
+        if (filteredSegments.length === 0) {
+            return {
+                fullText: '',
+                segments: [],
+                language: transcript.language,
+                duration: 0,
+            };
+        }
+        const fullText = filteredSegments.map((s) => s.text).join(' ');
+        const duration = filteredSegments.length > 0
+            ? Math.max(0, filteredSegments[filteredSegments.length - 1].end -
+                filteredSegments[0].start)
+            : 0;
+        return {
+            fullText,
+            segments: filteredSegments,
+            language: transcript.language,
+            duration,
+        };
+    },
+    /**
+     * Slice tagged transcripts
+     */
+    sliceTagged: (tagged, timeRange) => {
+        return tagged
+            .map((t) => ({
+            source: t.source,
+            transcript: Transcript.sliceByTime(t.transcript, timeRange),
+        }))
+            .filter((t) => !Transcript.isEmpty(t.transcript));
+    },
+    /**
+     * Interleave multiple transcripts by timestamp for better LLM understanding
+     */
+    interleave: (transcripts) => {
+        const formatTime = (seconds) => {
+            const mins = Math.floor(seconds / 60);
+            const secs = Math.floor(seconds % 60);
+            return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+        };
+        // Collect all segments with source tags
+        const allSegments = transcripts.flatMap(({ source, transcript }) => transcript.segments.map((seg) => ({
+            ...seg,
+            source: source.toUpperCase(),
+        })));
+        // Sort by timestamp
+        allSegments.sort((a, b) => a.start - b.start);
+        // Create interleaved transcript
+        const interleavedSegments = allSegments.map((seg, index) => ({
+            id: `seg-${index}`,
+            start: seg.start,
+            end: seg.end,
+            text: `[${formatTime(seg.start)} ${seg.source}] ${seg.text}`,
+            speaker: seg.speaker,
+        }));
+        const fullText = interleavedSegments.map((seg) => seg.text).join('\n');
+        // Use the maximum duration from all transcripts
+        const duration = Math.max(...transcripts.map((t) => t.transcript.duration), 0);
+        return {
+            fullText,
+            segments: interleavedSegments,
+            language: transcripts[0]?.transcript.language || 'en',
+            duration,
+        };
+    },
+};

package/dist/index.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/**
+ * Escribano CLI Entry Point
+ *
+ * Single command: process latest recording and generate summary
+ * Refactored to use batch-context for shared initialization logic
+ */
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { createCapCaptureSource } from './adapters/capture.cap.adapter.js';
+import { createFilesystemCaptureSource } from './adapters/capture.filesystem.adapter.js';
+import { cleanupMlxBridge, initializeSystem, processVideo, } from './batch-context.js';
+import { getDbPath } from './db/index.js';
+import { checkPrerequisites, hasMissingPrerequisites, printDoctorResults, } from './prerequisites.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);
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        showHelp();
+        process.exit(0);
+    }
+    if (args.doctor) {
+        runDoctor().catch((error) => {
+            console.error('Error:', error.message);
+            process.exit(1);
+        });
+        return;
+    }
+    run(args).catch((error) => {
+        console.error('Error:', error.message);
+        console.error(error.stack);
+        process.exit(1);
+    });
+}
+async function runDoctor() {
+    const results = checkPrerequisites();
+    printDoctorResults(results);
+    if (hasMissingPrerequisites(results)) {
+        process.exit(1);
+    }
+}
+function parseArgs(argsArray) {
+    const fileIndex = argsArray.indexOf('--file');
+    const filePath = fileIndex !== -1 ? argsArray[fileIndex + 1] || null : null;
+    const micIndex = argsArray.indexOf('--mic-audio');
+    const micAudio = micIndex !== -1 ? argsArray[micIndex + 1] || null : null;
+    const sysIndex = argsArray.indexOf('--system-audio');
+    const systemAudio = sysIndex !== -1 ? argsArray[sysIndex + 1] || null : null;
+    const formatIndex = argsArray.indexOf('--format');
+    const formatValue = formatIndex !== -1 ? argsArray[formatIndex + 1] : 'card';
+    return {
+        force: argsArray.includes('--force'),
+        help: argsArray.includes('--help') || argsArray.includes('-h'),
+        doctor: argsArray[0] === 'doctor',
+        file: filePath,
+        skipSummary: argsArray.includes('--skip-summary'),
+        micAudio,
+        systemAudio,
+        format: formatValue === 'standup' || formatValue === 'narrative'
+            ? formatValue
+            : 'card',
+        includePersonal: argsArray.includes('--include-personal'),
+        copyToClipboard: argsArray.includes('--copy'),
+        printToStdout: argsArray.includes('--stdout'),
+    };
+}
+function showHelp() {
+    console.log(`
+Escribano - Session Intelligence Tool
+
+Usage:
+  npx escribano                           Process latest Cap recording
+  npx escribano doctor                    Check prerequisites
+  npx escribano --file <path>             Process video from filesystem
+  npx escribano --file <path> --mic-audio <wav>   Use external mic audio
+  npx escribano --file <path> --system-audio <wav>  Provide system audio
+  npx escribano --force                   Reprocess from scratch
+  npx escribano --skip-summary            Process only (no summary generation)
+  npx escribano --format <format>         Artifact format: card (default), standup, narrative
+  npx escribano --include-personal        Include personal time in artifact
+  npx escribano --copy                    Copy artifact to clipboard
+  npx escribano --stdout                  Print artifact to stdout
+  npx escribano --help                    Show this help
+
+Examples:
+  npx escribano --file "~/Desktop/Screen Recording.mov"
+  npx escribano --file "/path/to/video.mp4" --mic-audio "/path/to/mic.wav"
+  npx escribano --file "/path/to/video.mp4" --system-audio "/path/to/system.wav"
+  npx escribano --format standup --stdout
+  npx escribano --format narrative --include-personal
+
+Output: Markdown summary saved to ~/.escribano/artifacts/
+`);
+}
+async function run(args) {
+    const { force, file: filePath, skipSummary, micAudio, systemAudio, format, includePersonal, copyToClipboard, printToStdout, } = args;
+    // Initialize system (reuses batch-context for consistency)
+    console.log('Initializing database...');
+    const ctx = await initializeSystem();
+    const { repos } = ctx;
+    console.log(`Database ready: ${getDbPath()}`);
+    console.log('');
+    // SIGINT handler for graceful cancellation
+    const sigintHandler = () => {
+        console.log('\n⚠️  Run cancelled.');
+        cleanupMlxBridge();
+        process.exit(130);
+    };
+    process.on('SIGINT', sigintHandler);
+    // Create appropriate capture source
+    let captureSource;
+    if (filePath) {
+        console.log(`Using filesystem source: ${filePath}`);
+        if (micAudio)
+            console.log(`  Mic audio: ${micAudio}`);
+        if (systemAudio)
+            console.log(`  System audio: ${systemAudio}`);
+        captureSource = createFilesystemCaptureSource({
+            videoPath: filePath,
+            micAudioPath: micAudio ?? undefined,
+            systemAudioPath: systemAudio ?? undefined,
+        }, ctx.adapters.video);
+    }
+    else {
+        console.log('Using Cap recordings source');
+        captureSource = createCapCaptureSource({}, ctx.adapters.video);
+    }
+    // Get recording
+    const recording = await captureSource.getLatestRecording();
+    if (!recording) {
+        if (filePath) {
+            console.log(`Failed to load video file: ${filePath}`);
+        }
+        else {
+            console.log('No Cap recordings found.');
+        }
+        cleanupMlxBridge();
+        return;
+    }
+    console.log(`Processing: ${recording.id}`);
+    console.log(`Duration: ${Math.round(recording.duration / 60)} minutes`);
+    console.log('');
+    // Use shared processVideo function
+    if (!recording.videoPath) {
+        console.error('Recording has no video path');
+        cleanupMlxBridge();
+        process.exit(1);
+    }
+    const result = await processVideo(recording.videoPath, ctx, {
+        force,
+        skipSummary,
+        micAudioPath: micAudio ?? undefined,
+        systemAudioPath: systemAudio ?? undefined,
+        format,
+        includePersonal,
+        copyToClipboard,
+        printToStdout,
+    });
+    // Cleanup
+    cleanupMlxBridge();
+    // Exit with appropriate code
+    if (!result.success) {
+        console.error(`\nProcessing failed: ${result.error}`);
+        process.exit(1);
+    }
+    console.log('\n✓ All done!');
+    if (result.outlineUrl) {
+        console.log(`Outline: ${result.outlineUrl}`);
+    }
+}
+main();

package/dist/pipeline/context.js

@@ -0,0 +1,162 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { performance } from 'node:perf_hooks';
+import { generateId } from '../db/helpers.js';
+import { pipelineEvents } from './events.js';
+const storage = new AsyncLocalStorage();
+let resourceTracker = null;
+export function setResourceTracker(tracker) {
+    resourceTracker = tracker;
+}
+export function getResourceTracker() {
+    return resourceTracker;
+}
+export function withPipeline(recordingId, runType, metadata, fn) {
+    const verbose = process.env.ESCRIBANO_VERBOSE === 'true';
+    const runId = generateId();
+    const startTime = performance.now();
+    const state = {
+        recordingId,
+        runId,
+        runType,
+        steps: [],
+        verbose,
+        startTime,
+    };
+    console.log(`\n🚀 Pipeline: [${recordingId}] (${runType})`);
+    pipelineEvents.emit('run:start', {
+        runId,
+        recordingId,
+        runType,
+        timestamp: Date.now(),
+        metadata,
+    });
+    return storage.run(state, async () => {
+        try {
+            const result = await fn();
+            const durationMs = performance.now() - startTime;
+            pipelineEvents.emit('run:end', {
+                runId,
+                status: 'completed',
+                timestamp: Date.now(),
+                durationMs,
+            });
+            printSummary(state);
+            return result;
+        }
+        catch (error) {
+            const durationMs = performance.now() - startTime;
+            const errorMessage = error.message;
+            pipelineEvents.emit('run:end', {
+                runId,
+                status: 'failed',
+                timestamp: Date.now(),
+                durationMs,
+                error: errorMessage,
+            });
+            printSummary(state);
+            throw error;
+        }
+    });
+}
+export async function step(name, fn, options) {
+    const state = storage.getStore();
+    if (!state)
+        return fn();
+    const phaseId = generateId();
+    const start = performance.now();
+    if (state.verbose) {
+        console.log(`  ▶ ${name}`);
+    }
+    pipelineEvents.emit('phase:start', {
+        runId: state.runId,
+        phaseId,
+        phase: name,
+        timestamp: Date.now(),
+        itemsTotal: options?.itemsTotal,
+    });
+    // Start resource tracking for this phase
+    await resourceTracker?.start();
+    try {
+        const result = await fn();
+        const durationMs = performance.now() - start;
+        state.steps.push({ name, durationMs, status: 'success' });
+        let itemsProcessed = result?.itemsProcessed;
+        if (itemsProcessed === undefined && Array.isArray(result)) {
+            itemsProcessed = result.length;
+        }
+        // Stop resource tracking and get stats
+        const resourceStats = resourceTracker?.stop();
+        pipelineEvents.emit('phase:end', {
+            runId: state.runId,
+            phaseId,
+            status: 'success',
+            timestamp: Date.now(),
+            durationMs,
+            itemsProcessed,
+            metadata: resourceStats ? { resources: resourceStats } : undefined,
+        });
+        const itemsInfo = options?.itemsTotal
+            ? ` (${itemsProcessed ?? options.itemsTotal}/${options.itemsTotal})`
+            : itemsProcessed
+                ? ` (${itemsProcessed})`
+                : '';
+        if (!state.verbose) {
+            console.log(`  ✅ ${name.padEnd(30, '.')} ${(durationMs / 1000).toFixed(1)}s${itemsInfo}`);
+        }
+        else {
+            console.log(`  ✅ ${name} completed in ${(durationMs / 1000).toFixed(1)}s${itemsInfo}`);
+        }
+        return result;
+    }
+    catch (error) {
+        const durationMs = performance.now() - start;
+        const errorMessage = error.message;
+        state.steps.push({
+            name,
+            durationMs,
+            status: 'error',
+            error: errorMessage,
+        });
+        // Stop resource tracking and get stats (even on error)
+        const resourceStats = resourceTracker?.stop();
+        pipelineEvents.emit('phase:end', {
+            runId: state.runId,
+            phaseId,
+            status: 'failed',
+            timestamp: Date.now(),
+            durationMs,
+            metadata: resourceStats ? { resources: resourceStats } : undefined,
+        });
+        console.error(`  ❌ ${name} failed after ${(durationMs / 1000).toFixed(1)}s: ${errorMessage}`);
+        throw error;
+    }
+}
+export function log(level, message) {
+    const state = storage.getStore();
+    if (!state) {
+        if (level === 'error')
+            console.error(message);
+        else if (level === 'warn')
+            console.warn(message);
+        else
+            console.log(message);
+        return;
+    }
+    if (level === 'debug' && !state.verbose)
+        return;
+    const prefix = level === 'info' ? '    ' : `    [${level}] `;
+    console.log(`${prefix}${message}`);
+}
+function printSummary(state) {
+    const totalDuration = (performance.now() - state.startTime) / 1000;
+    console.log('─'.repeat(50));
+    console.log(`🏁 Pipeline Finished: [${state.recordingId}]`);
+    console.log(`📊 Total Duration: ${totalDuration.toFixed(1)}s`);
+    console.log('─'.repeat(50));
+}
+export function getCurrentPipeline() {
+    return storage.getStore();
+}
+export function getCurrentRunId() {
+    return storage.getStore()?.runId;
+}

package/dist/pipeline/events.js

@@ -0,0 +1,2 @@
+import { EventEmitter } from 'node:events';
+export const pipelineEvents = new EventEmitter();