Shivacode commited on
Commit
aa97969
Β·
1 Parent(s): 75ba9ee

fix: complete HF Space README with full metadata and documentation

Browse files
Files changed (1) hide show
  1. README.md +188 -2
README.md CHANGED
@@ -4,8 +4,8 @@ emoji: πŸ“§
4
  colorFrom: blue
5
  colorTo: green
6
  sdk: docker
7
- pinned: false
8
  app_port: 7860
 
9
  tags:
10
  - openenv
11
  - email-triage
@@ -14,7 +14,193 @@ tags:
14
  - nlp
15
  ---
16
 
17
- # Hackathon β€” Meta x PyTorch OpenEnv
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
18
 
19
  ## Structure
20
 
 
4
  colorFrom: blue
5
  colorTo: green
6
  sdk: docker
 
7
  app_port: 7860
8
+ pinned: false
9
  tags:
10
  - openenv
11
  - email-triage
 
14
  - nlp
15
  ---
16
 
17
+ # πŸ“§ Email Triage Environment
18
+
19
+ > **Meta Γ— PyTorch OpenEnv Hackathon β€” Round 1**
20
+ > An RL environment where an AI agent learns to triage real-world emails.
21
+
22
+ ## 🎯 What Is This?
23
+
24
+ This environment simulates an **email triage system** β€” a task every business performs daily. An agent receives a queue of emails and must:
25
+
26
+ 1. **Classify** the email (spam / billing / technical / hr / general)
27
+ 2. **Assign a priority** (low / medium / high / urgent)
28
+ 3. **Route** to the correct department (support / finance / engineering / hr / management)
29
+ 4. **Draft a professional reply** (required for medium and hard tasks)
30
+
31
+ Rewards are **continuous and partial** β€” agents earn credit for getting each dimension right, incentivising learning even when the full answer isn't perfect.
32
+
33
+ ---
34
+
35
+ ## πŸ—‚οΈ Action Space
36
+
37
+ | Field | Type | Values |
38
+ |--------------|--------|-----------------------------------------------------|
39
+ | `category` | string | `spam` Β· `billing` Β· `technical` Β· `hr` Β· `general` |
40
+ | `priority` | string | `low` Β· `medium` Β· `high` Β· `urgent` |
41
+ | `department` | string | `support` Β· `finance` Β· `engineering` Β· `hr` Β· `management` |
42
+ | `reply` | string | Free-text reply draft (empty string for easy tasks) |
43
+
44
+ ---
45
+
46
+ ## πŸ‘οΈ Observation Space
47
+
48
+ | Field | Type | Description |
49
+ |-------------------|--------|----------------------------------------------|
50
+ | `email_id` | string | Unique email identifier |
51
+ | `subject` | string | Email subject line |
52
+ | `body` | string | Full email body |
53
+ | `sender` | string | Sender's email address |
54
+ | `task_level` | string | `easy` Β· `medium` Β· `hard` |
55
+ | `feedback` | string | Natural-language grader feedback |
56
+ | `score` | float | Cumulative average score (0.0–1.0) |
57
+ | `emails_remaining`| int | Number of emails left in the episode |
58
+ | `done` | bool | Episode complete flag |
59
+ | `reward` | float | Per-step reward (0.0–1.0) |
60
+
61
+ ---
62
+
63
+ ## πŸ“Š Task Descriptions
64
+
65
+ ### 🟒 Easy β€” Classification Only
66
+ - **5 emails** per episode (spam, billing, technical, HR, general)
67
+ - Agent must correctly classify category, priority, and department
68
+ - No reply required
69
+ - Score: `category(0.4) + priority(0.3) + department(0.3)`
70
+
71
+ ### 🟑 Medium β€” Classification + Short Reply
72
+ - **3 emails** per episode (billing urgency, technical incident, HR complaint)
73
+ - Agent must classify AND write a professional 2-4 sentence reply
74
+ - Score: `classification(0.5) + reply_quality(0.5)`
75
+ - Reply graded on: professional tone, keyword coverage
76
+
77
+ ### πŸ”΄ Hard β€” Classification + Detailed Accurate Reply
78
+ - **3 emails** per episode (enterprise escalations, security incidents, board complaints)
79
+ - Agent must classify AND write a detailed, accurate reply covering specific required points
80
+ - Score: `classification(0.4) + reply_depth(0.6)`
81
+ - Reply graded on: length, tone, keyword coverage (9 required keywords per email)
82
+
83
+ ---
84
+
85
+ ## πŸ† Reward Function
86
+
87
+ Rewards are **partial and continuous** β€” agents earn credit at every step:
88
+
89
+ | Condition | Reward |
90
+ |-------------------------------------------|---------------|
91
+ | Correct category | +0.15 – +0.40 |
92
+ | Correct priority | +0.13 – +0.30 |
93
+ | Correct department | +0.12 – +0.30 |
94
+ | Reply provided (non-trivial) | +0.05 – +0.10 |
95
+ | Professional tone in reply | +0.05 – +0.10 |
96
+ | Each required keyword matched | proportional |
97
+ | Missing reply on medium/hard | βˆ’0.10 penalty |
98
+
99
+ ---
100
+
101
+ ## πŸš€ Quick Start
102
+
103
+ ### 1. Install dependencies
104
+ ```bash
105
+ git clone https://huggingface.co/spaces/Shivacode/rl-hackathon
106
+ cd rl-hackathon
107
+ pip install -e email_triage_rl_hackathon/
108
+ ```
109
+
110
+ ### 2. Run the server locally
111
+ ```bash
112
+ # Easy task (default)
113
+ uvicorn email_triage_rl_hackathon.server.app:app --host 0.0.0.0 --port 8000 --reload
114
+
115
+ # Medium task
116
+ TASK_LEVEL=medium uvicorn email_triage_rl_hackathon.server.app:app --port 8000
117
+
118
+ # Hard task
119
+ TASK_LEVEL=hard uvicorn email_triage_rl_hackathon.server.app:app --port 8000
120
+ ```
121
+
122
+ ### 3. Interact with the environment (Python)
123
+ ```python
124
+ import asyncio
125
+ from email_triage_rl_hackathon import EmailTriageEnv, TriageAction
126
+
127
+ async def main():
128
+ env = EmailTriageEnv(base_url="http://localhost:8000")
129
+ obs = await env.reset(seed=42, task_level="easy")
130
+ print(obs.subject)
131
+
132
+ result = await env.step(TriageAction(
133
+ category="billing", priority="urgent",
134
+ department="finance",
135
+ reply="Dear customer, we apologize and will investigate within 24 hours."
136
+ ))
137
+ print(result.reward, result.observation.feedback)
138
+ await env.close()
139
+
140
+ asyncio.run(main())
141
+ ```
142
+
143
+ ### 4. Run with Docker
144
+ ```bash
145
+ docker build -t email-triage-env .
146
+ docker run -p 7860:7860 -e TASK_LEVEL=easy email-triage-env
147
+ ```
148
+
149
+ ### 5. Run inference against this Space
150
+ ```bash
151
+ HF_TOKEN=hf_your_token_here \
152
+ ENV_BASE_URL=https://Shivacode-rl-hackathon.hf.space \
153
+ TASK_LEVEL=easy \
154
+ python inference.py
155
+ ```
156
+
157
+ ---
158
+
159
+ ## πŸ“ˆ Scores (Qwen/Qwen2.5-72B-Instruct via HF Router)
160
+
161
+ | Task Level | Steps | Score |
162
+ |------------|-------|--------|
163
+ | Easy | 5 | 0.880 |
164
+ | Medium | 3 | 0.830 |
165
+ | Hard | 3 | 0.800 |
166
+ | **Overall**| | **0.837** |
167
+
168
+ ---
169
+
170
+ ## πŸ—ƒοΈ Project Structure
171
+
172
+ ```
173
+ rl-hackathon/
174
+ β”œβ”€β”€ Dockerfile # HF Spaces Docker deployment (port 7860)
175
+ β”œβ”€β”€ inference.py # Run agent against this environment
176
+ β”œβ”€β”€ baseline.py # Baseline script (OpenAI models)
177
+ └── email_triage_rl_hackathon/
178
+ β”œβ”€β”€ __init__.py # Public exports
179
+ β”œβ”€β”€ models.py # TriageAction, TriageObservation
180
+ β”œβ”€β”€ client.py # EmailTriageEnv (EnvClient)
181
+ β”œβ”€β”€ openenv.yaml # Environment manifest
182
+ β”œβ”€β”€ pyproject.toml # Package config + scripts entry point
183
+ β”œβ”€β”€ uv.lock # Locked dependencies
184
+ └── server/
185
+ β”œβ”€β”€ app.py # FastAPI app (uvicorn entry point)
186
+ β”œβ”€β”€ my_environment.py # EmailTriageEnvironment (reset/step/state)
187
+ β”œβ”€β”€ email_data.py # 11 curated emails across 3 levels
188
+ β”œβ”€β”€ graders.py # Deterministic graders (easy/medium/hard)
189
+ └── requirements.txt
190
+ ```
191
+
192
+ ---
193
+
194
+ ## πŸ”‘ Environment Variables
195
+
196
+ | Variable | Default | Description |
197
+ |-----------------|----------------------------|--------------------------------------|
198
+ | `TASK_LEVEL` | `easy` | Task difficulty: easy / medium / hard |
199
+ | `PORT` | `7860` | Server port |
200
+ | `HF_TOKEN` | β€” | Required for inference.py (HF router)|
201
+ | `MODEL_NAME` | `Qwen/Qwen2.5-72B-Instruct`| Model for inference |
202
+ | `ENV_BASE_URL` | `http://localhost:8000` | Environment server URL |
203
+
204
 
205
  ## Structure
206