WORKING ON YUMII

Running from Source

The development setup: uv, the backend, the desktop shell, and the checks.

Prerequisites

  • uv — the only package manager the project supports (dependencies are pinned to CPU-only builds that plain pip mangles). It brings its own Python 3.12.
  • Rust (stable) and — on Windows — the MSVC C++ Build Tools, for the desktop shell. WebView2 ships with Windows 10/11.

The setup

bash
git clone https://github.com/CodeNeuron58/Yumii.git
cd Yumii
uv sync                              # everything, ~a minute

cd desktop && npx @tauri-apps/cli dev    # the desktop app — the only way to run Yumii

tauri dev compiles the shell, opens the orb window, and spawns the backend from your live Python source — edit Python, relaunch, see changes. On a machine without ~/.yumii, the full first-run flow (model downloads + onboarding) runs exactly as it does for users.

Headless backend only (for API work):

bash
uv run yumii server    # FastAPI on 127.0.0.1:8000 (walks to 8011 if taken)
# serves /health, the REST API, /ws, and /dashboard.html — there is no browser orb

Checks

bash
uv run ruff check .                          # lint
uv run pytest tests/                         # test suite — runs keyless, no API needed
python .github/scripts/check_versions.py     # the version strings must agree
cargo build --manifest-path desktop/src-tauri/Cargo.toml   # shell compiles

CI runs all of these on every push. The suite passes with no API keys present — if you add a module that constructs a provider client at import time, collection crashes in CI; build clients lazily.

Things that will save you an afternoon

  • uv sync, never pip install. The #1 setup failure.
  • Your data is shared. Source runs use the same ~/.yumii as an installed copy — convenient, but a data wipe affects both.
  • One backend at a time. A forgotten yumii server in another terminal means your fresh code isn't the process you're talking to (the port walk hides this well — check ~/.yumii/backend.port).
  • Config loads at startup. Provider/key changes need a backend restart, in dev exactly as in production.
  • Structured logs are the debugger. YUMII_LOG_LEVEL=DEBUG uv run yumii server — events are named (stt_dropped, composio_load_failed, tool_result_truncated) and usually point straight at the cause.