get_voice_stats

Instructions

Implementation Reference

• packages/voice/src/contextpulse_voice/mcp_server.py:86-140 (handler)

  Primary implementation of the get_voice_stats tool. Decorated with @mcp_app.tool(), it queries the activity database for voice transcription events within the given hours window and returns dictation count, total audio duration, average duration, correction rate, and LLM cleanup count.

  @mcp_app.tool()
  def get_voice_stats(hours: float = 8.0) -> str:
      """Get voice dictation statistics over the last N hours.
  
      Returns dictation count, total duration, average length, and accuracy info.
  
      Args:
          hours: How many hours back to analyze (default 8).
      """
      hours = max(0.1, min(hours, 168.0))  # cap at 1 week
  
      conn = _get_db()
      if not conn:
          return "No activity database found."
  
      try:
          cutoff = time.time() - (hours * 3600)
          rows = conn.execute(
              "SELECT payload FROM events "
              "WHERE modality = 'voice' AND event_type = 'transcription' "
              "AND timestamp > ?",
              (cutoff,),
          ).fetchall()
          conn.close()
  
          if not rows:
              return f"No dictations in the last {hours:.0f} hours."
  
          total = len(rows)
          total_duration = 0.0
          corrections = 0
          llm_cleanups = 0
  
          for row in rows:
              payload = json.loads(row["payload"])
              total_duration += payload.get("duration_seconds", 0)
              if payload.get("raw_transcript") != payload.get("transcript"):
                  corrections += 1
              if payload.get("cleanup_applied"):
                  llm_cleanups += 1
  
          avg_duration = total_duration / total if total else 0
          correction_rate = corrections / total * 100 if total else 0
  
          lines = [
              f"=== Voice Stats (last {hours:.0f} hours) ===\n",
              f"Total dictations: {total}",
              f"Total audio: {total_duration:.1f}s ({total_duration / 60:.1f} min)",
              f"Average duration: {avg_duration:.1f}s per dictation",
              f"Corrections applied: {corrections}/{total} ({correction_rate:.0f}%)",
              f"LLM cleanups: {llm_cleanups}",
          ]
          return "\n".join(lines)
      except Exception as e:
          return f"Error calculating stats: {e}"

• packages/voice/src/contextpulse_voice/mcp_server.py:86-90 (registration)

  Registration via @mcp_app.tool() decorator. The mcp_app is a FastMCP instance created at line 18 of this same file.

  @mcp_app.tool()
  def get_voice_stats(hours: float = 8.0) -> str:
      """Get voice dictation statistics over the last N hours.
  
      Returns dictation count, total duration, average length, and accuracy info.

• scripts/canary_health_check.py:217-217 (registration)

  Health check registration that imports and invokes get_voice_stats with a minimal hours parameter (0.01) for testing.

  ("voice", "get_voice_stats",            voice.get_voice_stats,            {"hours": 0.01}),

• packages/voice/src/contextpulse_voice/mcp_server.py:23-29 (helper)

  The _get_db() helper used by get_voice_stats to open the shared activity SQLite database.

  def _get_db() -> sqlite3.Connection | None:
      """Open the activity database (shared with Sight/EventBus)."""
      if not _DB_PATH.exists():
          return None
      conn = sqlite3.connect(str(_DB_PATH), timeout=5)
      conn.row_factory = sqlite3.Row
      return conn

• glama/server.py:460-477 (schema)

  Glama registry stub — provides the tool definition/schema for the Glama.ai registry but returns a 'local only' message since this tool is only functional on the user's local machine.

  @mcp_app.tool()
  def get_voice_stats(hours: int = 24) -> str:
      """Return dictation quality stats (WPM, confidence average, correction rate) over a window.
  
      Returns aggregate metrics: words-per-minute, average Whisper confidence,
      correction rate (per get_correction_history), session count.
  
      USE WHEN: the user asks "how is my dictation going" or you're analyzing
      voice quality trends.
      NOT FOR: per-segment data — use get_recent_voice or search_voice.
  
      BEHAVIOR: pure read. Returns zero-valued metrics if no voice activity in
      the window.
  
      PARAMETERS:
        hours: lookback window. Range 1-720 (30d). Default 24.
      """
      return _LOCAL_ONLY_MSG