Cleveland Kitchen POC - Feature Requests & Implementation Roadmap

Last Updated: March 5, 2026 (Post-Onsite Meeting)

---

Phase 1: Email Extraction & Validation (Weeks 2-4)

Feature 1.1: Excel File Extraction (✅ COMPLETE)

Priority: CRITICAL
Status: ✅ Implemented & Tested

Requirements:

• Extract data from .xlsx files (Giant Eagle format)
• Extract data from .xls files (Heinen’s legacy binary format)
• Handle variable column counts, merged cells, empty rows
• Normalize sheet data to consistent row/column structure

Implementation:

• ✅ Use openpyxl engine for .xlsx files
• ✅ Add xlrd fallback for .xls (pandas 2.0+ compatibility)
• ✅ Handle merged cells via forward/backward fill
• ✅ Drop completely empty rows/columns
• ✅ Create placeholder names for unnamed columns

Tests:

• ✅ test_file_processing.py: 3 tests passing
• ✅ Giant Eagle .xlsx: 33 rows, 9 columns
• ✅ Heinen’s .xls: 19 rows, 31 columns

Evidence: commit e11c3ad1 + commit dda39dc8

---

Feature 1.2: Discount/Allowance Detection & Visual Indicator

Priority: HIGH
Status: 🔄 IN PROGRESS

Requirements:

• Detect discount/allowance line items in extracted orders
• Flag as separate line items (negative pricing in WhereFour)
• Display visual chip/badge in Ordermatic UI to show “discount applied”
• Prevent reviewer from overriding ERP price when discount already applied

Business Context:

• Cleveland Kitchen customers (e.g., Giant Eagle) have tiered pricing
  • List price: $21.50/unit
  • Customer agreement price: $20.00/unit
  • WhereFour handles as: full price ($21.50) + allowance line (-$1.50)
• Reviewers should see the discount chip to understand price difference
• Without visual indicator, reviewers feel compelled to manually change to $20

Implementation Plan:

1. Add discount detection in extraction logic
   • Keywords: “discount”, “rebate”, “allowance”, “promotional”, “offset”
   • Pattern matching for negative line items
   • Cross-reference against known allowance SKUs in master item list
2. Mark order with has_discount_applied: true flag
3. In DocumentOrderReview UI component:
   • Show yellow chip next to price field: “Discount Applied: -$1.50”
   • Styling: bg-yellow-50 border-l-4 border-yellow-400
   • Text: Small gray label explaining ERP price override

Design Reference: CK POC pricing verification alert (already in codebase)

Acceptance Criteria:

• ✅ Discount line items detected in 95%+ of applicable orders
• ✅ Visual chip visible in order review UI
• ✅ Reviewer sees explanation of why price differs from PDF

---

Feature 1.3: Multi-Address Extraction & Validation

Priority: HIGH
Status: 🔄 DESIGN PHASE

Requirements:

• Extract three distinct address types from email orders:
  1. Shipping Address - where products ship
  2. Billing Address - where invoice goes
  3. Location/Warehouse - customer’s DC (affects pricing tier)
• Validate each address against WhereFour customer record
• Flag if address is missing or unrecognized in system

Business Context:

• Cleveland Kitchen customers often have different shipping vs. billing addresses
• Pricing tiers may be location-specific (e.g., main facility vs. secondary DC)
• WhereFour tracks all three; Ordermatic must extract all three

Implementation Plan:

1. Enhance extraction prompt to request three address fields
   • “Shipping Address: [Where products should be delivered]”
   • “Billing Address: [Where invoice should go]”
   • “Location/Warehouse: [Specific facility or DC name]”
2. Add WhereFour address lookup:
   • Query /customers/{customer_id}/addresses (custom endpoint, verify in API)
   • Match extracted addresses against known locations
   • Flag new/unrecognized addresses for manual review
3. In order validation:
   • Require shipping address OR location to determine pricing tier
   • Flag if neither is provided
4. UI: Show all three address fields with validation status

Acceptance Criteria:

• ✅ All three address types extracted from 90%+ of orders
• ✅ WhereFour address validation working
• ✅ Flagged correctly if address is missing or unrecognized

---

Feature 1.4: Email Threading - Initial PO Only (✅ CONFIRMED)

Priority: MEDIUM
Status: ✅ DECISION MADE

Requirements:

