🧭 Project Overview

Navi is a personal modular AI agent system. FastAPI backend + vanilla JS client. The agent is named Navi — female personal assistant. Runs locally via Ollama.

📦 Stack

🗂️ Component Map

🔄 Request Lifecycle

Streaming flow from WebSocket message to final response.

🔗 Context Vars

Thread-safe async-safe state shared between Agent and tools. Defined in navi/tools/base.py.

⚙️ Agent Loop

Three entry points in navi/core/agent.py:

System prompt construction

Built fresh on every LLM call — never stored in session.context.

NAVI_PERSONA (global personality)
───────────────────────────────────────
profile.system_prompt (domain rules)
───────────────────────────────────────
[memory injection: "## What I remember about the user"]
───────────────────────────────────────
session.context messages (history, no system msgs)

Sub-agent isolation

run_ephemeral() sets current_session_id = "subagent_<uuid12>" so each subagent has its own isolated scratchpad and SSH connection pool entry.

🗺️ Planning Phase

Runs before the tool-calling loop when profile.planning_enabled = true.

💾 Sessions

Session model (navi/core/session.py)

Dual-buffer design

Message format

🗜️ Context Compression

Keeps the LLM context within the token budget. Only session.context is modified — session.messages is never touched.

Trigger points

Algorithm

Config

🔧 Built-in Tools

Registered in build_default_registries() as builtins. Never removed on hot-reload.

🔌 User Tools

Image tool → multimodal injection

When image_view succeeds, it returns metadata={is_image: true, base64: "..."}. The agent appends a synthetic user message with the image to session.context (not messages) — making it visible to the next LLM call without polluting display history.

📝 Tool Format

Module-level format (preferred for user tools)

name = "my_tool"
description = "What it does and when to use it — be specific."
parameters = {
    "type": "object",
    "properties": {
        "param": {"type": "string", "description": "..."}
    },
    "required": ["param"]
}

async def execute(params: dict) -> str:
    # Return a plain string on success.
    # Raise an exception to signal failure.
    return "result"

ToolResult (class-based format)

Self-extension via write_tool

The agent can install new tools permanently at runtime. WriteToolTool validates, writes to tools/{name}.py, adds to tools/enabled.json, then hot-reloads. New tool is available from the next user message.

📡 WebSocket Protocol

Endpoint: ws://host/ws/sessions/{session_id}
Closes with code 4004 if session not found.

Client → Server

{
  "type": "message",         // required, always "message"
  "content": "user text",    // required, non-empty
  "images": ["base64..."],   // optional; data: URI prefix stripped server-side
  "files": [                 // optional; from POST /sessions/{id}/files
    {"name": "file.pdf", "path": "/abs/path/..."}
  ]
}

📬 Events Reference

🎬 Typical Event Sequences

Simple question (no tools)

With planning + tools

Subagent (spawn_agent)

Profile switch

🌐 REST API

👤 Profiles

Profiles define tools, system prompt, model, and behaviour per domain. Defined in navi/profiles/.

Per-profile scratchpad sections

AgentProfile fields

🧠 Memory System

Long-term user memory: facts extracted from conversations, stored in SQLite, injected into every session.

Database schema

Automatic extraction trigger

POST /sessions (create new session) fires _process_stale_sessions() as a background task. Processes sessions idle > 30 minutes that haven't been extracted yet.

Memory injection

On every run_stream() / run() call, _memory_msg() fetches the summary and returns a system message: "## What I remember about the user\n\n{summary}". Injected after main system prompt, before conversation history.

Memory tools usage rules

⚙️ Configuration

All settings read from .env via pydantic-settings. Imported as from navi.config import settings.

LLM

Security / Sandboxing

Persona

Other