Update README.md

README.md

@@ -2,13 +2,146 @@
 title: Email Sorting Openenv
 emoji: 📧
 colorFrom: blue
-colorTo: purple
+colorTo: red
 sdk: docker
 pinned: false
+tags:
+  - openenv
 ---
 
-# Email Sorting OpenEnv
+# Email Sorting OpenEnv 📧
 
-An AI environment where an agent classifies emails as spam, important, or promotion.
+A real-world OpenEnv environment where an AI agent learns to classify
+emails as **spam**, **important**, or **promotion**.
+Built for the Meta x PyTorch OpenEnv Hackathon.
 
-Built for the Meta x PyTorch OpenEnv Hackathon.
+---
+
+## What This Project Does
+
+In today's world, people receive hundreds of emails daily.
+This environment trains an AI agent to automatically sort emails
+by reading the subject, body, and sender — just like a smart inbox.
+
+The agent learns:
+- Correct classification = **reward**
+- Wrong classification = **penalty**
+- Harder emails = **higher reward** (to encourage learning)
+
+---
+
+## Environment Details
+
+| Property | Value |
+|----------|-------|
+| Task Type | Email Classification |
+| Action Space | spam / important / promotion |
+| Max Steps | 10 per episode |
+| Reward Range | -0.5 to +1.0 |
+| Difficulty Levels | Easy / Medium / Hard |
+
+---
+
+## Action Space
+
+The agent can take exactly one of these actions per step:
+
+| Action | Meaning |
+|--------|---------|
+| `spam` | Email is unwanted, scam, or phishing |
+| `important` | Email needs attention (work, orders, real alerts) |
+| `promotion` | Genuine sale or discount from real shops |
+
+---
+
+## Observation Space
+
+Each step the agent receives:
+```json
+{
+  "email": {
+    "subject": "You won $1,000,000!",
+    "body": "Click here to claim your prize.",
+    "sender": "prize@randomsite.xyz"
+  },
+  "step": 1,
+  "max_steps": 10,
+  "total_reward": 0.0,
+  "done": false,
+  "valid_actions": ["spam", "important", "promotion"]
+}
+```
+
+---
+
+## Tasks
+
+| Task | Difficulty | Description | Expected Score |
+|------|------------|-------------|----------------|
+| `easy_sorting` | Easy | Classify obvious spam vs important emails | 0.6 – 0.8 |
+| `medium_sorting` | Medium | Distinguish spam, promotion, and important | 0.5 – 0.7 |
+| `hard_sorting` | Hard | Detect subtle phishing and tricky promotions | 0.4 – 0.6 |
+
+---
+
+## Reward Function
+
+| Event | Reward |
+|-------|--------|
+| Easy correct | +0.5 |
+| Medium correct | +0.75 |
+| Hard correct | +1.0 |
+| Easy wrong | -0.5 |
+| Medium wrong | -0.3 |
+| Hard wrong | -0.1 |
+| Invalid action | -0.2 |
+
+---
+
+## Baseline Scores
+
+Scores achieved by the rule-based baseline agent (`baseline_agent` in `graders.py`):
+
+| Task | Score |
+|------|-------|
+| easy_sorting | 0.8 |
+| medium_sorting | 0.67 |
+| hard_sorting | 0.5 |
+| **Average** | **0.657** |
+
+---
+
+## Setup & Usage
+
+### Local
+
+```bash
+pip install -r requirements.txt
+python server.py           # starts server at http://localhost:7860
+python graders.py          # run graders with baseline agent
+python inference.py        # run inference loop
+```
+
+### Docker
+
+```bash
+docker build -t email-sorting-openenv .
+docker run -p 7860:7860 email-sorting-openenv
+```
+
+### API
+
+```bash
+curl -X POST http://localhost:7860/reset
+curl -X POST http://localhost:7860/step -H "Content-Type: application/json" -d '{"action":"spam"}'
+curl http://localhost:7860/state
+curl http://localhost:7860/graders
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_BASE_URL` | LLM API base URL | `https://api.openai.com/v1` |
+| `MODEL_NAME` | Model to use | `gpt-4o-mini` |
+| `HF_TOKEN` | HuggingFace / API token | — |