@saibolla/ada 0.1.2

package/skills/timesfm-forecasting/examples/global-temperature/run_example.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# run_example.sh - Run the TimesFM temperature anomaly forecasting example
+#
+# This script:
+# 1. Runs the preflight system check
+# 2. Runs the TimesFM forecast
+# 3. Generates the visualization
+#
+# Usage:
+#   ./run_example.sh
+#
+# Prerequisites:
+#   - Python 3.10+
+#   - timesfm[torch] installed: uv pip install "timesfm[torch]"
+#   - matplotlib, pandas, numpy
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+
+echo "============================================================"
+echo "  TimesFM Example: Global Temperature Anomaly Forecast"
+echo "============================================================"
+
+# Step 1: Preflight check
+echo ""
+echo "🔍 Step 1: Running preflight system check..."
+python3 "$SKILL_ROOT/scripts/check_system.py" || {
+    echo "❌ Preflight check failed. Please fix the issues above before continuing."
+    exit 1
+}
+
+# Step 2: Run forecast
+echo ""
+echo "📊 Step 2: Running TimesFM forecast..."
+cd "$SCRIPT_DIR"
+python3 run_forecast.py
+
+# Step 3: Generate visualization
+echo ""
+echo "📈 Step 3: Generating visualization..."
+python3 visualize_forecast.py
+
+echo ""
+echo "============================================================"
+echo "  ✅ Example complete!"
+echo "============================================================"
+echo ""
+echo "Output files:"
+echo "  - $SCRIPT_DIR/output/forecast_output.csv"
+echo "  - $SCRIPT_DIR/output/forecast_output.json"
+echo "  - $SCRIPT_DIR/output/forecast_visualization.png"

