README.md

---
title: GraphWiz Ireland
emoji: 🍀
colorFrom: green
colorTo: yellow
sdk: streamlit
sdk_version: "1.36.0"
app_file: src/app.py
pinned: false
license: mit
---

# 🍀 GraphWiz Ireland - Advanced GraphRAG Q&A System

Intelligent question-answering about Ireland using GraphRAG, hybrid search, and Groq LLM.

## Features
- 📚 Comprehensive Wikipedia knowledge base (10,000+ articles, 86K+ chunks)
- 🔍 Hybrid search (HNSW semantic + BM25 keyword)
- 🧠 GraphRAG with community detection (16 topic clusters)
- ⚡ Sub-second responses via Groq API (Llama 3.3 70B)
- 📊 Citation tracking and confidence scores
- 💾 Intelligent caching for instant repeated queries

## How it works
1. **Data:** ALL Ireland-related Wikipedia articles extracted
2. **Processing:** Text chunking with entity extraction (spaCy)
3. **GraphRAG:** Hierarchical knowledge graph with community detection
4. **Search:** HNSW semantic (98% accuracy) + BM25 keyword fusion
5. **Generation:** Groq LLM for natural answers with citations

## Example Questions

- What is the capital of Ireland?
- Tell me about the Easter Rising
- Who was Michael Collins?
- What are the provinces of Ireland?
- Explain Irish mythology and the Tuatha Dé Danann

## Configuration

The app has a sidebar with these settings:
- **top_k**: Number of chunks to retrieve (3-15, default: 5)
- **semantic_weight**: Semantic vs keyword balance (0-1, default: 0.7)
- **use_community_context**: Include topic summaries (default: True)

## Technical Stack

Built with:
- **Streamlit** - Interactive web interface
- **HNSW** (hnswlib) - Fast approximate nearest neighbor search
- **spaCy** - Named entity recognition and text processing
- **Groq** - Ultra-fast LLM inference
- **NetworkX** - Graph algorithms for community detection
- **Sentence Transformers** - Text embeddings

## License

MIT License

---

**Note:** This space requires a `GROQ_API_KEY` secret to be configured in Settings → Repository secrets. Get your free API key at https://console.groq.com/