commodutil 3.9.0__tar.gz → 3.10.1__tar.gz

{commodutil-3.9.0 → commodutil-3.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 3.9.0
+Version: 3.10.1
 Summary: common commodity/oil analytics utils
 Author-email: aeorxc <author@example.com>
 Project-URL: Homepage, https://dev.azure.com/RWEST-MFI-TE/Oil/_git/commodutil

commodutil-3.10.1/commodutil/__init__.py

@@ -0,0 +1,80 @@
+"""commodutil: Commodity market standards backbone.
+
+Public API for unit conversions, forward curve transforms, date utilities,
+and pandas helpers. Symbols are loaded lazily on first access via PEP 562
+`__getattr__` so `import commodutil` stays cheap (~10ms vs. ~3s if the
+facade eagerly imported convfactors and its pint registry).
+
+Cheap paths:
+    import commodutil                                  # near-instant
+    from commodutil.standards.regions import ...       # stdlib only
+    from commodutil.standards.currency import ...      # stdlib only
+
+Heavier paths (lazy-load their sub-module on first attribute access):
+    from commodutil import convert_price               # triggers convfactors
+    from commodutil import curyear                     # triggers dates
+"""
+
+from __future__ import annotations
+
+# Map exported name -> dotted submodule path. Single source of truth for the
+# public facade. Keys in this dict are what `from commodutil import X` will
+# resolve via __getattr__ below.
+_LAZY_EXPORTS = {
+    # convfactors (heaviest -- pint registry + Commodity dataclass init)
+    "ALIASES": "commodutil.convfactors",
+    "COMMODITIES": "commodutil.convfactors",
+    "Commodity": "commodutil.convfactors",
+    "FRACTIONAL_TO_MAJOR": "commodutil.convfactors",
+    "VALID_CURRENCY_TOKENS": "commodutil.convfactors",
+    "convert": "commodutil.convfactors",
+    "convert_price": "commodutil.convfactors",
+    "convfactor": "commodutil.convfactors",
+    "fractional_to_major": "commodutil.convfactors",
+    "is_fractional_currency": "commodutil.convfactors",
+    "list_commodities": "commodutil.convfactors",
+    "list_units": "commodutil.convfactors",
+    "split_currency_unit": "commodutil.convfactors",
+    # dates
+    "curmon": "commodutil.dates",
+    "curmonyear": "commodutil.dates",
+    "curmonyear_str": "commodutil.dates",
+    "curyear": "commodutil.dates",
+    "find_year": "commodutil.dates",
+    "last_day_of_prev_month": "commodutil.dates",
+    "nextyear": "commodutil.dates",
+    "prevmon": "commodutil.dates",
+    "prevmon_str": "commodutil.dates",
+    "prevyear": "commodutil.dates",
+    "start_day_of_prev_month": "commodutil.dates",
+    # forwards
+    "all_spread_combinations": "commodutil.forwards",
+    "time_spreads": "commodutil.forwards",
+    # pandasutil
+    "fillna_downbet": "commodutil.pandasutil",
+    "mergets": "commodutil.pandasutil",
+    # transforms
+    "seasonalize": "commodutil.transforms",
+}
+
+__all__ = sorted(_LAZY_EXPORTS.keys())
+
+
+def __getattr__(name: str):
+    """PEP 562 lazy attribute access — loads the source submodule on first
+    use of a facade-exported symbol, caches the resolved value back into
+    the module's globals so subsequent accesses skip the dispatch.
+    """
+    module_path = _LAZY_EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module 'commodutil' has no attribute {name!r}")
+    import importlib
+
+    module = importlib.import_module(module_path)
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_EXPORTS))

commodutil-3.10.1/commodutil/standards/__init__.py

