README.md

---
title: ClassLens
emoji: 📊
colorFrom: green
colorTo: pink
sdk: docker
license: mit
---

# 📊 ClassLens

**AI-powered exam analysis that transforms Google Form quiz responses into beautiful, actionable reports for teachers.**

## ✨ Features

- 🔗 **Google Forms Integration**: Paste your Google Form response sheet URL
- 📈 **Automatic Grading**: Compare student answers to your answer key
- 📊 **Visual Statistics**: Interactive charts showing score distribution and per-question accuracy
- 🎯 **Detailed Explanations**: Bilingual (English + 中文) explanations for each question
- 👥 **Peer Learning Groups**: AI-suggested groupings for collaborative learning
- 📧 **Email Reports**: Send beautiful HTML reports directly to your inbox
- 🎨 **Beautiful Reports**: Dark theme with Chart.js visualizations

## 🚀 How to Use

1. **Paste your Google Form URL** (the response spreadsheet, not the form itself)
2. **Provide your email** (for receiving the report)
3. **Optionally add answer key** if not embedded in the form
4. **Click analyze** and watch the AI work!

## 🌿 Development and Deployment Workflow

GitHub is the source of truth for development. The two long-lived branches have separate deployment targets:

| GitHub branch | Automation | Destination | Purpose |
|---|---|---|---|
| `staging` | GitHub Action `deploy-hf-staging.yml` | [Hugging Face Space](https://huggingface.co/spaces/taboola-cz/ClassLensPortal) | Preview and acceptance testing |
| `main` | GCP Cloud Build trigger `class-lens-portal-main` | [Cloud Run production](https://class-lens-portal-370359340770.asia-east1.run.app) | Production |

```text
feature branch → staging → Hugging Face preview
                         ↓ approve
                       main → GCP Cloud Run production
```

### Standard change flow

1. Update local `staging`, then create a feature branch:

   ```bash
   git switch staging
   git pull origin staging
   git switch -c feature/<short-name>
   ```

2. Commit and push the feature branch, then open a pull request into `staging`.
3. After merge, GitHub automatically pushes `staging` to the HF Space for review.
4. Once the HF preview is approved, open and merge a pull request from `staging` into `main`.
5. The GCP trigger builds the root `Dockerfile`, stores the image in Artifact Registry, and updates only the Cloud Run service `class-lens-portal`.

### Deployment boundaries

- Only `staging` updates the HF Space; pushes to `main` do not run the HF workflow.
- Only `main` updates GCP production; feature and `staging` pushes do not deploy to Cloud Run.
- `class-lens-portal` has its own Cloud Run service, trigger, image path, and Secret Manager resources. It does not update `sel-chat-coach`.
- GitHub stores the HF write credential as the `HF_TOKEN` Actions secret. Runtime credentials remain in GCP Secret Manager and must never be committed.

## 🔐 Privacy

- Student names are displayed in full in reports for internal teacher use
- No data is stored permanently
- OAuth tokens are encrypted

## 🛠️ Tech Stack

- **Frontend**: React + Vite + TailwindCSS
- **Backend**: FastAPI + OpenAI ChatKit
- **Charts**: Chart.js
- **AI**: GPT-4.1-mini

## 📝 Example Report Sections

### 📝 Q&A Analysis (題目詳解)
- Reading passages with highlighted key terms
- Per-question explanations with concept tags
- Common mistakes and solving strategies

### 📊 Statistics (成績統計)
- Score distribution bar chart
- Question accuracy doughnut chart
- Individual student performance table

### 👩‍🏫 Teacher Insights (教師建議)
- Overall performance analysis
- Teaching recommendations
- AI prompt for next quiz generation
- Individual student support suggestions

---

Built with ❤️ by [taboola-cz](https://huggingface.co/taboola-cz) for educators