Skip to content

CLAUDE.md

Latest commit

 

History

History
356 lines (264 loc) · 13.7 KB

CLAUDE.md

File metadata and controls

356 lines (264 loc) · 13.7 KB
Raw

CLAUDE.md - shh Project

This file provides project-specific guidance to Claude Code when working on the shh voice transcription CLI.

For general Python development preferences, see ~/.claude/CLAUDE.md. This project file overrides global preferences where specified.

Project Overview

shh is a voice transcription CLI powered by OpenAI Whisper. It allows users to record audio from their terminal, transcribe it using the Whisper API, and optionally format or translate the output using AI.

Core Features:

  • Record audio from microphone or transcribe existing files
  • Format transcriptions with AI (casual, business, or neutral style)
  • Translate transcriptions to any language
  • Copy results to clipboard automatically
  • Async architecture for responsive UX

Tech Stack: Python 3.11+ • OpenAI Whisper • PydanticAI (gpt-4o-mini) • Typer • Rich • prompt_toolkit (transitive via ipython, used for the history picker) • sounddevice

Architecture

This project follows a Pragmatic Layered Architecture. The CLI calls a thin service layer that orchestrates the recording/transcription/formatting flow.

   CLI (Typer)
   ├─ Output UI:  Rich / Quiet / Pipe (TTY-aware selection)
   └─ History picker (prompt_toolkit, shh history)
              ↓
        Services Layer            RecordingService
              ↓
      ┌───────┴────────┐
    Core            Adapters
  (models,        (audio, whisper,
   styles)         llm, clipboard, history)

Dependency Rule: CLI → Services → (Core + Adapters). Lower layers never import from upper layers. Adapters are framework-agnostic and never import cli/ or services/.

Directory Structure

shh/
├── cli/                    # CLI Layer - Typer commands + UI abstraction
│   ├── app.py             # Typer app entry point (callback pattern, default = record)
│   ├── commands/          # Subcommands: record (default), setup, config, history
│   └── ui/                # UIOutput Protocol + RichUI / QuietUI / PipeUI + history_picker
├── services/               # Orchestration layer
│   └── recording.py       # RecordingService (record + transcribe + format + persist)
├── core/                   # Domain models & enums (no I/O, framework-agnostic)
│   ├── models.py          # RecordingOptions, TranscriptionOutput, HistoryEntry, WhisperTranscription
│   └── styles.py          # TranscriptionStyle enum
├── adapters/               # External Integrations (framework-agnostic)
│   ├── audio/             # sounddevice recording + scipy WAV processing
│   ├── whisper/           # OpenAI Whisper API client (AsyncOpenAI, verbose_json)
│   ├── llm/               # PydanticAI formatting agent (gpt-4o-mini)
│   ├── clipboard/         # pyperclip wrapper
│   └── history/           # JSONL-backed HistoryStore with size-bounded rotation
├── config/                 # Configuration management
│   └── settings.py        # pydantic-settings (env + JSON config file)
└── utils/                  # Shared utilities
    ├── exceptions.py      # Custom exceptions
    └── logger.py          # rich.logging setup

Key Architectural Principles

  1. Async-first: All I/O operations use async/await (Whisper API, LLM calls, recording service).
  2. Type safety: Full type hints + mypy --strict enforcement.
  3. Service layer for orchestration: Record/transcribe/format flow lives in RecordingService, not in a CLI command. Commands stay thin.
  4. Protocol-based UI: Output is abstracted through the UIOutput Protocol (shh/cli/ui/base.py). New UIs (e.g., QuietUI, RichUI) implement the methods structurally — no inheritance required.
  5. Framework-agnostic core/adapters/services: No Typer / Rich imports outside cli/.
  6. Temporary files: Audio recorded to temp WAV, deleted immediately after transcription (try/finally).

Development Commands

Environment Setup

# Create virtual environment and install
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

# Setup API key
shh setup

Running the CLI

# Quick record (press Ctrl+C to stop or enter)
shh

# Record with duration
shh record --duration 60

# Format with style
shh --style business

# Translate
shh --translate fr

# Minimal output (for scripts / piping)
shh --quiet

