OpenOats

https://github.com/yazinsai/openoats
Admin
OpenOats is a meeting note-taker app that transcribes conversations in real-time and surfaces...
Tokens:5,704
Snippets:36
Trust Score:9.4
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Build Swift App

Source: https://github.com/yazinsai/openoats/blob/main/README.md

Scripts for building, signing, and installing the Swift application. Includes options for development builds and packaging a DMG. Environment variables are available for code signing and notarization.

```bash
# Full build → sign → install to /Applications
./scripts/build_swift_app.sh

# Dev build only
cd OpenOats && swift build -c debug

# Package DMG
./scripts/make_dmg.sh
```

--------------------------------

### Orchestrate Transcription with TranscriptionEngine

Source: https://context7.com/yazinsai/openoats/llms.txt

The TranscriptionEngine handles dual-stream audio capture and supports multiple backends like Parakeet, Qwen3, and WhisperKit. It provides methods to start, stop, and hot-swap audio devices.

```swift
@Observable
@MainActor
final class TranscriptionEngine {
    var isRunning: Bool
    var assetStatus: String
    var lastError: String?
    var needsModelDownload: Bool

    // Start transcription with configured settings
    func start(
        locale: Locale,
        inputDeviceID: AudioDeviceID = 0,
        transcriptionModel: TranscriptionModel
    ) async {
        // Ensures microphone permission
        // Loads transcription model (downloads if needed)
        // Starts mic and system audio capture
        // Creates streaming transcribers for both channels
    }

    // Gracefully finalize (flush buffers)
    func finalize() async

    // Immediate stop
    func stop()

    // Hot-swap microphone device
    func restartMic(inputDeviceID: AudioDeviceID)
}

// Available transcription models
enum TranscriptionModel: String, CaseIterable {
    case parakeetV2
    case parakeetV3
    case qwen3ASR06B
    case whisperBase
    case whisperSmall

    func makeBackend(customVocabulary: String = "") -> any TranscriptionBackend {
        switch self {
        case .parakeetV2: return ParakeetBackend(version: .v2, customVocabulary: customVocabulary)
        case .parakeetV3: return ParakeetBackend(version: .v3, customVocabulary: customVocabulary)
        case .qwen3ASR06B: return Qwen3Backend()
        case .whisperBase: return WhisperKitBackend(variant: .base)
        case .whisperSmall: return WhisperKitBackend(variant: .small)
        }
    }
}

// Start transcription
await transcriptionEngine.start(
    locale: Locale(identifier: "en-US"),
    inputDeviceID: 0,
    transcriptionModel: .parakeetV2
)
```

--------------------------------

### Implement Contextual Suggestions with SuggestionEngine

Source: https://context7.com/yazinsai/openoats/llms.txt

The SuggestionEngine processes conversation transcripts to generate real-time suggestions. It utilizes a multi-stage pipeline including heuristic filtering, state tracking, KB retrieval, and an LLM-based surfacing gate.

```swift
@Observable
@MainActor
final class SuggestionEngine {
    var suggestions: [Suggestion]
    var isGenerating: Bool
    var lastDecision: SuggestionDecision?

    func onThemUtterance(_ utterance: Utterance) {
        // Pipeline: Filter -> Trigger Detection -> State Update -> KB Retrieval -> Surfacing Gate -> Generation
    }

    func clear()
}

transcriptStore.onNewThemUtterance = { utterance in
    suggestionEngine.onThemUtterance(utterance)
}
```

--------------------------------

### Manage Application Settings with AppSettings

Source: https://context7.com/yazinsai/openoats/llms.txt

The AppSettings class handles user preferences, including LLM providers, embedding configurations, and transcription settings. It supports both local (Ollama) and cloud-based (OpenRouter) backends, with persistence mechanisms for API keys and folder paths.

```swift
@Observable
@MainActor
final class AppSettings {
	var kbFolderPath: String
	var notesFolderPath: String
	var llmProvider: LLMProvider
	var selectedModel: String
	var ollamaBaseURL: String
	var ollamaLLMModel: String
	var mlxBaseURL: String
	var mlxModel: String
	var embeddingProvider: EmbeddingProvider
	var ollamaEmbedModel: String
	var openAIEmbedBaseURL: String
	var openAIEmbedModel: String
	var transcriptionModel: TranscriptionModel
	var transcriptionLocale: String
	var transcriptionCustomVocabulary: String
	var inputDeviceID: AudioDeviceID
	var openRouterApiKey: String
	var voyageApiKey: String
	var openAIEmbedApiKey: String
	var showLiveTranscript: Bool
	var saveAudioRecording: Bool
	var enableTranscriptRefinement: Bool
	var hideFromScreenShare: Bool
	var meetingAutoDetectEnabled: Bool
	var silenceTimeoutMinutes: Int
	var customMeetingAppBundleIDs: [String]
}
```

