giers10/Heimgeist
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
Files
25bb5b2be92132b8568568fddb3d24532ff332ad
Heimgeist/AGENTS.md

9.4 KiB
Raw Blame History

AGENTS.md

Project Overview

Heimgeist is a local desktop chat app for Ollama. It uses a React/Vite renderer, an Electron desktop shell, a FastAPI backend, SQLite chat storage, Whisper transcription, optional SearXNG web search, and local RAG libraries under the backend.

A future migration to Tauri is planned, but do not begin that migration unless the task explicitly asks for it. Electron support must remain intact until Tauri reaches feature parity.

Important Directories and Entry Points

  • src/ - React renderer code.
    • src/main.jsx mounts the app.
    • src/App.jsx owns most chat UI state, session flow, model startup checks, and library/sidebar orchestration.
    • src/chatApi.js, src/chatGeneration.js, and src/backendApi.js contain backend request and streaming helpers.
    • src/desktop/desktopApi.js is the renderer platform abstraction for desktop APIs.
    • src/styles.css contains the main UI styling.
  • electron/ - Electron desktop shell.
    • electron/main.cjs creates windows, stores settings, handles updates, and implements IPC handlers.
    • electron/preload.cjs exposes the Electron IPC surface as window.electronAPI.
  • src-tauri/ - isolated Tauri migration scaffold.
    • src-tauri/src/main.rs owns Tauri commands for the renderer desktopApi surface.
    • src-tauri/tauri.conf.json points Tauri at the existing Vite renderer.
    • src-tauri/capabilities/ contains Tauri permission grants for enabled plugins.
  • backend/ - FastAPI backend and local processing.
    • backend/main.py defines chat, session, model, audio, Ollama, and web search routes.
    • backend/local_rag.py defines library, file registration, job, and local context routes.
    • backend/schemas.py and backend/models.py define API and database data shapes.
    • backend/rag/ contains corpus, enrichment, embedding, indexing, and retrieval helpers.
    • backend/database.py points SQLite at backend/app.db.
  • scripts/ - development wrappers used by npm scripts.
    • scripts/run-backend.cjs starts Uvicorn from backend/.venv.
    • scripts/run-electron-dev.cjs waits for Vite and FastAPI, then launches Electron.
  • run.sh - bootstrap script for local development dependencies and dev startup.
  • vite.config.js - Vite dev/build configuration. Dev server is fixed at 127.0.0.1:5173.

Run and Build Commands

  • ./run.sh - bootstrap/update Python and npm dependencies, then start the full dev stack.
  • npm run dev - start backend, Vite renderer, and Electron together.
  • npm run dev:backend - start FastAPI on 127.0.0.1:8000 with reload. Requires backend/.venv.
  • npm run dev:renderer - start Vite on 127.0.0.1:5173.
  • npm run dev:electron - wait for Vite and backend health, then start Electron.
  • npm run dev:tauri - start the Tauri shell against the Vite renderer. The FastAPI backend is still external during migration work.
  • npm run build - build the renderer into dist/.
  • npm start - start Electron against the current app files.

There are currently no npm test or lint scripts in package.json.

Architectural Boundaries

  • Renderer code should remain platform-neutral where practical. It may call backend HTTP APIs and may call desktopApi, but it should not call window.electronAPI directly.
  • src/desktop/desktopApi.js is the renderer's platform abstraction. Add desktop capabilities there first, then back them with Electron IPC. This keeps the future Tauri migration bounded.
  • electron/preload.cjs is the only file that should expose raw Electron IPC to the renderer.
  • electron/main.cjs owns desktop concerns: windows, dialogs, shell opening, settings persistence, update checks, and IPC implementations.
  • src-tauri/src/main.rs owns the Tauri implementation of the same renderer desktopApi surface during migration. Keep it additive and do not remove Electron behavior until Tauri reaches parity.
  • Backend code owns chat/session persistence, Ollama integration, Whisper transcription, web search enrichment, and RAG library processing.
  • Backend API contracts should stay stable unless intentionally coordinated with renderer changes. If a response/request shape changes in backend/schemas.py or route handlers, update the renderer callers in the same change.
  • Keep local RAG job orchestration and generated library state in the backend. Renderer code should use backend endpoints rather than reading library files directly.

Generated and Runtime Data

