README.md

---
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

```bash
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:**
```json
{
  "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

```bash
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

```bash
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`):

```javascript
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
```