> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idoptlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TransportPredictor

> Unified API for all transport cost and time models

## Import

```python theme={null}
from air_travel_model import TransportPredictor
tp = TransportPredictor()
```

On instantiation, `TransportPredictor` loads all available `.pkl` model files from `src/air_travel_model/data/`. Missing files are skipped — the predictor still works with whatever models are present.

***

## Methods

### `predict(model, origin, destination, **kwargs) -> float | None`

Runs the ML model for the given mode. Returns a `float` (time in minutes or cost in USD), or `None` if the model is not loaded.

For `drive_time`, routes not in the training dataset fall back to a live OSRM query before returning `None`. See [Routing Fallback](/guides/routing-fallback).

```python theme={null}
fare     = tp.predict("air_fare",   "CHS", "ROA", quarter=2, is_business=False)
air_min  = tp.predict("air_time",   "CHS", "ROA", quarter=2)
drv_min  = tp.predict("drive_time", "CHS", "ROA")
```

| Parameter     | Type           | Description                              |
| ------------- | -------------- | ---------------------------------------- |
| `model`       | `str`          | Model name — see table below             |
| `origin`      | `str \| tuple` | IATA code, `"City, ST"`, or `(lat, lon)` |
| `destination` | `str \| tuple` | Same as origin                           |
| `**kwargs`    |                | Model-specific options — see table below |

Raises `ValueError` for unrecognised location strings.

***

### `estimate(model, origin, destination, **kwargs) -> float | None`

Heuristic estimate — intended as a guaranteed fallback when `predict()` returns `None` or the model is not loaded.

For `drive_time`, `estimate()` also queries OSRM first and only falls back to the haversine formula if OSRM is unavailable.

```python theme={null}
result = tp.estimate("drive_time", "BFD", "UNV")   # always returns a value
```

***

### `predict_all(origin, destination, **kwargs) -> dict`

Calls `predict()` for all loaded models and returns a `{model_name: float}` dict. Models that return `None` are omitted from the result.

```python theme={null}
results = tp.predict_all("CRW", "ATL", quarter=2)
# {"air_fare": 253.74, "air_time": 59.0, "drive_time": 595.0, "drive_fare": 58.49}
```

***

### `estimate_all(origin, destination) -> dict`

Calls `estimate()` for all models. Returns a `{model_name: float}` dict, skipping any model whose `estimate()` raises or returns `None`.

***

### `available -> list[str]`

Returns model names that have a trained `.pkl` loaded.

```python theme={null}
print(tp.available)
# ["air_fare", "air_time", "drive_time", "drive_fare", ...]
```

***

## Model names and kwargs

| Model name   | Unit    | Required kwargs | Optional kwargs                                            |
| ------------ | ------- | --------------- | ---------------------------------------------------------- |
| `air_fare`   | USD     | `quarter` (1–4) | `is_business` (bool, default `False`)                      |
| `air_time`   | minutes | `quarter` (1–4) | —                                                          |
| `drive_time` | minutes | —               | —                                                          |
| `drive_fare` | USD     | —               | `gas_price` (\$/gal, default `3.50`), `mpg` (default `28`) |
| `bus_fare`   | USD     | `quarter` (1–4) | `is_premium` (bool, default `False`)                       |
| `bus_time`   | minutes | `quarter` (1–4) | —                                                          |
| `train_time` | minutes | `quarter` (1–4) | —                                                          |

***

## Location resolution

Locations are resolved through `air_travel_model.resolvers.location.resolve()`:

* **IATA code** (`"CHS"`) — direct lookup in `airports.csv`
* **City name** (`"Charleston, SC"`) — matched against `city, state` entries in `airports.csv`
* **`(lat, lon)` tuple** — used directly for coordinate-based routing; no IATA code is assigned, so models that require a code for route-stats lookup (air\_fare, air\_time) will fall back to their heuristics

Raises `ValueError` with a descriptive message for unrecognised strings.

For `train_time`, origins and destinations are additionally resolved against `amtrak_stations.csv`. Amtrak station codes (`"NYP"`, `"WAS"`, `"CHI"`) give the best accuracy because the model was trained on station-to-station pairs.