@@ -0,0 +1,70 @@
+"""commodutil.standards: canonical vocabularies for commodity trading.
+
+Re-exports the public surface of each submodule so callers can write
+`from commodutil.standards import normalize_region` instead of reaching
+into the submodule directly.
+"""
+
+from commodutil.standards.analysis_types import (
+    ANALYSIS_TYPES,
+    infer_analysis_type,
+)
+from commodutil.standards.commodities import (
+    COMMODITY_CONVERSION_MAP,
+    COMMODITY_KEYWORDS,
+)
+from commodutil.standards.commodity_groups import (
+    COMMODITY_GROUPS,
+    VALID_COMMODITY_GROUPS,
+    is_valid_commodity_group,
+)
+from commodutil.standards.currency import (
+    FRACTIONAL_CURRENCY_DIVISORS,
+    FRACTIONAL_TO_MAJOR,
+    VALID_CURRENCY_TOKENS,
+    fractional_to_major,
+    is_fractional_currency,
+    required_fx_pair,
+    split_currency_unit,
+    to_symbol,
+)
+from commodutil.standards.regions import (
+    REGION_PATTERNS,
+    VALID_REGIONS,
+    is_valid_region,
+    normalize_region,
+)
+from commodutil.standards.units import (
+    UNIT_MAP,
+    default_unit_for_commodity,
+)
+
+__all__ = [
+    # analysis_types
+    "ANALYSIS_TYPES",
+    "infer_analysis_type",
+    # commodities
+    "COMMODITY_CONVERSION_MAP",
+    "COMMODITY_KEYWORDS",
+    # commodity_groups
+    "COMMODITY_GROUPS",
+    "VALID_COMMODITY_GROUPS",
+    "is_valid_commodity_group",
+    # currency
+    "FRACTIONAL_CURRENCY_DIVISORS",
+    "FRACTIONAL_TO_MAJOR",
+    "VALID_CURRENCY_TOKENS",
+    "fractional_to_major",
+    "is_fractional_currency",
+    "required_fx_pair",
+    "split_currency_unit",
+    "to_symbol",
+    # regions
+    "REGION_PATTERNS",
+    "VALID_REGIONS",
+    "is_valid_region",
+    "normalize_region",
+    # units
+    "UNIT_MAP",
+    "default_unit_for_commodity",
+]

commodutil-3.10.1/commodutil/standards/analysis_types.py

