openbuilder 0.1.0

package/scripts/builder-report.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env npx tsx
+/**
+ * builder-report.ts — Generate a full AI meeting report
+ *
+ * Usage:
+ *   npx openbuilder report                          # report on latest transcript
+ *   npx openbuilder report /path/to/transcript.txt  # report on specific file
+ *
+ * Generates: summary, chapters, action items, key decisions, key questions,
+ * and speaker analytics. Output is a markdown report saved to disk.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+
+import { getConfig, TRANSCRIPTS_DIR, REPORTS_DIR, ensureDirs } from "../src/utils/config.js";
+import { parseTranscript, formatTranscriptForAI, chunkTranscript } from "../src/utils/transcript-parser.js";
+import { ClaudeProvider } from "../src/ai/claude.js";
+import { OpenAIProvider } from "../src/ai/openai.js";
+import { getMeetingAnalysisPrompt, getMergeAnalysisPrompt } from "../src/ai/prompts.js";
+import { calculateSpeakerStats } from "../src/analytics/speaker-stats.js";
+import { parseAnalysisResponse, generateReport } from "../src/report/generator.js";
+import type { AIProvider } from "../src/ai/provider.js";
+
+function findLatestTranscript(): string | null {
+  if (!existsSync(TRANSCRIPTS_DIR)) return null;
+
+  const files = readdirSync(TRANSCRIPTS_DIR)
+    .filter((f) => f.endsWith(".txt"))
+    .map((f) => ({
+      path: `${TRANSCRIPTS_DIR}/${f}`,
+      mtime: statSync(`${TRANSCRIPTS_DIR}/${f}`).mtimeMs,
+    }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  return files.length > 0 ? files[0]!.path : null;
+}
+
+function getProvider(): AIProvider {
+  const config = getConfig();
+
+  if (config.aiProvider === "openai" && config.openaiApiKey) {
+    return new OpenAIProvider();
+  }
+  if (config.anthropicApiKey) {
+    return new ClaudeProvider();
+  }
+  if (config.openaiApiKey) {
+    return new OpenAIProvider();
+  }
+
+  console.error("No AI API key configured.");
+  console.error("Set one of these environment variables or use `openbuilder config`:");
+  console.error("  ANTHROPIC_API_KEY=your-key");
+  console.error("  OPENAI_API_KEY=your-key");
+  process.exit(1);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const transcriptPath = args.find((a) => !a.startsWith("--"));
+
+  let filePath: string;
+  if (transcriptPath) {
+    if (!existsSync(transcriptPath)) {
+      console.error(`File not found: ${transcriptPath}`);
+      process.exit(1);
+    }
+    filePath = transcriptPath;
+  } else {
+    const latest = findLatestTranscript();
+    if (!latest) {
+      console.error("No transcript files found.");
+      console.error("Provide a transcript path: npx openbuilder report /path/to/transcript.txt");
+      process.exit(1);
+    }
+    filePath = latest;
+  }
+
+  const content = readFileSync(filePath, "utf-8").trim();
+  if (!content) {
+    console.error("Transcript file is empty.");
+    process.exit(1);
+  }
+
+  ensureDirs();
+
+  console.log(`Generating meeting report for: ${filePath}\n`);
+
+  const provider = getProvider();
+  const transcript = parseTranscript(content);
+  const analytics = calculateSpeakerStats(transcript);
+
+  // Run AI analysis
+  const chunks = chunkTranscript(transcript, 30000);
+  let analysisResponse: string;
+
+  if (chunks.length === 1) {
+    console.log("Analyzing transcript...");
+    const formatted = formatTranscriptForAI(transcript);
+    analysisResponse = await provider.complete({
+      messages: [
+        { role: "system", content: "You are an expert meeting analyst. Return only valid JSON." },
+        { role: "user", content: getMeetingAnalysisPrompt(formatted) },
+      ],
+      maxTokens: 4096,
+      temperature: 0.3,
+    });
+  } else {
+    const chunkResults: string[] = [];
+    for (let i = 0; i < chunks.length; i++) {
+      console.log(`Analyzing chunk ${i + 1}/${chunks.length}...`);
+      const result = await provider.complete({
+        messages: [
+          { role: "system", content: "You are an expert meeting analyst. Return only valid JSON." },
+          {
+            role: "user",
+            content: getMeetingAnalysisPrompt(chunks[i]!, `chunk ${i + 1} of ${chunks.length}`),
+          },
+        ],
+        maxTokens: 4096,
+        temperature: 0.3,
+      });
+      chunkResults.push(result);
+    }
+
+    console.log("Merging analyses...");
+    analysisResponse = await provider.complete({
+      messages: [
+        { role: "system", content: "You are an expert meeting analyst. Return only valid JSON." },
+        { role: "user", content: getMergeAnalysisPrompt(chunkResults) },
+      ],
+      maxTokens: 4096,
+      temperature: 0.3,
+    });
+  }
+
+  const analysis = parseAnalysisResponse(analysisResponse);
+
+  // Derive meeting ID from filename
+  const meetingId = basename(filePath, ".txt");
+
+  const report = generateReport({
+    meetingId,
+    date: new Date().toISOString().split("T")[0],
+    transcriptPath: filePath,
+    analysis,
+    analytics,
+  });
+
+  // Save report
+  mkdirSync(REPORTS_DIR, { recursive: true });
+  const reportPath = `${REPORTS_DIR}/${meetingId}-report.md`;
+  writeFileSync(reportPath, report);
+
+  console.log("\n" + report);
+  console.log(`\nReport saved to: ${reportPath}`);
+}
+
+const isMain = process.argv[1]?.endsWith("builder-report.ts");
+if (isMain) {
+  main().catch((err) => {
+    console.error("Fatal:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}

package/scripts/builder-screenshot.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env npx tsx
+/**
+ * builder-screenshot.ts — Request an on-demand screenshot from a running bot
+ *
+ * Usage:
+ *   npx openbuilder screenshot
+ *
+ * Sends SIGUSR1 to the running builder-join process, waits for the
+ * screenshot to be saved, and prints the path.
+ */
+
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { PID_FILE, SCREENSHOT_READY_FILE } from "../src/utils/config.js";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function main() {
+  if (!existsSync(PID_FILE)) {
+    console.error("No running OpenBuilder bot found (missing PID file).");
+    console.error("Start a meeting first: npx openbuilder join <url> --auth|--anon");
+    process.exit(1);
+  }
+
+  const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+  if (isNaN(pid)) {
+    console.error("Invalid PID file contents.");
+    process.exit(1);
+  }
+
+  try {
+    process.kill(pid, 0);
+  } catch {
+    console.error(`OpenBuilder process (PID ${pid}) is not running.`);
+    try {
+      unlinkSync(PID_FILE);
+    } catch {
+      /* ignore */
+    }
+    process.exit(1);
+  }
+
+  try {
+    if (existsSync(SCREENSHOT_READY_FILE)) unlinkSync(SCREENSHOT_READY_FILE);
+  } catch {
+    /* ignore */
+  }
+
+  console.log(`Requesting screenshot from OpenBuilder (PID ${pid})...`);
+  process.kill(pid, "SIGUSR1");
+
+  const timeoutMs = 10_000;
+  const pollMs = 500;
+  const start = Date.now();
+
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(SCREENSHOT_READY_FILE)) {
+      try {
+        const data = JSON.parse(readFileSync(SCREENSHOT_READY_FILE, "utf-8")) as {
+          path: string;
+          timestamp: number;
+        };
+        console.log(`[OPENBUILDER_SCREENSHOT] ${data.path}`);
+        return;
+      } catch {
+        // File partially written, retry
+      }
+    }
+    await sleep(pollMs);
+  }
+
+  console.error("Timed out waiting for screenshot (10s).");
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/scripts/builder-summarize.ts