--------------------------------

### Index and Search Documents with KnowledgeBase

Source: https://context7.com/yazinsai/openoats/llms.txt

The KnowledgeBase class provides methods to index local markdown and text files into vector embeddings. It supports both single and multi-query searches with score fusion to retrieve relevant context from the indexed documents.

```swift
@Observable
@MainActor
final class KnowledgeBase {
    var isIndexed: Bool
    var fileCount: Int
    var indexingProgress: String

    func index(folderURL: URL) async
    func search(query: String, topK: Int = 5) async -> [KBResult]
    func search(queries: [String], topK: Int = 5) async -> [KBResult]
    func clear()
}

let kb = KnowledgeBase(settings: appSettings)
await kb.index(folderURL: URL(fileURLWithPath: "/Users/me/notes"))

let results = await kb.search(
    queries: ["What is the pricing strategy?", "Current pricing discussion", "Revenue model"],
    topK: 5
)
```

--------------------------------

### NotesEngine: Meeting Notes Generation (Swift)

Source: https://context7.com/yazinsai/openoats/llms.txt

Generates structured meeting notes from transcripts using streaming LLM completion. It allows for customizable templates and updates the generated markdown in real-time. Supports cancellation of the generation process.

```swift
@Observable
@MainActor
final class NotesEngine {
    var isGenerating: Bool
    var generatedMarkdown: String
    var error: String?

    // Stream note generation (updates generatedMarkdown in real-time)
    func generate(
        transcript: [SessionRecord],
        template: MeetingTemplate,
        settings: AppSettings
    ) async

    func cancel() {}
}

// Meeting template structure
struct MeetingTemplate: Identifiable, Codable, Sendable, Hashable {
    let id: UUID
    var name: String
    var icon: String           // SF Symbol name
    var systemPrompt: String   // LLM system prompt for formatting
    var isBuiltIn: Bool
}

// Generate notes with a template
let template = MeetingTemplate(
    id: UUID(),
    name: "1:1 Meeting",
    icon: "person.2",
    systemPrompt: """
    You are a meeting notes assistant. Generate structured notes with:
    - Key Discussion Points
    - Action Items (with owners)
    - Decisions Made
    - Follow-up Questions
    Format as clean markdown.
    """,
    isBuiltIn: true
)

let transcript = await sessionStore.loadTranscript(sessionID: sessionID)
await notesEngine.generate(
    transcript: transcript,
    template: template,
    settings: appSettings
)

// Notes appear in notesEngine.generatedMarkdown as they stream

```

--------------------------------

### NotesEngine - Meeting Notes Generation

Source: https://context7.com/yazinsai/openoats/llms.txt

High-level engine for processing meeting transcripts into structured markdown notes using LLM templates.

```APIDOC
## POST /generate-notes

### Description
Processes a transcript into structured markdown notes based on a provided MeetingTemplate.

### Parameters
#### Request Body
- **transcript** (Array) - Required - The session records to process.
- **template** (Object) - Required - The MeetingTemplate containing system prompts.
- **settings** (Object) - Required - Application-wide LLM settings.

### Response
#### Success Response (200)
- **generatedMarkdown** (String) - The resulting structured notes.
```

--------------------------------

### OpenRouterClient - LLM Completion

Source: https://context7.com/yazinsai/openoats/llms.txt

Provides methods for streaming and non-streaming text completion, compatible with OpenAI-style endpoints like OpenRouter and Ollama.

```APIDOC
## POST /chat/completions (OpenRouterClient)

### Description
Generates text completions using LLMs. Supports both standard request/response patterns and asynchronous streaming.

### Method
POST

### Parameters
#### Request Body
- **apiKey** (String) - Optional - Authentication token for the provider.
- **model** (String) - Required - The identifier of the model to use.
- **messages** (Array) - Required - List of message objects with 'role' and 'content'.
- **maxTokens** (Int) - Optional - Maximum tokens to generate.
- **baseURL** (URL) - Optional - Custom endpoint URL for local or self-hosted models.

### Request Example
{
  "model": "google/gemini-3-flash-preview",
  "messages": [{"role": "user", "content": "Summarize this meeting..."}],
  "maxTokens": 512
}

### Response
#### Success Response (200)
- **response** (String) - The generated text content.

#### Response Example
{
  "response": "The meeting focused on..."
}
```

