README.md

metadata

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

pip install contextflow-env

Usage (Async)

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)

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.

# 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

# 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

# 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

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