README.md

---
title: ContextFlow
emoji: 🎓
colorFrom: blue
colorTo: purple
sdk: static
description: OpenEnv environment for training AI agents to predict learner confusion
tags:
  - education
  - learning
  - reinforcement-learning
  - agent
  - openenv
app_file: index.html
pinned: false
---

# ContextFlow OpenEnv Environment

**ContextFlow** is an OpenEnv environment for training AI agents to predict learner confusion in educational settings. Agents learn to detect confusion signals from multi-modal data (gaze, gestures, biometrics, audio, behavior) and trigger proactive interventions.

## Environment Description

ContextFlow simulates a real-world educational technology use case where:
- Learners interact with educational content
- Multi-modal signals indicate confusion states
- AI agents must predict confusion BEFORE it occurs
- Agents can trigger interventions to help struggling learners

### Why This Matters

Traditional learning systems are **reactive** - they respond after confusion occurs. ContextFlow trains agents to be **proactive**, predicting confusion and intervening before disengagement. This is a genuine problem in EdTech with real utility for millions of learners.

## Quick Start

### Installation

```bash
pip install contextflow-env
```

### Usage (Async)

```python
import asyncio
from contextflow_env import ContextFlowEnv, Action, ActionType

async def main():
    async with ContextFlowEnv(base_url="https://your-space.hf.space") as env:
        # Reset environment
        result = await env.reset(difficulty="medium")
        print(f"Initial observation: Step {result.observation.step}")
        
        # Take actions
        for step in range(50):
            action = Action(
                action_type=ActionType.PREDICT_CONFUSION,
                predicted_confusion=0.5,  # Your prediction
            )
            result = await env.step(action)
            print(f"Step {result.observation.step}, Reward: {result.reward.total:.3f}")
            
            if result.done:
                print(f"Episode complete! Final score: {result.info['grader_result']}")
                break

asyncio.run(main())
```

### Usage (Sync)

```python
from contextflow_env import SyncContextFlowEnv, Action, ActionType

with SyncContextFlowEnv(base_url="https://your-space.hf.space") as env:
    result = env.reset(difficulty="medium")
    
    for step in range(50):
        action = Action(
            action_type=ActionType.PREDICT_CONFUSION,
            predicted_confusion=0.5,
        )
        result = env.step(action)
        
        if result.done:
            print(f"Final score: {result.info['grader_result']}")
            break
```

## Action and Observation Spaces

### Observation Space

| Feature | Dimensions | Description |
|---------|-----------|-------------|
| gaze_features | 16 | Gaze tracking (fixation, saccade, pupil) |
| gesture_features | 63 | Hand gesture landmarks (21×3) |
| biometric_features | 6 | Heart rate, GSR, temperature, etc. |
| audio_features | 8 | Pitch, tone, speaking rate, pauses |
| behavioral_features | 8 | Scroll speed, clicks, typing rhythm |
| confusion_history | ≤10 | Historical confusion probabilities |

### Action Space

| Action Type | Parameters |
|-------------|-----------|
| `predict_confusion` | `predicted_confusion` (0.0-1.0) |
| `analyze_behavior` | - |
| `trigger_intervention` | `intervention_type`, `intervention_intensity` |
| `classify_difficulty` | `difficulty_prediction` |
| `fuse_modalities` | `modality_weights` |

## Tasks

### Easy: Confusion Prediction (Basic)
- **Max Steps**: 50
- **Noise Level**: Low (0.1)
- **Prediction Window**: 3 steps
- **Passing Threshold**: 0.5

### Medium: Confusion Prediction (Standard)
- **Max Steps**: 75
- **Noise Level**: Medium (0.2)
- **Prediction Window**: 5 steps
- **Passing Threshold**: 0.6

### Hard: Confusion Prediction (Advanced)
- **Max Steps**: 100
- **Noise Level**: High (0.3)
- **Prediction Window**: 7 steps
- **Passing Threshold**: 0.7

## Reward Function

The reward is multi-component, providing signal throughout the episode:

1. **Confusion Prediction Reward** (40%): `1 - |predicted - ground_truth|`
2. **Early Detection Reward** (20%): Detecting confusion spikes before they peak
3. **Intervention Reward** (20%): Effective interventions that reduce confusion
4. **Partial Progress Reward** (10%): Sustaining low confusion over time
5. **Penalty** (-20%): Over-aggressive interventions

## Grading Metrics

| Metric | Weight | Description |
|--------|--------|-------------|
| MAE | 40% | Mean Absolute Error between prediction and ground truth |
| Early Detection Rate | 30% | % of confusion spikes detected early |
| Intervention Effectiveness | 30% | % of interventions that reduce confusion |

## Baseline Inference

See `baseline_inference.py` for a complete baseline using OpenAI API.

```bash
# Set your API key
export OPENAI_API_KEY=your-key-here

# Run baseline on all tasks
python baseline_inference.py --tasks easy medium hard
```

### Baseline Scores (GPT-4o)

| Task | MAE | Early Detection | Intervention | Total |
|------|-----|-----------------|--------------|-------|
| Easy | 0.18 | 0.72 | 0.65 | 0.51 |
| Medium | 0.24 | 0.58 | 0.51 | 0.45 |
| Hard | 0.31 | 0.42 | 0.38 | 0.38 |

## Setup and Development

### Local Development

```bash
# Clone repository
git clone https://github.com/contextflow/contextflow-env.git
cd contextflow-env

# Install dependencies
pip install -e .

# Run server locally
python -m uvicorn server.app:app --host 0.0.0.0 --port 8000

# Run tests
pytest tests/ -v
```

### Docker Deployment

```bash
# Build image
docker build -t contextflow-env .

# Run container
docker run -p 8000:8000 contextflow-env
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Health check |
| `/health` | GET | Detailed health status |
| `/reset` | POST | Initialize new episode |
| `/step` | POST | Execute action |
| `/state/{episode_id}` | GET | Get episode state |
| `/ws/{episode_id}` | WS | WebSocket for real-time interaction |

## License

MIT License

## Citation

```bibtex
@software{contextflow2026,
  title = {ContextFlow: OpenEnv Environment for Learning Confusion Prediction},
  author = {ContextFlow Team},
  year = {2026},
  url = {https://github.com/contextflow/contextflow-env}
}
```