NeuroNauts 🧠🚀

Advanced AI Learning Companion for Psychology
Engineered for the OpenStax Psychology 2e Textbook

---

📖 Overview

NeuroNauts is a state-of-the-art interactive learning platform designed to revolutionize how students interact with complex academic material. By leveraging a Cloud-Native Retrieval-Augmented Generation (RAG) architecture, it transforms the OpenStax Psychology 2e textbook into a dynamic, conversational knowledge base.

Unlike standard LLMs which frequently hallucinate or confidently invent incorrect academic facts, NeuroNauts provides hallucination-free answers by grounding every single response in highly-specific textbook segments. It rapidly serves high-quality Generation via Groq, accurate dense vector search via Zilliz Cloud, and seamlessly renders contextual infographics, charts, and scientific illustrations directly via Cloudinary.

---

✨ Key Features

Feature	Description
🏥 PsychLab Clinical Case Simulator	Interactive patient persona consultations for clinical psychology cases with automated OpenStax & DSM-5 diagnostic rubric grading.
🎯 Active Recall Study Hub	Adaptive AP & College-level quiz generation with distractor explanations, active recall tracking, and interactive mechanism flashcards.
🔍 Hybrid Retrieval Engine	High-precision Reciprocal Rank Fusion (RRF) combining Dense Vector Search on Zilliz Cloud with BM25 keyword matching for optimal academic recall.
📊 Enterprise RAG Triad Evaluation	Evaluates Faithfulness (sentence-level claim verification), Answer Relevancy, Context Precision (signal-to-noise ratio), and Context Recall.
🖼️ Intelligent Image Lightbox	Extracts charts, brain scans, and diagrams from the textbook and serves them via high-speed Cloudinary CDN alongside grounded answers.
🗺️ Interactive D3 Knowledge Graph	Dynamic hierarchical visualization of chapters and section chunk distributions with real-time topic filtering.
🛡️ Resilient Architecture	Built on Groq (Llama-3.3-70b), Zilliz Cloud, and Streamlit with comprehensive UI fallback sentinels for 401, 429, and 500 API states.

---

🏗️ Detailed Architecture

NeuroNauts evolved from a local-prototyped RAG into a highly-scalable cloud MVP. The system handles Ingestion, Retrieval, and Generation over distributed nodes to ensure millisecond-level inference times.

graph TD
    subgraph "1. Engineering & Ingestion Scripts (One-Time Execution)"
        A[Psychology 2e PDF] --> B[Docling Parser]
        B --> C[Section-Aware Chunking]
        C -->|Raw Images via PyMuPDF| D[Upload to Cloudinary CDN]
        C -->|Text via SentenceTransformers| E[Push to Zilliz Cloud DB]
        D --> F(image_url_map.json)
        F --> G[fix_image_refs.py aligner]
    end

    subgraph "2. Cloud-Native Retrieval Engine (App)"
        H[User Query] --> I[Context Window Management]
        I --> J[Zilliz Dense Vector Search]
        J --> K[Top-K Segment Extraction]
        K --> L[Extract Cloudinary Image URLs]
    end

    subgraph "3. Contextual Generation & UI"
        K --> M[Context Packaging]
        M --> N[Groq API: Llama-3.3-70b]
        N --> O[Streamlit UI Chatbot]
        L --> O
        O --> P[Frontend Error Sentinel Catching]
    end

Loading

---

🚀 Quick Start

1. Prerequisites

• Python 3.10+
• Keys for the following infrastructure:
  • Groq API (For lightning-fast LLM generation)
  • Zilliz Cloud (For Serverless Vector Search)
  • Cloudinary (For Cloud Image CDN hosting)

2. Installation

# Clone the repo
git clone https://github.com/Omen-bit/WCEHackathon2026_NeuroNauts.git
cd WCEHackathon2026_NeuroNauts

# Create and activate environment
python -m venv .venv
# Windows: .venv\Scripts\activate
# Mac/Linux: source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Configuration

Create a .env file in the root directory and populate it with your cloud credentials:

# --- GROQ (LLM Gen) ---
GROQ_API_KEY="your-groq-key"
GROQ_MODEL="llama-3.3-70b-versatile"

# --- CLOUDINARY (Images) ---
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-key"
CLOUDINARY_API_SECRET="your-secret"

# --- ZILLIZ (Vector DB) ---
ZILLIZ_URI="https://your-zilliz-cluster.cloud.zilliz.com"
ZILLIZ_TOKEN="your-zilliz-token"

4. Running the App

streamlit run app/app.py

---

📚 Use Your Own Textbook!

Want to use NeuroNauts for a different textbook? It's incredibly easy to adapt our custom engineering pipeline for any PDF.

1. Add Your Book: Place your new PDF in the data/ or root directory.
2. Run the Ingestion Pipeline:

   python pipeline/run_pipeline.py path/to/your_textbook.pdf

   This uses Docling to intelligently chunk your book specifically by academic headings, and uses PyMuPDF to rip out all the native high-res images to an extracted_images/ folder.
3. Upload Assets to CDN:

   python scripts/upload_images_to_cloud.py

   This securely streams your newly extracted textbook images into Cloudinary.
4. Push to Vector DB:

   python scripts/migrate_to_zilliz.py
   python scripts/fix_image_refs.py

   This connects the generated cloud URLs to your dense vector DB chunks and pushes everything securely to Zilliz.
5. Start Chatting: Your app is now an expert on your unique textbook!

---

📁 Project Structure

WCEHackathon2026_NeuroNauts/
├── app/                        # Streamlit Frontend & Multi-Mode Modules
│   ├── app.py                  # Main App, Multi-Mode Navigation & UI
│   ├── eval_suite.py           # Enterprise RAG Triad Multi-Metric Evaluation Engine
│   ├── psych_lab.py            # Clinical Case Simulator & Diagnostic Rubric Evaluator
│   ├── study_hub.py            # Active Recall Flashcards & Adaptive Quiz Generator
│   ├── knowledge_graph.py      # D3.js Interactive Knowledge Graph Visualizer
│   ├── retrieve.py             # Hybrid Dense (Zilliz) + BM25 RRF Retrieval Engine
│   ├── generate.py             # Groq Llama-3.3-70b Grounded Generation Layer
│   └── headless_eval.py        # Automated CLI Benchmark & Evaluation Script
├── pipeline/                   # Automated PDF Ingestion Pipeline
│   └── (Docling Parsers, PyMuPDF extractors, Recursive Chunking)
├── scripts/                    # Infrastructure Migration & Cleanup Toolkit
│   ├── migrate_to_zilliz.py    # Uplift script for moving local DB to Zilliz
│   ├── upload_images_to_cloud.py # Asset migration to Cloudinary
│   └── fix_image_refs.py       # Cloud DB JSON string serialization rectifier
├── queries.json                # Standardized testing queries
└── requirements.txt            # Modern, cloud-native project dependencies

---

🤝 Contributing

This project was built for the WCE Hackathon 2026 by Team NeuroNauts. We follow the MIT License and welcome community feedback.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

---

Made with ❤️ by Team NeuroNauts