tranpro 0.1.0a1__tar.gz

tranpro-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to tranpro are documented here. Versions follow
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.0a1 - 2026-11-02
+
+First public alpha.
+
+### Added
+
+- One-shot local transcription with Parakeet MLX on Apple Silicon.
+- Animated terminal progress and optional live timestamped output.
+- A persistent SQLite transcript library with immutable transcript runs.
+- Recording fingerprinting, reuse, full-text search, and recording-ID input.
+- Timestamped Markdown output and recoverable source-file trashing.
+- Provider boundaries for Parakeet MLX and whisper.cpp.
+
+### Deferred
+
+- Summarization and saved prompt templates.
+- Hosted OpenAI providers.
+- Google Docs publishing.
+- Speaker diarization.

tranpro-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Barmby
+
+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.

tranpro-0.1.0a1/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+recursive-include docs *.md

tranpro-0.1.0a1/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: tranpro
+Version: 0.1.0a1
+Summary: A local-first transcript library and one-shot transcription CLI
+Author: Will Barmby
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/WillBarmby/transcriber/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/WillBarmby/transcriber
+Project-URL: Issues, https://github.com/WillBarmby/transcriber/issues
+Project-URL: Repository, https://github.com/WillBarmby/transcriber.git
+Keywords: audio,cli,summarization,transcription
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: parakeet-mlx<0.7,>=0.6; sys_platform == "darwin" and platform_machine == "arm64"
+Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: rich<16,>=13.8
+Requires-Dist: Send2Trash<2,>=1.8
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == "dev"
+Requires-Dist: mypy<2,>=1.14; extra == "dev"
+Requires-Dist: pytest<10,>=8.3; extra == "dev"
+Requires-Dist: ruff<1,>=0.9; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Requires-Dist: types-Send2Trash<2,>=1.8; extra == "dev"
+Dynamic: license-file
+
+# tranpro
+
+`tranpro` is becoming a local-first transcript library with a straightforward
+one-shot command-line workflow:
+
+```text
+audio -> durable transcript -> optional summary -> optional Google Doc
+```
+
+The Python distribution and import package are named `tranpro`; the command is
+the shorter `tp`.
+
+The current release provides local transcription and the persistent transcript
+library. Summarization and Google Docs publication remain roadmap milestones.
+
+## Installation
+
+tranpro currently targets Python 3.11 or newer on Apple Silicon Macs. Install
+the CLI and its local Parakeet backend with one command:
+
+```shell
+python3 -m pip install tranpro
+tp --version
+tp recording.m4a
+```
+
+The first transcription downloads the model from Hugging Face and caches it for
+later runs. Parakeet MLX is installed automatically only on Apple Silicon;
+other platforms receive the portable CLI and database without that dependency.
+
+This is an alpha release: the transcript database is designed to persist, but
+commands and configuration may still change before 1.0.
+
+## Current commands
+
+After installation:
+
+```shell
+tp --help
+tp --version
+tp recording.m4a
+tp recording.m4a --output -
+tp recording.m4a --no-save
+tp recording.m4a --retranscribe
+tp 2 --retranscribe
+tp recording.m4a --retranscribe --live
+tp recording.m4a --no-progress
+tp recording.m4a --trash-source
+tp paths
+tp config show
+tp config init
+tp config edit
+tp library init
+tp library status
+tp list
+tp show RECORDING_ID
+tp search "budget constraints"
+tp forget RECORDING_ID
+tp restore RECORDING_ID
+```
+
+Library commands use an embedded SQLite database with automatic schema
+migrations and pre-migration backups. `forget` is a recoverable soft deletion:
+it does not remove source audio, transcripts, or summaries. Full-text search uses
+SQLite FTS5 across timestamped transcript segments and summary sections. See the
+[database design](docs/DATABASE.md) for identity, versioning, and safety details.
+
+Transcription is the default operation. The equivalent explicit form is also
+available:
+
+```shell
+tp recording.m4a
+tp transcribe recording.m4a
+```
+
+By default, tranpro saves a versioned library record and writes
+`recording.transcript.md` beside the source. `--output -` prints Markdown to
+stdout, while `--no-save` skips SQLite. Existing equivalent runs are reused;
+`--retranscribe` creates another immutable version. `--trash-source`/`-d` moves
+the source to the operating-system Trash only after output succeeds.
+Parakeet's `--live` mode prints finalized timestamped sentences as they become
+available while retaining the complete saved library and Markdown outputs.
+Interactive terminals show an animated progress bar by default. `--no-progress`
+disables it; redirected and non-interactive output disables it automatically.
+
+See the [transcription guide](docs/TRANSCRIPTION.md) and
+[roadmap](docs/ROADMAP.md).
+
+## Development setup
+
+tranpro requires Python 3.11 or newer. From a clone:
+
+```shell
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+tp --version
+```
+
+On Apple Silicon, the normal installation includes Parakeet MLX. Its model
+downloads to the Hugging Face cache on first use.
+
+Run the same checks used in continuous integration:
+
+```shell
+ruff check .
+ruff format --check .
+mypy src/tranpro
+pytest
+python -m build
+twine check dist/*
+```
+
+Maintainers can find the tagged-release process in
+[docs/RELEASING.md](docs/RELEASING.md).
+
+The first supported local runtime target is macOS on Apple Silicon. The core,
+database, and hosted-provider abstractions are intended to remain portable;
+Linux and Windows are best-effort until they are tested in CI and on real hosts.
+
+## Project principles
+
+- Local and free by default; hosted providers are explicit opt-ins.
+- Transcription is the default action; summarization is explicit.
+- SQLite is the source of truth. Markdown and Google Docs are rendered outputs.
+- Provider boundaries keep model selection out of the core workflow.
+- Source media is never deleted permanently by a normal command.
+- No server, account system, or telemetry is required.
+
+## License
+
+[MIT](LICENSE)

