Recall — Turnkey Enterprise RAG

A full-stack RAG product, not a notebook demo: multi-format ingest, hybrid retrieval, reranking, citation-backed chat, workspace tenancy, Firebase auth, optional Stripe billing, OpenTelemetry tracing, golden dataset API regression tests, and BEIR-backed eval gates — deployable to GCP Cloud Run or Docker Compose.

Who this repo is for

Audience	What to read
Engineers learning RAG	System at a glance · Request flows · Repo map · ADRs · Benchmarks · Golden dataset
Operators / pilots	Deploy · GCP guide · API quickstart · Production checklist

Author: Ajas Bakran — AI systems engineering (RAG, evals, production glue). LinkedIn · Newsletter

What problem this solves

Teams evaluating RAG usually wire vector DB + embeddings + lexical search + reranker + LLM + UI themselves. Recall is a single deployable product:

Upload PDF, DOCX, Markdown, TXT (format-aware chunking, dedup, table preservation).
Index dense vectors in Qdrant + BM25 hybrid (cloud or local embeddings).
Ask in the Web UI or REST API — answers include verified citations.
Isolate tenants with workspaces, API tokens, and (pilot) Firebase user accounts.
Measure retrieval with BEIR, the golden dataset (data/golden/), and CI gates; trace latency per pipeline stage.

North star: Open a URL → sign in → workspace → upload → cited chat → optional HTTP integration. Documented in ADR-016.

System at a glance

