vortexa-claude-skills 1.0.0

package/lib/aliases.json

@@ -0,0 +1,52 @@
+{
+  "geography": {
+    "AG": {"official": "Arabian Gulf", "layer": "shipping_region_v2"},
+    "MEG": {"official": "Middle East Gulf", "layer": "shipping_region_v2"},
+    "KSA": {"official": "Saudi Arabia", "layer": "country"},
+    "USG": {"official": "US Gulf Coast", "layer": "shipping_region_v2"},
+    "WAF": {"official": "West Africa", "layer": "shipping_region_v2"},
+    "PADD I": {"official": "US Atlantic Coast", "layer": "shipping_region_v2"},
+    "PADD 1": {"official": "US Atlantic Coast", "layer": "shipping_region_v2"},
+    "ARA": {"official": ["Amsterdam", "Rotterdam", "Antwerp"], "layer": "port", "multi": true},
+    "NWE": {"official": "Northwest Europe", "layer": "shipping_region_v2"},
+    "SEA": {"official": "Southeast Asia", "layer": "shipping_region_v2"},
+    "NEA": {"official": "Northeast Asia", "layer": "shipping_region_v2"},
+    "Med": {"official": "Mediterranean", "layer": "shipping_region_v2"},
+    "SAEC": {"official": "South America East Coast", "layer": "shipping_region_v2"},
+    "USWC": {"official": "US West Coast", "layer": "shipping_region_v2"},
+    "USAC": {"official": "US Atlantic Coast", "layer": "shipping_region_v2"},
+    "US": {"official": "United States", "layer": "country"},
+    "UAE": {"official": "United Arab Emirates", "layer": "country"},
+    "UK": {"official": "United Kingdom", "layer": "country"}
+  },
+  "product": {
+    "CPP": {"official": "Clean Petroleum Products", "layer": "group"},
+    "DPP": {"official": "Dirty Petroleum Products", "layer": "group"},
+    "crude": {"official": "Crude & Condensates", "layer": "group"},
+    "HSFO": {"official": "High Sulphur Fuel Oil", "layer": "category"},
+    "LSFO": {"official": "Low Sulphur Fuel Oil", "layer": "category"},
+    "ULSD": {"official": "ULSD", "layer": "grade"},
+    "mogas": {"official": "Gasoline / Mogas", "layer": "group_product"},
+    "gasoil": {"official": "Gasoil/Diesel", "layer": "group_product"},
+    "jet": {"official": "Jet/Kero", "layer": "group_product"},
+    "naphtha": {"official": "Naphtha", "layer": "group_product"},
+    "fuel oil": {"official": "Fuel Oil", "layer": "group_product"},
+    "condensate": {"official": "Condensate", "layer": "group_product"}
+  },
+  "vessel_class": {
+    "VLCC": "oil_vlcc",
+    "Suezmax": "oil_suezmax",
+    "Aframax": "oil_aframax",
+    "Panamax": "oil_panamax",
+    "MR": "oil_mr2",
+    "MR2": "oil_mr2",
+    "MR1": "oil_mr1",
+    "LR1": "oil_lr1",
+    "LR2": "oil_lr2",
+    "Handymax": "oil_handymax",
+    "Handysize": "oil_handysize",
+    "VLGC": "lpg_vlgc",
+    "LGC": "lpg_lgc",
+    "MGC": "lpg_mgc"
+  }
+}

package/lib/api.py

@@ -0,0 +1,20 @@
+"""Vortexa API authentication and HTTP utilities."""
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def get_api_key():
+    """Return the Vortexa API key from environment.
+
+    Raises EnvironmentError with clear instructions if not set.
+    """
+    key = os.environ.get("VORTEXA_API_KEY")
+    if not key:
+        raise EnvironmentError(
+            "VORTEXA_API_KEY not set. "
+            "Run /vortexa:init to set up your environment, "
+            "or add VORTEXA_API_KEY to your .env file."
+        )
+    return key

package/lib/entities.py

