Feature/API 004 news risk factors (#68)

* AIP-004 add maritime news sources, RSS parsing, and news configuration #50

Made-with: Cursor

* AIP-004 add risk factors, composite schema, and price suggestion news integration #50

Made-with: Cursor

* AIP-004 add tests and update phase-2 docs for news risk analysis #50

Made-with: Cursor

Author: michal-bakshi

docs/ISSUES-PHASE2.md

@@ -1500,14 +1500,14 @@ suggestion. The LLM synthesizes news headlines into risk factors that may affect
 
 ```java
 public interface NewsProvider {
-  List<NewsItem> getRecentHeadlines(String route, int maxResults);
+  List<MaritimeNewsArticle> getRecentHeadlines(String route, int maxResults);
 }
 ```
 
-**`NewsItem` DTO:**
+**`MaritimeNewsArticle` DTO:**
 
 ```java
-public class NewsItem {
+public class MaritimeNewsArticle {
   private String headline;
   private String source;
   private LocalDate publishedDate;

pom.xml

@@ -101,6 +101,12 @@
             <artifactId>json-schema-validator</artifactId>
             <version>1.0.87</version>
         </dependency>
+        <!-- RSS feed parsing -->
+        <dependency>
+            <groupId>com.rometools</groupId>
+            <artifactId>rome</artifactId>
+            <version>2.1.0</version>
+        </dependency>
     </dependencies>
 
     <build>

src/main/java/com/shipping/freightops/dto/MaritimeNewsArticle.java

@@ -0,0 +1,57 @@
+package com.shipping.freightops.dto;
+
+import java.time.LocalDate;
+
+/**
+ * Represents a maritime news article used for shipping risk analysis and freight pricing decisions.
+ * Contains headline, source, publication date, and summary information relevant to maritime
+ * operations.
+ */
+public class MaritimeNewsArticle {
+  private String headline;
+  private String source;
+  private LocalDate publishedDate;
+  private String summary;
+
+  public MaritimeNewsArticle() {}
+
+  public MaritimeNewsArticle(
+      String headline, String source, LocalDate publishedDate, String summary) {
+    this.headline = headline;
+    this.source = source;
+    this.publishedDate = publishedDate;
+    this.summary = summary;
+  }
+
+  public String getHeadline() {
+    return headline;
+  }
+
+  public void setHeadline(String headline) {
+    this.headline = headline;
+  }
+
+  public String getSource() {
+    return source;
+  }
+
+  public void setSource(String source) {
+    this.source = source;
+  }
+
+  public LocalDate getPublishedDate() {
+    return publishedDate;
+  }
+
+  public void setPublishedDate(LocalDate publishedDate) {
+    this.publishedDate = publishedDate;
+  }
+
+  public String getSummary() {
+    return summary;
+  }
+
+  public void setSummary(String summary) {
+    this.summary = summary;
+  }
+}

src/main/java/com/shipping/freightops/dto/PriceSuggestionResponse.java

@@ -4,6 +4,8 @@
 import com.shipping.freightops.enums.ContainerSize;
 import com.shipping.freightops.enums.PriceSuggestionConfidence;
 import java.math.BigDecimal;
+import java.util.ArrayList;
+import java.util.List;
 
 public class PriceSuggestionResponse {
   private String voyageNumber;
@@ -17,6 +19,7 @@ public class PriceSuggestionResponse {
   private BigDecimal historicalAvgUsd;
   private BigDecimal historicalMinUsd;
   private BigDecimal historicalMaxUsd;
+  private List<RiskFactor> riskFactors;
 
   public String getVoyageNumber() {
     return voyageNumber;
@@ -111,6 +114,14 @@ public void setHistoricalMaxUsd(BigDecimal historicalMaxUsd) {
     this.historicalMaxUsd = historicalMaxUsd;
   }
 
+  public List<RiskFactor> getRiskFactors() {
+    return riskFactors;
+  }
+
+  public void setRiskFactors(List<RiskFactor> riskFactors) {
+    this.riskFactors = riskFactors;
+  }
+
   /** Creates a fallback response for no-data or parse-failure scenarios. */
   public static PriceSuggestionResponse fallback(
       String voyageNumber, String route, ContainerSize containerSize, String reasoning) {
@@ -126,6 +137,7 @@ public static PriceSuggestionResponse fallback(
     response.setHistoricalAvgUsd(null);
     response.setHistoricalMinUsd(null);
     response.setHistoricalMaxUsd(null);
+    response.setRiskFactors(new ArrayList<>());
     return response;
   }
 }

src/main/java/com/shipping/freightops/dto/RiskFactor.java

@@ -0,0 +1,41 @@
+package com.shipping.freightops.dto;
+
+import com.shipping.freightops.enums.RiskImpact;
+
+public class RiskFactor {
+  private String factor;
+  private RiskImpact impact;
+  private String description;
+
+  public RiskFactor() {}
+
+  public RiskFactor(String factor, RiskImpact impact, String description) {
+    this.factor = factor;
+    this.impact = impact;
+    this.description = description;
+  }
+
+  public String getFactor() {
+    return factor;
+  }
+
+  public void setFactor(String factor) {
+    this.factor = factor;
+  }
+
+  public RiskImpact getImpact() {
+    return impact;
+  }
+
+  public void setImpact(RiskImpact impact) {
+    this.impact = impact;
+  }
+
+  public String getDescription() {
+    return description;
+  }
+
+  public void setDescription(String description) {
+    this.description = description;
+  }
+}

src/main/java/com/shipping/freightops/dto/VoyageResponse.java

@@ -86,7 +86,7 @@ public LocalDateTime getArrivalDate() {
     return arrivalTime;
   }
 
-  public void setArrivalDate(LocalDateTime departureTime) {
+  public void setArrivalDate(LocalDateTime arrivalTime) {
     this.arrivalTime = arrivalTime;
   }
 

src/main/java/com/shipping/freightops/enums/RiskImpact.java

@@ -0,0 +1,8 @@
+package com.shipping.freightops.enums;
+
+/** Represents the potential impact level of a risk factor on shipping pricing. */
+public enum RiskImpact {
+  HIGH,
+  MEDIUM,
+  LOW
+}

src/main/java/com/shipping/freightops/news/MaritimeNewsSource.java

@@ -0,0 +1,9 @@
+package com.shipping.freightops.news;
+
+import com.shipping.freightops.dto.MaritimeNewsArticle;
+import java.util.List;
+
+public interface MaritimeNewsSource {
+
+  List<MaritimeNewsArticle> getRecentHeadlines(String route, int maxResults);
+}

src/main/java/com/shipping/freightops/news/ShippingNewsAnalyzer.java

@@ -0,0 +1,80 @@
+package com.shipping.freightops.news;
+
+import com.shipping.freightops.dto.MaritimeNewsArticle;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Set;
+import java.util.stream.Collectors;
+import org.springframework.stereotype.Service;
+
+@Service
+public class ShippingNewsAnalyzer {
+
+  private static final String ROUTE_SPLIT_REGEX = "[→\\-\\s]+";
+
+  private static final Set<String> SHIPPING_KEYWORDS =
+      Set.of(
+          "port",
+          "shipping",
+          "container",
+          "vessel",
+          "freight",
+          "cargo",
+          "maritime",
+          "ocean",
+          "terminal",
+          "logistics",
+          "trade",
+          "export",
+          "import",
+          "suez",
+          "panama",
+          "canal",
+          "strait",
+          "route",
+          "disruption");
+
+  private final MaritimeNewsSource maritimeNewsSource;
+
+  public ShippingNewsAnalyzer(MaritimeNewsSource maritimeNewsSource) {
+    this.maritimeNewsSource = maritimeNewsSource;
+  }
+
+  public List<MaritimeNewsArticle> getRelevantHeadlines(String route, int maxResults) {
+    List<MaritimeNewsArticle> allHeadlines =
+        maritimeNewsSource.getRecentHeadlines(route, maxResults * 2);
+
+    if (allHeadlines.isEmpty()) {
+      return List.of();
+    }
+
+    Set<String> routeKeywords = extractRouteKeywords(route);
+
+    return allHeadlines.stream()
+        .filter(item -> isRelevantToRoute(item, routeKeywords))
+        .limit(maxResults)
+        .collect(Collectors.toList());
+  }
+
+  private Set<String> extractRouteKeywords(String route) {
+    return Arrays.stream(route.split(ROUTE_SPLIT_REGEX))
+        .map(String::trim)
+        .map(String::toLowerCase)
+        .filter(keyword -> !keyword.isEmpty())
+        .collect(Collectors.toSet());
+  }
+
+  private boolean isRelevantToRoute(MaritimeNewsArticle item, Set<String> routeKeywords) {
+    String content = (item.getHeadline() + " " + item.getSummary()).toLowerCase();
+
+    boolean matchesRouteKeywords =
+        routeKeywords.stream().anyMatch(keyword -> content.contains(keyword));
+    boolean matchesShippingKeywords = containsShippingKeywords(content);
+
+    return matchesRouteKeywords || matchesShippingKeywords;
+  }
+
+  private boolean containsShippingKeywords(String content) {
+    return SHIPPING_KEYWORDS.stream().anyMatch(content::contains);
+  }
+}

src/main/java/com/shipping/freightops/news/config/NewsConfig.java

@@ -0,0 +1,23 @@
+package com.shipping.freightops.news.config;
+
+import java.net.http.HttpClient;
+import java.time.Duration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.client.JdkClientHttpRequestFactory;
+import org.springframework.web.client.RestClient;
+
+@Configuration
+public class NewsConfig {
+
+  @Bean
+  public RestClient.Builder newsRestClientBuilder(NewsProperties properties) {
+    var requestFactory =
+        new JdkClientHttpRequestFactory(
+            HttpClient.newBuilder()
+                .connectTimeout(Duration.ofSeconds(properties.getConnectTimeout()))
+                .build());
+
+    return RestClient.builder().requestFactory(requestFactory);
+  }
+}