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

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

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.

See INTEGRATIONS.md for complete integration architecture