Add libsql dependency

server.py

@@ -4,9 +4,11 @@ Backend FinanceAI (SQLite/Turso + Groq)
 - Endpoints de gráficos (temporal e por categoria)
 - Módulo de Cartão de Crédito: cartões, compras, fatura (YYYY-MM) e pagamento
 - Relatórios: exportação por competência (normal + cartão)
-- IMPORTANTE (evitar dupla contagem):
+- Módulo de Projeção (ML leve): treino e previsão por competência (cash + cartão)
+
+IMPORTANTE (evitar dupla contagem):
   * Compras no cartão contam como DESPESA na competência da fatura (invoice_ym).
-  * Pagamento da fatura é movimento de CAIXA (saída da conta), mas NÃO é despesa “real” (é quitação de passivo).
+  * Pagamento da fatura é movimento de CAIXA (saída da conta), mas NÃO é despesa “real” (quitação de passivo).
     => por padrão, os endpoints de despesas EXCLUEM a categoria de pagamento de fatura.
 
 Como rodar:
@@ -29,6 +31,7 @@ Como rodar:
 
    # CORS
    CORS_ORIGINS="http://127.0.0.1:5500,http://localhost:5500"
+
 5) uvicorn server:app --reload --port 8000
 """
 
@@ -41,8 +44,9 @@ import os
 import sqlite3
 import urllib.error
 import urllib.request
-from contextlib import contextmanager
+from contextlib import contextmanager, asynccontextmanager
 from datetime import datetime
+from math import sin, cos, pi
 from typing import Any, Dict, Literal, Optional
 
 from dotenv import load_dotenv
@@ -50,7 +54,6 @@ from fastapi import FastAPI, HTTPException
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import StreamingResponse
 from pydantic import BaseModel, Field
-from contextlib import asynccontextmanager
 
 # ============================================================
 # Env
@@ -219,10 +222,7 @@ def q_scalar(conn: Any, sql: str, params: tuple = (), default: float = 0.0) -> f
 
 
 def _maybe_sync(conn: Any) -> None:
-    """
-    Se for libSQL, tenta sincronizar sem quebrar o fluxo.
-    Observação: em ambiente local puro (sqlite), não faz nada.
-    """
+    """Se for libSQL, tenta sincronizar sem quebrar o fluxo."""
     if not USE_TURSO:
         return
     try:
@@ -263,7 +263,6 @@ def get_conn():
         conn = sqlite3.connect(DB_PATH, check_same_thread=False)
         conn.row_factory = sqlite3.Row
 
-    # Garantir FKs no SQLite/libSQL
     try:
         conn.execute("PRAGMA foreign_keys = ON;")
     except Exception:
@@ -356,6 +355,15 @@ def init_db() -> None:
         conn.execute("CREATE INDEX IF NOT EXISTS idx_card_purchases_invoice ON card_purchases(card_id, invoice_ym);")
         conn.execute("CREATE INDEX IF NOT EXISTS idx_card_purchases_date ON card_purchases(purchase_date);")
 
+        # ---- ML models (forecast) ----
+        conn.execute("""
+        CREATE TABLE IF NOT EXISTS ml_models (
+          name TEXT PRIMARY KEY,
+          trained_at TEXT NOT NULL,
+          payload_json TEXT NOT NULL
+        );
+        """)
+
         conn.commit()
         _maybe_sync(conn)
 
@@ -371,7 +379,6 @@ def seed_defaults() -> None:
                 ("Carteira", "Pessoal", "carteira", now_iso()),
             )
 
-        # Categorias base (inclui bucket do cartão e categoria de pagamento)
         if cat_count == 0:
             base = [
                 "Alimentação",
@@ -393,13 +400,12 @@ def seed_defaults() -> None:
 
 
 # ============================================================
-# Lifespan (substitui on_event: startup/shutdown)
+# Lifespan
 # ============================================================
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     init_db()
     seed_defaults()
-    # Sincroniza 1x na subida (se for Turso/libSQL)
     if USE_TURSO:
         try:
             with db() as conn:
@@ -407,10 +413,9 @@ async def lifespan(app: FastAPI):
         except Exception:
             pass
     yield
-    # shutdown: nada a fazer (conexões são por-request)
 
 
-app = FastAPI(title="FinanceAI API", version="1.5.0", lifespan=lifespan)
+app = FastAPI(title="FinanceAI API", version="1.6.0", lifespan=lifespan)
 
 app.add_middleware(
     CORSMiddleware,
@@ -546,6 +551,28 @@ class MonthlyReportOut(BaseModel):
     card_purchases: list[Dict[str, Any]]
 
 
+# -------- Forecast (ML leve) --------
+class ForecastTrainOut(BaseModel):
+    ok: bool
+    basis: str
+    trained_at: str
+    n_months: int
+    start_ym: str
+    end_ym: str
+    metrics: Dict[str, Any]
+
+
+class ForecastOut(BaseModel):
+    ok: bool
+    basis: str
+    horizon: int
+    trained_at: Optional[str]
+    history: list[Dict[str, Any]]
+    predictions: list[Dict[str, Any]]
+    metrics: Dict[str, Any]
+    note: str
+
+
 # ============================================================
 # Healthcheck
 # ============================================================
@@ -611,7 +638,6 @@ def list_categories():
 
 @app.post("/categories", response_model=CategoryOut)
 def create_category(payload: CategoryIn):
-    # Protege nomes reservados (opcional; evita bagunça semântica)
     if payload.name.strip() == "":
         raise HTTPException(status_code=422, detail="Nome de categoria inválido.")
 
@@ -641,7 +667,6 @@ def delete_category(category_id: int):
         if not row:
             raise HTTPException(status_code=404, detail="Categoria não encontrada.")
 
-        # Evita deletar a categoria “contábil” do pagamento do cartão
         if row["name"] == CATEGORY_CARD_PAYMENT:
             raise HTTPException(status_code=409, detail="Categoria reservada. Não pode ser removida.")
 
@@ -659,10 +684,6 @@ def delete_category(category_id: int):
 # ============================================================
 @app.get("/transactions", response_model=list[TransactionOut])
 def list_transactions(year: Optional[int] = None, month: Optional[int] = None, limit: int = 200):
-    """
-    Retorna transações (caixa).
-    Observação: pagamentos de fatura são transações de caixa e ficam aqui.
-    """
     if limit < 1 or limit > 2000:
         raise HTTPException(status_code=422, detail="limit deve estar entre 1 e 2000.")
 
@@ -682,13 +703,6 @@ def list_transactions(year: Optional[int] = None, month: Optional[int] = None, l
 
 @app.get("/transactions/combined")
 def list_transactions_combined(year: int, month: int, limit: int = 2000, order: Literal["asc", "desc"] = "desc"):
-    """
-    Extrato “combinado” (competência):
-    - cash: transactions do mês (YYYY-MM)
-    - card: compras cujo invoice_ym = YYYY-MM
-
-    Retorno unificado com campo 'source' ('cash'|'card').
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
     if limit < 1 or limit > 5000:
