ryan
de88679f25
- Fail startup on unsafe or malformed production settings (scripts/validate_config.py), run it before migrations, and stop on a failed `aerich upgrade`. - Forward the context-budget, timeout and metrics settings through Compose; accept the historical TAVILIY_API_KEY spelling. - Build the image from uv.lock and yarn.lock in a multi-stage Dockerfile. - Add Gitea Actions CI: Ruff, unit tests, context evaluation, frontend tests, typecheck and build. - Update README and deployment/development docs to match the current stack. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
61 lines
4.1 KiB
Markdown
61 lines
4.1 KiB
Markdown
# 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).
|