Feature/API 004 news risk factors

[michal-bakshi]

AIP-004 — Risk factor analysis from news and events

Description

This pull request implements AIP-004: wiring maritime news into the price-suggestion flow so the model can surface structured risk factors alongside historical pricing data.

---

What changed

News layer

• Introduced MaritimeNewsSource with three implementations:
  • static — sample headlines for testing and development
  • rss — real RSS ingestion using Rome + RestClient
  • noop — returns empty results for safe testing
• Added ShippingNewsAnalyzer to:
  • Filter headlines by route relevance
  • Apply shipping/domain keyword matching
• Added NewsProperties and NewsConfig:
  • Configure provider type
  • RSS feed URLs
  • Max headlines limit
  • HTTP timeouts

---

Risk model

• Added RiskFactor DTO
• Added RiskImpact enum
• Introduced risk-factor.json schema
• Schema enums are injected dynamically at build time via RiskFactorSchemaBuilder

---

Schema composition

• Added CompositeSchemaBuilder
• Merges:
  • price suggestion schema
  • risk factor schema ($defs)
• Ensures LLM schema resolution works without external $ref dependencies at runtime

---

Services

• RiskAnalysisService

  • Fetches relevant maritime news
  • Builds structured prompt context
  • Parses riskFactors from LLM JSON response

• PriceSuggestionService

  • Injects news context into prompt
  • Maps parsed risk factors into response model

---

Prompts & configuration

• Updated system prompt:
  • Requests risk factors when news context is available
• Updated application.properties:
  • Documented all app.news.* settings
• Tests configured with:
  • app.news.provider=noop for deterministic behavior

---

Documentation

• Updated ISSUES-PHASE2.md
  • Replaced examples to use MaritimeNewsArticle

---

Fixes

• Fixed VoyageResponse#setArrivalDate parameter mismatch (renamed to match expected behavior)

---

Tests

• Unit tests for:

  • News providers (static / rss / noop)
  • ShippingNewsAnalyzer filtering logic
  • RSS parsing edge cases
  • Schema builders and composition logic
  • RiskAnalysisService parsing and prompt building
  • PriceSuggestionService end-to-end flow with mocked dependencies

• Test strategy:

  • Use test doubles for external dependencies
  • RSS and LLM integrations mocked for stability
  • Edge cases covered (empty, malformed, failure scenarios)

---

Close #50