# Agent Guide for pykokoro

This file is for coding agents working in this repository. It summarizes how to build,
test, lint, and follow the project's coding style.

No Cursor or Copilot instruction files were found in this repo.

## Repository layout

- `pykokoro/`: library source
- `tests/`: pytest suite
- `examples/`: runnable demos
- `docs/`: documentation

## Environment setup

- Python: 3.10+ (see `pyproject.toml`)
- Install editable:
  - `uv pip install -e .` (runtime only)

## Test commands

Pytest config lives in `pyproject.toml`.

- Run all tests:
  - `python -m pytest`
- Run a single file:
  - `python -m pytest tests/test_splitter_offsets.py`
- Run a single test:
  - `python -m pytest tests/test_splitter_offsets.py::test_phrasplit_splitter_handles_missing_offsets`
- Run by keyword:
  - `python -m pytest -k "splitter"`
- Skip slow tests:
  - `python -m pytest -m "not slow"`
- Coverage (if `pytest-cov` installed):
  - `python -m pytest --cov=pykokoro --cov-report=term-missing`

## Lint/format/type-check commands

Ruff and mypy are configured in `pyproject.toml`. Pre-commit is configured in
`.pre-commit-config.yaml`.

- Ruff lint:
  - `ruff check .`
- Ruff autofix (safe fixes):
  - `ruff check . --fix`
- Mypy:
  - `mypy pykokoro`
- pre-commit:
  - `pre-commit run --all-files`

There is no dedicated formatter configured; follow existing style and Ruff line-length
(100).

## Code style guidelines

### Imports

- Use `from __future__ import annotations` at the top of new Python modules.
- Order imports: standard library, third-party, local.
- Prefer explicit imports over wildcard.
- Use `typing.TYPE_CHECKING` to avoid heavy optional imports at runtime.

### Formatting

- Max line length: 100 (see Ruff).
- Use f-strings for interpolation.
- Prefer double quotes for strings (matches existing files).
- Keep small helpers near usage; larger helpers at module bottom.

### Types

- Use type hints on public functions/classes and key internal helpers.
- Use `dataclasses` for simple data containers.
- Use `| None` and `list[str]` style annotations (Python 3.10+).
- Follow mypy config: incomplete defs disallowed, but fully untyped defs are allowed
  when integration with third-party libs makes typing noisy.

### Naming conventions

- `snake_case` for functions/variables.
- `PascalCase` for classes.
- `ALL_CAPS` for constants.
- Use descriptive names that map to pipeline stages (doc/segment/g2p/synth).

### Error handling and warnings

- Raise clear exceptions when required dependencies are missing.
- Prefer `Trace.warnings` for recoverable runtime issues.
- Log via module-level `logger = logging.getLogger(__name__)`.
- Avoid swallowing exceptions; catch narrowly and emit context.

### Logging

- Use `logger.debug/info/warning` rather than `print` in library code.
- Examples may print directly for clarity.
- Debug flags are commonly via env vars (e.g. `PYKOKORO_DEBUG_SEGMENTS`).

### Segmentation and offsets

- Segment offsets should always refer to `doc.clean_text`.
- `Segment.text` should match `clean_text[char_start:char_end]`.
- Keep segments monotonic and non-overlapping.

### Pipeline conventions

- Stages follow the order: doc parse (includes segmentation) -> g2p -> synth.
- `PipelineConfig` and `GenerationConfig` are immutable dataclasses; use
  `dataclasses.replace` when overriding.
- New stages should match `pykokoro/stages/base.py` protocols.

### Tests

- Use pytest functions prefixed with `test_`.
- Keep tests deterministic; avoid network or model downloads where possible.
- Prefer targeted unit tests in `tests/` over new integration tests.
- Use fixtures from `tests/conftest.py` when available.

## Files to be careful with

- `pykokoro/_version.py` is generated by setuptools_scm.
- Large binary artifacts (e.g., WAVs) should not be added without need.
- Keep docs concise; prefer README for user-facing updates.

## Common workflows

- Update a document parser/segmentation or g2p behavior:

  - Adjust stage in `pykokoro/stages/...`
  - Add or update regression tests in `tests/`
  - Run `python -m pytest tests/<file>.py`

- Add a new example:
  - Add script under `examples/`
  - Keep it runnable from repo root
  - Avoid hardcoding large assets

## Notes for agentic changes

- Keep changes scoped; avoid touching unrelated files.
- Avoid modifying generated or downloaded artifacts.
- Align new code with existing conventions (type hints, dataclasses, logging).
