CONTRIBUTING.md

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.

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

2. Create an environment.

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:

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.

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.