|
Download VISUAL_GUIDE.md from VoidWalkers/document-classification-env: direct link, hf CLI and curl.
- Browser
- Download file 27.6 kB
-
https://huggingface.co/spaces/VoidWalkers/document-classification-env/resolve/main/VISUAL_GUIDE.md
- Command line
-
hf download hf://spaces/VoidWalkers/document-classification-env/VISUAL_GUIDE.md
-
curl -L -o VISUAL_GUIDE.md https://huggingface.co/spaces/VoidWalkers/document-classification-env/resolve/main/VISUAL_GUIDE.md
27.6 kB
π VISUAL GUIDE - HOW THE OPENENV WORKS
π¬ Complete Agent Interaction Flow
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β OPENENV DOCUMENT CLASSIFICATION ENVIRONMENT β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
ββββββββββββββββββββ START EPISODE ββββββββββββββββββββ
env.reset()
β
βΌ
βββββββββββββββββββββββββββββββββββββββ
β Generate Documents β
β βββββββββββββββββββββββββββββββββ β
β Easy: 100 documents β
β Medium: 500 documents β
β Hard: 1000 documents β
β β
β Categories: [5/10/20] β
β Features: TF-IDF (100-dim) β
βββββββββββββββββββββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββ
β Return Initial Observation β
β βββββββββββββββββββββββββββββββββ β
β { β
β "document_id": "doc_000000", β
β "content": "My invoice...", β
β "word_count": [47], β
β "features": [0.12, -0.34, ...], β
β "document_index": [0], β
β "total_documents": [100] β
β } β
βββββββββββββββββββββββββββββββββββββββ
β
ββββββββββββββββββββ AGENT LOOP ββββββββββββββββββββ
β
βββ [ DOCUMENT 1 ]
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β Agent Analyzes Document β
β β "My invoice shows error" β
β β β Features: TF-IDF weights β
β β β Decision: Category? β
β ββββββββββββββββββββββββββββββββββ
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β Agent Decision β
β β ββββββββββββββββββββββββββ β
β β Possible Actions (Easy): β
β β β’ 0 = General β
β β β’ 1 = Billing ββ PREDICTED β
β β β’ 2 = Support β
β β β’ 3 = Technical β
β β β’ 4 = HR β
β β β
β β Agent chooses: action = 1 β
β ββββββββββββββββββββββββββββββββββ
β β
β βΌ
β env.step(action=1)
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β Evaluate Decision β
β β ββββββββββββββββββββββββββ β
β β True Label: Billing (1) β β
β β Predicted: Billing (1) β β
β β Result: CORRECT! β
β ββββββββββββββββββββββββββββββββββ
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β Calculate Reward β
β β ββββββββββββββββββββββββββ β
β β Correct: +1.0 β β
β β Speed: +0.1 (< 100ms) β β
β β βββββββββββββββββββββββββ β
β β Total: +1.1 β
β ββββββββββββββββββββββββββββββββββ
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β Update Episode Stats β
β β ββββββββββββββββββββββββββ β
β β Correct: 1/1 = 100% β
β β Total Reward: 1.1 β
β β Avg Reward: 1.1 β
β ββββββββββββββββββββββββββββββββββ
β β
βββ [ DOCUMENT 2 ]
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β "I found a bug in system" β
β β True Label: Technical (3) β
β β Predicted: Support (2) β β
β β ββββββββββββββββββββββββββ β
β β Correct: -0.5 β β
β β Speed: +0.1 β β
β β Total: -0.4 β
β β ββββββββββββββββββββββββββ β
β β Accuracy: 1/2 = 50% β
β ββββββββββββββββββββββββββββββββββ
β β
β βΌ
β ... REPEATS FOR ALL DOCUMENTS ...
β β
βββ [ DOCUMENT N ]
β β
β βΌ
β ββββββββββββββββββββββββββββββββββ
β β Last Document β
β β All predictions made β
β β Episode complete! β
β ββββββββββββββββββββββββββββββββββ
β
ββββββββββββββββββββ END EPISODE ββββββββββββββββββββ
β
βΌ
βββββββββββββββββββββββββββββββββββββββ
β Episode Summary β
β βββββββββββββββββββββββββββββββββ β
β β’ Total Accuracy: 87/100 = 87% β
β β’ Total Reward: 87.3 β
β β’ Avg Time/Doc: 50ms β
β β’ Final Score: 0.87 (Easy) β
β βββββββββββββββββββββββββββββββββ β
β Returns: β
β - obs: empty (episode done) β
β - reward: 0.0 β
β - done: True β
β - info: β
β ββ episode_summary: {...} β
βββββββββββββββββββββββββββββββββββββββ
β
βΌ
Agent has learned from 100 documents!
Ready for next episode or deployment.
π Task Difficulty Progression
EASY (BASELINE: 0.78)
ββββββββββββββββββββββββββββββββββ
β Categories: 5 (Simple) β
β ββ General β
β ββ Billing β
β ββ Support β
β ββ Technical β
β ββ HR β
β β
β Documents: 100 (Pre-processed) β
β Time Limit: None β
β Challenge Level: β β
β Training Time: 1-2 seconds β
ββββββββββββββββββββββββββββββββββ
β
β Difficulty increases
βΌ
MEDIUM (BASELINE: 0.65)
ββββββββββββββββββββββββββββββββββ
β Categories: 10 (Detailed) β
β ββ General β
β ββ Billing β
β ββ Billing-Dispute β NEW β
β ββ Support β
β ββ Technical β
β ββ Technical-Bug β NEW β
β ββ HR-Payroll β
β ββ HR-Benefits β
β ββ Legal β
β ββ Executive β
β β
β Documents: 500 (Raw text) β
β Time Limit: 2 seconds/doc β
β Challenge Level: ββ β
β Training Time: 10-15 seconds β
ββββββββββββββββββββββββββββββββββ
β
β Difficulty increases
βΌ
HARD (BASELINE: 0.52)
ββββββββββββββββββββββββββββββββββ
β Categories: 20 (Fine-grained) β
β ββ General β
β ββ Billing / Billing-Dispute β
β ββ Billing-Refund β NEW β
β ββ Support-Urgent / Support- β
β β Normal β NEW (split) β
β ββ Technical / Technical-Bug β
β ββ Technical-Feature β NEW β
β ββ HR (3 variants) β
β ββ Legal (3 variants) β
β ββ Executive (2 variants) βNEW β
β ββ Finance β NEW β
β ββ Marketing β NEW β
β ββ Operations β NEW β
β β
β Documents: 1000 (Complex) β
β Time Limit: 1 second/doc β
β Challenge Level: βββ β
β Training Time: 30-60 seconds β
β Speed-Accuracy Tradeoff: YES β
ββββββββββββββββββββββββββββββββββ
π Scoring System Visualization
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β EASY TASK SCORING β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Calculation: SCORE = ACCURACY β
β β
β Example: 87 correct out of 100 β
β ββββββββββββββββββββββββββββββββββββββββββββββββ β
β Score = 87 / 100 = 0.87 β
β β
β Interpretation: β
β 1.0 ββββββββββββββββββββ Perfect β
β 0.9 ββββββββββββββββββββ Excellent β
β 0.8 ββββββββββββββββββββ Good ββ 0.87 (HERE) β
β 0.7 ββββββββββββββββββββ Fair β
β 0.6 ββββββββββββββββββββ Poor β
β 0.5 ββββββββββββββββββββ Baseline β
β 0.0 ββββββββββββββββββββ Random β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MEDIUM TASK SCORING β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Calculation: SCORE = 0.8 Γ ACCURACY + 0.2 Γ SPEED β
β β
β Example: β
β Accuracy = 68% β
β Processing Time = 140ms (within 2s limit) β 0.15 β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β Score = 0.8 Γ 0.68 + 0.2 Γ 0.15 β
β Score = 0.544 + 0.03 = 0.574 β
β β
β (Without speed bonus it would be 0.544) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β HARD TASK SCORING β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Calculation: SCORE = 0.75 Γ ACCURACY + 0.25 Γ SPEED β
β β
β Example: β
β Accuracy = 73% (1000 docs, this is hard!) β
β Processing Time = 95ms (< 100ms) β 0.20 bonus β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β Score = 0.75 Γ 0.73 + 0.25 Γ 0.20 β
β Score = 0.5475 + 0.05 = 0.5975 β
β β
β Speed is MORE valued in hard task (tradeoff) β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π° Reward Mechanics
CORRECT CLASSIFICATION
βββββββββββββββββββββββ
β Accuracy: +1.0 β
βββββββββββββββββββββββ
+
βββββββββββββββββββββββ ββββββββββββββββββββββββββββ
β Speed Bonus: ββββββΆβ Easy: +0.1 (< 100ms) β
β β β Medium: +0.15 (< 200ms) β
β β β Hard: +0.2 (< 100ms) β
βββββββββββββββββββββββ ββββββββββββββββββββββββββββ
β
βΌ
+1.1 to +1.2 Reward β
ββββββββββββββββββββββββββββββββββββββββ
INCORRECT CLASSIFICATION
βββββββββββββββββββββββ
β Accuracy: -0.5 β
βββββββββββββββββββββββ
+
βββββββββββββββββββββββ ββββββββββββββββββββββββββββ
β Speed Bonus: ββββββΆβ Easy: +0.1 (< 100ms) β
β β β Medium: +0.15 (< 200ms) β
β β β Hard: +0.2 (< 100ms) β
βββββββββββββββββββββββ ββββββββββββββββββββββββββββ
β
βΌ
-0.4 to -0.3 Reward β
ββββββββββββββββββββββββββββββββββββββββ
EPISODE REWARD ACCUMULATION (100 documents, Easy)
ββββββββββββββββββββββββββββββββββββββββββββββββ
β Doc 1: +1.1 β Total: 1.1 Acc: 100% β
β Doc 2: -0.4 β Total: 0.7 Acc: 50% β
β Doc 3: +1.1 β Total: 1.8 Acc: 67% β
β Doc 4: +1.1 β Total: 2.9 Acc: 75% β
β ... β
β Doc 87: +1.1 β Total: 87.3 Acc: 87% β ββ Final
β Doc 88: -0.4 β Total: 86.9 Acc: 86.36% β
β ... β
β Doc100: +1.1 β Total: 87.3 Acc: 87% β
β β
β Average Reward = 87.3 / 100 = 0.873 β
β Final Score = 0.87 β
ββββββββββββββββββββββββββββββββββββββββββββββββ
π Document Feature Representation
Document Text
β
βΌ
"I was overcharged on my last invoice"
β
β (TF-IDF Vectorizer)
β Extract important words
βΌ
[word_weights: 100 dimensional vector]
β
β Common words (low importance):
β "I", "on", "my" β near 0
β
β Important words (high importance):
β "overcharged" β 0.45 (rare, specific)
β "invoice" β 0.52 (rare, specific)
β "billing" β 0.38 (related, important)
β
βΌ
[-0.02, 0.45, 0.52, -0.01, ..., 0.38] ββ Fed to agent
(100 dimensions total)
β
βΌ
Agent Neural Net:
Input: [100 features]
βΌ
Hidden Layer 1: Learns feature combinations
βΌ
Hidden Layer 2: Learns category patterns
βΌ
Output: [5/10/20 category logits]
βΌ
Softmax: Probability distribution
βΌ
ArgMax: Best category
βΌ
Action: Category index (0-4, 0-9, or 0-19)
β
βΌ
Decision: "This is BILLING (category 1)"
π― Agent Learning Process
Episode 1: Random Guessing
ββββββββββββββββ
β Accuracy: 20%β ββ 1 in 5 correct (random)
β Score: 0.20 β
ββββββββββββββββ
β
βΌ
Agent learns: Document contains "invoice" β likely Billing
β
βΌ
Episode 2-5: Learning Keywords
ββββββββββββββββ
β Accuracy: 45%β ββ Better than random
β Score: 0.45 β
ββββββββββββββββ
β
βΌ
Agent learns: Category combinations, priority
β
βΌ
Episode 6-20: Pattern Recognition
ββββββββββββββββ
β Accuracy: 75%β ββ Strong signal learning
β Score: 0.75 β
ββββββββββββββββ
β
βΌ
Agent learns: Subtle distinctions, edge cases
β
βΌ
Episode 21+: Expert Level
ββββββββββββββββ
β Accuracy: 87%β ββ Near human performance
β Score: 0.87 β
ββββββββββββββββ
β
βΌ
Agent learns: Rare cases, complex routing
β
βΌ
Final: Deployed
π Full Example: One Complete Classification
STEP 1: Document Arrives
ββββββββββββββββββββββββββββββββββββ
β Email: "I was charged twice for β
β my order #5432. Please refund β
β one charge immediately!" β
ββββββββββββββββββββββββββββββββββββ
STEP 2: Features Extracted
ββββββββββββββββββββββββββββββββββββ
β Tokenized: ["charged", "twice", β
β "order", "refund", "immediately"]β
β β
β TF-IDF Vector: 100-dimensional β
β [0.45, 0.38, 0.52, 0.41, ...] β
ββββββββββββββββββββββββββββββββββββ
STEP 3: Agent Processes
ββββββββββββββββββββββββββββββββββββ
β Input: Feature vector β
β Process: Neural network inferenceβ
β Logits: [0.1, 0.9, 0.3, ...] β
β Probabilities: β
β General: 5% β
β Billing-Dispute: 85% ββ MAX β
β Support: 10% β
ββββββββββββββββββββββββββββββββββββ
STEP 4: Decision Made
ββββββββββββββββββββββββββββββββββββ
β Selected Category: β
β action = 2 (Billing-Dispute) β
β β
β Reasoning: β
β β’ "charged" + "twice" = dispute β
β β’ "refund" = compensation claim β
β β’ "immediately" = urgent tone β
ββββββββββββββββββββββββββββββββββββ
STEP 5: Evaluation
ββββββββββββββββββββββββββββββββββββ
β Ground Truth: Billing-Dispute β
β Prediction: Billing-Dispute β
β Result: β CORRECT β
β β
β Reward: β
β β’ Accuracy: +1.0 β
β β’ Speed (45ms): +0.1 β
β β’ Total: +1.1 β
ββββββββββββββββββββββββββββββββββββ
STEP 6: Routing
ββββββββββββββββββββββββββββββββββββ
β Route to Department: β
β β Billing Team β
β β Dispute Resolution Sub-team β
β β Priority: High β
β β
β Action Taken: Email forwarded β
β Learning: Agent improved score β
ββββββββββββββββββββββββββββββββββββ
π Performance Benchmarks
Baseline Agent Performance Across Tasks:
Easy Task (5 categories)
βββββββββββββββββββββββββββββββββββ
β Accuracy: 78% βββββββββ β
β Reward: 0.83 β
β Time: 48ms β
β Score: 0.78 β
βββββββββββββββββββββββββββββββββββ
ββ Why 78%? Keyword matching
β works well for simple cases
ββ Gap to perfect: 22%
Medium Task (10 categories)
βββββββββββββββββββββββββββββββββββ
β Accuracy: 68% ββββββββββ β
β Reward: 0.71 β
β Time: 150ms β
β Score: 0.65 β
βββββββββββββββββββββββββββββββββββ
ββ Why 68%? More categories,
β harder to distinguish
ββ Gap to target (0.85): 20%
Hard Task (20 categories)
βββββββββββββββββββββββββββββββββββ
β Accuracy: 55% βββββββββββββ β
β Reward: 0.57 β
β Time: 100ms β
β Score: 0.52 β
βββββββββββββββββββββββββββββββββββ
ββ Why 55%? Complex routing,
β tight time constraints
ββ Gap to target (0.75): 23%
Expected ML Model Performance:
βββββββββββββββββββββββββββββββββββ
β Easy: 0.95+ (Expert) β
β Medium: 0.85+ (Strong) β
β Hard: 0.75+ (Capable) β
βββββββββββββββββββββββββββββββββββ
π Summary
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β COMPLETE OPENENV DOCUMENT CLASSIFICATION SYSTEM β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β INPUT: Documents + Content + Features β
β βΌ β
β PROCESS: TF-IDF β Agent Decision β Evaluation β
β βΌ β
β OUTPUT: Score (0.0-1.0) + Feedback β
β β
β RESULT: Agents learn to route documents! β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Ready to deploy and test! β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββ