vortexa-claude-skills 1.0.0

package/lib/visualization.py

@@ -0,0 +1,164 @@
+"""Plotly chart builders with Vortexa brand theme.
+
+Theme auto-registers on import. All chart functions accept DataFrames
+and return go.Figure objects without calling the Vortexa API.
+"""
+
+import plotly.graph_objects as go
+import plotly.io as pio
+import plotly.express as px
+
+
+# -- Vortexa dark theme --------------------------------------------------------
+
+vortexa_colors = [
+    '#0090B9', '#A1F3FF', '#A891F4', '#A2DB40', '#0E534D',
+    '#20E1C7', '#FFA1B7', '#6B32CF', '#518FE0', '#F4C160',
+    '#B07E1E', '#124E67', '#FF6B90', '#850E9A', '#2F4F9E',
+    '#72ADE8', '#EB8F4C', '#D7581F', '#8B1043', '#4A0055',
+]
+
+pio.templates["vortexa_dark"] = go.layout.Template(
+    layout={
+        'colorway': vortexa_colors,
+        'paper_bgcolor': '#0f172a',
+        'plot_bgcolor': '#1e293b',
+        'font': {'family': 'Arial, Helvetica, sans-serif', 'size': 13, 'color': '#e2e8f0'},
+        'title': {'font': {'size': 18, 'color': '#ffffff'}},
+        'xaxis': {'gridcolor': '#334155', 'linecolor': '#475569', 'zerolinecolor': '#475569'},
+        'yaxis': {'gridcolor': '#334155', 'linecolor': '#475569', 'zerolinecolor': '#475569'},
+        'hovermode': 'x unified',
+        'legend': {'bgcolor': 'rgba(0,0,0,0)', 'font': {'color': '#e2e8f0'}},
+    }
+)
+pio.templates.default = "vortexa_dark"
+
+
+# -- Chart functions -----------------------------------------------------------
+
+def seasonal_chart(data, title="Seasonal Pattern", y_label="Volume"):
+    """Multi-year seasonal overlay with min/max band, average, last year, current year.
+
+    Accepts the DataFrame from seasonal_charts() in lib/seasonal.py.
+    Columns: Date, Min., Range Y1-Y2, Average Y1-Y2, Last year, Current year.
+    """
+    df = data.copy()
+    cols = list(df.columns)
+
+    fig = go.Figure()
+
+    # Invisible min trace as band baseline
+    fig.add_trace(go.Scatter(
+        x=df[cols[0]], y=df["Min."], mode="lines",
+        line=dict(width=0), showlegend=False, hoverinfo="skip",
+    ))
+
+    # Range band filled to min trace
+    range_col = cols[1]
+    fig.add_trace(go.Scatter(
+        x=df[cols[0]], y=df["Min."] + df[range_col],
+        fill="tonexty", fillcolor="rgba(0,144,185,0.15)",
+        line=dict(width=0), name=range_col,
+    ))
+
+    # Average line
+    avg_col = cols[2]
+    fig.add_trace(go.Scatter(
+        x=df[cols[0]], y=df[avg_col], mode="lines",
+        name=avg_col, line=dict(color=vortexa_colors[0], width=2),
+    ))
+
+    # Last year dashed
+    if "Last year" in df.columns:
+        fig.add_trace(go.Scatter(
+            x=df[cols[0]], y=df["Last year"], mode="lines",
+            name="Last year", line=dict(color=vortexa_colors[9], dash="dash", width=2),
+        ))
+
+    # Current year (forward-looking -- filter out empty values)
+    if "Current year" in df.columns:
+        cy = df[df["Current year"] != ""].copy()
+        if not cy.empty:
+            fig.add_trace(go.Scatter(
+                x=cy[cols[0]], y=cy["Current year"], mode="lines",
+                name="Current year",
+                line=dict(color=vortexa_colors[5], width=3),
+                connectgaps=False,
+            ))
+
+    fig.update_layout(title=title, yaxis_title=y_label)
+    return fig
+
+
+def oow_area_chart(ts_wide, freq="daily", top_n=8, title=None):
+    """Stacked area chart for cargo-on-water by location.
+
+    Accepts wide DataFrame from cargo_on_water_ts() in lib/movements.py
+    (date index, location columns, optional Total column).
+    """
+    ts = ts_wide.copy()
+
+    if "Total" in ts.columns:
+        ts = ts.drop(columns=["Total"])
+
+    freq_map = {"weekly": "W-SUN", "monthly": "MS"}
+    if freq.lower() in freq_map:
+        ts = ts.resample(freq_map[freq.lower()]).sum()
+
+    from lib.utils import top_n_with_other
+    ts = top_n_with_other(ts, n=top_n)
+
+    plot_df = ts.reset_index().rename(columns={ts.index.name or "index": "date"})
+    ycols = [c for c in plot_df.columns if c != "date"]
+
+    fig = px.area(
+        plot_df, x="date", y=ycols,
+        title=title or f"Cargo on Water by Region (Top {top_n})",
+        template="vortexa_dark",
+    )
+    fig.update_traces(stackgroup="one")
+    fig.update_layout(xaxis_rangeslider_visible=True)
+    return fig
+
+
+def flow_split_bars(plot_df, title="Flow Split", y_label="Volume"):
+    """Stacked bar chart for breakdown results.
+
+    Accepts wide DataFrame from flows_time_series_split() in lib/timeseries.py
+    (date index or column, category columns, optional Total column).
+    """
+    df = plot_df.copy()
+
+    # Detect and normalise date column
+    if "date" not in df.columns and "Date" not in df.columns:
+        df = df.reset_index()
+    if "Date" in df.columns and "date" not in df.columns:
+        df = df.rename(columns={"Date": "date"})
+
+    cols = [c for c in df.columns if c not in ("date", "Date", "Total")]
+
+    fig = px.bar(
+        df, x="date", y=cols, barmode="stack",
+        title=title, template="vortexa_dark",
+    )
+    fig.update_layout(yaxis_title=y_label)
+    return fig
+
+
+def comparison_overlay_chart(series_dict, x_labels, title="Comparison", y_label="Volume"):
+    """Overlay N series on the same chart for period or region comparison.
+
+    series_dict: mapping of series name to list of values, e.g. {"2025": [...], "2024": [...]}.
+    x_labels: common x-axis labels, e.g. ["Jan", "Feb", ...].
+    """
+    fig = go.Figure()
+
+    for i, (name, values) in enumerate(series_dict.items()):
+        fig.add_trace(go.Scatter(
+            x=x_labels, y=values, mode="lines+markers",
+            name=name,
+            line=dict(color=vortexa_colors[i % len(vortexa_colors)], width=2),
+        ))
+
+    fig.update_layout(title=title, yaxis_title=y_label)
+    return fig

