Metadata-Version: 2.4
Name: therminal-py
Version: 1.0.2
Summary: Python SDK for Therminal — Kalshi temperature prediction markets + NWS weather data
Project-URL: Homepage, https://github.com/Tarabcak/therminal-py
Project-URL: API, https://api.mostlyright.xyz
Author: Tarabcak
License-Expression: MIT
Keywords: METAR,OHLCV,kalshi,prediction-markets,trading,weather
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Provides-Extra: all
Requires-Dist: numpy>=1.24; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: pyarrow>=15.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: scikit-learn>=1.3; extra == 'all'
Requires-Dist: typer>=0.12; extra == 'all'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.12; extra == 'cli'
Provides-Extra: dev
Requires-Dist: numpy>=1.24; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pyarrow>=15.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: rich>=13.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: scikit-learn>=1.3; extra == 'dev'
Requires-Dist: typer>=0.12; extra == 'dev'
Provides-Extra: ml
Requires-Dist: numpy>=1.24; extra == 'ml'
Requires-Dist: scikit-learn>=1.3; extra == 'ml'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Requires-Dist: pyarrow>=15.0; extra == 'pandas'
Provides-Extra: torch
Requires-Dist: numpy>=1.24; extra == 'torch'
Requires-Dist: torch>=2.0; extra == 'torch'
Description-Content-Type: text/markdown

# therminal-py

Python SDK for [Therminal](https://api.mostlyright.xyz) — Kalshi temperature prediction markets + NWS weather data + real-time METAR signaling.

## Install

```bash
pip install therminal-py            # core
pip install therminal-py[pandas]    # + DataFrame + Parquet support
pip install therminal-py[ml]        # + scikit-learn ML features
pip install therminal-py[torch]     # + PyTorch Dataset
pip install therminal-py[cli]       # + CLI tool
pip install therminal-py[all]       # pandas + ml + cli
```

Requires Python 3.11+.

## Quick Start

```python
from therminal.weather import WeatherClient, LiveClient
from therminal.markets import MarketsClient

# Historical observations (via therminal-api)
weather = WeatherClient()
obs = weather.observations(station="NYC", units="metric", as_dataframe=True)

# Live METAR (direct from AWC — same Observation schema as historical)
live = LiveClient()
current = live.current("NYC")
print(current[0].temp_f)

# Batch: one AWC request for multiple stations
batch = live.current(["NYC", "ATL", "MDW", "LAX"])

# Market candles
markets = MarketsClient()
df = markets.candles(market="KXHIGHNY-26MAR20-T50", from_date="2026-03-01", as_dataframe=True)
```

Backward compatible: `from therminal import TherminalClient` still works.

## Configuration

Create `~/.therminal.toml` for sensible defaults:

```toml
[defaults]
units = "metric"
station = "NYC"

[api]
base_url = "https://api.mostlyright.xyz"
```

Resolution order: file < env vars (`THERMINAL_UNITS`, `THERMINAL_TZ`, `THERMINAL_STATION`) < per-call kwargs.

## Live METAR (AWC Direct)

`LiveClient` fetches real-time METAR from the Aviation Weather Center. Returns `Observation` objects identical in schema to `WeatherClient.observations()`, eliminating train/serve skew for trading signals.

```python
from therminal.weather import LiveClient

live = LiveClient()
obs = live.current(["NYC", "ATL"])         # batch: one request
history = live.latest("NYC", hours=3)      # last 3 hours
metric = live.current("NYC", units="metric")  # with conversion
```

## ML Features (scikit-learn)

```bash
pip install therminal-py[ml]
```

```python
from therminal.ml import WeatherFeatures, LOBFeatures
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import GradientBoostingRegressor

pipe = make_pipeline(
    WeatherFeatures(station="ATL", sources=["omo", "metar"], lookback_hours=24),
    StandardScaler(),
    GradientBoostingRegressor(),
)
pipe.fit(dates_train, y_train)
pipe.predict(dates_test)
```

## Typed Models

All responses return frozen dataclasses with both attribute and dict-style access:

```python
obs = weather.observations(station="NYC")[0]
obs.temp_f          # attribute access
obs["temp_f"]       # dict access (backward compat)
obs.get("temp_f")   # .get() with default
obs.to_dict()       # full dict with all 29 fields
```

## Documentation

Full API reference with interactive playground: **[docs.mostlyright.xyz](https://docs.mostlyright.xyz)**