# Verbose output (overrides quiet_mode config)
shh --verbose

# Skip persisting this transcription to history
shh --no-history

# Browse past transcriptions (interactive picker; Enter = copy, Esc = quit)
shh history

# Purge all history entries (with confirmation)
shh history clear

Testing

Recommended (using Poe):

uv run poe test              # Run all tests
uv run poe test-cov          # Run with coverage
uv run poe test-unit         # Run only unit tests
uv run poe test-integration  # Run only integration tests
uv run poe test-no-e2e       # Skip E2E tests (no real API calls)

Direct pytest commands:

pytest                                               # Run all tests
pytest --cov=shh --cov-report=html --cov-report=term # With coverage
pytest tests/unit/test_formatting.py                 # Specific test file
pytest -m "not e2e"                                  # Excluding E2E tests
pytest -v                                            # Verbose output

Code Quality

This project uses Poe the Poet for task automation. All tasks are run via uv run poe <task>.

# Type checking (strict mode enforced)
uv run poe type              # mypy --strict shh/

# Linting
uv run poe lint              # ruff check .
uv run poe lint-fix          # ruff check . --fix

# Formatting
uv run poe format            # ruff format .

# Combined quality check (before commit)
uv run poe check             # Runs: type + lint + test

# Auto-fix and format
uv run poe fix               # Runs: lint-fix + format

Direct commands (if needed):

mypy --strict shh/
ruff check .
ruff check . --fix

Development Utilities

# Clean cache directories
uv run poe clean

# Install in editable mode
uv pip install -e .

# Install with dev dependencies
uv pip install -e ".[dev]"

Configuration

Config File Location

Platform-specific paths via platformdirs:

  • macOS: ~/Library/Application Support/shh/config.json
  • Linux: ~/.config/shh/config.json
  • Windows: %APPDATA%\shh\config.json

Config Structure

{
  "openai_api_key": "sk-...",
  "default_output": ["clipboard", "stdout"],
  "show_progress": true,
  "default_style": "neutral",
  "default_translation_language": null,
  "quiet_mode": false,
  "whisper_model": "whisper-1",
  "history_enabled": true,
  "history_retention": 200
}

quiet_mode selects QuietUI over RichUI for shh invocations on a TTY. The CLI flags --quiet / --verbose override this field at runtime. When stdout is not a TTY, PipeUI is selected regardless. See shh/config/settings.py for the authoritative schema.

History persists to <config_dir>/history.jsonl next to settings.json. history_retention is the maximum entry count before rotation (rewrite with the most recent N). history_enabled = false disables persistence globally; --no-history skips a single invocation.

Priority Order

  1. CLI flags (highest)
  2. Environment variables (SHH_* prefix)
  3. Config file
  4. Defaults (lowest)

Implementation Patterns

Audio Recording

  • Library: sounddevice for cross-platform recording
  • Format: WAV (16kHz sample rate, optimal for Whisper)
  • Storage: Temporary files only, deleted after transcription
  • Modes: Duration-based (--duration 60) or interactive (Ctrl+C to stop)

Whisper Transcription

  • Client: AsyncOpenAI (from the openai SDK)
  • Adapter: shh/adapters/whisper/client.py — uploads the temp WAV, returns the raw transcript.
  • Model: whisper-1 (configurable via Settings.whisper_model).

PydanticAI Formatting

  • Agent: pydantic_ai.Agent with OpenAIChatModel("gpt-4o-mini") (shh/adapters/llm/formatter.py:103).
  • Styles:
    • neutral: No LLM call unless a target_language is provided — text is returned as-is from Whisper.
    • casual: Conversational tone, removes filler words.
    • business: Formal tone, structured paragraphs.
  • Output: Structured FormattedTranscription Pydantic model.
  • Errors: Wrapped in FormattingError and re-raised at the adapter boundary.