package/skills/timesfm-forecasting/examples/global-temperature/run_forecast.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Run TimesFM forecast on global temperature anomaly data.
+Generates forecast output CSV and JSON for the example.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+# Preflight check
+print("=" * 60)
+print("  TIMeSFM FORECAST - Global Temperature Anomaly Example")
+print("=" * 60)
+
+# Load data
+data_path = Path(__file__).parent / "temperature_anomaly.csv"
+df = pd.read_csv(data_path, parse_dates=["date"])
+df = df.sort_values("date").reset_index(drop=True)
+
+print(f"\n📊 Input Data: {len(df)} months of temperature anomalies")
+print(
+    f"   Date range: {df['date'].min().strftime('%Y-%m')} to {df['date'].max().strftime('%Y-%m')}"
+)
+print(f"   Mean anomaly: {df['anomaly_c'].mean():.2f}°C")
+print(
+    f"   Trend: {df['anomaly_c'].iloc[-12:].mean() - df['anomaly_c'].iloc[:12].mean():.2f}°C change (first to last year)"
+)
+
+# Prepare input for TimesFM
+# TimesFM expects a list of 1D numpy arrays
+input_series = df["anomaly_c"].values.astype(np.float32)
+
+# Load TimesFM 1.0 (PyTorch)
+# NOTE: TimesFM 2.5 PyTorch checkpoint has a file format issue at time of writing.
+# The model.safetensors file is not loadable via torch.load().
+# Using TimesFM 1.0 PyTorch which works correctly.
+print("\n🤖 Loading TimesFM 1.0 (200M) PyTorch...")
+import timesfm
+
+hparams = timesfm.TimesFmHparams(horizon_len=12)
+checkpoint = timesfm.TimesFmCheckpoint(
+    huggingface_repo_id="google/timesfm-1.0-200m-pytorch"
+)
+model = timesfm.TimesFm(hparams=hparams, checkpoint=checkpoint)
+
+# Forecast
+print("\n📈 Running forecast (12 months ahead)...")
+forecast_input = [input_series]
+frequency_input = [0]  # Monthly data
+
+point_forecast, experimental_quantile_forecast = model.forecast(
+    forecast_input,
+    freq=frequency_input,
+)
+
+print(f"   Point forecast shape: {point_forecast.shape}")
+print(f"   Quantile forecast shape: {experimental_quantile_forecast.shape}")
+
+# Extract results
+point = point_forecast[0]  # Shape: (horizon,)
+quantiles = experimental_quantile_forecast[0]  # Shape: (horizon, num_quantiles)
+
+# TimesFM quantiles: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.99]
+# Index mapping: 0=10%, 1=20%, ..., 4=50% (median), ..., 9=99%
+quantile_labels = ["10%", "20%", "30%", "40%", "50%", "60%", "70%", "80%", "90%", "99%"]
+
+# Create forecast dates (2025 monthly)
+last_date = df["date"].max()
+forecast_dates = pd.date_range(
+    start=last_date + pd.DateOffset(months=1), periods=12, freq="MS"
+)
+
+# Build output DataFrame
+output_df = pd.DataFrame(
+    {
+        "date": forecast_dates.strftime("%Y-%m-%d"),
+        "point_forecast": point,
+        "q10": quantiles[:, 0],
+        "q20": quantiles[:, 1],
+        "q30": quantiles[:, 2],
+        "q40": quantiles[:, 3],
+        "q50": quantiles[:, 4],  # Median
+        "q60": quantiles[:, 5],
+        "q70": quantiles[:, 6],
+        "q80": quantiles[:, 7],
+        "q90": quantiles[:, 8],
+        "q99": quantiles[:, 9],
+    }
+)
+
+# Save outputs
+output_dir = Path(__file__).parent / "output"
+output_dir.mkdir(exist_ok=True)
+output_df.to_csv(output_dir / "forecast_output.csv", index=False)
+
+# JSON output for the report
+output_json = {
+    "model": "TimesFM 1.0 (200M) PyTorch",
+    "input": {
+        "source": "NOAA GISTEMP Global Temperature Anomaly",
+        "n_observations": len(df),
+        "date_range": f"{df['date'].min().strftime('%Y-%m')} to {df['date'].max().strftime('%Y-%m')}",
+        "mean_anomaly_c": round(df["anomaly_c"].mean(), 3),
+    },
+    "forecast": {
+        "horizon": 12,
+        "dates": forecast_dates.strftime("%Y-%m").tolist(),
+        "point": point.tolist(),
+        "quantiles": {
+            label: quantiles[:, i].tolist() for i, label in enumerate(quantile_labels)
+        },
+    },
+    "summary": {
+        "forecast_mean_c": round(float(point.mean()), 3),
+        "forecast_max_c": round(float(point.max()), 3),
+        "forecast_min_c": round(float(point.min()), 3),
+        "vs_last_year_mean": round(
+            float(point.mean() - df["anomaly_c"].iloc[-12:].mean()), 3
+        ),
+    },
+}
+
+with open(output_dir / "forecast_output.json", "w") as f:
+    json.dump(output_json, f, indent=2)
+
+# Print summary
+print("\n" + "=" * 60)
+print("  FORECAST RESULTS")
+print("=" * 60)
+print(
+    f"\n📅 Forecast period: {forecast_dates[0].strftime('%Y-%m')} to {forecast_dates[-1].strftime('%Y-%m')}"
+)
+print(f"\n🌡️  Temperature Anomaly Forecast (°C above 1951-1980 baseline):")
+print(f"\n   {'Month':<10} {'Point':>8} {'80% CI':>15} {'90% CI':>15}")
+print(f"   {'-' * 10} {'-' * 8} {'-' * 15} {'-' * 15}")
+for i, (date, pt, q10, q90, q05, q95) in enumerate(
+    zip(
+        forecast_dates.strftime("%Y-%m"),
+        point,
+        quantiles[:, 1],  # 20%
+        quantiles[:, 7],  # 80%
+        quantiles[:, 0],  # 10%
+        quantiles[:, 8],  # 90%
+    )
+):
+    print(
+        f"   {date:<10} {pt:>8.3f} [{q10:>6.3f}, {q90:>6.3f}] [{q05:>6.3f}, {q95:>6.3f}]"
+    )
+
+print(f"\n📊 Summary Statistics:")
+print(f"   Mean forecast:  {point.mean():.3f}°C")
+print(
+    f"   Max forecast:   {point.max():.3f}°C (Month: {forecast_dates[point.argmax()].strftime('%Y-%m')})"
+)
+print(
+    f"   Min forecast:   {point.min():.3f}°C (Month: {forecast_dates[point.argmin()].strftime('%Y-%m')})"
+)
+print(f"   vs 2024 mean:   {point.mean() - df['anomaly_c'].iloc[-12:].mean():+.3f}°C")
+
+print(f"\n✅ Output saved to:")
+print(f"   {output_dir / 'forecast_output.csv'}")
+print(f"   {output_dir / 'forecast_output.json'}")