@@ -0,0 +1,59 @@
+"""commodutil.standards.analysis_types: canonical analysis-type vocabulary.
+
+Owns the inference function for classifying a curve as one of:
+- 'crack': cracking spread
+- 'arb': geographic arbitrage spread
+- 'diff': differential / generic spread
+- 'outright': none of the above (flat price)
+
+Previously duplicated in curvemetadata.ice._infer_analysis_type (substring
+matching) and curvemetadata.cme._infer_analysis_type (regex word-boundary).
+Consolidated here using the stricter regex approach -- substring 'crack' in
+'crackers' would have been a false positive in the ICE version.
+
+Future subtypes (hi5, regrade, freight) are NOT included in this round --
+they require validation against actual Curve.Definitions.Analysis values
+in MetadataDB2, which is a separate piece of work.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+# Closed set of types recognised by infer_analysis_type. Callers downstream
+# may treat the return as a canonical tag.
+ANALYSIS_TYPES = ("crack", "arb", "diff", "outright")
+
+
+def infer_analysis_type(
+    text: Optional[str],
+    extra_text: Optional[str] = None,
+    category: Optional[str] = None,
+) -> str:
+    """Infer analysis type from product metadata.
+
+    Returns one of: 'crack', 'arb', 'diff', 'outright'. Defaults to
+    'outright' when no pattern matches.
+
+    Args:
+        text: Primary product name or description.
+        extra_text: Optional secondary text (e.g. CME sub-category) --
+            appended to `text` for matching.
+        category: Optional explicit category field. If equals 'arb'
+            (case-insensitive), short-circuits to 'arb' regardless of
+            other text content (CME convention).
+    """
+    if isinstance(category, str) and category.strip().lower() == "arb":
+        return "arb"
+    combined = f"{text or ''} {extra_text or ''}".lower()
+    if re.search(r"\bcrack\b", combined):
+        return "crack"
+    if re.search(r"\barb\b", combined):
+        return "arb"
+    if re.search(r"\bdiff\b", combined) or re.search(r"\bspread\b", combined):
+        return "diff"
+    return "outright"
+
+
+__all__ = ["ANALYSIS_TYPES", "infer_analysis_type"]

commodutil-3.10.1/commodutil/standards/commodities.py

@@ -0,0 +1,71 @@
+"""commodutil.standards.commodities: canonical commodity vocabulary.
+
+Owns:
+- COMMODITY_KEYWORDS: ordered list of (display_name, group, [keywords])
+  used by free-text inference. Ordering matters — "Natural Gasoline"
+  must precede "Natural Gas" so the substring "natural gas" inside
+  "natural gasoline" doesn't win.
+- COMMODITY_CONVERSION_MAP: display_name -> commodutil.convfactors.COMMODITIES
+  key, for downstream conversion routing.
+
+Previously lived in curvemetadata.common_maps; relocated to eliminate
+divergence risk between curvemetadata and commodutil's commodity lists.
+curvemetadata.common_maps re-exports for backwards compatibility.
+"""
+
+from __future__ import annotations
+
+COMMODITY_KEYWORDS = [
+    ("Brent", "Crude Oil", ["brent"]),
+    ("WTI", "Crude Oil", ["wti"]),
+    ("Crude Oil", "Crude Oil", ["crude oil", "crude"]),
+    # NB: 'Natural Gasoline' MUST come before 'Natural Gas' — the substring
+    # "natural gas" is contained in "natural gasoline" and would otherwise win.
+    ("Natural Gasoline", "NGL", ["natural gasoline"]),
+    ("Natural Gas", "Natural Gas", ["natural gas", "nat gas", "natgas"]),
+    ("Jet", "Refined Products", ["jet fuel", "jet"]),
+    ("Diesel", "Refined Products", ["diesel", "ulsd", "gasoil", "heating oil"]),
+    ("Gasoline", "Refined Products", ["gasoline", "rbob", "cbob", "mogas", "eurobob"]),
+    ("Fuel Oil", "Refined Products", ["fuel oil", "hsfo", "lsfo", "marine fuel"]),
+    ("Naphtha", "Refined Products", ["naphtha"]),
+    ("Product Basket", "Refined Products", ["refined products", "product basket"]),
+    ("VGO", "Refined Products", ["vgo"]),
+    ("FAME", "Biofuel", ["fame"]),
+    ("HVO", "Biofuel", ["hvo"]),
+    ("Isobutane", "NGL", ["isobutane"]),
+    ("Butane", "NGL", ["butane"]),
+    ("Ethane", "NGL", ["ethane"]),
+    ("Propane", "NGL", ["propane"]),
+    ("NGL", "NGL", ["ngl"]),
+    ("FFA", "Freight", ["freight", "ffa"]),
+]
+
+COMMODITY_CONVERSION_MAP = {
+    "Crude Oil": "crude",
+    "Brent": "crude",
+    "WTI": "crude",
+    "Natural Gas": "natgas",
+    "Jet": "jet",
+    "Diesel": "diesel",
+    "Gasoline": "gasoline",
+    "Fuel Oil": "fuel_oil",
+    "Naphtha": "naphtha",
+    "Product Basket": "product_basket",
+    "VGO": "vgo",
+    "FAME": "fame",
+    "HVO": "hvo",
+    # NGL species — switched from the generic 'lpg' blend to first-class species
+    # in commodutil 2026-05 (each has its own density / HHV for $/gal<->$/MMBtu).
+    # Keep the generic 'NGL' bucket on 'lpg' as a safe blend default.
+    "Natural Gasoline": "natural_gasoline",
+    "Isobutane": "isobutane",
+    "Butane": "butane",
+    "Propane": "propane",
+    "NGL": "lpg",
+    "Ethane": "ethane",
+}
+
+__all__ = [
+    "COMMODITY_KEYWORDS",
+    "COMMODITY_CONVERSION_MAP",
+]

commodutil-3.10.1/commodutil/standards/commodity_groups.py

@@ -0,0 +1,40 @@
+"""commodutil.standards.commodity_groups: canonical commodity group taxonomy.
+
+Mirrors the CommodityGroup CHECK constraint on Curve.Definitions in
+MetadataDB2 (see curvemetadata/sql/001_create_curvemetadata_tables.sql).
+Single source of truth for the Python side -- curvemetadata.ice and
+curvemetadata.cme currently hard-code these strings; they can adopt
+this constant in a follow-up.
+"""
+
+from __future__ import annotations
+
+# Ordered to match the SQL constraint order (preserves what consumers see
+# when iterating). Treat as a closed set -- additions require a coordinated
+# SQL migration.
+COMMODITY_GROUPS = (
+    "Agriculture",
+    "Biofuel",
+    "Crude Oil",
+    "Freight",
+    "LNG",
+    "Natural Gas",
+    "NGL",
+    "Petrochemical",
+    "Refined Products",
+)
+
+# Set for O(1) membership checks
+VALID_COMMODITY_GROUPS = frozenset(COMMODITY_GROUPS)
+
+
+def is_valid_commodity_group(value: str) -> bool:
+    """Return True if `value` is a recognised commodity group string."""
+    return value in VALID_COMMODITY_GROUPS
+
+
+__all__ = [
+    "COMMODITY_GROUPS",
+    "VALID_COMMODITY_GROUPS",
+    "is_valid_commodity_group",
+]

{commodutil-3.9.0 → commodutil-3.10.1}/commodutil/standards/regions.py

@@ -60,8 +60,15 @@ def normalize_region(text: Optional[str]) -> Optional[str]:
 
     lower = text.lower()
 
-    # RBOB convention: always NY Harbor
-    if "rbob" in lower:
+    # CARBOB short-circuit: California Reformulated Blendstock for Oxygenate
+    # Blending — Los Angeles / US West Coast, NOT NY Harbor. Must run BEFORE
+    # the RBOB check so "carbob" doesn't fall through to the NYH heuristic.
+    if re.search(r"\bcarbob\b", lower):
+        return "LA"
+
+    # RBOB convention: always NY Harbor. Use word boundary so "carbob" (which
+    # has 'a' before 'rbob' — no word boundary) does not match here.
+    if re.search(r"\brbob\b", lower):
         return "NYH"
 
     # Pattern-match against REGION_PATTERNS

commodutil-3.10.1/commodutil/standards/units.py

@@ -0,0 +1,64 @@
+"""commodutil.standards.units: canonical unit vocabulary.
+
+Owns:
+- UNIT_MAP: alias -> canonical unit map for normalising free-form unit
+  strings from vendor contract specs ("barrel", "Barrels", "BBL" -> "bbl").
+- default_unit_for_commodity(): returns the canonical quoted unit for a
+  commodity (volume basis).
+
+Pure vocab -- no pint, no pandas. The pint registry in
+commodutil.convfactors handles unit algebra; this module handles the
+string-normalisation layer that runs BEFORE algebra.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+# ---- Alias -> canonical normalisation ----
+
+# Maps lowercase aliases (singular / plural / abbreviated forms) to the
+# canonical unit token used by downstream code. Used by vendor-spec
+# parsers (e.g. curvemetadata.ice_util.parse_unit). Keys are matched
+# case-insensitively at call time -- callers should lowercase input.
+UNIT_MAP = {
+    "barrel": "bbl",
+    "barrels": "bbl",
+    "bbl": "bbl",
+    "bbls": "bbl",
+    "gallon": "gal",
+    "gallons": "gal",
+    "gal": "gal",
+    "metric ton": "mt",
+    "metric tons": "mt",
+    "metric tonne": "mt",
+    "metric tonnes": "mt",
+    "tonne": "mt",
+    "tonnes": "mt",
+}
+
+
+# ---- Default unit per commodity ----
+
+_DEFAULT_UNIT = {
+    "natgas": "mmbtu",
+    "natural_gas": "mmbtu",
+    "gasoline": "gal",
+    "diesel": "gal",
+    "jet": "gal",
+}
+
+
+def default_unit_for_commodity(commodity: Optional[str]) -> str:
+    """Return the canonical quoted unit for a commodity (volume basis).
+
+    Falls back to 'bbl' for any commodity not in the explicit map (covers
+    crude / fuel oil / naphtha / VGO / NGL species etc.).
+    """
+    if not commodity:
+        return "bbl"
+    return _DEFAULT_UNIT.get(str(commodity).lower(), "bbl")
+
+
+__all__ = ["UNIT_MAP", "default_unit_for_commodity"]

