# Instructions to LLM Agents

This is a Python project designed to be run in a separate virtual environment with Python version >=3.11 nad its main objective is to convert any epub file without DRM to an audiobook with text-to-speech tools available on Github, Hugging Face or publicy available.

You may search for new tools to use, as long as they are kept as a separate package, preferrably as a git submodule under `./src/vendor/<repository-name>` and creating an interface inside `./src/epub_tts/<package-name>.py` to call the package in its own virtual environment, using python's builtin `subprocess.call()` or `subprocess.run()`.

If you add such a new tool, include a new item to the `backend` dictionary inside `./src/epub_tts/main.py`.

## Attribution
- For every python file created, add the following 4 lines to its top and follow it with your attribution string, authorship and then with a short docstring describing the file's purpose.
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Copyright (c) 2025-2026 Renato Xavier da Silveira Rosa
# See [LICENSE](./LICENSE) or [BSD-3-Clause-Clear](https://spdx.org/licenses/BSD-3-Clause-Clear.html)
```

## Package source code
- This project is called `epub-tts` and it is a Python>=3.11 package available under the folder [src/epub_tts](./src/epub_tts)
- Parse metadata inside [pyproject.toml](./pyproject.toml), including coding style configuration for `ruff`
- The subfolders under [src/vendor](./src/vendor) are external packages required for this project

## Dev environment tips
- Use `pip install '.[dev]'` to install package in editable mode with optional dependencies.

## PR instructions
- Title format: `[epub-tts] <Title>`
- Always run `ruff check --fix ./src/epub_tts` and `ruff format ./src/epub_tts` before committing.
- Write clear commit messages stating a general description of changes.
- Do not change any version or git tags, because they are handled automaticaly by `setuptools-scm`

## Operating Model
- Ask quick clarifying questions if versions, entry points, or expected behaviors are ambiguous.
- Prefer small, incremental changes with brief plans for multi-step work.
- Do not commit secrets, especially .env files or any TOKENS, APITOKENS, APIKEYS or KEYS in general;
- avoid committing large build artifacts unless requested.


## Typical Tasks
- Implement features, fix bugs, run tests, and update docs as requested by the user.
- Keep the environment reproducible and synced with the declared requirements.