TaitaCLIR

Semantic Multilingual Information Retrieval for the Taita Language

TaitaCLIR is a semantic search engine for market products. Users can search in plain English using a single keyword or a natural language description and retrieve the most relevant products with their names in English, Kiswahili, and Taita.

---

Project structure

TaitaCLIR/
├── .streamlit/
│   └── config.toml     # Streamlit customize theme
│
├── app.py              # Streamlit web interface (entry point)
├── loader.py           # Data loading & validation
├── embedder.py         # Sentence embedding generation
├── indexer.py          # FAISS index builder
├── retriever.py        # Query encoding & top-K retrieval
├── build_index.py      # Offline pipeline runner (run once before app)
│
├── data/
│   └── products.csv    # Dataset: english, swahili, taita, description, category, image
│
├── images/             # Product images (filename matches the image column in CSV)
│
├── embeddings/         # Auto-generated by build_index.py (do not edit manually)
│   ├── embeddings.npy
│   └── faiss.index
│
├── ui/   
│   └── style.py        # Customize CSS 
│   └── components.py   # Customize CSS w/ custom objects
│
├── requirements.txt
└── README.md

---

Setup

1. Clone and enter the project

git clone git@github.com:jomboi8/TaitaCLIR.git
cd TaitaCLIR

2. Create a virtual environment (recommended)

python -m venv venv
source venv/bin/activate        # Linux / macOS
venv\Scripts\activate           # Windows

3. Install dependencies

pip install -r requirements.txt

4. Add your product data

Edit data/products.csv. Required columns:

Column	Description
id	Unique integer
english	English product name
swahili	Kiswahili translation
taita	Taita translation
description	English description (used for semantic matching)
category	Product category (fruit, vegetable, grain, metadata for filtring)
image	Relative path to image file, e.g. images/coconut.jpg

5. Add product images

Place image files in the images/ folder. File names must match the image column in the CSV.

6. Build the index (run once)

python build_index.py

This generates embeddings/embeddings.npy and embeddings/faiss.index.
Re-run with --force whenever you update the dataset:

python build_index.py --force

7. Launch the app

streamlit run app.py

The app opens in your browser at http://localhost:8501.

---

Example queries

Query	Expected top results
coconut	Coconut
red juicy fruit	Tomato, Watermelon
green leafy vegetable	Spinach, Kales
starchy root	Cassava, Sweet potato, Arrow root
tropical fruit	Mango, Banana, Pawpaw

---

How it works

User Query
    ↓
Sentence Transformer  (paraphrase-multilingual-MiniLM-L12-v2)
    ↓
Query Embedding  (384-dim vector)
    ↓
FAISS Cosine Search  (IndexFlatIP on L2-normalised vectors)
    ↓
Top-K Results
    ↓
Streamlit Display  (image · English · Kiswahili · Taita · description · score)

---

Module reference

File	Purpose
loader.py	load_products(csv_path) → validated DataFrame
embedder.py	generate_embeddings(df) → saves & returns ndarray
indexer.py	build_index(embeddings) → saves & returns FAISS index
retriever.py	Retriever().search(query, k) → list of result dicts
build_index.py	Offline runner: loader → embedder → indexer
app.py	Streamlit UI: search box → retriever → result cards

---

Extending the dataset

1. Add new rows to data/products.csv
2. Add the corresponding images to images/
3. Run python build_index.py --force
4. Restart the Streamlit app

No code changes required.

---

License

Licensed under MIT