vortexa-claude-skills 1.0.0

package/context/date-units.md

@@ -0,0 +1,188 @@
+# Date Ranges & Units
+
+> Date parsing conventions and unit selection rules for all Vortexa queries.
+> Loaded automatically for every /vortexa: skill.
+
+---
+
+## Date Parsing Convention
+
+Two distinct patterns: **calendar periods** (named references to fixed ranges) and **trailing periods** (rolling windows from today).
+
+**Rule:** "last" + named period = calendar. "last" + number + period = trailing.
+
+### Calendar Periods (Named References)
+
+| User Says | Start | End |
+|---|---|---|
+| "last year" | Jan 1 of previous year, 00:00:00 | Dec 31 of previous year, 23:59:59 |
+| "last month" | 1st of previous month, 00:00:00 | Last day of previous month, 23:59:59 |
+| "last quarter" | 1st of previous quarter, 00:00:00 | Last day of previous quarter, 23:59:59 |
+| "Q3 2025" | Jul 1 2025, 00:00:00 | Sep 30 2025, 23:59:59 |
+| "Q1 2026" | Jan 1 2026, 00:00:00 | Mar 31 2026, 23:59:59 |
+| "2024" | Jan 1 2024, 00:00:00 | Dec 31 2024, 23:59:59 |
+| "2025" | Jan 1 2025, 00:00:00 | Dec 31 2025, 23:59:59 |
+| "YTD", "year to date" | Jan 1 of current year, 00:00:00 | Current timestamp |
+| "this month" | 1st of current month, 00:00:00 | Current timestamp |
+| "this quarter" | 1st of current quarter, 00:00:00 | Current timestamp |
+
+### Quarter Reference
+
+| Quarter | Start | End |
+|---|---|---|
+| Q1 | Jan 1 | Mar 31 |
+| Q2 | Apr 1 | Jun 30 |
+| Q3 | Jul 1 | Sep 30 |
+| Q4 | Oct 1 | Dec 31 |
+
+### Trailing Periods (Number + Unit)
+
+| User Says | Start | End |
+|---|---|---|
+| "last 6 months" | Today minus 6 months, 00:00:00 | Current timestamp |
+| "last 30 days" | Today minus 30 days, 00:00:00 | Current timestamp |
+| "last 12 months" | Today minus 12 months, 00:00:00 | Current timestamp |
+| "last 2 weeks" | Today minus 14 days, 00:00:00 | Current timestamp |
+| "rolling 3 months" | Today minus 90 days, 00:00:00 | Current timestamp |
+
+### CRITICAL DATE RULES
+
+**NEVER** leave end dates at midnight (00:00:00) -- data from the last day will be excluded entirely. This is the most common silent data loss bug.
+
+**ALWAYS** use `datetime(year, month, day, 23, 59, 59)` for historical end dates.
+
+**ALWAYS** specify `filter_time_min` and `filter_time_max` explicitly -- never rely on defaults.
+
+### Code Examples
+
+```python
+from datetime import datetime
+
+# "last year" (calendar) -- assuming current year is 2026
+time_min = datetime(2025, 1, 1)              # Jan 1, 00:00:00
+time_max = datetime(2025, 12, 31, 23, 59, 59)  # Dec 31, 23:59:59
+
+# "January 2025"
+time_min = datetime(2025, 1, 1)
+time_max = datetime(2025, 1, 31, 23, 59, 59)
+
+# "Q3 2025"
+time_min = datetime(2025, 7, 1)
+time_max = datetime(2025, 9, 30, 23, 59, 59)
+
+# "last 6 months" (trailing) -- rolling from today
+from dateutil.relativedelta import relativedelta
+time_min = datetime.now() - relativedelta(months=6)
+time_max = datetime.now()
+```
+
+---
+
+## Frequency Selection
+
+Frequency determines the time bucket size for timeseries queries.
+
+### Frequency Options
+
+| User Says | API Value (CM/CTS) | API Value (Voyages) | Description |
+|---|---|---|---|
+| "daily" | `day` | `day` | One data point per day |
+| "weekly" | `week` | `week` | One data point per week |
+| "DOE week" | `doe_week` | `doe_week` | US EIA/DOE week convention |
+| "monthly" | `month` | `month` | One data point per month |
+| "quarterly" | `quarter` | `quarter` | One data point per quarter |
+| "yearly", "annually" | `year` | `year` | One data point per year |
+
+### Frequency Guidance by Date Range
+
+| Date Range Length | Suggested Frequency | Rationale |
+|---|---|---|
+| < 1 month | `day` | Daily granularity is useful for short windows |
+| 1-3 months | `day` or `week` | Weekly smooths noise; daily for detail |
+| 3-12 months | `week` or `month` | Monthly is cleaner for medium ranges |
+| 1-3 years | `month` | Monthly avoids excessive data points |
+| > 3 years | `month` or `quarter` | Quarterly for very long ranges |
+
+### Frequency Rules
+
+**ALWAYS** ask the user what frequency they want -- unless they already specified it in the query.
+
+If the user says "monthly crude exports" -- "monthly" IS the frequency. No need to ask.
+
+If the user says "crude exports from Saudi Arabia last year" -- frequency is NOT specified. Ask: "What frequency would you like? daily / weekly / monthly?"
+
+The guidance table above is for suggesting defaults, not auto-selecting. Present it as a recommendation.
+
+For CargoTimeSeries, the parameter is `timeseries_frequency`.
+For VoyagesTimeseries, the parameter is `breakdown_frequency`.
+
+---
+
+## Unit Defaults by Commodity
+
+### Default Unit Table
+
+| Product Group | Default Unit | API Value | Reason |
+|---|---|---|---|
+| Crude & Condensates | barrels per day | `bpd` | Industry standard for oil flow rates |
+| Clean Petroleum Products | barrels per day | `bpd` | Industry standard for oil flow rates |
+| Dirty Petroleum Products | barrels per day | `bpd` | Industry standard for oil flow rates |
+| LNG | tonnes | `t` | Industry standard for LNG |
+| LPG | tonnes | `t` | Industry standard for LPG |
+| Counting queries | count | `c` | Number of cargoes |
+
+### All Available Units
+
+| Unit | API Value (CTS) | API Value (CM search) | Description |
+|---|---|---|---|
+| barrels | `b` | `b` | Absolute oil volume |
+| barrels per day | `bpd` | -- | Oil flow rate (most common for trends) |
+| tonnes | `t` | `t` | Absolute weight (LNG, LPG, or oil) |
+| tonnes per day | `tpd` | -- | Weight flow rate |
+| cubic metres | `cbm` | `cbm` | LNG volume |
+| count | `c` | -- | Number of cargo movements |
+| count per day | `cpd` | -- | Cargo movement rate |
+| million per day | `mpd` | -- | Millions per day |
+| barrels per annum | `bpa` | -- | Annual oil rate |
+| tonnes per annum | `tpa` | -- | Annual weight rate |
+| million per annum | `mpa` | -- | Millions per annum |
+
+**Note:** CargoMovements search uses `cm_unit` (only `b`, `t`, `cbm`). CargoTimeSeries uses `timeseries_unit` (full list above). VoyagesSearchEnriched uses `unit` (only `b`, `t`, `cbm`).
+
+### Unit Rules
+
+**NEVER** guess units if the product could use multiple -- ASK the user. Example: LNG can use tonnes (`t`) or cubic metres (`cbm`).
+
+**ALWAYS** mention the unit choice and its rationale in the confirmation step, so the user can override.
+
+**ALWAYS** match the unit to the commodity:
+- Oil queries: `bpd` for trends, `b` for absolute volumes
+- LNG queries: `t` (default), or `cbm` if user specifies volume
+- LPG queries: `t`
+- Counting: `c` or `cpd`
+
+**ALWAYS** use rate units (`bpd`, `tpd`) for timeseries trends. Use absolute units (`b`, `t`) only for snapshot/total queries.
+
+---
+
+## Confirmation Step: Date, Unit & Frequency
+
+Every data query confirmation must include:
+
+```
+Time: Jan 1 2025, 00:00:00 -> Dec 31 2025, 23:59:59  (calendar year 2025)
+Unit: bpd (barrels per day -- default for oil)
+Frequency: monthly
+```
+
+If the user did not specify frequency, the confirmation should say:
+
+```
+Frequency: Please specify -- daily / weekly / monthly?
+```
+
+If the unit choice is non-obvious, explain why:
+
+```
+Unit: tonnes (default for LNG -- would you prefer cubic metres?)
+```