• Monitor email threads; extract initial PO only
• Do NOT process reply emails for modifications (discount changes, date changes, etc.)
• Flag entire thread for human review if multiple POs/versions detected

Business Context:

• Cleveland Kitchen changes orders hourly (production scheduling)
• Email thread-based AI extraction would cause chaos
• CSR/Philippines team manually updates orders in Ordermatic as needed
• Integration log in WhereFour shows all changes for audit

Implementation:

• ✅ Use email hash mapping: identical PDF/content = skip
• ✅ New PDF or modified content = trigger new extraction
• Configuration flag per org: email_thread_mode: "initial_po_only"

Future Enhancement (Phase 4):

• Email Thread Skill: Listen for specific order modifications
  • “if discount is wrong” → generate new quote, send to inbox
  • “if shipping date changes” → auto-update order for CSR approval
  • “if location changes” → validate new pricing tier

Status Decision: APPROVED - implement initial PO only for Phase 1

---

Feature 1.5: Auto-Submission on Zero Validation Issues

Priority: HIGH
Status: 🔄 IN PROGRESS

Requirements:

• When extracted order has ZERO validation issues (all fields valid, all addresses matched, pricing confirmed):
  • Auto-submit to WhereFour
  • Log submission with metadata (extraction confidence, validation results)
  • Philippines team reviews only problematic orders (5-30 sec QA check)
• Generate integration log in WhereFour showing:
  • Ordermatic order ID
  • Extraction timestamp
  • AI confidence scores
  • Any flags/warnings

Business Context:

• Reduces manual review burden on Philippines team
• Creates eval set for future automation (Phase 3+)
• Builds trust in system through transparency

Implementation Plan:

1. Add validation scoring in Ordermatic
   • Customer ID match: confidence score
   • Shipping address match: confidence score
   • All SKUs found in inventory: confidence score
   • Pricing validated (no new customer/SKU combos): confidence score
   • Overall threshold: >= 95% confidence = auto-submit
2. WhereFour integration log:
   • Custom field or API endpoint to store extraction metadata
   • Query: POST /orders/{order_id}/integration_log (verify in API)
3. Dashboard for Philippines team:
   • “Auto-submitted” orders (view only, not editable)
   • “Requires Review” orders (full edit access)
   • Filters by date, customer, issue type

Acceptance Criteria:

• ✅ 60-80% of orders auto-submit without human review
• ✅ Integration log visible in WhereFour UI
• ✅ Zero auto-submitted orders have validation errors in production

---

Feature 1.6: Boilerplate Filtering (Contract Language)

Priority: MEDIUM
Status: 🔄 DESIGN PHASE

Requirements:

• Filter out contract/legal language from PDFs before extraction
• Focus extraction on actual order data (customer, SKUs, quantities, prices)
• Example: Cisco order contains extensive legal jargon → ignore, extract order only

Implementation Plan:

1. Identify boilerplate patterns:
   • Legal disclaimers
   • Terms & conditions blocks
   • Company signatures
   • Payment terms sections
2. Add filter step before LLM extraction:
   • Detect boilerplate regions (heuristic or ML-based)
   • Remove or mask before prompt
3. Test with Cisco order (known high boilerplate)

Acceptance Criteria:

• ✅ Extraction accuracy same or better when boilerplate removed
• ✅ Cisco order extracted without legal noise

---

Phase 2: WhereFour Integration (Weeks 5-10) - PLANNED

Feature 2.1: WhereFour API Mock & Dagster Simulation

Priority: CRITICAL
Status: 🔄 IN PROGRESS

Requirements:

• Fully mock WhereFour API endpoints based on OpenAPI spec
• Support order creation, customer lookup, inventory search, pricing validation
• Enable Dagster pipeline simulation (crawl products, sync pricing, validate orders)
• Seed mock data with real Cleveland Kitchen customers/products

Endpoints to Mock (from OpenAPI spec):

GET  /customers
GET  /customers/{customer_id}
GET  /customers/search
GET  /customers/{customer_id}/orders
POST /customers/{customer_id}/orders
GET  /customers/{customer_id}/orders/{order_id}
GET  /inventory
GET  /inventory/search
GET  /orders
POST /orders
GET  /orders/{order_id}
GET  /inventory/{inventory_id}/stocks

Implementation:

