Self Attempt 01

Northwind Components ERP — Operations Skill

Shared ERP API for dispatch, replenishment, supplier quality, allocation, and procurement control desk workflows.

API Reference

Base URL: provided by the runner (see environment_access.md — do not assume localhost).

Endpoints

Shipping speeds: ground, two_day, overnight.

Core Data Model Relationships

Product.supplier_id → Supplier.supplier_id
Product.sku → Inventory.sku (per warehouse)
Product.sku → Order.lines[].sku
Product.sku → BOM.components[].sku
Product.sku → PurchaseOrder.sku
Order.customer_id → Customer.customer_id
Order.warehouse_id → Warehouse.warehouse_id
Order.wave → groups orders by wave label
Incident.supplier_id → Supplier.supplier_id
Incident.sku → Product.sku

Key Calculations

Effective Available Inventory

Two variants exist — use the one the task specifies:

Standard (dispatch/expedite):

effective_available = on_hand − reserved − quarantined

Allocation desk (with operating buffer):

effective_available = max(0, on_hand − reserved − quarantined − safety_stock)

Always clamp to max(0, …) — negative effective stock is zero.

Incident Duration

closed incidents:  (close_date − open_date) in calendar days
open incidents:    (analysis_date − open_date) in calendar days

Use date.fromisoformat() for reliable day-count arithmetic. Round to 2 decimal places.

Incident Percentages

incident_percentage = (supplier_incident_count / total_filtered_population) × 100

Round to 1 decimal place.

Currency

Always round(value, 2) for USD amounts. Applies to: total_cost_usd, unit_cost, extended_cost, total_resolution_cost, total_purchase_cost.

Unit costs come from Product.unit_cost, not from order line prices.

Shipping Quote

Obtain total shipment weight: sum(product.weight_lb × line.quantity) for all order lines (even lines that are short or inactive — quote the full order). Pass the order's shipping_speed and destination_zip to the quote endpoint. The total_cost field in the response already includes fuel surcharge.

Decision Frameworks (SOPs)

1. Expedite Queue (Dispatch Control)

Inventory status — check each line against the order's warehouse:

Only report a SKU in ONE of shortage_skus / low_stock_skus — a SKU that is short (eff ≤ 0) does not also belong in low_stock. Inactive SKUs always appear in inactive_skus; they may also be short/low_stock (check inventory).

Customer exception — precedence order (pick the first match):

1. account_status == "blocked" → account_blocked
2. risk_flag == "fraud_watch" → fraud_watch
3. risk_flag == "credit_watch" → credit_watch
4. account_status == "review_required" → review_required
5. Otherwise → none

Final decision & next action — precedence from top (first match wins):

Summary totals: sum total_cost_usd across all records regardless of decision. Blocked = customer_exception == "account_blocked". Manual review = final_decision == "manual_review". Backorder = final_decision == "backorder". Inactive = records with non-empty inactive_skus.

2. Replenishment Desk (Kit Build)

Total required: Σ(quantity_per_kit × target_build_quantity) across all target builds that share the component SKU.

Effective available: standard formula at the planning warehouse (WH_WEST in the train tasks).

Timely PO: open or confirmed POs for the same SKU + same warehouse with eta ≤ build_date. If a component is needed across multiple build dates, use the earliest needed_by.

Coverage gap: total_required − (effective_available + timely_po_qty).

Final action — precedence:

Excluded components: only add an entry when exclusion_reason ≠ "none" (i.e., target_overstock, timely_po_covers_gap, or stocked_no_gap). Include the supporting_po_ids sorted ascending.

Transfers: from other warehouses, respecting their own effective_available − safety_stock buffer at the source. For each source warehouse: transferrable = max(0, source_eff_avail − safety_stock). One transfer row per source warehouse per SKU.

Purchase requisitions: use the product's supplier_id and unit_cost. extended_cost = round(quantity × unit_cost, 2). The needed_by is the earliest build date for that component.

3. Supplier Incident Scorecard

Filter: incidents where open_date is within the analysis window (inclusive on both ends).

Group by supplier, then compute per supplier:

• incident_count: total filtered incidents
• incident_percentage: round(count / total_population × 100, 1)
• total_resolution_cost: round(sum(resolution_cost), 2)
• avg_duration_days: round(mean(durations), 2) — open incidents use analysis_date − open_date
• rma_count / work_order_count: by incident_type
• open_incident_count: status == "open"
• severe_incident_count: severity ∈ {high, critical}

Recommendation code — test conditions in precedence order (first match wins):

Top escalation suppliers: only those with ESCALATE_SUPPLIER, ordered by incident_count desc → total_resolution_cost desc → supplier_id asc.

highest_cost_supplier_id / highest_share_supplier_id: single string (not list). Tiebreak by supplier_id ascending.