{commodutil-3.9.0 → commodutil-3.10.1}/commodutil.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commodutil
-Version: 3.9.0
+Version: 3.10.1
 Summary: common commodity/oil analytics utils
 Author-email: aeorxc <author@example.com>
 Project-URL: Homepage, https://dev.azure.com/RWEST-MFI-TE/Oil/_git/commodutil

{commodutil-3.9.0 → commodutil-3.10.1}/commodutil.egg-info/SOURCES.txt

@@ -32,6 +32,9 @@ commodutil/forward/spreads.py
 commodutil/forward/structure.py
 commodutil/forward/util.py
 commodutil/standards/__init__.py
+commodutil/standards/analysis_types.py
+commodutil/standards/commodities.py
+commodutil/standards/commodity_groups.py
 commodutil/standards/currency.py
 commodutil/standards/regions.py
 commodutil/standards/units.py
@@ -45,6 +48,9 @@ tests/test_dates.py
 tests/test_forwards.py
 tests/test_pandasutils.py
 tests/test_price_conv.py
+tests/test_standards_analysis_types.py
+tests/test_standards_commodities.py
+tests/test_standards_commodity_groups.py
 tests/test_standards_currency.py
 tests/test_standards_regions.py
 tests/test_standards_units.py

commodutil-3.10.1/tests/test_standards_analysis_types.py

