title	Education Graph RAG
emoji	🎓
colorFrom	blue
colorTo	indigo
sdk	docker
app_port	7860
pinned	false

Neo4j AuraDB Education Graph RAG

This project is a Gemini-powered RAG chatbot for education platforms. It uses Neo4j AuraDB as both the knowledge graph and vector retrieval layer:

• Book -> Chapter -> Chunk graph structure
• Neo4j vector index for semantic retrieval
• Neo4j full-text index for keyword retrieval
• Reciprocal Rank Fusion for hybrid search
• Gemini API for grounded answers
• FastAPI backend and Streamlit chat UI

Project Structure

• config.py - environment settings
• graph.py - Neo4j driver and embedding model helpers
• data_sources.py - public-domain book manifest
• ingest.py - downloads books, chunks them, embeds them, and writes the graph
• search.py - vector + keyword hybrid retrieval
• generate.py - Gemini prompt and answer generation
• api.py - FastAPI backend
• streamlit_app.py - Streamlit UI
• chatbot.py - terminal chatbot
• app.py - Neo4j/model connectivity check

Setup

pip install -r requirements.txt
cp .env.example .env

Fill .env with your Neo4j AuraDB credentials and Gemini API key.

Ingest Education Books

The default ingestion downloads public-domain books from Project Gutenberg and stores them as graph nodes with vector embeddings.

python ingest.py

For a quick smoke test:

python ingest.py --book elements-style --max-chunks-per-book 10

To rebuild the graph data created by this project:

python ingest.py --clear

Run the Backend

uvicorn api:app --reload

Health check:

curl http://localhost:8000/health

Chat:

curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"How can I write more clearly?","limit":5}'

Run the Streamlit UI

In a second terminal:

streamlit run streamlit_app.py

The UI calls the FastAPI backend at http://localhost:8000 by default.

Hybrid Search Flow

1. Embed the user query with all-MiniLM-L6-v2.
2. Retrieve vector candidates from Neo4j's chunk_vector index.
3. Retrieve lexical candidates from Neo4j's chunk_keyword full-text index.
4. Fuse both rankings with Reciprocal Rank Fusion.
5. Send the top chunks, with book/chapter graph metadata, to Gemini.
6. Return an answer with source citations.

Environment Variables

NEO4J_URI=neo4j+s://your-aura-host.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-2.5-flash

Optional tuning:

CHUNK_SIZE_WORDS=220
CHUNK_OVERLAP_WORDS=45
VECTOR_K=12
KEYWORD_K=12
FINAL_K=5
RRF_K=60

Docker & Hugging Face Spaces Deployment

The project includes containerization files (Dockerfile and start.sh) to run both the FastAPI backend and Streamlit UI in a single container.

Local Docker Testing

1. Build the image:

   docker build -t education-rag .

2. Run the container:

   docker run -p 7860:7860 --env-file .env education-rag

3. Open http://localhost:7860 in your browser.

Hugging Face Spaces Deployment

1. Create a new Space on Hugging Face, select Docker as the SDK, and choose the Blank template.
2. In the Space's Settings tab, add your credentials as Secrets:
   • NEO4J_URI
   • NEO4J_USERNAME
   • NEO4J_PASSWORD
   • GEMINI_API_KEY
   • GEMINI_MODEL (value: gemini-2.5-flash)
3. Clone the Space's Git repository, copy the project files in (do not include venv or .env), commit, and push.

Notes

• Neo4j AuraDB must support vector indexes.
• The first run may download the sentence-transformer model.
• --clear only deletes nodes labeled Book, Chapter, Chunk, or Topic.