UI Output Layer (Protocol)

  • Defined in shh/cli/ui/base.py. UIOutput is a typing.Protocol — structural typing, no inheritance.
  • Implementations:
    • RichUI — default. A single Live(transient=True) spinner morphs through Recording → Transcribing → [Formatting] and erases on stop. Final output is plain text + dim ✓ copied to clipboard (no Panel).
    • QuietUI — minimal: progress bar + final text.
    • PipeUI — non-TTY: writes only the transcribed text to stdout; errors/warnings to stderr.
  • TTY-aware selection (shh/cli/commands/record.py::_select_ui):
    • not sys.stdout.isatty() → PipeUI (overrides every other flag — pipes always get clean text).
    • --quiet or (Settings.quiet_mode and not --verbose) → QuietUI.
    • Otherwise → RichUI.
  • Adding a new UI: implement every method of UIOutput (show_error, show_recording_progress, show_result, cleanup, …) in a new class — no base class to extend.

Transcription History

  • Store: shh/adapters/history/store.py — HistoryStore(path, retention). JSONL, append-only, size-bounded rotation (keeps last N lines after append). Malformed lines on read are skipped with a logger warning.
  • Model: HistoryEntry in shh/core/models.py (id, ts, text, style, translate_to, duration_s, detected_lang).
  • Persistence: RecordingService appends one entry per successful transcription when settings.history_enabled and not skip_history. OSError on append is logged and swallowed — a successful transcription should never be lost because history failed to persist.
  • --no-history flag on shh / record path threads as skip_history=True through the service.
  • Picker UI: shh/cli/ui/history_picker.py — prompt_toolkit Application with list + preview + footer. Pure helpers (filter_entries, format_relative_time, truncate_text, render_row) are testable in isolation; the interactive layer is not unit-tested.
  • Commands: shh history opens the picker; shh history clear purges with confirmation.

CLI Entry Point Pattern

  • shh/cli/app.py uses Typer's @app.callback(invoke_without_command=True) so that the bare shh command runs the default record flow while still allowing shh setup, shh config, and shh history subcommands.
  • Whisper detected language is extracted via the SDK's verbose_json overload — the response is annotated TranscriptionVerbose and .language is accessed directly (no getattr defensiveness).

Error Handling

  • Philosophy: Fail fast with clear error messages
  • Custom exceptions: Defined in utils/exceptions.py
  • API errors: Translated at adapter boundaries, never leaked to core
  • Cleanup: Temp files deleted in try/finally blocks

Critical Constraints

MUST Do

  1. Full type hints: Every function must have complete type annotations.
  2. Pass mypy strict: mypy --strict shh/ must pass before committing.
  3. Clean up temp files: Use try/finally to ensure WAV files are deleted.
  4. Layer boundaries: CLI → Services → (Core + Adapters). Never the reverse.
  5. Structured outputs: Use Pydantic models for all LLM responses.
  6. Orchestration in services: New record/transcribe/format logic goes in services/, not in a command.

MUST NOT Do

  • Import typer / rich in core/, adapters/, or services/.
  • Import cli/ from services/, core/, or adapters/.
  • Put orchestration logic directly in a Typer command — call RecordingService instead.
  • Leave temp WAV files on disk after transcription.
  • Skip type hints or use Any without justification.
  • Commit code that fails mypy --strict or ruff check.

Adding a New Feature

  1. Plan: Identify which layer owns the logic (CLI / Services / Core / Adapters).
  2. Write tests first: Unit tests for services and adapters, integration tests for end-to-end flows.
  3. Implement: Follow layer boundaries strictly. Orchestration belongs in services/.
  4. Type check: Run uv run poe type.
  5. Lint: Run uv run poe lint (or uv run poe fix to auto-fix).
  6. Test: Run uv run poe test to ensure all tests pass.
  7. Document: Update CLAUDE.md if architectural changes were made.

Before Committing

# Full quality check (type + lint + test)
uv run poe check

# If all pass, you're good to commit
git add .
git commit -m "feat: description"

Alternative (manual commands):

mypy --strict shh/ && ruff check . && pytest

Roadmap Reference

See .roadmap.md for:

  • Detailed architectural decisions
  • Complete implementation checklist
  • Phase-by-phase development plan
  • Open questions and design philosophy

Note: .roadmap.md is gitignored and contains extensive planning details. This CLAUDE.md focuses on practical development guidance.

References