Download RUN_AND_DEPLOY.md from muffin2006/document-classification-env: direct link, hf CLI and curl.
- Browser
- Download file 11.5 kB
-
https://huggingface.co/spaces/muffin2006/document-classification-env/resolve/main/RUN_AND_DEPLOY.md
- Command line
-
hf download hf://spaces/muffin2006/document-classification-env/RUN_AND_DEPLOY.md
-
curl -L -o RUN_AND_DEPLOY.md https://huggingface.co/spaces/muffin2006/document-classification-env/resolve/main/RUN_AND_DEPLOY.md
π DEPLOYMENT & TESTING GUIDE
Installation & Setup
Step 1: Install Dependencies
cd c:\Users\91748\Desktop\metax
# For Windows:
python -m pip install --upgrade pip
pip install -r requirements.txt
# This installs:
# - gymnasium (OpenAI Gym modern replacement)
# - numpy, pandas, scikit-learn (data processing)
# - pyyaml (configuration)
# - flask (web framework)
# - gradio (web interface)
# - huggingface-hub (integration)
Step 2: Verify Installation
python -c "import gymnasium; print('β Gymnasium installed')"
python test_environment.py
Running the Environment
Option A: Quick Test (2 minutes)
python test_environment.py
Expected Output: ```
Document Classification Environment - Test Suite
Testing environment creation... β easy environment created successfully β medium environment created successfully β hard environment created successfully
Testing step function... β Step 1: reward=0.850, accuracy=1.000 β Step 2: reward=-0.400, accuracy=0.500 β Step 3: reward=1.100, accuracy=0.667 β Step 4: reward=0.750, accuracy=0.750 β Step 5: reward=1.050, accuracy=0.800 β Step function working correctly
[... more tests ...]
TEST SUMMARY
β PASS - Environment Creation β PASS - Step Function β PASS - State Function β PASS - Baseline Agent β PASS - Grading System
Total: 5/5 tests passed
### Option B: Baseline Evaluation (5 minutes)
```bash
# Test specific task
python baseline_inference.py --task easy
# Test all tasks
python baseline_inference.py --task all
# Test with verbose output
python baseline_inference.py --task hard --verbose
Expected Output: ```
Document Classification Environment - Baseline Evaluation
[easy] Starting evaluation...
============================================================ Task: EASY
Accuracy: 0.7800 Correct Classifications: 78/100 Average Reward: 0.8350 Total Reward: 83.5000 Average Processing Time: 48.23ms
Final Score: 0.7800
β EASY - Score: 0.7800
[medium] Starting evaluation... β MEDIUM - Score: 0.6500
[hard] Starting evaluation... β HARD - Score: 0.5200
====================================================================== BASELINE PERFORMANCE SUMMARY
EASY - Overall Score: 0.7800 | Accuracy: 0.7800 MEDIUM - Overall Score: 0.6500 | Accuracy: 0.6800 HARD - Overall Score: 0.5200 | Accuracy: 0.5500
Results saved to: baseline_results.json
### Option C: Interactive Demo (5 minutes)
```bash
python app.py
What happens:
- Gradio web server starts on
http://localhost:7860 - Browser opens automatically (or visit manually)
- Four tabs available:
- Interactive Demo: Try classifying documents in real-time
- Environment Info: Learn about the task
- Baseline Evaluation: See baseline scores
- OpenEnv Spec: View the specification
Demo Steps:
- Select difficulty (easy/medium/hard)
- Click "Create Environment"
- Click "Reset Episode"
- Choose a category
- Click "Classify Document"
- See the result (correct/incorrect)
- Try more documents
Option D: Run Examples (10 minutes)
python example_usage.py
What runs:
- Basic environment usage
- Environment state inspection
- Baseline agent performance
- Agent grading system
- Difficulty comparison
- Reproducibility with seeds
- Episode summaries
How It Works - Simple Explanation
The Loop
1. Create Environment
β
2. Reset Episode
ββ Generates 100/500/1000 documents
ββ Each document has text + features
ββ Tracks progress
β
3. Agent Receives Document
ββ Sees document content
ββ Sees 100-dimensional feature vector
ββ Must decide: which category?
β
4. Environment Rewards Agent
ββ +1.0 if correct classification
ββ -0.5 if incorrect
ββ +0.1 to +0.2 bonus if fast
ββ Returns next document
β
5. Repeat Until Done
ββ Episode ends when all documents classified
β
6. Get Final Score
ββ Accuracy
ββ Total Reward
ββ Average Processing Time
ββ Difficulty-weighted Score (0.0-1.0)
Understanding the Output
Key Metrics
Accuracy
- What % of documents were classified correctly?
- Easy: 78% (baseline)
- Medium: 68% (harder)
- Hard: 55% (hardest)
Reward
- +1.0: Correct classification
- -0.5: Wrong classification
- +0.1 to +0.2: Speed bonus
Processing Time
- How fast did the agent decide?
- Easy: No time limit (average 50ms)
- Medium: 2 seconds per decision (average 150ms)
- Hard: 1 second per decision (average 100ms)
Score
- 0.0-1.0 final rating
- Easy: Accuracy alone
- Medium: 80% accuracy + 20% speed
- Hard: 75% accuracy + 25% speed
Example: Running Your First Classification
Step-by-Step
1. Create Environment
from environment import DocumentClassificationEnv
env = DocumentClassificationEnv("easy")
2. Reset Episode
obs, info = env.reset()
print(obs['content'])
# Output: "My invoice shows an incorrect amount. Please review."
print(f"Words: {obs['word_count'][0]}")
# Output: Words: 9
3. Make Decision
# Easy categories: [General, Billing, Support, Technical, HR]
action = 1 # Choose "Billing"
4. Step Environment
obs, reward, done, _, info = env.step(action)
print(f"Reward: {reward}")
# Output: Reward: 1.1 (correct + speed bonus)
print(f"Accuracy: {info['episode_accuracy']}")
# Output: Accuracy: 1.0 (1 correct out of 1)
5. Repeat
while not done:
action = agent.decide(obs)
obs, reward, done, _, info = env.step(action)
print(info['episode_summary'])
# {
# 'accuracy': 0.87,
# 'total_reward': 87.3,
# 'average_reward': 0.873,
# 'total_documents_classified': 100
# }
Docker Deployment
Building Docker Image
# In project directory
docker build -t doc-classifier:latest .
# Monitor build
# Takes 2-3 minutes
# Downloads Python base image
# Installs dependencies
# Creates non-root user
# Sets up health check
Running Container
# Run with port mapping
docker run -p 7860:7860 doc-classifier:latest
# Run with environment variable
docker run -e TASK=easy -p 7860:7860 doc-classifier:latest
# Run interactively
docker run -it -p 7860:7860 doc-classifier:latest /bin/bash
Docker Output
* Running Gradio server
* Listening on http://0.0.0.0:7860
* Health check: PASS
Cloud Deployment (Hugging Face Spaces)
Step 1: Create Space
- Go to https://huggingface.co/spaces
- Click "Create new Space"
- Name:
document-classifier-env - License: MIT
- Space SDK: Docker
- Click "Create Space"
Step 2: Upload Files
git clone https://huggingface.co/spaces/YOUR_USERNAME/document-classifier-env
cd document-classifier-env
# Copy all files from project
cp c:\Users\91748\Desktop\metax\* .
# Commit and push
git add .
git commit -m "Initial OpenEnv environment"
git push
Step 3: Monitor Deployment
- Space automatically builds Docker image
- Watch build logs in Spaces UI
- Takes 5-10 minutes first time
- Then available at: https://huggingface.co/spaces/YOUR_USERNAME/document-classifier-env
Troubleshooting
Issue: "ModuleNotFoundError: No module named 'gymnasium'"
Solution:
pip install -r requirements.txt
# or
pip install gymnasium numpy pandas scikit-learn pyyaml requests flask gradio
Issue: "Port 7860 already in use"
Solution:
# Option 1: Use different port
python -c "from app import create_interface; create_interface().launch(server_port=8080)"
# Option 2: Kill process using port 7860
# Windows: taskkill /IM python.exe /F
# Linux: lsof -ti:7860 | xargs kill -9
Issue: "Docker build fails"
Solution:
# Clean build
docker build --no-cache -t doc-classifier:latest .
# Check Docker is running
docker ps
# Check Dockerfile syntax
docker build --progress=plain -t doc-classifier .
Issue: Tests fail with "Feature extraction error"
Solution:
# Reinstall scikit-learn
pip install --upgrade scikit-learn
python test_environment.py
Performance Tuning
For Speed
# Use Easy task
env = DocumentClassificationEnv("easy") # 100 docs, no time limit
# Process in batches
batch_size = 10
for _ in range(batch_size):
action = agent.decide(obs)
obs, _, _, _, _ = env.step(action)
For Accuracy
# Use Hard task
env = DocumentClassificationEnv("hard") # 1000 docs, tight deadline
# Give more time per decision
import time
start = time.time()
action = agent.decide(obs) # Can take up to 1 second
elapsed = time.time() - start
For Reproducibility
# Use fixed seed
env = DocumentClassificationEnv("easy", seed=42)
obs, _ = env.reset(seed=42)
# Results will be identical across runs
Monitoring & Logging
Enable Logging
import logging
logging.basicConfig(level=logging.DEBUG)
env = DocumentClassificationEnv("easy")
obs, _ = env.reset()
Save Results
# Baseline evaluation saves JSON
python baseline_inference.py --task all --output results.json
# View results
cat results.json
File Monitoring
Watch for Changes
# Windows: Use `watchdog` package
pip install watchdog
watchmedo shell-command \
--patterns="*.py" \
--recursive \
--command='python test_environment.py' \
.
Getting Help
Check Logs
# Python logs
python -u baseline_inference.py --task easy 2>&1 | tee run.log
# Docker logs
docker logs CONTAINER_ID
docker logs -f CONTAINER_ID # Follow logs
Verify Setup
# Run diagnostic
python -c """
import gymnasium
import numpy as np
import pandas as pd
from sklearn.feature_extraction.text import TfidfVectorizer
from environment import DocumentClassificationEnv
print('β All imports successful')
env = DocumentClassificationEnv('easy')
obs, _ = env.reset()
print(f'β Environment initialized')
print(f'β Observation keys: {list(obs.keys())}')
print(f'β Features shape: {obs[\"features\"].shape}')
print('β Setup verified - ready to go!')
"""
Quick Command Reference
# Setup
pip install -r requirements.txt
# Test
python test_environment.py
# Evaluate
python baseline_inference.py --task all
# Run examples
python example_usage.py
# Interactive demo
python app.py
# Docker
docker build -t doc-classifier .
docker run -p 7860:7860 doc-classifier
# Cleanup
rm -rf __pycache__
rm -rf *.egg-info
rm -rf .pytest_cache
Summary
β
Installation: pip install -r requirements.txt
β
Test: python test_environment.py
β
Try it: python app.py
β
Evaluate: python baseline_inference.py --task all
β
Deploy: docker build . && docker run -p 7860:7860 doc-classifier
Your environment is ready to use!