Toak/docs/HISTORY_AND_STATS.md

History and Stats

This document outlines the design and implementation of the history and stats features in Toak.

Data Storage

All transcriptions are stored in a JSON Lines (.jsonl) file.

• Location: ~/.local/share/toak/history.jsonl

Entry Model:

{
  "Timestamp": "2025-01-15T09:23:00Z",
  "RawTranscript": "hello world",
  "RefinedText": "Hello world.",
  "SkillName": "Professional",     // null if default
  "DurationMs": 1500               // total processing time
}

toak history Command

The CLI provides access to past dictations:

• toak history: Shows the last 10 entries.
• -n <count>: Shows the last <count> entries.
• --grep <pattern>: Case-insensitive search through refined text.
• --export <file>: Export history as a Markdown file.
• --shred: Securely delete the entire history.jsonl file.

toak stats Command

Aggregates usage metrics from the history file:

• Total recordings: Count of all entries.
• Total duration: Cumulative time spent transcribing (in minutes).
• Average latency: Mean processing time per request (in seconds).
• Most active day: Date with the highest number of recordings.
• Top spoken words: The 5 most frequent words (>3 characters).

Architecture

1. HistoryManager.cs: Handles thread-safe appending and reading of the .jsonl file.
2. TranscriptionOrchestrator.cs: Calls HistoryManager.SaveEntry after text is finalized.
3. HistoryCommand.cs & StatsCommand.cs: CLI command implementations.
4. AppJsonSerializerContext.cs: Provides AOT-compatible serialization for HistoryEntry.