@@ -0,0 +1,60 @@
+"""Tests for commodutil.standards.analysis_types."""
+
+from commodutil.standards.analysis_types import ANALYSIS_TYPES, infer_analysis_type
+
+
+def test_recognises_crack():
+    assert infer_analysis_type("Brent-Diesel Crack") == "crack"
+    assert infer_analysis_type("WTI Crack Spread") == "crack"
+
+
+def test_recognises_arb():
+    assert infer_analysis_type("Singapore-LA Gasoline Arb") == "arb"
+
+
+def test_recognises_diff():
+    assert infer_analysis_type("Brent-WTI Diff") == "diff"
+    assert infer_analysis_type("Gasoil-Heating Oil Spread") == "diff"
+
+
+def test_default_outright():
+    assert infer_analysis_type("Brent Front Month") == "outright"
+    assert infer_analysis_type("WTI Cushing") == "outright"
+
+
+def test_empty_and_none():
+    assert infer_analysis_type("") == "outright"
+    assert infer_analysis_type(None) == "outright"
+
+
+def test_word_boundary_prevents_false_match():
+    """Substring matching (old ICE behavior) would have wrongly returned
+    'crack' for 'crackers' or 'arb' for 'arbitrary'. Word boundary fixes."""
+    assert infer_analysis_type("crackers party") == "outright"
+    assert infer_analysis_type("arbitrary value") == "outright"
+    assert infer_analysis_type("trackers") == "outright"
+
+
+def test_category_short_circuit():
+    # CME convention: category="arb" wins regardless of text
+    assert infer_analysis_type("WTI Front Month", category="arb") == "arb"
+    assert infer_analysis_type("WTI Front Month", category="ARB") == "arb"
+    # Other category values don't override
+    assert infer_analysis_type("WTI Brent Diff", category="energy") == "diff"
+
+
+def test_extra_text_appended():
+    # ICE-style single-arg call still works (extra_text defaults to None)
+    assert infer_analysis_type("WTI Crack Spread") == "crack"
+    # CME-style multi-arg: sub_category contributes
+    assert infer_analysis_type("WTI Brent", "crack") == "crack"
+    assert infer_analysis_type("WTI Brent", None, None) == "outright"
+
+
+def test_crack_priority_over_arb_diff():
+    """Order matters: crack short-circuits before arb/diff checks."""
+    assert infer_analysis_type("Gasoline Crack Arb") == "crack"
+
+
+def test_analysis_types_constant():
+    assert ANALYSIS_TYPES == ("crack", "arb", "diff", "outright")

commodutil-3.10.1/tests/test_standards_commodities.py

@@ -0,0 +1,71 @@
+"""Tests for commodutil.standards.commodities."""
+
+from __future__ import annotations
+
+import pytest
+
+from commodutil.standards.commodities import (
+    COMMODITY_CONVERSION_MAP,
+    COMMODITY_KEYWORDS,
+)
+
+
+def test_commodity_keywords_sanity_length():
+    assert len(COMMODITY_KEYWORDS) >= 20
+
+
+def test_commodity_keywords_entry_shape():
+    for entry in COMMODITY_KEYWORDS:
+        assert isinstance(entry, tuple)
+        assert len(entry) == 3
+        display, group, kws = entry
+        assert isinstance(display, str)
+        assert isinstance(group, str)
+        assert isinstance(kws, list)
+        assert all(isinstance(k, str) for k in kws)
+
+
+def test_natural_gasoline_before_natural_gas():
+    displays = [d for d, _, _ in COMMODITY_KEYWORDS]
+    assert "Natural Gasoline" in displays
+    assert "Natural Gas" in displays
+    assert displays.index("Natural Gasoline") < displays.index("Natural Gas")
+
+
+def test_brent_entry_present():
+    assert ("Brent", "Crude Oil", ["brent"]) in COMMODITY_KEYWORDS
+
+
+def test_conversion_map_brent_is_crude():
+    assert COMMODITY_CONVERSION_MAP["Brent"] == "crude"
+
+
+def test_conversion_map_natural_gas_is_natgas():
+    assert COMMODITY_CONVERSION_MAP["Natural Gas"] == "natgas"
+
+
+def test_conversion_map_ngl_default_lpg_blend():
+    assert COMMODITY_CONVERSION_MAP["NGL"] == "lpg"
+
+
+def test_conversion_map_no_orphan_entries():
+    """Every commodity in COMMODITY_CONVERSION_MAP appears as a display_name
+    in COMMODITY_KEYWORDS — consistency check."""
+    displays = {d for d, _, _ in COMMODITY_KEYWORDS}
+    orphans = set(COMMODITY_CONVERSION_MAP.keys()) - displays
+    assert not orphans, f"Orphan conversion map entries: {orphans}"
+
+
+def test_parity_with_curvemetadata():
+    """Verify COMMODITY_KEYWORDS / COMMODITY_CONVERSION_MAP are identical to
+    the curvemetadata copies — guards against divergence during the migration."""
+    try:
+        from curvemetadata.common_maps import (
+            COMMODITY_CONVERSION_MAP as cm_MAP,
+            COMMODITY_KEYWORDS as cm_KW,
+        )
+    except ImportError:
+        pytest.skip("curvemetadata not available")
+
+    assert COMMODITY_KEYWORDS == cm_KW
+    assert COMMODITY_CONVERSION_MAP == cm_MAP

