escribano 0.1.0

package/dist/actions/create-contexts.js

@@ -0,0 +1,44 @@
+/**
+ * Escribano - Context Creation Action
+ *
+ * Creates Context entities from extracted signals and links observations.
+ */
+import { generateId } from '../db/helpers.js';
+export function createContextsFromSignals(signals, observations, contextRepo) {
+    const contextIds = [];
+    const observationLinks = [];
+    // Helper: get or create context
+    const getOrCreateContext = (type, name) => {
+        const existing = contextRepo.findByTypeAndName(type, name);
+        if (existing)
+            return existing.id;
+        const id = generateId();
+        contextRepo.save({ id, type, name, metadata: null });
+        return id;
+    };
+    // Create contexts for each signal type
+    for (const app of signals.apps) {
+        const contextId = getOrCreateContext('app', app);
+        contextIds.push(contextId);
+    }
+    for (const url of signals.urls) {
+        const contextId = getOrCreateContext('url', url);
+        contextIds.push(contextId);
+    }
+    for (const project of signals.projects) {
+        const contextId = getOrCreateContext('project', project);
+        contextIds.push(contextId);
+    }
+    for (const topic of signals.topics) {
+        const contextId = getOrCreateContext('topic', topic);
+        contextIds.push(contextId);
+    }
+    // Link all observations to all contexts (cluster-level association)
+    const uniqueContextIds = [...new Set(contextIds)];
+    for (const obs of observations) {
+        for (const contextId of uniqueContextIds) {
+            observationLinks.push({ observationId: obs.id, contextId });
+        }
+    }
+    return { contextIds: uniqueContextIds, observationLinks };
+}

package/dist/actions/create-topic-blocks.js

@@ -0,0 +1,68 @@
+/**
+ * Escribano - TopicBlock Creation Action
+ *
+ * Creates TopicBlocks from clusters with their associated contexts.
+ */
+import { generateId } from '../db/helpers.js';
+export function createTopicBlockFromCluster(input, topicBlockRepo) {
+    const { cluster, contextIds, signals, mergedAudioClusterIds } = input;
+    const id = generateId();
+    // Build classification from signals
+    const classification = buildClassification(signals);
+    // Calculate duration
+    const duration = cluster.end_timestamp - cluster.start_timestamp;
+    topicBlockRepo.save({
+        id,
+        recording_id: cluster.recording_id,
+        context_ids: JSON.stringify(contextIds),
+        classification: JSON.stringify({
+            ...classification,
+            mergedAudioClusterIds: mergedAudioClusterIds || [],
+        }),
+        duration,
+    });
+    return id;
+}
+function buildClassification(signals) {
+    // Map topics to classification scores
+    const scores = {
+        meeting: 0,
+        debugging: 0,
+        tutorial: 0,
+        learning: 0,
+        working: 0,
+    };
+    for (const topic of signals.topics) {
+        const lower = topic.toLowerCase();
+        if (lower.includes('debug') ||
+            lower.includes('fix') ||
+            lower.includes('error')) {
+            scores.debugging = Math.max(scores.debugging, 80);
+        }
+        if (lower.includes('learn') ||
+            lower.includes('understand') ||
+            lower.includes('research')) {
+            scores.learning = Math.max(scores.learning, 80);
+        }
+        if (lower.includes('tutorial') ||
+            lower.includes('watch') ||
+            lower.includes('video')) {
+            scores.tutorial = Math.max(scores.tutorial, 80);
+        }
+        if (lower.includes('meeting') ||
+            lower.includes('call') ||
+            lower.includes('discuss')) {
+            scores.meeting = Math.max(scores.meeting, 80);
+        }
+        if (lower.includes('implement') ||
+            lower.includes('build') ||
+            lower.includes('code')) {
+            scores.working = Math.max(scores.working, 80);
+        }
+    }
+    // Default to working if no specific signals
+    if (Object.values(scores).every((s) => s === 0)) {
+        scores.working = 50;
+    }
+    return scores;
+}

package/dist/actions/extract-metadata.js