package/lib/voyages.py

@@ -0,0 +1,236 @@
+"""Voyage queries and enriched search utilities."""
+
+from datetime import timedelta
+
+import pandas as pd
+
+from lib.utils import _to_dt, _cols
+
+
+_keep_cols = [
+    "VOYAGE ID", "IMO", "VESSEL NAME", "VESSEL CLASS", "VOYAGE STATUS",
+    "START DATE", "END DATE",
+    "LATEST PRODUCT GROUP", "LATEST PRODUCT",
+    "ORIGIN PORT", "DESTINATION SHIPPING REGION", "DESTINATION PORT",
+]
+
+
+def live_voyages_now(
+    now, destination_id, vessel_type, voyage_status,
+    latest_product_group=None,
+):
+    """Query live voyages with fallback to 30-day window."""
+    from vortexasdk import VoyagesSearchEnriched
+
+    def run_query(tmin, tmax):
+        return VoyagesSearchEnriched().search(
+            time_min=tmin, time_max=tmax,
+            voyage_date_range_activity="active",
+            voyage_status=voyage_status,
+            destinations=[destination_id],
+            vessels=[vessel_type],
+            movement_status="moving",
+            columns="all",
+        ).to_df()
+
+    def filter_product(df):
+        if latest_product_group is None or df.empty or "LATEST PRODUCT GROUP" not in df.columns:
+            return df
+        key = latest_product_group.strip().lower()
+        return df[df["LATEST PRODUCT GROUP"].astype(str).str.strip().str.lower() == key]
+
+    def select_cols(df):
+        cols = [c for c in _keep_cols if c in df.columns]
+        return df[cols].reset_index(drop=True)
+
+    df_live = filter_product(run_query(now, now))
+    if not df_live.empty:
+        return select_cols(df_live)
+
+    df_30 = filter_product(run_query(now - timedelta(days=30), now))
+    if not df_30.empty:
+        print("No live voyages. Showing last 30 days.")
+        return select_cols(df_30)
+
+    print("No voyages found (live or last 30 days).")
+    return pd.DataFrame(columns=_keep_cols)
+
+
+def voyages_ts_with_alerts(
+    time_min, time_max, destination_id, vessel_type,
+    voyage_status, latest_products=None,
+):
+    """Voyage timeseries with percentile alert bands.
+
+    Returns (ts_dataframe, alert_stats_dict) where alert_stats_dict
+    contains p20, p80 thresholds for downstream visualization.
+    """
+    import numpy as np
+    from vortexasdk import VoyagesTimeseries
+
+    lp = None
+    if latest_products not in (None, "None", [], ()):
+        lp = list(latest_products) if isinstance(latest_products, (list, tuple, set)) else [latest_products]
+
+    kwargs = dict(
+        time_min=time_min, time_max=time_max,
+        voyage_status=voyage_status,
+        destinations=[destination_id],
+        vessels=[vessel_type],
+        movement_status="moving",
+        voyage_date_range_activity="active",
+        breakdown_property="vessel_count",
+        breakdown_frequency="day",
+    )
+    if lp:
+        kwargs["latest_products"] = lp
+
+    ts_raw = VoyagesTimeseries().search(**kwargs).to_df()
+
+    if {"key", "value"}.issubset(ts_raw.columns):
+        ts = ts_raw[["key", "value"]].rename(columns={"key": "date", "value": "count"})
+    else:
+        date_col = "date" if "date" in ts_raw.columns else ts_raw.columns[0]
+        val_col = "value" if "value" in ts_raw.columns else ts_raw.columns[-1]
+        ts = ts_raw[[date_col, val_col]].rename(columns={date_col: "date", val_col: "count"})
+
+    ts["date"] = pd.to_datetime(ts["date"]).dt.floor("D")
+    if ts.empty:
+        return ts.assign(count=0.0), {"p20": 0.0, "p80": 0.0}
+
+    full_idx = pd.date_range(ts["date"].min(), ts["date"].max(), freq="D")
+    ts = (
+        ts.set_index("date")
+        .reindex(full_idx, fill_value=0.0)
+        .rename_axis("date")
+        .reset_index()
+    )
+    ts["count"] = ts["count"].astype(float)
+
+    p20 = float(np.percentile(ts["count"], 20))
+    p80 = float(np.percentile(ts["count"], 80))
+
+    return ts, {"p20": p20, "p80": p80}
+
+
+def post_ballast_distribution_and_medians(
+    origin_ids, destination_ids,
+    time_min, time_max,
+    vessels="oil_aframax",
+    latest_products=None,
+    split_layer="FINAL DESTINATION SHIPPING REGION",
+    top_n=5,
+):
+    """Post-discharge ballast analysis with destination distribution and median durations.
+
+    Returns dict with keys: cohort, detail, counts_monthly, proportions_monthly, medians.
+    """
+    from vortexasdk import VoyagesSearchEnriched
+
+    tmin, tmax = _to_dt(time_min), _to_dt(time_max)
+
+    cohort = VoyagesSearchEnriched().search(
+        origins=list(origin_ids or []),
+        destinations=list(destination_ids or []),
+        time_min=tmin, time_max=tmax,
+        vessels=[vessels] if isinstance(vessels, str) else list(vessels or []),
+        voyage_status="laden",
+        voyage_date_range_activity="arrivals",
+        columns="all",
+        latest_products=(list(latest_products) if latest_products not in (None, [], ()) else None),
+    ).to_df()
+
+    empty_result = {
+        "cohort": pd.DataFrame(), "detail": pd.DataFrame(),
+        "counts_monthly": pd.DataFrame(), "proportions_monthly": pd.DataFrame(),
+        "medians": pd.DataFrame(),
+    }
+
+    if cohort is None or cohort.empty:
+        return empty_result
+
+    cohort["END DATE"] = _to_dt(cohort["END DATE"])
+    cohort = (
+        cohort.dropna(subset=["END DATE", "NEXT VOYAGE ID"])
+        .loc[cohort["END DATE"] <= tmax]
+        .copy()
+    )
+    if cohort.empty:
+        return empty_result
+
+    next_ids = cohort["NEXT VOYAGE ID"].astype(str).str.strip()
+    next_ids = next_ids[next_ids.ne("")].unique().tolist()
+    if not next_ids:
+        return empty_result
+
+    nxt = VoyagesSearchEnriched().search(voyage_id=next_ids, columns="all").to_df()
+    if nxt is None or nxt.empty:
+        return empty_result
+
+    nxt["START DATE"] = _to_dt(nxt["START DATE"])
+    nxt["END DATE"] = _to_dt(nxt["END DATE"])
+    nxt = nxt.dropna(subset=["START DATE", "END DATE"]).copy()
+    nxt = nxt[nxt["VOYAGE STATUS"].astype(str).str.upper().eq("BALLAST")].copy()
+    if nxt.empty:
+        return empty_result
+
+    base = cohort[_cols(cohort, ["IMO", "VESSEL NAME", "VOYAGE ID", "NEXT VOYAGE ID"])].copy()
+    j = base.merge(nxt, left_on="NEXT VOYAGE ID", right_on="VOYAGE ID", how="inner", suffixes=("_COHORT", "_NEXT"))
+
+    label_col = None
+    for candidate in [split_layer, "FINAL DESTINATION SHIPPING REGION", "DESTINATION SHIPPING REGION"]:
+        if candidate in j.columns:
+            label_col = candidate
+            break
+
+    j["duration_days"] = (j["END DATE"] - j["START DATE"]).dt.days
+
+    keep = ["IMO", "VESSEL NAME", "VOYAGE ID_COHORT", "NEXT VOYAGE ID", "START DATE", "END DATE", "duration_days", "VOYAGE STATUS"]
+    if label_col:
+        keep.append(label_col)
+    detail = j[_cols(j, keep)].copy()
+    if label_col:
+        detail = detail.rename(columns={label_col: "BALLAST DEST SPLIT"})
+
+    if detail.empty or "BALLAST DEST SPLIT" not in detail.columns:
+        return empty_result
+
+    detail["month"] = detail["START DATE"].dt.to_period("M").dt.to_timestamp()
+    months_index = pd.date_range(
+        start=max(detail["month"].min(), tmin.floor("D")),
+        end=min(detail["month"].max(), tmax.floor("D")),
+        freq="MS",
+    )
+
+    pivot_counts = detail.groupby(["month", "BALLAST DEST SPLIT"]).size().unstack(fill_value=0)
+    pivot_counts = pivot_counts.reindex(months_index, fill_value=0)
+
+    totals = pivot_counts.sum(axis=0).sort_values(ascending=False)
+    keep_labels = totals.head(top_n).index.tolist()
+    others = [c for c in pivot_counts.columns if c not in keep_labels]
+
+    counts_topn = pivot_counts.copy()
+    if others:
+        counts_topn["Other"] = counts_topn[others].sum(axis=1)
+        counts_topn = counts_topn[keep_labels + (["Other"] if others else [])]
+
+    proportions_topn = counts_topn.div(counts_topn.sum(axis=1), axis=0).fillna(0)
+
+    g = detail.dropna(subset=["duration_days"]).groupby("BALLAST DEST SPLIT", dropna=False)["duration_days"]
+    medians = (
+        pd.DataFrame({
+            "BALLAST DEST SPLIT": g.median().index,
+            "median_days": g.median().values,
+            "count": g.size().values,
+        })
+        .sort_values(["count", "BALLAST DEST SPLIT"], ascending=[False, True])
+        .reset_index(drop=True)
+    )
+
+    return {
+        "cohort": cohort[["IMO", "VESSEL NAME", "VOYAGE ID"]],
+        "detail": detail,
+        "counts_monthly": counts_topn,
+        "proportions_monthly": proportions_topn,
+        "medians": medians,
+    }

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vortexa-claude-skills",
+  "version": "1.0.0",
+  "description": "Claude Code skills for Vortexa commodity/energy data analytics",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "vortexa-skills": "bin/setup.js"
+  },
+  "files": [
+    "commands/",
+    "context/",
+    "lib/",
+    "!lib/__pycache__/",
+    "bin/",
+    "templates/",
+    "VERSION",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/node/",
+    "test:python": "pytest tests/python/",
+    "lint": "ruff check lib/",
+    "lint:fix": "ruff check --fix lib/"
+  }
+}

package/templates/.env.template

@@ -0,0 +1,3 @@
+# Vortexa API Key
+# Get your key from your Vortexa account manager
+VORTEXA_API_KEY=your_key_here