--------------------------------

### OpenRouterClient: LLM API Integration (Swift)

Source: https://context7.com/yazinsai/openoats/llms.txt

Provides streaming and non-streaming completion APIs compatible with OpenRouter, Ollama, and any OpenAI-compatible endpoint. It handles message formatting and API calls for generating text completions.

```swift
actor OpenRouterClient {
    struct Message: Codable, Sendable {
        let role: String    // "system", "user", "assistant"
        let content: String
    }

    // Streaming completion (for notes generation)
    func streamCompletion(
        apiKey: String? = nil,
        model: String,
        messages: [Message],
        maxTokens: Int = 1024,
        baseURL: URL? = nil
    ) -> AsyncThrowingStream<String, Error>

    // Non-streaming completion (for JSON tasks)
    func complete(
        apiKey: String? = nil,
        model: String,
        messages: [Message],
        maxTokens: Int = 512,
        baseURL: URL? = nil
    ) async throws -> String
}

// Using with OpenRouter (cloud)
let client = OpenRouterClient()
let response = try await client.complete(
    apiKey: "sk-or-v1-...",
    model: "google/gemini-3-flash-preview",
    messages: [
        .init(role: "system", content: "You are a helpful assistant."),
        .init(role: "user", content: "Summarize this meeting...")
    ],
    maxTokens: 512
)

// Using with Ollama (local)
let ollamaURL = URL(string: "http://localhost:11434/v1/chat/completions")!
let localResponse = try await client.complete(
    apiKey: nil,
    model: "qwen3:8b",
    messages: messages,
    baseURL: ollamaURL
)

// Streaming for real-time display
let stream = await client.streamCompletion(
    apiKey: apiKey,
    model: "google/gemini-3-flash-preview",
    messages: messages,
    maxTokens: 4096
)
for try await chunk in stream {
    print(chunk, terminator: "")
}
```

--------------------------------

### Capture and Finalize Audio with AudioRecorder

Source: https://context7.com/yazinsai/openoats/llms.txt

The AudioRecorder class handles real-time audio capture from microphone and system sources. It writes buffers to temporary files and provides a finalization method to encode the output into M4A format.

```Swift
final class AudioRecorder: @unchecked Sendable {
    init(outputDirectory: URL)
    func updateDirectory(_ url: URL)
    func startSession()
    func writeMicBuffer(_ buffer: AVAudioPCMBuffer)
    func writeSysBuffer(_ buffer: AVAudioPCMBuffer)
    func finalizeRecording() async
}

let recorder = AudioRecorder(outputDirectory: notesDirectory)
recorder.startSession()
transcriptionEngine.audioRecorder = recorder
await recorder.finalizeRecording()
```

--------------------------------

### Manage Meeting Lifecycle with AppCoordinator

Source: https://context7.com/yazinsai/openoats/llms.txt

The AppCoordinator uses a state machine pattern to manage meeting lifecycles, including recording, stopping, and finalization. It acts as the central hub for transcript storage and session management.

```swift
// AppCoordinator manages meeting state through events
@Observable
@MainActor
final class AppCoordinator {
    var transcriptStore: TranscriptStore
    var transcriptionEngine: TranscriptionEngine?
    var sessionStore: SessionStore

    // Handle meeting lifecycle events
    func handle(_ event: MeetingEvent, settings: AppSettings? = nil) {
        let oldState = state
        state = transition(from: oldState, on: event)
        guard state != oldState else { return }
        performSideEffects(for: event, settings: settings)
    }
}

// Meeting event types
enum MeetingEvent {
    case userStarted(MeetingMetadata)
    case userStopped
    case userDiscarded
    case finalizationComplete
    case finalizationTimeout
}

// State machine states
enum MeetingState {
    case idle
    case recording(MeetingMetadata)
    case stopping
}

// Example: Start a recording session
let metadata = MeetingMetadata(
    detectionContext: nil,
    calendarEvent: nil,
    title: "Weekly Standup",
    startedAt: Date(),
    endedAt: nil
)
coordinator.handle(.userStarted(metadata), settings: appSettings)

// Stop the session and finalize
coordinator.handle(.userStopped)
```

--------------------------------

### VoyageClient - Embeddings and Reranking

Source: https://context7.com/yazinsai/openoats/llms.txt

Interfaces with Voyage AI to generate vector embeddings for text and perform relevance-based reranking of search results.

