muffin2006/document-classification-env

1# 🚀 DEPLOYMENT & TESTING GUIDE2 3## Installation & Setup4 5### Step 1: Install Dependencies6```bash7cd c:\Users\91748\Desktop\metax8 9# For Windows:10python -m pip install --upgrade pip11pip install -r requirements.txt12 13# This installs:14# - gymnasium (OpenAI Gym modern replacement)15# - numpy, pandas, scikit-learn (data processing)16# - pyyaml (configuration)17# - flask (web framework)18# - gradio (web interface)19# - huggingface-hub (integration)20```21 22### Step 2: Verify Installation23```bash24python -c "import gymnasium; print('✓ Gymnasium installed')"25python test_environment.py26```27 28---29 30## Running the Environment31 32### Option A: Quick Test (2 minutes)33```bash34python test_environment.py35```36 37**Expected Output**:38```39============================================================40Document Classification Environment - Test Suite41============================================================42 43Testing environment creation...44✓ easy environment created successfully45✓ medium environment created successfully46✓ hard environment created successfully47 48Testing step function...49✓ Step 1: reward=0.850, accuracy=1.00050✓ Step 2: reward=-0.400, accuracy=0.50051✓ Step 3: reward=1.100, accuracy=0.66752✓ Step 4: reward=0.750, accuracy=0.75053✓ Step 5: reward=1.050, accuracy=0.80054✓ Step function working correctly55 56[... more tests ...]57 58TEST SUMMARY59============================================================60✓ PASS - Environment Creation61✓ PASS - Step Function62✓ PASS - State Function63✓ PASS - Baseline Agent64✓ PASS - Grading System65 66Total: 5/5 tests passed67============================================================68```69 70### Option B: Baseline Evaluation (5 minutes)71```bash72# Test specific task73python baseline_inference.py --task easy74 75# Test all tasks76python baseline_inference.py --task all77 78# Test with verbose output79python baseline_inference.py --task hard --verbose80```81 82**Expected Output**:83```84======================================================================85Document Classification Environment - Baseline Evaluation86======================================================================87 88[easy] Starting evaluation...89 90============================================================91Task: EASY92============================================================93Accuracy: 0.780094Correct Classifications: 78/10095Average Reward: 0.835096Total Reward: 83.500097Average Processing Time: 48.23ms98 99Final Score: 0.7800100============================================================101 102✓ EASY - Score: 0.7800103 104[medium] Starting evaluation...105✓ MEDIUM - Score: 0.6500106 107[hard] Starting evaluation...108✓ HARD - Score: 0.5200109 110======================================================================111BASELINE PERFORMANCE SUMMARY112======================================================================113EASY     - Overall Score: 0.7800  |  Accuracy: 0.7800114MEDIUM   - Overall Score: 0.6500  |  Accuracy: 0.6800115HARD     - Overall Score: 0.5200  |  Accuracy: 0.5500116======================================================================117 118Results saved to: baseline_results.json119```120 121### Option C: Interactive Demo (5 minutes)122```bash123python app.py124```125 126**What happens**:1271. Gradio web server starts on `http://localhost:7860`1282. Browser opens automatically (or visit manually)1293. Four tabs available:130   - **Interactive Demo**: Try classifying documents in real-time131   - **Environment Info**: Learn about the task132   - **Baseline Evaluation**: See baseline scores133   - **OpenEnv Spec**: View the specification134 135**Demo Steps**:136- Select difficulty (easy/medium/hard)137- Click "Create Environment"138- Click "Reset Episode"139- Choose a category140- Click "Classify Document"141- See the result (correct/incorrect)142- Try more documents143 144### Option D: Run Examples (10 minutes)145```bash146python example_usage.py147```148 149**What runs**:1501. Basic environment usage1512. Environment state inspection1523. Baseline agent performance1534. Agent grading system1545. Difficulty comparison1556. Reproducibility with seeds1567. Episode summaries157 158---159 160## How It Works - Simple Explanation161 162### The Loop163```1641. Create Environment165   ↓1662. Reset Episode167   ├─ Generates 100/500/1000 documents168   ├─ Each document has text + features169   └─ Tracks progress170   ↓1713. Agent Receives Document172   ├─ Sees document content173   ├─ Sees 100-dimensional feature vector174   └─ Must decide: which category?175   ↓1764. Environment Rewards Agent177   ├─ +1.0 if correct classification178   ├─ -0.5 if incorrect179   ├─ +0.1 to +0.2 bonus if fast180   └─ Returns next document181   ↓1825. Repeat Until Done183   └─ Episode ends when all documents classified184   ↓1856. Get Final Score186   ├─ Accuracy187   ├─ Total Reward188   ├─ Average Processing Time189   └─ Difficulty-weighted Score (0.0-1.0)190```191 192---193 194## Understanding the Output195 196### Key Metrics197 198**Accuracy**199- What % of documents were classified correctly?200- Easy: 78% (baseline)201- Medium: 68% (harder)202- Hard: 55% (hardest)203 204**Reward**205- +1.0: Correct classification206- -0.5: Wrong classification207- +0.1 to +0.2: Speed bonus208 209**Processing Time**210- How fast did the agent decide?211- Easy: No time limit (average 50ms)212- Medium: 2 seconds per decision (average 150ms)213- Hard: 1 second per decision (average 100ms)214 215**Score**216- 0.0-1.0 final rating217- Easy: Accuracy alone218- Medium: 80% accuracy + 20% speed219- Hard: 75% accuracy + 25% speed220 221---222 223## Example: Running Your First Classification224 225### Step-by-Step226 227**1. Create Environment**228```python229from environment import DocumentClassificationEnv230env = DocumentClassificationEnv("easy")231```232 233**2. Reset Episode**234```python235obs, info = env.reset()236print(obs['content'])237# Output: "My invoice shows an incorrect amount. Please review."238print(f"Words: {obs['word_count'][0]}")239# Output: Words: 9240```241 242**3. Make Decision**243```python244# Easy categories: [General, Billing, Support, Technical, HR]245action = 1  # Choose "Billing"246```247 248**4. Step Environment**249```python250obs, reward, done, _, info = env.step(action)251 252print(f"Reward: {reward}")253# Output: Reward: 1.1 (correct + speed bonus)254print(f"Accuracy: {info['episode_accuracy']}")255# Output: Accuracy: 1.0 (1 correct out of 1)256```257 258**5. Repeat**259```python260while not done:261    action = agent.decide(obs)262    obs, reward, done, _, info = env.step(action)263    264print(info['episode_summary'])265# {266#   'accuracy': 0.87,267#   'total_reward': 87.3,268#   'average_reward': 0.873,269#   'total_documents_classified': 100270# }271```272 273---274 275## Docker Deployment276 277### Building Docker Image278```bash279# In project directory280docker build -t doc-classifier:latest .281 282# Monitor build283# Takes 2-3 minutes284# Downloads Python base image285# Installs dependencies286# Creates non-root user287# Sets up health check288```289 290### Running Container291```bash292# Run with port mapping293docker run -p 7860:7860 doc-classifier:latest294 295# Run with environment variable296docker run -e TASK=easy -p 7860:7860 doc-classifier:latest297 298# Run interactively299docker run -it -p 7860:7860 doc-classifier:latest /bin/bash300```301 302### Docker Output303```304* Running Gradio server305* Listening on http://0.0.0.0:7860306* Health check: PASS307```308 309---310 311## Cloud Deployment (Hugging Face Spaces)312 313### Step 1: Create Space3141. Go to https://huggingface.co/spaces3152. Click "Create new Space"3163. Name: `document-classifier-env`3174. License: MIT3185. Space SDK: Docker3196. Click "Create Space"320 321### Step 2: Upload Files322```bash323git clone https://huggingface.co/spaces/YOUR_USERNAME/document-classifier-env324cd document-classifier-env325 326# Copy all files from project327cp c:\Users\91748\Desktop\metax\* .328 329# Commit and push330git add .331git commit -m "Initial OpenEnv environment"332git push333```334 335### Step 3: Monitor Deployment336- Space automatically builds Docker image337- Watch build logs in Spaces UI338- Takes 5-10 minutes first time339- Then available at: https://huggingface.co/spaces/YOUR_USERNAME/document-classifier-env340 341---342 343## Troubleshooting344 345### Issue: "ModuleNotFoundError: No module named 'gymnasium'"346**Solution**:347```bash348pip install -r requirements.txt349# or350pip install gymnasium numpy pandas scikit-learn pyyaml requests flask gradio351```352 353### Issue: "Port 7860 already in use"354**Solution**:355```bash356# Option 1: Use different port357python -c "from app import create_interface; create_interface().launch(server_port=8080)"358 359# Option 2: Kill process using port 7860360# Windows: taskkill /IM python.exe /F361# Linux: lsof -ti:7860 | xargs kill -9362```363 364### Issue: "Docker build fails"365**Solution**:366```bash367# Clean build368docker build --no-cache -t doc-classifier:latest .369 370# Check Docker is running371docker ps372 373# Check Dockerfile syntax374docker build --progress=plain -t doc-classifier .375```376 377### Issue: Tests fail with "Feature extraction error"378**Solution**:379```bash380# Reinstall scikit-learn381pip install --upgrade scikit-learn382python test_environment.py383```384 385---386 387## Performance Tuning388 389### For Speed390```python391# Use Easy task392env = DocumentClassificationEnv("easy")  # 100 docs, no time limit393 394# Process in batches395batch_size = 10396for _ in range(batch_size):397    action = agent.decide(obs)398    obs, _, _, _, _ = env.step(action)399```400 401### For Accuracy402```python403# Use Hard task404env = DocumentClassificationEnv("hard")  # 1000 docs, tight deadline405 406# Give more time per decision407import time408start = time.time()409action = agent.decide(obs)  # Can take up to 1 second410elapsed = time.time() - start411```412 413### For Reproducibility414```python415# Use fixed seed416env = DocumentClassificationEnv("easy", seed=42)417obs, _ = env.reset(seed=42)418 419# Results will be identical across runs420```421 422---423 424## Monitoring & Logging425 426### Enable Logging427```python428import logging429logging.basicConfig(level=logging.DEBUG)430 431env = DocumentClassificationEnv("easy")432obs, _ = env.reset()433```434 435### Save Results436```bash437# Baseline evaluation saves JSON438python baseline_inference.py --task all --output results.json439 440# View results441cat results.json442```443 444---445 446## File Monitoring447 448### Watch for Changes449```bash450# Windows: Use `watchdog` package451pip install watchdog452watchmedo shell-command \453    --patterns="*.py" \454    --recursive \455    --command='python test_environment.py' \456    .457```458 459---460 461## Getting Help462 463### Check Logs464```bash465# Python logs466python -u baseline_inference.py --task easy 2>&1 | tee run.log467 468# Docker logs469docker logs CONTAINER_ID470docker logs -f CONTAINER_ID  # Follow logs471```472 473### Verify Setup474```bash475# Run diagnostic476python -c """477import gymnasium478import numpy as np479import pandas as pd480from sklearn.feature_extraction.text import TfidfVectorizer481from environment import DocumentClassificationEnv482 483print('✓ All imports successful')484 485env = DocumentClassificationEnv('easy')486obs, _ = env.reset()487print(f'✓ Environment initialized')488print(f'✓ Observation keys: {list(obs.keys())}')489print(f'✓ Features shape: {obs[\"features\"].shape}')490print('✓ Setup verified - ready to go!')491"""492```493 494---495 496## Quick Command Reference497 498```bash499# Setup500pip install -r requirements.txt501 502# Test503python test_environment.py504 505# Evaluate506python baseline_inference.py --task all507 508# Run examples509python example_usage.py510 511# Interactive demo512python app.py513 514# Docker515docker build -t doc-classifier .516docker run -p 7860:7860 doc-classifier517 518# Cleanup519rm -rf __pycache__520rm -rf *.egg-info521rm -rf .pytest_cache522```523 524---525 526## Summary527 528✅ **Installation**: `pip install -r requirements.txt`529✅ **Test**: `python test_environment.py`530✅ **Try it**: `python app.py`531✅ **Evaluate**: `python baseline_inference.py --task all`532✅ **Deploy**: `docker build . && docker run -p 7860:7860 doc-classifier`533 534**Your environment is ready to use!**535