• Create Mockoon collection from OpenAPI spec
• Seed mock database with:
  • 5 Cleveland Kitchen customers (Giant Eagle, Heinen’s, Rainforest, etc.)
  • 20+ inventory items (Kimchi, Kraut, Pickle SKUs with UPC variations)
  • 10 orders (mix of clean and problematic)
  • Pricing tiers per customer

Testing:

• Dagster pipeline crawls mock inventory
• Sync pricing tiers to Ordermatic
• Validate sample orders against mock WhereFour

---

Feature 2.2: Pricing Tier Validation (New Customer/SKU Flagging)

Priority: HIGH
Status: 🔄 DESIGN PHASE

Requirements:

• Check if customer + SKU combination exists in WhereFour pricing
• Flag for manual review if NEW pairing (first-time order for that combo)
• Display yellow chip in UI: “New Customer/SKU Pairing - Review Pricing”

Implementation:

• Query WhereFour pricing API
• Cross-reference extracted customer + each SKU
• Build pricing cache (local copy of WhereFour pricing tiers)
• Flag unknowns

---

Feature 2.3: Inventory Blocking - DISABLED

Priority: CRITICAL
Status: ✅ CONFIRMED

Requirements:

• Do NOT block orders due to low inventory
• Cleveland Kitchen manages MRP in Excel (not WhereFour)
• WhereFour inventory data unreliable for decision-making
• Orders MUST submit regardless of stock status

Implementation:

• ✅ Disable inventory checks in validation logic
• ✅ Configuration flag: skip_inventory_validation: true for CK org

---

Phase 3 & Beyond: Optimization & Learning (Ongoing)

Feature 3.1: Same-as-Last-Time Order Detection

Priority: MEDIUM
Status: 🔄 FUTURE (Phase 3)

Requirements:

• Detect “same as last week” or “repeat previous order” references
• Extract reference date or order number
• Flag for human review to confirm quantities/pricing haven’t changed

Future Enhancement: Query WhereFour order history API, auto-suggest previous order match

---

Feature 3.2: Email Thread Skill (Future)

Priority: LOW
Status: 🔄 FUTURE (Phase 4)

Requirements:

• AI listens for specific order modifications in reply threads
• Generate new quote with proposed changes → send to inbox
• Auto-update order in Ordermatic for CSR approval

Trigger Examples:

• “discount is wrong”
• “change DC to [location]”
• “different shipping date”

---

Success Criteria Summary

Phase 1 (Extraction PoC) - Week 4

• ✅ Excel extraction working (both .xlsx and .xls)
• ✅ Discount detection & visual chip
• ✅ Multi-address extraction + validation
• ✅ Email initial-PO-only configured
• ✅ 90%+ extraction accuracy on Cleveland Kitchen sample orders
• ✅ Correct UPC normalization (12-digit ↔ 14-digit)
• ✅ Ben + Philippines team approve quality

Phase 2 (WhereFour Integration) - Week 10

• ✅ Orders successfully created in WhereFour
• ✅ Pricing validation working (flags new customer/SKU combos)
• ✅ Inventory blocking disabled (orders submit regardless of stock)
• ✅ Auto-submission on zero validation issues
• ✅ Integration log visible in WhereFour
• ✅ Error rate < 2%
• ✅ Philippines team reports time savings

Phase 3 (Optimization) - Week 12+

• ✅ 60-80% of orders require minimal human editing
• ✅ Same-as-last-time order detection working
• ✅ CSR team trusts system enough to reduce validation time
• ✅ Cleveland Kitchen decides to move forward with paid agreement

---

Risk Mitigation

Risk	Mitigation
UPC/SKU mapping complexity	Per-customer cross-ref table, human-in-loop for first occurrence
WhereFour API limitations	Early exploration, fallback to ODBC/CSV if needed
Email thread chaos	Initial-PO-only mode, human makes changes in Ordermatic
Discount detection errors	Visual chip prevents overrides, easy human verification
Inventory blocking trap	Feature explicitly disabled via config flag

---

Delivery Milestones

Milestone	Target	Owner
Phase 1 Demo Video (Giant Eagle + Heinen’s)	This weekend	David
WhereFour Sandbox Access	ASAP	Dan (CK)
4-Month Historical ROI Data	ASAP	Dan (CK)
Master Item List + Cross-Ref Table	ASAP	Ben (CK)
Mockoon WhereFour Mock Complete	Week 2	David
Phase 1 PoC Testing & Refinement	Week 3	David + Ben
Phase 1 Success Signoff	Week 4	Dan + Ben (CK)