@hasna/microservices 0.0.8 → 0.0.10

package/microservices/microservice-transcriber/src/lib/proofread.ts

@@ -0,0 +1,296 @@
+/**
+ * AI-powered non-destructive spellcheck/proofread for transcripts.
+ * Uses OpenAI or Anthropic to find spelling, grammar, punctuation, and clarity issues.
+ * NEVER modifies transcript_text directly — issues are stored in proofread_issues table
+ * and must be explicitly applied one by one.
+ */
+
+import { getTranscript, updateTranscript } from "../db/transcripts.js";
+import {
+  createProofreadIssue,
+  listProofreadIssues,
+  getProofreadIssue,
+  updateIssueStatus,
+  getProofreadStats as getDbProofreadStats,
+  type ProofreadIssue,
+  type IssueType,
+  type IssueStatus,
+  type ListProofreadIssuesOptions,
+  type ProofreadStats,
+} from "../db/proofread.js";
+import { getDefaultSummaryProvider, type SummaryProvider } from "./summarizer.js";
+
+export type { ProofreadIssue, ProofreadStats, IssueType, IssueStatus };
+
+export interface ProofreadOptions {
+  types?: IssueType[];
+  confidence_threshold?: number;
+  provider?: SummaryProvider;
+}
+
+interface RawProofreadIssue {
+  issue_type: string;
+  position_start: number;
+  position_end: number;
+  original_text: string;
+  suggestion: string;
+  confidence: number;
+  explanation: string;
+}
+
+const PROOFREAD_PROMPT = (text: string, types?: IssueType[]) => {
+  const typeFilter = types && types.length > 0
+    ? `Only check for these issue types: ${types.join(", ")}.`
+    : "Check for all issue types: spelling, grammar, punctuation, clarity.";
+
+  return `You are a professional proofreader. Analyze the following transcript text and find all issues.
+
+${typeFilter}
+
+For each issue found, return a JSON object with:
+- "issue_type": one of "spelling", "grammar", "punctuation", "clarity"
+- "position_start": character index where the issue starts in the original text
+- "position_end": character index where the issue ends in the original text
+- "original_text": the exact text that has the issue
+- "suggestion": the corrected text
+- "confidence": a number 0-1 indicating how confident you are this is an issue
+- "explanation": brief explanation of the issue
+
+Return ONLY a valid JSON array of issue objects. If no issues found, return [].
+Do not wrap in markdown code fences.
+
+Transcript text:
+${text.slice(0, 15000)}`;
+};
+
+async function callOpenAI(prompt: string, maxTokens: number): Promise<string> {
+  const apiKey = process.env["OPENAI_API_KEY"];
+  if (!apiKey) throw new Error("OPENAI_API_KEY is not set");
+
+  const res = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: "gpt-4o-mini",
+      messages: [{ role: "user", content: prompt }],
+      max_tokens: maxTokens,
+      temperature: 0.2,
+    }),
+  });
+
+  if (!res.ok) { const body = await res.text(); throw new Error(`OpenAI API error ${res.status}: ${body}`); }
+  const data = (await res.json()) as { choices: Array<{ message: { content: string } }> };
+  return data.choices[0]?.message?.content?.trim() ?? "";
+}
+
+async function callAnthropic(prompt: string, maxTokens: number): Promise<string> {
+  const apiKey = process.env["ANTHROPIC_API_KEY"];
+  if (!apiKey) throw new Error("ANTHROPIC_API_KEY is not set");
+
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: { "x-api-key": apiKey, "anthropic-version": "2023-06-01", "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: "claude-haiku-4-5-20251001",
+      max_tokens: maxTokens,
+      messages: [{ role: "user", content: prompt }],
+    }),
+  });
+
+  if (!res.ok) { const body = await res.text(); throw new Error(`Anthropic API error ${res.status}: ${body}`); }
+  const data = (await res.json()) as { content: Array<{ type: string; text: string }> };
+  return data.content.find((b) => b.type === "text")?.text?.trim() ?? "";
+}
+
+function parseAIResponse(raw: string): RawProofreadIssue[] {
+  const cleaned = raw.replace(/```json\n?/g, "").replace(/```\n?/g, "").trim();
+  try {
+    const parsed = JSON.parse(cleaned);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item: unknown) =>
+        typeof item === "object" &&
+        item !== null &&
+        "issue_type" in item &&
+        "original_text" in item
+    );
+  } catch {
+    return [];
+  }
+}
+
+const VALID_ISSUE_TYPES: Set<string> = new Set(["spelling", "grammar", "punctuation", "clarity"]);
+
+/**
+ * Run AI proofreading on a transcript. Stores issues in DB. Never changes transcript_text.
+ */
+export async function proofreadTranscript(
+  transcriptId: string,
+  options: ProofreadOptions = {}
+): Promise<ProofreadIssue[]> {
+  const transcript = getTranscript(transcriptId);
+  if (!transcript) throw new Error(`Transcript '${transcriptId}' not found.`);
+  if (!transcript.transcript_text) throw new Error(`Transcript '${transcriptId}' has no text.`);
+
+  const provider = options.provider ?? getDefaultSummaryProvider();
+  if (!provider) throw new Error("No AI provider configured. Set OPENAI_API_KEY or ANTHROPIC_API_KEY.");
+
+  const prompt = PROOFREAD_PROMPT(transcript.transcript_text, options.types);
+  const confidenceThreshold = options.confidence_threshold ?? 0.7;
+
+  let raw: string;
+  if (provider === "openai") {
+    raw = await callOpenAI(prompt, 3000);
+  } else {
+    raw = await callAnthropic(prompt, 3000);
+  }
+
+  const rawIssues = parseAIResponse(raw);
+  const created: ProofreadIssue[] = [];
+
+  for (const issue of rawIssues) {
+    // Validate issue_type
+    if (!VALID_ISSUE_TYPES.has(issue.issue_type)) continue;
+
+    // Filter by confidence threshold
+    const confidence = typeof issue.confidence === "number" ? issue.confidence : 0.8;
+    if (confidence < confidenceThreshold) continue;
+
+    // Filter by types if specified
+    if (options.types && options.types.length > 0 && !options.types.includes(issue.issue_type as IssueType)) continue;
+
+    const created_issue = createProofreadIssue({
+      transcript_id: transcriptId,
+      issue_type: issue.issue_type as IssueType,
+      position_start: typeof issue.position_start === "number" ? issue.position_start : undefined,
+      position_end: typeof issue.position_end === "number" ? issue.position_end : undefined,
+      original_text: String(issue.original_text),
+      suggestion: issue.suggestion ? String(issue.suggestion) : undefined,
+      confidence,
+      explanation: issue.explanation ? String(issue.explanation) : undefined,
+    });
+
+    created.push(created_issue);
+  }
+
+  return created;
+}
+
+/**
+ * List proofread issues for a transcript with optional filters.
+ */
+export function listIssues(
+  transcriptId: string,
+  filters?: ListProofreadIssuesOptions
+): ProofreadIssue[] {
+  return listProofreadIssues(transcriptId, filters);
+}
+
+/**
+ * Apply a suggestion: replaces the original_text in transcript_text at the
+ * specified position with the suggestion, and marks the issue as 'applied'.
+ */
+export function applySuggestion(issueId: string): ProofreadIssue | null {
+  const issue = getProofreadIssue(issueId);
+  if (!issue) return null;
+  if (issue.status !== "pending") return issue; // already handled
+
+  if (!issue.suggestion) {
+    // No suggestion to apply, just dismiss
+    return updateIssueStatus(issueId, "dismissed");
+  }
+
+  const transcript = getTranscript(issue.transcript_id);
+  if (!transcript || !transcript.transcript_text) return null;
+
+  let newText: string;
+
+  if (issue.position_start !== null && issue.position_end !== null) {
+    // Apply at exact position if the text at that position matches
+    const textAtPosition = transcript.transcript_text.slice(issue.position_start, issue.position_end);
+    if (textAtPosition === issue.original_text) {
+      newText =
+        transcript.transcript_text.slice(0, issue.position_start) +
+        issue.suggestion +
+        transcript.transcript_text.slice(issue.position_end);
+    } else {
+      // Position mismatch (text may have shifted from prior edits), fall back to first occurrence
+      newText = transcript.transcript_text.replace(issue.original_text, issue.suggestion);
+    }
+  } else {
+    // No position info, replace first occurrence
+    newText = transcript.transcript_text.replace(issue.original_text, issue.suggestion);
+  }
+
+  // Only update if text actually changed
+  if (newText !== transcript.transcript_text) {
+    updateTranscript(issue.transcript_id, { transcript_text: newText });
+  }
+
+  return updateIssueStatus(issueId, "applied");
+}
+
+/**
+ * Dismiss an issue without changing the transcript text.
+ */
+export function dismissIssue(issueId: string): ProofreadIssue | null {
+  const issue = getProofreadIssue(issueId);
+  if (!issue) return null;
+  return updateIssueStatus(issueId, "dismissed");
+}
+
+/**
+ * Get proofread statistics for a transcript.
+ */
+export { getDbProofreadStats as getProofreadStats };
+
+/**
+ * Export annotated transcript text with inline markers showing issues.
+ * Format: [TYPE: "original" -> "suggestion"]
+ */
+export function exportAnnotated(transcriptId: string): string {
+  const transcript = getTranscript(transcriptId);
+  if (!transcript || !transcript.transcript_text) {
+    throw new Error(`Transcript '${transcriptId}' not found or has no text.`);
+  }
+
+  const issues = listProofreadIssues(transcriptId, { status: "pending" });
+  if (issues.length === 0) return transcript.transcript_text;
+
+  // Sort issues by position_start descending so we can safely replace from end to start
+  // without shifting positions. Issues without positions are handled via string replacement.
+  const positionalIssues = issues
+    .filter((i) => i.position_start !== null && i.position_end !== null)
+    .sort((a, b) => (b.position_start ?? 0) - (a.position_start ?? 0));
+
+  const nonPositionalIssues = issues.filter((i) => i.position_start === null || i.position_end === null);
+
+  let text = transcript.transcript_text;
+
+  // Apply positional annotations from end to start
+  for (const issue of positionalIssues) {
+    const start = issue.position_start!;
+    const end = issue.position_end!;
+    const marker = formatMarker(issue);
+    text = text.slice(0, start) + marker + text.slice(end);
+  }
+
+  // Apply non-positional annotations via first occurrence replacement
+  for (const issue of nonPositionalIssues) {
+    const marker = formatMarker(issue);
+    const idx = text.indexOf(issue.original_text);
+    if (idx !== -1) {
+      text = text.slice(0, idx) + marker + text.slice(idx + issue.original_text.length);
+    }
+  }
+
+  return text;
+}
+
+function formatMarker(issue: ProofreadIssue): string {
+  const type = issue.issue_type.toUpperCase();
+  if (issue.suggestion) {
+    return `[${type}: "${issue.original_text}" -> "${issue.suggestion}"]`;
+  }
+  return `[${type}: "${issue.original_text}"]`;
+}

