procurement_strategy
Determine whether to lock annual contract rates, use spot market, or split for ocean freight lanes by comparing costs, break-even rates, and risk-adjusted outcomes across market regimes.
Instructions
Decide the OCEAN SOURCING STRATEGY for a lane over a YEAR — lock an annual/quarterly CONTRACT rate, stay on SPOT, or SPLIT — and in what proportion. This is the procurement/CFO decision the other tools don't touch: not 'book this box now' but 'how do I source my whole volume?'. It costs THREE strategies over your expected annual volume: 100% SPOT, 100% CONTRACT, and the OPTIMAL MIX. The spot side is a real DISTRIBUTION, not a mean: it builds a 52-week expected-spot path from our own forecast (Holt-Winters), the corridor's spot volatility and the seasonal calendar, so a peak-season spike shows up as a fat P95 TAIL. It reads the MARKET REGIME (soft / balanced / tight / extreme) — because the contract↔spot relationship FLIPS with the cycle: in a soft market a contract sits ABOVE cheap spot (you'd overpay), in a tight market spot spikes above contract (the contract PROTECTS you). It computes the BREAK-EVEN contract rate (where 100% contract beats expected 100% spot), optimizes the contract/spot MIX on a mean-variance objective for your risk tolerance (contract the steady base, leave the peak on spot), models MQC shortfall penalties (the cost of over-committing in a light year) and the loading-PRIORITY a contract buys (less peak rollover), and quantifies the VALUE OF PROTECTION in dollars. Honest by design (regla 7): the contract↔spot relationship is regime-dependent and uncertain, so contract rates are MODELED BANDS anchored to the lane's mid-cycle — NOT a filed carrier tariff. Pass your own offered contract rate to score it against break-even. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origin_port | Yes | Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate. | |
| dest_port | Yes | Destination port (city name, UN/LOCODE, or 'City, Country'). | |
| container_type | No | Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'. | |
| annual_volume | Yes | Expected ANNUAL volume in containers of this type (TEU-equivalent ok) — REQUIRED. It is the basis of the contract-vs-spot trade-off. | |
| risk_tolerance | No | 'low' (pay to avoid the tail → favors contract), 'medium' (default), or 'high' (chase the mean → favors spot). Sets the mean-variance λ. | |
| contract_rate_offered | No | An actual contract rate you've been offered (USD/container). If given, it is scored against break-even instead of using the modeled band. Optional. | |
| volume_cv | No | Relative std-dev of YOUR annual volume (e.g. 0.2 = ±20%), driving MQC shortfall risk. Optional; default 0.20. | |
| ship_date | No | Ship-date / contract-start anchor (ISO 'YYYY-MM-DD') for the seasonal & forecast overlay. Optional; defaults to today. | |
| weeks | No | Weeks of lane history to analyze for the forecast & mid-cycle reference (4–52, default 16). Optional. |