# 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 |
| [`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, self-extension |
| [`sessions.md`](sessions.md) | Session model, dual-buffer design, context compression |
| [`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 |
| [`memory.md`](memory.md) | Long-term memory — facts, extraction, search |
| [`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 |

## 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`)