Upload README.md with huggingface_hub

README.md

@@ -1,10 +1,224 @@
 ---
-title: Contextflow Env
-emoji: 🏢
-colorFrom: pink
-colorTo: green
+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
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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}
+}
+```