@@ -740,8 +754,6 @@ def list_transactions_combined(year: int, month: int, limit: int = 2000, order:
         )
 
         rows = cash + card
-
-        # Ordenação previsível (front costuma querer desc)
         rows.sort(key=lambda r: (r.get("date") or "", int(r.get("id") or 0)), reverse=(order == "desc"))
         return rows[:limit]
 
@@ -795,11 +807,6 @@ def delete_transaction(tx_id: int):
 # ============================================================
 @app.get("/summary", response_model=SummaryOut)
 def get_summary(year: int, month: int, exclude_card_payments: bool = True):
-    """
-    Sumário de CAIXA (transactions).
-    Por padrão, exclui pagamentos de fatura da categoria CATEGORY_CARD_PAYMENT,
-    porque isso não é “despesa real”, é quitação de passivo.
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
 
@@ -849,13 +856,6 @@ def get_summary(year: int, month: int, exclude_card_payments: bool = True):
 
 @app.get("/summary/combined", response_model=CombinedSummaryOut)
 def get_summary_combined(year: int, month: int):
-    """
-    Sumário por competência (cartão por invoice_ym):
-    - income: receitas em transactions
-    - expense_cash: despesas em transactions (EXCLUINDO pagamento de fatura)
-    - expense_card: soma das compras em card_purchases com invoice_ym=YYYY-MM
-    - expense_total = expense_cash + expense_card
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
     ym = f"{year:04d}-{month:02d}"
