escribano 0.1.0

package/dist/adapters/capture.cap.adapter.js

@@ -0,0 +1,107 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { capConfigSchema } from '../0_types.js';
+import { normalizeSessionId } from '../utils/id-normalization.js';
+function expandPath(path) {
+    if (path.startsWith('~/')) {
+        return join(homedir(), path.slice(2));
+    }
+    return path;
+}
+async function parseCapRecording(capDirPath, videoService) {
+    try {
+        const metaPath = join(capDirPath, 'recording-meta.json');
+        const metaContent = await readFile(metaPath, 'utf-8');
+        const meta = JSON.parse(metaContent);
+        if (!meta.segments ||
+            !Array.isArray(meta.segments) ||
+            meta.segments.length === 0) {
+            throw new Error(`Invalid metadata in ${capDirPath}: missing or empty segments array`);
+        }
+        const firstSegment = meta.segments[0];
+        const videoPath = firstSegment.display?.path
+            ? join(capDirPath, firstSegment.display.path)
+            : null;
+        // we fked up cuz we have mic but also system_audio.ogg
+        const micAudio = firstSegment.mic?.path
+            ? join(capDirPath, firstSegment.mic.path)
+            : null;
+        const systemAudio = firstSegment.system_audio?.path
+            ? join(capDirPath, firstSegment.system_audio.path)
+            : null;
+        const audioToStat = micAudio || systemAudio;
+        if (!audioToStat) {
+            console.log(`Skipping ${capDirPath}: none audio track found`);
+            return null;
+        }
+        const stats = await stat(audioToStat);
+        const capturedAt = stats.mtime;
+        // Calculate duration from video if available
+        let duration = 0;
+        if (videoPath) {
+            try {
+                const metadata = await videoService.getMetadata(videoPath);
+                duration = metadata.duration;
+            }
+            catch (e) {
+                console.warn(`Failed to get video duration for ${capDirPath}: ${e.message}`);
+            }
+        }
+        const rawId = capDirPath.split('/').pop() || 'unknown';
+        const recordingId = normalizeSessionId(rawId);
+        return {
+            id: recordingId,
+            source: {
+                type: 'cap',
+                originalPath: capDirPath,
+                metadata: meta,
+            },
+            videoPath,
+            audioMicPath: micAudio ? micAudio : null,
+            audioSystemPath: systemAudio ? systemAudio : null,
+            duration,
+            capturedAt,
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Recording directory or files not found: ${capDirPath}`);
+        }
+        if (error.name === 'SyntaxError') {
+            throw new Error(`Invalid JSON in recording-meta.json at ${capDirPath}`);
+        }
+        throw new Error(`Failed to parse recording at ${capDirPath}: ${error.message}`);
+    }
+}
+export function createCapCaptureSource(config = {}, videoService) {
+    const parsedConfig = capConfigSchema.parse(config);
+    const recordingsPath = expandPath(parsedConfig.recordingsPath);
+    const innerList = async (limit = 10) => {
+        try {
+            //
+            // 7 directories, 5 files
+            const entries = await readdir(recordingsPath, { withFileTypes: true });
+            const capDirs = entries.filter((entry) => entry.isDirectory() && entry.name.endsWith('.cap'));
+            const recordings = await Promise.allSettled(capDirs.map(async (dir) => parseCapRecording(join(recordingsPath, dir.name), videoService)));
+            // logging errors
+            console.log(recordings
+                .filter((p) => p.status === 'rejected')
+                .map((p) => `${p.reason}\n`));
+            return recordings
+                .filter((p) => p.status === 'fulfilled')
+                .map((x) => x.value)
+                .filter((r) => r !== null)
+                .sort((a, b) => b.capturedAt.getTime() - a.capturedAt.getTime())
+                .slice(0, limit);
+        }
+        catch (error) {
+            console.error('Failed to list Cap recordings:', error);
+            return [];
+        }
+    };
+    return {
+        getLatestRecording: () => innerList(1).then((recordings) => recordings[0] ?? null),
+        listRecordings: innerList,
+    };
+}

package/dist/adapters/capture.filesystem.adapter.js

@@ -0,0 +1,124 @@
+/**
+ * Filesystem Capture Adapter
+ *
+ * Allows processing arbitrary video files from the filesystem.
+ * Useful for QuickTime screen recordings, downloaded videos, etc.
+ */
+import { exec } from 'node:child_process';
+import { mkdir, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execAsync = promisify(exec);
+function expandPath(inputPath) {
+    if (inputPath.startsWith('~/')) {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        return path.join(homeDir, inputPath.slice(2));
+    }
+    return inputPath;
+}
+function sanitizeFilenameToId(filename) {
+    // Remove extension
+    const baseName = filename.replace(/\.[^/.]+$/, '');
+    // Replace spaces and special chars with hyphens, keep only alphanumeric and hyphens
+    return baseName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .substring(0, 100);
+}
+async function checkHasAudio(videoPath) {
+    const command = `ffprobe -v error -select_streams a -show_entries stream=codec_type -of csv=p=0 "${videoPath}"`;
+    const { stdout } = await execAsync(command);
+    return stdout.trim().length > 0;
+}
+async function extractAudio(videoPath, outputPath) {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    const command = `ffmpeg -i "${videoPath}" -vn -acodec pcm_s16le -ar 16000 "${outputPath}" -y`;
+    await execAsync(command);
+}
+async function parseFilesystemRecording(videoPath, videoService, audioOverrides) {
+    try {
+        const stats = await stat(videoPath);
+        const capturedAt = stats.mtime;
+        // Get video metadata (duration, dimensions)
+        const metadata = await videoService.getMetadata(videoPath);
+        // Generate recording ID from filename
+        const fileName = path.basename(videoPath);
+        const recordingId = sanitizeFilenameToId(fileName);
+        // Audio handling - check for overrides first
+        let audioMicPath = null;
+        let audioSystemPath = null;
+        if (audioOverrides?.micAudioPath) {
+            audioMicPath = expandPath(audioOverrides.micAudioPath);
+        }
+        else {
+            const hasAudio = await checkHasAudio(videoPath);
+            if (hasAudio) {
+                const tempAudioPath = path.join(os.tmpdir(), 'escribano', recordingId, 'audio.wav');
+                await extractAudio(videoPath, tempAudioPath);
+                audioMicPath = tempAudioPath;
+            }
+        }
+        if (audioOverrides?.systemAudioPath) {
+            audioSystemPath = expandPath(audioOverrides.systemAudioPath);
+        }
+        return {
+            id: recordingId,
+            source: {
+                type: 'raw',
+                originalPath: videoPath,
+                metadata: {
+                    filename: fileName,
+                    size: stats.size,
+                    duration: metadata.duration,
+                    width: metadata.width,
+                    height: metadata.height,
+                },
+            },
+            videoPath: videoPath,
+            audioMicPath: audioMicPath,
+            audioSystemPath: audioSystemPath,
+            duration: metadata.duration,
+            capturedAt,
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`Video file not found: ${videoPath}`);
+        }
+        throw new Error(`Failed to parse video at ${videoPath}: ${error.message}`);
+    }
+}
+/**
+ * Creates a CaptureSource that reads a single video file from the filesystem.
+ *
+ * @param config - Configuration with video file path
+ * @param videoService - Video service for metadata extraction
+ * @returns CaptureSource that treats the file as the "latest" recording
+ */
+export function createFilesystemCaptureSource(config, videoService) {
+    const resolvedPath = expandPath(config.videoPath);
+    return {
+        getLatestRecording: async () => {
+            try {
+                const recording = await parseFilesystemRecording(resolvedPath, videoService, {
+                    micAudioPath: config.micAudioPath,
+                    systemAudioPath: config.systemAudioPath,
+                });
+                return recording;
+            }
+            catch (error) {
+                console.error('Failed to load filesystem recording:', error);
+                return null;
+            }
+        },
+        listRecordings: async (_limit = 1) => {
+            const recording = await parseFilesystemRecording(resolvedPath, videoService, {
+                micAudioPath: config.micAudioPath,
+                systemAudioPath: config.systemAudioPath,
+            });
+            return recording ? [recording] : [];
+        },
+    };
+}

package/dist/adapters/embedding.ollama.adapter.js

@@ -0,0 +1,141 @@
+/**
+ * Escribano - Embedding Adapter (Ollama)
+ *
+ * Simplified atomic worker for Ollama REST /api/embed API.
+ * Batching and parallelism are handled by the pipeline, not here.
+ */
+const MIN_TEXT_LENGTH = 5;
+const DEFAULT_TIMEOUT_MS = 600_000; // 10 minutes
+const MAX_RETRIES = 3;
+export function createOllamaEmbeddingService(config) {
+    const baseUrl = config.endpoint.replace('/api/chat', '');
+    const model = process.env.ESCRIBANO_EMBED_MODEL ||
+        config.embedding?.model ||
+        'qwen3-embedding:8b';
+    /**
+     * Call Ollama /api/embed endpoint with retry logic
+     */
+    async function callEmbedAPI(texts, externalSignal) {
+        let lastError = null;
+        for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+            // Link external signal if provided
+            if (externalSignal) {
+                externalSignal.addEventListener('abort', () => controller.abort());
+            }
+            try {
+                const response = await fetch(`${baseUrl}/api/embed`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model,
+                        input: texts,
+                        truncate: true,
+                        options: {
+                            num_ctx: 40000,
+                        },
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    throw new Error(`Ollama embed error: ${response.status} ${response.statusText} - ${errorText.substring(0, 200)}`);
+                }
+                const data = await response.json();
+                return data.embeddings;
+            }
+            catch (error) {
+                lastError = error;
+                const isRetryable = lastError.message.includes('abort') ||
+                    lastError.message.includes('500') ||
+                    lastError.message.includes('ECONNRESET');
+                if (isRetryable && attempt < MAX_RETRIES) {
+                    const delay = 2 ** attempt * 1000; // Exponential backoff
+                    console.warn(`[Embedding] Attempt ${attempt}/${MAX_RETRIES} failed, retrying in ${delay / 1000}s...`);
+                    await new Promise((r) => setTimeout(r, delay));
+                }
+                else {
+                    // If not retryable or max retries reached, don't just continue the loop
+                    break;
+                }
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        throw lastError || new Error('Embedding failed after retries');
+    }
+    return {
+        embed: async (text, taskType) => {
+            if (!text || text.trim().length < MIN_TEXT_LENGTH) {
+                return [];
+            }
+            const prefix = taskType === 'clustering'
+                ? 'Instruct: Cluster screen recording observations for semantic similarity\n'
+                : '';
+            const results = await callEmbedAPI([prefix + text]);
+            return results[0] || [];
+        },
+        embedBatch: async (texts, taskType, options) => {
+            const prefix = taskType === 'clustering'
+                ? 'Instruct: Cluster screen recording observations for semantic similarity\n'
+                : '';
+            // Filter valid texts and track indices
+            const validItems = [];
+            for (let i = 0; i < texts.length; i++) {
+                if (texts[i] && texts[i].trim().length >= MIN_TEXT_LENGTH) {
+                    validItems.push({ index: i, text: prefix + texts[i] });
+                }
+            }
+            if (validItems.length === 0) {
+                return new Array(texts.length).fill([]);
+            }
+            // Single API call for this batch
+            const textsToEmbed = validItems.map((v) => v.text);
+            const embeddings = await callEmbedAPI(textsToEmbed, options?.signal);
+            // Reconstruct full array in original order
+            const finalEmbeddings = new Array(texts.length).fill([]);
+            for (let i = 0; i < validItems.length; i++) {
+                finalEmbeddings[validItems[i].index] = embeddings[i] || [];
+            }
+            return finalEmbeddings;
+        },
+        similarity: (a, b) => {
+            if (a.length === 0 || b.length === 0)
+                return 0;
+            if (a.length !== b.length) {
+                throw new Error(`Embedding dimensions 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];
+            }
+            if (normA === 0 || normB === 0)
+                return 0;
+            return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+        },
+        centroid: (embeddings) => {
+            const valid = embeddings.filter((e) => e.length > 0);
+            if (valid.length === 0)
+                return [];
+            if (valid.length === 1)
+                return valid[0];
+            const dim = valid[0].length;
+            const result = new Array(dim).fill(0);
+            for (const emb of valid) {
+                for (let i = 0; i < dim; i++) {
+                    result[i] += emb[i];
+                }
+            }
+            for (let i = 0; i < dim; i++) {
+                result[i] /= valid.length;
+            }
+            return result;
+        },
+    };
+}

