conversa-transcribe 0.1.0__tar.gz

conversa_transcribe-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC), no secrets
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

conversa_transcribe-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      # whisperx (torch) isn't needed for these tests: conversa.asr imports it
+      # lazily inside Transcriber.__init__, not at module load time.
+      - name: Install (skip heavy ASR deps)
+        run: |
+          python -m pip install --upgrade pip
+          pip install anthropic pytest
+          pip install -e . --no-deps
+      - run: pytest

conversa_transcribe-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.venv-*/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Secrets
+.env
+
+# Generated outputs
+transcripciones/
+relatos*/
+
+# Source recordings — never commit sensitive audio
+*.m4a
+*.mp3
+*.wav
+*.mp4
+*.ogg
+*.flac
+*.zip
+
+# OS
+.DS_Store

conversa_transcribe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salvador
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

conversa_transcribe-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+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.

conversa_transcribe-0.1.0/README.md

@@ -0,0 +1,102 @@
+# 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.

conversa_transcribe-0.1.0/conversa.example.toml

@@ -0,0 +1,29 @@
+# Example conversa configuration. Copy it to `conversa.toml` in the directory
+# from which you run the tool (or generate it with `conversa init`).
+# All keys are optional; anything omitted falls back to the code defaults.
+
+[general]
+# ISO 639-1 code. Drives both the Whisper ASR model and the language the LLM
+# stages (clean/summarize/narrate) write their output in. Must match your
+# audio's actual language — Whisper's auto-detection is intentionally
+# disabled (unreliable on noisy call audio), so a mismatch silently produces
+# a garbled transcript. Any language Whisper supports works; see
+# src/conversa/config.py:LANGUAGE_NAMES for the ones with a friendly display
+# name (others still work, just less polished prompts).
+language = "es"
+
+[asr]
+model = "large-v3-turbo"        # large-v3-turbo | medium | small
+min_speakers = 2
+max_speakers = 3
+threads = 8
+
+[io]
+output_dir = "transcripciones"
+audio_exts = [".m4a", ".mp3", ".wav", ".mp4", ".ogg", ".flac"]
+
+[llm]
+clean_model = "claude-haiku-4-5"
+summary_model = "claude-sonnet-5"
+narrate_model = "claude-sonnet-5"
+chunk_chars = 8000

conversa_transcribe-0.1.0/plans/visibility-license-topics-pypi.md

