itslikethisnow/hsba-rag-chat

HSBA AI Data Assistant

An intelligent RAG-powered chatbot for analyzing High School Student Assessment (HSBA) data. This application provides conversational access to comprehensive educational assessment data through natural language queries.

Features

• —Task-Specific Analysis: Select any HSBA task for focused data analysis
• —Comprehensive Data Processing: Analyzes demographics, performance patterns, time statistics, and factor scores
• —Natural Language Queries: Ask questions in plain English about student data
• —Educational Insights: Get expert-level analysis of assessment patterns and trends
• —Secure Data Handling: Connects to private HSBA backend API for data access

How It Works

1. 1.Data Integration: Connects to the HSBA backend API to fetch comprehensive task documents
2. 2.Document Processing: Uses Haystack to chunk and embed educational data for retrieval
3. 3.Intelligent Retrieval: Finds relevant data sections based on user questions
4. 4.Expert Analysis: Uses large language models to provide educational insights

Usage

For Hugging Face Spaces Deployment

1. 1.Environment Variables Required:
2. 2.HF_TOKEN: Hugging Face API token for model access
3. 3.BACKEND_URL: URL of the HSBA backend API (defaults to itslikethisnow-hsba-backend-api.hf.space)

1. 1.Getting Started:
2. 2.Select a task from the dropdown
3. 3.Click "Generate Analysis Document" to load data
4. 4.Start asking questions about student performance

Example Questions

• —"What are the key demographic patterns in this task?"
• —"How did different grade levels perform?"
• —"Are there any concerning performance gaps by gender or race?"
• —"What were the most common response patterns?"
• —"What insights can you provide about student engagement?"
• —"How does completion time vary by demographic groups?"

Architecture

• —Frontend: Gradio interface for user interaction
• —RAG Engine: Haystack pipeline for document retrieval and generation
• —Embeddings: SentenceTransformers for semantic search
• —LLM: Meta-Llama-3.1-8B-Instruct for response generation
• —Data Source: Private HSBA backend API

Security & Privacy

• —All educational data remains within secure research environments
• —Private backend API requires authentication
• —No sensitive student data is stored in this public interface
• —Data processing follows educational research privacy guidelines

Technical Details

Dependencies

• —Gradio 4.0+ for web interface
• —Haystack 2.0+ for RAG pipeline
• —SentenceTransformers for embeddings
• —Hugging Face Transformers for LLM access

Data Processing Pipeline

1. 1.Fetch comprehensive task documents from HSBA API
2. 2.Clean and split documents into semantic chunks
3. 3.Generate embeddings for similarity search
4. 4.Store in in-memory vector database
5. 5.Retrieve relevant chunks for user queries
6. 6.Generate contextual responses with educational insights

Integration with HSBA Dashboard

This RAG assistant integrates with the main HSBA Data Dashboard:

• —Accessible through the "AI Chat" tab in the dashboard
• —Seamless task selection and data synchronization
• —Consistent authentication and security model
• —Complementary to existing statistical analysis tools

Development

To run locally:

1. 1.Set environment variables (HF_TOKEN, BACKEND_URL)
2. 2.Install requirements: pip install -r requirements.txt
3. 3.Run: python app.py

Support

This tool is designed for educational researchers and assessment professionals working with HSBA data. For technical support or feature requests, please contact the development team.