package/microservices/microservice-transcriber/src/mcp/index.ts

@@ -23,7 +23,8 @@ import {
   type TranscriptStatus,
   type TranscriptSourceType,
 } from "../db/transcripts.js";
-import { prepareAudio, detectSourceType, getVideoInfo, downloadAudio, downloadVideo, createClip, isPlaylistUrl, getPlaylistUrls, type TrimOptions } from "../lib/downloader.js";
+import { prepareAudio, detectSourceType, getVideoInfo, downloadAudio, downloadVideo, createClip, isPlaylistUrl, getPlaylistUrls, fetchComments, type TrimOptions } from "../lib/downloader.js";
+import { listComments, getTopComments, searchComments, getCommentStats, importComments } from "../db/comments.js";
 import { getConfig, setConfig, resetConfig } from "../lib/config.js";
 import { summarizeText, extractHighlights, generateMeetingNotes, getDefaultSummaryProvider } from "../lib/summarizer.js";
 import { translateText } from "../lib/translator.js";
@@ -31,6 +32,7 @@ import { fetchFeedEpisodes } from "../lib/feeds.js";
 import { createAnnotation, listAnnotations, deleteAnnotation } from "../db/annotations.js";
 import { wordDiff, diffStats, formatDiff } from "../lib/diff.js";
 import { transcribeFile, checkProviders, toSrt, toVtt, toAss, toMarkdown, segmentByChapters, formatWithConfidence } from "../lib/providers.js";
