recito 0.7.2__tar.gz

recito-0.7.2/.env.example

@@ -0,0 +1,35 @@
+# recito server-backend settings.
+#
+# Used only when synthesizing via a vLLM-Omni server instead of the
+# default in-process engine:
+#
+#     recito speak mybook.pdf --engine vllm-omni
+#
+# Copy this file to .env and edit; real environment variables win over
+# .env values. Only VLLM_OMNI_*-prefixed keys are read from .env — unrelated
+# variables in the file never affect a run. (.env is gitignored; this
+# example file is not.)
+
+# Base URL of the vLLM-Omni OpenAI-compatible server.
+# Default: http://127.0.0.1:44001
+#VLLM_OMNI_URL=http://127.0.0.1:44001
+
+# The server's --served-model-name.
+# Default: qwen3-tts
+#VLLM_OMNI_MODEL=qwen3-tts
+
+# Voice cloning (--voice clone:ref.wav) needs a server serving the Base
+# checkpoint instead — one server serves one checkpoint at a time, so
+# run a second instance and point this file at it, e.g.:
+#VLLM_OMNI_URL=http://127.0.0.1:45001
+#VLLM_OMNI_MODEL=qwen3-tts-base
+
+# Maximum concurrent synthesis requests. The server's own scheduler depth
+# (per-replica max_num_seqs x replica count) is the ceiling; going past it
+# only queues requests client-side.
+# Default: 64 (128 measured fastest on an 8xB200 fleet)
+#VLLM_OMNI_CONCURRENCY=128
+
+# Per-request timeout in seconds.
+# Default: 600
+#VLLM_OMNI_TIMEOUT=600

recito-0.7.2/.gitignore

@@ -0,0 +1,97 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+# lib/  # Commented out - needed for frontend/src/lib
+# lib64/  # Commented out - this was blocking frontend lib files
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+.hypothesis/
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Frontend
+frontend/node_modules/
+frontend/dist/
+frontend/.svelte-kit/
+frontend/build/
+frontend/.env.local
+frontend/.env.*.local
+frontend/npm-debug.log*
+frontend/yarn-debug.log*
+frontend/yarn-error.log*
+
+# Logs
+logs/
+*.log
+
+# Environment files
+.env
+.env.*
+!.env.example
+!deploy/production.env
+
+# Test results
+test_results_*.json
+integration_test_results_*.json
+
+# Temporary files
+*.tmp
+*.temp
+.cache/
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Secrets
+*.pem
+*.key
+*.crt
+*.csr
+
+# OS files
+Thumbs.db
+Desktop.ini
+
+# Backup files
+*.bak
+*.backup
+*~
+
+config.toml.local
+
+_version.py
+
+tmp

recito-0.7.2/.python-version

@@ -0,0 +1 @@
+3.12

recito-0.7.2/AGENTS.md

