TanujInsane
professional README - badges, architecture, API docs, scoring table
bd7ba9a
|
Raw History Blame Contribute Delete
4.71 kB
metadata
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

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

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

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

# 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