README.md

metadata

title: CO SDG Mapper API
emoji: 🌍
colorFrom: green
colorTo: blue
sdk: docker
pinned: false

CO → SDG Mapping API v2

OBEP ERP | NBA / NAAC / ABET Compliance Module

Maps Course Outcome (CO) statements to UN Sustainable Development Goals using semantic similarity. Generates formal, accreditation-ready justifications for NBA/NAAC/ABET audit documentation.

Model: all-mpnet-base-v2 (fine-tunable — see training pipeline) Data: UN Global Indicator Framework, Post-2025 Review (A/RES/71/313) Coverage: 17 SDGs · 122 Targets · 196 Indicators

---

Authentication

All mapping and feedback endpoints require an API key passed as a header:

X-API-Key: your-secret-key

Set your key as a HuggingFace Space Secret: Settings → Variables and Secrets → New Secret → Name: API_KEY → Value: your-key

---

Endpoints

Method	Endpoint	Auth	Description
POST	/map	✅	Map a single CO
POST	/batch	✅	Map up to 50 COs at once
POST	/feedback	✅	Submit faculty correction
GET	/feedback/stats	✅	Correction statistics
GET	/sdgs	❌	List all 17 SDGs
GET	/sdgs/{key}	❌	Single SDG detail
GET	/sdg-wheel	❌	SDG wheel data for UI
GET	/health	❌	Health check
GET	/docs	❌	Swagger UI

---

POST /map

curl -X POST https://<your-space>.hf.space/map \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "course_outcome": "Students will be able to design energy-efficient IoT systems for smart cities using renewable energy sources.",
    "faculty_override": null
  }'

Response:

{
  "course_outcome": "...",
  "mapped_sdg": {
    "goal": "SDG 7 – Affordable and Clean Energy",
    "confidence_score": 0.7821,
    "confidence_level": "HIGH",
    "confidence_explanation": "CO vocabulary closely mirrors official SDG indicator language."
  },
  "mapped_targets": ["7.3", "7.b"],
  "mapped_indicators": [
    "7.3.1 – Energy intensity measured in terms of primary energy and GDP",
    "7.b.1 – Installed renewable energy-generating capacity in watts per capita"
  ],
  "secondary_sdgs": [
    { "goal": "SDG 9 – Industry, Innovation and Infrastructure", "confidence_score": 0.6412 }
  ],
  "justification": "The course outcome — '...' — demonstrates a strong and direct alignment...",
  "override_applied": false,
  "override_note": null,
  "request_id": "a3f2b1c4"
}

---

POST /batch

curl -X POST https://<your-space>.hf.space/batch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "course_outcomes": [
      "Students will design wastewater treatment systems.",
      "Students will analyse ICT skills for employment."
    ],
    "faculty_overrides": [null, null]
  }'

---

POST /feedback

curl -X POST https://<your-space>.hf.space/feedback \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "co_text": "Students will design wastewater treatment systems.",
    "correct_sdg_key": "SDG6",
    "incorrect_sdg_key": "SDG3",
    "accepted": false,
    "faculty_name": "Dr. Sharma",
    "course_code": "CE401"
  }'

---

Using from Next.js / React

Create a shared API client utility (lib/sdgApi.js):

const BASE_URL = process.env.NEXT_PUBLIC_SDG_API_URL;
const API_KEY  = process.env.SDG_API_KEY; // server-side only

export async function mapCO(courseOutcome, facultyOverride = null) {
  const res = await fetch(`${BASE_URL}/map`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({
      course_outcome: courseOutcome,
      faculty_override: facultyOverride,
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

export async function mapBatch(courseOutcomes, overrides = null) {
  const res = await fetch(`${BASE_URL}/batch`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify({
      course_outcomes: courseOutcomes,
      faculty_overrides: overrides,
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

export async function submitFeedback(payload) {
  const res = await fetch(`${BASE_URL}/feedback`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": API_KEY,
    },
    body: JSON.stringify(payload),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

export async function getSDGWheel() {
  const res = await fetch(`${BASE_URL}/sdg-wheel`);
  return res.json();
}

Add to .env.local:

NEXT_PUBLIC_SDG_API_URL=https://<your-username>-co-sdg-mapper-api.hf.space
SDG_API_KEY=your-secret-key

---

Deployment Checklist

Files to push to HF Space:
  ✅ app.py
  ✅ Dockerfile
  ✅ requirements.txt
  ✅ README.md
  ✅ sdg_data.json
  ✅ indicator_corpus.pkl        ← generated by Colab training script
  ✅ indicator_embeddings.npy    ← generated by Colab training script

Optional (after fine-tuning):
  ✅ finetuned_model/            ← download from Colab as zip, unzip here

HF Space Settings:
  ✅ SDK: Docker
  ✅ Secret: API_KEY = your-secret-key