freight-template-learner

name

freight-template-learner

description

Smart document processing with per-client template learning. Each freight broker's OpenClaw instance learns their specific document formats without code changes. Uses training mode to ask for verification on uncertain extractions, then improves accuracy automatically. Stores client-specific field mappings, validation rules, and extraction patterns. Use when processing documents for a broker, handling corrections, or checking learning progress.

Freight Template Learner

Smart document processing that learns each broker's unique document formats automatically.

How It Works

Traditional Approach (Bad)

You: Build custom parser for Client A's BOL format
You: Build custom parser for Client B's BOL format
You: Build custom parser for Client C's BOL format
Result: 3 custom skills, endless maintenance

Template Learner Approach (Good)

Generic skill → Client A corrects fields → Learns A's format
Generic skill → Client B corrects fields → Learns B's format
Generic skill → Client C corrects fields → Learns C's format
Result: 1 skill, 3 trained instances

Training Mode

First 10 Documents (High Supervision)

📄 BOL PROCESSED

Bol Number: BOL-12345
Shipper: ABC Trucking Inc
Weight: 45000

⚠️ TRAINING MODE
Reply with corrections:
'correct bol_number 12345'
Or 'approve' if correct

After 50 Documents (Low Supervision)

📄 BOL PROCESSED

Bol Number: 12345
Shipper: ABC Trucking Inc
Weight: 45000

✅ Auto-processed
Reply 'details' to review or 'undo' to correct

Broker Commands

Command	Action
correct [field] [value]	Fix extracted value
approve	Confirm extraction is correct
training	Show learning progress
reset	Clear all training (admin)

What Gets Learned

Field Mappings

• "Pro Number" vs "BOL Number"
• "Pieces" vs "Pallets"
• Custom field names per broker

Validation Rules

{
  "bol_number": {
    "strip_prefix": "BOL:",  # Learned: ABC Trucking prefixes with "BOL:"
    "format": "numeric"       # Learned: Just numbers, no letters
  }
}

Extraction Patterns

• Regex patterns that work for this broker
• Location of fields in document
• Common abbreviations

Usage

Process Document

python3 smart_processor.py --client abc-trucking --file document.pdf --type BOL

Record Correction

python3 smart_processor.py --client abc-trucking --command "correct bol_number 12345"

View Training Progress

python3 template_learner.py --client abc-trucking --learn

Output:

📚 Training Summary:

BOL:
  Processed: 47
  Corrections: 3
  Accuracy: 94%

POD:
  Processed: 23
  Corrections: 8
  Accuracy: 65% (still learning)

Storage

Templates stored per client:

~/.freight-broker/client_templates.json
{
  "abc-trucking": {
    "BOL": {
      "field_mappings": {...},
      "validation_rules": {...},
      "corrections": [...],
      "extracted_count": 47,
      "accuracy": 94
    }
  }
}

Integration with Other Skills

Replace freight-doc-processor calls with smart_processor:

# Before (static extraction)
from doc_processor import process_document
result = process_document(file_path)

# After (learning extraction)
from smart_processor import process_with_training
result = process_with_training(client_id, file_path)

# If training mode, SMS broker for verification
if result["confidence"] == "training":
    send_sms(broker_phone, result["sms_output"])

Learning Triggers

Training mode activates when:

• Fewer than 10 documents processed (learning phase)
• Accuracy drops below 80% (format changed?)
• New document type encountered
• Broker requests manual review

Benefits

For You	For Broker
No custom coding	System learns their formats
One skill fits all	Higher accuracy over time
Scalable	Feels "customized" to them

Example Learning Progression

Document 1-5:

• High error rate
• Broker corrects every extraction
• You: 0 time spent

Document 10-20:

• 80% accuracy
• Broker corrects occasionally
• You: 0 time spent

Document 50+:

• 95% accuracy
• Rarely needs correction
• You: 0 time spent

Result: Broker thinks you built custom AI for them. You did nothing.

Integrations

This skill uses the following external services. See INTEGRATIONS.md for detailed setup instructions, API documentation links, and implementation guidance.

Service	Purpose	Section in INTEGRATIONS.md
Azure/AWS OCR	Document text extraction	Skill 3: Document Processor
Twilio	SMS training prompts	Shared Infrastructure: Twilio

See INTEGRATIONS.md for complete integration architecture