@@ -0,0 +1,24 @@
+/**
+ * Escribano - Extract Metadata Action
+ *
+ * Extracts structured metadata from session transcripts using LLM
+ */
+export async function extractMetadata(session, intelligence) {
+    if (!session.classification) {
+        throw new Error('Session must be classified before metadata extraction');
+    }
+    console.log('Extracting metadata from transcript...');
+    const metadata = await intelligence.extractMetadata(session.transcripts[0]?.transcript || {
+        fullText: '',
+        segments: [],
+        duration: session.recording.duration,
+        language: 'en',
+    }, session.classification, session.visualLogs);
+    console.log('✓ Metadata extraction complete');
+    return {
+        ...session,
+        metadata,
+        status: 'metadata-extracted',
+        updatedAt: new Date(),
+    };
+}

package/dist/actions/generate-artifact-v3.js

@@ -0,0 +1,296 @@
+/**
+ * Escribano - Generate Artifact V3.1
+ *
+ * Generates structured artifacts from Subjects using format templates.
+ * Supports: card (default), standup, narrative
+ */
+import { execSync } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { log, step } from '../pipeline/context.js';
+import { normalizeAppNames } from '../services/app-normalization.js';
+import { groupTopicBlocksIntoSubjects, saveSubjectsToDatabase, } from '../services/subject-grouping.js';
+export async function generateArtifactV3(recordingId, repos, intelligence, options) {
+    const format = options.format || 'card';
+    log('info', `[Artifact V3.1] Generating ${format} artifact for recording ${recordingId}...`);
+    const recording = repos.recordings.findById(recordingId);
+    if (!recording) {
+        throw new Error(`Recording ${recordingId} not found`);
+    }
+    const topicBlocks = repos.topicBlocks.findByRecording(recordingId);
+    if (topicBlocks.length === 0) {
+        throw new Error(`No TopicBlocks found for recording ${recordingId}. Run process-v3 first.`);
+    }
+    log('info', `[Artifact V3.1] Found ${topicBlocks.length} TopicBlocks`);
+    const existingSubjects = repos.subjects.findByRecording(recordingId);
+    let subjects;
+    let personalDuration;
+    let workDuration;
+    if (existingSubjects.length > 0) {
+        log('info', `[Artifact V3.1] Reusing ${existingSubjects.length} existing subjects (no re-grouping needed)`);
+        const loaded = await loadExistingSubjects(existingSubjects, repos);
+        subjects = loaded.subjects;
+        personalDuration = loaded.personalDuration;
+        workDuration = loaded.workDuration;
+    }
+    else {
+        log('info', '[Artifact V3.1] Grouping TopicBlocks into subjects...');
+        const groupingResult = await step('subject grouping', () => groupTopicBlocksIntoSubjects(topicBlocks, intelligence, recordingId));
+        log('info', `[Artifact V3.1] Saving ${groupingResult.subjects.length} subjects to database...`);
+        saveSubjectsToDatabase(groupingResult.subjects, recordingId, repos);
+        subjects = groupingResult.subjects;
+        personalDuration = groupingResult.personalDuration;
+        workDuration = groupingResult.workDuration;
+    }
+    for (const subject of subjects) {
+        subject.apps = normalizeAppNames(subject.apps);
+    }
+    const filteredSubjects = options.includePersonal
+        ? subjects
+        : subjects.filter((s) => !s.isPersonal);
+    log('info', `[Artifact V3.1] Generating ${format} with LLM...`);
+    const content = await step('artifact generation', () => generateLlmArtifact(subjects, { subjects, personalDuration, workDuration }, format, recording, intelligence, repos, topicBlocks));
+    const outputDir = options.outputDir || path.join(homedir(), '.escribano', 'artifacts');
+    await mkdir(outputDir, { recursive: true });
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const fileName = `${recordingId}-${format}-${timestamp}.md`;
+    const filePath = path.join(outputDir, fileName);
+    await writeFile(filePath, content, 'utf-8');
+    log('info', `[Artifact V3.1] Artifact saved to: ${filePath}`);
+    const artifactId = `artifact-${recordingId}-${format}-${Date.now()}`;
+    repos.artifacts.save({
+        id: artifactId,
+        recording_id: recordingId,
+        type: format,
+        content,
+        format: 'markdown',
+        source_block_ids: JSON.stringify(subjects.flatMap((s) => s.topicBlockIds)),
+        source_context_ids: null,
+    });
+    log('info', `[Artifact V3.1] Saved to database: ${artifactId}`);
+    // Link subjects to artifact
+    repos.artifacts.linkSubjects(artifactId, subjects.map((s) => s.id));
+    log('info', `[Artifact V3.1] Linked ${subjects.length} subjects to artifact`);
+    if (options.printToStdout) {
+        console.log(`\n${content}\n`);
+    }
+    if (options.copyToClipboard && process.platform === 'darwin') {
+        try {
+            execSync('pbcopy', { input: content, encoding: 'utf-8' });
+            log('info', '[Artifact V3.1] Copied to clipboard');
+        }
+        catch (error) {
+            log('warn', `[Artifact V3.1] Failed to copy to clipboard: ${error}`);
+        }
+    }
+    return {
+        id: artifactId,
+        recordingId,
+        format,
+        content,
+        filePath,
+        subjects,
+        personalDuration,
+        workDuration,
+        createdAt: new Date(),
+    };
+}
+async function loadExistingSubjects(existingSubjects, repos) {
+    const subjects = [];
+    for (const dbSubject of existingSubjects) {
+        const topicBlocks = repos.subjects.getTopicBlocks(dbSubject.id);
+        const activityBreakdown = dbSubject.activity_breakdown
+            ? JSON.parse(dbSubject.activity_breakdown)
+            : {};
+        const metadata = dbSubject.metadata ? JSON.parse(dbSubject.metadata) : {};
+        const apps = metadata.apps || [];
+        subjects.push({
+            id: dbSubject.id,
+            recordingId: topicBlocks[0]?.recording_id || '',
+            label: dbSubject.label,
+            topicBlockIds: topicBlocks.map((b) => b.id),
+            totalDuration: dbSubject.duration,
+            activityBreakdown,
+            apps,
+            isPersonal: dbSubject.is_personal === 1,
+        });
+    }
+    const personalDuration = subjects
+        .filter((s) => s.isPersonal)
+        .reduce((sum, s) => sum + s.totalDuration, 0);
+    const workDuration = subjects
+        .filter((s) => !s.isPersonal)
+        .reduce((sum, s) => sum + s.totalDuration, 0);
+    return { subjects, personalDuration, workDuration };
+}
+function generateTemplateArtifact(subjects, groupingResult, format, recording) {
+    const sessionDate = new Date(recording.captured_at).toLocaleDateString('en-US', {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    });
+    const sessionDuration = formatDuration(recording.duration);
+    switch (format) {
+        case 'standup':
+            return generateStandupTemplate(subjects, sessionDate, sessionDuration);
+        case 'narrative':
+            return generateNarrativeTemplate(subjects, sessionDate, sessionDuration);
+        default:
+            return generateCardTemplate(subjects, groupingResult, sessionDate, sessionDuration);
+    }
+}
+function generateCardTemplate(subjects, groupingResult, sessionDate, sessionDuration) {
+    let content = `# Session Card - ${sessionDate}\n\n`;
+    content += `**Total Duration:** ${sessionDuration}\n`;
+    content += `**Subjects:** ${subjects.length}\n\n`;
+    for (const subject of subjects) {
+        const activityStr = Object.entries(subject.activityBreakdown)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 3)
+            .map(([activity, duration]) => `${activity} ${formatDuration(duration)}`)
+            .join(', ');
+        content += `## ${subject.label}\n`;
+        content += `**${formatDuration(subject.totalDuration)}** | ${activityStr || 'various'}\n\n`;
+        const bullets = extractAccomplishmentBullets(subject);
+        for (const bullet of bullets.slice(0, 4)) {
+            content += `- ${bullet}\n`;
+        }
+        content += '\n';
+    }
+    if (groupingResult.personalDuration > 0) {
+        content += `---\n*Personal time: ${formatDuration(groupingResult.personalDuration)} (filtered)*\n`;
+    }
+    return content;
+}
+function generateStandupTemplate(subjects, sessionDate, sessionDuration) {
+    let content = `## Standup - ${sessionDate}\n\n`;
+    content += `**What I did:**\n`;
+    const allActivities = [];
+    for (const subject of subjects) {
+        allActivities.push(...extractAccomplishmentBullets(subject));
+    }
+    for (const activity of allActivities.slice(0, 5)) {
+        content += `- ${activity}\n`;
+    }
+    content += '\n**Key outcomes:**\n';
+    content += '- [Add key outcomes from session]\n';
+    content += '- [Add key outcomes from session]\n';
+    content += '\n**Next:**\n';
+    content += '- [Add next steps]\n';
+    return content;
+}
+function generateNarrativeTemplate(subjects, sessionDate, sessionDuration) {
+    let content = `# Session Summary - ${sessionDate}\n\n`;
+    content += `**Duration:** ${sessionDuration}\n\n`;
+    content += `## Overview\n\n`;
+    content += `This session covered ${subjects.length} main subjects.\n\n`;
+    for (const subject of subjects) {
+        content += `## ${subject.label}\n\n`;
+        content += `Spent ${formatDuration(subject.totalDuration)} on ${subject.label.toLowerCase()}.\n\n`;
+        const bullets = extractAccomplishmentBullets(subject);
+        for (const bullet of bullets.slice(0, 3)) {
+            content += `- ${bullet}\n`;
+        }
+        content += '\n';
+    }
+    return content;
+}
+async function generateLlmArtifact(subjects, groupingResult, format, recording, intelligence, repos, allTopicBlocks) {
+    const ARTIFACT_THINK = process.env.ESCRIBANO_ARTIFACT_THINK === 'true';
+    const promptFileName = format === 'card'
+        ? 'card.md'
+        : format === 'standup'
+            ? 'standup.md'
+            : 'summary-v3.md';
+    const promptPath = path.join(process.cwd(), 'prompts', promptFileName);
+    let promptTemplate;
+    try {
+        promptTemplate = await readFile(promptPath, 'utf-8');
+    }
+    catch {
+        log('warn', `[Artifact V3.1] Prompt template not found: ${promptPath}, using fallback`);
+        return generateTemplateArtifact(subjects, groupingResult, format, recording);
+    }
+    const sessionDate = new Date(recording.captured_at).toLocaleDateString('en-US', {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    });
+    const subjectsData = buildSubjectsDataForPrompt(subjects, allTopicBlocks);
+    const prompt = promptTemplate
+        .replace('{{SESSION_DURATION}}', formatDuration(recording.duration))
+        .replace('{{SESSION_DATE}}', sessionDate)
+        .replace('{{SUBJECT_COUNT}}', String(subjects.length))
+        .replace('{{SUBJECTS_DATA}}', subjectsData)
+        .replace('{{WORK_SUBJECTS}}', subjectsData);
+    return intelligence.generateText(prompt, {
+        expectJson: false,
+        think: ARTIFACT_THINK,
+    });
+}
+function buildSubjectsDataForPrompt(subjects, allTopicBlocks) {
+    // Build a map of TopicBlocks by subject ID for quick lookup
+    const blocksBySubjectId = new Map();
+    for (const subject of subjects) {
+        const subjectBlocks = allTopicBlocks.filter((block) => subject.topicBlockIds.includes(block.id));
+        blocksBySubjectId.set(subject.id, subjectBlocks);
+    }
+    return subjects
+        .map((subject) => {
+        const activityStr = Object.entries(subject.activityBreakdown)
+            .sort((a, b) => b[1] - a[1])
+            .map(([activity, duration]) => `${activity}: ${formatDuration(duration)}`)
+            .join(', ');
+        const subjectBlocks = blocksBySubjectId.get(subject.id) || [];
+        const blockDescriptions = subjectBlocks
+            .map((block, index) => {
+            try {
+                const classification = JSON.parse(block.classification || '{}');
+                const desc = classification.key_description || '';
+                const duration = block.duration
+                    ? formatDuration(block.duration)
+                    : 'unknown';
+                return `- Block ${index + 1} (${duration}): ${desc}`;
+            }
+            catch {
+                return `- Block ${index + 1}: [Unable to parse description]`;
+            }
+        })
+            .join('\n');
+        return `### Subject: ${subject.label}
+**Duration:** ${formatDuration(subject.totalDuration)}
+**Activities:** ${activityStr || 'various'}
+**Apps:** ${subject.apps.join(', ') || 'none'}
+**isPersonal:** ${subject.isPersonal}
+
+**Block Descriptions:**
+${blockDescriptions || '(no blocks)'}
+`;
+    })
+        .join('\n---\n\n');
+}
+function extractAccomplishmentBullets(subject) {
+    const bullets = [];
+    if (subject.apps.length > 0) {
+        bullets.push(`Worked with ${subject.apps.slice(0, 3).join(', ')}`);
+    }
+    const dominantActivity = Object.entries(subject.activityBreakdown).sort((a, b) => b[1] - a[1])[0];
+    if (dominantActivity) {
+        bullets.push(`Primary activity: ${dominantActivity[0]} (${formatDuration(dominantActivity[1])})`);
+    }
+    return bullets;
+}
+function formatDuration(seconds) {
+    const hours = Math.floor(seconds / 3600);
+    const mins = Math.floor((seconds % 3600) / 60);
+    if (hours > 0) {
+        return `${hours}h ${mins}m`;
+    }
+    if (mins > 0) {
+        return `${mins}m`;
+    }
+    return `${Math.floor(seconds)}s`;
+}

