121 lines
11 KiB
Markdown
121 lines
11 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
Heimgeist is a local desktop chat app for Ollama. It uses a React/Vite renderer, a Tauri desktop shell, a FastAPI backend, SQLite chat storage, Whisper transcription, optional SearXNG web search, and local RAG libraries under the backend.
|
|
|
|
## 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.
|
|
- `src-tauri/` - Tauri desktop shell.
|
|
- `src-tauri/src/main.rs` owns Tauri commands for the renderer `desktopApi` surface, settings persistence, dialogs, path opening, external links, focus events, and update placeholders.
|
|
- `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/sidecar_main.py` is the PyInstaller entrypoint used by packaged Tauri builds to start `backend.main:app`.
|
|
- `backend/local_rag.py` defines library, file registration, job, and local context routes.
|
|
- `backend/paths.py` centralizes backend runtime data paths for SQLite and local RAG libraries.
|
|
- `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` gets the SQLite path from `backend/paths.py`.
|
|
- `scripts/` - development wrappers used by npm scripts.
|
|
- `scripts/run-backend.cjs` starts Uvicorn from `backend/.venv`.
|
|
- `scripts/run-tauri-dev.cjs` starts or reuses FastAPI, then launches the Tauri dev shell.
|
|
- `scripts/build-backend-sidecar.cjs` builds the PyInstaller backend sidecar and helper binaries for Tauri packaging.
|
|
- `run.sh` - bootstrap script for local development dependencies and dev startup.
|
|
- `vite.config.js` - Vite dev/build configuration. Tauri dev uses the strict Vite port `127.0.0.1:5174`.
|
|
|
|
## Run and Build Commands
|
|
|
|
- `./run.sh` - bootstrap/update Python and npm dependencies, then start the full dev stack.
|
|
- `npm run dev` - start or reuse FastAPI on `127.0.0.1:8000`, start the Vite renderer on `127.0.0.1:5174`, then launch Tauri.
|
|
- `npm run dev:tauri` - alias for the primary Tauri development workflow.
|
|
- `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:5174` for Tauri.
|
|
- `npm run dev:tauri:shell` - launch the raw Tauri shell when backend lifecycle is managed separately.
|
|
- `npm run build` - build the renderer into `dist/`.
|
|
- `npm run build:sidecar` - build the PyInstaller backend sidecar and helper binaries into `src-tauri/binaries/`.
|
|
- `npm run package:mac` - build the sidecar and produce `src-tauri/target/release/bundle/macos/Heimgeist.app`.
|
|
- `npm run build:app` - alias for `npm run package:mac`.
|
|
- `npm start` - alias for `npm run dev`.
|
|
|
|
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 import or call Tauri APIs directly.
|
|
- `src/desktop/desktopApi.js` is the renderer's platform abstraction. Add desktop capabilities there first, then back them with Tauri commands/events.
|
|
- `src-tauri/src/main.rs` owns desktop concerns: windows, menus, dialogs, shell opening, settings persistence, update placeholders, focus events, and Tauri command implementations.
|
|
- `src-tauri/src/main.rs` also starts the packaged backend sidecar in release builds, waits for `/health`, passes app-managed data-path environment, and shuts the sidecar down when the app exits.
|
|
- `backend/paths.py` owns backend runtime path resolution. Default development paths must remain `backend/app.db` and `backend/libraries`; packaged launchers pass app-managed paths through internal environment hooks.
|
|
- 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 Tauri app config directory or `HEIMGEIST_SETTINGS_FILE`.
|
|
- Packaged-build backend data directories supplied through internal deployment hooks such as `HEIMGEIST_DATA_DIR`, `HEIMGEIST_DB_PATH`, or `HEIMGEIST_LIB_ROOT`.
|
|
- Tauri-generated `src-tauri/target/`, `src-tauri/gen/`, and local `src-tauri/Cargo.lock` if generated by local verification.
|
|
- Generated sidecar binaries in `src-tauri/binaries/` except `src-tauri/binaries/.gitignore`.
|
|
|
|
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 Tauri.
|
|
- 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/Tauri 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`. Use a temporary `HEIMGEIST_SETTINGS_FILE` when testing ordinary shared settings behavior; use a temporary `HOME` with a fake legacy settings file when testing first-run import, because `HEIMGEIST_SETTINGS_FILE` intentionally bypasses import.
|
|
- Tauri packaging changes: run `npm run build:sidecar`, then `npm run package:mac` on macOS. Verify `src-tauri/target/release/bundle/macos/Heimgeist.app` exists, launches, starts or reuses a compatible backend on `127.0.0.1:8000`, uses app-managed data outside the app bundle, and stops its sidecar processes on quit.
|
|
- 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.
|
|
|
|
## Tauri Guidance
|
|
|
|
- Keep renderer desktop 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 stay stable for renderer callers.
|
|
- Preserve `HEIMGEIST_SETTINGS_FILE` as an explicit shared settings override.
|
|
- Keep first-run legacy settings import available when Tauri settings do not already exist.
|
|
- Do not move or rewrite `backend/app.db` or `backend/libraries`; the development backend must keep using the existing backend working directory.
|
|
- Treat `HEIMGEIST_DATA_DIR`, `HEIMGEIST_DB_PATH`, and `HEIMGEIST_LIB_ROOT` as internal app/sidecar deployment hooks only. Do not expose them in the UI or document them as normal user configuration.
|
|
- Packaged Tauri builds use `backend/sidecar_main.py` and `scripts/build-backend-sidecar.cjs` to bundle the FastAPI backend. Do not move or migrate development data into the packaged app data directory as part of packaging.
|
|
- Production-release work still needs signed updater/changelog parity, final bundle metadata, signing/notarization, full Windows/Linux packaging scripts, and installer behavior.
|
|
- 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 Tauri 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 Tauri bridge is intentionally narrow. Direct `window.__TAURI__` use outside `src/desktop/desktopApi.js` makes desktop behavior harder to reason about.
|
|
- `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/paths.py` controls where chat and local RAG data are stored. Preserve development defaults unless the task explicitly concerns packaged app data paths.
|
|
- `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.
|