navi-1

Модульная агентная система с REST API и WebSocket. FastAPI бэкенд, Ollama LLM, vanilla JS клиент.

Запуск

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

cp .env.example .env  # настрой OLLAMA_HOST, DATABASE_URL и др.

uvicorn navi.main:app --reload --reload-dir navi --port 8000

Клиент: http://localhost:8000
Swagger UI: http://localhost:8000/docs
Debug panel: http://localhost:8000/debug

Быстрый старт (REST)

# 1. Создать сессию с профилем "secretary"
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{"profile_id": "secretary"}'

# 2. Отправить сообщение (замени <session_id>)
curl -X POST http://localhost:8000/sessions/<session_id>/messages \
  -H "Content-Type: application/json" \
  -d '{"content": "Найди последние новости про Python 3.13"}'

WebSocket

ws://localhost:8000/ws/sessions/<session_id>

Клиент отправляет:

{"type": "message", "content": "...", "images": [...], "files": [...]}

Сервер стримит события в порядке:

stream_start
plan_ready          (если profile.planning_enabled — план до начала выполнения)
thinking_delta*     (reasoning chunks)
thinking_end
turn_thinking       (reasoning из tool-calling турна, целиком)
tool_started        (начало вызова инструмента — pending card в UI)
tool_call           (инструмент завершён — результат)
stream_delta*       (финальный текстовый ответ)
stream_end
context_compressed  (опционально — после сжатия контекста)

Остановить генерацию: POST /sessions/<session_id>/stop

Полная спецификация: docs/websocket.md и docs/api.md

Структура

navi/
├── main.py            # FastAPI app, роутеры, startup hooks
├── config.py          # настройки через .env (pydantic-settings)
├── exceptions.py      # доменные исключения
├── llm/               # LLM бэкенды: ollama.py, openai_backend.py
├── tools/             # встроенные инструменты (~20 шт.)
├── profiles/          # профили агентов: secretary, server_admin, smart_home, developer
├── core/              # Agent, registry, session, compressor, events
├── memory/            # долгосрочная память (PostgreSQL или SQLite)
├── workers/           # post-turn workers (CompressionWorker, MemoryWorker)
└── api/               # роуты и WebSocket handler

tools/                 # пользовательские инструменты (auto-discovered)
├── enabled.json       # список инструментов, активных во всех профилях
├── _template.py       # шаблон формата
├── get_current_datetime.py
├── user_notes.py
└── weather.py

manuals/               # markdown-мануалы для tool_manual
docs/                  # архитектурная документация
persona.txt            # глобальная личность и инструкции агента

Профили

Каждый профиль определяет свой набор enabled_tools. developer — единственный профиль с reload_tools, delete_tool и test_tool; остальные профили не имеют доступа к инструментам разработки.

Расширение

Пользовательский инструмент — переключись в профиль developer и попроси Нави создать инструмент. Она напишет файл в tools/, протестирует через test_tool и перезагрузит через reload_tools. Либо вручную создай tools/my_tool.py:

name = "my_tool"
description = "Когда и зачем использовать."
parameters = {"type": "object", "properties": {...}, "required": [...]}

async def execute(params: dict) -> str:
    return "результат"

Добавить во все профили: занести имя в tools/enabled.json.

Новый профиль — создай navi/profiles/my_profile.py, добавь в ALL_PROFILES в __init__.py.

Новый LLM бэкенд — реализуй LLMBackend из navi/llm/base.py, зарегистрируй в build_default_registries() в navi/core/registry.py.

База данных

Нави поддерживает два варианта хранилища — выбор определяется наличием DATABASE_URL в .env.

PostgreSQL (рекомендуется для production):

DATABASE_URL=postgresql://user:password@host:5432/navidb

Требует asyncpg. Использует пул соединений. Хранит сессии и долгосрочную память в одной базе.

SQLite (быстрый старт, без внешних зависимостей):

# DATABASE_URL не задан — автоматически используется SQLite
DB_PATH=navi.db  # опционально, по умолчанию navi.db

Конфигурация (.env)

Ключевые переменные (полный список: docs/config.md):

# LLM
OLLAMA_HOST=http://localhost:11434
OLLAMA_API_KEY=
OLLAMA_DEFAULT_MODEL=gemma4:31b-cloud
OLLAMA_NUM_CTX=65536
OLLAMA_THINK=true

# База данных (выбери одно)
DATABASE_URL=postgresql://user:pass@host:5432/db   # PostgreSQL
# DB_PATH=navi.db                                  # SQLite (если DATABASE_URL не задан)

# Персона
NAVI_PERSONA_FILE=persona.txt

Для прямого доступа к Ollama Cloud:

OLLAMA_HOST=https://ollama.com
OLLAMA_API_KEY=your_api_key

Также укажи cloud-модель в navi/profiles/*/config.json, потому что профили могут переопределять OLLAMA_DEFAULT_MODEL.