newsAR 0.3.0__tar.gz

newsar-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Vieira de Souza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

newsar-0.3.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: newsAR
+Version: 0.3.0
+Summary: Autorregressão Bayesiana com Sentimento de Notícias para previsão de commodities
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: requests>=2.28
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == "anthropic"
+Provides-Extra: openailib
+Requires-Dist: openai>=1.0; extra == "openailib"
+Provides-Extra: groq
+Requires-Dist: groq>=0.9; extra == "groq"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: groq>=0.9; extra == "all"
+Requires-Dist: joblib>=1.3; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: anthropic>=0.25; extra == "dev"
+Requires-Dist: openai>=1.0; extra == "dev"
+Requires-Dist: groq>=0.9; extra == "dev"
+Requires-Dist: joblib>=1.3; extra == "dev"
+Dynamic: license-file

newsar-0.3.0/newsAR/__init__.py

@@ -0,0 +1,62 @@
+"""newsAR — Autorregressão Bayesiana com Sentimento de Notícias.
+
+Pipeline integrado: coleta de notícias → pontuação via LLM →
+seleção de lags → modelo AR bayesiano com Gibbs Sampling.
+
+Quick start (API simplificada)::
+
+    from newsAR import quick_fit
+
+    # Com CSV de notícias pré-coletadas
+    forecaster = quick_fit(
+        y=serie_mensal,
+        keyword="petróleo",
+        csv_path="noticias.csv",
+        groq_api_key="gsk_...",
+    )
+    forecast = forecaster.predict(steps=6, credible_interval=0.90)
+
+API completa::
+
+    from newsAR.news.fetcher import CSVNewsFetcher
+    from newsAR.sentiment.llm_scorer import ConstantSentimentScorer
+    from newsAR.forecaster import NewsARForecaster
+
+    fetcher = CSVNewsFetcher("noticias.csv")
+    forecaster = NewsARForecaster("petróleo", fetcher=fetcher)
+    forecaster.fit(y_train)
+    forecast = forecaster.predict(steps=6, credible_interval=0.90)
+
+"""
+
+from .forecaster import NewsARForecaster
+from .quick import quick_fit
+from .lags.selector import LagSelector
+from .model.bayesian_ar import BayesianARModel
+from .news.fetcher import CSVNewsFetcher, NewsAPIFetcher
+from .sentiment.llm_scorer import (
+    AnthropicSentimentScorer,
+    ConstantSentimentScorer,
+    GroqSentimentScorer,
+    OpenAISentimentScorer,
+)
+from . import diagnostics, benchmark
+from .benchmark import theil_u
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "NewsARForecaster",
+    "quick_fit",
+    "LagSelector",
+    "BayesianARModel",
+    "NewsAPIFetcher",
+    "CSVNewsFetcher",
+    "AnthropicSentimentScorer",
+    "OpenAISentimentScorer",
+    "GroqSentimentScorer",
+    "ConstantSentimentScorer",
+    "diagnostics",
+    "benchmark",
+    "theil_u",
+]

newsar-0.3.0/newsAR/benchmark.py

