simbarag/README.md

SimbaRAG

SimbaRAG is a personal assistant with a Quart backend and React 19 frontend, document retrieval, persistent conversations, and configurable household integrations.

PostgreSQL stores application data and pgvector stores document embeddings (simba_docs). LangGraph checkpoints and conversation summaries use separate SQLite files on a persistent volume. Chat uses an OpenAI-compatible llama-server when configured, with OpenAI gpt-5-mini fallback; without llama-server it uses OpenAI directly. Embeddings use a configured OpenAI-compatible server or OpenAI text-embedding-3-small. Ollama is used by image/PDF helper workflows.

Setup

Install Python 3.13, uv 0.7.2, Node 22.14.0, and Docker Compose v2. From the repository root:

cp .env.example .env
# Edit .env before starting services; it is deliberately not deployable as-is.
uv sync --frozen --extra test
cd raggr-frontend
npm ci
npm run build
cd ..

Set DATABASE_URL, JWT_SECRET_KEY, FERNET_KEY, and OPENAI_API_KEY. Use a random database password and match it to POSTGRES_PASSWORD if using the included PostgreSQL service. OpenAI fallback and encrypted model fields initialize even when their integrations are otherwise unused. Optional integration credentials can remain empty in validation. The current Tavily client initialization still needs TAVILY_API_KEY at app import time; making it optional requires an application change. Configure all OIDC fields together to enable browser login.

For local backend development, start only PostgreSQL with docker compose up -d postgres, set DATABASE_URL to the host connection (localhost:5432), and use local writable checkpoint paths. Then:

uv run --frozen aerich upgrade
uv run --frozen python app.py

See the development guide for new database initialization, frontend development, and CI checks. For production configuration and blue/green services, see the deployment guide.

Agent tools and integrations

Tools are selected per request by the tool router. The current tool families include:

• Document retrieval (simba_search) and Tavily web search (web_search).
• Obsidian note search/read/create, journal tasks, and saved user memory.
• Mealie recipes, meal plans, and shopping lists.
• Google Calendar and Gmail, using the OAuth token file; access is gated by the router.
• SimbaKit/PetKit device status, weight, litter, and drinking history.
• Beli restaurant lists; credentials are stored encrypted per profile.
• Admin integrations: YNAB mirror SQL, Homebox inventory through homebox-mcp, and BookStack wiki through bookstack-mcp.

The application also supports WhatsApp (Twilio), email (Mailgun), iMessage (SendBlue), scheduled messages, and Cronicle triggers. Integration availability and access depend on credentials and user role. Tool schemas being present does not imply an integration is configured.

Checks and operations

make test             # backend unit tests; no deployment secrets required
make evaluate         # deterministic context fixture evaluation
make lint             # Ruff 0.8.2, matching pre-commit/CI
make frontend-check   # locked install, renderer tests, TypeScript, build
make validate-config  # production policy; prints setting names, not secrets

Gitea Actions runs backend Ruff/unit/evaluation and frontend renderer/typecheck/build checks independently. Python dependencies come from uv.lock; frontend dependencies come from raggr-frontend/package-lock.json with npm ci.

The production Makefile detects the active blue/green color for make logs, make migrate, and make migrate-history. make redeploy pulls the current branch and invokes scripts/deploy.sh; run it only when an actual deployment is intended. make reindex clears and rebuilds documents; make reindex-obsidian rebuilds only Obsidian documents. make ynab-sync performs a delta mirror sync and make ynab-resync a full download.

Further documentation: pgvector management, authentication, context management, and desktop client.