Do not edit or commit generated/runtime data unless the task explicitly requires it:

  • backend/app.db and any *.db files - local SQLite runtime data.
  • backend/libraries/ - local RAG library metadata, corpora, enrichment outputs, embeddings, indexes, and job state.
  • backend/.venv/ and .venv/ - Python virtual environments.
  • node_modules/ - npm dependencies.
  • dist/ - Vite build output.
  • __pycache__/, *.pyc, .DS_Store, and similar machine-generated files.
  • Local app settings files under the Electron user data directory or HEIMGEIST_SETTINGS_FILE.
  • Tauri-generated src-tauri/target/, src-tauri/gen/, and local src-tauri/Cargo.lock if generated by local verification.

Avoid broad file operations that traverse these directories. Use ignore patterns with search tools when inspecting the repo.

Verification Expectations

  • Frontend changes: run npm run build at minimum. For UI or interaction changes, also run the dev stack and exercise the affected flow in Electron.
  • Backend changes: run a targeted syntax/import check such as backend/.venv/bin/python -m py_compile backend/main.py backend/local_rag.py for touched modules, then start npm run dev:backend or the full dev stack and check GET /health.
  • Desktop bridge/Electron changes: run the full dev stack with npm run dev and verify Electron launches, settings load/save, dialogs or shell actions work, and no renderer code bypasses src/desktop/desktopApi.js.
  • Tauri desktop bridge changes: run cargo check --manifest-path src-tauri/Cargo.toml with a temp CARGO_TARGET_DIR when useful, run npm run build, and if practical run npm run dev:tauri with a temporary HEIMGEIST_SETTINGS_FILE so local user settings are not modified during verification.
  • API contract changes: verify both sides together. Update backend schemas/routes and renderer callers in the same change, then exercise the affected request path.
  • RAG, Whisper, Ollama, or SearXNG changes: note any external services or local models required for verification, and test graceful failure paths when those services are unavailable.

Future Tauri Migration Guidance

  • Do not start a Tauri migration opportunistically.
  • Keep new renderer desktop calls behind src/desktop/desktopApi.js; do not spread Electron-specific assumptions through React components.
  • Keep Tauri renderer calls behind src/desktop/desktopApi.js; do not import Tauri APIs directly in React components.
  • When adding desktop capabilities, prefer method names and payloads that could map cleanly to either Electron IPC or Tauri commands.
  • Maintain Electron behavior while any Tauri work is incomplete. Electron remains the supported desktop shell until Tauri reaches feature parity for settings, file picking/opening, external links, update flow, window events, backend startup expectations, and packaging.
  • Avoid refactors that mix migration prep with unrelated feature work. Migration work should be explicit and reviewable.

Coding and Refactor Guidelines

  • Keep changes scoped to the request. Do not refactor large files such as src/App.jsx, src/styles.css, backend/main.py, or backend/local_rag.py unless the task needs it.
  • Prefer existing helper modules and patterns over new abstractions.
  • Preserve stable backend contracts and persisted data compatibility. Add small migration helpers when changing database-backed fields.
  • Keep settings keys backward compatible where possible. Existing settings migrations live in Electron and backend settings helpers.
  • Use structured JSON/schema changes rather than ad hoc string parsing for API payloads.
  • Add comments only where they explain non-obvious control flow, concurrency, migration, or integration behavior.
  • Do not silently swallow errors in user-facing flows; surface useful messages while preserving graceful degradation for optional services.
  • Do not mix formatting churn with behavior changes.

Known Fragile Areas

  • The Electron bridge is intentionally narrow. Direct window.electronAPI use in renderer files will make Tauri migration harder.
  • src/App.jsx, src/chatGeneration.js, and backend chat routes share assumptions about streaming, regeneration, attachments, source metadata, and session state.
  • backend/main.py creates/migrates SQLite tables at import/startup. Schema changes need care because they run against local user data.
  • backend/local_rag.py coordinates asynchronous jobs, file registration, generated artifacts, and per-library locks. Avoid changes that can start duplicate jobs or corrupt backend/libraries/.
  • RAG builders under backend/rag/ run heavier file processing and subprocess/threaded work. Test with small inputs before broader runs.
  • Whisper depends on ffmpeg/ffprobe paths supplied by the Node backend runner when available.
  • Web search depends on an optional SearXNG instance, usually http://127.0.0.1:8888; features should fail gracefully when it is absent.
  • Ollama availability, model names, embedding model choices, and vision capability checks are runtime-dependent. Keep related UI and backend paths tolerant of missing models.