README.md

metadata

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.

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)

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

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