feat: prepare to publish to pypi (#7)

Author: gitcommitshow

.env.example

@@ -1,7 +1,7 @@
 # Copy to .env and fill in values (optional for many runs):
 #   cp .env.example .env
 #
-# On startup, `orchestrator.main` loads `.env` automatically (python-dotenv).
+# On startup, `resilient-stt` loads `.env` automatically (python-dotenv).
 # Variables already set in your shell are not overwritten.
 
 # --- Shortest full pipeline (OpenAI ASR + repair) ---
@@ -15,7 +15,7 @@
 # ASR_BASE_URL=https://openrouter.ai/api/v1
 # ASR_API_KEY=sk-or-...
 #
-#   uv run python -m orchestrator.main --audio path/to/audio.mp3 --output data/output/run
+#   resilient-stt --audio path/to/audio.mp3 --output data/output/run
 #
 # Local ASR is preferred when available. Hosted ASR auto-detection requires:
 # no --model, no ASR_BASE_URL/ASR_ENDPOINT, and no reachable local worker.

.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "Tag v$TAG does not match pyproject.toml version $VERSION"
+            exit 1
+          fi
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/release-please.yml

@@ -0,0 +1,18 @@
+# Opens/updates a Release PR on main; merging it creates vX.Y.Z and triggers publish.yml.
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.3.2"
+}

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+Release versions and notes are managed by [release-please](https://github.com/googleapis/release-please)
+from [Conventional Commits](https://www.conventionalcommits.org/) on `main`.
+
+## [0.3.2](https://github.com/gitcommitshow/resilient-stt/releases/tag/v0.3.2) (2026-05-25)
+
+### Features
+
+* PyPI packaging (`src/resilient_stt` layout), bundled qwen worker, and tag-based publish workflow

MANIFEST.in

@@ -0,0 +1,4 @@
+graft src
+prune tests
+prune scripts
+global-exclude *.egg-info

README.md

@@ -1,12 +1,51 @@
-# Resilient STT (Speech-To-Text)
+# Resilient STT
 
-A local speech transcription pipeline for English, Hindi, and Hinglish audio.  
-The orchestrator owns chunking, diarization, repair, and exports; ASR inference is **externalized** behind an OpenAI-compatible `/v1/audio/transcriptions` endpoint that you choose (vLLM, hosted APIs including OpenAI and Open Router API, faster-whisper wrapper, Parakeet wrapper, etc.).
+**The only Speech-To-Text pipeline you need.**
+
+A provider-agnostic speech-to-text pipeline that plugs into **any OpenAI-compatible ASR endpoint** — OpenAI, OpenRouter, vLLM, faster-whisper, or the bundled Qwen worker — and returns rich, timestamped transcripts with speaker labels and validated metadata. Resilient STT handles everything around inference: audio preprocessing, voice-activity detection, intelligent chunking, pyannote diarization, and LLM-powered transcript repair. Tested on English, Hindi, and Hinglish but it is designed to support all the languages the ASR model of your choice supports.
+
+## Features
+
+- **Any ASR provider** — Point at any service that implements `POST /v1/audio/transcriptions` (or OpenRouter STT); swap models with flags, not code changes.
+- **Resilient ASR discovery** — Auto-detects local workers and hosted APIs, retries failed requests, and starts a bundled Qwen fallback when nothing else is reachable.
+- **Audio preprocessing** — ffmpeg normalization to mono 16 kHz WAV with optional enhancement before transcription.
+- **Voice activity detection** — Silero, webrtcvad, or RMS fallback to skip silence and focus compute on speech.
+- **Smart chunking & stitching** — Fixed or pause-aligned chunks for long files, with global word and segment timestamps stitched back together.
+- **Speaker diarization** — pyannote on the full audio, with word-level speaker assignment (IoU + segment fallback).
+- **LLM transcript repair** — Optional two-pass repair via any OpenAI-compatible chat endpoint, with validation to preserve timing and mixed-script Hinglish.
+- **Rich exports** — JSON, SRT, and VTT with segments, words, speakers, and pipeline metadata.
+- **Lightweight orchestrator** — No ASR model weights in the core package; inference stays in the microservice you choose.
+- **CLI and Python API** — `resilient-stt` from the terminal, or `pipeline.run(JobConfig)` for programmatic use.
 
 > **Experimental:** This project is under active development and is **not production-ready**. Expect breaking changes, incomplete features, and behavior that may shift between releases. Use for evaluation and prototyping only.
 
 **Architecture & design decisions:** [docs/design.md](docs/design.md)
 
+**CLI reference:** [docs/cli.md](docs/cli.md)
+
+## Repository layout
+
+```text
+resilient-stt/
+  src/resilient_stt/          # installable package (PyPI name: resilient-stt)
+    orchestrator/             # CLI, pipeline, ASR discovery
+    core/                     # audio, VAD, chunking, schemas, exports
+    asr/                      # OpenAI-compatible ASR client, fallback worker
+    diarization/              # pyannote + speaker assignment
+    alignment/                # optional aligner (stubs in v1)
+    repair/                   # LLM transcript repair
+    workers/                  # bundled qwen-asr HTTP service (shipped in wheel)
+  workers/                    # docs for optional ASR workers (vLLM, Whisper, …)
+  scripts/                    # bootstrap helpers (not installed from PyPI)
+  tests/
+  docs/
+  data/                       # input / work / output (local runs)
+```
+
+- **PyPI / pip:** `pip install resilient-stt` → CLI command **`resilient-stt`** (hyphen).
+- **Python imports:** `resilient_stt` (underscore), e.g. `from resilient_stt.orchestrator.pipeline import run`.
+- **From source:** `uv sync` then `uv run resilient-stt …` (or activate `.venv` and run `resilient-stt`).
+
 ## Architecture
 
 ```
@@ -87,7 +126,7 @@ The orchestrator sends 16 kHz mono WAV chunks.
 
 | Worker | Endpoint (default) | Example `--model` | Status |
 | ------ | ------------------ | ----------------- | ------ |
-| [qwen_transformers_service](workers/qwen_transformers_service/README.md) | `http://127.0.0.1:8002/v1` | `Qwen/Qwen3-ASR-0.6B` | **Bundled** — auto-started when no other ASR is reachable |
+| [qwen_transformers_service](src/resilient_stt/workers/qwen_transformers_service/README.md) | `http://127.0.0.1:8002/v1` | `Qwen/Qwen3-ASR-0.6B` | **Bundled** — auto-started when no other ASR is reachable |
 | [qwen_vllm_service](workers/qwen_vllm_service/README.md) | `http://127.0.0.1:8001/v1` | `Qwen/Qwen3-ASR-1.7B` | **Bundled bootstrap** — Linux + NVIDIA GPU |
 | Custom (faster-whisper, vLLM, hosted proxy, etc.) | Your URL | Your model id | **Supported** — implement or deploy separately |
 | [whisper_openai_service](workers/whisper_openai_service/README.md) | — | — | **Planned Roadmap** |
@@ -121,13 +160,74 @@ Any OpenAI-compatible **`/chat/completions`** endpoint. Set `REPAIR_BASE_URL`,
 
 | Component | Status |
 | --------- | ------ |
-| Qwen forced aligner (`alignment/qwen_aligner.py`) | **Planned Roadmap** |
+| Qwen forced aligner (`src/resilient_stt/alignment/qwen_aligner.py`) | **Planned Roadmap** |
 | WhisperX | **Planned Roadmap** |
 
 Today, alignment runs only when `--align` is set or ASR returned weak
 timestamps; the default aligner is a no-op pass-through.
 
-## Install (uv)
+## Install (PyPI)
+
+Prerequisites: **Python 3.11 or 3.12**, **ffmpeg** on PATH.
+
+```bash
+# Minimal orchestrator (webrtcvad VAD; ASR via API or bundled qwen worker)
+pip install resilient-stt
+
+# Recommended on Apple Silicon / Linux (Silero VAD + pyannote diarization + torch)
+pip install "resilient-stt[full]"
+
+# Contributors
+pip install "resilient-stt[full,dev]"
+```
+
+Verify the CLI:
+
+```bash
+resilient-stt --help
+```
+
+### Usage after `pip install`
+
+Run from any directory (creates `data/work/` under the current working dir unless you pass `--work-root`):
+
+```bash
+resilient-stt \
+  --audio /path/to/audio.wav \
+  --output /path/to/output-dir \
+  --language hi
+```
+
+With diarization and Silero VAD you need the `[full]` extra and usually `HF_TOKEN` in `.env` (see [Environment variables](#environment-variables)). Quick smoke test without pyannote:
+
+```bash
+resilient-stt \
+  --audio /path/to/audio.wav \
+  --output /path/to/output-dir \
+  --language hi \
+  --skip-diarization \
+  --repair false
+```
+
+Hosted ASR (no local qwen worker) — set `OPENAI_API_KEY` or `OPENROUTER_API_KEY` in `.env`:
+
+```bash
+resilient-stt \
+  --audio /path/to/audio.wav \
+  --output /path/to/output-dir \
+  --no-asr-fallback \
+  --skip-diarization
+```
+
+**Bundled qwen-asr worker:** On first auto-start, the CLI creates an isolated venv at
+`~/.cache/resilient-stt/qwen-transformers-worker/.venv` (requires network to download
+`qwen-asr` and model weights). If inference fails on Apple Silicon, start the worker
+manually with `python scripts/bootstrap_qwen_asr_fallback.py --no-aligner` (from a git
+checkout) or see the [bundled worker README](src/resilient_stt/workers/qwen_transformers_service/README.md).
+
+Platform notes for `[full]` match [Platform notes (torch / diarization)](#platform-notes-torch--diarization) below (Intel Mac: base install + `--skip-diarization`).
+
+## Install from source (uv)
 
 Prerequisites: [uv](https://docs.astral.sh/uv/), **ffmpeg** on PATH. ASR is optional to
 configure manually — see [ASR auto-detection](#asr-auto-detection) below.
@@ -192,19 +292,21 @@ uv run python -c "import torch; print('mps', torch.backends.mps.is_available())"
 
 ## Usage
 
+From a **git checkout**, prefix commands with `uv run` (or activate `.venv` and use `resilient-stt` directly). After **`pip install`**, use `resilient-stt` only.
+
 Minimal run (no ASR setup — auto-starts local **qwen-asr** on CPU/MPS when needed):
 
 ```bash
-uv run python -m orchestrator.main \
+uv run resilient-stt \
   --audio data/input/meeting.mp3 \
   --output data/output/meeting \
   --language hi
 ```
 
-With an external ASR service (vLLM, hosted API, etc.):
+With an external ASR service (vLLM, hosted API, etc.) — the endpoint must already be running and respond to `GET {base}/v1/models`:
 
 ```bash
-uv run python -m orchestrator.main \
+uv run resilient-stt \
   --audio data/input/meeting.mp3 \
   --asr-endpoint http://localhost:8001/v1 \
   --model Qwen/Qwen3-ASR-1.7B \
@@ -218,14 +320,14 @@ auto-detect (no local ASR on `:8001`/`:8002`) or point at the API explicitly:
 
 ```bash
 # Auto-detect when no local ASR is running (--no-asr-fallback avoids starting qwen-asr)
-uv run python -m orchestrator.main \
+uv run resilient-stt \
   --audio data/input/speech.wav \
   --output data/output/openai \
   --no-asr-fallback \
   --skip-diarization
 
 # Explicit endpoint
-uv run python -m orchestrator.main \
+uv run resilient-stt \
   --audio data/input/speech.wav \
   --output data/output/openai \
   --asr-endpoint https://api.openai.com/v1 \
@@ -237,7 +339,7 @@ uv run python -m orchestrator.main \
 the key via `ASR_API_KEY`:
 
 ```bash
-uv run python -m orchestrator.main \
+uv run resilient-stt \
   --audio data/input/speech.wav \
   --output data/output/openrouter/chirp \
   --asr-endpoint https://openrouter.ai/api/v1 \
@@ -257,10 +359,12 @@ When `--asr-endpoint` is omitted (and `ASR_BASE_URL` / `ASR_ENDPOINT` are unset)
 2. Probe an existing **qwen-asr** worker at `http://127.0.0.1:8002/v1`
 3. **OpenRouter** when `OPENROUTER_API_KEY` is set (no `--model`)
 4. **OpenAI** when `OPENAI_API_KEY` is set (no `--model`)
-5. Otherwise **start** the local qwen-asr fallback ([workers/qwen_transformers_service/README.md](workers/qwen_transformers_service/README.md)) — slow on CPU/MPS but needs no NVIDIA GPU
+5. Otherwise **start** the local qwen-asr fallback ([bundled worker](src/resilient_stt/workers/qwen_transformers_service/README.md)) — slow on CPU/MPS but needs no NVIDIA GPU
 
 Use `--no-asr-fallback` to require an explicit or already-running ASR service.
 
+If you pass `--asr-endpoint` explicitly, that URL must respond to `GET …/v1/models` before the pipeline runs (otherwise the CLI exits with “endpoint configured but unreachable”).
+
 Useful flags:
 
 
@@ -340,13 +444,29 @@ Final exports land under `--output`: `transcript.json`, `transcript.srt`,
 
 ## Tests
 
+From source:
+
 ```bash
+uv sync --extra dev
 uv run pytest
 ```
 
+After `pip install "resilient-stt[dev]"` from a checkout (with `src/` on `PYTHONPATH`) or when developing in the repo, the same `pytest` command applies if `src` is configured in `pyproject.toml` (`pythonpath = ["src"]`).
+
 The included tests use synthetic fixtures and mocked HTTP responses; they do
 not invoke ffmpeg, pyannote, or any LLM.
 
+## Publishing (maintainers)
+
+1. **Commits on `main`** — use [Conventional Commits](https://www.conventionalcommits.org/) in PR titles or squash messages (`feat:`, `fix:`, `chore:`, etc.).
+2. **release-please** (`.github/workflows/release-please.yml`) — opens/updates a **Release PR** that bumps `pyproject.toml`, `CHANGELOG.md`, and `.release-please-manifest.json`.
+3. **Ship** — merge the Release PR; release-please creates GitHub Release + tag `vX.Y.Z`.
+4. **PyPI** (`.github/workflows/publish.yml`) — runs on that tag when it matches `version` in `pyproject.toml`.
+
+One-time: configure a [PyPI trusted publisher](https://docs.pypi.org/trusted-publishers/) for workflow `publish.yml` on repo `gitcommitshow/resilient-stt`. In the org/repo settings, allow GitHub Actions to create and approve pull requests if Release PRs do not appear.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## License
 
 This project is licensed under the [GNU General Public License v3.0 or

conftest.py

@@ -1,12 +1,5 @@
-"""Make repo root importable so `import core` etc. works in tests without install."""
+"""Pytest hooks: disable third-party telemetry before any tests run."""
 
-import sys
-from pathlib import Path
-
-_ROOT = Path(__file__).resolve().parent
-if str(_ROOT) not in sys.path:
-    sys.path.insert(0, str(_ROOT))
-
-from core.privacy import disable_dependency_telemetry  # noqa: E402
+from resilient_stt.core.privacy import disable_dependency_telemetry
 
 disable_dependency_telemetry()