Fork: 0
root / navi-1
Transfer to URL with SHA Find file
Newer
Older
navi-1 / NAVI.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy on 1 May 3 KB Add 3D modeling specification workflow
Raw Blame History

NAVI — Project Context

Personal modular AI agent system. FastAPI backend + Ollama LLM + Vue webclient.

Server

.venv/bin/uvicorn navi.main:app --reload --reload-dir navi --port 8000
  • UI: http://localhost:8000
  • Debug panel: http://localhost:8000/debug
  • Default model: gemma4:26b-a4b-it-q4_K_M (26B, Q4)

Key paths

Path What
navi/core/agent.py Agent loop, planning, tool execution
navi/profiles/ Profile definitions (secretary, server_admin, developer)
navi/api/websocket.py WebSocket handler + event replay
tools/ User tools (auto-loaded at startup)
tools/enabled.json Tools enabled across all profiles
persona.txt Global persona injected into every profile
DATABASE_URL PostgreSQL session + memory store
workspace/ Persistent private working files for Navi
session_files/{session_id}/ Per-session uploads and publishable chat artifacts (SESSION_FILES_DIR)
manuals/ Tool manuals (served by tool_manual)

Documentation

Detailed reference is in docs/. Query a specific file when you need depth:

Use the filesystem tool with action query on the specific documentation file.

File Covers
docs/agent.md Agent loop, 3-phase planning, thinking mechanics flags
docs/profiles.md Profile fields, all config flags, how to add a profile
docs/tools.md Built-in tools, user tool format, hot-reload
docs/sessions.md Session model, dual-buffer, context compression
docs/websocket.md WebSocket protocol, all event types, reconnect replay
docs/memory.md Long-term memory system
docs/api.md Full REST + WebSocket API reference with schemas
docs/config.md All .env variables
docs/architecture.md Component diagram, data flow, registry wiring

Tool manuals

For detailed usage of any tool:

Call the tool_manual tool with the relevant tool name.

Manuals exist for: write_tool, spawn_agent, reflect, gmail, share_file, content_publish.

Extending Navi

To add a new tool: call the tool_manual tool for write_tool — full format reference + working example.

Agent prompt conventions

  • Keep the main agent context small: delegate bounded subtasks that need 3+ tool calls and can be summarized independently.
  • Before asking the user for project facts, proactively check nearest NAVI.md, then docs/, manuals/, memory, files, tool schemas, or web sources.
  • Treat NAVI.md as the active operational notebook for its directory, not just static project documentation. Update it with stable commands, conventions, local quirks, and current project decisions.
  • For Navi internals, use docs/index.md as the documentation map before scanning broad source trees.
  • File-location rule: workspace/ is persistent/private working storage; session_files/{session_id}/ is the per-session area for uploads, downloads, and inline artifacts. share_file copies an existing local file into the session directory and returns a download link. content_publish registers an existing session file for inline viewing and does not copy from workspace/.

Active 3D modeling improvements

Near-term work for modeler_3d:

  • Convert abstract user requests into an internal technical specification before detailed planning or OpenSCAD generation.
  • Make 3D implementation plans more detailed: object class, dimensions, print orientation, interfaces, tolerances, support strategy, geometry modules, verification steps.
  • Use a fixed preview inspection checklist after image_view, comparing the rendered model against the technical specification.
  • Require a critique/revision pass for medium+ 3D tasks before publishing, unless the model is a trivial primitive and the no-change rationale is explicit.
  • Add a source comments contract to generated .scad files: purpose, units, assumptions, print orientation, key dimensions, parameters, and revision notes.