@@ -909,10 +909,6 @@ def get_summary_combined(year: int, month: int):
 # ============================================================
 @app.get("/charts/timeseries")
 def chart_timeseries(year: int, month: int, exclude_card_payments: bool = True):
-    """
-    Agregação diária do mês: income/expense por dia (transactions).
-    Por padrão, exclui pagamentos de fatura da categoria CATEGORY_CARD_PAYMENT.
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
 
@@ -953,10 +949,6 @@ def chart_timeseries(year: int, month: int, exclude_card_payments: bool = True):
 
 @app.get("/charts/categories")
 def chart_categories(year: int, month: int, tx_type: TxType = "expense", exclude_card_payments: bool = True):
-    """
-    Total por categoria no mês (transactions).
-    Se tx_type='expense', por padrão exclui pagamentos de fatura (CATEGORY_CARD_PAYMENT).
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
     if tx_type not in ("income", "expense"):
@@ -1042,7 +1034,6 @@ def delete_card(card_id: int):
 
 @app.get("/cards/{card_id}/invoices")
 def list_card_invoices(card_id: int):
-    """Lista competências (invoice_ym) existentes para um cartão."""
     with db() as conn:
         card = q_one(conn, "SELECT id FROM credit_cards WHERE id=?", (card_id,))
         if not card:
@@ -1134,7 +1125,6 @@ def create_card_purchase(payload: CardPurchaseIn):
 
 @app.patch("/cards/purchases/{purchase_id}", response_model=dict)
 def patch_card_purchase(purchase_id: int, payload: CardPurchasePatch):
-    """Atualiza status de uma compra (pending/paid)."""
     if payload.status not in ("pending", "paid"):
         raise HTTPException(status_code=422, detail="status inválido.")
 
@@ -1206,12 +1196,6 @@ def invoice_summary(card_id: int, invoice_ym: str):
 
 @app.post("/cards/pay-invoice")
 def pay_invoice(payload: PayInvoiceIn):
-    """
-    Paga uma fatura:
-    1) marca compras pendentes como pagas
-    2) cria transação de CAIXA para baixar o saldo da conta
-       - categoria: CATEGORY_CARD_PAYMENT (por padrão, NÃO entra como “despesa real” nos somatórios)
-    """
     parse_ym(payload.invoice_ym)
     parse_date_yyyy_mm_dd(payload.pay_date)
 
@@ -1238,7 +1222,6 @@ def pay_invoice(payload: PayInvoiceIn):
         if total <= 0:
             return {"ok": True, "message": "Nada pendente para pagar nesta fatura.", "paid_total": 0.0}
 
-        # 1) Marca compras como pagas
         conn.execute(
             """
             UPDATE card_purchases
@@ -1248,7 +1231,6 @@ def pay_invoice(payload: PayInvoiceIn):
             (now_iso(), payload.card_id, payload.invoice_ym),
         )
 
-        # 2) Transação de caixa (quitação)
         desc = f"Pagamento fatura {card['name']} ({payload.invoice_ym})"
         conn.execute(
             """
@@ -1268,7 +1250,6 @@ def pay_invoice(payload: PayInvoiceIn):
 # ============================================================
 @app.get("/charts/card/categories")
 def chart_card_categories(card_id: int, invoice_ym: str):
-    """Total por categoria na fatura (invoice_ym) de um cartão."""
     parse_ym(invoice_ym)
 
     with db() as conn:
@@ -1291,11 +1272,6 @@ def chart_card_categories(card_id: int, invoice_ym: str):
 
 @app.get("/charts/combined/categories")
 def chart_combined_categories(year: int, month: int):
-    """
-    Categorias de DESPESA por competência, combinando:
-    - transactions (expense) no mês, EXCLUINDO pagamento de fatura
-    - card_purchases com invoice_ym no mês
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
     ym = f"{year:04d}-{month:02d}"
@@ -1329,11 +1305,6 @@ def chart_combined_categories(year: int, month: int):
 
 @app.get("/charts/combined/timeseries")
 def chart_combined_timeseries(year: int, month: int):
-    """
-    Série temporal diária por competência, combinando:
-    - transactions (despesas) no mês, EXCLUINDO pagamento de fatura
-    - card_purchases (invoice_ym do mês) agrupadas por purchase_date
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
     ym = f"{year:04d}-{month:02d}"
@@ -1415,14 +1386,6 @@ def report_monthly(year: int, month: int):
 
 @app.get("/reports/export")
 def report_export(year: int, month: int, fmt: ExportFormat = "csv"):
-    """
-    Exporta por competência (ym):
-    - transactions do mês (caixa)
-    - card_purchases com invoice_ym do mês (cartão)
-
-    fmt=json => retorna JSON
-    fmt=csv  => retorna CSV (download)
-    """
     if month < 1 or month > 12:
         raise HTTPException(status_code=422, detail="month deve estar entre 1 e 12.")
     ym = f"{year:04d}-{month:02d}"
@@ -1520,7 +1483,7 @@ def ask_ai(payload: AIRequest):
         headers={
             "Content-Type": "application/json",
             "Authorization": f"Bearer {GROQ_API_KEY}",
-            "User-Agent": "FinanceAI/1.5.0",
+            "User-Agent": "FinanceAI/1.6.0",
         },
     )
 
