# options-analysis

Este proyecto se distribuye bajo la licencia GNU General Public License,
version 3 o posterior. Consulta [`LICENSE`](LICENSE).

MCP local para consultar cadenas de opciones y calcular exposicion gamma estimada
para ETFs y otros subyacentes con opciones liquidas.

El alcance, los supuestos y los criterios de aceptacion se mantienen en
[`PLAN.md`](PLAN.md).

## Estructura

```text
src/options_mcp/
|-- domain/       # Modelos y calculos puros
|-- providers/    # Fuentes externas de cadenas y precios
|-- services/     # Casos de uso de cadena, gamma y proxies
|-- storage/      # Cache local
`-- tools/        # Adaptadores expuestos por MCP
tests/            # Pruebas unitarias y fixtures sin red
../var/options-analysis/
```

## Herramientas

- `get_options_expirations`
- `get_options_chain`
- `get_gamma_exposure`
- `get_gamma_snapshot`
- `calculate_proxy_gamma`
- `get_proxy_definition`
- `calculate_named_proxy_gamma`
- `compare_gamma_with_price`
- `audit_gamma_history`

La fuente inicial es Yahoo Finance mediante `yfinance`. Los datos pueden estar
retrasados y el open interest puede corresponder a la sesion anterior.

`GEX` y `proxy_gamma` son estimaciones derivadas, no posiciones observadas de
dealers. El signo depende de la convencion solicitada y siempre se devuelve
junto con los supuestos y advertencias.

## Ejemplo

```json
{
  "target_symbol": "IUVL",
  "components": [
    {"symbol": "QQQ", "weight": 0.40, "reason": "technology proxy"},
    {"symbol": "IWD", "weight": 0.60, "reason": "value proxy"}
  ]
}
```

Los pesos son una hipotesis de proxy y deben validarse contra las tenencias
vigentes del emisor del ETF.

Las definiciones durables pueden proporcionarse mediante
`OPTIONS_MCP_PROXY_DEFINITIONS_PATH`; el runtime por defecto se configura
mediante `OPTIONS_DATA_ROOT` y no se incluyen datos de mercado ni instantaneas
historicas en el repositorio.

## Fuentes publicas

- Yahoo Finance: fuente automatizada inicial para cadenas retrasadas.
- Cboe delayed quotes: validacion manual de cotizaciones y cadenas cuando la
  pagina publica esta disponible.
- Nasdaq Option Chain: validacion optativa de vencimiento, spot y contratos
  comunes mediante `tests/test_secondary_validation.py`.
- OCC: referencia oficial de open interest y estadisticas diarias.

Estas fuentes no publican una posicion observada de dealers. El MCP calcula
gamma y GEX a partir de los campos disponibles y conserva la fecha, proveedor,
calidad y supuestos del calculo.

## Historico diario

El repositorio no incluye una watchlist ni datos de mercado. Para recoger una
observacion manual, proporciona una watchlist externa o simbolos directamente:

```bash
uv run options-gamma-snapshot --symbols SPY QQQ IWM
```

La salida se guarda como `OPTIONS_DATA_ROOT/options_history/GAMMA_SNAPSHOT_YYYY-MM-DD.json`.
La fecha del archivo usa el calendario de `America/Montevideo`, igual que el
cron; el archivo es idempotente por fecha y conserva errores individuales de
simbolos.
La tarea del repositorio `cron/daily/2115_options_gamma_snapshot.md` ejecuta el
recolector diariamente a las 21:15 en `America/Montevideo`.

Para auditar la cobertura acumulada sin consultar la red:

```bash
uv run options-gamma-history-audit
```

El auditor informa la primera y ultima observacion por simbolo y el estado de
preparacion para cada horizonte diario. Tambien esta disponible como la
herramienta MCP `audit_gamma_history`.

`compare_gamma_with_price` usa solo snapshots persistidos y admite `next_day`,
`short_term` (cinco observaciones diarias) y `medium_term` (veinte
observaciones diarias). Devuelve `insufficient_data` hasta alcanzar el minimo
requerido para el horizonte. `intraday` devuelve `unsupported_horizon` porque
el recolector actual solo persiste una observacion diaria. La comparacion es
descriptiva y no implica causalidad ni constituye una senal.

## Smoke test optativo

La suite normal no usa red. Para validar la disponibilidad de Yahoo y una cadena
real de `SPY`, ejecutar:

```bash
OPTIONS_MCP_LIVE_TESTS=1 uv run pytest tests/test_live_smoke.py -q
```