README.md

metadata

license: mit
title: ChatQnA RAG Service
sdk: docker
emoji: ⚡
colorFrom: red
colorTo: yellow

RAG Service (Python)

apps/rag-service is now the production Python intelligence engine used by apps/api. It contains migrated retrieval + LLM routing behavior from the Streamlit reference (app.py).

Run locally

python -m pip install -r requirements.txt
uvicorn app.main:app --reload --port 8002 --app-dir .

API contract

• POST /query accepts:
  • sessionId, message, history, topK
  • optional document object (documentName, documentKind, documentText)
• returns:
  • answer
  • retrievedChunks[] with id, page, chunkType, text
  • optional span mapping fields: startOffset, endOffset, sourceDocument, score
  • citations[] aligned to returned chunks

Runtime behavior

• Primary retrieval:
  • Uploaded document text (if provided) is chunked and ranked.
  • Default mode is lexical for low-memory/free-tier reliability.
  • Optional mode semantic uses all-MiniLM-L6-v2 embeddings (higher memory).
• Secondary retrieval:
  • Qdrant if configured, else FAISS local fallback (faiss_store/).
• Answer generation:
  • HF Router->Groq primary route, Groq fallback.
  • Local guarded fallback answer if LLM route is unavailable.

Required/optional env

• RAG_SERVICE_URL (set in API, points to this service)
• Optional:
  • QDRANT_URL, QDRANT_API_KEY, QDRANT_COLLECTION
  • KB_BACKEND (qdrant or faiss)
  • RAG_RETRIEVAL_MODE (lexical or semantic, default lexical)
  • HUGGINGFACE_API_TOKEN, GROQ_API_KEY
  • RAG_MODEL_ID, RAG_TEMPERATURE, RAG_MAX_TOKENS
  • UPLOAD_CHUNK_SIZE, UPLOAD_CHUNK_OVERLAP

Deploy on Hugging Face Spaces (free CPU)

1. Create a new Space with SDK = Docker.
2. Point the Space to apps/rag-service.
3. The included Dockerfile exposes FastAPI on port 7860.
4. Add secrets:
   • QDRANT_URL, QDRANT_API_KEY, HUGGINGFACE_API_TOKEN, GROQ_API_KEY
5. Add variables:
   • KB_BACKEND=qdrant
   • RAG_RETRIEVAL_MODE=lexical
   • QDRANT_COLLECTION=doc_kb