vortexa-claude-skills 1.0.0

package/commands/vortexa/init.md

@@ -0,0 +1,133 @@
+---
+name: vortexa:init
+description: Set up Vortexa analytics environment in the current project
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+<objective>
+Initialize the Vortexa analytics environment in the current project directory. Verifies the global install at ~/.claude/vortexa/, creates a local .env for API key management, sets up CLAUDE.md with context @-imports, verifies .gitignore protection, and validates the Python environment.
+</objective>
+
+<process>
+
+## Step 1: Verify Global Install
+
+Check that `~/.claude/vortexa/` exists and contains expected files:
+- `~/.claude/vortexa/VERSION` must exist
+- `~/.claude/vortexa/context/guardrails.md` must exist
+- `~/.claude/vortexa/lib/__init__.py` must exist
+- `~/.claude/commands/vortexa/cargo-flows.md` must exist
+
+If any are missing, tell the user:
+"Vortexa skills package is not installed or is incomplete. Run: npx @vortexa/claude-skills setup"
+Stop execution.
+
+If all present, read VERSION and display: "Vortexa skills v{version} detected."
+
+## Step 2: Create/Verify .env File
+
+Read the template from the global install: `~/.claude/vortexa/templates/.env.template`
+
+**If .env does NOT exist in the current directory:**
+- Create .env from the template content
+- Tell user: "Created .env file. Please add your Vortexa API key: edit .env and replace 'your_key_here' with your actual key."
+
+**If .env EXISTS:**
+- Read it and check if `VORTEXA_API_KEY` is present
+- If present and not `your_key_here`: "Vortexa API key detected in .env -- you're all set."
+- If present but still `your_key_here`: "Found .env but API key is still the placeholder. Please edit .env and add your real API key."
+- If VORTEXA_API_KEY line is missing: Append `VORTEXA_API_KEY=your_key_here` to the .env and tell user to fill it in.
+
+## Step 3: Verify .gitignore Protection
+
+Check if `.gitignore` exists in the project root.
+
+**If .gitignore does NOT exist:**
+- Create it with `.env` and `.env.*` entries
+- Tell user: "Created .gitignore to protect your API key from being committed."
+
+**If .gitignore EXISTS:**
+- Check if it contains `.env`
+- If YES: Good, no action needed
+- If NO: Append `.env` and `.env.*` to .gitignore
+- Tell user: "Updated .gitignore to protect your .env file."
+
+## Step 4: Create/Update Project CLAUDE.md
+
+**If no CLAUDE.md exists in the current directory:**
+Create a minimal one:
+```markdown
+# Project
+
+## Vortexa Analytics Context
+@~/.claude/vortexa/context/guardrails.md
+@~/.claude/vortexa/context/entity-resolution.md
+@~/.claude/vortexa/context/date-units.md
+```
+Tell user: "Created CLAUDE.md with Vortexa context imports."
+
+**If CLAUDE.md exists but has no Vortexa imports:**
+Check if the file contains `vortexa/context/guardrails.md`. If not, append:
+```markdown
+
+## Vortexa Analytics Context
+@~/.claude/vortexa/context/guardrails.md
+@~/.claude/vortexa/context/entity-resolution.md
+@~/.claude/vortexa/context/date-units.md
+```
+Tell user: "Added Vortexa context imports to existing CLAUDE.md."
+
+**If CLAUDE.md already has Vortexa imports:**
+Tell user: "CLAUDE.md already has Vortexa context configured."
+
+## Step 5: Check Python Environment
+
+Run each check and collect results:
+
+1. `python3 --version` (fall back to `python --version`): Require 3.10+
+2. `python3 -c "import vortexasdk; print(vortexasdk.__version__)"`: Check vortexasdk installed
+3. `python3 -c "import pandas; print(pandas.__version__)"`: Check pandas installed
+4. `python3 -c "import plotly; print(plotly.__version__)"`: Check plotly installed
+5. `python3 -c "from dotenv import load_dotenv; print('ok')"`: Check python-dotenv installed
+6. `python3 -c "import numpy; print(numpy.__version__)"`: Check numpy installed
+7. `python3 -c "import dateutil; print(dateutil.__version__)"`: Check python-dateutil installed
+
+For any missing package, collect it. At the end, if anything is missing, print:
+```
+Missing Python dependencies:
+  pip install vortexasdk pandas plotly python-dotenv numpy python-dateutil
+```
+
+If all present, print versions found. Do NOT block setup if anything is missing -- warn only.
+
+## Step 6: Verify Context Accessibility
+
+Read `~/.claude/vortexa/context/guardrails.md` (first 5 lines) to confirm file access works from the current directory.
+
+If read fails: "Warning: Cannot read context files from ~/.claude/vortexa/. Check file permissions."
+If read succeeds: "Context files accessible."
+
+## Step 7: Print Summary
+
+```
+Vortexa Analytics Environment Ready!
+
+  Package: v{version} (installed at ~/.claude/vortexa/)
+  API Key: {status}
+  Python: {version}
+  Dependencies: {all ok / missing list}
+  Context: {accessible / warning}
+  CLAUDE.md: {created / updated / already configured}
+
+  You're ready to go! Try:
+    /vortexa:cargo-flows crude exports from Saudi Arabia last month
+    /vortexa:explain what is the difference between loading_end and loading_state?
+```
+
+</process>

