CODE_AUDIT_REPORT.md

# Reachy_OpenWebUI Code Audit Report

Scope audited: `C:\Users\jsnmd\Documents\Reachy_OpenWebUI\working\Reachy_OpenWebUI`

No fixes were applied during the audit.

## High Priority

### 1. Undefined `BackgroundToolManager` type reference

File: `src/Reachy_OpenWebUI/tools/core_tools.py:266`

`dispatch_tool_call_with_manager()` annotates `tool_manager` as `"BackgroundToolManager"`, but the name is not imported anywhere in the module. Ruff reports this as `F821 Undefined name BackgroundToolManager`.

Suggested fix: import `BackgroundToolManager` under `TYPE_CHECKING` from `Reachy_OpenWebUI.tools.background_tool_manager`, or replace the annotation with a protocol / less specific type.

### 2. Missing runtime dependency for Marionette upload route

File: `src/Reachy_OpenWebUI/sub_apps/marionette/marionette/routes.py:87`

The route uses `UploadFile = File(...)`, which requires `python-multipart` at runtime. `pyproject.toml` does not currently list `python-multipart` in `[project].dependencies`.

Suggested fix: add `python-multipart` to runtime dependencies.

### 3. Missing runtime dependency for Marionette community dataset fallback

File: `src/Reachy_OpenWebUI/sub_apps/marionette/marionette/datasets.py:598`

The community dataset fallback lazily imports `requests`, but `pyproject.toml` only lists `types-requests` in dev dependencies.

Suggested fix: add `requests` to runtime dependencies or replace that path with the existing `httpx` dependency.

### 4. Broad CORS on robot-facing app/tool surfaces

Files:

- `src/Reachy_OpenWebUI/console.py:964`
- `src/Reachy_OpenWebUI/tool_server/openapi_routes.py:35`

Both surfaces use `allow_origins=["*"]`. That is convenient for development, but risky for a LAN-visible robot control UI.

Suggested fix: restrict origins to the expected app/host origins, or gate broad CORS behind a development setting.

## Dead / Bad Links

### 5. Missing landing-page GIF

File: `index.html:43`

The landing page references `docs/assets/reachy_mini_dance.gif`, but that file is missing from the tree.

Suggested fix: restore the asset or update the page to reference an existing media file.

### 6. Broken Marionette dev video paths

Files:

- `dev/Jail/marionette_port/index.html:509`
- `dev/Jail/marionette_port/index.html:570`

The referenced video files exist under `dev/Jail/marionette_port/assets/`, but the HTML points to `marionette/assets/...`.

Suggested fix: update the dev HTML paths or remove the stale dev page from the active tree.

External links checked successfully:

- `https://www.contributor-covenant.org/version/3/0/`
- `https://www.contributor-covenant.org/faq/`
- `https://creativecommons.org/licenses/by-sa/4.0/`
- `https://huggingface.co/spaces/pollen-robotics/Reachy_Mini_Apps`

## Duplicate / Stale Code

### 7. Exact duplicate tool modules

Exact duplicate modules exist between the main app and the cookAIware sub-app, including:

- `src/Reachy_OpenWebUI/tools/move_head.py`
- `src/Reachy_OpenWebUI/sub_apps/cookAIware/tools/move_head.py`
- `src/Reachy_OpenWebUI/tools/stop_dance.py`
- `src/Reachy_OpenWebUI/sub_apps/cookAIware/tools/stop_dance.py`
- `src/Reachy_OpenWebUI/tools/stop_emotion.py`
- `src/Reachy_OpenWebUI/sub_apps/cookAIware/tools/stop_emotion.py`
- `src/Reachy_OpenWebUI/tools/head_tracking.py`
- `src/Reachy_OpenWebUI/sub_apps/cookAIware/tools/head_tracking.py`

Suggested fix: keep one shared implementation and have the sub-app import or wrap it.

### 8. Large stale `dev/` area

The `dev/` directory contains large copied experiments, old bot folders, `.bk` backups, logs, test ports, and stale app copies. It is ignored by `.gitignore`, but still lives in the working tree and affects scans/reviews.

Suggested fix: move archival material outside the repo or keep only documented, intentional dev fixtures.

### 9. Duplicate image assets

Large image files are duplicated between `src/Reachy_OpenWebUI/images/` and `src/Reachy_OpenWebUI/static/assets/`, including:

- `reachy-conversation-app.png`
- `cooking-chief.png`
- `reachy-how-to-create-app.png`

Suggested fix: choose one asset location and reference it consistently.

## Maintainability Risks

### 10. Oversized classes and route/controller files

Notable hotspots:

- `src/Reachy_OpenWebUI/console.py:284` - `LocalStream`
- `src/Reachy_OpenWebUI/sub_apps/conversation_app/local/llm.py:246` - `OpenWebUIClient`
- `src/Reachy_OpenWebUI/sub_apps/conversation_app/local/handler.py:408` - `LocalSessionHandler`
- `src/Reachy_OpenWebUI/sub_apps/marionette/marionette/datasets.py:54` - `DatasetMixin`
- `src/Reachy_OpenWebUI/sub_apps/marionette/marionette/recording.py:46` - `RecordingMixin`
- `src/Reachy_OpenWebUI/sub_apps/marionette/marionette/routes.py:48` - `register_routes`

Suggested fix: split transport, persistence, UI route, robot-control, and OpenWebUI-client responsibilities into smaller services.

### 11. Heavy use of catch-all exception handling

Static search found many broad `except Exception` handlers across `console.py`, Marionette, cookAIware, and the local conversation code.

Suggested fix: keep catch-all handlers at route/process boundaries; use narrower exception types inside logic paths and preserve actionable error messages.

### 12. Hardcoded robot/tool-server default

File: `src/Reachy_OpenWebUI/sub_apps/conversation_app/local/llm.py:1449`

The fallback default is `http://172.30.3.8:7860/reachy-tools`. This can silently point at the wrong robot/network.

Suggested fix: require explicit config or derive the tool-server URL from the current settings-app origin.

## Validation Notes

- Python AST parsing passed for all `.py` files.
- `ruff check . --statistics` found 282 issues. Most are style/doc/import-order findings; the highest-risk functional finding is the undefined `BackgroundToolManager` annotation.
- `ruff check src/Reachy_OpenWebUI --select F` reported 46 pyflakes findings, mostly unused re-export/import warnings plus the one undefined-name issue above.
- Route mapping showed the main UI and Marionette UI route calls mostly line up. Marionette API calls are intentionally rebased through a frontend fetch wrapper when mounted under `/apps/marionette`.
- The working tree was already dirty before the audit.