Spaces:
Running
Running
File size: 3,635 Bytes
cf1f373 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | # 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.
|