tranpro-0.1.0a1/README.md

@@ -0,0 +1,133 @@
+# tranpro
+
+`tranpro` is becoming a local-first transcript library with a straightforward
+one-shot command-line workflow:
+
+```text
+audio -> durable transcript -> optional summary -> optional Google Doc
+```
+
+The Python distribution and import package are named `tranpro`; the command is
+the shorter `tp`.
+
+The current release provides local transcription and the persistent transcript
+library. Summarization and Google Docs publication remain roadmap milestones.
+
+## Installation
+
+tranpro currently targets Python 3.11 or newer on Apple Silicon Macs. Install
+the CLI and its local Parakeet backend with one command:
+
+```shell
+python3 -m pip install tranpro
+tp --version
+tp recording.m4a
+```
+
+The first transcription downloads the model from Hugging Face and caches it for
+later runs. Parakeet MLX is installed automatically only on Apple Silicon;
+other platforms receive the portable CLI and database without that dependency.
+
+This is an alpha release: the transcript database is designed to persist, but
+commands and configuration may still change before 1.0.
+
+## Current commands
+
+After installation:
+
+```shell
+tp --help
+tp --version
+tp recording.m4a
+tp recording.m4a --output -
+tp recording.m4a --no-save
+tp recording.m4a --retranscribe
+tp 2 --retranscribe
+tp recording.m4a --retranscribe --live
+tp recording.m4a --no-progress
+tp recording.m4a --trash-source
+tp paths
+tp config show
+tp config init
+tp config edit
+tp library init
+tp library status
+tp list
+tp show RECORDING_ID
+tp search "budget constraints"
+tp forget RECORDING_ID
+tp restore RECORDING_ID
+```
+
+Library commands use an embedded SQLite database with automatic schema
+migrations and pre-migration backups. `forget` is a recoverable soft deletion:
+it does not remove source audio, transcripts, or summaries. Full-text search uses
+SQLite FTS5 across timestamped transcript segments and summary sections. See the
+[database design](docs/DATABASE.md) for identity, versioning, and safety details.
+
+Transcription is the default operation. The equivalent explicit form is also
+available:
+
+```shell
+tp recording.m4a
+tp transcribe recording.m4a
+```
+
+By default, tranpro saves a versioned library record and writes
+`recording.transcript.md` beside the source. `--output -` prints Markdown to
+stdout, while `--no-save` skips SQLite. Existing equivalent runs are reused;
+`--retranscribe` creates another immutable version. `--trash-source`/`-d` moves
+the source to the operating-system Trash only after output succeeds.
+Parakeet's `--live` mode prints finalized timestamped sentences as they become
+available while retaining the complete saved library and Markdown outputs.
+Interactive terminals show an animated progress bar by default. `--no-progress`
+disables it; redirected and non-interactive output disables it automatically.
+
+See the [transcription guide](docs/TRANSCRIPTION.md) and
+[roadmap](docs/ROADMAP.md).
+
+## Development setup
+
+tranpro requires Python 3.11 or newer. From a clone:
+
+```shell
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev]'
+tp --version
+```
+
+On Apple Silicon, the normal installation includes Parakeet MLX. Its model
+downloads to the Hugging Face cache on first use.
+
+Run the same checks used in continuous integration:
+
+```shell
+ruff check .
+ruff format --check .
+mypy src/tranpro
+pytest
+python -m build
+twine check dist/*
+```
+
+Maintainers can find the tagged-release process in
+[docs/RELEASING.md](docs/RELEASING.md).
+
+The first supported local runtime target is macOS on Apple Silicon. The core,
+database, and hosted-provider abstractions are intended to remain portable;
+Linux and Windows are best-effort until they are tested in CI and on real hosts.
+
+## Project principles
+
+- Local and free by default; hosted providers are explicit opt-ins.
+- Transcription is the default action; summarization is explicit.
+- SQLite is the source of truth. Markdown and Google Docs are rendered outputs.
+- Provider boundaries keep model selection out of the core workflow.
+- Source media is never deleted permanently by a normal command.
+- No server, account system, or telemetry is required.
+
+## License
+
+[MIT](LICENSE)

