Hadith AI

Arabic-first semantic search application for hadith collections, with optional Gemini-powered analysis.

Highlights

• Arabic UI focused on fast discovery of relevant hadiths.
• TF-IDF semantic retrieval with per-collection caching.
• Resilient remote loading (retry + graceful fallback on API errors).
• Safe HTML rendering for external/API/LLM content.
• Modern branded UI (Khalfa AI Solutions) with responsive layout.
• Search history and quick-topic shortcuts.

Tech Stack

• Python 3.10+
• Streamlit
• scikit-learn
• requests
• Google GenAI SDK (google-genai)

Project Structure

• app.py: Streamlit app and UI flow.
• hadith_core.py: Core logic (API loading, parsing, TF-IDF bundle, escaping).
• tests/test_hadith_core.py: Unit tests for core behavior.
• requirements.txt: Runtime dependencies.

Setup

pip install -r requirements.txt

Run

streamlit run app.py

Default URL:

• http://localhost:8501

Gemini Configuration

You can configure the Gemini API key in either way:

1. In-app sidebar input field.
2. Environment variable (recommended):

$env:GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
streamlit run app.py

Persistent on Windows:

setx GEMINI_API_KEY "YOUR_GEMINI_API_KEY"

Open a new terminal after setx.

Quota / 429 Handling

The app handles 429 RESOURCE_EXHAUSTED with:

• Friendly error messages.
• Temporary cooldown using retry delay when available.
• Clear guidance for billing/quota issues.

If your project shows limit: 0, update quota/billing or use another project key.

Tests

Run unit tests:

python -m unittest discover -s tests -p "test_*.py"

Branding Assets

If present, the app auto-loads brand images from:

• assets/khalfa-brand.png
• assets/khalfa-logo.png
• assets/brand-khalfa.png
• khalfa-brand.png
• khalfa-logo.png

Security Notes

• Do not hardcode API keys in source files.
• Rotate any key that has been shared in chat/screenshots.

License

Add your preferred license (MIT/Apache-2.0/etc.) in a LICENSE file.