vortexa-claude-skills 1.0.0

package/context/voyages.md

@@ -0,0 +1,636 @@
+# Voyages & VoyagesSearchEnriched
+
+> Endpoint documentation for querying vessel voyages, laden/ballast periods, events, and location enrichment.
+> For date/unit rules, see date-units.md (pre-loaded). For entity resolution, see entity-resolution.md (pre-loaded).
+
+---
+
+## When to Use Voyages vs CargoMovements
+
+This is the most important decision. Getting it wrong means querying the wrong endpoint entirely.
+
+| User Wants | Use This | Why |
+|---|---|---|
+| Product-centric flow volumes (exports, imports, trade flows) | CargoMovements / CargoTimeSeries | CM tracks cargo quantity from origin to destination |
+| Vessel-centric voyage tracking (where did this ship go?) | VoyagesSearchEnriched | Voyages tracks the vessel journey with events |
+| OOW volumes broken down by region | CM for volumes + Voyages for location | CM-Authoritative pattern (see below) |
+| Individual vessel journey details | VoyagesSearchEnriched | Full voyage with events, ports, durations |
+| Congestion / waiting time analysis | Congestion breakdown or VoyagesSearchEnriched | Location + waiting time data |
+| Aggregate vessel counts or DWT over time | VoyagesTimeseries | Time-series vessel-perspective metrics |
+| Tonne-miles, voyage counts with corporate splits | VoyagesTimeseriesV2 | V2 has richer corporate breakdowns |
+| Fleet utilisation, ballast positioning | VoyagesTimeseries or VoyagesSearchEnriched | Voyage status + vessel class filters |
+| "How much crude flowed from A to B?" | CargoMovements / CargoTimeSeries | NEVER use Voyages for volume flow questions |
+| "How many tankers arrived at port X?" | VoyagesTimeseries with `arrivals` | Vessel count, not cargo volume |
+
+**Signal words for Voyages:** "vessels", "ships", "voyages", "fleet", "tonne-miles", "DWT", "congestion", "ballast", "laden", "voyage events", "vessel journey", "speed", "waiting time"
+
+**Signal words for CargoMovements:** "exports", "imports", "barrels", "tonnes", "cargo", "trade flow", "product flow", "volumes shipped", "floating storage volumes"
+
+---
+
+## CRITICAL RULES
+
+**NEVER** mix V1 underscore naming with V2 hyphen naming:
+- V1: `origin_country`, `vessel_count`, `tonne_miles`
+- V2: `origin-country`, `voyage-count`, `tonne-miles-sum`
+- V2 metric and breakdown are constructor args; V1 they are search params
+
+**NEVER** forget the `exclude_overlapping_entries` behavior difference:
+- Timeseries: defaults to `true` (de-duplicates overlapping voyage periods)
+- Search: defaults to `false` (may count overlapping days)
+
+**NEVER** assume ballast voyage origin = vessel's starting port:
+- 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 and a common source of confusion
+
+**ALWAYS** specify `voyage_status` filter -- default returns all statuses including outdated ones.
+
+**ALWAYS** set `size` higher than 1 for search endpoints -- the default is `1`, which returns only a single record.
+
+**ALWAYS** set `time_min` and `time_max` explicitly -- never rely on defaults.
+
+**ALWAYS** match `voyage_date_range_activity` to user intent:
+
+| User Says | `voyage_date_range_activity` | Meaning |
+|---|---|---|
+| "active vessels", "vessels during this period" | `active` | Voyage overlapped the time window at any point |
+| "arrivals", "vessels that arrived" | `arrivals` | Voyage ended (final discharge) within the time window |
+| "departures", "vessels that departed" | `departures` | Voyage started (first load) within the time window |
+| "transited waypoint" | `waypoint` | Had a waypoint event within the time window |
+
+See also: guardrails.md for cross-cutting rules on entity resolution, date ranges, and confirmation steps.
+
+---
+
+## Endpoint Selection
+
+| Endpoint | Purpose | Returns | When to Use |
+|---|---|---|---|
+| VoyagesSearchEnriched | Individual voyage details | List of voyage objects with events | "show voyages", "vessel journey", "list ships" |
+| VoyagesTimeseries (V1) | Aggregate vessel metrics over time | Time series with breakdowns | "how many vessels", "DWT trend", "fleet utilisation" |
+| VoyagesTimeseriesV2 | Voyage-level metric aggregations | Time series with V2 splits | "tonne-miles by class", "voyage count by corporate" |
+| Congestion breakdown | Congestion counts by location | Port/terminal congestion data | "port congestion", "waiting times" |
+| Top hits | Voyage counts by property | Ranked list | "busiest ports", "top destinations" |
+
+---
+
+## What is a Voyage
+
+A voyage is a **continuous laden or ballast period** for a single vessel. Each voyage contains multiple **Voyage Events** describing activity during that period.
+
+**Key rules:**
+- A laden voyage starts at first load, ends at full discharge (partial discharges do not end a voyage)
+- A ballast voyage starts after full discharge, ends before next load
+- Multiple loads/discharges within one continuous period = still one voyage
+- STS transfers, congestion/waiting, and floating storage are recorded as events within the voyage, not as separate voyages
+- Congestion events include duration and location, extractable from voyage events
+
+---
+
+## Status Filters
+
+Each status filter has a corresponding `*_excluded` variant for exclusion.
+
+### Voyage Status
+
+| Value | Meaning | When to Use |
+|---|---|---|
+| `laden` | Vessel is carrying cargo | "loaded ships", "carrying cargo" |
+| `ballast` | Vessel is empty / repositioning | "empty vessels", "ballast fleet" |
+
+### Movement Status
+
+| Value | Meaning | When to Use |
+|---|---|---|
+| `moving` | Vessel underway | "in transit", "moving vessels" |
+| `stationary` | Vessel stopped | "anchored", "stopped" |
+| `waiting` | Vessel queuing | "waiting vessels", "queuing" |
+| `congestion` | Vessel in congestion zone | "congested" |
+| `slow` | Vessel slow steaming | "slow steaming" |
+
+### Cargo Status
+
+| Value | Meaning | When to Use |
+|---|---|---|
+| `in-transit` | Cargo underway | "in transit cargo" |
+| `loading` | Cargo being loaded | "at load port" |
+| `discharging` | Cargo being discharged | "at discharge port" |
+| `floating-storage` | Cargo in floating storage | "stored at sea" |
+
+### Location Status
+
+| Value | Meaning | When to Use |
+|---|---|---|
+| `berth` | At berth / docked | "docked" |
+| `anchorage-zone` | At anchorage | "anchored" |
+| `on-the-sea` | At sea | "on the water" |
+| `dry-dock` | In dry dock | "in dry dock" |
+
+### Commitment Status
+
+| Value | Meaning | When to Use |
+|---|---|---|
+| `committed` | Vessel booked / fixed | "committed", "fixed" |
+| `uncommitted` | Vessel not committed | "open", "available" |
+| `open` | Vessel open for charter | "open" |
+| `unknown` | Status unknown | -- |
+
+### Vessel Risk Level
+
+| Value | When to Use |
+|---|---|
+| `low` | "clean vessels", "low risk" |
+| `medium` | "medium risk" |
+| `high` | "high risk", "risky vessels" |
+| `sanctioned` | "sanctioned fleet" |
+
+---
+
+## Geography Filters
+
+All geography filters require Vortexa hex hash IDs (see entity-resolution.md). Each has a `*_excluded` variant.
+
+| Parameter | Filters On | Use When User Says |
+|---|---|---|
+| `origins` | Cargo origin(s); for ballast = last discharge port | "departing from", "loaded in" |
+| `destinations` | Cargo destination(s); for ballast = next load port | "heading to", "discharging at" |
+| `locations` | Any visited location during the voyage | "passing through", "currently at" |
+| `voyage_origins` | First port visit of the voyage | "voyage started from" |
+| `voyage_destinations` | Last port visit of the voyage | "voyage ended at" |
+| `voyage_routes` | First origin OR final destination matches | "route involves" |
+| `congestion_target_location` | Location where congestion occurred | "congested at" |
+
+---
+
+## API Reference: VoyagesSearchEnriched
+
+**Endpoint:** `POST /v5/voyages/search-enriched`
+**SDK:** `VoyagesSearchEnriched().search(...)`
+**Purpose:** Retrieve individual voyage records with full event, vessel, product, and corporate detail.
+
+### Endpoint-Specific Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `size` | integer | `1` | Records per page (0-500). **Default is 1 -- always set higher.** |
+| `unit` | enum | `b` | Quantity unit: `b` (barrels), `t` (tonnes), `cbm` (cubic metres) |
+| `order` | enum | `vessel_name` | Sort by: `vessel_name`, `dwt`, `vessel_class`, `start_date`, `end_date`, `latest_product`, `tonne_miles`, `distance`, `duration`, `quantity`, `quantity_tonnes`, `quantity_barrels`, `quantity_cubic_metres` |
+| `order_direction` | enum | `desc` | `asc` or `desc` |
+| `search_after` | object | none | Pagination cursor from previous response's `next_request` |
+| `_response` | enum | `json` | `json` or `csv` |
+
+### SDK-Specific Parameters
+
+| Parameter | Description |
+|---|---|
+| `columns` | `None` for `.to_list()`, `'all'` or list of column names for `.to_df()` |
+| `origin_behaviour` | Which departure mode `voyage_date_range_activity` counts: `first_load` or `any_load` |
+| `destination_behaviour` | Which arrival mode counts: `last_discharge` or `any_discharge` |
+| `flags` | SDK uses `flags` instead of REST `vessel_flags` |
+| `ice_class` | SDK uses `ice_class` instead of REST `vessel_ice_class` |
+| `vessel_propulsion` | Filter by propulsion type IDs |
+
+### DataFrame Columns
+
+Available columns for `.to_df()` and CSV output:
+
+**Vessel:** `vessel_name`, `imo`, `dwt`, `capacity`, `vessel_class`, `build_year`, `flag`, `risk_rating`, `scrubber`, `coating`
+
+**Voyage:** `voyage_status`, `cargo_status`, `start_date`, `end_date`, `duration`, `distance`, `tonne_miles`, `quantity`, `voyage_id`, `previous_voyage_id`, `next_voyage_id`
+
+**Origin (cargo origin):** `origin`, `origin_terminal`, `origin_port`, `origin_country`, `origin_shipping_region`, `origin_basin`, `origin_wider_shipping_region`, `origin_country_zone`, `origin_alternative_region`, `origin_state_or_province`
+
+**Destination (cargo destination):** `destination`, `destination_terminal`, `destination_port`, `destination_country`, `destination_shipping_region`, `destination_basin`, `destination_wider_shipping_region`, `destination_country_zone`, `destination_alternative_region`, `destination_state_or_province`
+
+**First/Final (voyage-level):** `first_origin`, `first_origin_terminal`, `first_origin_port`, `first_origin_country`, `first_origin_shipping_region` (and same pattern with `final_destination_*`)
+
+**Commercial:** `charterer`, `effective_controller`, `time_charterer`
+
+**Product:** `latest_product`, `latest_product_group`, `latest_product_category`, `latest_product_grade`
+
+### CSV Output
+
+Request CSV by setting `_response='csv'` or header `accept: text/csv`, with `csv_columns='all'` or a list of specific columns.
+
+---
+
+## API Reference: VoyagesTimeseries (V1)
+
+**Endpoint:** `POST /v5/voyages/timeseries`
+**SDK:** `VoyagesTimeseries().search(...)`
+**Purpose:** Time-series vessel data. Aggregate metrics like vessel count, cargo quantity, tonne-miles, DWT, speed, wait times with breakdowns.
+
+### Endpoint-Specific Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `breakdown_frequency` | enum | `day` | `day`, `week`, `doe_week`, `month`, `quarter`, `year` |
+| `breakdown_property` | enum | `vessel_count` | What to measure: `vessel_count`, `utilisation`, `cargo_quantity`, `avg_wait_time`, `dwt`, `cubic_capacity`, `tonne_miles`, `avg_distance`, `avg_speed` |
+| `breakdown_split_property` | enum | `none` | How to split. See split values below. |
+| `breakdown_unit_operator` | enum | `sum` | `sum` or `avg` |
+| `breakdown_size` | integer | `100` | Max breakdown categories (0-10000). Overflow grouped under "Other". |
+| `exclude_overlapping_entries` | boolean | `true` | De-duplicate overlapping voyage periods. **Defaults true for timeseries.** |
+
+### Split Property Values (V1)
+
+**Vessel:** `vessel_status`, `vessel_class_group`, `vessel_class_coarse`, `vessel_class_granular`, `vessel_flag`, `commitment_status`, `fixture_status`, `cargo_status`, `location_status`, `movement_status`, `presets`
+
+**Corporate:** `effective_controller`, `charterer`
+
+**Origin geography:** `origin_region`, `origin_shipping_region`, `origin_shipping_region_v2`, `origin_wider_shipping_region`, `origin_basin`, `origin_trading_region`, `origin_trading_sub_region`, `origin_trading_block`, `origin_country`, `origin_country_zone`, `origin_port`, `origin_port_or_sts_zone`, `origin_terminal`, `origin_alternative_region`, `origin_state_or_province`
+
+**Destination geography:** `destination_region`, `destination_shipping_region`, `destination_shipping_region_v2`, `destination_wider_shipping_region`, `destination_basin`, `destination_trading_region`, `destination_trading_sub_region`, `destination_trading_block`, `destination_country`, `destination_country_zone`, `destination_port`, `destination_port_or_sts_zone`, `destination_terminal`, `destination_alternative_region`, `destination_state_or_province`
+
+**Location (current):** `location_port`, `location_country`, `location_shipping_region`, `location_shipping_region_v2`, `location_wider_shipping_region`, `location_basin`, `location_country_zone`
+
+**Congestion location:** `congestion_location_port`, `congestion_location_country`, `congestion_location_shipping_region`, `congestion_location_shipping_region_v2`, `congestion_location_basin`, `congestion_location_wider_shipping_region`, `congestion_location_region`, `congestion_location_trading_region`, `congestion_location_trading_sub_region`, `congestion_location_trading_block`, `congestion_location_alternative_region`, `congestion_location_country_zone`, `congestion_location_state_or_province`
+
+**Product:** `product_group`, `product_group_product`, `product_category`, `product_grade`, `latest_product_group`, `latest_product_group_product`, `latest_product_category`, `latest_product_grade`
+
+### Response Format
+
+Each row contains `key` (timestamp), `value` (aggregate), `count`, and a `breakdown` array of `{id, label, value, count}` pairs for each split category.
+
+---
+
+## API Reference: VoyagesTimeseriesV2
+
+**Endpoint:** `POST /v5/voyages/timeseries/{metric}/{breakdown_property}`
+**SDK:** `VoyagesTimeseriesV2(metric, breakdown_property).search(...)`
+**Purpose:** Voyage-level metric aggregations with metric and breakdown set at instantiation (SDK) or in URL path (REST).
+
+### Constructor / Path Parameters
+
+| Parameter | Values |
+|---|---|
+| `metric` | `voyage-count`, `voyage-count-per-day`, `tonne-miles-sum`, `tonne-miles-sum-per-day`, `distance-avg`, `distance-voyage-avg`, `duration-avg` |
+| `breakdown_property` | `status`, `vessel-class-group`, `vessel-class-coarse`, `vessel-class-granular`, `origin-region`, `origin-shipping-region`, `origin-wider-shipping-region`, `origin-trading-region`, `origin-basin`, `origin-country`, `origin-port`, `origin-terminal`, `destination-region`, `destination-shipping-region`, `destination-wider-shipping-region`, `destination-trading-region`, `destination-basin`, `destination-country`, `destination-port`, `destination-terminal`, `location-waypoint`, `product-group`, `product-group-product`, `product-category`, `product-grade`, `corporate-entity-cargo-trader`, `corporate-entity-charterer`, `corporate-entity-effective-controller`, `corporate-entity-vessel-owner`, `corporate-entity-time-charterer` |
+
+### Search Parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `breakdown_frequency` | enum | `day` | `day`, `week`, `doe_week`, `month`, `quarter`, `year` |
+| `breakdown_size` | integer | `100` | Max breakdown categories |
+| `exclude_overlapping_entries` | boolean | `true` | De-duplicate overlapping voyages |
+
+All shared filters apply.
+
+---
+
+## API Reference: Top Hits
+
+**Endpoint:** `POST /v5/voyages/top-hits`
+**Purpose:** Count of voyages aggregated by a chosen property. Use for "busiest port", "top destination" rankings.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `breakdown_size` | integer | Number of top results |
+| `breakdown_property` | enum | Fixed: `vessel_count` |
+| `breakdown_split_property` | enum | Same options as V1 timeseries split |
+
+---
+
+## API Reference: Congestion Breakdown
+
+**Endpoint:** `POST /v5/voyages/congestion-breakdown`
+**Purpose:** Count of congested voyages by location. Use for port congestion analysis.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `breakdown_size` | integer | Number of results |
+| `breakdown_property` | enum | `port`, `terminal`, or `shipping_region` |
+| `order` | enum | `location`, `avg_wait`, `dwt`, `capacity`, `count` |
+| `order_direction` | enum | `asc` or `desc` |
+
+---
+
+## V1 vs V2 Timeseries: When to Use Which
+
+| Aspect | V1 (`VoyagesTimeseries`) | V2 (`VoyagesTimeseriesV2`) |
+|---|---|---|
+| Architecture | Single endpoint, property + split params | Metric and breakdown in constructor/URL |
+| Naming convention | Underscores (`origin_country`) | Hyphens (`origin-country`) |
+| Metrics | `vessel_count`, `cargo_quantity`, `avg_wait_time`, `dwt`, `cubic_capacity`, `tonne_miles`, `avg_distance`, `avg_speed`, `utilisation` | `voyage-count`, `voyage-count-per-day`, `tonne-miles-sum`, `tonne-miles-sum-per-day`, `distance-avg`, `distance-voyage-avg`, `duration-avg` |
+| Corporate splits | `charterer`, `effective_controller` only | Full corporate: `corporate-entity-cargo-trader`, `-charterer`, `-effective-controller`, `-vessel-owner`, `-time-charterer` |
+| Vessel owner/TC filters | Not in V1 SDK `search()` | `vessel_owners`, `time_charterer` available |
+| Use case | General vessel analytics, fleet metrics (DWT, speed, wait time, utilisation) | Voyage-level metrics, corporate breakdowns, per-day rates |
+
+**Rule of thumb:** Use V1 for vessel-perspective metrics (DWT, speed, wait time, utilisation). Use V2 for voyage-perspective metrics (voyage counts, tonne-miles sums, duration averages) especially when you need corporate entity breakdowns or per-day rates.
+
+---
+
+## Shared Filter Reference
+
+### Time & ID Filters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `time_min` | ISO 8601 | Start of time range. **Always specify explicitly.** |
+| `time_max` | ISO 8601 | End of time range. **Always specify explicitly.** |
+| `voyage_id` | string[] | Filter by specific voyage IDs |
+| `cargo_movement_id` | string[] | Filter by related cargo movement IDs |
+
+### Product Filters
+
+| Parameter | Description |
+|---|---|
+| `products` | Product IDs in the voyage's cargo |
+| `latest_products` | Product IDs of the latest cargo (current voyage if laden, previous if ballast) |
+
+### Corporate Filters
+
+| Parameter | Description |
+|---|---|
+| `charterers` | Charterer corporation IDs |
+| `effective_controllers` | Effective controller corporation IDs |
+| `vessel_owners` | Vessel owner corporation IDs (REST) |
+| `time_charterer` | Time charterer corporation IDs (REST) |
+
+### Vessel Filters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `vessels` | string[] | Vessel IDs OR vessel class strings (e.g., `oil_vlcc`, `lng_tfde_dfde`) |
+| `vessel_flags` | string[] | Flag country IDs (REST) / `flags` (SDK) |
+| `vessel_ice_class` | string[] | Ice class IDs (REST) / `ice_class` (SDK) |
+| `vessel_propulsion` | string[] | Propulsion type IDs |
+| `vessel_age_min` / `max` | number | Age in years (0-100) |
+| `vessel_dwt_min` / `max` | number | Deadweight tonnage (0-550,000) |
+| `vessel_cbm_min` / `max` | number | Cubic capacity (0-300,000) |
+| `vessel_wait_time_min` / `max` | number | Days until vessel available |
+| `vessel_scrubbers` | enum | `disabled` (default), `inc` (only with), `exc` (only without) |
+| `vessel_risk_level` | enum[] | `low`, `medium`, `high`, `sanctioned` |
+| `vessel_tags` | Tag[] | Time-bound vessel tag objects |
+| `average_speed_min` / `max` | number | Avg speed in knots (0-100) |
+
+### Toggle Filters
+
+| Parameter | Values | Description |
+|---|---|---|
+| `has_ship_to_ship` | `disabled`, `inc`, `exc` | Filter by STS occurrence |
+| `has_charterer` | `disabled`, `inc`, `exc` | Filter by charterer presence |
+
+### Behaviour Filters
+
+| Parameter | Values | Description |
+|---|---|---|
+| `voyage_date_range_activity` | `active`, `arrivals`, `departures`, `waypoint` | How time range interacts with voyages |
+| `origin_behaviour` | `first_load`, `any_load` | Which load counts for departure activity (SDK) |
+| `destination_behaviour` | `last_discharge`, `any_discharge` | Which discharge counts for arrival activity (SDK) |
+| `intra_movements` | `all`, `exclude_intra_country`, `exclude_intra_geography` | Exclude domestic/intra-region voyages |
+| `exclude_overlapping_entries` | boolean | De-duplicate overlapping voyages. **Timeseries: true; Search: false.** |
+| `event_types` | `vessel`, `cargo`, `status` | Filter which event types are returned in voyage records |
+
+---
+
+## Worked Examples
+
+### Example 1: Laden VLCC voyages from MEG to Asia
+
+**User:** "Show me all laden VLCC voyages from the Middle East to Asia this quarter"
+
+**Analysis:**
+- "laden" -> `voyage_status='laden'`
+- "VLCC" -> `vessels=['oil_vlcc']`
+- "from the Middle East" -> resolve MEG geography ID -> `origins`
+- "to Asia" -> resolve Asia geography ID -> `destinations`
+- "this quarter" -> `time_min`/`time_max` for current quarter (see date-units.md)
+- Individual records -> VoyagesSearchEnriched
+
+```python
+from vortexasdk import VoyagesSearchEnriched, Geographies
+from datetime import datetime
+
+meg = [g.id for g in Geographies().search("Middle East", filter_layer="region").to_list()]
+asia = [g.id for g in Geographies().search("Asia", filter_layer="region").to_list()]
+
+df = VoyagesSearchEnriched().search(
+    time_min=datetime(2026, 1, 1),
+    time_max=datetime(2026, 3, 31),
+    voyage_status="laden",
+    vessels=["oil_vlcc"],
+    origins=meg,
+    destinations=asia,
+    columns="all",
+).to_df()
+```
+
+### Example 2: Monthly vessel count by destination country
+
+**User:** "How many tankers arrived at European ports monthly in 2025, split by country?"
+
+**Analysis:**
+- "how many tankers" -> VoyagesTimeseries, `breakdown_property='vessel_count'`
+- "arrived" -> `voyage_date_range_activity='arrivals'`
+- "European ports" -> resolve Europe region ID -> `destinations`
+- "monthly" -> `breakdown_frequency='month'`
+- "split by country" -> `breakdown_split_property='destination_country'`
+
+```python
+from vortexasdk import VoyagesTimeseries, Geographies
+from datetime import datetime
+
+europe = [g.id for g in Geographies().search("Europe", filter_layer="region").to_list()]
+
+df = VoyagesTimeseries().search(
+    time_min=datetime(2025, 1, 1),
+    time_max=datetime(2025, 12, 31),
+    destinations=europe,
+    voyage_date_range_activity="arrivals",
+    breakdown_frequency="month",
+    breakdown_property="vessel_count",
+    breakdown_split_property="destination_country",
+).to_df()
+```
+
+### Example 3: Tonne-miles by vessel class (V2)
+
+**User:** "Show weekly tonne-miles for crude voyages in 2025, split by vessel class"
+
+**Analysis:**
+- "tonne-miles" -> metric `tonne-miles-sum` (V2 hyphen naming)
+- "split by vessel class" -> `breakdown_property='vessel-class-granular'` (V2 hyphen naming)
+- "crude" -> resolve Crude product ID -> `products`
+- "weekly" -> `breakdown_frequency='week'`
+- V2 for metric+split architecture
+
+```python
+from vortexasdk import VoyagesTimeseriesV2, Products
+from datetime import datetime
+
+crude = [p.id for p in Products().search("crude").to_list() if p.name == "Crude & Condensates"]
+
+df = VoyagesTimeseriesV2(
+    metric="tonne-miles-sum",
+    breakdown_property="vessel-class-granular",
+).search(
+    time_min=datetime(2025, 1, 1),
+    time_max=datetime(2025, 12, 31),
+    products=crude,
+    voyage_status="laden",
+    breakdown_frequency="week",
+).to_df()
+```
+
+### Example 4: Port congestion analysis
+
+**User:** "Which ports have the worst congestion for LNG carriers right now?"
+
+**Analysis:**
+- "congestion" -> Congestion breakdown endpoint
+- "worst" -> order by `avg_wait` descending
+- "LNG carriers" -> `vessels=['lng']`
+- "right now" -> last 7 days
+
+```python
+import requests
+from datetime import datetime, timedelta
+
+headers = {"x-api-key": VORTEXA_API_KEY}
+payload = {
+    "time_min": (datetime.now() - timedelta(days=7)).isoformat() + "Z",
+    "time_max": datetime.now().isoformat() + "Z",
+    "vessels": ["lng"],
+    "breakdown_property": "port",
+    "order": "avg_wait",
+    "order_direction": "desc",
+    "breakdown_size": 20,
+}
+
+response = requests.post(
+    "https://api.vortexa.com/v5/voyages/congestion-breakdown",
+    headers=headers,
+    json=payload,
+)
+data = response.json()
+```
+
+### Example 5: Ballast fleet positioning (supply indicator)
+
+**User:** "How many ballast VLCCs are heading to the MEG this month?"
+
+**Analysis:**
+- "ballast" -> `voyage_status='ballast'`
+- "VLCCs" -> `vessels=['oil_vlcc']`
+- "heading to the MEG" -> resolve MEG ID -> `destinations` (for ballast, this means next load port)
+- "this month" -> current month date range
+- "how many" but wants vessel list -> VoyagesSearchEnriched for detail
+
+```python
+from vortexasdk import VoyagesSearchEnriched, Geographies
+from datetime import datetime
+
+meg = [g.id for g in Geographies().search("Middle East", filter_layer="region").to_list()]
+
+df = VoyagesSearchEnriched().search(
+    time_min=datetime(2026, 2, 1),
+    time_max=datetime(2026, 2, 28),
+    voyage_status="ballast",
+    vessels=["oil_vlcc"],
+    destinations=meg,
+    voyage_date_range_activity="active",
+    columns=["vessel_name", "imo", "dwt", "origin_country", "destination_country",
+             "start_date", "distance", "duration"],
+).to_df()
+```
+
+### Example 6: Fleet DWT utilisation over time with split
+
+**User:** "Show me total laden DWT by shipping region for Suezmaxes, monthly"
+
+**Analysis:**
+- "DWT" -> `breakdown_property='dwt'` (V1 metric)
+- "by shipping region" -> `breakdown_split_property='destination_shipping_region_v2'` (V1 underscore naming)
+- "Suezmaxes" -> `vessels=['oil_suezmax']`
+- "monthly" -> `breakdown_frequency='month'`
+- V1 for DWT metric
+
+```python
+from vortexasdk import VoyagesTimeseries
+from datetime import datetime
+
+df = VoyagesTimeseries().search(
+    time_min=datetime(2025, 1, 1),
+    time_max=datetime(2025, 12, 31),
+    voyage_status="laden",
+    vessels=["oil_suezmax"],
+    breakdown_frequency="month",
+    breakdown_property="dwt",
+    breakdown_split_property="destination_shipping_region_v2",
+).to_df()
+```
+
+---
+
+## CM-Authoritative OOW Pattern (Preview)
+
+For accurate oil-on-water (OOW) volumes broken down by region, **CargoMovements provides authoritative volumes** while **VoyagesSearchEnriched provides location enrichment**.
+
+**Why not just use Voyages for OOW?** Voyages tracks the vessel, not the cargo. A single vessel may carry multiple parcels, and cargo quantities are authoritative only in CargoMovements (0% variance from CargoTimeSeries).
+
+**High-level pattern:**
+1. Query CargoMovements with `cargo_on_water_state` for authoritative OOW periods and quantities
+2. Query VoyagesSearchEnriched for vessel location data (shipping_region from events)
+3. Join on `cargo_movement_id` (16-char truncated) to enrich CM cargoes with voyage location
+4. Query location at end of day for the latest region assignment
+5. Full-day counting: if OOW period overlaps a day at all, count full quantity
+
+**When a user asks "OOW by region":** Use this CM-Authoritative pattern. Do NOT use VoyagesTimeseries alone -- it will give vessel counts or DWT, not cargo volumes.
+
+Full implementation details will be in the cargo-movements.md context document and the OOW skill.
+
+---
+
+## Defaults and Common Pitfalls
+
+| Parameter | Default | Pitfall | Fix |
+|---|---|---|---|
+| `time_min/max` | Current timestamp | Silently returns only current data | Always specify explicitly |
+| `size` (search) | `1` | Returns only 1 record | Set to 500 for batch retrieval |
+| `voyage_date_range_activity` | `active` | Returns all voyages touching the window, may overcount | Use `arrivals`/`departures` for event-anchored counting |
+| `exclude_overlapping_entries` | `true` (TS), `false` (search) | Double-counting in search, dedup in timeseries | Set explicitly based on intent |
+| `breakdown_frequency` | `day` | Too granular for long ranges | Use `month` for >3 months |
+| `breakdown_property` (V1) | `vessel_count` | Wrong metric silently | Override for DWT, tonne-miles, speed |
+| `breakdown_split_property` | `none` | No breakdown returned | Set to split by geography, vessel class, etc. |
+| `breakdown_size` | `100` | Categories beyond 100 grouped as "Other" | Increase for many-category splits |
+| `unit` | `b` (barrels) | Wrong for LNG/LPG | Use `t` for LNG/LPG, `cbm` for LNG volume |
+| `vessel_scrubbers` | `disabled` | No filter applied | Use `inc`/`exc` when scrubber status matters |
+| `intra_movements` | `all` | Includes domestic voyages | Exclude for international-only analysis |
+
+---
+
+## Error Recovery
+
+**Empty results?** Check in this order:
+1. Are entity IDs correct? Re-run geography/product search to verify (see entity-resolution.md)
+2. Is the time range reasonable? Voyages need non-trivial windows
+3. Is `voyage_date_range_activity` appropriate? `active` is broadest; `arrivals`/`departures` are narrower
+4. For search: is `size` still set to 1 (default)?
+5. Are status filters too restrictive? Remove filters one at a time
+6. Is `intra_movements` excluding data? Try `all` first
+
+**Unexpected counts / double-counting?**
+1. Check `exclude_overlapping_entries` -- `false` can double-count days with overlapping voyages
+2. Verify `voyage_date_range_activity` matches intent -- `active` counts every voyage that touched the window, not just those that started/ended in it
+3. For ballast voyages, `origins` means the last discharge port and `destinations` means the next load port -- this is inverted from laden logic
+
+**V1 vs V2 confusion?**
+- V2 uses hyphens (`tonne-miles-sum`, `origin-country`); V1 uses underscores (`tonne_miles`, `origin_country`)
+- V2 metric + breakdown are constructor args; V1 they are search params
+- Mixing naming conventions will silently fail or return errors
+
+---
+
+## Validation Rules
+
+1. `time_min` must be before `time_max`
+2. `size` for search defaults to 1 -- set to 500 for batch retrieval
+3. All ID filters require valid Vortexa hex hash IDs (see entity-resolution.md)
+4. `vessel_age_min/max`: 0-100 years
+5. `vessel_dwt_min/max`: 0-550,000 tonnes
+6. `vessel_cbm_min/max`: 0-300,000 cubic metres
+7. `average_speed_min/max`: 0-100 knots
+8. For pagination, use `search_after` from previous response's `next_request`
+9. `breakdown_size` max is 10,000

package/lib/__init__.py

@@ -0,0 +1,4 @@
+"""Vortexa Analytics -- Python function library for commodity/energy data."""
+__version__ = "0.1.0"
+
+from lib.entities import resolve, disambiguate, EntityCache