fix(api): expose trend_analysis at top level

README.md

@@ -318,8 +318,7 @@ Example:
 
 ```python
 import numpy as np
-from eo_processor._core import trend_analysis
-from eo_processor import linear_regression
+from eo_processor import trend_analysis, linear_regression
 
 # Simple linear regression
 y_reg = np.array([1.0, 2.1, 2.9, 4.2])

docs/source/README.md

@@ -318,8 +318,7 @@ Example:
 
 ```python
 import numpy as np
-from eo_processor._core import trend_analysis
-from eo_processor import linear_regression
+from eo_processor import trend_analysis, linear_regression
 
 # Simple linear regression
 y_reg = np.array([1.0, 2.1, 2.9, 4.2])

python/eo_processor/__init__.py

@@ -51,6 +51,8 @@
     replace_nans as _replace_nans,
     savi as _savi,
     linear_regression as _linear_regression,
+    trend_analysis as _trend_analysis,
+    TrendSegment as _TrendSegment,
     temporal_sum as _temporal_sum,
     temporal_composite as _temporal_composite,
     zonal_stats as _zonal_stats,
@@ -355,7 +357,29 @@ def linear_regression(y):
     return _linear_regression(y)
 
 
+def trend_analysis(y, threshold):
+    """
+    Detect breaks in a time series by recursively fitting linear models.
+
+    Parameters
+    ----------
+    y : sequence of float
+        1D time series of finite values.
+    threshold : float
+        Maximum absolute residual tolerated before a segment is split.
+        Must be non-negative.
+
+    Returns
+    -------
+    list of TrendSegment
+        Each segment exposes `start_index`, `end_index`, `slope`, and
+        `intercept` attributes.
+    """
+    return _trend_analysis(y, threshold)
+
+
 ZoneStats = _ZoneStats
+TrendSegment = _TrendSegment
 
 
 def zonal_stats(values: np.ndarray, zones: np.ndarray) -> dict[int, ZoneStats]:

python/eo_processor/__init__.pyi

@@ -84,6 +84,17 @@ def composite(
 def temporal_mean(arr: NumericArray, skip_na: bool = ...) -> NDArray[np.float64]: ...
 def temporal_std(arr: NumericArray, skip_na: bool = ...) -> NDArray[np.float64]: ...
 
+# Trend analysis & regression
+class TrendSegment:
+    start_index: int
+    end_index: int
+    slope: float
+    intercept: float
+
+def trend_analysis(
+    y: Sequence[float], threshold: float
+) -> list[TrendSegment]: ...
+
 # Advanced temporal processes
 def moving_average_temporal(
     arr: NumericArray,

tests/test_trends.py

@@ -1,7 +1,7 @@
 import numpy as np
 import pytest
 
-from eo_processor import linear_regression
+from eo_processor import linear_regression, trend_analysis
 
 
 def test_linear_regression_basic():
@@ -20,3 +20,37 @@ def test_linear_regression_rejects_too_short():
 def test_linear_regression_rejects_non_finite():
     with pytest.raises(ValueError, match="finite"):
         linear_regression(np.array([1.0, np.nan, 2.0], dtype=np.float64))
+
+
+def test_trend_analysis_no_break_single_segment():
+    y = np.linspace(0.0, 10.0, 50)
+    segments = trend_analysis(y.tolist(), threshold=1e9)
+    assert len(segments) == 1
+    assert segments[0].start_index == 0
+    assert segments[0].end_index == 49
+    assert segments[0].slope == pytest.approx(10.0 / 49.0, rel=1e-6)
+
+
+def test_trend_analysis_detects_break():
+    y = np.concatenate([np.linspace(0, 10, 50), np.linspace(10, 0, 50)])
+    segments = trend_analysis(y.tolist(), threshold=1.0)
+    assert len(segments) >= 2
+    for segment in segments:
+        assert segment.end_index >= segment.start_index
+
+
+def test_trend_analysis_rejects_negative_threshold():
+    y = np.linspace(0.0, 10.0, 20)
+    with pytest.raises(ValueError, match="non-negative"):
+        trend_analysis(y.tolist(), threshold=-1.0)
+
+
+def test_trend_analysis_rejects_non_finite():
+    with pytest.raises(ValueError, match="finite"):
+        trend_analysis([1.0, np.nan, 2.0], threshold=0.5)
+
+
+def test_star_import_exposes_trend_analysis():
+    namespace = {}
+    exec("from eo_processor import *", namespace)
+    assert "trend_analysis" in namespace