tidegap 0.18.0__py3-none-any.whl

tidegap/__init__.py

@@ -0,0 +1,226 @@
+"""Tidegap — carbon-aware scheduling for agentic AI workflows.
+
+Python port of ``@tidegap/core``. Public surface mirrors the
+TypeScript package so the two stay in sync.
+
+Quick start
+-----------
+
+>>> import asyncio
+>>> from tidegap import defer
+>>> async def main():
+...     return await defer(
+...         lambda: 42,
+...         deadline="2099-01-01T00:00:00Z",
+...         carbon_budget_g=5,
+...         region="US-CAL-CISO",
+...     )
+>>> asyncio.run(main())
+42
+
+The default scheduler runs in-memory. For durable receipts and
+crash-recovery, instantiate a :class:`Scheduler` with a SQLite
+``db_path``:
+
+>>> from tidegap import Scheduler
+>>> scheduler = Scheduler(db_path="/var/lib/tidegap/queue.sqlite")
+
+See ``packages/core-py/README.md`` for the full API reference.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+from .budget import (
+    CarbonAlert,
+    CarbonBudgetConfig,
+    CarbonBudgetStatus,
+    CarbonBudgetUsage,
+    CarbonBudgetWindowKind,
+    carbon_budget_config_path,
+    carbon_budget_status,
+    carbon_budget_usage,
+    load_carbon_budget_config,
+    receipt_carbon_g,
+    window_bounds,
+)
+from .energy import (
+    DEFAULT_PUE,
+    ENERGY_SOURCES,
+    LEGACY_KWH_PER_TASK,
+    MODEL_ENERGY_COEFFICIENTS,
+    MODEL_FAMILIES,
+    EnergyResolutionTier,
+    EnergySourceTier,
+    ModelEnergyCoefficients,
+    ResolvedModelEnergy,
+    estimate_energy_kwh,
+    grams_for_intensity,
+    lookup_model_energy,
+    normalize_model_name,
+    resolve_model_energy,
+)
+from .errors import (
+    CarbonBudgetExceededError,
+    InvalidDeadlineError,
+    SchedulerShutdownError,
+    TaskCancelledError,
+)
+from .grid import (
+    EntsoePeriod,
+    EntsoeTimeSeries,
+    GridFeed,
+    build_default_grid_feed,
+    eia_feed,
+    electricity_maps_feed,
+    entsoe_feed,
+    mock_grid_feed,
+    multi_source_grid_feed,
+    parse_entsoe_xml,
+    uk_carbon_intensity_feed,
+    watttime_feed,
+)
+from .recommend import (
+    RecommendAlternative,
+    RecommendResult,
+    recommend_window,
+)
+from .scheduler import (
+    DEFAULT_REGION,
+    ENERGY_KWH_PER_TASK,
+    MAX_HORIZON_HOURS,
+    TOLERANCE_FLOOR_G,
+    TOLERANCE_FRACTION,
+    DeferrableTask,
+    Scheduler,
+    SelectWindowResult,
+    defer,
+    normalize_deadline,
+    pick_best_window,
+    select_window,
+)
+from .sign import (
+    SigningKeyPair,
+    SigningNotInstalled,
+    VerifyOutcome,
+    VerifyResult,
+    default_signing_key_path,
+    is_signing_available,
+    load_or_create_signing_key,
+    sign_receipt,
+    verify_receipt,
+)
+from .types import (
+    Band,
+    CarbonReceipt,
+    DeferOptions,
+    EnergyResolution,
+    EnergySource,
+    ForecastKind,
+    GridForecast,
+    GridForecastEntry,
+    GridSignalType,
+    GridSource,
+    IntensitySource,
+    Provider,
+    ProviderCallSpec,
+    TaskRecord,
+    TaskStatus,
+    TickResult,
+    TickResultEntry,
+)
+
+# The package version is declared once, in pyproject.toml. Read it back from
+# the installed metadata rather than hard-coding a second copy here.
+try:
+    __version__ = _pkg_version("tidegap")
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    __version__ = "0+unknown"
+
+__all__ = [
+    "DEFAULT_PUE",
+    "DEFAULT_REGION",
+    "ENERGY_KWH_PER_TASK",
+    "ENERGY_SOURCES",
+    "LEGACY_KWH_PER_TASK",
+    "MAX_HORIZON_HOURS",
+    "MODEL_ENERGY_COEFFICIENTS",
+    "MODEL_FAMILIES",
+    "TOLERANCE_FLOOR_G",
+    "TOLERANCE_FRACTION",
+    "Band",
+    "CarbonAlert",
+    "CarbonBudgetConfig",
+    "CarbonBudgetExceededError",
+    "CarbonBudgetStatus",
+    "CarbonBudgetUsage",
+    "CarbonBudgetWindowKind",
+    "CarbonReceipt",
+    "DeferOptions",
+    "DeferrableTask",
+    "EnergyResolution",
+    "EnergyResolutionTier",
+    "EnergySource",
+    "EnergySourceTier",
+    "EntsoePeriod",
+    "EntsoeTimeSeries",
+    "ForecastKind",
+    "GridFeed",
+    "GridForecast",
+    "GridForecastEntry",
+    "GridSignalType",
+    "GridSource",
+    "IntensitySource",
+    "InvalidDeadlineError",
+    "ModelEnergyCoefficients",
+    "Provider",
+    "ProviderCallSpec",
+    "RecommendAlternative",
+    "RecommendResult",
+    "ResolvedModelEnergy",
+    "Scheduler",
+    "SchedulerShutdownError",
+    "SelectWindowResult",
+    "SigningKeyPair",
+    "SigningNotInstalled",
+    "TaskCancelledError",
+    "TaskRecord",
+    "TaskStatus",
+    "TickResult",
+    "TickResultEntry",
+    "VerifyOutcome",
+    "VerifyResult",
+    "__version__",
+    "build_default_grid_feed",
+    "carbon_budget_config_path",
+    "carbon_budget_status",
+    "carbon_budget_usage",
+    "default_signing_key_path",
+    "defer",
+    "eia_feed",
+    "electricity_maps_feed",
+    "entsoe_feed",
+    "estimate_energy_kwh",
+    "grams_for_intensity",
+    "is_signing_available",
+    "load_carbon_budget_config",
+    "load_or_create_signing_key",
+    "lookup_model_energy",
+    "mock_grid_feed",
+    "multi_source_grid_feed",
+    "normalize_deadline",
+    "normalize_model_name",
+    "parse_entsoe_xml",
+    "pick_best_window",
+    "receipt_carbon_g",
+    "recommend_window",
+    "resolve_model_energy",
+    "select_window",
+    "sign_receipt",
+    "uk_carbon_intensity_feed",
+    "verify_receipt",
+    "watttime_feed",
+    "window_bounds",
+]

tidegap/_data.py

@@ -0,0 +1,245 @@
+# GENERATED — DO NOT EDIT.
+#
+# Produced by scripts/gen-data.mjs from packages/core-ts/src/data/*.json.
+# Edit those JSON files and run 'pnpm gen:data' to regenerate. CI fails
+# on drift ('pnpm gen:data:check').
+# ruff: noqa
+"""Generated data tables mirrored from the JSON SSOT in @tidegap/core."""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: Industry-average Power Usage Effectiveness for hyperscaler data centres.
+DEFAULT_PUE: float = 1.15
+
+#: Backwards-compatible flat estimate. Used when no model is provided.
+LEGACY_KWH_PER_TASK: float = 0.0015
+
+#: Typical token shape used when a caller names a model but no token counts.
+TYPICAL_INPUT_TOKENS: int = 500
+TYPICAL_OUTPUT_TOKENS: int = 500
+
+#: Per-model coefficient table. Keys are canonical lowercase names.
+COEFFICIENTS: dict[str, dict[str, Any]] = {
+    "claude-fable-5-1": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "claude-fable-5": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "claude-opus-5-5": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "claude-opus-5": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "claude-opus-4-8": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "claude-opus-4": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": "deprecated"},
+    "claude-opus-4-7": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": None},
+    "claude-opus-4-6": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": None},
+    "claude-opus-4-5": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "claude-opus-4-1": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": "retired"},
+    "claude-opus-3": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": "retired"},
+    "claude-sonnet-5": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": None, "source": "estimated", "status": None},
+    "claude-sonnet-4": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "estimated", "status": "deprecated"},
+    "claude-sonnet-4-6": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "estimated", "status": None},
+    "claude-sonnet-4-5": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "estimated", "status": None},
+    "claude-sonnet-3-7": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "estimated", "status": "retired"},
+    "claude-sonnet-3-5": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "estimated", "status": "retired"},
+    "claude-sonnet-3": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "estimated", "status": "retired"},
+    "claude-haiku-4-5": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": 13, "source": "estimated", "status": None},
+    "claude-haiku-3-5": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": 13, "source": "estimated", "status": "retired"},
+    "claude-haiku-3": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": 13, "source": "estimated", "status": "retired"},
+    "gpt-6-astra": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "gpt-6-sol": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": None, "source": "estimated", "status": None},
+    "gpt-6-luna": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": None, "source": "estimated", "status": None},
+    "gpt-5": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "gpt-5-mini": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": None, "source": "estimated", "status": None},
+    "gpt-5-nano": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": None, "source": "estimated", "status": None},
+    "gpt-4o": {"wh_per_input_token": 0.002, "wh_per_output_token": 0.01, "params_b": 200, "source": "estimated", "status": None},
+    "gpt-4o-mini": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": 30, "source": "estimated", "status": None},
+    "gpt-4-1": {"wh_per_input_token": 0.002, "wh_per_output_token": 0.01, "params_b": None, "source": "estimated", "status": None},
+    "gpt-4-1-mini": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": None, "source": "estimated", "status": None},
+    "gpt-4-1-nano": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": None, "source": "estimated", "status": None},
+    "gpt-4-turbo": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": "deprecated"},
+    "gpt-4": {"wh_per_input_token": 0.005, "wh_per_output_token": 0.025, "params_b": 1000, "source": "estimated", "status": "deprecated"},
+    "gpt-3-5-turbo": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": 20, "source": "estimated", "status": None},
+    "o1": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": None},
+    "o1-mini": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": 30, "source": "estimated", "status": "retired"},
+    "o3": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": 400, "source": "estimated", "status": None},
+    "o3-mini": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": 30, "source": "estimated", "status": "deprecated"},
+    "gemini-3-1-pro": {"wh_per_input_token": 0.002, "wh_per_output_token": 0.01, "params_b": None, "source": "estimated", "status": None},
+    "gemini-3-8-flash": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": None, "source": "estimated", "status": None},
+    "gemini-3-5-flash-lite": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": None, "source": "estimated", "status": None},
+    "gemini-1-5-pro": {"wh_per_input_token": 0.002, "wh_per_output_token": 0.01, "params_b": 200, "source": "estimated", "status": "retired"},
+    "gemini-1-5-flash": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": 20, "source": "estimated", "status": "retired"},
+    "gemini-2-0-flash": {"wh_per_input_token": 0.0003, "wh_per_output_token": 0.0015, "params_b": 20, "source": "estimated", "status": "retired"},
+    "gemini-2-0-pro": {"wh_per_input_token": 0.002, "wh_per_output_token": 0.01, "params_b": 200, "source": "estimated", "status": "retired"},
+    "llama-3-1-405b": {"wh_per_input_token": 0.005, "wh_per_output_token": 0.025, "params_b": 405, "source": "measured", "status": None},
+    "llama-3-1-70b": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "measured", "status": None},
+    "llama-3-1-8b": {"wh_per_input_token": 0.0002, "wh_per_output_token": 0.001, "params_b": 8, "source": "measured", "status": None},
+    "llama-3-70b": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": 70, "source": "measured", "status": None},
+    "llama-3-8b": {"wh_per_input_token": 0.0002, "wh_per_output_token": 0.001, "params_b": 8, "source": "measured", "status": None},
+    "llama-4-scout": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": None, "source": "estimated", "status": None},
+    "llama-4-maverick": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": None, "source": "estimated", "status": None},
+    "mistral-small-4": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": None, "source": "estimated", "status": None},
+    "mistral-medium-3-5": {"wh_per_input_token": 0.001, "wh_per_output_token": 0.005, "params_b": None, "source": "estimated", "status": None},
+    "mistral-large-3": {"wh_per_input_token": 0.003, "wh_per_output_token": 0.015, "params_b": None, "source": "estimated", "status": None},
+    "mistral-7b": {"wh_per_input_token": 0.0002, "wh_per_output_token": 0.001, "params_b": 7, "source": "measured", "status": None},
+    "mixtral-8x7b": {"wh_per_input_token": 0.0006, "wh_per_output_token": 0.003, "params_b": 47, "source": "measured", "status": None},
+    "mixtral-8x22b": {"wh_per_input_token": 0.0015, "wh_per_output_token": 0.0075, "params_b": 141, "source": "measured", "status": None},
+}
+
+#: Ordered family-fallback rules (see _family_representative).
+FAMILIES: list[dict[str, Any]] = [
+    {"id": "claude-fable", "representative": "claude-fable-5-1", "contains": ["fable"], "prefix": None, "regex": None},
+    {"id": "claude-mythos", "representative": "claude-fable-5-1", "contains": ["mythos"], "prefix": None, "regex": None},
+    {"id": "claude-opus", "representative": "claude-opus-5", "contains": ["opus"], "prefix": None, "regex": None},
+    {"id": "claude-sonnet", "representative": "claude-sonnet-5", "contains": ["sonnet"], "prefix": None, "regex": None},
+    {"id": "claude-haiku", "representative": "claude-haiku-4-5", "contains": ["haiku"], "prefix": None, "regex": None},
+    {"id": "gpt-6", "representative": "gpt-6-sol", "contains": None, "prefix": "gpt-6", "regex": None},
+    {"id": "gpt-5", "representative": "gpt-5", "contains": None, "prefix": "gpt-5", "regex": None},
+    {"id": "gpt-4o", "representative": "gpt-4o", "contains": None, "prefix": "gpt-4o", "regex": None},
+    {"id": "gpt-4-1", "representative": "gpt-4-1", "contains": None, "prefix": "gpt-4-1", "regex": None},
+    {"id": "gpt-4", "representative": "gpt-4", "contains": None, "prefix": "gpt-4", "regex": None},
+    {"id": "gpt-3", "representative": "gpt-3-5-turbo", "contains": None, "prefix": "gpt-3", "regex": None},
+    {"id": "openai-o", "representative": "o3", "contains": None, "prefix": None, "regex": "^o[0-9]"},
+    {"id": "gemini-flash", "representative": "gemini-3-8-flash", "contains": ["flash"], "prefix": "gemini", "regex": None},
+    {"id": "gemini-pro", "representative": "gemini-3-1-pro", "contains": None, "prefix": "gemini", "regex": None},
+    {"id": "mixtral", "representative": "mixtral-8x7b", "contains": None, "prefix": "mixtral", "regex": None},
+    {"id": "mistral", "representative": "mistral-7b", "contains": None, "prefix": "mistral", "regex": None},
+    {"id": "llama", "representative": "llama-3-1-70b", "contains": None, "prefix": "llama", "regex": None},
+]
+
+#: Citation metadata for the coefficient table.
+ENERGY_SOURCES: dict[str, dict[str, str]] = {
+    "patterson2021": {"citation": "Patterson et al. 2021, 'Carbon Emissions and Large Neural Network Training'", "arxiv": "2104.10350"},
+    "luccioni2024": {"citation": "Luccioni, Jernite, Strubell 2024, 'Power Hungry Processing'", "venue": "FAccT 2024", "arxiv": "2311.16863"},
+    "huggingface": {"citation": "Hugging Face AI Energy Score", "url": "https://huggingface.co/AIEnergyScore"},
+}
+
+#: Synthetic-curve region midpoints (gCO2/kWh).
+REGION_FLOORS: dict[str, int] = {
+    "US-CAL-CISO": 280,
+    "US-TEX-ERCO": 340,
+    "US-NE-ISNE": 320,
+    "US-MIDA-PJM": 420,
+    "GB": 220,
+    "FR": 60,
+    "DE": 380,
+    "IE": 340,
+    "NL": 350,
+    "ES": 160,
+    "BE": 140,
+    "AT": 110,
+    "PL": 650,
+    "JP-TK": 470,
+    "KR": 430,
+    "SG": 420,
+    "AU-NSW": 500,
+    "CA-ON": 50,
+    "US-NY-NYIS": 360,
+    "US-MIDW-MISO": 460,
+    "US-NW-BPAT": 110,
+    "US-FLA-FPL": 400,
+    "IT-NO": 320,
+    "SE-SE3": 40,
+    "NO-NO1": 30,
+    "FI": 120,
+    "DK-DK1": 180,
+    "IN-WE": 700,
+    "ZA": 700,
+    "AE": 620,
+    "NZ": 80,
+}
+
+#: Fallback midpoint for regions with no explicit floor.
+DEFAULT_REGION_FLOOR: int = 380
+
+#: Peak-to-trough half-swing of the synthetic curve (gCO2/kWh).
+SYNTHETIC_AMPLITUDE: int = 220
+
+#: Per-region UTC-hour offset applied to the synthetic curve's local trough.
+REGION_UTC_OFFSETS: dict[str, int] = {
+    "US-CAL-CISO": -8,
+    "US-TEX-ERCO": -6,
+    "US-NE-ISNE": -5,
+    "US-MIDA-PJM": -5,
+    "GB": 0,
+    "FR": 1,
+    "DE": 1,
+    "IE": 0,
+    "NL": 1,
+    "ES": 1,
+    "BE": 1,
+    "AT": 1,
+    "PL": 1,
+    "JP-TK": 9,
+    "KR": 9,
+    "SG": 8,
+    "AU-NSW": 10,
+    "CA-ON": -5,
+    "US-NY-NYIS": -5,
+    "US-MIDW-MISO": -6,
+    "US-NW-BPAT": -8,
+    "US-FLA-FPL": -5,
+    "IT-NO": 1,
+    "SE-SE3": 1,
+    "NO-NO1": 1,
+    "FI": 2,
+    "DK-DK1": 1,
+    "IN-WE": 5,
+    "ZA": 2,
+    "AE": 4,
+    "NZ": 12,
+}
+
+#: Band thresholds (ascending). A value maps to the first band it is below.
+BAND_THRESHOLDS: list[tuple[int, str]] = [
+    (100, "very_clean"),
+    (250, "clean"),
+    (450, "average"),
+    (700, "dirty"),
+]
+
+#: Band for values at or above every threshold.
+DEFAULT_BAND: str = "very_dirty"
+
+#: Month the price table figures were read (see prices.json).
+PRICES_AS_OF: str = "2026-09"
+
+#: Per-model public list prices (USD per million tokens), keyed by the same
+#: canonical lowercase ids as COEFFICIENTS. Ollama-routable open-weight models
+#: are 0 (self-hosted). Used by cross-provider routing's cost dimension.
+MODEL_PRICES: dict[str, dict[str, Any]] = {
+    "claude-fable-5-1": {"in_usd_per_mtok": 10, "out_usd_per_mtok": 50, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-fable-5": {"in_usd_per_mtok": 10, "out_usd_per_mtok": 50, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-opus-5-5": {"in_usd_per_mtok": 4, "out_usd_per_mtok": 20, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-opus-5": {"in_usd_per_mtok": 5, "out_usd_per_mtok": 25, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-opus-4-8": {"in_usd_per_mtok": 5, "out_usd_per_mtok": 25, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-opus-4": {"in_usd_per_mtok": 15, "out_usd_per_mtok": 75, "batch_discount": 0.5, "as_of": "2026-07", "source": "Anthropic pricing (anthropic.com/pricing)"},
+    "claude-opus-4-7": {"in_usd_per_mtok": 5, "out_usd_per_mtok": 25, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-opus-4-6": {"in_usd_per_mtok": 5, "out_usd_per_mtok": 25, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-sonnet-5": {"in_usd_per_mtok": 2, "out_usd_per_mtok": 10, "batch_discount": 0.5, "as_of": "2026-09", "source": "Anthropic pricing (platform.claude.com/docs/en/about-claude/pricing)"},
+    "claude-sonnet-4": {"in_usd_per_mtok": 3, "out_usd_per_mtok": 15, "batch_discount": 0.5, "as_of": "2026-07", "source": "Anthropic pricing (anthropic.com/pricing)"},
+    "claude-sonnet-4-6": {"in_usd_per_mtok": 3, "out_usd_per_mtok": 15, "batch_discount": 0.5, "as_of": "2026-07", "source": "Anthropic pricing (anthropic.com/pricing)"},
+    "claude-sonnet-4-5": {"in_usd_per_mtok": 3, "out_usd_per_mtok": 15, "batch_discount": 0.5, "as_of": "2026-07", "source": "Anthropic pricing (anthropic.com/pricing)"},
+    "claude-haiku-4-5": {"in_usd_per_mtok": 1, "out_usd_per_mtok": 5, "batch_discount": 0.5, "as_of": "2026-07", "source": "Anthropic pricing (anthropic.com/pricing)"},
+    "gpt-6-astra": {"in_usd_per_mtok": 10, "out_usd_per_mtok": 50, "batch_discount": 0.5, "as_of": "2026-09", "source": "OpenAI API pricing (developers.openai.com/api/docs/pricing)"},
+    "gpt-6-sol": {"in_usd_per_mtok": 2, "out_usd_per_mtok": 10, "batch_discount": 0.5, "as_of": "2026-09", "source": "OpenAI API pricing (developers.openai.com/api/docs/pricing)"},
+    "gpt-6-luna": {"in_usd_per_mtok": 0.1, "out_usd_per_mtok": 0.5, "batch_discount": 0.5, "as_of": "2026-09", "source": "OpenAI API pricing (developers.openai.com/api/docs/pricing)"},
+    "gpt-4o": {"in_usd_per_mtok": 2.5, "out_usd_per_mtok": 10, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "gpt-4o-mini": {"in_usd_per_mtok": 0.15, "out_usd_per_mtok": 0.6, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "gpt-4-turbo": {"in_usd_per_mtok": 10, "out_usd_per_mtok": 30, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "gpt-4": {"in_usd_per_mtok": 30, "out_usd_per_mtok": 60, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "gpt-3-5-turbo": {"in_usd_per_mtok": 0.5, "out_usd_per_mtok": 1.5, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "o1": {"in_usd_per_mtok": 15, "out_usd_per_mtok": 60, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "o3": {"in_usd_per_mtok": 2, "out_usd_per_mtok": 8, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "o3-mini": {"in_usd_per_mtok": 1.1, "out_usd_per_mtok": 4.4, "batch_discount": 0.5, "as_of": "2026-07", "source": "OpenAI API pricing (openai.com/api/pricing)"},
+    "llama-3-1-405b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "llama-3-1-70b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "llama-3-1-8b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "llama-3-70b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "llama-3-8b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "llama-4-scout": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-09", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "llama-4-maverick": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-09", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "mistral-small-4": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-09", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "mistral-medium-3-5": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-09", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "mistral-large-3": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-09", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "mistral-7b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "mixtral-8x7b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+    "mixtral-8x22b": {"in_usd_per_mtok": 0, "out_usd_per_mtok": 0, "batch_discount": None, "as_of": "2026-07", "source": "Ollama local (self-hosted; no per-token vendor price)"},
+}

tidegap/_env.py

@@ -0,0 +1,43 @@
+"""Read a Tidegap environment variable, falling back to its 0.17 ``EBB_*`` name.
+
+``TIDEGAP_<NAME>`` wins when set. Otherwise ``EBB_<NAME>`` is read, and the
+first fallback for each name prints one deprecation line to stderr. The
+fallback is removed in 0.19.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+KEY_PREFIX = "TIDEGAP_"
+LEGACY_KEY_PREFIX = "EBB_"
+
+_reported: set[str] = set()
+
+
+def env_value(name: str) -> str | None:
+    """``TIDEGAP_<name>``, else ``EBB_<name>`` (with one stderr line), else ``None``."""
+    current = os.environ.get(KEY_PREFIX + name)
+    if current is not None and current.strip() != "":
+        return current
+    legacy = os.environ.get(LEGACY_KEY_PREFIX + name)
+    if legacy is not None and legacy.strip() != "":
+        if name not in _reported:
+            _reported.add(name)
+            print(
+                f"tidegap: rename EBB_{name} -> TIDEGAP_{name}; "
+                "the EBB_* names stop working in 0.19.",
+                file=sys.stderr,
+            )
+        return legacy
+    return current
+
+
+def with_tidegap_keys(values: dict[str, str]) -> dict[str, str]:
+    """Fold ``EBB_*`` keys into ``TIDEGAP_*`` names; a ``TIDEGAP_*`` key wins."""
+    out = {k: v for k, v in values.items() if not k.startswith(LEGACY_KEY_PREFIX)}
+    for key, value in values.items():
+        if key.startswith(LEGACY_KEY_PREFIX):
+            out.setdefault(KEY_PREFIX + key[len(LEGACY_KEY_PREFIX) :], value)
+    return out