package/context/endpoint-template.md

@@ -0,0 +1,176 @@
+# Adding a New Vortexa Endpoint
+
+> Developer guide for extending the skills package with new API endpoints.
+> Each new endpoint requires exactly 3 files that compose shared infrastructure.
+
+---
+
+## The 3-File Pattern
+
+| File | Location | Purpose |
+|------|----------|---------|
+| Context doc | `context/<endpoint>.md` | API reference: parameters, filters, columns, code examples |
+| Python module | `lib/<module>.py` | SDK wrapper functions: query, parse, transform |
+| Skill file | `commands/vortexa/<skill>.md` | Slash command: NL parsing, confirmation, code generation |
+
+Everything else -- entity resolution, date parsing, guardrails, visualization, setup checks -- is shared infrastructure already built.
+
+---
+
+## Shared Infrastructure (Already Built)
+
+These are composed by all endpoints -- no duplication needed:
+
+| Component | Path | What It Provides |
+|-----------|------|-----------------|
+| Guardrails | `context/guardrails.md` | NEVER/ALWAYS rules, activity filter table, confirmation template |
+| Entity resolution | `context/entity-resolution.md` | Name-to-ID workflow, disambiguation protocol |
+| Date & units | `context/date-units.md` | Date parsing, unit defaults, frequency guidance |
+| Entity resolver | `lib/entities.py` | `resolve_geography()`, `resolve_product()`, `EntityCache` |
+| API auth | `lib/api.py` | `load_api_key()`, environment validation |
+| Utilities | `lib/utils.py` | `_to_dt()`, `_cols()`, `top_n_with_other()` |
+| Visualization | `lib/visualization.py` | Vortexa theme, chart functions |
+| Setup check | `commands/vortexa/_check-setup.md` | Pre-execution environment validation |
+| Skill template | `commands/vortexa/_skill-template.md` | YAML frontmatter and process structure reference |
+
+---
+
+## Step-by-Step: Adding an Endpoint
+
+### Step 1: Context Doc (`context/<endpoint>.md`)
+
+Create the API reference document. Follow the structure of `context/cargo-movements.md`:
+
+1. **Header**: Endpoint name, one-line description, SDK class name
+2. **When to Use**: Decision table -- when this endpoint vs others, with signal words
+3. **Parameters**: Full parameter table with name, type, default, description
+4. **Filter Options**: All filter parameters with valid values
+5. **Response Fields**: Column/field names, types, descriptions
+6. **Code Examples**: Working SDK code snippets for common queries
+7. **Cross-References**: Links to guardrails.md, entity-resolution.md, date-units.md
+
+Target: 400-700 lines. Every parameter documented. Include negative guidance (NEVER do X).
+
+### Step 2: Python Module (`lib/<module>.py`)
+
+Create SDK wrapper functions. Follow the structure of `lib/movements.py`:
+
+1. **Lazy imports**: `from vortexasdk import X` inside functions, not at module level
+2. **Internal imports**: `from lib.entities import resolve_geography, resolve_product`
+3. **Function signature**: Accept human-readable parameters, return DataFrames
+4. **Column renaming**: Apply `_cols()` from lib/utils.py for human-readable output
+5. **Error handling**: Catch SDK exceptions, return helpful messages
+
+Minimum functions:
+- `<endpoint>_timeseries(...)` -- time-series query with filters
+- `<endpoint>_search(...)` -- individual record search
+- Column rename map as module-level dict
+
+### Step 3: Skill File (`commands/vortexa/<skill>.md`)
+
+Create the slash command. Follow the structure of `commands/vortexa/cargo-flows.md`:
+
+1. **YAML frontmatter**: name, description, argument-hint, allowed-tools
+2. **Objective**: What this skill does (1-3 sentences)
+3. **Execution context**: Pre-loaded vs on-demand context docs
+4. **Setup check**: Include `@commands/vortexa/_check-setup.md`
+5. **Process steps**:
+   - Read endpoint context doc
+   - Parse user query (extract entities, dates, filters)
+   - Check for missing parameters (ask if needed)
+   - Resolve entity IDs
+   - Confirm before executing (MANDATORY)
+   - Generate and execute Python code artifact
+   - Present results with methodology footnote
+   - Offer CSV export and summary
+
+Target: 180-250 lines.
+
+---
+
+## Worked Example: Freight Outlook (Hypothetical)
+
+To add Freight Outlook as a new endpoint:
+
+### File 1: `context/freight-outlook.md`
+
+Document all FFA routes (TC1-TC17, TD1-TD25), pricing parameters, rate types (flat rate, worldscale, $/tonne), time-series options, and settlement conventions. Include a decision table for when to use Freight Outlook vs CargoTimeSeries for cost analysis. Cross-reference guardrails.md for confirmation template and date-units.md for time range parsing.
+
+### File 2: `lib/freight.py`
+
+```python
+"""Freight outlook queries and rate helpers."""
+
+import pandas as pd
+
+# column rename map
+freight_cols = {
+    "key": "route",
+    "value": "rate",
+    "count": "fixtures",
+}
+
+def freight_timeseries(route, time_min, time_max, rate_type="flat_rate", frequency="day"):
+    """Query freight rate timeseries for a given route."""
+    from vortexasdk import FreightPricing
+    from lib.utils import _to_dt, _cols
+
+    result = FreightPricing().search(
+        route=route,
+        filter_time_min=_to_dt(time_min),
+        filter_time_max=_to_dt(time_max),
+        rate_type=rate_type,
+        breakdown_frequency=frequency,
+    ).to_df()
+
+    return _cols(result, freight_cols)
+
+def freight_search(route, time_min, time_max, size=500):
+    """Search individual freight fixtures for a route."""
+    from vortexasdk import FreightPricing
+    from lib.utils import _to_dt, _cols
+
+    result = FreightPricing().search(
+        route=route,
+        filter_time_min=_to_dt(time_min),
+        filter_time_max=_to_dt(time_max),
+        size=size,
+    ).to_df()
+
+    return _cols(result, freight_cols)
+```
+
+### File 3: `commands/vortexa/freight.md`
+
+Register as `/vortexa:freight`. Parse route names from natural language ("TD3C", "AG to Japan VLCC"), resolve to Vortexa route IDs, confirm rate type and time range, generate Python code artifact using `lib/freight.py`, present rate chart with Vortexa theme.
+
+### Shared infrastructure reused automatically:
+
+- Entity resolution for vessel classes and geographies
+- Date parsing for time ranges
+- Vortexa theme for rate charts
+- Setup check for environment validation
+- Guardrails confirmation template
+
+---
+
+## Checklist for New Endpoint
+
+Before submitting, verify all items:
+
+- [ ] Context doc covers all parameters and response fields
+- [ ] Context doc includes NEVER/ALWAYS negative guidance
+- [ ] Context doc has "When to Use" decision table with signal words
+- [ ] Context doc cross-references guardrails.md, entity-resolution.md, date-units.md
+- [ ] Python module uses lazy imports (no top-level vortexasdk)
+- [ ] Python module uses `_cols()` for column renaming
+- [ ] Python module has both timeseries and search functions
+- [ ] Python module has module-level column rename dict
+- [ ] Skill file includes setup check via `@commands/vortexa/_check-setup.md`
+- [ ] Skill file has mandatory confirmation step before execution
+- [ ] Skill file includes methodology footnote in results
+- [ ] Skill file offers CSV export after presenting results
+- [ ] All entity resolution goes through `lib/entities.py`
+- [ ] Generated code uses `sys.path.insert(0, "lib")` pattern
+- [ ] npm `files` allowlist includes the new files' directories (already covered if using `context/`, `lib/`, `commands/`)
+- [ ] CLAUDE.md "Available Skills" section updated with the new skill