tranpro-0.1.0a1/docs/ARCHITECTURE.md

@@ -0,0 +1,98 @@
+# Architecture
+
+## Product boundary
+
+tranpro is a local command-line application and library, not a hosted service.
+It owns metadata, transcripts, summaries, prompts, and publication records in an
+embedded SQLite database. Audio stays outside the database and is identified by
+a streaming content fingerprint.
+
+SQLite is canonical. Markdown files and Google Docs are projections that can be
+recreated from stored artifacts.
+
+## Dependency direction
+
+The finished backend will follow these boundaries:
+
+```text
+CLI -> application workflows -> domain models
+                    |                 ^
+                    v                 |
+        provider/repository ports ----+
+                    ^
+                    |
+       SQLite, Parakeet, Ollama, OpenAI, Google adapters
+```
+
+- **Domain models** describe recordings, timestamped transcript segments,
+  transcript runs, prompt versions, summaries, and publications. They do not
+  import a model SDK, Typer, or SQLite.
+- **Application workflows** implement use cases such as transcribe, summarize,
+  search, publish, forget, and restore.
+- **Ports** define the capabilities workflows need: transcription,
+  summarization, persistence, rendering, and publication.
+- **Adapters** contain provider-specific APIs and filesystem/database details.
+- **CLI** translates user intent into workflow calls and renders results.
+
+Provider model names belong in profiles, not workflow code. A workflow receives
+a selected provider through a registry and consumes normalized domain objects.
+
+## Application data
+
+On macOS, `platformdirs` resolves the application state to:
+
+```text
+~/Library/Application Support/tranpro/
+├── config.toml
+├── library.sqlite3
+└── backups/
+
+~/Library/Caches/tranpro/
+```
+
+User-facing Markdown remains beside the source audio unless `--output` says
+otherwise. Provider-managed model caches remain provider-managed. OAuth secrets
+will be stored in the operating-system keychain rather than SQLite or TOML.
+
+The database will use explicit, ordered schema migrations. Before a migration,
+tranpro will make a timestamped SQLite backup. Records are soft-deleted by
+default. A normal delete flag moves source media to the operating-system Trash
+only after every requested output succeeds.
+
+## Versioned artifacts
+
+A recording is stable identity; processing results are immutable runs:
+
+```text
+Recording
+├── Transcript run 1 (provider, model, settings)
+│   ├── Summary run 1 (prompt version, model, settings)
+│   └── Summary run 2
+└── Transcript run 2
+```
+
+A repeated fingerprint plus equivalent transcription settings may reuse a
+successful transcript. Retranscription creates a run instead of overwriting
+history. Summaries always point to the exact transcript and prompt versions used.
+
+## Context planning
+
+Summary providers expose their effective runtime context budget. Before a call,
+the planner accounts for the system contract, rendered prompt, transcript,
+reserved output, and a safety margin. Whole-transcript summarization is preferred
+when it fits. Otherwise the planner creates coherent timestamped sections,
+summarizes each under the same user instructions, and synthesizes the section
+notes. The calculation and intermediate artifacts are persisted for auditability.
+
+Summary evidence refers to stable transcript segment IDs. Renderers turn those
+IDs into timestamps and links after validation, so models never invent display
+timestamps.
+
+## Explicit non-goals for version 1
+
+- A server, web UI, accounts, or telemetry
+- Folder watching
+- Storing audio blobs in SQLite
+- Two-way Google Docs synchronization
+- A separate vector database
+- Permanent deletion as a convenience flag

