Skip to content

Development Setup

Complete the local installation in Getting Started first. This guide covers the extra tools and checks used when modifying Numi.

Requirements

Alongside the local runtime requirements, install Node.js 22.22.2+ and npm to match the frontend checks in CI. Install Deno as well if you work on the Pyodide sandbox path in code_interpreter.

Initial Setup

From the repository root:

make install-dev

This runs uv sync --group dev and npm ci, installing the Python test, lint, and documentation tools along with the frontend linters and formatter.

Development Workflow

  1. Start the server with make run-web and open http://localhost:4567.
  2. Make your changes and run the relevant unit tests.
  3. Run the quality checks below and review git diff before committing.

Keep development databases separate from instances that hold real accounts and conversations. Read Database Migrations before changing SQLModel tables.

Available Commands

Command What it does
make run-web Restores pinned browser assets if missing, then starts the app
make test Runs the full Python test suite (including network tests)
npm test Runs the JavaScript behavior tests
make check Checks formatting, lint, unused code, and core-path complexity without modifying files
make fix Applies Python and frontend lint fixes and formatting (modifies files)
make docs Serves the documentation locally with live reload
make docs-build Builds the documentation in strict mode (warnings fail the build)
make bump-deps Updates dependencies and browser assets, installs them, and runs checks
make help Lists all available Make targets

Updating Dependencies

From the repository root, run:

make bump-deps

This refreshes uv.lock and requirements.txt within the Python constraints and seven-day release cooldown in pyproject.toml, keeping the Python version unchanged. It also runs a pinned npm-check-updates via npx to update npm minor and patch versions, refreshes the npm lockfile, and downloads the latest browser assets.

After installing updates, make bump-deps verifies dependency consistency, asset checksums, formatting, and lint, runs the JavaScript and non-network Python suites, and builds the documentation strictly. It stops at the first failing step and leaves the working tree ready for inspection without committing.

Testing

Run focused tests while iterating:

uv run pytest tests/agent/test_agent_runtime.py
node --test tests/js/test_chat_menu.cjs

See Running Tests for the full test suite, coverage reports, and test fixtures.

Code Quality

For Python changes, check the files you touched:

uv run ruff format --check src/numi_chat/agent/runtime.py
uv run ruff check src/numi_chat/agent/runtime.py

For frontend changes, bump any modified asset's ?v= cache version with make bump-asset ASSET=css/base.css and run:

npm run fix:web
npm run check:web
make check

fix:web formats all frontend files, so check git diff afterward to make sure unrelated edits remain untouched. make check and make ci-lint are read-only; make fix, make format, and make lint-fix modify files in place.

Project Structure

Path Start here for
src/numi_chat/agent_core/ Reusable turn loop, streaming/retries, and SimpleAgent
src/numi_chat/agent/ Chat TurnHost, prompt builder, context layers, and model resolution
src/numi_chat/llm/ Model catalog and provider wire adapters
src/numi_chat/web/ FastAPI routes, WebSocket connection manager, and browser UI
src/numi_chat/services/ Chat streaming, tool execution, shares, memory, and deep research
src/numi_chat/tools/ Built-in and optional tool implementations
src/numi_chat/data/models.py SQLModel table definitions
src/numi_chat/data/db.py Database engine, sessions, and startup migration hook
migrations/versions/ Alembic schema revisions
tests/ Python (tests/) and JavaScript (tests/js/) test suites