therminal-py 1.0.0

Python SDK for Therminal — Kalshi temperature prediction markets + NWS weather data

therminal-py

Python SDK for Therminal — Kalshi temperature prediction markets + NWS weather data.

Install

pip install therminal-py            # core (returns dicts)
pip install therminal-py[pandas]    # + DataFrame support
pip install therminal-py[ml]       # + scikit-learn ML features
pip install therminal-py[cli]       # + CLI tool
pip install therminal-py[all]       # pandas + ml + cli

Quick Start

from therminal import TherminalClient

client = TherminalClient()

# Get candles as a Pandas DataFrame
df = client.candles(
    market="KXHIGHNY-26MAR20-T50",
    from_date="2026-03-01",
    interval=5,
    as_dataframe=True,
)

# Get NYC weather observations in metric units
obs = client.observations(station="NYC", units="metric", limit=10)

# Get 1-minute ASOS observations (integer °C)
omo = client.observations(station="ATL", resolution="1min", from_date="2025-01-01", limit=100)

ML Features (scikit-learn)

pip install therminal-py[ml]

from therminal.ml import WeatherFeatures
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import GradientBoostingRegressor

# WeatherFeatures is a scikit-learn Transformer
# Input: dates → Output: feature matrix (X)
# Target (y) is your responsibility
pipe = make_pipeline(
    WeatherFeatures(station="ATL", sources=["omo", "metar"], lookback_hours=24),
    StandardScaler(),
    GradientBoostingRegressor(),
)
pipe.fit(dates_train, y_train)
pipe.predict(dates_test)

# Configurable: sources, lookback window, aggregations, calendar features
wf = WeatherFeatures(
    station="ATL",
    sources=["omo", "metar"],
    lookback_hours=48,
    omo_aggs=("min", "max", "mean", "std", "range"),
    include_calendar=True,
)
X = wf.fit_transform(dates)
wf.get_feature_names_out()  # ['omo_temp_c_mean_48h', 'metar_temp_f_last_48h', ...]

Documentation

Full API reference with interactive playground: docs.mostlyright.xyz