tranpro-0.1.0a1/docs/DATABASE.md

@@ -0,0 +1,62 @@
+# Transcript library
+
+tranpro uses one application-owned SQLite database as the canonical record of
+processing history. The source audio remains an external file; the database
+stores its path, metadata, and a streaming SHA-256 content fingerprint.
+
+## Identity and versions
+
+```text
+recordings
+├── transcript_runs
+│   ├── transcript_segments
+│   └── summary_runs
+│       └── summary_sections
+└── publication records (planned)
+```
+
+A recording is identified by audio content rather than filename. Registering the
+same bytes at another path returns the existing recording. A different provider,
+model, or explicit retranscription creates another transcript run instead of
+overwriting an earlier result.
+
+Transcript segments receive stable references such as `s000001`. Summary
+sections preserve the segment references used as evidence, allowing renderers to
+add grounded timestamps later without asking a language model to invent them.
+
+## Schema changes and backups
+
+The SQLite `user_version` pragma records the current ordered migration. Before
+tranpro modifies an existing older schema, it creates a consistent backup using
+SQLite's online backup API:
+
+```text
+~/Library/Application Support/tranpro/backups/
+└── library-20261102T030405006789Z-v0.sqlite3
+```
+
+The database carries a tranpro application identifier. Migration refuses a file
+marked as another application's database, an unmarked database containing
+unknown tables, or a schema newer than the installed tranpro version. These
+checks turn likely path mistakes and downgrade attempts into explicit errors.
+
+## Search
+
+SQLite FTS5 indexes transcript segment text, speaker names, summary headings, and
+summary bodies. Search results retain the recording, artifact version, stable
+segment or section location, and transcript start time. Normal search excludes
+soft-deleted recordings; `--all` includes them.
+
+FTS is intentionally lexical in this milestone. The future semantic index will
+be derived from versioned transcript passages and combined with FTS results; it
+will not replace canonical transcript storage.
+
+## Deletion semantics
+
+`tp forget ID` timestamps the recording as deleted. It does not remove database
+rows or touch source and output files. `tp restore ID` reverses that state. A
+future permanent-purge operation will be separate, explicit, and confirmed.
+
+The later `--trash-source` transcription option will use the operating-system
+Trash only after all requested outputs succeed. That is independent of forgetting
+a library record.

tranpro-0.1.0a1/docs/RELEASING.md