@@ -0,0 +1,142 @@
+#!/usr/bin/env npx tsx
+/**
+ * builder-summarize.ts — Run AI summary on a transcript file
+ *
+ * Usage:
+ *   npx openbuilder summarize                        # summarize latest transcript
+ *   npx openbuilder summarize /path/to/transcript.txt  # summarize specific file
+ *
+ * Works standalone on any transcript file in [HH:MM:SS] Speaker: text format.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+
+import { getConfig, TRANSCRIPTS_DIR } from "../src/utils/config.js";
+import { parseTranscript, formatTranscriptForAI, chunkTranscript } from "../src/utils/transcript-parser.js";
+import { ClaudeProvider } from "../src/ai/claude.js";
+import { OpenAIProvider } from "../src/ai/openai.js";
+import { getQuickSummaryPrompt } from "../src/ai/prompts.js";
+import type { AIProvider } from "../src/ai/provider.js";
+
+function findLatestTranscript(): string | null {
+  if (!existsSync(TRANSCRIPTS_DIR)) return null;
+
+  const files = readdirSync(TRANSCRIPTS_DIR)
+    .filter((f) => f.endsWith(".txt"))
+    .map((f) => ({
+      path: `${TRANSCRIPTS_DIR}/${f}`,
+      mtime: statSync(`${TRANSCRIPTS_DIR}/${f}`).mtimeMs,
+    }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  return files.length > 0 ? files[0]!.path : null;
+}
+
+function getProvider(): AIProvider {
+  const config = getConfig();
+
+  if (config.aiProvider === "openai" && config.openaiApiKey) {
+    return new OpenAIProvider();
+  }
+  if (config.anthropicApiKey) {
+    return new ClaudeProvider();
+  }
+  if (config.openaiApiKey) {
+    return new OpenAIProvider();
+  }
+
+  console.error("No AI API key configured.");
+  console.error("Set one of these environment variables or use `openbuilder config`:");
+  console.error("  ANTHROPIC_API_KEY=your-key");
+  console.error("  OPENAI_API_KEY=your-key");
+  process.exit(1);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const transcriptPath = args.find((a) => !a.startsWith("--"));
+
+  let filePath: string;
+  if (transcriptPath) {
+    if (!existsSync(transcriptPath)) {
+      console.error(`File not found: ${transcriptPath}`);
+      process.exit(1);
+    }
+    filePath = transcriptPath;
+  } else {
+    const latest = findLatestTranscript();
+    if (!latest) {
+      console.error("No transcript files found.");
+      console.error("Provide a transcript path: npx openbuilder summarize /path/to/transcript.txt");
+      process.exit(1);
+    }
+    filePath = latest;
+  }
+
+  const content = readFileSync(filePath, "utf-8").trim();
+  if (!content) {
+    console.error("Transcript file is empty.");
+    process.exit(1);
+  }
+
+  console.log(`Summarizing: ${filePath}\n`);
+
+  const provider = getProvider();
+  const transcript = parseTranscript(content);
+  const chunks = chunkTranscript(transcript, 30000);
+
+  let summary: string;
+
+  if (chunks.length === 1) {
+    const formatted = formatTranscriptForAI(transcript);
+    summary = await provider.complete({
+      messages: [
+        { role: "system", content: "You are an expert meeting analyst. Write clear, professional summaries." },
+        { role: "user", content: getQuickSummaryPrompt(formatted) },
+      ],
+      maxTokens: 2048,
+      temperature: 0.3,
+    });
+  } else {
+    // For long transcripts, summarize each chunk then combine
+    const chunkSummaries: string[] = [];
+    for (let i = 0; i < chunks.length; i++) {
+      console.log(`Processing chunk ${i + 1}/${chunks.length}...`);
+      const result = await provider.complete({
+        messages: [
+          { role: "system", content: "You are an expert meeting analyst. Write clear, professional summaries." },
+          { role: "user", content: getQuickSummaryPrompt(chunks[i]!) },
+        ],
+        maxTokens: 2048,
+        temperature: 0.3,
+      });
+      chunkSummaries.push(result);
+    }
+
+    summary = await provider.complete({
+      messages: [
+        { role: "system", content: "You are an expert meeting analyst. Combine these summaries into one cohesive summary." },
+        {
+          role: "user",
+          content: `Combine these meeting summaries into a single 3-5 paragraph summary:\n\n${chunkSummaries.join("\n\n---\n\n")}`,
+        },
+      ],
+      maxTokens: 2048,
+      temperature: 0.3,
+    });
+  }
+
+  console.log("---\n");
+  console.log(summary);
+  console.log("\n---");
+  console.log(`\nTranscript: ${filePath}`);
+  console.log(`Lines: ${transcript.lines.length}, Speakers: ${transcript.speakers.join(", ")}`);
+}
+
+const isMain = process.argv[1]?.endsWith("builder-summarize.ts");
+if (isMain) {
+  main().catch((err) => {
+    console.error("Fatal:", err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  });
+}

package/scripts/builder-transcript.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env npx tsx
+/**
+ * builder-transcript.ts — Print the latest transcript from a meeting
+ *
+ * Usage:
+ *   npx openbuilder transcript
+ *   npx openbuilder transcript --last 20
+ *
+ * Finds the most recent transcript file and prints its contents.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { TRANSCRIPTS_DIR } from "../src/utils/config.js";
+
+function main() {
+  const args = process.argv.slice(2);
+  const lastIdx = args.indexOf("--last");
+  const lastN = lastIdx >= 0 ? parseInt(args[lastIdx + 1] ?? "0", 10) : 0;
+
+  if (!existsSync(TRANSCRIPTS_DIR)) {
+    console.error("No transcripts directory found. Is the bot running in a meeting?");
+    process.exit(1);
+  }
+
+  const files = readdirSync(TRANSCRIPTS_DIR)
+    .filter((f) => f.endsWith(".txt"))
+    .map((f) => ({
+      name: f,
+      path: `${TRANSCRIPTS_DIR}/${f}`,
+      mtime: statSync(`${TRANSCRIPTS_DIR}/${f}`).mtimeMs,
+    }))
+    .sort((a, b) => b.mtime - a.mtime);
+
+  if (files.length === 0) {
+    console.error("No transcript files found. Captions may not have been captured yet.");
+    console.error("Make sure the bot is in a meeting and captions are enabled.");
+    process.exit(1);
+  }
+
+  const latest = files[0]!;
+  const content = readFileSync(latest.path, "utf-8").trim();
+
+  if (!content) {
+    console.log(`[OPENBUILDER_TRANSCRIPT] ${latest.path}`);
+    console.log("\n(No captions captured yet — is someone speaking?)");
+    return;
+  }
+
+  const lines = content.split("\n");
+
+  console.log(`[OPENBUILDER_TRANSCRIPT] ${latest.path}`);
+  console.log(`Transcript: ${latest.name} (${lines.length} lines)\n`);
+
+  if (lastN > 0 && lines.length > lastN) {
+    console.log(`(showing last ${lastN} of ${lines.length} lines)\n`);
+    console.log(lines.slice(-lastN).join("\n"));
+  } else {
+    console.log(content);
+  }
+}
+
+main();

package/src/ai/claude.ts

@@ -0,0 +1,59 @@
+/**
+ * claude.ts — Claude/Anthropic AI provider implementation
+ *
+ * Uses the @anthropic-ai/sdk package (optional peer dependency).
+ * Dynamically imported to avoid crashing if not installed.
+ */
+
+import { type AICompletionOptions, type AIProvider, AIProviderError } from "./provider.js";
+import { getConfig } from "../utils/config.js";
+
+export class ClaudeProvider implements AIProvider {
+  readonly name = "Claude";
+
+  async complete(options: AICompletionOptions): Promise<string> {
+    const config = getConfig();
+    const apiKey = config.anthropicApiKey;
+
+    if (!apiKey) {
+      throw new AIProviderError(
+        "claude",
+        "Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable or run: openbuilder config set anthropicApiKey <key>",
+      );
+    }
+
+    let Anthropic: typeof import("@anthropic-ai/sdk").default;
+    try {
+      const mod = await import("@anthropic-ai/sdk");
+      Anthropic = mod.default;
+    } catch {
+      throw new AIProviderError(
+        "claude",
+        "The @anthropic-ai/sdk package is not installed. Run: npm install @anthropic-ai/sdk",
+      );
+    }
+
+    const client = new Anthropic({ apiKey });
+
+    // Separate system message from user/assistant messages
+    const systemMessages = options.messages.filter((m) => m.role === "system");
+    const chatMessages = options.messages.filter((m) => m.role !== "system");
+
+    const response = await client.messages.create({
+      model: "claude-sonnet-4-5-20250929",
+      max_tokens: options.maxTokens ?? 4096,
+      temperature: options.temperature ?? 0.3,
+      system: systemMessages.map((m) => m.content).join("\n\n") || undefined,
+      messages: chatMessages.map((m) => ({
+        role: m.role as "user" | "assistant",
+        content: m.content,
+      })),
+    });
+
+    const textBlock = response.content.find((b) => b.type === "text");
+    if (!textBlock || textBlock.type !== "text") {
+      throw new AIProviderError("claude", "No text content in Claude response");
+    }
+    return textBlock.text;
+  }
+}

