AIP-003 — Market Data Integration for Enriched Suggestions 🟠

[hajk1]

Enrich the price suggestion by pulling in external market rate data so the LLM can compare internal
pricing against the broader market.

What to create:

Interface: MarketDataProvider

public interface MarketDataProvider {
  Optional<MarketRate> getCurrentRate(String originPort, String destPort, ContainerSize size);
}

MarketRate DTO:

public class MarketRate {
  private BigDecimal spotRateUsd;
  private String source;          // e.g. "Freightos Baltic Index"
  private LocalDate asOfDate;
  private String route;           // e.g. "China → North Europe"
}

Implementations:

• FreightosMarketDataProvider — calls Freightos FBX API (free tier available)
• StaticMarketDataProvider — returns hardcoded sample rates for demo/testing

Configuration:

app.market-data.provider=static   # or "freightos"
app.market-data.api-key=${MARKET_DATA_API_KEY}

Update PriceSuggestionService (from AIP-002):

• Before calling the LLM, fetch current market rate
• Include it in the prompt: "The current market spot rate for this route is $X/TEU as of [date]"
• Update the response DTO:

{
  "suggestedPriceLowUsd": 1200.00,
  "suggestedPriceHighUsd": 1450.00,
  "confidence": "HIGH",
  "reasoning": "Historical average is $1,180/TEU across 12 voyages. Current market spot rate is $1,380/TEU (Freightos Baltic Index, 2025-03-28), indicating upward pressure. Suggested range positions you competitively below spot while maintaining margin.",
  "marketRate": {
    "spotRateUsd": 1380.00,
    "source": "Freightos Baltic Index",
    "asOfDate": "2025-03-28"
  },
  "dataPoints": 12,
  "historicalAvgUsd": 1180.00
}

Acceptance criteria:

• Market data provider abstraction defined
• At least StaticMarketDataProvider implemented
• Market rate included in LLM prompt and response
• Suggestion works gracefully when market data is unavailable
• Test with static provider verifies enriched suggestion
• Code is formatted

---

[ArturSlimak]

HI @hajk1 let me do this one as soon as #48 is done :)

[hajk1]

Hi @ArturSlimak , ticket #48 is done.