@@ -0,0 +1,352 @@
+"""Benchmarking out-of-sample para o pipeline newsAR.
+
+Compara o desempenho preditivo do ``newsAR`` contra modelos clássicos
+usando validação walk-forward (rolling origin) 1-step-ahead.
+
+Modelos avaliados
+-----------------
+- **newsAR** : AR Bayesiano + sentimento LLM
+- **BayesAR** : AR Bayesiano puro (sem sentimento)
+- **ARIMA**   : ARIMA(p,0,0) com ``p`` selecionado por AIC
+- **OLS-AR**  : AR por OLS clássico
+- **Naive**   : y_{t+1} = y_t (Random Walk)
+- **SeasonalNaive** : y_{t+1} = y_{t-11} (mesmo mês do ano anterior)
+
+Métricas reportadas: RMSE, MAE, MAPE, Theil's U, melhoria_vs_Naive_%.
+"""
+from __future__ import annotations
+
+import warnings
+from typing import Callable
+
+import numpy as np
+import pandas as pd
+
+from .lags.selector import LagSelector
+from .model.bayesian_ar import BayesianARModel
+from .news.base import BaseNewsFetcher
+from .sentiment.base import BaseSentimentScorer
+from .sentiment.llm_scorer import ConstantSentimentScorer
+
+
+def _rmse(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    return float(np.sqrt(np.mean((y_true - y_pred) ** 2)))
+
+
+def _mae(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    return float(np.mean(np.abs(y_true - y_pred)))
+
+
+def _mape(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """MAPE (%), ignorando observações onde y_true == 0."""
+    mask = y_true != 0
+    if not mask.any():
+        return float("nan")
+    return float(100 * np.mean(np.abs((y_true[mask] - y_pred[mask]) / y_true[mask])))
+
+
+def theil_u(y_true: np.ndarray, y_pred: np.ndarray) -> float:
+    """Coeficiente Theil's U — compara o modelo com o Random Walk.
+
+    Fórmula
+    -------
+    ::
+
+                  Σ (y_t - ŷ_t)²
+        Theil U = ─────────────────
+                  Σ (y_t - y_{t-1})²
+
+    Onde ``y_{t-1}`` é a previsão do Random Walk (Naive).
+
+    Interpretação
+    -------------
+    - U < 1  →  modelo melhor que Random Walk  ✓
+    - U = 1  →  igual ao Random Walk
+    - U > 1  →  pior que Random Walk  ✗
+
+    Parameters
+    ----------
+    y_true : np.ndarray
+        Valores reais da série temporal (comprimento n).
+    y_pred : np.ndarray
+        Previsões do modelo avaliado (comprimento n).
+
+    Returns
+    -------
+    float
+        Valor de Theil's U.  ``nan`` se o denominador for zero.
+    """
+    y_true = np.asarray(y_true, dtype=float)
+    y_pred = np.asarray(y_pred, dtype=float)
+    if len(y_true) != len(y_pred):
+        raise ValueError("y_true e y_pred devem ter o mesmo comprimento.")
+    numerator   = np.sum((y_true[1:] - y_pred[1:]) ** 2)
+    denominator = np.sum((y_true[1:] - y_true[:-1]) ** 2)
+    if denominator == 0:
+        return float("nan")
+    return float(numerator / denominator)
+
+
+def _naive_forecast(y_train: np.ndarray) -> float:
+    """Naive: última observação."""
+    return float(y_train[-1])
+
+
+def _seasonal_naive_forecast(y_train: np.ndarray, season: int = 12) -> float:
+    """Seasonal naive: mesmo período do ano/ciclo anterior."""
+    if len(y_train) >= season:
+        return float(y_train[-season])
+    return float(y_train[-1])  # fallback se série curta
+
+
+def _ols_ar_forecast(y_train: np.ndarray, lags: list[int]) -> float:
+    """AR por OLS (mínimos quadrados ordinários) via numpy."""
+    max_lag = max(lags)
+    n = len(y_train)
+    if n <= max_lag:
+        return float(y_train[-1])
+
+    # Construir matriz de design
+    lag_cols = [y_train[max_lag - lag: n - lag] for lag in lags]
+    X = np.column_stack([np.ones(n - max_lag)] + lag_cols)
+    y_t = y_train[max_lag:]
+
+    try:
+        beta, _, _, _ = np.linalg.lstsq(X, y_t, rcond=None)
+    except np.linalg.LinAlgError:
+        return float(y_train[-1])
+
+    x_new = np.array([1.0] + [y_train[-(lag)] for lag in lags])
+    return float(x_new @ beta)
+
+
+def _arima_forecast(y_train: np.ndarray) -> float:
+    """ARIMA(p,0,0) com p escolhido por AIC entre 1..min(12, n//4)."""
+    try:
+        from statsmodels.tsa.arima.model import ARIMA
+    except ImportError:
+        return float(y_train[-1])
+
+    n = len(y_train)
+    max_p = min(12, max(1, n // 4))
+    best_aic = np.inf
+    best_pred = float(y_train[-1])
+
+    for p in range(1, max_p + 1):
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                model = ARIMA(y_train, order=(p, 0, 0)).fit()
+                if model.aic < best_aic:
+                    best_aic = model.aic
+                    best_pred = float(model.forecast(steps=1)[0])
+        except Exception:
+            continue
+
+    return best_pred
+
+
+def _bayes_ar_forecast(
+    y_train: np.ndarray,
+    lags: list[int],
+    n_iter: int,
+    burnin: int,
+    nu_t: float,
+    random_seed: int | None,
+    exog: np.ndarray | None = None,
+    future_exog: float | None = None,
+) -> float:
+    """AR Bayesiano 1-step-ahead via Gibbs."""
+    model = BayesianARModel(
+        lags=lags, n_iter=n_iter, burnin=burnin, nu_t=nu_t, random_seed=random_seed
+    )
+    model.fit(y_train, exog=exog)
+    fc = model.predict(
+        steps=1,
+        future_exog=np.array([future_exog]) if future_exog is not None else None,
+    )
+    return float(fc["mean"].iloc[0])
+
+
+def run_benchmark(
+    y: pd.Series,
+    keyword: str,
+    fetcher: BaseNewsFetcher | None = None,
+    scorer: BaseSentimentScorer | None = None,
+    test_size: int = 12,
+    n_iter: int = 1000,
+    burnin: int = 300,
+    max_lag: int = 12,
+    nu_t: float = 5.0,
+    random_seed: int | None = 42,
+    season: int = 12,
+    verbose: bool = True,
+) -> pd.DataFrame:
+    """Benchmarking out-of-sample walk-forward 1-step-ahead.
+
+    Para cada ponto de teste ``t`` (dos últimos ``test_size`` períodos),
+    treina cada modelo com os dados até ``t-1`` e faz previsão para ``t``.
+    Ao final computa RMSE, MAE e MAPE de cada modelo.
+
+    Parameters
+    ----------
+    y : pd.Series
+        Série temporal com DatetimeIndex mensal.
+    keyword : str
+        Keyword para coleta de notícias (passada ao fetcher).
+    fetcher : BaseNewsFetcher, optional
+        Coletor de notícias. Se ``None``, usa sentimento neutro.
+    scorer : BaseSentimentScorer, optional
+        Pontuador de sentimento. Se ``None``, usa ``ConstantSentimentScorer``.
+    test_size : int
+        Número de períodos de teste (previsões a fazer). Padrão: 12.
+    n_iter : int
+        Iterações Gibbs (reduzido para velocidade no benchmark). Padrão: 1000.
+    burnin : int
+        Burn-in do Gibbs. Padrão: 300.
+    max_lag : int
+        Máximo de lags para seleção automática. Padrão: 12.
+    nu_t : float
+        Graus de liberdade da t-Student. Padrão: 5.0.
+    random_seed : int, optional
+        Semente para reprodutibilidade.
+    season : int
+        Sazonalidade para Seasonal Naive (padrão 12 = anual).
+    verbose : bool
+        Se ``True``, imprime progresso step a step.
+
+    Returns
+    -------
+    pd.DataFrame
+        Colunas: ``modelo``, ``RMSE``, ``MAE``, ``MAPE_%``, ``Theil_U``,
+        ``n_previsoes``, ``melhoria_vs_Naive_%``.
+        Ordenado por RMSE crescente.
+
+    Examples
+    --------
+    >>> from newsAR.benchmark import run_benchmark
+    >>> results = run_benchmark(y=serie, keyword="petróleo", test_size=12)
+    >>> results[["modelo", "RMSE", "Theil_U"]]
+    """
+    if not isinstance(y.index, pd.DatetimeIndex):
+        raise TypeError("y deve ter DatetimeIndex.")
+
+    n_total = len(y)
+    n_train_min = n_total - test_size
+
+    if n_train_min < max_lag + 4:
+        raise ValueError(
+            f"Série muito curta para {test_size} passos de teste. "
+            f"Reduza test_size ou forneça mais dados."
+        )
+
+    if scorer is None:
+        scorer = ConstantSentimentScorer(3.0)
+
+    # Acumular predições de cada modelo
+    models_preds: dict[str, list[float]] = {
+        "newsAR": [],
+        "BayesAR": [],
+        "ARIMA": [],
+        "OLS-AR": [],
+        "Naive": [],
+        "SeasonalNaive": [],
+    }
+    y_actual: list[float] = []
+
+    lag_selector = LagSelector(max_lag=max_lag, use_aic=False)
+
+    for step in range(test_size):
+        train_end = n_train_min + step
+        y_train_series = y.iloc[:train_end]
+        y_train = y_train_series.values
+        y_true_val = float(y.iloc[train_end])
+        y_actual.append(y_true_val)
+
+        if verbose:
+            periodo = y.index[train_end].strftime("%Y-%m")
+            print(f"  [{step + 1:02d}/{test_size}] Prevendo {periodo} …", end=" ")
+
+        # Selecionar lags para este trecho de treino
+        lags = lag_selector.select(y_train)
+
+        # ---- Sentimento para newsAR ----
+        exog_train = None
+        future_sent = 3.0  # neutro como fallback
+        if fetcher is not None:
+            start = y_train_series.index[0].strftime("%Y-%m-%d")
+            end   = y_train_series.index[-1].strftime("%Y-%m-%d")
+            try:
+                news_df = fetcher.fetch(keyword, start, end)
+                if not news_df.empty:
+                    raw_sent = scorer.score_series(news_df)
+                    periods = y_train_series.index.strftime("%Y-%m")
+                    sent_aligned = raw_sent.reindex(periods, fill_value=3.0)
+                    exog_train = sent_aligned.values.astype(float)
+                    future_sent = float(exog_train[-3:].mean())
+            except Exception as exc:
+                warnings.warn(f"Erro ao buscar notícias: {exc}. Usando neutro.", stacklevel=2)
+
+        # ---- newsAR ----
+        try:
+            pred_news = _bayes_ar_forecast(
+                y_train, lags, n_iter, burnin, nu_t, random_seed,
+                exog=exog_train, future_exog=future_sent,
+            )
+        except Exception:
+            pred_news = float(y_train[-1])
+        models_preds["newsAR"].append(pred_news)
+
+        # ---- BayesAR puro ----
+        try:
+            pred_bayes = _bayes_ar_forecast(
+                y_train, lags, n_iter, burnin, nu_t, random_seed,
+                exog=None, future_exog=None,
+            )
+        except Exception:
+            pred_bayes = float(y_train[-1])
+        models_preds["BayesAR"].append(pred_bayes)
+
+        # ---- ARIMA ----
+        pred_arima = _arima_forecast(y_train)
+        models_preds["ARIMA"].append(pred_arima)
+
+        # ---- OLS-AR ----
+        pred_ols = _ols_ar_forecast(y_train, lags)
+        models_preds["OLS-AR"].append(pred_ols)
+
+        # ---- Naive ----
+        models_preds["Naive"].append(_naive_forecast(y_train))
+
+        # ---- Seasonal Naive ----
+        models_preds["SeasonalNaive"].append(
+            _seasonal_naive_forecast(y_train, season=season)
+        )
+
+        if verbose:
+            print(f"real={y_true_val:.4f}  newsAR={pred_news:.4f}  "
+                  f"Naive={models_preds['Naive'][-1]:.4f}")
+
+    y_true_arr = np.array(y_actual)
+    rows = []
+    for name, preds in models_preds.items():
+        y_pred_arr = np.array(preds)
+        rows.append(
+            {
+                "modelo": name,
+                "RMSE": round(_rmse(y_true_arr, y_pred_arr), 4),
+                "MAE": round(_mae(y_true_arr, y_pred_arr), 4),
+                "MAPE_%": round(_mape(y_true_arr, y_pred_arr), 2),
+                "Theil_U": round(theil_u(y_true_arr, y_pred_arr), 4),
+                "n_previsoes": test_size,
+            }
+        )
+
+    result_df = pd.DataFrame(rows).sort_values("RMSE").reset_index(drop=True)
+
+    naive_rmse = float(result_df.loc[result_df["modelo"] == "Naive", "RMSE"].iloc[0])
+    result_df["melhoria_vs_Naive_%"] = result_df["RMSE"].apply(
+        lambda r: round(100 * (naive_rmse - r) / (naive_rmse + 1e-12), 1)
+    )
+
+    return result_df