File size: 4,712 Bytes
bd7ba9a
 
d183b62
c5c9f44
 
c9b7f59
 
 
 
9a75cf3
bd7ba9a
c5c9f44
c9b7f59
8ddfad6
bd7ba9a
8ddfad6
c5c9f44
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
c5c9f44
8ddfad6
bd7ba9a
9a75cf3
bd7ba9a
 
 
 
 
 
 
 
 
 
 
 
8ddfad6
bd7ba9a
8ddfad6
 
 
 
bd7ba9a
c5c9f44
8ddfad6
c5c9f44
bd7ba9a
 
 
c5c9f44
 
 
 
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
 
 
 
 
8ddfad6
bd7ba9a
 
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
 
8ddfad6
bd7ba9a
 
 
8ddfad6
bd7ba9a
 
 
 
 
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
8ddfad6
bd7ba9a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
d183b62
bd7ba9a
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
---
title: Document Classification Env
emoji: πŸ“„
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
tags:
- openenv
- document-classification
- reinforcement-learning
- gymnasium
---

# πŸ“„ Document Classification Environment

**OpenEnv submission for Meta x PyTorch Hackathon**

An interactive Gymnasium-compatible environment where AI agents learn to classify and route customer support tickets to the correct department.

---

## 🎯 Real-World Task

Customer support teams receive hundreds of tickets daily β€” billing issues, technical bugs, HR complaints, legal queries. This environment simulates that routing challenge, training agents to read a document and instantly decide which department should handle it.

**Why this matters:** Misrouted tickets waste time and frustrate customers. A well-trained agent can reduce misrouting by 80%+.

---

## πŸ—οΈ Environment Design

```
DocumentClassificationEnv(task_difficulty="hard", seed=42)
β”œβ”€β”€ observation_space: Dict
β”‚   β”œβ”€β”€ content: Text (the document)
β”‚   β”œβ”€β”€ document_id: Text
β”‚   β”œβ”€β”€ word_count: Box(1,)
β”‚   β”œβ”€β”€ has_urgency_markers: MultiBinary(1)
β”‚   β”œβ”€β”€ features: Box(100,)  ← TF-IDF features
β”‚   β”œβ”€β”€ document_index: Box(1,)
β”‚   └── total_documents: Box(1,)
└── action_space: Discrete(N)  ← N = num categories
```

### API

```python
from environment import DocumentClassificationEnv

env = DocumentClassificationEnv(task_difficulty="hard", seed=42)
obs, info = env.reset()

while True:
    action = your_agent(obs)          # int: category index
    obs, reward, done, _, info = env.step(action)
    print(f"Reward: {reward:.3f}, Correct: {info['is_correct']}")
    if done:
        print(info["episode_summary"])
        break
```

---

## πŸ“Š Three Progressive Tasks

| Task | Categories | Documents | Time Limit | Target Score |
|------|-----------|-----------|------------|--------------|
| **Easy** | 5 | 100 | None | 0.85 |
| **Medium** | 10 | 500 | 2 sec | 0.75 |
| **Hard** | 22 | 1000 | 1 sec | 0.75 |

### Categories (Hard Mode β€” 22 total)
`General` `Billing` `Billing-Dispute` `Billing-Refund` `Support` `Support-Urgent` `Support-Normal` `Technical` `Technical-Bug` `Technical-Feature` `HR` `HR-Payroll` `HR-Benefits` `HR-Complaint` `Legal` `Legal-Contract` `Legal-Compliance` `Executive` `Executive-Strategic` `Finance` `Marketing` `Operations`

---

## πŸ† Reward Function

```python
reward = accuracy_reward + speed_bonus

# accuracy_reward:
#   +1.0 for correct classification
#   -0.5 for wrong classification

# speed_bonus (difficulty-dependent):
#   Easy:   +0.10 if < 100ms
#   Medium: +0.15 if < 200ms, +0.10 if < 500ms
#   Hard:   +0.20 if < 100ms, +0.10 if < 300ms
```

Partial credit via speed bonus encourages efficient inference, not just accuracy.

---

## πŸ“ˆ Baseline Results (Keyword Agent)

| Task | Score | Notes |
|------|-------|-------|
| EASY | **0.77** | Simple keyword matching |
| MEDIUM | **0.89** | Priority-ordered keywords |
| HARD | **0.165** | 22 categories, harder to distinguish |

Better agents (TF-IDF similarity, fine-tuned LLM) can significantly beat baseline.

---

## πŸš€ Quick Start

```bash
git clone https://huggingface.co/spaces/TanujInsane/document-classification-env
cd document-classification-env
pip install -r requirements.txt

# Run baseline
python baseline_inference.py --task all --output results.json

# Launch UI
python app.py
```

---

## πŸ“ File Structure

```
β”œβ”€β”€ environment.py          # Main Gymnasium environment
β”œβ”€β”€ tasks.py               # Document generation + TF-IDF features
β”œβ”€β”€ grading.py             # Scoring logic (0.0 - 1.0)
β”œβ”€β”€ baseline_inference.py  # Keyword-based baseline agent
β”œβ”€β”€ app.py                 # Gradio interactive demo
β”œβ”€β”€ test_environment.py    # 5 unit tests (all passing βœ…)
β”œβ”€β”€ openenv.yaml           # OpenEnv specification
β”œβ”€β”€ Dockerfile             # Container deployment
└── requirements.txt       # Dependencies
```

---

## πŸ”¬ Reproducibility

- Seed-controlled document generation
- Fixed test sets for fair grading
- Deterministic reward calculation
- Docker containerization for consistent deployment

---

## πŸ’‘ Improving Beyond Baseline

```python
# Example: TF-IDF similarity agent (beats keyword matching)
from sklearn.metrics.pairwise import cosine_similarity

class TFIDFAgent:
    def __init__(self, difficulty):
        self.env = DocumentClassificationEnv(difficulty)
        # Pre-compute category centroid vectors
        # Use cosine similarity at inference time
        ...
```

---

*Built for Meta x PyTorch OpenEnv Hackathon | Gymnasium-compatible | Docker deployed*