README.md

---
title: Maria Learning Service
emoji: 📚
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: mit
---

# Maria Learning Service

A FastAPI-based AI tutoring service powered by Qwen2.5-1.5B-Instruct (float16, CPU-preloaded) with ZeroGPU.

## Endpoints

| Endpoint   | Method | Description                                              |
|------------|--------|----------------------------------------------------------|
| `/dataset` | POST   | Pre-load FAISS index + metadata for a board/class/subject |
| `/chat`    | POST   | Main tutoring endpoint (requires `/dataset` called first) |
| `/health`  | GET    | Health check                                             |

## Workflow

**Always call `/dataset` before `/chat`.**  
`/dataset` loads and caches the knowledge base for the requested board/class/subject.  
`/chat` performs RAG against the cached dataset and runs inference.

## Authentication

Pass **one** of these headers per request:

| Header | Description |
|--------|-------------|
| `auth_code` | Raw value whose SHA-256 must match `HASH_VALUE` secret |
| `cf-turnstile-token` | Cloudflare Turnstile token verified against `CF_SECRET_KEY` secret |

## Secrets Required

Set these in your Space → Settings → Secrets:

- `HASH_VALUE` — SHA-256 hex digest of your auth code
- `CF_SECRET_KEY` — Cloudflare Turnstile secret key

## `/dataset` Reference

**Request**
```json
{
  "board": "NCERT",
  "class": "Class 1",
  "subject": "English"
}
```

**Response**
```json
{
  "status": "ready",
  "message": "Dataset Loaded"
}
```

Repeated calls with the same `board/class/subject` are no-ops (served from cache).  
Returns `412 Precondition Failed` from `/chat` if `/dataset` has not been called first.