package/src/ai/openai.ts

@@ -0,0 +1,54 @@
+/**
+ * openai.ts — OpenAI AI provider implementation
+ *
+ * Uses the openai package (optional peer dependency).
+ * Dynamically imported to avoid crashing if not installed.
+ */
+
+import { type AICompletionOptions, type AIProvider, AIProviderError } from "./provider.js";
+import { getConfig } from "../utils/config.js";
+
+export class OpenAIProvider implements AIProvider {
+  readonly name = "OpenAI";
+
+  async complete(options: AICompletionOptions): Promise<string> {
+    const config = getConfig();
+    const apiKey = config.openaiApiKey;
+
+    if (!apiKey) {
+      throw new AIProviderError(
+        "openai",
+        "OpenAI API key not configured. Set OPENAI_API_KEY environment variable or run: openbuilder config set openaiApiKey <key>",
+      );
+    }
+
+    let OpenAI: typeof import("openai").default;
+    try {
+      const mod = await import("openai");
+      OpenAI = mod.default;
+    } catch {
+      throw new AIProviderError(
+        "openai",
+        "The openai package is not installed. Run: npm install openai",
+      );
+    }
+
+    const client = new OpenAI({ apiKey });
+
+    const response = await client.chat.completions.create({
+      model: "gpt-4o",
+      max_tokens: options.maxTokens ?? 4096,
+      temperature: options.temperature ?? 0.3,
+      messages: options.messages.map((m) => ({
+        role: m.role,
+        content: m.content,
+      })),
+    });
+
+    const content = response.choices[0]?.message?.content;
+    if (!content) {
+      throw new AIProviderError("openai", "No content in OpenAI response");
+    }
+    return content;
+  }
+}

