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:

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:

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:

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.