package/skills/timesfm-forecasting/examples/global-temperature/temperature_anomaly.csv

@@ -0,0 +1,37 @@
+date,anomaly_c
+2022-01-01,0.89
+2022-02-01,0.89
+2022-03-01,1.02
+2022-04-01,0.88
+2022-05-01,0.85
+2022-06-01,0.88
+2022-07-01,0.88
+2022-08-01,0.90
+2022-09-01,0.88
+2022-10-01,0.95
+2022-11-01,0.77
+2022-12-01,0.78
+2023-01-01,0.87
+2023-02-01,0.98
+2023-03-01,1.21
+2023-04-01,1.00
+2023-05-01,0.94
+2023-06-01,1.08
+2023-07-01,1.18
+2023-08-01,1.24
+2023-09-01,1.47
+2023-10-01,1.32
+2023-11-01,1.18
+2023-12-01,1.16
+2024-01-01,1.22
+2024-02-01,1.35
+2024-03-01,1.34
+2024-04-01,1.26
+2024-05-01,1.15
+2024-06-01,1.20
+2024-07-01,1.24
+2024-08-01,1.30
+2024-09-01,1.28
+2024-10-01,1.27
+2024-11-01,1.22
+2024-12-01,1.20

package/skills/timesfm-forecasting/examples/global-temperature/visualize_forecast.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+Visualize TimesFM forecast results for global temperature anomaly.
+
+Generates a publication-quality figure showing:
+- Historical data (2022-2024)
+- Point forecast (2025)
+- 80% and 90% confidence intervals (fan chart)
+
+Usage:
+    python visualize_forecast.py
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+# Configuration
+EXAMPLE_DIR = Path(__file__).parent
+INPUT_FILE = EXAMPLE_DIR / "temperature_anomaly.csv"
+FORECAST_FILE = EXAMPLE_DIR / "output" / "forecast_output.json"
+OUTPUT_FILE = EXAMPLE_DIR / "output" / "forecast_visualization.png"
+
+
+def main() -> None:
+    # Load historical data
+    df = pd.read_csv(INPUT_FILE, parse_dates=["date"])
+
+    # Load forecast results
+    with open(FORECAST_FILE) as f:
+        forecast = json.load(f)
+
+    # Extract forecast data
+    dates = pd.to_datetime(forecast["forecast"]["dates"])
+    point = np.array(forecast["forecast"]["point"])
+    q10 = np.array(forecast["forecast"]["quantiles"]["10%"])
+    q20 = np.array(forecast["forecast"]["quantiles"]["20%"])
+    q80 = np.array(forecast["forecast"]["quantiles"]["80%"])
+    q90 = np.array(forecast["forecast"]["quantiles"]["90%"])
+
+    # Create figure
+    fig, ax = plt.subplots(figsize=(12, 6))
+
+    # Plot historical data
+    ax.plot(
+        df["date"],
+        df["anomaly_c"],
+        color="#2563eb",
+        linewidth=1.5,
+        marker="o",
+        markersize=3,
+        label="Historical (NOAA GISTEMP)",
+    )
+
+    # Plot 90% CI (outer band)
+    ax.fill_between(dates, q10, q90, alpha=0.2, color="#dc2626", label="90% CI")
+
+    # Plot 80% CI (inner band)
+    ax.fill_between(dates, q20, q80, alpha=0.3, color="#dc2626", label="80% CI")
+
+    # Plot point forecast
+    ax.plot(
+        dates,
+        point,
+        color="#dc2626",
+        linewidth=2,
+        marker="s",
+        markersize=4,
+        label="TimesFM Forecast",
+    )
+
+    # Add vertical line at forecast boundary
+    ax.axvline(
+        x=df["date"].max(), color="#6b7280", linestyle="--", linewidth=1, alpha=0.7
+    )
+
+    # Formatting
+    ax.set_xlabel("Date", fontsize=12)
+    ax.set_ylabel("Temperature Anomaly (°C)", fontsize=12)
+    ax.set_title(
+        "TimesFM Zero-Shot Forecast Example\n36-month Temperature Anomaly → 12-month Forecast",
+        fontsize=14,
+        fontweight="bold",
+    )
+
+    # Add annotations
+    ax.annotate(
+        f"Mean forecast: {forecast['summary']['forecast_mean_c']:.2f}°C\n"
+        f"vs 2024: {forecast['summary']['vs_last_year_mean']:+.2f}°C",
+        xy=(dates[6], point[6]),
+        xytext=(dates[6], point[6] + 0.15),
+        fontsize=10,
+        arrowprops=dict(arrowstyle="->", color="#6b7280", lw=1),
+        bbox=dict(boxstyle="round,pad=0.3", facecolor="white", edgecolor="#6b7280"),
+    )
+
+    # Grid and legend
+    ax.grid(True, alpha=0.3)
+    ax.legend(loc="upper left", fontsize=10)
+
+    # Set y-axis limits
+    ax.set_ylim(0.7, 1.5)
+
+    # Rotate x-axis labels
+    plt.xticks(rotation=45, ha="right")
+
+    # Tight layout
+    plt.tight_layout()
+
+    # Save
+    fig.savefig(OUTPUT_FILE, dpi=150, bbox_inches="tight")
+    print(f"✅ Saved visualization to: {OUTPUT_FILE}")
+
+    plt.close()
+
+
+if __name__ == "__main__":
+    main()