package/src/ai/prompts.ts

@@ -0,0 +1,95 @@
+/**
+ * prompts.ts — Meeting analysis prompts for AI processing
+ *
+ * Designed to work with transcripts in [HH:MM:SS] Speaker: text format.
+ * Handles long meetings via chunking when needed.
+ */
+
+export const SYSTEM_PROMPT = `You are an expert meeting analyst. You analyze meeting transcripts and produce structured, actionable meeting intelligence. Be concise but thorough. Focus on what matters most.`;
+
+/**
+ * Prompt for generating a full meeting analysis from a transcript.
+ * Returns structured JSON for programmatic parsing.
+ */
+export function getMeetingAnalysisPrompt(transcript: string, chunkInfo?: string): string {
+  const chunkNote = chunkInfo
+    ? `\n\nNOTE: This is ${chunkInfo} of a longer meeting. Analyze this portion thoroughly.`
+    : "";
+
+  return `Analyze this meeting transcript and return a JSON object with the following structure. Be thorough but concise.${chunkNote}
+
+Return ONLY valid JSON — no markdown fences, no explanation before or after.
+
+{
+  "summary": "2-3 paragraph summary covering the main topics discussed, key outcomes, and overall meeting flow",
+  "chapters": [
+    { "timestamp": "HH:MM", "title": "Topic name", "description": "Brief description of what was discussed" }
+  ],
+  "actionItems": [
+    { "description": "What needs to be done", "assignee": "Person name or null if unspecified" }
+  ],
+  "keyDecisions": [
+    "Decision that was made"
+  ],
+  "keyQuestions": [
+    { "question": "Question that was asked", "status": "answered" or "unanswered" }
+  ]
+}
+
+Guidelines:
+- For chapters: Group discussion into logical topic segments with approximate timestamps
+- For action items: Look for commitments, tasks, follow-ups. Detect assignees from context (e.g. "Alice will..." → assignee: "Alice")
+- For key decisions: Only include explicit decisions, not suggestions or ideas
+- For key questions: Include important questions raised. Mark as "answered" if the transcript shows a response
+- Use the speaker names exactly as they appear in the transcript
+- Timestamps should use HH:MM format from the transcript
+
+TRANSCRIPT:
+${transcript}`;
+}
+
+/**
+ * Prompt for merging multiple chunk analyses into a single cohesive report.
+ * Used when a transcript is too long to process in one pass.
+ */
+export function getMergeAnalysisPrompt(chunkResults: string[]): string {
+  const numbered = chunkResults
+    .map((r, i) => `--- CHUNK ${i + 1} ANALYSIS ---\n${r}`)
+    .join("\n\n");
+
+  return `You were given a long meeting transcript in chunks. Below are the analyses of each chunk. Merge them into a single cohesive meeting analysis.
+
+Return ONLY valid JSON with the same structure — no markdown fences:
+
+{
+  "summary": "Unified 2-3 paragraph summary of the entire meeting",
+  "chapters": [{ "timestamp": "HH:MM", "title": "...", "description": "..." }],
+  "actionItems": [{ "description": "...", "assignee": "..." }],
+  "keyDecisions": ["..."],
+  "keyQuestions": [{ "question": "...", "status": "answered|unanswered" }]
+}
+
+Guidelines:
+- Combine and deduplicate items across chunks
+- Create a unified summary that flows naturally
+- Merge chapter lists chronologically
+- Deduplicate action items, decisions, and questions
+
+CHUNK ANALYSES:
+${numbered}`;
+}
+
+/**
+ * Prompt for a quick summary (used by the summarize command).
+ */
+export function getQuickSummaryPrompt(transcript: string): string {
+  return `Summarize this meeting transcript in 3-5 paragraphs. Focus on:
+1. What was discussed (main topics)
+2. Key outcomes or decisions
+3. Action items or next steps mentioned
+
+Write in clear, professional prose. Use the speaker names from the transcript.
+
+TRANSCRIPT:
+${transcript}`;
+}

package/src/ai/provider.ts

@@ -0,0 +1,39 @@
+/**
+ * provider.ts — AI provider interface for OpenBuilder
+ *
+ * Clean abstraction layer so adding new AI providers is trivial.
+ * Providers are dynamically imported — the app won't crash if SDKs aren't installed.
+ */
+
+export interface AIMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface AICompletionOptions {
+  messages: AIMessage[];
+  maxTokens?: number;
+  temperature?: number;
+}
+
+export interface AIProvider {
+  /** Human-readable name of this provider (e.g. "Claude", "OpenAI") */
+  readonly name: string;
+
+  /**
+   * Send a chat completion request and return the response text.
+   * Throws if the API key is missing or the request fails.
+   */
+  complete(options: AICompletionOptions): Promise<string>;
+}
+
+/** Error thrown when an AI provider is not available (SDK not installed or no API key). */
+export class AIProviderError extends Error {
+  constructor(
+    public readonly provider: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "AIProviderError";
+  }
+}