Summarization & Chat
Relevant source files
The following files were used as context for generating this wiki page:
- Sources/MacParakeetCore/Services/LLM/LLMService.swift
- Sources/MacParakeetCore/Models/Prompt.swift
- plans/completed/2026-04-prompt-library-multi-summary.md
- plans/completed/2026-02-llm-provider-integration.md
- spec/adr/013-prompt-library-multi-summary.md
- Sources/MacParakeetCore/Resources/community-prompts.json
The Summarization & Chat systems in MacParakeet provide optional, AI-driven post-processing for local transcriptions. While speech recognition (STT) is strictly local to preserve privacy, these features allow users to leverage External LLM Providers for generating structured summaries, action items, and multi-turn chat interactions based on transcript content.
This system is built around a "Prompt Library" architecture, allowing users to apply different instruction sets (e.g., "Meeting Notes" vs. "Action Items") to a single transcript. The integration supports various providers including Anthropic, OpenAI, and local runners like Ollama or LM Studio, ensuring the user maintains control over where their transcript text is processed.
Sources: spec/adr/013-prompt-library-multi-summary.md, README.md:144-160
Architecture & Data Flow
The system follows a layered architecture where the LLM Service acts as the domain operations layer, communicating with an LLM Client that handles OpenAI-compatible API requests. Data is persisted in a local SQLite database, maintaining a one-to-many relationship between a single transcription and multiple summary results.
LLM Integration Flow
The following diagram illustrates the flow from a user request to the external LLM provider and back to the local database.
The system uses Streaming SSE by default to provide incremental UI updates during generation.
Sources: plans/completed/2026-02-llm-provider-integration.md, spec/adr/013-prompt-library-multi-summary.md
Prompt Library
The Prompt Library is the central repository for instruction templates. Prompts are stored in a dedicated SQLite table and categorized by their intended use.
Prompt Data Model
The Prompt struct defines the structure for all templates, whether built-in or custom.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier |
name | String | Display name (e.g., "General Summary") |
content | String | The actual system prompt instructions |
category | Enum | .result (summary) or .transform |
isBuiltIn | Bool | True for templates shipped with the app |
isVisible | Bool | Determines if it appears in selection menus |
isAutoRun | Bool | If true, runs automatically after transcription |
Sources: Sources/MacParakeetCore/Models/Prompt.swift:6-21, plans/completed/2026-04-prompt-library-multi-summary.md
Built-in Templates
MacParakeet includes several high-quality built-in prompts to handle common use cases:
- Summary: A structured summary with key points, decisions, and open questions.
- Action Items & Decisions: Extracts concrete commitments and owners.
- Chapter Breakdown: Segments the transcript into logical topics.
- Study Guide: Transforms transcripts into learning resources with key concepts and review questions.
Sources: Sources/MacParakeetCore/Models/Prompt.swift:145-250, Sources/MacParakeetCore/Resources/community-prompts.json
Summarization Logic
The summarization process allows for Multiple Summaries per Transcript. Instead of overwriting a single field, the system appends new results to a summaries table.
Generation Process
- Prompt Selection: User chooses a template from the library.
- Context Assembly: The
LLMServicecombines the system prompt, transcript text, and optional "extra instructions." - Truncation: If the transcript exceeds the model's context budget (e.g., 100k characters for cloud, 24k for local), the service truncates from the middle to preserve the beginning and end of the audio.
- Snapshots: Each summary stores a snapshot of the
promptContentused. This ensures that if the original library prompt is edited later, the existing summary remains an accurate record of that specific run.
Sources: spec/adr/013-prompt-library-multi-summary.md, plans/completed/2026-02-llm-provider-integration.md
Chat Interaction
The Chat feature allows for multi-turn questions about a transcript. Unlike summaries, chat history is currently in-memory only and scoped to a single viewing session of a transcript.
LLM Provider Support
MacParakeet acts as a "Bring Your Own Key" (BYOK) client. It supports any provider that adheres to the OpenAI-compatible /v1/chat/completions specification.
Supported Integrations
| Provider Type | Examples | Configuration Requirements |
|---|---|---|
| Cloud | Anthropic, OpenAI, Gemini | API Key (Stored in Keychain) |
| Local | Ollama, LM Studio | Base URL (usually localhost) |
| Custom | vLLM, LiteLLM | Custom Base URL + Model Name |
| CLI | Claude Code, Codex | Configured local command |
Sources: README.md:154-165, plans/completed/2026-02-llm-provider-integration.md
Error Taxonomy
The LLMError enum handles failures across various providers to present consistent feedback to the user:
.authenticationFailed: Invalid API Key..rateLimited: Provider-side throttling (HTTP 429)..contextTooLong: Transcript exceeds model limits..modelNotFound: The specified model name is incorrect.
Sources: plans/completed/2026-02-llm-provider-integration.md
Conclusion
The Summarization & Chat features bridge the gap between local privacy and AI utility. By utilizing a local SQLite repository for prompts and results, MacParakeet ensures that while the processing may happen externally, the resulting data is a durable, organized part of the user's local transcription library. The snapshot-based architecture protects the integrity of historical results, while the multi-provider support provides flexibility in choosing between cloud power and local privacy.