Nixtla/nixtla

📦 What is Niixla?

Nixtla is the SDK that lets you talk to TimeGPT, a large‑scale transformer model built specifically for time‑series forecasting and anomaly detection. The model itself is hosted as a service (you need an API key), while the Python package provides a thin client, helper utilities and integrations (Snowflake, other languages) so you can call the model from your own code.

---

🚀 Core capabilities

Feature	What it does	How you use it
Zero‑shot forecasting	Generate point forecasts and prediction intervals for any time‑series without any local training.	client.forecast(df, h=24, level=[80,90])
Anomaly detection	Identify outliers in historic data (batch) or online streams.	client.detect_anomalies(df, …) (batch) / client.detect_anomalies_online(df, h, detection_size)
Fine‑tuning	Adapt the pre‑trained model to your own domain for better accuracy.	Available through the API (not shown in the README).
Exogenous variables	Add extra regressors (holidays, prices, etc.) to improve forecasts.	Pass them via the API request.
Multi‑series support	Forecast many series in a single call, saving compute.	Same forecast method works on a DataFrame with multiple IDs.
Cross‑validation & custom loss	Built‑in utilities for model validation and custom fine‑tuning objectives.	Exposed through the API.
Deployments	Run the service inside Snowflake or call it from JavaScript, Go, etc.	pip install nixtla[snowflake] then run the install script.

---

🛠️ How to get started (quick‑start)

pip install "nixtla>=0.8.0"

import pandas as pd
from nixtla import NixtlaClient

# 1️⃣ Get a free‑trial API key at https://nixtla.io/free-trial
client = NixtlaClient(api_key="YOUR_KEY")

# 2️⃣ Load a time‑series (example: electricity demand)
df = pd.read_csv(
    "https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short.csv"
)

# 3️⃣ Forecast the next 24 steps
forecast = client.forecast(df, h=24, level=[80, 90])

# 4️⃣ (optional) Plot
client.plot(df, forecast, level=[80, 90])

The same pattern works for anomaly detection, just replace forecast with detect_anomalies.

---

📚 Documentation & community

• Docs – https://docs.nixtla.io – full API reference, tutorials (fine‑tuning, scaling with Spark/Dask/Ray, handling irregular timestamps, etc.).
• Slack community – join via the badge in the README.
• GitHub – CI status, issue tracker, contribution guide.

---

⚙️ Architecture at a glance

TimeGPT is a decoder‑only transformer trained on >100 B data points from many domains (finance, IoT, weather, web traffic, …). It uses self‑attention to capture patterns across long horizons and outputs a vector that is linearly projected to the forecast horizon. The model is not a generic LLM; it is a purpose‑built time‑series foundation model.

---

📈 When to use it

Use case	Why TimeGPT fits
Rapid prototyping – you need a forecast today, not weeks of model building.	Zero‑shot inference works out‑of‑the‑box.
Multiple series – thousands of SKU sales or sensor streams.	One API call can handle many series, saving compute.
Limited ML expertise – business analysts or product teams.	Low‑code Python client, just a few lines of code.
Production workloads – need a reliable, versioned service.	Hosted model with SLA, optional on‑prem deployment.

---

📝 Licensing & access

• The SDK (nixtla package) is Apache 2.0 open source.
• TimeGPT itself is a closed‑source service; you must provide an API key (free trial available) or deploy the model on‑prem if you obtain a commercial license.

---

🎯 Bottom line

Nixtla’s SDK is a thin, well‑documented client that makes a powerful, purpose‑built time‑series foundation model (TimeGPT) accessible via a simple Python API, with extra support for Snowflake, other languages, and enterprise‑grade features like fine‑tuning and custom loss functions.