TanujInsane commited on
Commit
bd7ba9a
Β·
1 Parent(s): d183b62

professional README - badges, architecture, API docs, scoring table

Browse files
Files changed (1) hide show
  1. README.md +118 -82
README.md CHANGED
@@ -1,5 +1,5 @@
1
- ο»Ώ---
2
- title: Document Classification Environment
3
  emoji: πŸ“„
4
  colorFrom: blue
5
  colorTo: green
@@ -7,124 +7,160 @@ sdk: docker
7
  pinned: false
8
  tags:
9
  - openenv
10
- - reinforcement-learning
11
  - document-classification
 
12
  - gymnasium
13
- - pytorch
14
  ---
15
 
16
- # Document Classification Environment
17
 
18
  **OpenEnv submission for Meta x PyTorch Hackathon**
19
 
20
- [![Spaces](https://img.shields.io/badge/HuggingFace-Spaces-blue)](https://huggingface.co/spaces/TanujInsane/document-classification-env)
21
- [![Python](https://img.shields.io/badge/Python-3.11-green)](https://python.org)
22
- [![Gymnasium](https://img.shields.io/badge/Gymnasium-0.28-orange)](https://gymnasium.farama.org)
23
 
24
- ## Overview
25
 
26
- A real-world OpenEnv environment that trains AI agents to classify and route enterprise support tickets. Agents learn to distinguish 22 categories across 3 difficulty levels using adversarial document noise.
27
 
28
- **Baseline Agent Scores: EASY 1.00 | MEDIUM 1.00 | HARD 1.00**
29
 
30
- ## Quick Start
31
- ```python
32
 
33
- $readme = @'
34
- ---
35
- title: Document Classification Environment
36
- emoji: πŸ“„
37
- colorFrom: blue
38
- colorTo: green
39
- sdk: docker
40
- pinned: false
41
- tags:
42
- - openenv
43
- - reinforcement-learning
44
- - document-classification
45
- - gymnasium
46
- - pytorch
47
  ---
48
 
49
- # Document Classification Environment
50
-
51
- **OpenEnv submission for Meta x PyTorch Hackathon**
52
 
53
- [![Spaces](https://img.shields.io/badge/HuggingFace-Spaces-blue)](https://huggingface.co/spaces/TanujInsane/document-classification-env)
54
- [![Python](https://img.shields.io/badge/Python-3.11-green)](https://python.org)
55
- [![Gymnasium](https://img.shields.io/badge/Gymnasium-0.28-orange)](https://gymnasium.farama.org)
56
-
57
- ## Overview
58
-
59
- A real-world OpenEnv environment that trains AI agents to classify and route enterprise support tickets. Agents learn to distinguish 22 categories across 3 difficulty levels using adversarial document noise.
 
 
 
 
 
60
 
61
- **Baseline Agent Scores: EASY 1.00 | MEDIUM 1.00 | HARD 1.00**
62
 
63
- ## Quick Start
64
  ```python
65
  from environment import DocumentClassificationEnv
66
 
67
- env = DocumentClassificationEnv("hard")
68
  obs, info = env.reset()
69
 
70
  while True:
71
- action = your_agent(obs)
72
- obs, reward, done, truncated, info = env.step(action)
 
73
  if done:
74
  print(info["episode_summary"])
75
  break
76
  ```
77
 
78
- ## Environment Design
79
 
80
- ### Difficulty Levels
81
 
82
- | Level | Categories | Documents | Challenge |
83
- |-------|-----------|-----------|-----------|
84
- | Easy | 5 | 500 | Basic keyword routing |
85
- | Medium | 10 | 750 | Overlapping categories |
86
- | Hard | 22 | 1000 | Adversarial noise injection |
87
 
88
- ### Observation Space
 
89
 
90
- | Field | Type | Description |
91
- |-------|------|-------------|
92
- | content | str | Document text (with noise) |
93
- | features | array[100] | Normalized TF-IDF features |
94
- | word_count | int | Document length |
95
- | has_urgency_markers | bool | Urgency signal |
96
- | true_category | str | Structural category signal |
97
 
98
- ### Action Space
99
- Discrete(N) where N = number of categories for difficulty level
100
 
101
- ### Reward Structure
102
- | Outcome | Reward |
103
- |---------|--------|
104
- | Exact match | 1.00 |
105
- | Parent category match | 0.50 |
106
- | Wrong category | 0.00 |
107
 
108
- ## Real-World Application
 
 
109
 
110
- Enterprise customer support ticket routing - a high-value task where AI agents classify and route incoming tickets (Billing, Technical, HR, Legal, Executive, Finance, Marketing, Operations) to the correct department.
 
 
 
 
111
 
112
- ## Files
113
 
114
- | File | Description |
115
- |------|-------------|
116
- | environment.py | Core Gymnasium environment |
117
- | tasks.py | Document generation with adversarial noise |
118
- | grading.py | Hierarchical partial credit scoring |
119
- | baseline_inference.py | Structural feature agent (1.0 accuracy) |
120
- | app.py | Interactive Gradio demo |
121
- | openenv.yaml | Environment specification |
122
 
123
- ## Scoring Criteria Met
124
 
125
- - Real-world utility: Enterprise ticket routing
126
- - Task and grader quality: 3 difficulty levels, partial credit
127
- - Environment design: Full Gymnasium API compliance
128
- - Code quality: Modular, documented, reproducible
129
- - Creativity: Adversarial noise injection in Hard mode
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
130
 
 
 
1
+ ---
2
+ title: Document Classification Env
3
  emoji: πŸ“„
4
  colorFrom: blue
5
  colorTo: green
 
7
  pinned: false
8
  tags:
9
  - openenv
 
10
  - document-classification
11
+ - reinforcement-learning
12
  - gymnasium
 
13
  ---
14
 
15
+ # πŸ“„ Document Classification Environment
16
 
17
  **OpenEnv submission for Meta x PyTorch Hackathon**
18
 
19
+ An interactive Gymnasium-compatible environment where AI agents learn to classify and route customer support tickets to the correct department.
 
 
20
 
21
+ ---
22
 
23
+ ## 🎯 Real-World Task
24
 
25
+ 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.
26
 
27
+ **Why this matters:** Misrouted tickets waste time and frustrate customers. A well-trained agent can reduce misrouting by 80%+.
 
28
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
29
  ---
30
 
31
+ ## πŸ—οΈ Environment Design
 
 
32
 
33
+ ```
34
+ DocumentClassificationEnv(task_difficulty="hard", seed=42)
35
+ β”œβ”€β”€ observation_space: Dict
36
+ β”‚ β”œβ”€β”€ content: Text (the document)
37
+ β”‚ β”œβ”€β”€ document_id: Text
38
+ β”‚ β”œβ”€β”€ word_count: Box(1,)
39
+ β”‚ β”œβ”€β”€ has_urgency_markers: MultiBinary(1)
40
+ β”‚ β”œβ”€β”€ features: Box(100,) ← TF-IDF features
41
+ β”‚ β”œβ”€β”€ document_index: Box(1,)
42
+ β”‚ └── total_documents: Box(1,)
43
+ └── action_space: Discrete(N) ← N = num categories
44
+ ```
45
 
46
+ ### API
47
 
 
48
  ```python
49
  from environment import DocumentClassificationEnv
50
 
51
+ env = DocumentClassificationEnv(task_difficulty="hard", seed=42)
52
  obs, info = env.reset()
53
 
54
  while True:
55
+ action = your_agent(obs) # int: category index
56
+ obs, reward, done, _, info = env.step(action)
57
+ print(f"Reward: {reward:.3f}, Correct: {info['is_correct']}")
58
  if done:
59
  print(info["episode_summary"])
60
  break
61
  ```
62
 
63
+ ---
64
 
65
+ ## πŸ“Š Three Progressive Tasks
66
 
67
+ | Task | Categories | Documents | Time Limit | Target Score |
68
+ |------|-----------|-----------|------------|--------------|
69
+ | **Easy** | 5 | 100 | None | 0.85 |
70
+ | **Medium** | 10 | 500 | 2 sec | 0.75 |
71
+ | **Hard** | 22 | 1000 | 1 sec | 0.75 |
72
 
73
+ ### Categories (Hard Mode β€” 22 total)
74
+ `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`
75
 
76
+ ---
 
 
 
 
 
 
77
 
78
+ ## πŸ† Reward Function
 
79
 
80
+ ```python
81
+ reward = accuracy_reward + speed_bonus
 
 
 
 
82
 
83
+ # accuracy_reward:
84
+ # +1.0 for correct classification
85
+ # -0.5 for wrong classification
86
 
87
+ # speed_bonus (difficulty-dependent):
88
+ # Easy: +0.10 if < 100ms
89
+ # Medium: +0.15 if < 200ms, +0.10 if < 500ms
90
+ # Hard: +0.20 if < 100ms, +0.10 if < 300ms
91
+ ```
92
 
93
+ Partial credit via speed bonus encourages efficient inference, not just accuracy.
94
 
95
+ ---
 
 
 
 
 
 
 
96
 
97
+ ## πŸ“ˆ Baseline Results (Keyword Agent)
98
 
99
+ | Task | Score | Notes |
100
+ |------|-------|-------|
101
+ | EASY | **0.77** | Simple keyword matching |
102
+ | MEDIUM | **0.89** | Priority-ordered keywords |
103
+ | HARD | **0.165** | 22 categories, harder to distinguish |
104
+
105
+ Better agents (TF-IDF similarity, fine-tuned LLM) can significantly beat baseline.
106
+
107
+ ---
108
+
109
+ ## πŸš€ Quick Start
110
+
111
+ ```bash
112
+ git clone https://huggingface.co/spaces/TanujInsane/document-classification-env
113
+ cd document-classification-env
114
+ pip install -r requirements.txt
115
+
116
+ # Run baseline
117
+ python baseline_inference.py --task all --output results.json
118
+
119
+ # Launch UI
120
+ python app.py
121
+ ```
122
+
123
+ ---
124
+
125
+ ## πŸ“ File Structure
126
+
127
+ ```
128
+ β”œβ”€β”€ environment.py # Main Gymnasium environment
129
+ β”œβ”€β”€ tasks.py # Document generation + TF-IDF features
130
+ β”œβ”€β”€ grading.py # Scoring logic (0.0 - 1.0)
131
+ β”œβ”€β”€ baseline_inference.py # Keyword-based baseline agent
132
+ β”œβ”€β”€ app.py # Gradio interactive demo
133
+ β”œβ”€β”€ test_environment.py # 5 unit tests (all passing βœ…)
134
+ β”œβ”€β”€ openenv.yaml # OpenEnv specification
135
+ β”œβ”€β”€ Dockerfile # Container deployment
136
+ └── requirements.txt # Dependencies
137
+ ```
138
+
139
+ ---
140
+
141
+ ## πŸ”¬ Reproducibility
142
+
143
+ - Seed-controlled document generation
144
+ - Fixed test sets for fair grading
145
+ - Deterministic reward calculation
146
+ - Docker containerization for consistent deployment
147
+
148
+ ---
149
+
150
+ ## πŸ’‘ Improving Beyond Baseline
151
+
152
+ ```python
153
+ # Example: TF-IDF similarity agent (beats keyword matching)
154
+ from sklearn.metrics.pairwise import cosine_similarity
155
+
156
+ class TFIDFAgent:
157
+ def __init__(self, difficulty):
158
+ self.env = DocumentClassificationEnv(difficulty)
159
+ # Pre-compute category centroid vectors
160
+ # Use cosine similarity at inference time
161
+ ...
162
+ ```
163
+
164
+ ---
165
 
166
+ *Built for Meta x PyTorch OpenEnv Hackathon | Gymnasium-compatible | Docker deployed*