pocket-tts: Instructions file for Codex

AGENTS.md

This file provides guidance to AI agents when working with code in this repository.

Project Overview

pocket-tts is a CPU-based text-to-speech (TTS) model. The project uses a flow-based language model architecture with a neural audio codec (Mimi) for efficient speech synthesis.

Key Architecture Components:

• FlowLMModel: Transformer-based flow language model that generates latent representations from text using Lagrangian Self Distillation (LSD)
• MimiModel: Neural audio codec (from the moshi package) that compresses/decompresses audio to/from latent representations
• Conditioners: Text processing via SentencePiece tokenizer and lookup table embeddings
• Streaming Architecture: The entire pipeline supports streaming generation via stateful modules
• Web API: FastAPI-based server for HTTP API access with web interface

Common Commands

Setup and Development

# Install pre-commit hooks
uvx pre-commit install

# Run tests (3 parallel workers)
uv run pytest -n 3 -v

# Run a single test
uv run pytest tests/test_python_api.py -v

# Run CLI locally (editable install)
uv run pocket-tts generate
uv run pocket-tts serve

Linting and Formatting

Pre-commit handles this automatically, but you can run manually:

# Ruff will run automatically on commit via pre-commit
# Includes: ruff-check, ruff-format (with --fix), and import sorting

Building (No Build Step)

This is a pure Python package with Rust extensions in training/rust_exts/audio_ds/ for training-time audio processing. The main package does not require building.

Code Structure

Main Package (pocket_tts/)

Entry Points:

• main.py: CLI implementation with Typer (commands: generate, serve, and web interface)
• __init__.py: Public API exports only TTSModel
• __main__.py: Python module entry point
• default_parameters.py: Default configuration values for generation parameters
• static/: Web interface files (HTML for server UI)