# Contributing

Thank you for helping improve Reachy OpenWebUI.

This repository is an OpenWebUI-native Reachy Mini app. Keep changes aligned with the current shape of the code: OpenWebUI owns transcription, model/workspace behavior, variables, and speech; the Reachy app owns robot media, settings, tool dispatch, VAD, and motion.

## Quick Start

1. Fork and clone the repo.

```bash
git clone https://github.com/pollen-robotics/Reachy_OpenWebUI
cd Reachy_OpenWebUI
```

2. Create an environment.

```bash
uv venv --python python3.12 .venv
source .venv/bin/activate
uv sync --group dev
```

3. Copy `.env.example` only for local development. Do not commit real `.env` files or secrets.

## Current Project Shape

- Python package: `Reachy_OpenWebUI`
- Reachy Mini Apps entry point: `Reachy_OpenWebUI`
- Console script: `reachy-mini-conversation-app-openwebui`
- Main runtime code: `src/Reachy_OpenWebUI/`
- Settings/call UI: `src/Reachy_OpenWebUI/static/`
- Default tool allow-list: `src/Reachy_OpenWebUI/profiles/default/tools.txt`
- Hugging Face Space project page: `app.py`

`requirements.txt` is for the Space project page only. Use `pyproject.toml` for the robot app dependencies.

## Development Workflow

- Keep pull requests focused on one behavior or documentation update.
- Prefer small, reviewable changes over broad rewrites.
- Do not reintroduce legacy local STT, voice-provider, or old package-name docs unless the code actually supports them again.
- Keep OpenWebUI auth wording precise: API keys may work for HTTP endpoints, but the realtime socket path needs a JWT in `OPENWEBUI_TOKEN`.
- Update README and `.env.example` whenever settings, CLI flags, package names, or user-visible behavior change.
- Avoid committing generated files, real settings files, downloaded models, caches, or secrets.

## Checks

Run the checks that are available in this checkout:

```bash
uv run ruff check .
uv run ruff format . --check
uv run mypy --pretty --show-error-codes
uv run python -m compileall src app.py
```

There is no `tests/` directory in this checkout. Add focused tests when you add behavior that can be tested without robot hardware.

## Documentation Checklist

Before opening a PR, verify docs against the actual code:

- CLI flags come from `src/Reachy_OpenWebUI/utils.py`.
- Env keys come from `src/Reachy_OpenWebUI/settings_keys.py` and `src/Reachy_OpenWebUI/config.py`.
- Settings UI routes come from `src/Reachy_OpenWebUI/console.py`.
- Tool names come from `src/Reachy_OpenWebUI/profiles/default/tools.txt` and `src/Reachy_OpenWebUI/tools/`.
- Package names and entry points come from `pyproject.toml`.

## Release Notes

When preparing a release:

1. Update the version in `pyproject.toml`.
2. Confirm README and `.env.example` match the release behavior.
3. Run the checks above.
4. Commit the version bump.
5. Create and push a tag.

```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```

## AI-Assisted Contributions

AI tools are fine for exploration and drafts, but the human author is responsible for the final patch. Keep AI-assisted changes readable, minimal, and verified against the code that is actually in the repo.

## Filing Issues

For bugs, include the Reachy Mini environment, Python version, OpenWebUI URL shape, auth mode, exact command or launcher path, and relevant logs. Use `--debug` when collecting local logs.

For feature requests, describe the user workflow, expected robot behavior, and whether the change belongs in OpenWebUI, the Reachy settings UI, or the robot-side tool/runtime layer.