Toak/docs/HISTORY_AND_STATS.md

History and Stats Implementation Plan

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

Data Storage

All transcriptions will be stored in a JSON Lines (.jsonl) file located at ~/.local/share/toak/history.jsonl. Since Toak uses Native AOT and JSON serialization needs source generation, we'll keep the model simple.

Entry Model:

{
  "Timestamp": "2025-01-15T09:23:00Z",
  "RawTranscript": "hello world",
  "RefinedText": "Hello world.",
  "SkillName": "Professional",     // null if default type/script
  "DurationMs": 1500               // time taken for STT + LLM
}

toak history Command

Provides access to past dictations.

• toak history - Shows the last 10 entries.
• toak history -n <count> - Shows the last <count> entries.
• toak history --grep <pattern> - Filters the history entries matching the given keyword in the RefinedText (case-insensitive).
• toak history --export <file> - Writes the output as a Markdown file.
• toak history --shred - Deletes the history.jsonl file entirely.

toak stats Command

Reads the history.jsonl file and outputs usage analytics using Spectre.Console.

Metrics:

• Total recording count
• Total processing duration (sum of DurationMs)
• Average processing duration
• Most active day
• Most frequently used skill (if any)

Architecture Changes

1. HistoryManager.cs: Handles thread-safe appending HistoryEntry to the .jsonl file, reading, and clearing.
2. DaemonService.cs: Calls HistoryManager.SaveEntry during the ProcessStopRecordingAsync method after text is finalized.
3. HistoryCommand.cs & StatsCommand.cs: CLI command definitions.
4. AppJsonSerializerContext.cs: Needs [JsonSerializable(typeof(HistoryEntry))].