@@ -0,0 +1,122 @@
+# AGENTS.md
+
+Guidance for coding agents working on recito.
+
+## What this is
+
+recito turns a PDF or EPUB ebook into a chaptered `.m4b` audiobook
+with local, license-clean TTS (Qwen3-TTS, Apache-2.0 weights). Five
+pipeline stages: EXTRACT → CLEAN → CHUNK → SYNTHESIZE → ASSEMBLE.
+Project page: <https://recito.org>; source:
+<https://spacecruft.org/books/recito>. User
+docs: [README.md](README.md) (brief overview; links on it are absolute
+because PyPI renders it), [docs/INSTALL.md](docs/INSTALL.md) (detailed
+install), [docs/USAGE.md](docs/USAGE.md) (the user guide). Architecture,
+design decisions, measured performance: [docs/DEVELOP.md](docs/DEVELOP.md).
+
+## Layout
+
+- `src/recito/` — the package. One module per pipeline stage:
+  `extract.py` (dispatch) + `extract_pdf.py` / `extract_epub.py`,
+  `clean.py` + `textnorm/`, `chunk.py`, `synthesize.py`,
+  `assemble.py`. Plus `models.py` (JSON-round-trippable data model),
+  `config.py` (book.toml), `cover.py`, `main.py` (typer CLI), and
+  `engines/` (TTS adapters behind the protocol in `engines/base.py`;
+  registry in `engines/__init__.py`).
+- `src/recito/textnorm/` — speakability normalization as three
+  phases: `prepare.py` (typography, boundary-neutral) → `segment.py`
+  (sentence boundaries, the one authority; pysbd + data corrections) →
+  `verbalize.py` (one sentence at a time, terminator held aside).
+  `profile.py` holds every per-language fact as a `LanguageProfile`;
+  `backends/own_en.py` is the English token classifier, `backends/basic.py`
+  the digits-only fallback; `overlay.py` + `data/<lang>/*.tsv` +
+  `rules_<lang>.py` are the whitelist layers.
+- `tests/` — pytest suite; synthetic PDF/epub fixtures are built in
+  `tests/conftest.py`. `tests/textnorm/` is one file per normalization
+  phase plus `golden_en.tsv`.
+- `tools/` — dev-only scripts, not shipped: `norm_probe.py`
+  (regenerates `tools/probe/en.txt`, the classifier's readings for the
+  maintainer's audio check), `norm_spike.py` (the NeMo measurement
+  spike; `norm_probe.py` imports its probe rows), `audio_probe.py`
+  (renders the probe readings with the real engine and transcribes
+  them with the take gate's whisper stack — the audio check itself),
+  `delivery_probe.py` (the take gate's replay instrument: re-decodes
+  cached/pending takes through `_Verifier.transcribe` and scores them
+  with the working tree's `_similarity_raw` via its `spans_out`
+  diagnostics — the set gate for gate/verifier rule changes),
+  `common_words.py` (regenerates `data/en/common.tsv`, the common-words
+  table shared by the verifier and prepare's diacritic fold, from the
+  SCOWL-huge US+UK wordlists).
+- `docs/` — INSTALL.md (detailed install), USAGE.md (user guide:
+  voices, cloning, server backend, recipes, per-book config,
+  troubleshooting), DEVELOP.md (internals), TTS.md (TTS engine
+  landscape + license audits), FUTURE.md (planned features),
+  ISSUES.md (known bugs), ALTERNATIVES.md (prior art), REJECT.md
+  (rejected models/licenses), SGLANG.md (SGLang-Omni server-backend evaluation).
+- `vllm/` — vLLM-Omni server deploy files (systemd units, YAML).
+- `sglang/` — SGLang-Omni server deploy files (systemd units, YAML);
+  backend evaluation in docs/SGLANG.md.
+- `tmp/` — gitignored real test corpus. **Never commit ebooks,
+  extracted text, or generated audio.**
+
+## Commands
+
+```
+python3.12 -m venv venv
+venv/bin/pip install -e '.[dev]'
+venv/bin/pytest          # full suite
+venv/bin/ruff check
+venv/bin/ruff format
+```
+
+GPU-less pipeline smoke test (renders sine tones, not speech — the
+`tone` engine exists for exactly this):
+
+```
+recito speak book.pdf -o out.m4b --engine tone
+```
+
+## Hard rules
+
+- **Quality bar:** the goal is the highest-quality output and the best
+  code — no quick fixes, no minimal patches that trade correctness for
+  size. Confirm every claim against the code, docs, tests, or corpus
+  before making it; if a claim can't be confirmed, say so instead of
+  stating it.
+- **License policy:** model weights must be under an OSI-approved
+  license (or public domain). NC/ND/custom-restricted weights are
+  rejected — check [docs/REJECT.md](docs/REJECT.md) before evaluating
+  any model, and add new rejections there. ffmpeg/ffprobe are invoked
+  as external binaries only, never linked.
+- **Chunk-hash contract:** an engine's `generation_params()` must cover
+  everything that changes the audio and nothing that doesn't — chunk
+  ids drive the resume cache across books and runs.
+- **Language is data.** Pipeline code never branches on a language
+  code (`if lang == "en"` is a bug); every per-language fact lives in a
+  `LanguageProfile` (`textnorm/profile.py`) or a `data/<lang>/*.tsv`
+  table. The English classifier and rules apply only to the `en`
+  profile; other profiles use the basic verbalizer until they get their
+  own (docs/FUTURE.md).
+- **Boundary discipline in textnorm.** `prepare` never reads a number
+  or abbreviation; `segment` is the only place a sentence boundary is
+  decided; a verbalizer rule never consults sentence context and must
+  accept the dotless end-of-body form of any abbreviation it anchors on
+  a period (the driver holds the terminator aside). Every table row is
+  asserted with the tail byte-identical and no terminator gained.
+  Normalizer changes are reviewed on the corpus before the expectation
+  tables are re-baselined: `recito extract <book> --workdir DIR`
+  on the unmodified tree and again after the change, then diff the two
+  workdirs (`.txt` for readings, `clean.json` `sentences` for
+  boundaries); every changed paragraph must be explained by the change.
+- **Doc discipline:** new planned work → docs/FUTURE.md; bugs and
+  operational issues → docs/ISSUES.md; rejected models/licenses →
+  docs/REJECT.md; TTS engine evaluations and license audits →
+  docs/TTS.md. Keep README.md user-facing; internals go in
+  docs/DEVELOP.md.
+- Python 3.12, ruff is the linter/formatter (config in pyproject.toml).
+- Tests run on CPU via the `tone` engine; don't add GPU requirements to
+  the test suite.
+- **Never touch `CHANGELOG.txt`** — release notes are maintained by the
+  maintainer.
+- **Never make git commits** (or any other git mutations) — commit and
+  changelog decisions belong to the maintainer.

recito-0.7.2/CHANGELOG.txt

@@ -0,0 +1,24 @@
+v0.7.2    Add build deps.
+v0.7.1    Clearer docs. Prep for pypi.
+v0.7.0    Rename to recito.
+v0.6.10   More fixes, working well despite many quirky source document issues.
+v0.6.9    Yet another 'nother round of bug fixes, lots of text normalization fixes.
+v0.6.8    Yet another round of bug fixes, lots of text normalization fixes.
+v0.6.7    Another round of bug fixes, lots of text normalization fixes.
+v0.6.6    Fix all current known issues/bugs.
+v0.6.5    Endless bug fixes, normalization, overfitting to a few docs.
+v0.6.4    Major text normalization rework. File locking, many bugfixes.
+v0.6.3    Support for cloned voices with vLLM.
+v0.6.2    Fix verifier false positives, speed up, non-blocking.
+v0.6.1    Significant speedups to ffmpeg processing.
+v0.6.0    Support vLLM Omni server. MUCH faster.
+v0.5.2    Add support for epub and other formats.
+v0.5.1    Better metadata. Add cover art.
+v0.5.0    Better doc parsing. Auto output filename. Verify by default.
+v0.4.1    Add feature to use cloned voices. Add developer docs.
+v0.4.0    Multi-GPU support. Confirmed working with 70+ page, 4 hour audio.
+v0.3.0    Initial code implementation.
+v0.2.0    Final plan, ready to code. Updated dependencies.
+v0.1.2    Update plan, future, rejects. License as AGPLv3+.
+v0.1.1    Create plan, evaluate alternatives, reject non-libre.
+v0.1.0    Initial project setup.