README.md

---
title: CogTraceEnv
emoji: 🧠
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
license: apache-2.0
short_description: OpenEnv RL environment for Alzheimer's cognitive monitoring
---

# CogTraceEnv 🧠

**An OpenEnv-compliant RL training environment for AI agents that monitor Alzheimer's patients.**

Built for the [Open Env Scalar × Hugging Face Hackathon](https://huggingface.co/spaces/huggingface-projects/openenv-hackathon).

## Live Demo

The interactive demo lets you step through a 30-day patient monitoring episode, choosing clinical actions day by day and receiving rewards based on your decisions.

## What It Is

CogTraceEnv simulates a synthetic Alzheimer's patient using a rule-based model calibrated to published CDR-scale research. An RL agent observes 5 daily behavioral signals and must decide when — and at what urgency level — to raise a clinical alert.

### Observation Space (10 features)
| Feature | Description |
|---|---|
| `typing_delay_delta` | Change in typing latency vs baseline (z-score) |
| `sleep_hours` | Hours of sleep last night |
| `routine_adherence_score` | Fraction of daily routine completed on time [0–1] |
| `speech_pause_freq` | Average speech pause frequency (pauses/min) |
| `memory_lapse_count` | Observed memory-lapse events today |
| `days_elapsed` | Days since episode start |
| `trend_typing_delay` | 7-day slope of typing delay |
| `trend_sleep` | 7-day slope of sleep hours |
| `trend_routine` | 7-day slope of routine adherence |
| `alerts_last_7_days` | Alerts raised in last 7 days (spam deterrent) |

### Action Space (4 discrete actions)
| Action | Label | Description |
|---|---|---|
| 0 | Do Nothing | Patient appears stable |
| 1 | Soft Alert | Flag for non-urgent review |
| 2 | Medium Alert | Schedule clinical check within 48h |
| 3 | Escalate | Immediate clinical intervention |

### Reward Structure
- Correct escalation during anomaly: **+1.0**
- Medium alert during anomaly: **+0.6**
- Soft alert during anomaly: **+0.3**
- Missed anomaly (silence during critical event): **−1.0**
- Unnecessary false alert: **−0.1 to −0.5**
- Alert spam penalty: **−0.15**

## Three Tasks

| Task | Difficulty | Description |
|---|---|---|
| `task1_easy` | Easy | Single-step stage classification (0–4) |
| `task2_medium` | Medium | Detect anomaly onset day within 7-step window |
| `task3_hard` | Hard | Full 30-step triage episode, scored by F1 + reward |

## API Endpoints (OpenEnv Spec)

```
POST /reset          → Initial observation
POST /step           → {observation, reward, done, info}
GET  /state          → Full environment state
GET  /tasks          → Available tasks
GET  /health         → {"status": "ok"}
GET  /openenv.yaml   → OpenEnv spec file
```

## Quick Start (Local)

```bash
git clone https://github.com/Sparsha2708/Alzheimers
cd Alzheimers
pip install -r requirements.txt
python app.py
# Open http://localhost:7860
```

## Usage with an Agent

```python
import httpx

base = "https://sparsha2708-alzheimers.hf.space"

# Start episode
obs = httpx.post(f"{base}/reset", json={"true_stage": 2, "seed": 42}).json()

# Step through
while True:
    action = my_agent(obs)  # 0–3
    result = httpx.post(f"{base}/step", json={"action": action}).json()
    obs = result["observation"]
    if result["done"]:
        break
```

## Citation

```
@misc{cogtraceenv2025,
  title  = {CogTraceEnv: An OpenEnv RL Environment for Alzheimer's Monitoring},
  year   = {2025},
  url    = {https://huggingface.co/spaces/Sparsha2708/Alzheimers}
}
```