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:
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¶
- Start the server with
make run-weband openhttp://localhost:4567. - Make your changes and run the relevant unit tests.
- Run the quality checks below and review
git diffbefore 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:
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:
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:
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 |
Related Documentation¶
- Database Migrations: update the schema and verify that existing data upgrades cleanly.
- Adding Custom Tools: implement and enable a new tool.
- Manage Models: configure models through the admin UI or
state/models.json. - Architecture: understand module boundaries and request flow.