@@ -0,0 +1,55 @@
+# Releasing tranpro
+
+Releases are built by GitHub Actions from the repository and published with
+PyPI Trusted Publishing. No long-lived PyPI token belongs in GitHub secrets.
+
+## One-time setup
+
+Create pending Trusted Publishers on PyPI and TestPyPI with these values:
+
+| Setting | Value |
+| --- | --- |
+| PyPI project | `tranpro` |
+| GitHub owner | `WillBarmby` |
+| Repository | `transcriber` |
+| Workflow | `release.yml` |
+| Environment | `pypi` on PyPI; `testpypi` on TestPyPI |
+
+Create matching `pypi` and `testpypi` environments in the GitHub repository.
+The environments may require approval if an extra release confirmation is
+desired.
+
+## Rehearse on TestPyPI
+
+1. Update the version in `pyproject.toml` and the entry in `CHANGELOG.md`.
+2. Merge the release preparation pull request into `main`.
+3. Run the **Release** workflow manually from the `main` branch.
+4. Inspect the TestPyPI project and download its wheel artifact.
+
+The manual workflow publishes only to TestPyPI. Re-running the same version is
+safe: an already uploaded file is skipped.
+
+## Publish to PyPI
+
+After the TestPyPI rehearsal succeeds, tag the exact tested commit and push the
+tag:
+
+```shell
+git switch main
+git pull --ff-only
+git tag v0.1.0a1
+git push origin v0.1.0a1
+```
+
+A `v*` tag makes the workflow rebuild the distributions, verify a clean wheel
+installation, publish to PyPI, and create a GitHub release containing the wheel
+and source distribution. The tag version must match the package version without
+the leading `v`.
+
+Finally, verify the public installation in a fresh virtual environment:
+
+```shell
+python3 -m venv /tmp/tranpro-release-check
+/tmp/tranpro-release-check/bin/python -m pip install tranpro
+/tmp/tranpro-release-check/bin/tp --version
+```

tranpro-0.1.0a1/docs/ROADMAP.md

@@ -0,0 +1,72 @@
+# Roadmap
+
+Work is intentionally divided into reviewable pull requests. Each pull request
+must install independently, keep the command usable, and include tests for its
+behavior.
+
+## 1. Application foundation
+
+- Package `tranpro` with the `tp` console command
+- Establish platform-native paths and versioned TOML configuration
+- Document architecture, support policy, and project vision
+- Add linting, typing, tests, build validation, and CI
+
+## 2. Transcript library
+
+- SQLite migrations and pre-migration backups
+- Recording fingerprints and versioned artifact records
+- Stable transcript segment representation
+- Soft delete, restore, list, show, and FTS5 search
+
+## 3. Local transcription
+
+- Parakeet MLX as the Apple Silicon default
+- Accelerated whisper.cpp fallback
+- Provider/model selection through profiles
+- Deduplication, `--retranscribe`, Markdown output, and `--no-save`
+- Trash source media only after successful completion
+- Retire the legacy watcher/archive pipeline
+
+## 4. Public alpha distribution
+
+- Publish `tranpro` to PyPI with the `tp` console command
+- Verify wheel installation in a clean environment
+- Rehearse on TestPyPI and publish through short-lived trusted credentials
+- Attach built distributions to a tagged GitHub release
+
+## 5. Summaries and prompts
+
+- Ollama with Gemma 4 12B as the local default
+- Built-in detailed-notes preset and versioned user prompts
+- Explicit `--summarize` and standalone summarize commands
+- Context feasibility planning and hierarchical fallback
+- Grounded segment references and Markdown rendering
+
+## 6. OpenAI profile
+
+- Hosted transcription with `gpt-transcribe`
+- Hosted summaries with `gpt-6.1-terra`
+- Usage and estimated-cost records
+- Mocked provider tests; no network calls in the test suite
+
+## 7. Google Docs publication
+
+- Bring-your-own desktop OAuth credentials and Keychain token storage
+- Polished native Google Docs styles
+- Immutable publication snapshots, reuse, and explicit updates
+- Transcript-only and transcript-plus-summary publication
+
+## 8. Release polish
+
+- Optional fzf-based interactive browsing
+- Doctor/setup commands and shell completion
+- Clean-environment wheel and source-distribution installation checks
+- Migration notes and TestPyPI release rehearsal
+
+Semantic search is a planned extension after the core library stabilizes. Its
+passage index will be versioned and derived from canonical transcript segments so
+it can coexist with SQLite FTS without changing recording identity.
+
+Speaker diarization is also planned as an optional second pass over timestamped
+segments. It will remain provider-independent so local diarizers can be compared
+without coupling speaker labels to the transcription model.