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

# Volatility Skills

> Reference for vol.realized, vol.term_structure, vol.iv_rank, vol.vrp, vol.anomaly_score, and vol.character — computed-from-archive-closes volatility skills exposed to AI agents.

Volatility skills are **computed analytics** — they run trusted numpy code over archive closes to produce derived volatility metrics. They never execute agent-authored code, and every result includes the [provenance envelope](/skills/overview#the-provenance-envelope) with `source: "computed"`.

<Callout type="info">
  These skills read **real archive closes** — no agent-supplied price series. Pass a `symbol` and a window; the skill pulls the closes from the archive and computes the metric.
</Callout>

## Skill summary

| Skill ID             | Tool name            | Source   | Runtime     | Description                                        |
| -------------------- | -------------------- | -------- | ----------- | -------------------------------------------------- |
| `vol.realized`       | `vol_realized`       | computed | interactive | Annualized realized volatility from archive closes |
| `vol.term_structure` | `vol_term_structure` | computed | interactive | IV term structure by expiry                        |
| `vol.iv_rank`        | `vol_iv_rank`        | computed | interactive | IV rank and percentile                             |
| `vol.vrp`            | `vol_vrp`            | computed | interactive | Variance risk premium (IV − RV)                    |
| `vol.anomaly_score`  | `vol_anomaly_score`  | computed | interactive | Z-score of current vol vs. history                 |
| `vol.character`      | `vol_character`      | computed | interactive | Vol regime classification                          |

***

## vol.realized

Annualized realized volatility from archive closes. Computed as the annualized standard deviation of log returns over the window.

**Arguments**

| Name            | Type     | Required | Default          | Description                                                 |
| --------------- | -------- | -------- | ---------------- | ----------------------------------------------------------- |
| `symbol`        | string   | yes      | —                | Ticker symbol                                               |
| `window`        | int      | no       | `20`             | Lookback in trading days                                    |
| `as_of`         | ISO date | no       | latest           | End date for the window                                     |
| `annualization` | int      | no       | `252`            | Trading days per year                                       |
| `method`        | string   | no       | `close_to_close` | `close_to_close`, `parkinson`, `garman_klass`, `yang_zhang` |

**What it computes**: `RV = std(log_returns[-window:]) * sqrt(annualization)`

**Example**

```json theme={null}
vol_realized({ "symbol": "SPY", "window": 20, "method": "close_to_close" })
```

```json theme={null}
{
  "skill_id": "vol.realized",
  "data": {
    "symbol": "SPY", "window": 20, "as_of": "2025-06-27",
    "realized_vol": 0.112, "realized_vol_pct": 11.2,
    "method": "close_to_close", "annualization": 252
  },
  "provenance": { "source": "computed", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 1, "tier": "free" }, "warnings": [] }
}
```

***

## vol.term\_structure

IV term structure — implied vol by expiry, derived from the archive options chain.

**Arguments**

| Name           | Type     | Required | Default | Description                   |
| -------------- | -------- | -------- | ------- | ----------------------------- |
| `symbol`       | string   | yes      | —       | Ticker symbol                 |
| `as_of`        | ISO date | no       | latest  | Snapshot date                 |
| `strike`       | float    | no       | ATM     | Strike (defaults to spot)     |
| `moneyness`    | float    | no       | `1.0`   | K/S ratio if `strike` omitted |
| `max_expiries` | int      | no       | `12`    | Max expiries to return        |

**What it computes**: pulls the archive options chain, fits IV per expiry (Black-Scholes), returns the curve.

**Example**

```json theme={null}
vol_term_structure({ "symbol": "NVDA", "moneyness": 1.0 })
```

```json theme={null}
{
  "skill_id": "vol.term_structure",
  "data": {
    "symbol": "NVDA", "as_of": "2025-06-27", "spot": 128.42,
    "curve": [
      { "expiry": "2025-07-18", "dte": 21, "iv": 0.42 },
      { "expiry": "2025-08-15", "dte": 49, "iv": 0.39 },
      { "expiry": "2025-09-19", "dte": 84, "iv": 0.37 },
      { "expiry": "2025-12-19", "dte": 175, "iv": 0.35 }
    ],
    "slope": -0.0007
  },
  "provenance": { "source": "computed", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## vol.iv\_rank

IV rank and percentile — where current IV sits relative to its own trailing history.

**Arguments**

| Name            | Type     | Required | Default | Description    |
| --------------- | -------- | -------- | ------- | -------------- |
| `symbol`        | string   | yes      | —       | Ticker symbol  |
| `lookback_days` | int      | no       | `252`   | History window |
| `as_of`         | ISO date | no       | latest  | Snapshot date  |
| `strike`        | float    | no       | ATM     | Strike         |

**What it computes**:

* `iv_rank = (current_iv - min_iv) / (max_iv - min_iv) * 100`
* `iv_percentile` = rank of current IV in the trailing distribution

**Example**

```json theme={null}
vol_iv_rank({ "symbol": "TSLA", "lookback_days": 252 })
```

```json theme={null}
{
  "skill_id": "vol.iv_rank",
  "data": {
    "symbol": "TSLA", "as_of": "2025-06-27",
    "current_iv": 0.58, "iv_rank": 72, "iv_percentile": 0.78,
    "lookback_min_iv": 0.31, "lookback_max_iv": 0.92, "lookback_days": 252
  },
  "provenance": { "source": "computed", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## vol.vrp

Variance risk premium — the gap between implied and realized vol. Positive VRP means options are priced richer than realized.

**Arguments**

| Name        | Type     | Required | Default | Description                  |
| ----------- | -------- | -------- | ------- | ---------------------------- |
| `symbol`    | string   | yes      | —       | Ticker symbol                |
| `rv_window` | int      | no       | `21`    | Realized vol lookback (days) |
| `iv_window` | int      | no       | `30`    | Implied vol horizon (days)   |
| `as_of`     | ISO date | no       | latest  | Snapshot date                |

**What it computes**: `VRP = IV^2 − RV^2` (in variance space), plus the ratio `IV / RV`.

**Example**

```json theme={null}
vol_vrp({ "symbol": "SPY", "rv_window": 21, "iv_window": 30 })
```

```json theme={null}
{
  "skill_id": "vol.vrp",
  "data": {
    "symbol": "SPY", "as_of": "2025-06-27",
    "iv": 0.142, "rv": 0.112,
    "vrp_variance": 0.0078, "iv_rv_ratio": 1.27
  },
  "provenance": { "source": "computed", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## vol.anomaly\_score

Z-score of current realized vol against its trailing distribution — flags vol spikes.

**Arguments**

| Name            | Type     | Required | Default | Description         |
| --------------- | -------- | -------- | ------- | ------------------- |
| `symbol`        | string   | yes      | —       | Ticker symbol       |
| `window`        | int      | no       | `20`    | Realized vol window |
| `lookback_days` | int      | no       | `252`   | Baseline history    |
| `as_of`         | ISO date | no       | latest  | Snapshot date       |

**What it computes**: `z = (current_rv - mean_rv) / std_rv` over the trailing `lookback_days`.

**Example**

```json theme={null}
vol_anomaly_score({ "symbol": "NVDA", "window": 20 })
```

```json theme={null}
{
  "skill_id": "vol.anomaly_score",
  "data": {
    "symbol": "NVDA", "as_of": "2025-06-27",
    "current_rv": 0.48, "baseline_mean_rv": 0.35, "baseline_std_rv": 0.08,
    "z_score": 1.625, "is_anomaly": false, "threshold": 2.0
  },
  "provenance": { "source": "computed", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

***

## vol.character

Vol regime classification — labels the current vol environment.

**Arguments**

| Name            | Type     | Required | Default | Description    |
| --------------- | -------- | -------- | ------- | -------------- |
| `symbol`        | string   | yes      | —       | Ticker symbol  |
| `lookback_days` | int      | no       | `252`   | History window |
| `as_of`         | ISO date | no       | latest  | Snapshot date  |

**What it computes**: classifies the regime as `low`, `normal`, `elevated`, `high`, or `crisis` based on realized vol percentile and trend; also returns `term_structure` (`contango` / `backwardation`) and `trend` (`rising` / `falling` / `flat`).

**Example**

```json theme={null}
vol_character({ "symbol": "SPY" })
```

```json theme={null}
{
  "skill_id": "vol.character",
  "data": {
    "symbol": "SPY", "as_of": "2025-06-27",
    "regime": "low", "rv_percentile": 0.18,
    "term_structure": "contango", "trend": "falling",
    "iv_rank": 22
  },
  "provenance": { "source": "computed", "freshness": { "as_of": "2025-06-27T20:00:00Z", "lag_seconds": 0 }, "cost": { "credits": 2, "tier": "basic" }, "warnings": [] }
}
```

## Next steps

<Card title="Options Skills" icon="sliders" href="/skills/options">
  Black-Scholes greeks and implied vol — pure computed from agent-supplied inputs.
</Card>

<Card title="Computed Analytics Skills" icon="calculator" href="/skills/computed">
  Correlations, factor exposures, DCF, portfolio optimization, Monte Carlo, and tearsheets.
</Card>