```APIDOC
## POST /embed

### Description
Converts text into vector embeddings for semantic search or indexing.

### Parameters
#### Request Body
- **apiKey** (String) - Required - Voyage AI API key.
- **texts** (Array) - Required - List of strings to embed.
- **inputType** (String) - Required - 'document' or 'query'.
- **model** (String) - Optional - Embedding model name.

### Response
#### Success Response (200)
- **embeddings** (Array) - A list of float arrays representing the vectors.

---

## POST /rerank

### Description
Scores documents based on their relevance to a specific query.

### Parameters
#### Request Body
- **query** (String) - Required - The search query.
- **documents** (Array) - Required - List of candidate strings.
- **topN** (Int) - Optional - Number of results to return.

### Response
#### Success Response (200)
- **results** (Array) - List of tuples containing index and relevance score.
```

--------------------------------

### Define Transcript and Meeting Data Models

Source: https://context7.com/yazinsai/openoats/llms.txt

Defines the core data structures for meeting interactions. Utterance represents individual transcript entries with support for refinement, while ConversationState tracks the high-level context of a meeting.

```swift
struct Utterance: Identifiable, Codable, Sendable {
	let id: UUID
	let text: String
	let speaker: Speaker
	let timestamp: Date
	let refinedText: String?
	let refinementStatus: RefinementStatus?

	var displayText: String {
		refinedText ?? text
	}
}

struct ConversationState: Sendable, Codable {
	var currentTopic: String
	var shortSummary: String
	var openQuestions: [String]
	var activeTensions: [String]
	var recentDecisions: [String]
	var themGoals: [String]
	var suggestedAnglesRecentlyShown: [String]
	var lastUpdatedAt: Date
}
```

--------------------------------

### Manage Session Transcripts with SessionStore

Source: https://context7.com/yazinsai/openoats/llms.txt

The SessionStore actor manages the lifecycle of session transcripts, including appending records, loading history, and handling notes. It utilizes a SessionRecord struct for JSONL-compatible data persistence.

```Swift
actor SessionStore {
    var currentSessionID: String?

    func startSession(templateID: UUID? = nil)
    func appendRecord(_ record: SessionRecord)
    func appendRecordDelayed(baseRecord: SessionRecord, utteranceID: UUID?, suggestionEngine: SuggestionEngine?, transcriptStore: TranscriptStore?)
    func awaitPendingWrites() async
    func endSession()
    func loadSessionIndex() -> [SessionIndex]
    func loadTranscript(sessionID: String) -> [SessionRecord]
    func loadNotes(sessionID: String) -> EnhancedNotes?
    func saveNotes(sessionID: String, notes: EnhancedNotes)
    func deleteSession(sessionID: String)
    func renameSession(sessionID: String, newTitle: String)
    func moveToRecentlyDeleted(sessionID: String)
}

struct SessionRecord: Codable {
    let speaker: Speaker
    let text: String
    let timestamp: Date
    let suggestions: [String]?
    let kbHits: [String]?
    let suggestionDecision: SuggestionDecision?
    let surfacedSuggestionText: String?
    let conversationStateSummary: String?
    let refinedText: String?
}
```

--------------------------------

### VoyageClient: Embeddings and Reranking (Swift)

Source: https://context7.com/yazinsai/openoats/llms.txt

Interfaces with Voyage AI to generate text embeddings for indexing and search queries, and to rerank search results based on relevance. Requires an API key for authentication.

```swift
actor VoyageClient {
    // Generate embeddings for texts
    func embed(
        apiKey: String,
        texts: [String],
        inputType: String,      // "document" or "query"
        model: String = "voyage-4-lite",
        dimensions: Int = 256
    ) async throws -> [[Float]]

    // Rerank documents by relevance to query
    func rerank(
        apiKey: String,
        query: String,
        documents: [String],
        topN: Int = 5,
        model: String = "rerank-2.5-lite"
    ) async throws -> [(index: Int, score: Double)]
}

// Embed documents for indexing
let client = VoyageClient()
let embeddings = try await client.embed(
    apiKey: "pa-...",
    texts: ["Document 1 content...", "Document 2 content..."],
    inputType: "document"
)

// Embed query for search
let queryEmbedding = try await client.embed(
    apiKey: "pa-...",
    texts: ["What is the pricing model?"],
    inputType: "query"
)

// Rerank search results
let reranked = try await client.rerank(
    apiKey: "pa-...",
    query: "pricing strategy",
    documents: candidateTexts,
    topN: 5
)
for result in reranked {
    print("Document \(result.index): score \(result.score)")
}
```
Tokens:
Raw