README.md

---
title: Spandan AI API
emoji: 🫀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# Spandan AI API

**Version:** 1.0.0

REST API for AI-powered prediction of:

- Stress
- Physical Activity
- Focus
- Cognitive Engagement

The API is built using **FastAPI** and serves ONNX models using **ONNX Runtime**.

---

# Base URL

```
https://theanalyzer-spandan-api.hf.space
```

---

# Interactive API Documentation

Swagger UI:

```
https://theanalyzer-spandan-api.hf.space/docs
```

---

# Endpoints

## 1. Health Check

### Request

```http
GET /
```

### Response

```json
{
    "message": "Spandan API Running",
    "status": "healthy",
    "version": "1.0.0"
}
```

---

# 2. Stress / Physical Activity / Focus Prediction

Predicts the current state of an individual using **13 wearable sensor values**.

## Endpoint

```http
POST /predict/state
```

Full URL

```
https://theanalyzer-spandan-api.hf.space/predict/state
```

---

## Request

### Headers

```http
Content-Type: application/json
```

### Body

```json
{
    "sensor_values": [
        1.0,
        2.0,
        3.0,
        4.0,
        5.0,
        6.0,
        7.0,
        8.0,
        9.0,
        10.0,
        11.0,
        12.0,
        13.0
    ]
}
```

> **Note:** Exactly **13 sensor values** must be provided.

---

## Successful Response

```json
{
    "prediction": "Physical Activity",
    "confidence": 0.9999,
    "scores": {
        "Stress": 0.0000,
        "Physical Activity": 0.9999,
        "Focus": 0.0001
    }
}
```

---

## Response Fields

| Field | Type | Description |
|--------|------|-------------|
| prediction | string | Predicted class |
| confidence | float | Confidence of predicted class |
| scores | object | Confidence score for all classes |

### Possible Classes

- Stress
- Physical Activity
- Focus

---

# 3. Cognitive Engagement Prediction

Predicts whether an individual is **Engaged** or **Distracted** using **7 wearable sensor values**.

## Endpoint

```http
POST /predict/engagement
```

Full URL

```
https://theanalyzer-spandan-api.hf.space/predict/engagement
```

---

## Request

### Headers

```http
Content-Type: application/json
```

### Body

```json
{
    "sensor_values": [
        1.0,
        2.0,
        3.0,
        4.0,
        5.0,
        6.0,
        7.0
    ]
}
```

> **Note:** Exactly **7 sensor values** must be provided.

---

## Successful Response

```json
{
    "prediction": 1,
    "status": "Engaged"
}
```

or

```json
{
    "prediction": 0,
    "status": "Distracted"
}
```

---

## Response Fields

| Field | Type | Description |
|--------|------|-------------|
| prediction | integer | Model prediction (`1 = Engaged`, `0 = Distracted`) |
| status | string | Human-readable prediction |

---

# Error Responses

## Invalid Input

HTTP Status

```http
400 Bad Request
```

Example

```json
{
    "detail": "Expected exactly 13 sensor values, got 10"
}
```

---

## Internal Server Error

HTTP Status

```http
500 Internal Server Error
```

Example

```json
{
    "detail": "Model inference failed: <error details>"
}
```

---

# Python Example

```python
import requests

url = "https://theanalyzer-spandan-api.hf.space/predict/state"

payload = {
    "sensor_values": [
        1,2,3,4,5,6,7,8,9,10,11,12,13
    ]
}

response = requests.post(url, json=payload)

print(response.json())
```

---

# JavaScript Example

```javascript
const response = await fetch(
    "https://theanalyzer-spandan-api.hf.space/predict/state",
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json"
        },
        body: JSON.stringify({
            sensor_values: [
                1,2,3,4,5,6,7,8,9,10,11,12,13
            ]
        })
    }
);

const data = await response.json();

console.log(data);
```

---

# Notes

- All requests and responses use **JSON**.
- The `/predict/state` endpoint requires **exactly 13 sensor values**.
- The `/predict/engagement` endpoint requires **exactly 7 sensor values**.
- Sensor values **must be provided in the same order used during model training**.
- The API is stateless and can be called independently for each prediction.
- Interactive API documentation is available at:

```
https://theanalyzer-spandan-api.hf.space/docs
```

---

## Technology Stack

- FastAPI
- ONNX Runtime
- NumPy
- Python 3.11
- Hugging Face Spaces (Docker)

---

## Status

🟢 **Production Ready**