# Navi — Backend Documentation

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

## Quick start

```bash
# 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 |
|---|---|
| [`mechanics.md`](mechanics.md) | **Master catalog of all mechanisms** — use before designing new features |
| [`navi_code.md`](navi_code.md) | Navi Code — local terminal mode (profile, .env, security) |
| [`navi_code_cli.md`](navi_code_cli.md) | `navi-code` CLI/TUI client — flags, commands, TUI layout, events |
| [`api_tokens.md`](api_tokens.md) | API token auth for headless clients — schema, REST endpoints, security |
| [`architecture.md`](architecture.md) | Component diagram, data flow, dependency graph |
| [`agent.md`](agent.md) | Agent loop, planning phase, tool execution, subagents, workers |
| [`tools.md`](tools.md) | Built-in tools, user tool format, hot-reload |
| [`sessions.md`](sessions.md) | Session model, dual-buffer design, context compression |
| [`store.md`](store.md) | KV store — per-session/per-user key-value persistence |
| [`recall.md`](recall.md) | Scheduled callbacks — headless recall system |
| [`websocket.md`](websocket.md) | WebSocket protocol — all events, stop mechanism |
| [`profiles.md`](profiles.md) | Profiles, system prompts, persona, profile switching |
| [`context_providers.md`](context_providers.md) | Context providers — inject dynamic system context per turn |
| [`memory.md`](memory.md) | Long-term memory — facts, extraction, search |
| [`eval_system.md`](eval_system.md) | Eval system — open scale, weekly trend |
| [`android-client.md`](android-client.md) | Android WebView client — architecture, build/deploy |
| [`permissions.md`](permissions.md) | Permission gate — authoritative backend confirmation for destructive tool calls (**design only, not yet implemented**) |
| [`auth.md`](auth.md) | Auth: multi-user OAuth via gnexus-auth, or disable with `NAVI_AUTH_ENABLED=false` |
| [`config.md`](config.md) | All environment variables with types and defaults |
| [`api.md`](api.md) | REST API endpoints + full WebSocket event schemas and sequences |
| [`testing.md`](testing.md) | Test layout, fixtures, how to run the suite |

Historical design notes and tech-debt reviews live in [`archive/`](archive/).

## 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`, `navi_code`, etc.) |
| `tools/` | User-defined tools (auto-discovered at startup) |
| `clients/terminal/` | Navi Code TUI and raw CLI (`navi-code`) |

## 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`)
- **Terminal client**: Textual 8.x (`clients/terminal/`, command `navi-code`)