commodutil-3.10.1/tests/test_standards_commodity_groups.py

@@ -0,0 +1,93 @@
+"""Tests for commodutil.standards.commodity_groups."""
+
+from __future__ import annotations
+
+import pytest
+
+from commodutil.standards.commodity_groups import (
+    COMMODITY_GROUPS,
+    VALID_COMMODITY_GROUPS,
+    is_valid_commodity_group,
+)
+
+
+EXPECTED_GROUPS = (
+    "Agriculture",
+    "Biofuel",
+    "Crude Oil",
+    "Freight",
+    "LNG",
+    "Natural Gas",
+    "NGL",
+    "Petrochemical",
+    "Refined Products",
+)
+
+
+def test_count_is_nine():
+    assert len(COMMODITY_GROUPS) == 9
+
+
+def test_exact_tuple_equality_preserves_sql_order():
+    # COMMODITY_GROUPS docstring promises SQL constraint order is preserved.
+    # A future maintainer reordering the tuple would silently change what
+    # downstream consumers see when iterating.
+    assert COMMODITY_GROUPS == EXPECTED_GROUPS
+
+
+def test_valid_set_matches_expected():
+    assert VALID_COMMODITY_GROUPS == frozenset(EXPECTED_GROUPS)
+
+
+def test_all_expected_groups_present():
+    for group in EXPECTED_GROUPS:
+        assert group in VALID_COMMODITY_GROUPS, f"Missing: {group}"
+
+
+def test_is_valid_crude_oil():
+    assert is_valid_commodity_group("Crude Oil") is True
+
+
+def test_is_valid_case_sensitive():
+    # Matches SQL semantics -- the CHECK constraint uses exact-cased
+    # N'Crude Oil' literals.
+    assert is_valid_commodity_group("crude oil") is False
+
+
+def test_is_valid_unknown_returns_false():
+    assert is_valid_commodity_group("Unknown") is False
+
+
+def test_is_valid_empty_string_returns_false():
+    assert is_valid_commodity_group("") is False
+
+
+def test_commodity_groups_is_tuple():
+    assert isinstance(COMMODITY_GROUPS, tuple)
+
+
+def test_valid_commodity_groups_is_frozenset():
+    assert isinstance(VALID_COMMODITY_GROUPS, frozenset)
+
+
+# Cross-check: every CommodityGroup string used by curvemetadata.cme and
+# curvemetadata.ice must round-trip through VALID_COMMODITY_GROUPS. If
+# curvemetadata adds a new group string before the SQL constraint is
+# extended, this test flags the divergence loudly.
+CURVEMETADATA_USED_GROUPS = (
+    "Crude Oil",
+    "Refined Products",
+    "Petrochemical",
+    "Freight",
+    "NGL",
+    "Biofuel",
+    # Natural Gas / LNG / Agriculture are not currently used by ice.py /
+    # cme.py but are reserved by the SQL constraint.
+)
+
+
+@pytest.mark.parametrize("group", CURVEMETADATA_USED_GROUPS)
+def test_curvemetadata_group_is_recognised(group):
+    assert is_valid_commodity_group(group), (
+        f"curvemetadata uses {group!r} but it is not in VALID_COMMODITY_GROUPS"
+    )