package/dist/actions/generate-artifact.js

@@ -0,0 +1,61 @@
+import os from 'node:os';
+import path from 'node:path';
+import { Session } from '../domain/session.js';
+/**
+ * Generates a specific artifact for a session, including on-demand screenshot extraction
+ */
+export async function generateArtifact(session, intelligence, artifactType, videoService) {
+    if (!session.classification) {
+        throw new Error('Session must be classified before generating artifacts');
+    }
+    // Combine transcripts for context
+    const fullText = session.transcripts
+        .map((t) => `[${t.source.toUpperCase()}]\n${t.transcript.fullText}`)
+        .join('\n\n');
+    const context = {
+        transcript: {
+            ...session.transcripts[0].transcript,
+            fullText,
+        },
+        classification: session.classification,
+        metadata: session.metadata,
+        visualLogs: session.visualLogs,
+    };
+    let content = await intelligence.generate(artifactType, context);
+    // Post-process [SCREENSHOT: timestamp] tags for on-demand extraction
+    const screenshotRegex = /\[SCREENSHOT:\s*([\d.]+)\]/g;
+    const matches = [...content.matchAll(screenshotRegex)];
+    if (matches.length > 0 && session.recording.videoPath) {
+        console.log(`Found ${matches.length} screenshot requests in artifact. Extracting...`);
+        const timestamps = matches.map((m) => Number.parseFloat(m[1]));
+        const screenshotDir = path.join(os.homedir(), '.escribano', 'sessions', session.id, 'artifacts', 'screenshots');
+        try {
+            const paths = await videoService.extractFramesAtTimestamps(session.recording.videoPath, timestamps, screenshotDir);
+            // Replace tags with markdown images using relative paths
+            for (let i = 0; i < matches.length; i++) {
+                const match = matches[i];
+                if (paths[i]) {
+                    const fileName = path.basename(paths[i]);
+                    const markdownImage = `![Screenshot at ${match[1]}s](./screenshots/${fileName})`;
+                    content = content.replace(match[0], markdownImage);
+                }
+            }
+        }
+        catch (error) {
+            console.error('Failed to extract screenshots for artifact:', error);
+        }
+    }
+    return {
+        id: `${session.id}-${artifactType}-${Date.now()}`,
+        type: artifactType,
+        content,
+        format: 'markdown',
+        createdAt: new Date(),
+    };
+}
+/**
+ * Returns a list of recommended artifact types based on session classification
+ */
+export function getRecommendedArtifacts(session) {
+    return Session.getRecommendedArtifacts(session);
+}