package/commands/vortexa/oow.md

@@ -0,0 +1,189 @@
+---
+name: vortexa:oow
+description: "Run oil-on-water breakdown by region using the CM-Authoritative methodology"
+argument-hint: "crude on water by shipping region, last 3 months"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Build an oil-on-water breakdown by region using the CM-Authoritative methodology: CargoMovements for authoritative OOW periods and quantities, VoyagesSearchEnriched for real-time vessel location enrichment. Uses `cargo_on_water_ts()` from lib/movements.py for data and `oow_area_chart()` from lib/visualization.py for stacked area visualization.
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+The following are automatically available -- do NOT re-read them:
+- context/guardrails.md -- NEVER/ALWAYS rules for all Vortexa API calls
+- context/entity-resolution.md -- How to resolve entity names to hex IDs
+- context/date-units.md -- Date parsing rules and unit defaults
+
+## Required Context (Read on demand)
+Read before processing the user's query:
+- context/cargo-movements.md -- CargoMovements parameters, activity filters, column naming
+- context/voyages.md -- VoyagesSearchEnriched parameters, event structure, location details
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## CM-Authoritative OOW -- MANDATORY
+
+The ONLY correct method for location-based OOW analysis is `cargo_on_water_ts()` from lib/movements.py.
+
+DO NOT use CTS `cargo_on_water_state` for this skill. CTS shows where cargo was LOADED FROM and GOING TO (origin/destination), NOT where it currently IS on the water.
+
+The CM-Authoritative pattern:
+1. CargoMovements with `cargo_on_water_state` for authoritative OOW periods and quantities
+2. VoyagesSearchEnriched for real-time vessel location (shipping_region from events)
+3. Join on cargo_movement_id (16-char truncated) to enrich CM cargoes with voyage location
+
+If the generated code imports CargoTimeSeries for the OOW skill, it is WRONG.
+
+## Step 1: Read Endpoint Context
+
+Read `context/cargo-movements.md` and `context/voyages.md` (both are needed -- CM for quantities, VSE for location).
+
+## Step 2: Parse the Query
+
+Analyze $ARGUMENTS and extract:
+
+- **Product**: typically crude, but any product group works
+- **Location layer**: `shipping_region_v2` (default), `region`, or `country`. Controls how granular the location breakdown is.
+- **Time range**: Apply date-units.md convention. Note: longer ranges = longer API queries (CM + VSE both queried).
+- **Unit**: commodity defaults (oil=b for OOW since it's absolute volume, not rate)
+- **Top-N**: how many regions to show in chart (default 8)
+- **Frequency**: for chart display resampling -- daily (default), weekly, monthly
+- **Exclude intra-country**: optional, default false for OOW
+
+## Step 3: Check for Missing Parameters
+
+Required (ask if missing):
+- **Product** -- MUST be specified
+- **Time range** -- MUST be specified
+
+Optional with smart defaults (mention in confirmation):
+- **Location layer**: default `shipping_region_v2`
+- **Unit**: default `b` (absolute barrels for OOW volumes)
+- **Top-N**: default 8
+- **Frequency**: default `daily`
+- **Exclude intra-country**: default false
+
+Ask one parameter at a time. Do NOT bulk-ask.
+
+## Step 4: Resolve Entity IDs
+
+Resolve product ID using `lib/entities.py`:
+1. Check `lib/aliases.json` for common shorthands
+2. Call `resolve_product(term, layer)` with the correct layer
+3. If multiple matches: present top 3 candidates. Ask user to pick. NEVER auto-correct.
+4. If zero matches: tell user the term wasn't found.
+
+No geography resolution needed -- OOW covers global flows; the location layer is applied during the CM+VSE join.
+
+Use `EntityCache()` from `lib/entities.py` for the session.
+
+## Step 5: Confirm Before Executing (MANDATORY)
+
+Present the complete parameter set:
+
+```
+Query: [restate the user's question]
+Analysis: Oil-on-water by region (CM-Authoritative)
+Data: CargoMovements (OOW periods) + VoyagesSearchEnriched (location)
+Product: [name (layer)]
+Time: [start datetime] -> [end datetime]
+Location level: [shipping_region_v2 / region / country]
+Unit: [unit] (absolute volume)
+Chart: Stacked area, Top [N] regions + Other
+Display frequency: [daily/weekly/monthly]
+
+Note: This query calls both CM and VSE endpoints -- may take 1-3 minutes for large date ranges.
+
+Confirm or adjust?
+```
+
+NEVER execute without confirmation. Wait for user response.
+
+## Step 6: Generate & Execute Code Artifact
+
+Generate a self-contained .py file using the data -> viz -> save pipeline:
+
+```python
+"""Vortexa OOW: {description}
+Generated by /vortexa:oow
+Date: {date}
+"""
+from datetime import datetime
+import os
+import sys; sys.path.insert(0, "lib")
+from entities import resolve_product, EntityCache
+from movements import cargo_on_water_ts
+from visualization import oow_area_chart
+
+# Entity Resolution
+cache = EntityCache()
+{product_resolution_code}
+
+# OOW by Region (CM-Authoritative)
+ts_wide = cargo_on_water_ts(
+    time_min=datetime({time_min}),
+    time_max=datetime({time_max}),
+    product={product_id},
+    unit="{unit}",
+    location_layer="{location_layer}",
+    exclude_intra_country={exclude_intra},
+    verbose=True,
+)
+
+print(ts_wide)
+
+# Chart
+fig = oow_area_chart(ts_wide, freq="{freq}", top_n={top_n}, title="{title}")
+
+os.makedirs("output", exist_ok=True)
+filepath = f"output/{slug}_oow_{datetime.now().strftime('%Y-%m-%d')}.html"
+fig.write_html(filepath, auto_open=True)
+print(f"Chart saved: {filepath}")
+
+# Export (uncomment to save)
+# ts_wide.to_csv(f"output/{slug}_oow_{datetime.now().strftime('%Y-%m-%d')}.csv")
+```
+
+After generating, ask: "Save as new file, or add to an existing notebook/script?" Default: new file.
+Run the code to get results.
+
+## Step 7: Present Results
+
+- Show the wide DataFrame (Top-N regions + Other + Total by date)
+- Row cap by display frequency: daily=30, weekly=52, monthly=24
+- If capped: "Showing first N of M rows"
+- One-line methodology footnote using CONFIRMED parameters:
+  ```
+  Methodology: CM-Authoritative OOW | CargoMovements (cargo_on_water_state) + VoyagesSearchEnriched (location) | {product} | {unit} | {location_layer} | Top {N}
+  ```
+  Use human-readable names for entity filters (not hex IDs).
+- File path to chart HTML
+- Offer: "Export to CSV?" and "Want a summary?"
+
+## Error Handling
+
+Report immediately in plain English, no auto-retry:
+
+- **401 Unauthorized**: "API key is invalid or expired. Run /vortexa:init to check your setup."
+- **500 Server Error**: "Vortexa API returned a server error. Try again in a few minutes."
+- **Timeout**: "Query timed out. Try narrowing the date range or reducing filters."
+- **Empty results / No cargo movements found**: "No cargo movements found for this query. Try broadening the product filter or date range."
+- **Entity not found**: "The term '{term}' returned no matches. Check spelling or try a broader term."
+- **Multiple entity matches**: "{n} matches found for '{term}': [list]. Which did you mean?"
+- **Long query warning**: Already included in confirmation step (1-3 min for large date ranges).
+
+Never auto-retry. Never self-correct. Report the error and let the user decide.
+
+</process>

package/commands/vortexa/seasonal.md

@@ -0,0 +1,185 @@
+---
+name: vortexa:seasonal
+description: "Run multi-year seasonal pattern analysis for cargo flows with min/max/avg bands and forward-looking current year"
+argument-hint: "crude exports from Middle East, 2020-2026, monthly"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Run multi-year seasonal pattern analysis using CargoTimeSeries, producing a seasonal overlay chart with historical min/max range band, average line, last year, and forward-looking current year segment. Uses `complete_seasonal_flows()` and `seasonal_charts()` from lib/seasonal.py for data, and `seasonal_chart()` from lib/visualization.py for Plotly output.
+</objective>
+
+<execution_context>
+## Pre-loaded Context (via CLAUDE.md @imports)
+The following are automatically available -- do NOT re-read them:
+- context/guardrails.md -- NEVER/ALWAYS rules for all Vortexa API calls
+- context/entity-resolution.md -- How to resolve entity names to hex IDs
+- context/date-units.md -- Date parsing rules and unit defaults
+
+## Required Context (Read on demand)
+Read before processing the user's query:
+- context/cargo-movements.md -- CTS parameters, activity filter rules
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## CRITICAL PITFALLS
+
+- `complete_seasonal_flows()` handles the 4-year API block limit automatically via `get_search_blocks()`. Do NOT manually split date ranges.
+- `seasonal_charts()` filters out Feb 29 automatically. The viz function handles "Current year" column filtering (non-empty values only).
+- Minimum 3 years for meaningful min/max/avg bands. Warn if user requests < 3 years: "Seasonal analysis with fewer than 3 years produces unreliable min/max bands. Consider extending the range."
+
+## Step 1: Read Endpoint Context
+
+Read `context/cargo-movements.md` for CTS parameters and activity filter rules.
+
+## Step 2: Parse the Query
+
+Analyze $ARGUMENTS and extract:
+
+- **Product**: commodity (crude, LNG, clean products, etc.)
+- **Geography**: origin and/or destination
+- **Activity**: movement stage
+  - exports / shipped out / departures = `loading_end`
+  - imports / arrivals / received = `unloading_start`
+  - on the water / afloat / in transit = `cargo_on_water_state`
+  - floating storage = `storing_state`
+- **Year range**: start year to current year. "2020-2026" or "last 5 years" = start year 5 years ago. MINIMUM 3 years for meaningful seasonal pattern.
+- **Unit**: commodity defaults (oil=bpd, LNG=t, LPG=t)
+- **Frequency**: `day` or `month` -- these are the two supported by `seasonal_charts()`. Default to `month` if not specified. Do NOT ask -- just default and mention in confirmation.
+- **Chart type**: multi-year overlay line chart (default). User can request "area chart" override.
+- **Moving average**: optional, if user says "7-day MA" or "30-day smoothing"
+
+## Step 3: Check for Missing Parameters (ASK before confirming)
+
+Required (ask if missing):
+- **Product** -- MUST be specified
+- **Activity** -- MUST be specified. If direction ambiguous, ask: "exports from origin or imports to destination?"
+- **Year range** -- MUST be specified. If user says just "seasonal", ask: "What year range should I analyze? e.g., 2020-2026"
+
+Optional but commonly specified:
+- **Geography** -- origin and/or destination (optional)
+
+Ask one parameter at a time. Do NOT bulk-ask.
+
+## Step 4: Resolve Entity IDs
+
+For each entity mentioned (origin, destination, product):
+1. Check `lib/aliases.json` for common shorthands (ME, AG, USG, ARA, etc.)
+2. Call `lib/entities.py` resolve functions with the correct entity type and layer:
+   - `resolve_geography(term, layer)` for origins/destinations
+   - `resolve_product(term, layer)` for products
+   - `resolve(term, entity_type, layer, cache)` for the unified resolver with caching
+3. If multiple matches: present top 3 candidates. Ask user to pick. NEVER auto-correct.
+4. If zero matches: tell user the term wasn't found, suggest checking spelling or trying a broader term.
+
+Use `EntityCache()` from `lib/entities.py` for the session to avoid re-resolving the same entities.
+
+## Step 5: Confirm Before Executing (MANDATORY)
+
+Present the complete parameter set:
+
+```
+Query: [restate the user's question]
+Analysis: Seasonal pattern
+Endpoint: CargoTimeSeries (via complete_seasonal_flows)
+Activity: [filter_activity value] ([user's term])
+Origin: [name (layer)] or "not specified"
+Destination: [name (layer)] or "not specified"
+Product: [name (layer)]
+Year range: [start_year] to [current_year] ([N] years)
+Frequency: [day/month]
+Unit: [unit] ([reason])
+Chart: Multi-year overlay with min/max band, average, last year, current year
+Intra: [exclude_intra_country for exports/imports, all otherwise]
+
+Confirm or adjust?
+```
+
+NEVER execute without confirmation. Wait for user response.
+
+## Step 6: Generate & Execute Code Artifact
+
+Generate a self-contained .py file using the data -> viz -> save pipeline:
+
+```python
+"""Vortexa Seasonal: {description}
+Generated by /vortexa:seasonal
+Date: {date}
+"""
+from datetime import datetime
+import os
+import sys; sys.path.insert(0, "lib")
+from entities import resolve_geography, resolve_product, EntityCache
+from seasonal import complete_seasonal_flows
+from visualization import seasonal_chart
+
+# Entity Resolution
+cache = EntityCache()
+{entity_resolution_code}
+
+# Seasonal Analysis
+seasonal_df = complete_seasonal_flows(
+    start_y={start_year}, start_m=1, start_d=1,
+    product_ids=[{product_id}], product_ids_excl=[],
+    freq="{frequency}",
+    unit="{unit}",
+    activity="{activity}",
+    origin_ids=[{origin_ids}], origin_ids_excl=[],
+    destination_ids=[{destination_ids}], destination_ids_excl=[],
+    ma_period={ma_period_or_None},
+    exclude_intra={True_or_False},
+)
+
+print(seasonal_df)
+
+# Chart
+fig = seasonal_chart(seasonal_df, title="{title}", y_label="{unit_label}")
+
+os.makedirs("output", exist_ok=True)
+filepath = f"output/{slug}_seasonal_{datetime.now().strftime('%Y-%m-%d')}.html"
+fig.write_html(filepath, auto_open=True)
+print(f"Chart saved: {filepath}")
+
+# Export (uncomment to save)
+# seasonal_df.to_csv(f"output/{slug}_seasonal_{datetime.now().strftime('%Y-%m-%d')}.csv", index=False)
+```
+
+After generating, ask: "Save as new file, or add to an existing notebook/script?" Default: new file.
+Run the code to get results.
+
+## Step 7: Present Results
+
+- Show full seasonal DataFrame (12-365 rows depending on freq)
+- One-line methodology footnote using CONFIRMED parameters:
+  ```
+  Methodology: CargoTimeSeries (seasonal) | {activity} | {key filters} | {freq} | {unit} | {start_year}-{current_year}
+  ```
+  Use human-readable names for entity filters (not hex IDs).
+- File path to chart HTML
+- Offer: "Export to CSV?" and "Want a summary of these results?"
+
+## Error Handling
+
+Report immediately in plain English, no auto-retry:
+
+- **401 Unauthorized**: "API key is invalid or expired. Run /vortexa:init to check your setup."
+- **500 Server Error**: "Vortexa API returned a server error. Try again in a few minutes."
+- **Timeout**: "Query timed out. Try narrowing the date range or reducing filters."
+- **Empty results**: "No data found for this query. Check that the entity names, date range, and filters are correct."
+- **Entity not found**: "The term '{term}' returned no matches. Check spelling or try a broader term."
+- **Multiple entity matches**: "{n} matches found for '{term}': [list]. Which did you mean?"
+- **< 3 years**: "Seasonal analysis with fewer than 3 years produces unreliable min/max bands. Consider extending the range."
+
+Never auto-retry. Never self-correct. Report the error and let the user decide.
+
+</process>