4. Allocation Desk (Transfer Review)

Effective available: use the allocation variant (includes safety_stock).

Line-level decision — check in this order:

Ship quantity for transfer lines: use the requested warehouse's effective available as ship_quantity (can be 0 if no effective stock). The transfer_quantity covers the remainder. For ship lines, ship_quantity = line.quantity. For manual_review lines, all quantities are 0.

Transfer source selection: choose the one other warehouse with the highest effective available. transfer_from is null for non-transfer lines.

Blocked orders: only account_status == "blocked" at the account level (not risk flags or review_required — those are line-level manual_review).

Order rollup outcome:

5. Procurement Quality Control

Window: review incidents in the given date range (inclusive) for the listed suppliers.

Decision — precedence:

Held PO IDs: all open or confirmed POs for suppliers whose decision is NOT monitor_only. Deduplicate and sort across all suppliers.

Release supplier IDs: suppliers with monitor_only decision, sorted ascending.

Affected SKUs: unique SKUs from the supplier's filtered incidents, sorted ascending. Sample incident IDs: sorted, max 5.

Enum Quick Reference

Account / Risk

account_status: active, blocked, review_required risk_flag: none, fraud_watch, credit_watch

Quality

quality_status: approved, watch, quality_hold severity: low, medium, high, critical

Incident

incident_type: RMA, WORK_ORDER status: open, closed

Order decisions

inventory_status: ready, low_stock, shortage, inactive_sku, inactive_and_shortage customer_exception: none, review_required, account_blocked, fraud_watch, credit_watch final_decision: ship_now, delayed_release, manual_review, backorder, reject_hold next_action: release_to_pick, delay_and_monitor, send_account_review, create_backorder, hold_credit_or_fraud, escalate_product_master

Allocation

action: ship, transfer, backorder, manual_review primary_reason: none, account_blocked, account_review_required, fraud_watch, inactive_product, insufficient_effective_stock

Replenishment

final_action: no_action_stocked, transfer_only, purchase_required, timely_po_covered, overstock_excluded exclusion_reason: none, target_overstock, timely_po_covers_gap, stocked_no_gap

Procurement

decision: freeze_new_replenishment, buyer_review_required, monitor_only

Recommendation

recommendation_code: ESCALATE_SUPPLIER, PROCESS_REVIEW, WATCHLIST, MONITOR

Ordering Rules (Sort Conventions)

Default: string fields sort ascending lexicographically unless otherwise stated.

Common Pitfalls

1. Overlapping SKU lists: A SKU with effective_available ≤ 0 is shortage, not low_stock. A SKU already in inactive_skus should still be checked for shortage/low_stock classification in the inventory status roll-up.

2. Customer exception vs. primary_reason: Different tasks use different enum sets. customer_exception uses review_required; primary_reason uses account_review_required. Match the answer template exactly.

3. Effective available → 0 floor: Always max(0, on_hand − reserved − quarantined − safety_stock). Negative effective stock means zero availability, not negative.

4. Cancelled POs: Do not count cancelled purchase orders as coverage. Only open and confirmed statuses are eligible.

5. Date inclusivity: When a filter says "Q1" or specifies "inclusive": true, include incidents where open_date falls exactly on the boundary dates. Use start <= open_date <= end.

6. Shipping quotes for ALL orders: Request quotes even for orders that are blocked, backordered, or under manual review. The quote informs the cost summary regardless of fulfillment decision.

7. Weight calculation for shipping: Multiply product.weight_lb × line.quantity for ALL lines in the order, including lines with inactive SKUs (the courier charges by total package weight). Use the product catalog weight, not a zero default for lookups that fail.

8. Supplier-level analysis windows: For scorecards (train_003), filter by open_date. For procurement control (train_005), the window is the review period — filter incidents whose open_date falls in that range.

9. Exclusion reason "none" vs. excluded_components: Only add entries to excluded_components when the exclusion_reason is not "none". Components with exclusion_reason: "none" that still appear in component_plan do not go in excluded_components.

10. Transfer source buffer: When pulling inventory from a source warehouse, respect its own safety stock — transferrable = max(0, source_eff_avail − safety_stock). Don't drain a warehouse below its operating buffer.

11. RMA critical check: For ESCALATE_SUPPLIER, check if ANY incident has incident_type == "RMA" AND severity == "critical" — not just RMAs overall.

12. top_escalation_suppliers: This is a list of supplier_id strings, not objects. Only suppliers with recommendation_code == "ESCALATE_SUPPLIER".

13. PO status for held POs: Include both open and confirmed POs. Exclude received and cancelled.

14. Order rollup edge case: If an order has multiple lines with different actions, outcome is mixed_actions regardless of whether one action dominates.