flowchart TB
  subgraph clients [Clients]
    UI[Web UI static]
    API[REST /v1/*]
  end
  subgraph app [Recall FastAPI]
    AUTH[Firebase session BFF]
    ING[Ingest + chunk]
    RET[Hybrid retrieve + RRF]
    RNK[FlashRank rerank]
    SYN[LiteLLM synthesis + citations]
    OBS[OTel + structured logs]
  end
  subgraph data [Data plane]
    QD[(Qdrant)]
    GCS[(GCS workspaces)]
    BM25[BM25 lexical]
  end
  subgraph external [External APIs]
    LLM[LiteLLM / OpenRouter]
    EMB[Embedding API cloud mode]
  end
  UI --> AUTH
  UI --> API
  API --> ING --> QD
  API --> RET --> QD
  RET --> BM25
  RET --> RNK --> SYN --> LLM
  ING --> EMB
  AUTH --> GCS
  app --> OBS

Layer	Technology	ADR
API + UI	FastAPI, static HTML/JS/CSS	010
Ingest	Format adapters, xxhash + MinHash dedup	003 · 004
Vectors	Qdrant HNSW, optional sparse	006
Retrieval	Dense + BM25, RRF, circuit breakers	007
Rerank	FlashRank ONNX	008
Generation	LiteLLM, sandboxed context, citation check	009
SaaS pilot	Cloud embeddings, workspaces, quotas	016
Auth	Firebase + httpOnly session cookie	017
Billing	Stripe + plan quotas (feature-flagged)	018
Deploy	Docker, Cloud Run, GCE Qdrant	011 · 015

How it was designed

Recall follows spec & ADR first: every major fork (chunking, hybrid weights, auth, billing, cloud vs local embeddings) is recorded under docs/decisions/ before lock-in.

Process:

19 ADRs — recorded design decisions (full index).
Engineering ledger — session notes, attack plans, lessons (docs/engineering-ledger/).
Pilot UX bar — product checklist for static UI (recall-pilot-ux · journey doc).

Dual-mode engine (honest trade-offs, not marketing):

Mode	Embeddings	Best for
`RAG_MODE=cloud` (SaaS default)	LiteLLM / OpenRouter at ingest + query	GCP pilot, paid API, no SPLADE ONNX on server
`RAG_MODE=local`	FastEmbed + SPLADE ONNX	Air-gap, BEIR reproduction, zero embed API cost

See local vs cloud and benchmarks.

End-to-end request flows

Chat (browser)

sequenceDiagram
  autonumber
  participant U as User
  participant UI as Web UI
  participant API as FastAPI
  participant R as Retrieve + Rerank
  participant L as LiteLLM
  U->>UI: Sign in Firebase → POST /auth/session
  U->>UI: Upload file
  UI->>API: POST /v1/ingest
  API->>API: chunk, embed, Qdrant upsert
  U->>UI: Question
  UI->>API: POST /v1/chat
  API->>R: hybrid + rerank
  API->>L: synthesis with context_document XML
  API-->>UI: answer + citations + timing

Machine client

Workspace header X-Workspace-Key + Bearer workspace token (rcl_…) — see API Integration and pilot client guide.

Repository map

src/recall/
  api/           FastAPI app, auth, billing (flag), static UI
  core/          Config (.env + config.yaml)
  ingestion/     Loaders, chunking, dedup
  retrieval/     Hybrid fusion, rerank, compress
  storage/       Qdrant abstraction
  eval/          Benchmarks, retrieval gates, deploy eval floors
  observability/ OpenTelemetry, structured logging
data/golden/     Golden dataset manifest (eval cases; docs in data/sample/)
deploy/gcp/      Cloud Run, Qdrant GCE, VPC scripts
docs/decisions/  ADRs (design rationale)
tests/           pytest + golden API tests + Firebase session tests

Frontend (pilot UI)

Pages: / chat · /integration API tokens · /login · /signup · /landing · /auth/action (password reset).
Patterns: Workspace modal, storage meter, citation dialog, corner sign-out when auth on, skippable onboarding card.
No framework — intentional for pilot velocity; shared recall-shared.js + style.css design tokens.

Observability

Capability	Where
OpenTelemetry spans	ingest → retrieve → rerank → compress → synthesis
Per-stage latency	`timing` on `/v1/chat`; UI footer
Structured logs	`request_id`, workspace context (`logging.py`)
OTLP export	`OTEL_EXPORTER_OTLP_ENDPOINT`
Health	`GET /v1/health`

Details: config.yaml observability · production-readiness.

Quality & evaluations

Gate	When	What
pytest	Every PR	Unit + integration (+ auth, tenancy, billing when enabled)
Sample benchmark	CI	HitRate@5 ≥ 90%, MRR ≥ 0.60 on bundled corpus
Golden dataset	CI	`data/golden/manifest.json` — fixed Q&A cases over `data/sample/` docs; `tests/test_golden_rag_api.py` exercises ingest → search → chat with verified citations
BEIR	Release / research	SciFact, FiQA @500/@10k — methodology
Deploy eval	Optional workflow	DeepEval on golden cases — ADR-019

The golden dataset is the product-shaped regression harness: same HTTP surface pilots use, not just retrieval metrics in isolation.

RAG_ENV=test RAG_MODE=local pytest -q
RAG_ENV=test pytest tests/test_golden_rag_api.py -q
RAG_ENV=test recall benchmark --dataset sample --in-memory --min-hit-rate 0.90 --min-mrr 0.60

Published retrieval results (local ONNX, Sep 2026): FiQA @10k HitRate@5 73.8%; SciFact @500 91.0%. Full tables: benchmarks README.

Deployment

Target	Command	Docs
Local / demo	`docker compose up` or `recall serve`	.env.example
GCP Cloud Run	`RECALL_ENV_FILE=.env.gcp ./deploy/gcp/deploy.sh`	google-cloud.md
Custom domain	Cloud Run mapping + Spaceship DNS	§8 in GCP doc (Firebase `authDomain` ≠ app host)

Secrets: Use .env.gcp.example locally; prefer Secret Manager for API keys on GCP. Never commit real env files — see SECURITY.md.

Security & credentials

.gitignore blocks .env, .env.* (except *.example), keys, and service account JSON.
Pre-push: run the checks in SECURITY.md.
Auth matrix: session cookie or workspace token / deploy key — ADR-017.

Quickstart

git clone https://github.com/DTiapan/Recall.git && cd Recall
cp .env.example .env   # add OPENROUTER_API_KEY etc. — never commit .env
uv venv && source .venv/bin/activate
uv pip install -e ".[formats,dev]"
recall serve
# → http://localhost:8000  (AUTH_ENABLED=false by default in CI)

GCP pilot: copy .env.gcp.example → .env.gcp, configure Firebase + AUTH_ENABLED=true, deploy script as above.

Local vs cloud embeddings

	Cloud (`RAG_MODE=cloud`)	Local (`RAG_MODE=local`)
Dense	LiteLLM / OpenRouter	FastEmbed ONNX
Lexical	BM25 (rehydrate from Qdrant)	BM25 + SPLADE sparse in Qdrant
Cost	API spend at ingest + query	CPU/RAM, $0 embed API
Evidence	Production pilot path	BEIR tables

Documentation index

Topic	Path
All ADRs	docs/decisions/README.md
GCP deploy + Firebase	docs/deployment/google-cloud.md
Production checklist	docs/deployment/production-readiness.md
API quickstart	docs/api-quickstart.md
Benchmarks & scale	docs/benchmarks/README.md
Pilot UX journey	docs/product/pilot-ux-journey.md
Engineering ledger	docs/engineering-ledger/INDEX.md

REST API (summary)

Endpoint	Description
`POST /v1/ingest`	Upload or ingest text
`POST /v1/search`	Hybrid search + scores
`POST /v1/chat`	RAG answer + citations + `timing`
`GET /v1/health`	Health + tracing flag
OpenAPI	`/docs` when server running

Built with

Piece	Role
Qdrant	Vector store
LiteLLM	LLM + cloud embeddings gateway
FlashRank	ONNX reranker
FastEmbed	Local embeddings (optional)
Craft	Agent workflow + ledger discipline

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
.agents		.agents
.cursor		.cursor
.github/workflows		.github/workflows
data		data
deploy/gcp		deploy/gcp
docs		docs
scripts		scripts
src/recall		src/recall
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.env.gcp.example		.env.gcp.example
.gcloudignore		.gcloudignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONSTRAINTS.md		CONSTRAINTS.md
Dockerfile		Dockerfile
README.md		README.md
SECURITY.md		SECURITY.md
cloudbuild.yaml		cloudbuild.yaml
config.yaml		config.yaml
craft.project.yaml		craft.project.yaml
docker-compose.smoke.yml		docker-compose.smoke.yml
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
skills-lock.json		skills-lock.json
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

Recall — Turnkey Enterprise RAG

Who this repo is for

What problem this solves

System at a glance

How it was designed

End-to-end request flows

Chat (browser)

Machine client

Repository map

Frontend (pilot UI)

Observability

Quality & evaluations

Deployment

Security & credentials

Quickstart

Local vs cloud embeddings

Documentation index

REST API (summary)

Built with

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Recall — Turnkey Enterprise RAG

Who this repo is for

What problem this solves

System at a glance

How it was designed

End-to-end request flows

Chat (browser)

Machine client

Repository map

Frontend (pilot UI)

Observability

Quality & evaluations

Deployment

Security & credentials

Quickstart

Local vs cloud embeddings

Documentation index

REST API (summary)

Built with

License

About

Topics

Resources

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages