# 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:

```bash
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:

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

See the [development guide](docs/development.md) for new database initialization, frontend development, and CI checks. For production configuration and blue/green services, see the [deployment guide](docs/deployment.md).

## 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

```bash
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](docs/VECTORSTORE.md), [authentication](docs/authentication.md), [context management](docs/context-management.md), and [desktop client](docs/desktop-client.md).