jerry-theengineer/afri-tales-

AfriTales AI is an platform that uses a database and Google's Gemma 4 to preserve, teach African folklore history and stories # AfriTales AI — Frontend A Gradio Blocks interface for the AfriTales AI RAG pipeline (Intent Detection → Metadata Filtering → ChromaDB Semantic Search → Gemma 4 Response Generation). ## Files - **`app.py`** — the entire UI. This is the only file you should need to touch for layout/styling changes. It does not contain any retrieval or generation logic. - **`backend.py`** — a **mock stub** standing in for your real pipeline, so the app runs end-to-end right now with sample stories (Moremi Ajasoro, Queen Amina, Sundiata Keita, Bayajidda, Sango, the Yoruba creation myth). ## Running it as-is (with the mock backend) ```bash pip install -r requirements.txt python app.py ``` Then open the local URL Gradio prints (defaults to `127.0.0.1`). ## Connecting your real backend Your real pipeline just needs one function with this exact contract: ```python def ask(question: str, exclude_story_id: str | None = None) -> dict: return { "answer": "...", # markdown string "story_id": "...", # unique id for the matched story "related_stories": [ # 4-5 items {"id": "...", "title": "..."}, ... ], "metadata": { "country": "...", "region": "...", "ethnic_group": "...", "genre": "...", "themes": "...", "historical_period": "...", "moral": "...", }, "sources": ["Oral Tradition", "Dataset Entry #...", "Nigeria"], } ``` Then in `app.py`, change: ```python from backend import ask ``` to: ```python from your_rag_pipeline import ask ``` That's it — nothing else in `app.py` needs to change. `exclude_story_id` is only used by the "🔄 Another Version" button, so your retriever should filter that id out of the ChromaDB results when it's provided. ## Notes on how the UI is wired - **Loading state**: every ask-triggered handler is a Python generator. It yields once immediately with a "🌀 Consulting the archives..." placeholder bubble, then yields again once `ask()` returns — so the chat updates twice per question with no page reload. - **Related-story …