|
Download VISUAL_GUIDE.md from muffin2006/document-classification-env: direct link, hf CLI and curl.
- Browser
- Download file 27.6 kB
-
https://huggingface.co/spaces/muffin2006/document-classification-env/resolve/main/VISUAL_GUIDE.md
- Command line
-
hf download hf://spaces/muffin2006/document-classification-env/VISUAL_GUIDE.md
-
curl -L -o VISUAL_GUIDE.md https://huggingface.co/spaces/muffin2006/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! β | |
| βββββββββββββββββββββββββββββββββββββββββββββββββββββββ | |
| ``` | |