Spec-Based Matching

Overview

Traditional paper surplus trading relies on personal networks and manual scanning of Excel lists. A trader like Mara in Holland sends daily surplus lists to contacts, who then manually check specs against their client portfolios. This is slow (1-4 weeks), incomplete (most surplus only reaches the trader's existing contacts), and error-prone.

The marketplace replaces this with automated specification-based matching. Each surplus item has structured technical attributes (paper type, GSM, width, quality grade, origin). Each buyer has stored specifications (BuyerSpec) defining what their machines can handle and what they need. The system programmatically compares every surplus item against every buyer specification, scoring compatibility across five dimensions.

Why Specifications, Not Text

Paper is a technical commodity. A buyer of wiki/entities/kraftliner cannot use wiki/entities/testliner -- they are fundamentally different products. A machine with a maximum width of 2500mm physically cannot process a 2800mm roll. A buyer needing 120-200 GSM paper has no use for 300 GSM board. These are hard physical constraints, not preferences.

This means matching is inherently specification-driven:

• Paper type is a binary gate -- kraftliner, testliner, wiki/entities/fluting, etc. are not interchangeable
• GSM (grammage) must fall within the buyer's acceptable range or within narrow tolerance bands
• Width must fit the buyer's machine constraints (hard ceiling) and fall within their preferred range
• Quality grade follows a hierarchy: A (prime), B (near-prime), C (off-grade), each with different discount levels and usability
• Geography affects freight cost and delivery time, making some origins more economical than others

The Five Scoring Dimensions

Each dimension has a weight reflecting its importance to trade viability:

The composite score ranges from 0-100. Matches below 50 are not surfaced. Classifications: exact (>=90), close (70-89), partial (50-69). See wiki/concepts/matching-algorithm for the full scoring functions.

BuyerSpec: The Demand Profile

Each buyer can have multiple BuyerSpecs, one per paper type they purchase. A BuyerSpec captures:

• Paper type (must match exactly)
• GSM range (min/max, e.g., 120-200)
• Width range (min/max, e.g., 1000-2400mm)
• Machine constraints (absolute max width, max diameter)
• Acceptable quality grades (e.g., ['A', 'B'])
• Fiber type preference (virgin/recycled/any)
• Food contact requirement (boolean)
• Maximum price per MT
• Monthly volume estimate
• Priority (1-5, with 1 being highest)

BuyerSpecs are initially derived from Morichal's historical purchase data during the data bootstrap phase, with GSM ranges set as (min_purchased - 10%, max_purchased + 10%) and width ranges with +/-5% tolerance.

Pre-Filtering for Performance

Before scoring, the algorithm applies two pre-filters to avoid wasted computation:

1. Visibility check -- geographic rules must allow the buyer to see the surplus item (see wiki/concepts/geographic-visibility-system)
2. Paper type gate -- paper type must match exactly (eliminates ~80% of specs immediately)

Only surplus-buyer pairs that pass both pre-filters proceed to full 5-dimension scoring.

Auto-Trigger and Downstream Effects

Matching runs automatically whenever:

• New surplus is ingested (Excel pipeline commits new items)
• A buyer's specifications change

When a match scores >=80, it becomes a candidate for exclusivity. All matches feed into newsletter generation and container assembly proposals.

Sources

• raw/articles/PRD -- sections 6.8, 7.1-7.6

Related

• wiki/concepts/matching-algorithm -- detailed scoring functions and composite calculation
• wiki/concepts/48-hour-exclusivity-window -- triggered by high-score matches
• wiki/concepts/geographic-visibility-system -- pre-filter for matching
• wiki/concepts/quality-grades -- grade hierarchy used in scoring
• wiki/concepts/paper-types-overview -- the paper type dimension