natbag

What this skill does

# Natbag — Ben Gurion Airport Flights

Live flight data, destination weather, and historical analysis for Ben Gurion Airport (TLV/LLBG). Data from Israel's open data portal (data.gov.il), covering a rolling ~3-day window.

## Query Workflow

Show step progress to the user as each step runs:

1. **Step 1: Fetching flights** — run `query_flights.py` with appropriate filters
2. **Step 2: Getting weather** — fetch destination weather (for single flight or when relevant)
3. **Step 3: Checking history** — query historical stats (only if user asks about delays/patterns)

Not all steps run every time. Skip steps that aren't relevant to the query:
- Departure board → Step 1 only
- "Is my flight on time?" → Step 1 + Step 2
- "Are El Al flights usually delayed?" → Step 3 only
- "Next flight to London with weather" → Step 1 + Step 2

Display each step label before running it so the user sees progress.

## Data Sources

1. **Live flights**: data.gov.il API — departures, arrivals, status, gates
2. **Weather**: Open-Meteo API — free, no API key — current conditions at destination
3. **Historical**: Local SQLite DB at `~/.natbag/flights.db` — accumulated via daily snapshots

## Daily Snapshot (Automatic)

A PreToolUse hook runs `snapshot.py` automatically whenever this skill is invoked. On first run, it copies the shipped `data/db.db` (airlines + airports) to `~/.natbag/flights.db`, adds the flights table, and fetches live flights. On subsequent runs, it self-guards: skips if it already ran today or if the user disabled snapshots.

After the first invocation, inform the user: "Natbag initialized. Flight data and IATA reference loaded. Historical data will accumulate automatically on each use. To disable daily snapshots, set `daily_snapshot: false` in `~/.natbag/config.json`."

Replace `SKILL_DIR` with the resolved path to this skill's directory (where this SKILL.md lives).

## Querying Live Flights

Use the composable `query_flights.py` script for live API queries:

```bash
python3 SKILL_DIR/scripts/query_flights.py --departures --date YYYY-MM-DD
python3 SKILL_DIR/scripts/query_flights.py --arrivals --date YYYY-MM-DD --upcoming
python3 SKILL_DIR/scripts/query_flights.py --arrivals --airline LY --date YYYY-MM-DD
python3 SKILL_DIR/scripts/query_flights.py --destination JFK --upcoming
python3 SKILL_DIR/scripts/query_flights.py --flight LY001
python3 SKILL_DIR/scripts/query_flights.py --status DELAYED
python3 SKILL_DIR/scripts/query_flights.py --search "London"
```

Flags can be combined. All scripts return JSON — Claude handles formatting for the user.

> **CRITICAL: Always use `--date YYYY-MM-DD` when counting or listing flights for a specific day.** Without it, the API returns a rolling ~3-day window, inflating counts. When `--date` is set, the script automatically pages through all API results before filtering, so counts are accurate. Replace `YYYY-MM-DD` with the actual date (e.g., `2026-04-03`).

For raw API access, use `curl` directly — see [references/api.md](references/api.md) for filter patterns.

### Resolving Ambiguous Queries

The local DB at `~/.natbag/flights.db` includes `airlines` and `airports` tables (from [data/db.db](data/db.db)) for resolving user input:

- **Airline name → code**: User says "El Al" or "Wizz Air" → look up IATA code:
  ```bash
  python3 SKILL_DIR/scripts/query_history.py --airline-lookup "El Al"
  ```
- **Multi-airport cities**: User says "flights to London" → find all London airports:
  ```bash
  python3 SKILL_DIR/scripts/query_history.py --airports London
  ```
  Then query each relevant code (LHR, LGW, STN, LTN, LCY) or use full-text search `--search London`.
