README.md

# ---
# title: "Learning Outcome OS — AI Service"
# emoji: "🤖"
# colorFrom: "blue"
# colorTo: "purple"
# sdk: docker
# app_file: Dockerfile
# pinned: false
# ---

# LearningOutcomeOS-AI-V2

AI inference service for Learning Outcome OS — a school intelligence platform that converts classroom data into outcome-based learning intelligence. This repository is designed to deploy as a Hugging Face Docker Space for a production-ready API.

**Version:** 2.0.0

## Which Hugging Face Space to create

Create a **Docker Space**.

Recommended options:
- Runtime: **Docker**
- Hardware: **CPU** (free tier is sufficient for scikit-learn models)
- Port: **7860** (Hugging Face Spaces standard)

> Do not create a Gradio or Static Space. This service requires a Docker Space because it runs a FastAPI backend with Python dependencies and custom runtime configuration.

## Clean HF deployment plan

1. Create a new Hugging Face Space as a Docker Space.
2. Clone the HF Space repository locally:

```bash
git clone https://huggingface.co/spaces/<your-username>/<your-space-name>.git
cd <your-space-name>
```

3. Copy the contents of `AI_Services_V2/` into the space repository root.
4. Add trained model artifacts under `artifacts/models/`.
5. Add the dataset under `learning_outcome_os_dataset_v2/` if runtime dataset-backed endpoints are required.
6. Commit and push:

```bash
git add .
git commit -m "Deploy LearningOutcomeOS-AI-V2 to Hugging Face Space"
git push
```

## Repository structure for the HF Space

The space should contain:
- `Dockerfile`
- `requirements.txt`
- `README.md`
- `app/`
- `scripts/`
- `artifacts/models/` (trained `.joblib` models)
- `learning_outcome_os_dataset_v2/` (dataset files, if needed)

## Runtime configuration

This repository is configured to use Hugging Face persistent storage under `/data`:
- `MODEL_ARTIFACT_DIR=/data/artifacts/models`
- `DATASET_DIR=/data/learning_outcome_os_dataset_v2`
- `METRICS_DIR=/data/artifacts/metrics`
- `REPORTS_DIR=/data/artifacts/reports`
- `FEEDBACK_DIR=/data/artifacts/feedback`

These values are set by the `Dockerfile` and by the default application configuration.

## Deploying the Docker Space

The existing `Dockerfile` is already set up for HF Spaces. After you push the repo, the space will build and expose the API on port `7860`.

## API endpoints

The service exposes the following HTTP endpoints under `/ai/v2`:

- `GET /ai/v2/health` — health status and service success
- `GET /ai/v2/data/summary` — dataset metadata summary
- `GET /ai/v2/monitoring/model-health` — model health report
- `POST /ai/v2/tag-learning-outcome` — learning outcome tagging
- `POST /ai/v2/classify-bloom` — Bloom taxonomy classification
- `POST /ai/v2/predict-mastery` — mastery prediction
- `GET /ai/v2/risk/{student_id}` — risk prediction
- `GET /ai/v2/recommendations/{student_id}` — recommendations
- `GET /ai/v2/student-profile/{student_id}` — student profile
- `POST /ai/v2/evaluate-answer` — answer evaluation
- `GET /ai/v2/class-insights/{class_id}` — class insights
- `POST /ai/v2/teacher-feedback` — teacher feedback storage

## Verifying your deployed space

After push completes, verify with:

```bash
curl https://<your-space-name>.hf.space/ai/v2/health
```

A successful response should include `status: "ok"` and `models_loaded: true`.

## Local development notes

For local development, create a `.env` file based on `.env.example` and override paths as needed. In the Hugging Face Space, the Docker container already sets the required `/data` paths.

## Notes

- Keep the HF Space repo clean: only `app/`, `requirements.txt`, `Dockerfile`, and the required artifacts/dataset.
- Avoid pushing the old `aaa/`, `AI_Services/`, or `HF_SPACE_FILES/` directories into the new space.
- If training scripts are not required in production, they can remain outside the HF deployment repo.