Spaces:
Running
Running
| # 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. | |