vortexa-claude-skills 1.0.0

package/commands/vortexa/voyages.md

@@ -0,0 +1,285 @@
+---
+name: vortexa:voyages
+description: "Query vessel voyages, fleet movements, and voyage timeseries from the Vortexa API"
+argument-hint: "Show me VLCC voyages from Arabian Gulf to China in January 2025"
+allowed-tools:
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Glob
+  - Grep
+---
+
+<objective>
+Translate natural language voyage questions into correct Vortexa API calls using VoyagesSearchEnriched (individual voyages) or VoyagesTimeseries (aggregate vessel metrics), generating re-runnable Python code artifacts with transparent filter confirmation. This skill handles all vessel voyage queries -- laden/ballast periods, events, port calls, fleet counts, DWT trends, and tonne-miles.
+</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 this file before processing the user's query:
+- context/voyages.md -- Full parameter reference, voyage definitions, event types, status filters, V1/V2 differences
+</execution_context>
+
+## Setup Check
+@commands/vortexa/_check-setup.md
+
+<process>
+## 1. Read Endpoint Context
+
+Read `context/voyages.md` for full parameter reference, voyage definitions, event types, status filters, and V1/V2 differences.
+
+## 2. Parse the Query
+
+Analyze $ARGUMENTS and extract:
+- **Vessel class**: VLCC, Suezmax, Aframax, MR, LR1/LR2, Handysize, etc.
+- **Geography**: Origins and/or destinations -- identify what layer (country, port, shipping_region_v2, region)
+- **Voyage status**: Laden, ballast, or both
+- **Time range**: Apply date-units.md calendar/trailing convention
+- **voyage_date_range_activity**: active / arrivals / departures -- infer from query context or ask
+- **Product filter**: Optional (e.g. crude, LNG, clean products)
+- **Additional filters**: Flag, DWT range, vessel age, scrubber status, risk level, speed, corporate filters
+
+## 3. Check for Breakdown Redirect
+
+If the query contains a dimension phrase -- "by origin", "by destination", "by product", "by vessel class", "by vessel type", "by vessel flag", "by DWT", "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, type, DWT, owner, charterer, 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 a voyage-specific query (individual voyages, fleet counts) without cargo breakdown, continue to Step 4.
+
+## 4. Route -- VoyagesSearchEnriched or VoyagesTimeseries?
+
+Use signal words to determine endpoint:
+
+**VoyagesSearchEnriched** (individual voyage records):
+- Signal words: "show voyages", "vessel journey", "voyage details", "laden/ballast", "events", "port calls", "where is", "vessel track", "list vessels", "which ships"
+- Returns individual voyage rows with vessel name, IMO, origin, destination, events, duration
+- This is the DEFAULT if the query is ambiguous
+
+**VoyagesTimeseries V1** (aggregate vessel metrics):
+- Signal words: "how many vessels", "vessel count", "DWT trend", "fleet utilisation", "average speed", "wait time", "aggregate"
+- Use for: vessel_count, dwt, cargo_quantity, avg_wait_time, avg_speed, utilisation, cubic_capacity, tonne_miles, avg_distance
+- V1 uses underscore naming: origin_country, vessel_count, tonne_miles
+
+**VoyagesTimeseries V2** (voyage-level metric aggregations):
+- Signal words: "tonne-miles", "voyage count", "distance average", "duration average", "by owner", "by time charterer"
+- Use for: voyage-count, tonne-miles-sum, distance-avg, duration-avg, and per-day rates
+- V2 uses hyphen naming: origin-country, voyage-count, tonne-miles-sum
+- V2 has richer corporate breakdowns (vessel owner, time charterer, cargo trader)
+
+**NEVER mix V1 and V2 naming conventions in the same query.**
+
+**Rule of thumb:** V1 for vessel-perspective metrics (DWT, speed, wait time, utilisation). V2 for voyage-perspective metrics (voyage counts, tonne-miles sums, duration averages) especially when corporate breakdowns are needed.
+
+If ambiguous, ask: "Are you looking for individual voyage details or aggregate vessel statistics over time?"
+
+## 5. Check for Missing Parameters (ASK before confirming)
+
+Ask targeted questions one at a time. Do NOT bulk-dump all missing params.
+
+**For VoyagesSearchEnriched queries:**
+- Voyage status -- ask if not specified: "Laden voyages, ballast voyages, or both?"
+- Time range -- MUST be specified. Ask if missing: "What time period?"
+- voyage_date_range_activity -- infer from context: "active vessels" = active, "arrivals" = arrivals, "departures" = departures. If ambiguous, ask: "Should I look for voyages active during this period, or specifically arrivals/departures?"
+- At least one filter should be present (vessel class, geography, or product). If none specified, ask what to filter by.
+
+**For VoyagesTimeseries queries:**
+- Metric -- what to measure (vessel_count, tonne_miles, dwt, etc.). Ask if not clear.
+- Breakdown dimension -- ask if a split is desired: "Would you like this broken down by destination country, vessel class, or another dimension?"
+- Time range -- MUST be specified. Ask if missing.
+- Frequency -- ask if not specified: "What frequency? daily / weekly / monthly?"
+
+## 6. Resolve Entity IDs
+
+For each entity (origins, destinations, products, corporates):
+1. Check lib/aliases.json for common shorthands (AG, MEG, ARA, USG, etc.)
+2. Call lib/entities.py resolve functions with the correct entity_type and layer
+3. Multiple matches: present top 3 candidates, ask user to pick. NEVER auto-correct.
+4. Zero matches: suggest checking spelling or trying broader terms
+5. For vessel class filters: use `filter_vessel_classes=["oil_vlcc"]` directly -- no ID resolution needed
+
+**CRITICAL -- ballast voyage origin/destination inversion:**
+- For ballast voyages, `origins` = last DISCHARGE port (not where the ballast voyage started)
+- For ballast voyages, `destinations` = next LOAD port (not where the ballast voyage ends)
+- This is the OPPOSITE of laden voyage logic
+- When querying ballast voyages with geography filters, always warn the user about this inversion in the confirmation step
+
+## 7. Confirm Before Executing (MANDATORY)
+
+Present the complete parameter set:
+
+```
+Query: [restate the user's question]
+Endpoint: VoyagesSearchEnriched / VoyagesTimeseries V1 / VoyagesTimeseries V2
+Voyage Status: [laden / ballast / both]
+Date Range Activity: [active / arrivals / departures]
+Origins: [name (layer)] or "not specified"
+Destinations: [name (layer)] or "not specified"
+Vessel Class: [class] or "not specified"
+Product: [name (layer)] or "not specified"
+Time: [start datetime] -> [end datetime] ([interpretation])
+Metric: [vessel_count / tonne_miles / dwt / etc.] (timeseries only)
+Frequency: [day / week / month / etc.] (timeseries only)
+Breakdown: [split property] or "none" (timeseries only)
+Additional: [any other filters -- flag, DWT range, scrubber, corporate, etc.]
+Note: [ballast inversion warning if querying ballast voyages with geography filters]
+
+Confirm or adjust?
+```
+
+NEVER execute without user confirmation.
+
+## 8. Determine Execution Mode
+
+**Mode 3 -- Code-aware** (user references an existing file):
+- User mentions a .py file or notebook: read the file first, then extend or fix it
+- Use context/voyages.md to validate and improve existing logic
+
+**Mode 1 -- Pre-built function** (query matches a lib/ function pattern):
+- Live laden voyages to a specific destination -> `live_voyages_now()` from lib/voyages.py
+- Voyage count/DWT timeseries with percentile alerts -> `voyages_ts_with_alerts()` from lib/voyages.py
+- Post-discharge ballast destination analysis -> `post_ballast_distribution_and_medians()` from lib/voyages.py
+
+**Mode 2 -- Custom SDK code** (no matching lib/ function):
+- VSE queries without a matching lib/ function -> write `VoyagesSearchEnriched().search()` code using voyages.md as reference
+- VoyagesTimeseries queries -> write timeseries code using correct V1 or V2 syntax
+- Add comment: `# Custom query -- built from Vortexa API documentation`
+
+Selection order: if user references existing file -> Mode 3. Else if query matches a lib/ function -> Mode 1. Else -> Mode 2.
+
+**VOY-02 Building Block Note:**
+VoyagesSearchEnriched is also available as a building block for CM-Authoritative OOW workflows via `cargo_on_water_ts()` in lib/movements.py. That function uses VSE internally for vessel location enrichment, joining on cargo_movement_id. Users who need OOW by region should use Phase 6's `/vortexa:oow` skill, which calls this lib function. For direct VSE queries, use this `/vortexa:voyages` skill with appropriate filters.
+
+## 9. Generate & Execute Code Artifact
+
+Write a self-contained .py file:
+
+```python
+"""Vortexa Query: {description}
+Generated by /vortexa:voyages
+Date: {date}
+"""
+from datetime import datetime
+import sys; sys.path.insert(0, "lib")
+# Entity resolution imports (if needed)
+from entities import resolve, EntityCache
+
+# For pre-built functions:
+from voyages import live_voyages_now  # or voyages_ts_with_alerts, etc.
+
+# For custom SDK code:
+from vortexasdk import VoyagesSearchEnriched  # or VoyagesTimeseries, VoyagesTimeseriesV2
+
+# Entity Resolution
+cache = EntityCache()
+# {resolve each geography/product entity}
+
+# Query Parameters
+# {set up all confirmed parameters}
+
+# Execute Query
+df = VoyagesSearchEnriched().search(
+    time_min=..., time_max=...,
+    voyage_status=...,
+    voyage_date_range_activity=...,
+    # ... all confirmed filters
+    columns="all",
+).to_df()
+
+# Format Results
+# For VSE results, use rename_vse_columns(df) from lib/utils.py for human-readable names
+# For timeseries, parse breakdown using standard pattern
+
+# Display
+print(f"Results: {len(df)} rows")
+print(df.head(30))
+
+# Export (uncomment to save)
+# df.to_csv("output/{description}_{date}.csv", index=False)
+```
+
+Key rules:
+- For VoyagesSearchEnriched, use `.to_df(columns="all")` to get full detail
+- For VoyagesTimeseries, use `.to_df()` and parse the breakdown array
+- Use `rename_vse_columns(df)` from lib/utils.py for VSE column renaming
+- Code must be self-contained and re-runnable
+- All entity resolution is inline for transparency
+
+Ask the user: new file or append to existing? Default: new file `vortexa_query_{slug}.py`.
+
+## 10. Present Results
+
+Show a terminal summary:
+
+```
+Results: {n} voyages, {start_date} to {end_date}
+
+{brief description of findings -- top destinations, vessel counts, notable patterns}
+
+{DataFrame preview with row cap}
+
+Full data: {file_path}
+Export to CSV? (y/n)
+```
+
+Row cap by frequency (terminal summary only; full data in code artifact):
+- Daily timeseries: first 30 rows
+- Weekly timeseries: first 52 rows
+- Monthly timeseries: first 24 rows
+- Yearly timeseries / individual voyages: all rows (up to reasonable limit)
+
+Always mention total row count if capped.
+
+After the DataFrame preview and before the export offer, show a one-line methodology footnote using the CONFIRMED parameters from Step 7:
+```
+Methodology: {Endpoint} | {voyage_status} | {key filters} | {frequency} | {metric} | {other relevant params}
+```
+Example: `Methodology: VoyagesSearchEnriched | active | filter_origins=[Arabian/Persian Gulf] | filter_vessel_classes=[oil_vlcc] | size=500`
+
+Use human-readable names for entity filters (not hex IDs).
+</process>
+
+## 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 the execution step with these error patterns:
+
+- **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. Check entity names, date range, and filters."
+- **Entity not found**: Report clearly -- "The term '{term}' returned no matches. Check spelling or try a broader term."
+- **Multiple entity matches**: Present top 3 candidates with name, layer, and first 8 chars of ID. Ask user to pick.
+
+No auto-retry. No auto-correction. Report the error in plain English and let the user decide.