jerry-theengineer/afri-tales-
Domain:
natural language processingRecord type:
softwareproject
Creator:
jer
Host:
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 …