package/dist/adapters/intelligence.adapter.js

@@ -0,0 +1,202 @@
+/**
+ * Escribano - Intelligence Adapter (Ollama)
+ *
+ * Implements IntelligenceService using Ollama REST API
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export function createIntelligenceService(config) {
+    return {
+        classify: (transcript) => classifyWithOllama(transcript, config),
+        extractMetadata: (transcript, classification) => extractMetadata(transcript, classification, config),
+        generate: (artifactType, context) => generateArtifact(artifactType, context, config),
+    };
+}
+async function checkOllamaHealth() {
+    try {
+        const response = await fetch('http://localhost:11434/api/tags');
+        if (!response.ok) {
+            throw new Error('Ollama API not accessible');
+        }
+        const data = await response.json();
+        console.log('✓ Ollama is running and accessible');
+        console.log(`  Available models: ${data.models?.length || 0}`);
+    }
+    catch (error) {
+        console.error('✗ Ollama is not running or not accessible');
+        console.error('  Error:', error.message);
+        console.error('');
+        console.error('Please start Ollama:');
+        console.error('  brew install ollama');
+        console.error('  ollama pull qwen3:32b');
+        console.error('  ollama serve');
+        console.error('');
+        throw new Error('Ollama service required for classification');
+    }
+}
+async function classifyWithOllama(transcript, config) {
+    console.log('Classifying transcript with Ollama...');
+    const tick = setInterval(() => {
+        process.stdout.write('.');
+    }, 1000);
+    await checkOllamaHealth();
+    const prompt = loadClassifyPrompt(transcript);
+    const raw = await callOllama(prompt, config, { expectJson: true });
+    clearInterval(tick);
+    console.log('\nClassification completed.');
+    const classification = {
+        meeting: raw.meeting * (raw.meeting <= 1 ? 100 : 1) || 0,
+        debugging: raw.debugging * (raw.debugging <= 1 ? 100 : 1) || 0,
+        tutorial: raw.tutorial * (raw.tutorial <= 1 ? 100 : 1) || 0,
+        learning: raw.learning * (raw.learning <= 1 ? 100 : 1) || 0,
+        working: raw.working * (raw.working <= 1 ? 100 : 1) || 0,
+    };
+    return classification;
+}
+function loadClassifyPrompt(transcript) {
+    const promptPath = join(process.cwd(), 'prompts', 'classify.md');
+    let prompt = readFileSync(promptPath, 'utf-8');
+    const segmentsText = transcript.segments
+        .map((seg) => `[seg-${seg.id}] [${seg.start}s - ${seg.end}s] ${seg.text}`)
+        .join('\n');
+    prompt = prompt.replace('{{TRANSCRIPT_ALL}}', transcript.fullText);
+    prompt = prompt.replace('{{TRANSCRIPT_SEGMENTS}}', segmentsText);
+    return prompt;
+}
+async function callOllama(prompt, config, options = { expectJson: true }) {
+    const { endpoint, model, maxRetries, timeout } = config;
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    model,
+                    messages: [
+                        {
+                            role: 'system',
+                            content: options.expectJson
+                                ? 'You are a JSON-only output system. Output ONLY valid JSON, no other text.'
+                                : 'You are a helpful assistant that generates high-quality markdown documentation.',
+                        },
+                        {
+                            role: 'user',
+                            content: prompt,
+                        },
+                    ],
+                    stream: false,
+                    ...(options.expectJson && { format: 'json' }),
+                }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                throw new Error(`Ollama API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            if (!data.done || data.done_reason !== 'stop') {
+                throw new Error(`Incomplete response: done=${data.done}, reason=${data.done_reason}`);
+            }
+            const content = data.message.content;
+            if (options.expectJson) {
+                const jsonMatch = content.match(/\{[\s\S]*\}/);
+                if (!jsonMatch)
+                    throw new Error('No JSON found in response');
+                return JSON.parse(jsonMatch[0]);
+            }
+            return content;
+        }
+        catch (error) {
+            lastError = error;
+            if (error instanceof Error && error.name === 'AbortError') {
+                console.log(`Attempt ${attempt}/${maxRetries}: Request timed out, retrying...`);
+            }
+            else {
+                console.log(`Attempt ${attempt}/${maxRetries}: Request failed, retrying...`);
+            }
+            if (attempt < maxRetries) {
+                await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
+            }
+        }
+    }
+    throw new Error(`Request failed after ${maxRetries} retries: ${lastError?.message}`);
+}
+async function extractMetadata(transcript, classification, config) {
+    const prompt = loadMetadataPrompt(transcript, classification);
+    const raw = await callOllama(prompt, config, { expectJson: true });
+    return {
+        speakers: raw.speakers || [],
+        keyMoments: raw.keyMoments || [],
+        actionItems: raw.actionItems || [],
+        technicalTerms: raw.technicalTerms || [],
+        codeSnippets: raw.codeSnippets || [],
+    };
+}
+function loadMetadataPrompt(transcript, classification) {
+    const promptPath = join(process.cwd(), 'prompts', 'extract-metadata.md');
+    let prompt = readFileSync(promptPath, 'utf-8');
+    const classificationSummary = Object.entries(classification)
+        .filter(([_, score]) => score >= 25)
+        .map(([type, score]) => `${type}: ${score}%`)
+        .join(', ');
+    const segmentsText = transcript.segments
+        .map((seg) => `[${seg.start}s - ${seg.end}s] ${seg.text}`)
+        .join('\n');
+    prompt = prompt.replace('{{CLASSIFICATION_SUMMARY}}', classificationSummary);
+    prompt = prompt.replace('{{TRANSCRIPT_SEGMENTS}}', segmentsText);
+    prompt = prompt.replace('{{TRANSCRIPT_ALL}}', transcript.fullText);
+    return prompt;
+}
+function parseMetadataJson(content) {
+    const jsonMatch = content.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+        throw new Error('No JSON object found in metadata extraction response');
+    }
+    const parsed = JSON.parse(jsonMatch[0]);
+    return {
+        speakers: parsed.speakers || [],
+        keyMoments: parsed.keyMoments || [],
+        actionItems: parsed.actionItems || [],
+        technicalTerms: parsed.technicalTerms || [],
+        codeSnippets: parsed.codeSnippets || [],
+    };
+}
+async function generateArtifact(artifactType, context, config) {
+    const prompt = loadArtifactPrompt(artifactType, context);
+    const response = await callOllama(prompt, config, { expectJson: false });
+    return response;
+}
+function loadArtifactPrompt(artifactType, context) {
+    const promptPath = join(process.cwd(), 'prompts', `${artifactType}.md`);
+    let prompt = readFileSync(promptPath, 'utf-8');
+    prompt = prompt.replace('{{TRANSCRIPT_ALL}}', context.transcript.fullText);
+    const segmentsText = context.transcript.segments
+        .map((seg) => `[${seg.start}s - ${seg.end}s] ${seg.text}`)
+        .join('\n');
+    prompt = prompt.replace('{{TRANSCRIPT_SEGMENTS}}', segmentsText);
+    const classificationSummary = Object.entries(context.classification)
+        .filter(([_, score]) => score >= 25)
+        .map(([type, score]) => `${type}: ${score}%`)
+        .join(', ');
+    prompt = prompt.replace('{{CLASSIFICATION_SUMMARY}}', classificationSummary);
+    if (context.metadata) {
+        prompt = prompt.replace('{{SPEAKERS}}', JSON.stringify(context.metadata.speakers || [], null, 2));
+        prompt = prompt.replace('{{KEY_MOMENTS}}', JSON.stringify(context.metadata.keyMoments || [], null, 2));
+        prompt = prompt.replace('{{ACTION_ITEMS}}', JSON.stringify(context.metadata.actionItems || [], null, 2));
+        prompt = prompt.replace('{{TECHNICAL_TERMS}}', JSON.stringify(context.metadata.technicalTerms || [], null, 2));
+        prompt = prompt.replace('{{CODE_SNIPPETS}}', JSON.stringify(context.metadata.codeSnippets || [], null, 2));
+    }
+    else {
+        prompt = prompt.replace('{{SPEAKERS}}', 'N/A');
+        prompt = prompt.replace('{{KEY_MOMENTS}}', 'N/A');
+        prompt = prompt.replace('{{ACTION_ITEMS}}', 'N/A');
+        prompt = prompt.replace('{{TECHNICAL_TERMS}}', 'N/A');
+        prompt = prompt.replace('{{CODE_SNIPPETS}}', 'N/A');
+    }
+    return prompt;
+}