package/context/entity-resolution.md

@@ -0,0 +1,217 @@
+# Entity Resolution
+
+> Step-by-step workflow for resolving human-readable names to Vortexa 64-char hex IDs.
+> Loaded automatically for every /vortexa: skill.
+
+---
+
+## Resolution Workflow
+
+Every Vortexa API filter requires hex IDs, not names. Follow this process for every entity:
+
+1. **Identify entity type** -- geography, product, vessel, or corporate
+2. **Call the correct SDK search method** with appropriate filters (especially `filter_layer` for geographies and products)
+3. **Handle results:**
+   - 1 match = use it
+   - Multiple matches = disambiguate (present to user)
+   - 0 matches = suggest alternatives (broaden search, check spelling, try partial name)
+
+---
+
+## Entity Types & SDK Methods
+
+| Entity Type | SDK Class | Search Method | Key Filter | Size Default |
+|---|---|---|---|---|
+| Geography | `Geographies` | `.search(term=..., filter_layer=...)` | `filter_layer` (critical) | 1 -- set higher |
+| Product | `Products` | `.search(term=..., filter_layer=...)` | `filter_layer` | 1 -- set higher |
+| Vessel | `Vessels` | `.search(term=..., vessel_classes=...)` | `vessel_classes` | 1 -- set higher |
+| Corporation | `Corporations` | `.search(term=...)` | (none in SDK) | 1 -- set higher |
+
+**ALWAYS** set `size` to at least 10 for resolution searches. Default `size=1` may return the wrong match.
+
+---
+
+## Geography Resolution
+
+Geographies have a deep hierarchy. The `filter_layer` parameter is mandatory for accurate resolution.
+
+### Hierarchy (widest to most specific)
+
+```
+wider_shipping_region > shipping_region_v2 > region > country > port > terminal
+```
+
+### Resolution Table
+
+| User Says | filter_layer | Example Vortexa Name | Notes |
+|---|---|---|---|
+| "China", "US", "Saudi Arabia" | `country` | China, United States, Saudi Arabia | Country names |
+| "Rotterdam", "Fujairah", "Ras Tanura" | `port` | Rotterdam [NL], Fujairah, Ras Tanura | Port names |
+| "Middle East", "Asia", "Europe" | `region` | Middle East/North Africa, Asia, Europe | Broad regions |
+| "AG", "Arabian Gulf", "Persian Gulf" | `shipping_region_v2` | Arabian/Persian Gulf | Shipping regions |
+| "USG", "US Gulf Coast" | `shipping_region_v2` | US Gulf Coast | Shipping regions |
+| "WAF", "West Africa" | `shipping_region_v2` | West Africa | Shipping regions |
+| "ARA" | `port` (multiple) | Amsterdam, Rotterdam, Antwerp | Resolve each port separately |
+| "PADD I", "East Coast" | `shipping_region_v2` | US Atlantic Coast | US regional |
+| "Suez Canal", "Panama Canal" | `waypoint` | Suez Canal, Panama Canal | Chokepoints |
+
+### Code Pattern
+
+```python
+from vortexasdk import Geographies
+
+# ALWAYS specify filter_layer
+result = Geographies().search(
+    term="Saudi Arabia",
+    filter_layer="country",
+    exact_term_match=True
+).to_df()
+
+saudi_id = result.iloc[0]["id"]  # 64-char hex
+```
+
+**NEVER** search geographies without `filter_layer`. "China" without a layer returns ports, regions, and the country.
+
+---
+
+## Product Resolution
+
+Products have a 4-level hierarchy. Match the `filter_layer` to the user's specificity.
+
+### Hierarchy
+
+```
+group > group_product > category > grade
+```
+
+### Resolution Table
+
+| User Says | filter_layer | Vortexa Name | Notes |
+|---|---|---|---|
+| "crude", "crude oil" | `group` | Crude & Condensates | Broadest oil group |
+| "clean products", "CPP" | `group` | Clean Petroleum Products | |
+| "dirty products", "DPP" | `group` | Dirty Petroleum Products | |
+| "LNG" | `group` | LNG | |
+| "LPG" | `group` | LPG | |
+| "fuel oil" | `group_product` | Fuel Oil | Under Dirty Products |
+| "naphtha" | `group_product` | Naphtha | Under Clean Products |
+| "gasoline" | `group_product` | Gasoline / Mogas | Under Clean Products |
+| "gasoil", "diesel" | `group_product` | Gasoil/Diesel | Under Clean Products |
+| "condensate" | `group_product` | Condensate | Under Crude & Condensates |
+| "Arab Light", "Bonny Light" | `grade` | Arab Light, Bonny Light | Most specific |
+
+### Code Pattern
+
+```python
+from vortexasdk import Products
+
+result = Products().search(
+    term="crude",
+    filter_layer="group"
+).to_df()
+
+# Verify the match -- "crude" may return multiple layers
+crude_id = result[result["name"] == "Crude & Condensates"].iloc[0]["id"]
+```
+
+**ALWAYS** verify the `layer` and `name` columns in results. Fuzzy matching may return grades when you want the group.
+
+---
+
+## Vessel Resolution
+
+Vessels are searched by name, IMO number, or class. No `filter_layer` applies.
+
+| Search By | Method | Notes |
+|---|---|---|
+| Vessel name | `Vessels().search(term="vessel name")` | Fuzzy match; may return multiple |
+| IMO number | `Vessels().search(ids=[9779836])` | Pass IMO as integer, not string |
+| Vessel class | `Vessels().search(vessel_classes="oil_vlcc")` | Returns all vessels of that class |
+| Name + class | `Vessels().search(term="ocean", vessel_classes="oil_vlcc")` | Narrows by both |
+
+### Code Pattern
+
+```python
+from vortexasdk import Vessels
+
+# By name
+result = Vessels().search(term="Olympic Pride").to_df()
+
+# By IMO (MUST be integer)
+result = Vessels().search(ids=[9779836]).to_df(columns="all")
+```
+
+**NEVER** pass IMO numbers as strings -- the API requires integers in the `ids` or `term` array.
+
+For vessel class filtering in data queries (CM/Voyages), use `filter_vessel_classes=["oil_vlcc"]` directly -- no ID resolution needed.
+
+---
+
+## Corporate Resolution
+
+Corporations (shipowners, charterers, traders) are searched by name only. The SDK does not support filtering by entity type.
+
+| Search By | Method | Notes |
+|---|---|---|
+| Company name | `Corporations().search(term="Shell")` | Fuzzy match |
+| Exact name | `Corporations().search(term="CHEVRON", exact_term_match=True)` | Exact match |
+
+### Code Pattern
+
+```python
+from vortexasdk import Corporations
+
+result = Corporations().search(term="BAHRI", exact_term_match=True).to_df()
+corp_id = result.iloc[0]["id"]
+```
+
+**Limitation:** The SDK `Corporations` class does not expose `corporateEntityType` filtering. To filter by role (effective_controller, charterer, etc.), use the REST API directly:
+
+```python
+import requests
+
+payload = {
+    "term": "CHEVRON",
+    "corporateEntityType": ["effective_controller"],
+    "size": 10
+}
+resp = requests.post(
+    "https://api.vortexa.com/v5/reference/charterers",
+    headers={"x-api-key": VORTEXA_API_KEY},
+    json=payload
+)
+```
+
+---
+
+## Disambiguation Protocol
+
+When a search returns multiple matches:
+
+1. **Present top 5 matches** to the user with: name, type/layer, and first 8 chars of ID
+2. **Ask the user to select** the correct entity
+3. **NEVER guess** -- ambiguous entities cause silently wrong results
+
+### Example Disambiguation
+
+```
+Multiple matches found for "Gulf":
+
+1. Arabian/Persian Gulf (shipping_region_v2) - ID: a3c1e9f2...
+2. US Gulf Coast (shipping_region_v2) - ID: b7d4f8a1...
+3. Gulf of Mexico (region) - ID: c2e5a7b3...
+4. Gulf of Oman (shipping_region_v2) - ID: d8f1c4e6...
+
+Which did you mean?
+```
+
+---
+
+## ID Format
+
+| Format | Length | Used In | Example |
+|---|---|---|---|
+| Full hex ID | 64 characters | All API filter parameters | `a1b2c3d4e5f6...` (64 chars) |
+| Truncated ID | 16 characters | `cargo_movement_id` in joins, voyage links | `a1b2c3d4e5f6a7b8` |
+
+**ALWAYS** use full 64-character IDs for API calls. Truncated 16-char IDs appear in cross-endpoint joins (e.g., matching cargo movements to voyages) but are not valid for filter parameters.