package/skills/timesfm-forecasting/references/api_reference.md

@@ -0,0 +1,231 @@
+# TimesFM API Reference
+
+## Model Classes
+
+### `timesfm.TimesFM_2p5_200M_torch`
+
+The primary model class for TimesFM 2.5 (200M parameters, PyTorch backend).
+
+#### `from_pretrained()`
+
+```python
+model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
+    "google/timesfm-2.5-200m-pytorch",
+    cache_dir=None,         # Optional: custom cache directory
+    force_download=True,    # Re-download even if cached
+)
+```
+
+| Parameter | Type | Default | Description |
+| --------- | ---- | ------- | ----------- |
+| `model_id` | str | `"google/timesfm-2.5-200m-pytorch"` | Hugging Face model ID |
+| `revision` | str \| None | None | Specific model revision |
+| `cache_dir` | str \| Path \| None | None | Custom cache directory |
+| `force_download` | bool | True | Force re-download of weights |
+
+**Returns**: Initialized `TimesFM_2p5_200M_torch` instance (not yet compiled).
+
+#### `compile()`
+
+Compiles the model with the given forecast configuration. **Must be called before `forecast()`.**
+
+```python
+model.compile(
+    timesfm.ForecastConfig(
+        max_context=1024,
+        max_horizon=256,
+        normalize_inputs=True,
+        per_core_batch_size=32,
+        use_continuous_quantile_head=True,
+        force_flip_invariance=True,
+        infer_is_positive=True,
+        fix_quantile_crossing=True,
+    )
+)
+```
+
+**Raises**: Nothing (but `forecast()` will raise `RuntimeError` if not compiled).
+
+#### `forecast()`
+
+Run inference on one or more time series.
+
+```python
+point_forecast, quantile_forecast = model.forecast(
+    horizon=24,
+    inputs=[array1, array2, ...],
+)
+```
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `horizon` | int | Number of future steps to forecast |
+| `inputs` | list[np.ndarray] | List of 1-D numpy arrays (each is a time series) |
+
+**Returns**: `tuple[np.ndarray, np.ndarray]`
+
+- `point_forecast`: shape `(batch_size, horizon)` — median (0.5 quantile)
+- `quantile_forecast`: shape `(batch_size, horizon, 10)` — [mean, q10, q20, ..., q90]
+
+**Raises**: `RuntimeError` if model is not compiled.
+
+**Key behaviors**:
+
+- Leading NaN values are stripped automatically
+- Internal NaN values are linearly interpolated
+- Series longer than `max_context` are truncated (last `max_context` points used)
+- Series shorter than `max_context` are padded
+
+#### `forecast_with_covariates()`
+
+Run inference with exogenous variables (requires `timesfm[xreg]`).
+
+```python
+point, quantiles = model.forecast_with_covariates(
+    inputs=inputs,
+    dynamic_numerical_covariates={"temp": [temp_array1, temp_array2]},
+    dynamic_categorical_covariates={"dow": [dow_array1, dow_array2]},
+    static_categorical_covariates={"region": ["east", "west"]},
+    xreg_mode="xreg + timesfm",
+)
+```
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `inputs` | list[np.ndarray] | Target time series |
+| `dynamic_numerical_covariates` | dict[str, list[np.ndarray]] | Time-varying numeric features |
+| `dynamic_categorical_covariates` | dict[str, list[np.ndarray]] | Time-varying categorical features |
+| `static_categorical_covariates` | dict[str, list[str]] | Fixed categorical features per series |
+| `xreg_mode` | str | `"xreg + timesfm"` or `"timesfm + xreg"` |
+
+**Note**: Dynamic covariates must have length `context + horizon` for each series.
+
+---
+
+## `timesfm.ForecastConfig`
+
+Immutable dataclass controlling all forecast behavior.
+
+```python
+@dataclasses.dataclass(frozen=True)
+class ForecastConfig:
+    max_context: int = 0
+    max_horizon: int = 0
+    normalize_inputs: bool = False
+    per_core_batch_size: int = 1
+    use_continuous_quantile_head: bool = False
+    force_flip_invariance: bool = True
+    infer_is_positive: bool = True
+    fix_quantile_crossing: bool = False
+    return_backcast: bool = False
+    quantiles: list[float] = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
+    decode_index: int = 5
+```
+
+### Parameter Details
+
+#### `max_context` (int, default=0)
+
+Maximum number of historical time points to use as context.
+
+- **0**: Use the model's maximum supported context (16,384 for v2.5)
+- **N**: Truncate series to last N points
+- **Best practice**: Set to the length of your longest series, or 512–2048 for speed
+
+#### `max_horizon` (int, default=0)
+
+Maximum forecast horizon.
+
+- **0**: Use the model's maximum
+- **N**: Forecasts up to N steps (can still call `forecast(horizon=M)` where M ≤ N)
+- **Best practice**: Set to your expected maximum forecast length
+
+#### `normalize_inputs` (bool, default=False)
+
+Whether to z-normalize each series before feeding to the model.
+
+- **True** (RECOMMENDED): Normalizes each series to zero mean, unit variance
+- **False**: Raw values are passed directly
+- **When False is OK**: Only if your series are already normalized or very close to scale 1.0
+
+#### `per_core_batch_size` (int, default=1)
+
+Number of series processed per device in each batch.
+
+- Increase for throughput, decrease if OOM
+- See `references/system_requirements.md` for recommended values by hardware
+
+#### `use_continuous_quantile_head` (bool, default=False)
+
+Use the 30M-parameter continuous quantile head for better interval calibration.
+
+- **True** (RECOMMENDED): More accurate prediction intervals, especially for longer horizons
+- **False**: Uses fixed quantile buckets (faster but less accurate intervals)
+
+#### `force_flip_invariance` (bool, default=True)
+
+Ensures the model satisfies `f(-x) = -f(x)`.
+
+- **True** (RECOMMENDED): Mathematical consistency — forecasts are invariant to sign flip
+- **False**: Slightly faster but may produce asymmetric forecasts
+
+#### `infer_is_positive` (bool, default=True)
+
+Automatically detect if all input values are positive and clamp forecasts ≥ 0.
+
+- **True**: Safe for sales, demand, counts, prices, volumes
+- **False**: Required for temperature, returns, PnL, any series that can be negative
+
+#### `fix_quantile_crossing` (bool, default=False)
+
+Post-process quantiles to ensure monotonicity (q10 ≤ q20 ≤ ... ≤ q90).
+
+- **True** (RECOMMENDED): Guarantees well-ordered quantiles
+- **False**: Slightly faster but quantiles may occasionally cross
+
+#### `return_backcast` (bool, default=False)
+
+Return the model's reconstruction of the input (backcast) in addition to forecast.
+
+- **True**: Used for covariate workflows and diagnostics
+- **False**: Only return forecast
+
+---
+
+## Available Model Checkpoints
+
+| Model ID | Version | Params | Backend | Context |
+| -------- | ------- | ------ | ------- | ------- |
+| `google/timesfm-2.5-200m-pytorch` | 2.5 | 200M | PyTorch | 16,384 |
+| `google/timesfm-2.5-200m-flax` | 2.5 | 200M | JAX/Flax | 16,384 |
+| `google/timesfm-2.5-200m-transformers` | 2.5 | 200M | Transformers | 16,384 |
+| `google/timesfm-2.0-500m-pytorch` | 2.0 | 500M | PyTorch | 2,048 |
+| `google/timesfm-2.0-500m-jax` | 2.0 | 500M | JAX | 2,048 |
+| `google/timesfm-1.0-200m-pytorch` | 1.0 | 200M | PyTorch | 2,048 |
+| `google/timesfm-1.0-200m` | 1.0 | 200M | JAX | 2,048 |
+
+---
+
+## Output Shape Reference
+
+| Output | Shape | Description |
+| ------ | ----- | ----------- |
+| `point_forecast` | `(B, H)` | Median forecast for B series, H steps |
+| `quantile_forecast` | `(B, H, 10)` | Full quantile distribution |
+| `quantile_forecast[:,:,0]` | `(B, H)` | Mean |
+| `quantile_forecast[:,:,1]` | `(B, H)` | 10th percentile |
+| `quantile_forecast[:,:,5]` | `(B, H)` | 50th percentile (= point_forecast) |
+| `quantile_forecast[:,:,9]` | `(B, H)` | 90th percentile |
+
+Where `B` = batch size (number of input series), `H` = forecast horizon.
+
+---
+
+## Error Handling
+
+| Error | Cause | Fix |
+| ----- | ----- | --- |
+| `RuntimeError: Model is not compiled` | Called `forecast()` before `compile()` | Call `model.compile(ForecastConfig(...))` first |
+| `torch.cuda.OutOfMemoryError` | Batch too large for GPU | Reduce `per_core_batch_size` |
+| `ValueError: inputs must be list` | Passed array instead of list | Wrap in list: `[array]` |
+| `HfHubHTTPError` | Download failed | Check internet, set `HF_HOME` to writable dir |