+import { proofreadTranscript, listIssues, applySuggestion, dismissIssue, getProofreadStats, exportAnnotated, type IssueType } from "../lib/proofread.js";
 
 const server = new McpServer({
   name: "microservice-transcriber",
@@ -63,9 +65,10 @@ server.registerTool(
       diarize: z.boolean().optional().describe("Identify different speakers — ElevenLabs only"),
       vocab: z.array(z.string()).optional().describe("Custom vocabulary hints for accuracy (e.g. ['Karpathy', 'MicroGPT'])"),
       force: z.boolean().optional().describe("Re-transcribe even if URL already exists in DB"),
+      comments: z.boolean().optional().describe("Also fetch and store YouTube/Vimeo comments"),
     },
   },
-  async ({ source, provider = "elevenlabs", language, title, start, end, diarize, vocab, force }) => {
+  async ({ source, provider = "elevenlabs", language, title, start, end, diarize, vocab, force, comments: fetchCommentsFlag }) => {
     // Duplicate detection
     if (!force) {
       const existing = findBySourceUrl(source);
@@ -129,8 +132,33 @@ server.registerTool(
         },
       });
 
+      // Fetch comments if requested
+      let commentCount = 0;
+      if (fetchCommentsFlag && (sourceType === "youtube" || sourceType === "vimeo")) {
+        try {
+          const rawComments = await fetchComments(source);
+          if (rawComments.length > 0) {
+            const mapped = rawComments.map((c) => ({
+              platform: sourceType,
+              author: c.author,
+              author_handle: c.author_id,
+              comment_text: c.text,
+              likes: c.like_count,
+              reply_count: 0,
+              is_reply: c.parent !== null,
+              parent_comment_id: c.parent,
+              published_at: c.timestamp ? new Date(c.timestamp * 1000).toISOString() : null,
+            }));
+            commentCount = importComments(record.id, mapped);
+          }
+        } catch {
+          // Comment fetch is best-effort — don't fail the transcription
+        }
+      }
+
+      const finalResult = { ...getTranscript(record.id), comments_imported: commentCount };
       return {
-        content: [{ type: "text", text: JSON.stringify(updated, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(finalResult, null, 2) }],
       };
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
@@ -943,6 +971,86 @@ server.registerTool(
   }
 );
 
+// ---------------------------------------------------------------------------
+// list_comments
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "list_comments",
+  {
+    title: "List Comments",
+    description: "List comments for a transcript, optionally sorted by likes.",
+    inputSchema: {
+      transcript_id: z.string().describe("Transcript ID"),
+      top: z.boolean().optional().describe("Sort by most liked"),
+      limit: z.number().optional().describe("Max results (default 50)"),
+      offset: z.number().optional().describe("Offset for pagination"),
+    },
+  },
+  async ({ transcript_id, top, limit, offset }) => {
+    const comments = listComments(transcript_id, { top, limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(comments, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// top_comments
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "top_comments",
+  {
+    title: "Top Comments",
+    description: "Get the most liked comments for a transcript.",
+    inputSchema: {
+      transcript_id: z.string().describe("Transcript ID"),
+      limit: z.number().optional().describe("Number of top comments (default 10)"),
+    },
+  },
+  async ({ transcript_id, limit }) => {
+    const comments = getTopComments(transcript_id, limit);
+    return { content: [{ type: "text", text: JSON.stringify(comments, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// search_comments
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "search_comments",
+  {
+    title: "Search Comments",
+    description: "Search comment text across all transcripts using LIKE matching.",
+    inputSchema: {
+      query: z.string().describe("Search query"),
+    },
+  },
+  async ({ query }) => {
+    const results = searchComments(query);
+    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// comment_stats
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "comment_stats",
+  {
+    title: "Comment Stats",
+    description: "Get comment statistics for a transcript: total, replies, unique authors, avg likes, top commenter.",
+    inputSchema: {
+      transcript_id: z.string().describe("Transcript ID"),
+    },
+  },
+  async ({ transcript_id }) => {
+    const stats = getCommentStats(transcript_id);
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
 // ---------------------------------------------------------------------------
 // get_config / set_config
 // ---------------------------------------------------------------------------
@@ -991,6 +1099,142 @@ server.registerTool(
   }
 );
 
+// ---------------------------------------------------------------------------
+// proofread_transcript
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "proofread_transcript",
+  {
+    title: "Proofread Transcript",
+    description: "Run AI-powered spellcheck/proofread on a transcript. Finds spelling, grammar, punctuation, and clarity issues. Non-destructive: stores issues in DB without modifying transcript text.",
+    inputSchema: {
+      id: z.string().describe("Transcript ID"),
+      types: z.array(z.enum(["spelling", "grammar", "punctuation", "clarity"])).optional().describe("Issue types to check (default: all)"),
+      confidence_threshold: z.number().optional().describe("Minimum confidence 0-1 (default: 0.7)"),
+      provider: z.enum(["openai", "anthropic"]).optional().describe("AI provider (auto-detected from env)"),
+    },
+  },
+  async ({ id, types, confidence_threshold, provider }) => {
+    try {
+      const issues = await proofreadTranscript(id, {
+        types: types as IssueType[] | undefined,
+        confidence_threshold,
+        provider: provider as "openai" | "anthropic" | undefined,
+      });
+      return { content: [{ type: "text", text: JSON.stringify(issues, null, 2) }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Proofread failed: ${error instanceof Error ? error.message : error}` }], isError: true };
+    }
+  }
+);
+
+// ---------------------------------------------------------------------------
+// list_proofread_issues
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "list_proofread_issues",
+  {
+    title: "List Proofread Issues",
+    description: "List proofread issues for a transcript with optional filters.",
+    inputSchema: {
+      transcript_id: z.string().describe("Transcript ID"),
+      issue_type: z.enum(["spelling", "grammar", "punctuation", "clarity"]).optional().describe("Filter by issue type"),
+      status: z.enum(["pending", "applied", "dismissed"]).optional().describe("Filter by status"),
+    },
+  },
+  async ({ transcript_id, issue_type, status }) => {
+    const issues = listIssues(transcript_id, {
+      issue_type: issue_type as IssueType | undefined,
+      status: status as "pending" | "applied" | "dismissed" | undefined,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(issues, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// apply_suggestion
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "apply_suggestion",
+  {
+    title: "Apply Proofread Suggestion",
+    description: "Apply a proofread suggestion to the transcript text. Replaces the original text with the suggestion and marks the issue as applied.",
+    inputSchema: {
+      issue_id: z.string().describe("Proofread issue ID"),
+    },
+  },
+  async ({ issue_id }) => {
+    const result = applySuggestion(issue_id);
+    if (!result) return { content: [{ type: "text", text: `Issue '${issue_id}' not found.` }], isError: true };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// dismiss_issue
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "dismiss_issue",
+  {
+    title: "Dismiss Proofread Issue",
+    description: "Dismiss a proofread issue without modifying the transcript text.",
+    inputSchema: {
+      issue_id: z.string().describe("Proofread issue ID"),
+    },
+  },
+  async ({ issue_id }) => {
+    const result = dismissIssue(issue_id);
+    if (!result) return { content: [{ type: "text", text: `Issue '${issue_id}' not found.` }], isError: true };
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// proofread_stats
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "proofread_stats",
+  {
+    title: "Proofread Stats",
+    description: "Get proofread issue statistics for a transcript: total, by type, pending/applied/dismissed counts.",
+    inputSchema: {
+      transcript_id: z.string().describe("Transcript ID"),
+    },
+  },
+  async ({ transcript_id }) => {
+    const stats = getProofreadStats(transcript_id);
+    return { content: [{ type: "text", text: JSON.stringify(stats, null, 2) }] };
+  }
+);
+
+// ---------------------------------------------------------------------------
+// export_annotated
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "export_annotated",
+  {
+    title: "Export Annotated Transcript",
+    description: "Export transcript text with inline proofread annotations showing pending issues as [TYPE: \"original\" -> \"suggestion\"] markers.",
+    inputSchema: {
+      transcript_id: z.string().describe("Transcript ID"),
+    },
+  },
+  async ({ transcript_id }) => {
+    try {
+      const text = exportAnnotated(transcript_id);
+      return { content: [{ type: "text", text }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `Export failed: ${error instanceof Error ? error.message : error}` }], isError: true };
+    }
+  }
+);
+
 // ---------------------------------------------------------------------------
 // search_tools / describe_tools
 // ---------------------------------------------------------------------------
@@ -1021,6 +1265,16 @@ server.registerTool(
       "get_config",
       "set_config",
       "reset_config",
+      "list_comments",
+      "top_comments",
+      "search_comments",
+      "comment_stats",
+      "proofread_transcript",
+      "list_proofread_issues",
+      "apply_suggestion",
+      "dismiss_issue",
+      "proofread_stats",
+      "export_annotated",
       "search_tools",
       "describe_tools",
     ];
@@ -1048,6 +1302,12 @@ server.registerTool(
       export_transcript: "Export as txt/srt/json. Params: id, format?",
       transcript_stats: "Counts by status and provider.",
       check_providers: "Check which API keys are configured.",
+      proofread_transcript: "AI spellcheck/proofread. Params: id, types?, confidence_threshold?, provider?",
+      list_proofread_issues: "List proofread issues. Params: transcript_id, issue_type?, status?",
+      apply_suggestion: "Apply a proofread suggestion. Params: issue_id",
+      dismiss_issue: "Dismiss a proofread issue. Params: issue_id",
+      proofread_stats: "Proofread stats. Params: transcript_id",
+      export_annotated: "Export with inline annotations. Params: transcript_id",
     };
     const result = names.map((n) => `${n}: ${descriptions[n] || "See tool schema"}`).join("\n");
     return { content: [{ type: "text" as const, text: result }] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/microservices",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Mini business apps for AI agents - invoices, contacts, bookkeeping and more, each with its own SQLite database",
   "type": "module",
   "bin": {