IQES School Quality Dashboard Assistant

Expert guidance for working with a professional German educational evaluation dashboard that analyzes IQES (Instrumente für die Qualitätsentwicklung und Evaluation an Schulen) school quality data using Streamlit and AI-powered insights.

Repository Context

This is a specialized application for German educational institutions that processes IQES evaluation data. The dashboard provides comprehensive analysis of school quality metrics, comparing different educational programs (BM - Büromanagement vs VK - Veranstaltungskaufleute) and generating AI-powered recommendations.

**Key technologies:** Streamlit, pandas, plotly, scikit-learn, OpenAI API, openpyxl

Application Architecture

Main Components

1. **SchulqualitätsDashboard** (`dashboard.py:109`)

- Main dashboard class with IQES-specific data processing

- Handles Excel file parsing with proper IQES structure recognition

- Processes multi-sheet evaluations (Antwortskala, Offene Frage, Einfachauswahl)

2. **KI_Schulqualitäts_Analyzer** (`dashboard.py:492`)

- AI-powered analysis engine

- German text processing with sentiment analysis

- OpenAI integration for advanced insights

IQES Data Structure

The application processes standard IQES Excel exports with specific sheet types:

- Scale: 1 = "trifft nicht zu" to 4 = "trifft zu"

- Column J: Pre-calculated averages (primary metric)

- Column K: Response counts (N values)

- Columns B,D,F,H: Response distribution counts

- German sentiment analysis

- Keyword extraction with German stopwords

Scoring Logic

Development Guidelines

Running the Application

**Quick start:**

```bash

chmod +x start_dashboard.sh

./start_dashboard.sh

```

**Manual setup:**

```bash

Install dependencies

./install_requirements.sh

Start dashboard

streamlit run dashboard.py

```

**Enable AI features (optional):**

```bash

export OPENAI_API_KEY='your-api-key'

streamlit run dashboard.py

```

File Naming Conventions

Key Dependencies

```

streamlit>=1.28.0 # Web framework

pandas>=1.5.0 # IQES data processing

plotly>=5.15.0 # Interactive visualizations

scikit-learn>=1.3.0 # ML clustering

openai>=1.0.0 # German text analysis (optional)

openpyxl>=3.1.0 # Excel file processing

```

Core Features

1. IQES-Compliant Data Extraction

2. German Text Analysis

3. AI-Powered Recommendations

4. Multi-Program Comparison

5. Temporal Trend Analysis

Coding Standards

When Adding Features

1. **Maintain German localization** - All UI text, labels, and outputs must be in German

2. **Respect IQES data structure** - Never assume column positions; always use column J for averages, column K for N values

3. **Handle malformed files gracefully** - Include try/except blocks with user-friendly German error messages

4. **Preserve professional styling** - Follow existing CSS patterns for educational reporting standards

Error Handling

Always wrap IQES file processing in error handlers:

```python

try:

# IQES data processing

except Exception as e:

st.error(f"Fehler beim Verarbeiten der IQES-Datei: {str(e)}")

```

German Text Processing

When working with text analysis:

Common Tasks

Adding a New Analysis Type

1. Create new method in `SchulqualitätsDashboard` class

2. Follow IQES column mapping (J=average, K=count)

3. Add German UI labels in Streamlit sidebar

4. Update CSS if new visualization types are needed

Modifying AI Recommendations

1. Edit `KI_Schulqualitäts_Analyzer.generiere_handlungsempfehlungen()`

2. Adjust critical thresholds (currently <2.5 for high priority)

3. Update German prompt templates for OpenAI calls

4. Test with real IQES data files

Extending Visualizations

1. Use plotly for consistency

2. Apply German labels and tooltips

3. Use professional color scheme (matching existing charts)

4. Ensure mobile responsiveness

Important File References

Notes

Best Practices

1. **Always test with real IQES files** before deploying changes

2. **Preserve backward compatibility** with existing IQES export formats

3. **Document German terminology** when adding new features

4. **Consider educational context** in all UI/UX decisions

5. **Optimize for non-technical users** (school administrators)