vortexa-claude-skills 1.0.0

package/commands/vortexa/breakdown.md

@@ -0,0 +1,294 @@
+---
+name: vortexa:breakdown
+description: "Break down cargo flows by origin, destination, product, vessel class, or other dimensions"
+argument-hint: "crude exports by destination country, monthly, last year"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Break down cargo flow timeseries by any supported dimension (geography, product, vessel, commercial) using CargoTimeSeries split queries. Produce wide-format DataFrames with Top-N bucketing for clean, readable breakdown results.
+</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 -- Full timeseries_property values, CTS parameters, activity filters
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## Step 1: Read Endpoint Context
+
+Read `context/cargo-movements.md` for the full list of `timeseries_property` values, activity filter rules, and CTS parameters.
+
+## Step 2: Parse the Query
+
+Analyze $ARGUMENTS and extract:
+
+- **Dimension**: The "by X" phrase. Map to `timeseries_property` using the table below.
+- **Product**: What commodity? (crude, LNG, clean products, etc.)
+- **Geography**: Origin and/or destination filters (country, port, region, shipping_region_v2)
+- **Activity**: What 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`
+  - loadings / loading at port = `loading_state`
+- **Time range**: Apply date-units.md calendar/trailing convention
+- **Unit**: Apply date-units.md commodity defaults (oil=bpd, LNG=t, LPG=t)
+- **Frequency**: daily/weekly/monthly -- note if user specified or not
+- **Top-N**: Look for "top 5", "top 20", "show top 3", etc. Default 10 if not specified.
+
+### Dimension Mapping Table
+
+**Geographic dimensions:**
+
+| User Says | timeseries_property |
+|---|---|
+| "by origin country", "by source country" | `origin_country` |
+| "by destination country", "by receiving country" | `destination_country` |
+| "by origin port", "by loading port" | `origin_port` |
+| "by destination port", "by discharge port" | `destination_port` |
+| "by origin region" | `origin_region` |
+| "by destination region" | `destination_region` |
+| "by origin shipping region" | `origin_shipping_region_v2` |
+| "by destination shipping region" | `destination_shipping_region_v2` |
+| "by origin terminal" | `origin_terminal` |
+| "by destination terminal" | `destination_terminal` |
+| "by storage country" (floating storage) | `storage_location_country` |
+| "by storage region" (floating storage) | `storage_location_region` |
+| "by storage shipping region" (floating storage) | `storage_location_shipping_region_v2` |
+
+**Product dimensions:**
+
+| User Says | timeseries_property |
+|---|---|
+| "by product group", "by product type" | `product_group` |
+| "by product sub-group" | `product_group_product` |
+| "by product category" | `product_category` |
+| "by product grade", "by grade", "by crude grade" | `product_grade` |
+
+**Vessel dimensions:**
+
+| User Says | timeseries_property |
+|---|---|
+| "by vessel type" | `vessel_class_group` |
+| "by vessel class" | `vessel_class_granular` |
+| "by vessel class (coarse)" | `vessel_class_coarse` |
+| "by flag", "by flag state" | `vessel_flag` |
+
+**Commercial dimensions:**
+
+| User Says | timeseries_property |
+|---|---|
+| "by shipper" | `shipper` |
+| "by consignee" | `consignee` |
+| "by buyer" | `load_buyer` |
+| "by seller" | `load_seller` |
+| "by contract type" (spot vs term) | `contract_type` |
+| "by delivery method" (FOB, DES, etc.) | `delivery_method` |
+
+**Ambiguity defaults:**
+- "by destination" without specifying level -> default to `destination_country`. Mention: "I'll break down by destination country. If you want port/region/shipping region level, let me know."
+- "by origin" without specifying level -> default to `origin_country`. Same note.
+- "by product" without specifying level -> default to `product_group`.
+
+**Not a CTS split property:**
+- "by effective controller", "by charterer", "by time charterer" -- these are NOT available as CTS `timeseries_property` values. If the user requests one, explain: "Corporate breakdowns (effective controller, charterer) are not available as CTS split dimensions. You can use `/vortexa:custom` to query CargoMovements search with a groupby on the corporate entity column instead."
+
+## Step 3: Check for Missing Parameters (ASK before confirming)
+
+Ask targeted questions BEFORE the confirmation step. Never default silently.
+
+**Required (ask if missing):**
+- **Dimension** -- MUST be specified. If user says "breakdown" without "by X", ask: "What dimension should I break down by? e.g., destination country, product group, vessel class"
+- **Product** -- MUST be specified. Ask if missing.
+- **Activity** -- MUST be specified. If direction ambiguous, ask: "exports from origin or imports to destination?"
+- **Time range** -- MUST be specified. Ask if missing. Do NOT default to "last 3 months."
+
+**Ask if not specified:**
+- **Frequency** -- Ask if not determinable from query context.
+- **Unit** -- Ask if not obvious from commodity (oil=bpd, LNG=t, LPG=t).
+
+Ask one parameter at a time. Do NOT ask all missing params in a bulk dump.
+
+## 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 including the split dimension:
+
+```
+Query: [restate the user's question]
+Endpoint: CargoTimeSeries (split)
+Activity: [filter_activity value] ([user's term])
+Split by: [timeseries_property value] ([user's term])
+Top N: [N] categories + "Other"
+Origin: [name (layer)] or "not specified"
+Destination: [name (layer)] or "not specified"
+Product: [name (layer)]
+Time: [start datetime] -> [end datetime] ([interpretation])
+Unit: [unit] ([reason])
+Frequency: [value]
+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
+
+**Primary path** -- use `flows_time_series_split()` from `lib/timeseries.py`:
+
+```python
+"""Vortexa Breakdown: {description}
+Generated by /vortexa:breakdown
+Date: {date}
+"""
+from datetime import datetime
+import sys; sys.path.insert(0, "lib")
+from entities import resolve_geography, resolve_product, EntityCache
+from timeseries import flows_time_series_split
+
+# Entity Resolution
+cache = EntityCache()
+{entity_resolution_code}
+
+# Query
+full_df, plot_df = flows_time_series_split(
+    time_min=..., time_max=...,
+    activity=...,
+    split_property=...,
+    products=[...],
+    origins=[...],
+    destinations=[...],
+    unit=...,
+    frequency=...,
+    top_n=N,
+)
+
+print(plot_df)
+
+# Chart
+from visualization import flow_split_bars
+
+fig = flow_split_bars(plot_df.reset_index(), title="{title}", y_label="{unit_label}")
+
+import os
+os.makedirs("output", exist_ok=True)
+filepath = f"output/{slug}_breakdown_{datetime.now().strftime('%Y-%m-%d')}.html"
+fig.write_html(filepath, auto_open=True)
+print(f"Chart saved: {filepath}")
+
+# Export (uncomment to save)
+# plot_df.to_csv("output/{description}_{date}.csv")
+```
+
+`flows_time_series_split()` returns two DataFrames: `full_df` (all categories, daily resolution) and `plot_df` (Top-N + Other, resampled to requested frequency). Use `plot_df` for display.
+
+**Fallback path** -- if `flows_time_series_split` doesn't support a specific parameter combination, use `cargo_timeseries_split()` + `top_n_with_other()`:
+
+```python
+from timeseries import cargo_timeseries_split
+from utils import top_n_with_other
+
+df = cargo_timeseries_split(
+    time_min=..., time_max=...,
+    activity=..., split_property=...,
+    products=[...], origins=[...], destinations=[...],
+    unit=..., frequency=...,
+)
+df = top_n_with_other(df, n=N)
+```
+
+After generating:
+- Ask user: "Save as new file, or add to an existing notebook/script?" Default: new file.
+- If new file: create `vortexa_breakdown_{slug}.py` in project directory.
+- Run the generated code to get results.
+
+## Step 7: Present Results
+
+- Show chart path: "Stacked bar chart saved to output/{slug}_breakdown_{date}.html and opened in browser"
+- Show a preview of the wide-format DataFrame with row cap by frequency:
+  - daily: 30 rows
+  - weekly: 52 rows
+  - monthly: 24 rows
+  - yearly: all rows
+- If capped: "Showing first N of M rows"
+- List the categories shown: "Columns: Saudi Arabia, China, India, ... Other (aggregating 15 smaller categories)"
+- Show row count and date range
+- File path to generated code artifact
+- Offer: "Export to CSV?" and "Want a summary of these results?"
+
+After the DataFrame preview and before the export offer, show a one-line methodology footnote using the CONFIRMED parameters from Step 5:
+```
+Methodology: {Endpoint} (split) | {activity} | timeseries_property={dimension} | {key filters} | {frequency} | {unit} | Top {N}
+```
+Example: `Methodology: CargoTimeSeries (split) | loading_end | timeseries_property=destination_country | filter_products=[Crude & Condensates] | monthly | bpd | Top 10`
+
+Use human-readable names for entity filters (not hex IDs).
+
+If user says yes to CSV: ask where to save, default `./output/{description}_{date}.csv`, create `output/` directory if needed.
+
+## Step 8: Summary (if triggered)
+
+**Smart trigger:** If the user's query contains "analyze", "summarize", "explain results", "what does this show", or "key findings" -- generate the summary automatically.
+
+**Post-query offer:** After showing results, always offer: "Want a summary of these results?"
+
+**Brief summary (default):**
+Analyze the DataFrame and produce 3-5 bullet points:
+- Top 3-5 contributors by volume with percentages of total
+- Period-over-period change if comparable time periods exist
+- Notable outliers: spikes, drops, record values, trend reversals
+- Each bullet includes specific numbers, not vague descriptions
+
+**Extended summary (if user requests "detailed summary" or "full analysis"):**
+- 100-200 word narrative paragraph in market commentary style
+- Includes everything from brief plus trend descriptions and broader context
+
+After showing the summary, offer: "Save this summary to a .md file?"
+If yes: create `output/{description}_summary_{date}.md`
+
+## 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?"
+- **Unsupported dimension**: "'{dimension}' is not available as a CTS split dimension. [suggest alternative approach]"
+
+Never auto-retry. Never self-correct. Report the error and let the user decide.
+
+</process>

package/commands/vortexa/cargo-flows.md

@@ -0,0 +1,247 @@
+---
+name: vortexa:cargo-flows
+description: "Query cargo flows, exports, imports, and timeseries from the Vortexa API"
+argument-hint: "How much crude oil moved from Middle East to China last quarter?"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Translate natural language cargo flow questions into correct Vortexa API calls using CargoTimeSeries (aggregate volumes) or CargoMovements search (individual cargoes). Generate re-runnable Python code artifacts with transparent filter confirmation.
+</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 -- Full parameter reference, column names, filter options, code examples
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+
+## Step 1: Read Endpoint Context
+
+Read `context/cargo-movements.md` for the full parameter reference, activity filter rules, column naming convention, breakdown properties, and worked examples.
+
+## Step 2: Parse the Query
+
+Analyze $ARGUMENTS and extract:
+- **Product**: What commodity? (crude, LNG, clean products, etc.)
+- **Geography**: Origin and/or destination? What layer? (country, port, region, shipping_region_v2)
+- **Activity**: What 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`
+  - loadings / loading at port = `loading_state`
+- **Time range**: Apply date-units.md calendar/trailing convention
+- **Unit**: Apply date-units.md commodity defaults (oil=bpd, LNG=t, LPG=t)
+- **Frequency**: daily/weekly/monthly -- note if user specified or not
+- **Additional filters**: vessel class, intra_movements, waypoints, corporate entities, etc.
+
+## Step 3: Check for Breakdown Redirect
+
+If the query contains a dimension phrase -- "by origin", "by destination", "by product", "by vessel class", "by grade", "by flag", "split by", "breakdown by", "broken down by" -- this is a breakdown query.
+
+**Exclude frequency phrases:** "by month", "by week", "by day", "by quarter", "by year", "monthly", "weekly", "daily" are NOT dimension phrases. These specify frequency, not a split dimension.
+
+**Trigger rule:** "by" + a DIMENSION word (country, port, region, product, vessel, class, grade, flag, origin, destination, shipper, consignee, type, terminal). NOT "by" + a TIME word (month, week, day, year, quarter).
+
+If a dimension phrase is detected, suggest:
+"This looks like a breakdown query. Try: `/vortexa:breakdown {restate the full query}` for split analysis with Top-N bucketing and wide-format DataFrames."
+
+If the user explicitly wants the basic aggregate query without breakdown, continue to Step 4.
+
+## Step 4: Route -- CargoTimeSeries or CargoMovements.search?
+
+Use signal words to determine the endpoint:
+
+**CargoTimeSeries** (aggregate volumes over time) -- DEFAULT if ambiguous:
+- Signal words: "how much", "total", "trend", "monthly", "weekly", "bpd", "chart", "exports", "imports", "timeseries", "volumes", "flow", "by origin", "by destination", "breakdown"
+
+**CargoMovements.search** (individual cargo records):
+- Signal words: "list cargoes", "which shipments", "specific vessel", "cargo details", "show me the movements", "individual", "cargo records"
+
+If still ambiguous after checking signal words, ask:
+"Are you looking for aggregate volume trends or a list of individual cargo records?"
+
+## Step 5: Check for Missing Parameters
+
+Ask targeted questions BEFORE the confirmation step. Never default silently.
+
+**For CargoTimeSeries queries, ALL of these must be decided:**
+- Product -- MUST be specified. Ask if missing.
+- Activity -- MUST be specified. If direction ambiguous, ask: "exports from origin or imports to destination?"
+- Time range -- MUST be specified. Ask if missing. Do NOT default to "last 3 months."
+- Frequency -- Ask if not specified and not determinable from query context.
+- Unit -- Ask if not obvious from commodity (oil=bpd, LNG=t, LPG=t).
+- Geography -- optional but commonly specified.
+
+**For CargoMovements.search queries:**
+- Time range -- MUST be specified.
+- At least one filter: product, origin, destination, or vessel.
+
+Ask one parameter at a time. Do NOT ask all missing params in a bulk dump. Do NOT propose a concrete interpretation and ask "is this right?"
+
+## Step 6: 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 with name, layer, and parent context. Ask user to pick. NEVER auto-correct, even for single matches that look obvious.
+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 7: Confirm Before Executing (MANDATORY)
+
+Present the complete parameter set:
+
+```
+Query: [restate the user's question]
+Endpoint: CargoTimeSeries / CargoMovements.search
+Activity: [filter_activity value] ([user's term])
+Origin: [name (layer)] or "not specified"
+Destination: [name (layer)] or "not specified"
+Product: [name (layer)]
+Time: [start datetime] -> [end datetime] ([interpretation])
+Unit: [unit] ([reason])
+Frequency: [value] (CTS only)
+Intra: [exclude_intra_country for exports/imports, all otherwise]
+Additional: [any other filters]
+
+Confirm or adjust?
+```
+
+NEVER execute without confirmation. Wait for user response.
+
+## Step 8: Determine Execution Mode
+
+Choose the code generation approach:
+
+**Mode 1 -- Pre-built function** (when query matches a lib/ pattern):
+- Aggregate CTS query -> `cargo_timeseries_split()` from `lib/timeseries.py`
+- CTS with split/breakdown -> `flows_time_series_split()` from `lib/timeseries.py`
+- These functions handle parsing, pivoting, and Top-N automatically.
+
+**Mode 2 -- Custom SDK code** (when no pre-built function fits):
+- CM.search always uses Mode 2 (no pre-built wrapper exists).
+- Write raw SDK code using `context/cargo-movements.md` as reference.
+- Add comment: `# Custom query -- built from Vortexa API documentation`
+
+**Mode 3 -- Code-aware** (when user references an existing file):
+- If user says "add this to my analysis.py" or similar, read the file first.
+- Extend or fix the existing code using context docs.
+- Preserve the user's code style and structure.
+
+## Step 9: Generate & Execute Code Artifact
+
+Write a self-contained `.py` file:
+
+```python
+"""Vortexa Query: {description}
+Generated by /vortexa:cargo-flows
+Date: {date}
+"""
+from datetime import datetime
+import sys; sys.path.insert(0, "lib")
+from entities import resolve_geography, resolve_product, EntityCache
+# ... imports based on execution mode
+
+# Entity Resolution
+cache = EntityCache()
+{entity_resolution_code}
+
+# Query Parameters (confirmed by user)
+{parameter_setup}
+
+# Execute Query
+{api_call_code}
+
+# Format Results
+{column_renaming_using_rename_cm_columns_or_inline}
+{display_code}
+
+# Export (uncomment to save)
+# df.to_csv("output/{description}_{date}.csv", index=False)
+```
+
+After generating:
+- Ask user: "Save as new file, or add to an existing notebook/script?" Default: new file.
+- If new file: create `vortexa_query_{slug}.py` in project directory.
+- Run the generated code to get results.
+
+## Step 10: Present Results
+
+Terminal summary:
+- Brief natural language description of what was queried
+- Row count and date range covered
+- DataFrame preview with row cap by frequency:
+  - daily: 30 rows
+  - weekly: 52 rows
+  - monthly: 24 rows
+  - yearly: all rows
+- If capped: "Showing first N of M rows"
+- File path to generated code artifact
+- Offer: "Export to CSV?"
+
+After the DataFrame preview and before the export offer, show a one-line methodology footnote using the CONFIRMED parameters from Step 7:
+```
+Methodology: {Endpoint} | {activity} | {key filters} | {frequency} | {unit} | {other relevant params}
+```
+Example: `Methodology: CargoTimeSeries | loading_end | filter_origins=[Saudi Arabia] | filter_products=[Crude & Condensates] | monthly | bpd | exclude_intra_country`
+
+Use human-readable names for entity filters (not hex IDs).
+
+If user says yes to CSV: ask where to save, default `./output/{description}_{date}.csv`, create `output/` directory if needed.
+
+## Step 11: Summary (if triggered)
+
+**Smart trigger:** If the user's query contains "analyze", "summarize", "explain results", "what does this show", or "key findings" -- generate the summary automatically.
+
+**Post-query offer:** After showing results, always offer: "Want a summary of these results?"
+
+**Brief summary (default):**
+Analyze the DataFrame and produce 3-5 bullet points:
+- Top 3-5 contributors by volume with percentages of total
+- Period-over-period change if comparable time periods exist
+- Notable outliers: spikes, drops, record values, trend reversals
+- Each bullet includes specific numbers, not vague descriptions
+
+**Extended summary (if user requests "detailed summary" or "full analysis"):**
+- 100-200 word narrative paragraph in market commentary style
+- Includes everything from brief plus trend descriptions and broader context
+
+After showing the summary, offer: "Save this summary to a .md file?"
+If yes: create `output/{description}_summary_{date}.md`
+
+## Error Handling
+
+Wrap execution with these patterns -- 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?"
+
+Never auto-retry. Never self-correct. Report the error and let the user decide.
+
+</process>