Flutterwave AI Service (RAG)

This monorepo ingests official Flutterwave docs via llms.txt, chunks and embeds them into Postgres+pgvector, and serves streaming answers with citations.

Key Design Choices

• Hybrid retrieval: pgvector cosine + Postgres full‑text (tsvector).
• Rerank: Cohere/Voyage if configured; MMR fallback.
• Context packing: diverse, section‑coherent top‑8 chunks.
• Guardrails: system prompt forbids hallucinated fees/guarantees.

Develop

cp .env.example .env
# start DB/Redis
docker compose up -d db redis
# migrate
pnpm -w --filter @fw-ai/db dev
# crawl
pnpm -w --filter @fw-ai/crawler dev
# run RAG
pnpm -w --filter @fw-ai/rag-server dev

Production

• Build container images from the repository Dockerfiles (Dockerfile.*)
  • Example: docker build -f Dockerfile.rag-server -t <registry>/fw-ai/rag-server:latest .
• Run database migrations during deploy (CI/CD or migration container).
  • Example: pnpm -w --filter @fw-ai/db migrate
• Set production secrets: OpenAI / Cohere / Voyage keys (e.g. OPENAI_API_KEY, COHERE_API_KEY, VOYAGE_API_KEY) in your environment or secret store.
• Place a CDN/WAF (Cloudflare recommended) in front for protection and performance.
  • Use WAF rules to protect endpoints.
  • Enable caching for /answer?q= only if you implement a safe HTTP cache for packed contexts and respect cache-control headers.
• Add a change-detector to re-ingest source docs when ETag or content hash changes (automated re-indexing on diff).

Notes

• The reranker providers are optional. If unset, we do MMR to avoid duplicate snippets.
• The embeddings dimension (3072) matches text-embedding-3-large; change vector(N) if you pick a different model.
• Retrieval SQL mixes cosine (vector) and ts_rank. Adjust weights 0.6/0.4 per evals.
• All responses are streamed as text/event-stream. Wrap in your web UI as needed.