@@ -0,0 +1,254 @@
+"""Entity ID resolution -- translates human names to Vortexa hex IDs."""
+
+import json
+from pathlib import Path
+
+_aliases = None
+
+
+def _load_aliases():
+    global _aliases
+    if _aliases is None:
+        path = Path(__file__).parent / "aliases.json"
+        with open(path) as f:
+            _aliases = json.load(f)
+    return _aliases
+
+
+class EntityCache:
+    """Per-session cache for resolved entity IDs."""
+
+    def __init__(self):
+        self._cache = {}
+
+    def get(self, term, entity_type, layer=None):
+        key = (term.lower().strip(), entity_type, layer)
+        return self._cache.get(key)
+
+    def put(self, term, entity_type, layer, hex_id):
+        key = (term.lower().strip(), entity_type, layer)
+        self._cache[key] = hex_id
+
+    def clear(self):
+        self._cache.clear()
+
+
+def resolve(term, entity_type=None, layer=None, cache=None):
+    """Resolve a human-readable name to a Vortexa 64-char hex ID.
+
+    Returns (hex_id, []) on single match, (None, candidates) on multiple,
+    (None, []) on zero matches.
+    """
+    aliases = _load_aliases()
+    term_stripped = term.strip()
+    term_lower = term_stripped.lower()
+
+    # Check cache
+    if cache is not None:
+        cached = cache.get(term_stripped, entity_type, layer)
+        if cached is not None:
+            return cached, []
+
+    # Check alias map -- auto-detect entity_type if not provided
+    alias_entry = None
+    alias_type = entity_type
+
+    if entity_type:
+        section = aliases.get(entity_type, {})
+        for alias_key, val in section.items():
+            if alias_key.lower() == term_lower:
+                alias_entry = val
+                break
+    else:
+        for section_name in ("geography", "product", "vessel_class"):
+            section = aliases.get(section_name, {})
+            for alias_key, val in section.items():
+                if alias_key.lower() == term_lower:
+                    alias_entry = val
+                    alias_type = section_name
+                    break
+            if alias_entry is not None:
+                break
+
+    # Vessel class: return SDK class string directly
+    if alias_type == "vessel_class":
+        if alias_entry is not None:
+            sdk_class = alias_entry if isinstance(alias_entry, str) else alias_entry
+            if cache is not None:
+                cache.put(term_stripped, "vessel_class", None, sdk_class)
+            return sdk_class, []
+        return None, []
+
+    # Expand alias to official name + layer
+    if alias_entry is not None:
+        if isinstance(alias_entry, dict):
+            if alias_entry.get("multi"):
+                # Multi-entity alias (e.g. ARA -> multiple ports)
+                ids = []
+                official_list = alias_entry["official"]
+                entry_layer = alias_entry.get("layer", layer)
+                for name in official_list:
+                    hex_id, _ = _resolve_by_type(name, alias_type, entry_layer)
+                    if hex_id:
+                        ids.append(hex_id)
+                if cache is not None and ids:
+                    cache.put(term_stripped, alias_type, entry_layer, ids)
+                return (ids if ids else None), []
+            term_stripped = alias_entry["official"]
+            layer = alias_entry.get("layer", layer)
+        else:
+            term_stripped = alias_entry
+
+    if alias_type is None:
+        return None, [{"error": "entity_type required -- could not auto-detect from alias map"}]
+
+    hex_id, candidates = _resolve_by_type(term_stripped, alias_type, layer)
+
+    if hex_id and cache is not None:
+        cache.put(term.strip(), alias_type, layer, hex_id)
+
+    return hex_id, candidates
+
+
+def _resolve_by_type(term, entity_type, layer=None):
+    """Route to the correct type-specific resolver."""
+    if entity_type == "geography":
+        return resolve_geography(term, layer)
+    elif entity_type == "product":
+        return resolve_product(term, layer)
+    elif entity_type == "vessel":
+        return resolve_vessel(term)
+    elif entity_type == "corporate":
+        return resolve_corporate(term)
+    return None, []
+
+
+def resolve_geography(term, layer=None, exact=False):
+    """Resolve a geography name to Vortexa hex ID."""
+    from vortexasdk import Geographies
+
+    results = Geographies().search(
+        term=term, filter_layer=layer,
+        exact_term_match=exact,
+    ).to_df()
+
+    if results.empty:
+        return None, []
+
+    if layer and "layer" in results.columns:
+        exact_layer = results[results["layer"].apply(
+            lambda x: x == layer if isinstance(x, str) else layer in x if isinstance(x, list) else False
+        )]
+        if not exact_layer.empty:
+            results = exact_layer
+
+    if len(results) == 1:
+        return results.iloc[0]["id"], []
+
+    candidates = _extract_candidates(results, "layer")
+    return None, candidates
+
+
+def resolve_product(term, layer=None, exact=False):
+    """Resolve a product name to Vortexa hex ID."""
+    from vortexasdk import Products
+
+    results = Products().search(
+        term=term, filter_layer=layer,
+        exact_term_match=exact,
+    ).to_df()
+
+    if results.empty:
+        return None, []
+
+    if layer and "layer" in results.columns:
+        exact_layer = results[results["layer"].apply(
+            lambda x: x == layer if isinstance(x, str) else layer in x if isinstance(x, list) else False
+        )]
+        if not exact_layer.empty:
+            results = exact_layer
+
+    if len(results) == 1:
+        return results.iloc[0]["id"], []
+
+    candidates = _extract_candidates(results, "layer")
+    return None, candidates
+
+
+def resolve_vessel(term, vessel_classes=None):
+    """Resolve a vessel name to Vortexa hex ID."""
+    from vortexasdk import Vessels
+
+    kwargs = {"term": term}
+    if vessel_classes:
+        kwargs["vessel_classes"] = vessel_classes
+
+    results = Vessels().search(**kwargs).to_df()
+
+    if results.empty:
+        return None, []
+
+    if len(results) == 1:
+        return results.iloc[0]["id"], []
+
+    candidates = []
+    for _, row in results.head(3).iterrows():
+        candidates.append({
+            "name": row.get("name", ""),
+            "layer": row.get("vessel_class", ""),
+            "parent": str(row.get("imo", "")),
+            "id": row["id"],
+        })
+    return None, candidates
+
+
+def resolve_corporate(term, exact=False):
+    """Resolve a corporate entity name to Vortexa hex ID."""
+    from vortexasdk import Corporations
+
+    results = Corporations().search(
+        term=term, exact_term_match=exact,
+    ).to_df()
+
+    if results.empty:
+        return None, []
+
+    if len(results) == 1:
+        return results.iloc[0]["id"], []
+
+    candidates = _extract_candidates(results, "corporate_entity_type")
+    return None, candidates
+
+
+def _extract_candidates(results, layer_col="layer"):
+    """Extract top 3 candidates from search results for disambiguation."""
+    candidates = []
+    for _, row in results.head(3).iterrows():
+        layer_val = row.get(layer_col, "")
+        if isinstance(layer_val, list):
+            layer_val = ", ".join(str(x) for x in layer_val)
+        parent = ""
+        for col in ("parent", "leaf"):
+            if col in row.index and row[col]:
+                val = row[col]
+                if isinstance(val, list) and val:
+                    parent = str(val[0].get("name", "")) if isinstance(val[0], dict) else str(val[0])
+                elif isinstance(val, dict):
+                    parent = str(val.get("name", ""))
+                elif isinstance(val, str):
+                    parent = val
+                break
+        candidates.append({
+            "name": row.get("name", ""),
+            "layer": str(layer_val),
+            "parent": parent,
+            "id": row["id"],
+        })
+    return candidates
+
+
+def disambiguate(matches, term):
+    """Format top 3 matches for user presentation. Returns list of candidate dicts."""
+    if not matches:
+        return []
+    return matches[:3]

