Metadata-Version: 2.4
Name: conversa-transcribe
Version: 0.1.0
Summary: Local, evidence-oriented conversation transcription (WhisperX + Anthropic)
Project-URL: Repository, https://github.com/salvagit/conversa
Project-URL: Issues, https://github.com/salvagit/conversa/issues
Author: Salvador
License: MIT
License-File: LICENSE
Keywords: anthropic,claude,cli,evidence,speaker-diarization,speech-to-text,transcription,whisper,whisperx
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Legal Industry
Classifier: Intended Audience :: Other Audience
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.11
Requires-Dist: anthropic<1,>=0.40
Requires-Dist: whisperx<4,>=3.4
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# conversa

Local console tool to transcribe spoken conversations with speaker separation
(WhisperX + diarization) and post-process them with the Anthropic API: filler-word
cleanup, structured summarization, and first-person narrative. Designed for use
with evidentiary value (interviews, evidence): the audio never leaves your
machine; only the text is, optionally, sent to the language model.

> ⚠️ Transcripts are **automatic** and may contain errors. The primary evidence
> is always the recording.

## Requirements

- Python 3.11+
- `ffmpeg` on `PATH` (`brew install ffmpeg`)
- A Hugging Face token with access to
  `pyannote/speaker-diarization-community-1` (accept the terms)
- An Anthropic API key (console.anthropic.com — pay-as-you-go, **different from
  a Claude Pro/Max subscription**)

## Installation

```bash
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .
conversa init          # creates conversa.toml and .env.example
```

Fill in `.env` with `HF_TOKEN` and `ANTHROPIC_API_KEY`.

## Usage

```bash
conversa run audios/                 # full pipeline (transcribe→clean→summarize)
conversa transcribe audios/my.m4a    # WhisperX only
conversa clean audios/               # cleanup only
conversa summarize audios/           # summary only
conversa rename my-audio --map "A=Ana,B=Beto" --to names/
conversa narrate names/my-audio.limpia.md --narrator Ana --brief \
    --context "September 3, 2024. Participants: Ana and Beto."
```

Outputs (in `output_dir`, `transcripciones/` by default): `<base>.md`,
`<base>.srt`, `<base>.limpia.md`, `<base>.resumen.md`.

## Configuration

`conversa.toml` (optional) lets you override models, language, speaker range,
audio extensions, output folder and tokens. Prompts live in
`src/conversa/prompts/*.txt` and can be edited without touching code.

## Language

`conversa` works with any language WhisperX/Whisper supports (~100 languages).
A single `language` setting (ISO 639-1 code, `"es"` by default) drives both
transcription and the LLM stages: `clean`, `summarize` and `narrate` all write
their output in that language.

**This is not auto-detected.** You must set `language` to match your audio;
conversa always tells Whisper which language to expect instead of letting it
guess. Whisper's own auto-detection is disabled on purpose — it's unreliable
on noisy, accented phone-call audio, which is exactly this tool's main use
case, and a wrong guess silently produces a garbled transcript. If you record
audio in English but leave the default `language = "es"`, expect a bad
transcription. Set it in `conversa.toml`:

```toml
[general]
language = "en"   # or "pt", "fr", "de", ...
```

Languages listed in `src/conversa/config.py:LANGUAGE_NAMES` get a friendly name
in the prompt instructions (e.g. "in Spanish"); anything else still works, the
model just sees the raw ISO code instead. The Spanish (`es`) summary headings
are hardcoded for exact, tested wording; other languages get the model's own
translation of the English headings, which reads naturally but isn't pinned
word-for-word.

## Security and privacy

Evidentiary, sensitive material. Keep the data flow in mind:

- **The audio never leaves your machine.** Transcription (WhisperX +
  diarization) runs 100% locally.
- **The text IS sent to the Anthropic API** in the `clean`, `summarize` and
  `narrate` stages. If you need **nothing** to leave the machine, use only
  `conversa transcribe` (raw transcription, no LLM). Review Anthropic's API
  data-retention policy for your case.
- **Secrets:** `HF_TOKEN` and `ANTHROPIC_API_KEY` go in environment variables or
  in `.env` (excluded by `.gitignore`). Prefer environment variables and run the
  tool in trusted directories (a foreign `.env` could inject a different API
  key).
- **Always review the outputs.** Transcription is automatic (ASR errors) and the
  LLM can be influenced by the audio content itself (prompt injection). For
  evidence, the primary proof is the recording; rely on the `.srt` with
  timestamps to cross-check figures and key phrases.

## Next steps

- Provenance manifest (model/version/hash per output) for chain of custody.
- `--local-only` flag / explicit consent before sending text to the LLM.
- Graphical interface for non-technical users.
