Navi — Backend Documentation

Personal modular AI agent system. FastAPI backend + WebSocket streaming + Ollama LLM.

Quick start

# Install dependencies
python -m venv .venv && .venv/bin/pip install -r requirements.txt

# Configure (copy and edit)
cp .env.example .env   # set OLLAMA_HOST, NAVI_PERSONA_FILE, etc.

# Run
.venv/bin/uvicorn navi.main:app --reload --reload-dir navi --port 8000

Default UI: http://localhost:8000
Debug panel: http://localhost:8000/debug

File map

File	What it covers
`architecture.md`	Component diagram, data flow, dependency graph
`agent.md`	Agent loop, planning phase, tool execution, subagents, workers
`tools.md`	Built-in tools, user tool format, hot-reload, self-extension
`sessions.md`	Session model, dual-buffer design, context compression
`recall.md`	Scheduled callbacks — headless recall system
`websocket.md`	WebSocket protocol — all events, stop mechanism
`profiles.md`	Profiles, system prompts, persona, profile switching
`memory.md`	Long-term memory — facts, extraction, search
`auth.md`	Multi-user auth via gnexus-auth OAuth — roles, permissions, webhooks
`config.md`	All environment variables with types and defaults
`api.md`	REST API endpoints + full WebSocket event schemas and sequences

Key entry points in code

File	Role
`navi/main.py`	FastAPI app, router registration, startup hooks
`navi/core/agent.py`	Agent class — `run()`, `run_stream()`, `run_ephemeral()`
`navi/core/registry.py`	`build_default_registries()` — wires everything together
`navi/api/websocket.py`	WebSocket handler + `POST /sessions/{id}/stop`
`navi/config.py`	`Settings` — all config loaded from `.env`
`navi/profiles/`	Profile definitions (`secretary`, `server_admin`, `developer`)
`tools/`	User-defined tools (auto-discovered at startup)

Stack

Web framework: FastAPI + uvicorn
LLM: Ollama (primary), OpenAI-compatible backend wired in
Default model: gemma4:31b-cloud (configurable per profile)
Database: PostgreSQL via asyncpg
Logging: structlog
Config: pydantic-settings (reads .env)