package/lib/inventory.py

@@ -0,0 +1,140 @@
+"""LNG and onshore inventory queries."""
+
+import os
+
+import pandas as pd
+import requests
+
+
+def lng_inventory_timeseries(
+    time_min, time_max,
+    unit_operator="fill",
+    split_property="location_country",
+    unit="cbm",
+    location_ids=None,
+    terminal_ids=None,
+    storage_type=None,
+):
+    """Query LNG inventory timeseries via REST API. Returns wide DataFrame."""
+    api_key = os.environ.get("VORTEXA_API_KEY")
+    base_url = "https://api.vortexa.com/v5/lng-inventories/timeseries"
+
+    payload = {
+        "timeseries_unit_operator": unit_operator,
+        "timeseries_split_property": split_property,
+        "timeseries_frequency": "day",
+        "timeseries_unit": unit,
+        "order": "gas_day",
+        "order_direction": "asc",
+        "size": 500,
+        "time_min": time_min.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+        "time_max": time_max.strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+    }
+    if location_ids:
+        payload["location_ids"] = location_ids
+    if terminal_ids:
+        payload["terminal_ids"] = terminal_ids
+    if storage_type:
+        payload["storage_type"] = storage_type
+
+    headers = {"x-api-key": api_key, "Content-Type": "application/json"}
+    response = requests.post(base_url, json=payload, headers=headers)
+    response.raise_for_status()
+
+    data = response.json()
+    timeseries_data = data.get("data", [])
+
+    if not timeseries_data:
+        return pd.DataFrame()
+
+    if split_property == "quantity":
+        records = [{"date": entry["key"], "value": entry.get("value", 0)} for entry in timeseries_data]
+        df = pd.DataFrame(records)
+        df["date"] = pd.to_datetime(df["date"])
+        df = df.set_index("date").sort_index()
+        df.columns = ["Total"]
+    else:
+        records = [
+            {"date": entry["key"], "label": item["label"], "value": item["value"]}
+            for entry in timeseries_data
+            for item in entry.get("breakdown", [])
+        ]
+        df = pd.DataFrame(records)
+        df["date"] = pd.to_datetime(df["date"])
+        df = df.pivot(index="date", columns="label", values="value").fillna(0).sort_index()
+        df["Total"] = df.sum(axis=1)
+        df.columns.name = None
+
+    return df
+
+
+def topn_onshore_inventory_timeseries(
+    *,
+    time_min,
+    time_max,
+    location_id,
+    frequency="weekly",
+    top_n=10,
+    storage_types=None,
+    unit_operator="fill",
+    unit="b",
+):
+    """Onshore inventories Top-N terminals via SDK. Returns wide DataFrame."""
+    from vortexasdk import OnshoreInventoriesTimeseries
+
+    freq_map = {
+        "weekly": "week", "week": "week", "w": "week",
+        "monthly": "month", "month": "month", "m": "month",
+    }
+    freq = freq_map.get(frequency.lower())
+    if freq not in {"week", "month"}:
+        raise ValueError("frequency must be weekly or monthly")
+
+    res = OnshoreInventoriesTimeseries().search(
+        location_ids=[location_id],
+        time_min=time_min,
+        time_max=time_max,
+        timeseries_frequency=freq,
+        timeseries_split_property="storage_terminal",
+        timeseries_unit_operator=unit_operator,
+        timeseries_unit=unit,
+        storage_types=list(storage_types) if storage_types else None,
+    ).to_list()
+
+    if not res:
+        return pd.DataFrame(columns=["date", "Other"])
+
+    def _val(x, k):
+        if hasattr(x, k):
+            return getattr(x, k)
+        if isinstance(x, dict):
+            return x.get(k)
+        return None
+
+    rows = []
+    for it in res:
+        d = pd.to_datetime(getattr(it, "key"))
+        t = float(getattr(it, "value", 0.0) or 0.0)
+        b = getattr(it, "breakdown", None) or []
+        if not b:
+            rows.append((d, "Other", t))
+        else:
+            s = 0.0
+            for x in b:
+                val = float(_val(x, "value") or 0.0)
+                lab = _val(x, "label") or _val(x, "name") or _val(x, "id") or "Unknown"
+                rows.append((d, lab, val))
+                s += val
+            rows.append((d, "Other", max(t - s, 0.0)))
+
+    df = pd.DataFrame(rows, columns=["date", "series", "value"])
+    means = df[df.series != "Other"].groupby("series")["value"].mean().nlargest(top_n)
+    keep = set(means.index)
+    df["series"] = df["series"].where(df["series"].isin(keep) | (df["series"] == "Other"), "Other")
+
+    df_p = df.groupby(["date", "series"], as_index=False)["value"].sum()
+    wide = df_p.pivot(index="date", columns="series", values="value").fillna(0.0)
+    ordered = [s for s in means.index if s in wide.columns] + (["Other"] if "Other" in wide.columns else [])
+    wide = wide.reindex(columns=ordered).reset_index()
+
+    return wide