@@ -1546,3 +1509,386 @@ def ask_ai(payload: AIRequest):
         answer = "Não consegui extrair a resposta do Groq. Verifique o payload retornado no servidor."
 
     return {"answer_md": answer}
+
+
+# ============================================================
+# FORECAST (ML leve) — Ridge simples + lags (competência)
+# ============================================================
+try:
+    import numpy as np
+except Exception:
+    np = None
+
+
+def ym_from_year_month(year: int, month: int) -> str:
+    return f"{year:04d}-{month:02d}"
+
+
+def ym_to_year_month(ym: str) -> tuple[int, int]:
+    parse_ym(ym)
+    y, m = ym.split("-")
+    return int(y), int(m)
+
+
+def month_seq(start_ym: str, end_ym: str) -> list[str]:
+    sy, sm = ym_to_year_month(start_ym)
+    ey, em = ym_to_year_month(end_ym)
+    out = []
+    y, m = sy, sm
+    while (y < ey) or (y == ey and m <= em):
+        out.append(ym_from_year_month(y, m))
+        y, m = add_months(y, m, 1)
+    return out
+
+
+def get_min_max_ym(conn: Any) -> Optional[tuple[str, str]]:
+    r1 = q_one(conn, "SELECT MIN(substr(date,1,7)) AS mn, MAX(substr(date,1,7)) AS mx FROM transactions")
+    r2 = q_one(conn, "SELECT MIN(invoice_ym) AS mn, MAX(invoice_ym) AS mx FROM card_purchases")
+
+    mins = [x for x in [(r1 or {}).get("mn"), (r2 or {}).get("mn")] if x]
+    maxs = [x for x in [(r1 or {}).get("mx"), (r2 or {}).get("mx")] if x]
+    if not mins or not maxs:
+        return None
+
+    return min(mins), max(maxs)
+
+
+def build_monthly_series_competencia(conn: Any) -> list[dict]:
+    mm = get_min_max_ym(conn)
+    if not mm:
+        return []
+
+    start_ym, end_ym = mm
+    yms = month_seq(start_ym, end_ym)
+
+    series = []
+    for ym in yms:
+        income = q_scalar(
+            conn,
+            """
+            SELECT SUM(amount) AS s
+            FROM transactions
+            WHERE substr(date,1,7)=? AND type='income'
+            """,
+            (ym,),
+            default=0.0,
+        )
+
+        expense_cash_real = q_scalar(
+            conn,
+            """
+            SELECT SUM(amount) AS s
+            FROM transactions
+            WHERE substr(date,1,7)=?
+              AND type='expense'
+              AND category<>?
+            """,
+            (ym, CATEGORY_CARD_PAYMENT),
+            default=0.0,
+        )
+
+        expense_card = q_scalar(
+            conn,
+            """
+            SELECT SUM(amount) AS s
+            FROM card_purchases
+            WHERE invoice_ym=?
+            """,
+            (ym,),
+            default=0.0,
+        )
+
+        expense_total = float(expense_cash_real) + float(expense_card)
+        balance = float(income) - expense_total
+
+        series.append({
+            "ym": ym,
+            "income": float(income),
+            "expense_cash_real": float(expense_cash_real),
+            "expense_card": float(expense_card),
+            "expense_total": float(expense_total),
+            "balance": float(balance),
+        })
+
+    return series
+
+
+def ridge_fit(X: "np.ndarray", y: "np.ndarray", alpha: float = 1.0) -> tuple["np.ndarray", float]:
+    x_mean = X.mean(axis=0)
+    y_mean = y.mean()
+
+    Xc = X - x_mean
+    yc = y - y_mean
+
+    n_features = Xc.shape[1]
+    A = Xc.T @ Xc + alpha * np.eye(n_features)
+    b = Xc.T @ yc
+    coef = np.linalg.solve(A, b)
+
+    intercept = y_mean - float(x_mean @ coef)
+    return coef, float(intercept)
+
+
+def ridge_predict(X: "np.ndarray", coef: "np.ndarray", intercept: float) -> "np.ndarray":
+    return X @ coef + intercept
+
+
+def make_time_feats(ym: str, t_idx: int) -> list[float]:
+    _, m = ym_to_year_month(ym)
+    ang = 2.0 * pi * (float(m) / 12.0)
+    return [float(t_idx), float(m), sin(ang), cos(ang)]
+
+
+def make_supervised(series_vals: list[float], yms: list[str], lags: int = 6) -> tuple[list[list[float]], list[float], list[str]]:
+    X, y, out_yms = [], [], []
+    for i in range(lags, len(series_vals)):
+        lag_feats = [series_vals[i - k] for k in range(1, lags + 1)]
+        ma3 = sum(series_vals[i-3:i]) / 3.0 if i >= 3 else series_vals[i-1]
+        ma6 = sum(series_vals[i-6:i]) / 6.0 if i >= 6 else ma3
+
+        feats = make_time_feats(yms[i], i) + lag_feats + [ma3, ma6]
+        X.append([float(v) for v in feats])
+        y.append(float(series_vals[i]))
+        out_yms.append(yms[i])
+    return X, y, out_yms
+
+
+def walk_forward_metrics(y_true: list[float], y_pred: list[float]) -> dict:
+    if not y_true:
+        return {"mae": None, "mape": None}
+    abs_err = [abs(a - b) for a, b in zip(y_true, y_pred)]
+    mae = sum(abs_err) / len(abs_err)
+
+    mape_vals = []
+    for yt, yp in zip(y_true, y_pred):
+        if abs(yt) < 1e-9:
+            continue
+        mape_vals.append(abs(yt - yp) / abs(yt))
+    mape = (sum(mape_vals) / len(mape_vals)) if mape_vals else None
+    return {"mae": float(mae), "mape": (float(mape) if mape is not None else None)}
+
+
+def train_models_competencia(conn: Any, alpha: float = 3.0, lags: int = 6) -> dict:
+    series = build_monthly_series_competencia(conn)
+    if len(series) < (lags + 6):
+        raise HTTPException(status_code=422, detail="Histórico insuficiente para treinar. Recomendo >= 12 meses.")
+
+    if np is None:
+        raise HTTPException(status_code=500, detail="numpy não instalado. Adicione numpy ao requirements.txt.")
+
+    yms = [r["ym"] for r in series]
+    income_vals = [float(r["income"]) for r in series]
+    expense_vals = [float(r["expense_total"]) for r in series]
+
+    Xi, yi, _ = make_supervised(income_vals, yms, lags=lags)
+    Xe, ye, _ = make_supervised(expense_vals, yms, lags=lags)
+
+    Xi_np = np.array(Xi, dtype=float)
+    yi_np = np.array(yi, dtype=float)
+    Xe_np = np.array(Xe, dtype=float)
+    ye_np = np.array(ye, dtype=float)
+
+    def split_train_val(X, y, n_val=3):
+        n = len(y)
+        n_val = min(max(1, n_val), max(1, n - 1))
+        return (X[:-n_val], y[:-n_val], X[-n_val:], y[-n_val:])
+
+    Xi_tr, yi_tr, Xi_va, yi_va = split_train_val(Xi_np, yi_np, n_val=3)
+    Xe_tr, ye_tr, Xe_va, ye_va = split_train_val(Xe_np, ye_np, n_val=3)
+
+    coef_i, b_i = ridge_fit(Xi_tr, yi_tr, alpha=alpha)
+    coef_e, b_e = ridge_fit(Xe_tr, ye_tr, alpha=alpha)
+
+    pred_i = ridge_predict(Xi_va, coef_i, b_i).tolist()
+    pred_e = ridge_predict(Xe_va, coef_e, b_e).tolist()
+
+    m_i = walk_forward_metrics(yi_va.tolist(), pred_i)
+    m_e = walk_forward_metrics(ye_va.tolist(), pred_e)
+
+    res_i = (ridge_predict(Xi_tr, coef_i, b_i) - yi_tr)
+    res_e = (ridge_predict(Xe_tr, coef_e, b_e) - ye_tr)
+    std_i = float(np.std(res_i)) if len(res_i) > 1 else 0.0
+    std_e = float(np.std(res_e)) if len(res_e) > 1 else 0.0
+
+    payload = {
+        "basis": "competencia",
+        "alpha": float(alpha),
+        "lags": int(lags),
+        "trained_at": now_iso(),
+        "start_ym": yms[0],
+        "end_ym": yms[-1],
+        "history": series,
+        "models": {
+            "income": {"coef": coef_i.tolist(), "intercept": float(b_i), "std": std_i, "metrics": m_i},
+            "expense_total": {"coef": coef_e.tolist(), "intercept": float(b_e), "std": std_e, "metrics": m_e},
+        },
+        "feature_spec": {
+            "time_feats": ["t_idx", "month_num", "sin12", "cos12"],
+            "lags": [f"lag_{k}" for k in range(1, lags + 1)],
+            "ma": ["ma3", "ma6"],
+        }
+    }
+    return payload
+
+
+def save_model(conn: Any, name: str, payload: dict) -> None:
+    conn.execute(
+        """
+        INSERT INTO ml_models(name, trained_at, payload_json)
+        VALUES (?,?,?)
+        ON CONFLICT(name) DO UPDATE SET
+          trained_at=excluded.trained_at,
+          payload_json=excluded.payload_json
+        """,
+        (name, payload.get("trained_at", now_iso()), json.dumps(payload, ensure_ascii=False)),
+    )
+    conn.commit()
+    _maybe_sync(conn)
+
+
+def load_model(conn: Any, name: str) -> Optional[dict]:
+    row = q_one(conn, "SELECT payload_json FROM ml_models WHERE name=?", (name,))
+    if not row:
+        return None
+    try:
+        return json.loads(row["payload_json"])
+    except Exception:
+        return None
+
+
+def forecast_next_months(payload: dict, horizon: int = 12) -> list[dict]:
+    if np is None:
+        raise HTTPException(status_code=500, detail="numpy não instalado. Adicione numpy ao requirements.txt.")
+
+    horizon = int(horizon)
+    if horizon < 1 or horizon > 24:
+        raise HTTPException(status_code=422, detail="horizon deve estar entre 1 e 24.")
+
+    hist = payload.get("history") or []
+    if not hist:
+        raise HTTPException(status_code=422, detail="Modelo sem histórico.")
+
+    lags = int(payload.get("lags", 6))
+    mi = payload["models"]["income"]
+    me = payload["models"]["expense_total"]
+
+    coef_i = np.array(mi["coef"], dtype=float)
+    b_i = float(mi["intercept"])
+    std_i = float(mi.get("std", 0.0))
+
+    coef_e = np.array(me["coef"], dtype=float)
+    b_e = float(me["intercept"])
+    std_e = float(me.get("std", 0.0))
+
+    yms = [r["ym"] for r in hist]
+    inc_vals = [float(r["income"]) for r in hist]
+    exp_vals = [float(r["expense_total"]) for r in hist]
+
+    last_ym = yms[-1]
+    y, m = ym_to_year_month(last_ym)
+
+    preds = []
+    for h in range(1, horizon + 1):
+        fy, fm = add_months(y, m, h)
+        fym = ym_from_year_month(fy, fm)
+
+        t_idx = (len(yms) - 1) + h
+
+        inc_lags = [inc_vals[-k] for k in range(1, lags + 1)]
+        exp_lags = [exp_vals[-k] for k in range(1, lags + 1)]
+
+        inc_ma3 = sum(inc_vals[-3:]) / 3.0 if len(inc_vals) >= 3 else inc_vals[-1]
+        inc_ma6 = sum(inc_vals[-6:]) / 6.0 if len(inc_vals) >= 6 else inc_ma3
+
+        exp_ma3 = sum(exp_vals[-3:]) / 3.0 if len(exp_vals) >= 3 else exp_vals[-1]
+        exp_ma6 = sum(exp_vals[-6:]) / 6.0 if len(exp_vals) >= 6 else exp_ma3
+
+        Xi = np.array([make_time_feats(fym, t_idx) + inc_lags + [inc_ma3, inc_ma6]], dtype=float)
+        Xe = np.array([make_time_feats(fym, t_idx) + exp_lags + [exp_ma3, exp_ma6]], dtype=float)
+
+        inc_pred = float(ridge_predict(Xi, coef_i, b_i)[0])
+        exp_pred = float(ridge_predict(Xe, coef_e, b_e)[0])
+
+        inc_pred = max(0.0, inc_pred)
+        exp_pred = max(0.0, exp_pred)
+
+        bal_pred = inc_pred - exp_pred
+
+        z = 1.28  # ~80%
+        inc_low, inc_high = max(0.0, inc_pred - z * std_i), inc_pred + z * std_i
+        exp_low, exp_high = max(0.0, exp_pred - z * std_e), exp_pred + z * std_e
+
+        preds.append({
+            "ym": fym,
+            "income_pred": inc_pred,
+            "expense_pred": exp_pred,
+            "balance_pred": bal_pred,
+            "income_low": inc_low,
+            "income_high": inc_high,
+            "expense_low": exp_low,
+            "expense_high": exp_high,
+        })
+
+        inc_vals.append(inc_pred)
+        exp_vals.append(exp_pred)
+
+    return preds
+
+
+# ============================================================
+# Forecast Endpoints
+# ============================================================
+@app.post("/forecast/train", response_model=ForecastTrainOut)
+def forecast_train(alpha: float = 3.0, lags: int = 6):
+    with db() as conn:
+        payload = train_models_competencia(conn, alpha=float(alpha), lags=int(lags))
+        save_model(conn, "forecast_competencia_v1", payload)
+
+        metrics = {
+            "income": payload["models"]["income"]["metrics"],
+            "expense_total": payload["models"]["expense_total"]["metrics"],
+        }
+
+        return {
+            "ok": True,
+            "basis": "competencia",
+            "trained_at": payload["trained_at"],
+            "n_months": len(payload.get("history") or []),
+            "start_ym": payload["start_ym"],
+            "end_ym": payload["end_ym"],
+            "metrics": metrics,
+        }
+
+
+@app.get("/forecast", response_model=ForecastOut)
+def forecast_get(horizon: int = 12):
+    with db() as conn:
+        payload = load_model(conn, "forecast_competencia_v1")
+        if not payload:
+            raise HTTPException(status_code=404, detail="Modelo não treinado. Rode POST /forecast/train.")
+
+        preds = forecast_next_months(payload, horizon=int(horizon))
+
+        hist = payload.get("history") or []
+        hist_tail = hist[-24:] if len(hist) > 24 else hist
+
+        metrics = {
+            "income": payload["models"]["income"]["metrics"],
+            "expense_total": payload["models"]["expense_total"]["metrics"],
+        }
+
+        note = (
+            "Projeção por competência: despesas = (caixa sem pagamento de fatura) + (compras do cartão por invoice_ym). "
+            "Pagamento de fatura afeta caixa, mas não é despesa real e não entra na projeção de despesa."
+        )
+
+        return {
+            "ok": True,
+            "basis": "competencia",
+            "horizon": int(horizon),
+            "trained_at": payload.get("trained_at"),
+            "history": hist_tail,
+            "predictions": preds,
+            "metrics": metrics,
+            "note": note,
+        }