ndambuki8/super-coach

A conversational, retrieval-augmented Q&A coach for nutrition, fitness and meal planning, designed for adolescent girls and young women (13–24) in low-resource settings # Super Coach A RAG chatbot that answers nutrition, fitness and meal-planning questions for adolescent girls and young women. Answers are grounded in a bundled corpus of guidance derived from WHO, USDA and NIH material, with citations back to the source documents. Out-of-scope and sensitive questions (crisis, disordered eating, medical) are caught by guardrails and get fixed responses instead of going to the model. ## Screenshots The Streamlit UI shows the question, the coach's answer, and cited sources under each turn. Multi-turn chat with grounded answers (Ollama, local run): ## Setup Requires Python 3.10+. python3 -m venv .venv .venv/bin/pip install -e ".[dev]" The default LLM provider is Ollama running locally: ollama serve ollama pull llama3.2:3b ## Run Index the corpus (writes an embedded Qdrant store under data/qdrant): .venv/bin/python scripts/ingest.py Start the API: .venv/bin/uvicorn supercoach.api.main:app --port 8000 Start the UI in another terminal: .venv/bin/streamlit run app/streamlit_app.py ## Swapping the LLM The provider is set in config/config.yaml (or via SUPERCOACH_LLM_PROVIDER / SUPERCOACH_LLM_MODEL env vars). Supported values: ollama, openai, gemini, mock. The cloud providers need `pip install -e ".[openai]"` or `".[gemini]"` plus the matching API key in .env (see .env.example). ## Evaluation A gold set of 41 questions lives in eval/datasets/qa_goldens.jsonl. The runner scores guardrail behaviour, retrieval (hit rate, recall, MRR), readability, and optionally faithfulness/relevancy/tone via LLM-as-judge: .venv/bin/python scripts/run_eval.py --provider mock --no-judge .venv/bin/python scripts/run_eval.py --provider ollama Reports are written to eval/results/. ## Tests .venv/bin/python -m pytest