Workbook Tools

Tools for maintaining an audit trail of classification decisions.

Overview

The workbook provides persistent storage for classification decisions, enabling:

Audit trails for compliance
Documentation of reasoning
Historical reference for similar businesses
Review workflows for low-confidence classifications

write_to_workbook

Save a classification decision to the workbook.

Parameters

Parameter	Type	Required	Description
`description`	string	Yes	Business description
`code`	string	Yes	Assigned NAICS code
`confidence`	float	Yes	Confidence score (0-1)
`reasoning`	string	No	Classification reasoning
`alternatives`	array	No	Alternative codes considered
`user_notes`	string	No	Additional notes
`tags`	array	No	Tags for categorization

Response


{
  "entry_id": "cls_20240115_001",
  "status": "saved",
  "timestamp": "2024-01-15T10:30:00Z",
  "summary": {
    "description": "Organic dog treat manufacturer",
    "code": "311111",
    "confidence": 0.91
  }
}

Example


{
  "description": "Company that manufactures organic dog treats",
  "code": "311111",
  "confidence": 0.91,
  "reasoning": "Primary activity is manufacturing dog food products from organic ingredients",
  "alternatives": [
    {
      "code": "311119",
      "reason": "Considered but rejected - products are dog-specific"
    }
  ],
  "user_notes": "Verified with client that 100% of revenue is from manufacturing",
  "tags": ["manufacturing", "pet-food", "verified"]
}

read_workbook

Retrieve saved classification decisions from the workbook.

Parameters

Parameter	Type	Required	Default	Description
`entry_id`	string	No	—	Specific entry ID
`code`	string	No	—	Filter by NAICS code
`tag`	string	No	—	Filter by tag
`min_confidence`	float	No	—	Minimum confidence
`max_confidence`	float	No	—	Maximum confidence
`from_date`	string	No	—	Start date (ISO format)
`to_date`	string	No	—	End date (ISO format)
`limit`	integer	No	`50`	Maximum results

Response


{
  "entries": [
    {
      "entry_id": "cls_20240115_001",
      "timestamp": "2024-01-15T10:30:00Z",
      "description": "Organic dog treat manufacturer",
      "code": "311111",
      "title": "Dog and Cat Food Manufacturing",
      "confidence": 0.91,
      "reasoning": "Primary activity is manufacturing...",
      "alternatives": [...],
      "user_notes": "Verified with client...",
      "tags": ["manufacturing", "pet-food", "verified"]
    }
  ],
  "total_results": 1,
  "filters_applied": {
    "code": null,
    "tag": null,
    "date_range": null
  }
}

Examples

Get specific entry:


{
  "entry_id": "cls_20240115_001"
}

Filter by code:


{
  "code": "311111"
}

Filter by tag:


{
  "tag": "needs-review"
}

Filter by confidence:


{
  "max_confidence": 0.7,
  "tag": "pending"
}

Filter by date:


{
  "from_date": "2024-01-01",
  "to_date": "2024-01-31"
}

Workflow Patterns

Audit Trail Workflow


1. classify_business(description)
2. Present to user for confirmation
3. write_to_workbook(
     description,
     code,
     confidence,
     reasoning,
     user_notes: "Approved by [name]"
   )

Review Workflow


1. read_workbook(max_confidence: 0.7, tag: "pending")
2. For each entry:
   a. validate_classification(description, code)
   b. If invalid, get alternatives
   c. Update workbook with final decision

Compliance Reporting


1. read_workbook(
     from_date: "2024-Q1-start",
     to_date: "2024-Q1-end"
   )
2. Generate report with:
   - Total classifications
   - Confidence distribution
   - Codes by frequency

Tagging Best Practices

Use tags to organize classifications:

Tag	Usage
`verified`	Confirmed by subject matter expert
`needs-review`	Low confidence, requires human review
`client-confirmed`	Client verified the classification
`batch-import`	Imported from bulk classification
`updated`	Previously classified, updated

Example Tagging


{
  "tags": ["manufacturing", "pet-industry", "verified", "2024-Q1"]
}

Data Retention

Workbook entries are persisted across server restarts
Consider implementing archival for old entries
Export periodically for backup

Integration with Classification

The workbook integrates with the classification workflow:


classify_business()
        │
        ▼
Present recommendation
        │
        ▼
User confirms/modifies
        │
        ▼
write_to_workbook()
        │
        ▼
Entry saved with full context