@@ -0,0 +1,108 @@
+# Plan — Visibilidad: LICENSE, topics de GitHub, publicación en PyPI
+
+_Fecha: 2026-07-07_
+
+## Contexto
+
+`conversa` es público en `github.com/salvagit/conversa` pero invisible: sin
+licencia, sin topics, y solo instalable clonando el repo. "SEO" tradicional
+no aplica a una herramienta de consola — la visibilidad acá se juega en
+señales que entiende GitHub (licencia, topics, CI) y en estar donde la gente
+instala paquetes (PyPI). Se prioriza esto sobre otras acciones (badges, demo,
+awesome-lists, redes) que se evalúan después.
+
+## Hallazgo bloqueante: nombre en PyPI
+
+El nombre **`conversa` ya está tomado** en PyPI (paquete no relacionado, de
+conversión de unidades). Verificado libres: `conversa-cli`,
+`conversa-transcribe`, `conversa-evidence`.
+
+Esto **no afecta al usuario final**: `[project.scripts]` define el comando
+`conversa` de forma independiente del nombre de distribución (`[project]
+name`). Cambiar el nombre de distribución para PyPI no cambia que el comando
+siga siendo `conversa` una vez instalado.
+
+## Decisiones (ya tomadas por el usuario, 2026-07-07)
+
+1. **Nombre de distribución en PyPI: `conversa-transcribe`.** El comando que
+   escribe el usuario final sigue siendo `conversa` (no cambia).
+2. **Cuenta de PyPI: no existe todavía, hay que crearla.** Bloquea solo el
+   paso 3.4 (configurar Trusted Publisher); el resto del código se prepara
+   igual sin necesitar la cuenta.
+3. **Método de publicación: Trusted Publisher** (OIDC de GitHub Actions →
+   PyPI), sin tokens ni secrets. Evita repetir el problema de la API key de
+   Anthropic compartida en texto plano.
+
+## Fase 1 — LICENSE (sin dependencias, se puede hacer ya)
+
+- Agregar `LICENSE` en la raíz del repo: texto MIT estándar, copyright
+  "Salvador", año 2026 (coincide con `pyproject.toml: license = {text="MIT"}`).
+- Verificar que GitHub detecta la licencia (aparece en la barra lateral del repo).
+
+## Fase 2 — Topics de GitHub (sin dependencias, se puede hacer ya)
+
+- `gh repo edit salvagit/conversa --add-topic <topic>` para cada uno:
+  `cli`, `transcription`, `speech-to-text`, `whisper`, `whisperx`,
+  `speaker-diarization`, `anthropic`, `claude`, `legal-tech`, `evidence`,
+  `python`.
+- Verificar con `gh repo view --json repositoryTopics`.
+
+## Fase 3 — Publicación en PyPI (requiere decisiones del usuario arriba)
+
+3.1. **Metadata de `pyproject.toml`** para descubribilidad en PyPI:
+   - Cambiar `[project] name` al nombre de distribución elegido (el
+     `[project.scripts] conversa = ...` NO cambia).
+   - Agregar `keywords` (transcription, whisper, diarization, evidence, cli,
+     spanish, anthropic, claude).
+   - Agregar `classifiers` (Development Status, Intended Audience, License ::
+     OSI Approved :: MIT, Programming Language :: Python :: 3.11/3.12,
+     Topic :: Multimedia :: Sound/Audio :: Speech, Environment :: Console).
+   - Agregar `[project.urls]` (Repository, Issues) apuntando a
+     `github.com/salvagit/conversa`.
+
+3.2. **CI mínimo** (`.github/workflows/test.yml`): correr `pytest` en cada
+   push/PR. Barato (ya hay 22 tests livianos, sin whisperx) y da una señal de
+   confianza real (badge verde) para cualquiera que llegue al repo.
+
+3.3. **Workflow de publicación** (`.github/workflows/publish.yml`): build con
+   `python -m build`, publish vía `pypa/gh-action-pypi-publish` usando Trusted
+   Publisher (sin secrets), disparado por tags `v*.*.*`.
+
+3.4. **Configurar Trusted Publisher en pypi.org** (acción manual del usuario:
+   crear cuenta si no existe, ir a "Publishing" → agregar repo
+   `salvagit/conversa`, workflow `publish.yml`, environment opcional).
+
+3.5. **Primer release**: tag `v0.1.0` → dispara el workflow → publica en PyPI.
+   Verificar `pip install <nombre-elegido>` funciona en un venv limpio y expone
+   el comando `conversa`.
+
+3.6. Actualizar `README.md`: instrucciones de instalación pasan a
+   `pip install <nombre-elegido>` como opción principal, con "desde código
+   fuente" como alternativa para desarrollo.
+
+## Estado (2026-07-07)
+
+- ✅ Fase 1 (LICENSE), Fase 2 (topics), Fase 3.1-3.3 (metadata, CI, workflow de
+  publicación) hechas, commiteadas (`8adc173`) y pusheadas. CI corrido y
+  **verde en GitHub** (no solo local).
+- 🐛 Encontrado y arreglado en el camino: `python -m build` fallaba
+  (`force-include` de prompts duplicaba archivos). No lo detectaba
+  `pip install -e .` porque usa un code path distinto. Verificado con un
+  build real + instalación del wheel en venv limpio: `conversa --version`
+  y los prompts cargan bien.
+- ⏳ Pendiente, bloqueado por acción del usuario: 3.4 (cuenta de PyPI +
+  Trusted Publisher) y 3.5/3.6 (primer release + actualizar README).
+
+## Verificación
+
+- `LICENSE` presente y detectado por GitHub.
+- Topics visibles en `gh repo view --json repositoryTopics`.
+- CI verde en un push de prueba.
+- `pip install <nombre-elegido>` en un venv limpio (o Docker) instala y
+  `conversa --version` funciona.
+- README refleja el nuevo método de instalación.
+
+## Fuera de alcance (para después)
+
+Badges en el README, GIF de demo, listas "awesome-*", publicación en foros/redes
+(Show HN, Reddit, etc.) — se retoman una vez esto esté andando.

conversa_transcribe-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "conversa-transcribe"
+version = "0.1.0"
+description = "Local, evidence-oriented conversation transcription (WhisperX + Anthropic)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Salvador" }]
+keywords = [
+    "transcription", "whisper", "whisperx", "speaker-diarization",
+    "speech-to-text", "evidence", "cli", "anthropic", "claude",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Legal Industry",
+    "Intended Audience :: Other Audience",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "whisperx>=3.4,<4",
+    "anthropic>=0.40,<1",
+]
+
+[project.urls]
+Repository = "https://github.com/salvagit/conversa"
+Issues = "https://github.com/salvagit/conversa/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+conversa = "conversa.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/conversa"]

conversa_transcribe-0.1.0/src/conversa/__init__.py

@@ -0,0 +1,3 @@
+"""conversa — local, evidence-oriented conversation transcription toolkit."""
+
+__version__ = "0.1.0"