- **Partial flight numbers**: User says "flight 001" without airline → use `--search 001` to match across all airlines.
- **Hebrew city names**: User types "לונדון" → use `--search לונדון`. Supports partial prefix matching (e.g., `--search לונ` finds לונדון).
- **Empty results**: If a filtered query returns 0 results, try broadening: drop the direction filter, switch from exact filter to `--search`, or check if the city has multiple airport codes.

### Output Fields

`query_flights.py` returns clean JSON with these fields:

| Field | Content |
|-------|---------|
| flight | Airline code + number (e.g., "LY 1008") |
| airline | Airline full name |
| date | Scheduled date (YYYY-MM-DD) |
| time | Scheduled time (HH:MM) |
| updated_time | Actual/updated time (compare with time to detect delays) |
| direction | "departure" or "arrival" |
| city / city_he | City name (English / Hebrew) |
| country / country_he | Country (English / Hebrew) |
| airport | IATA airport code |
| terminal | Terminal number |
| gate | Gate assignment (null if unassigned) |
| checkin_zone | Check-in zone (null if N/A) |
| status / status_he | Flight status (English / Hebrew) |

Full field reference and curl examples: see [references/api.md](references/api.md).
For complete output examples: see [examples/](examples/) (departure board, single flight, historical stats).

## Destination Weather

After showing flight info, offer weather at the destination. Uses Open-Meteo (free, no key).

**Steps:**
1. Get the `city` field from the flight JSON (e.g., "BERLIN")
2. Geocode: `curl -s 'https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1'`
3. Extract `latitude` and `longitude` from `results[0]`
4. Fetch weather: `curl -s 'https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true'`
5. Display: temperature, weather description, wind speed

Open-Meteo returns the most populated city match, so "Berlin" → Berlin Germany (not Berlin NH). Tested and correct for all TLV route cities.

Weather codes: 0=Clear, 1-3=Partly cloudy, 45/48=Fog, 51-55=Drizzle, 61-65=Rain, 71-75=Snow, 80-82=Showers, 95=Thunderstorm.

## Historical Analysis

Use the composable `query_history.py` script for historical queries:

```bash
python3 SKILL_DIR/scripts/query_history.py --coverage                    # data range
python3 SKILL_DIR/scripts/query_history.py --ontime                      # all airlines
python3 SKILL_DIR/scripts/query_history.py --ontime --airline LY          # specific airline
python3 SKILL_DIR/scripts/query_history.py --delays --route JFK           # delays by route
python3 SKILL_DIR/scripts/query_history.py --cancellations                # cancellation rates
python3 SKILL_DIR/scripts/query_history.py --airports London              # multi-airport lookup
python3 SKILL_DIR/scripts/query_history.py --airline-lookup "Wizz"        # airline code lookup
```

Add `--days N` to change the lookback period (default: 30). All output is JSON.

### Flight Change History

Track how flights evolve over time — status changes, time updates, gate reassignments:

```bash
python3 SKILL_DIR/scripts/query_history.py --flight-history LY001         # all changes for a flight
python3 SKILL_DIR/scripts/query_history.py --delay-patterns               # when are delays announced?
python3 SKILL_DIR/scripts/query_history.py --delay-patterns --airline LY   # per-airline patterns
python3 SKILL_DIR/scripts/query_history.py --status-transitions            # status paths (e.g., DELAYED -> CANCELED)
```

Change history accumulates from version 1.1.0 onward. Older flights (captured before the upgrade) will not have change records.

Use `--flight-history` when the user asks about a specific flight's progression. Use `--delay-patterns` when they ask about how early delays are typically announced. Use `--status-transitions` when they ask about flights that were delayed then cancelled, or other status paths.

If the database doesn't exist or is empty, inform the user: "Historical data accumulates from install date via daily snapshots. Run `python3 SKILL_DIR/scripts/snapshot.py --force` to start collecting now."

For custom SQL queries, use `sqlite3 ~/.natbag/flights.db` directly. The DB also has `airlines`, `airports`, and `flight_changes` tables for JOINs. See [references/api.md](references/api.md) for query pattern