mostlyrightmd 0.1.0__py3-none-any.whl

mostlyright/_internal/_bounds.py

@@ -0,0 +1,167 @@
+"""Schema-derived bounds and validation helpers.
+
+Constants from specs/observation.json. Shared by AWC, GHCNh, and IEM parsers.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# Pressure bounds (observation.json: sea_level_pressure_mb)
+SLP_MIN_MB = 870.0
+SLP_MAX_MB = 1084.0
+
+# Temperature bounds (°C). World records: -89.2°C (Vostok) / 56.7°C (Death Valley).
+TEMP_MIN_C = -90.0
+TEMP_MAX_C = 60.0
+
+# String length limits
+MAX_RAW_METAR_LEN = 2048
+MAX_WX_CODES_LEN = 256
+
+# Visibility (observation.json: visibility_miles max)
+MAX_VISIBILITY_MILES = 99.99
+
+# Wind bounds (observation.json: wind_dir_degrees, wind_speed_kt, wind_gust_kt)
+WIND_DIR_BOUNDS = (0, 360)
+WIND_SPEED_MAX = 200
+WIND_GUST_MAX = 250
+
+# Sky (observation.json: sky_base max)
+SKY_BASE_MAX_FT = 60000
+
+# Station code regex - security boundary: codes flow into Hive partition paths.
+# Use `\A...\Z` (not `^...$`) so trailing-newline inputs like "KJFK\n" fail to
+# match. Python's `$` matches BEFORE a trailing newline; `\Z` requires the
+# absolute end of string. Codex review fix.
+STATION_CODE_RE = re.compile(r"\A[A-Z]{3,4}\Z")
+
+# GHCNh station identifier regex. The NCEI archive uses two id flavors:
+# - ICAO-derived joined USAF-WBAN form, e.g. ``"744860-94789"`` for KJFK
+# - 11-character NCEI station ids, alphanumeric
+# Either way: alphanumeric + hyphen, length-bounded, anchored. This is a
+# SECURITY BOUNDARY identical to STATION_CODE_RE: ids flow into URL params
+# and cache paths, so any path-separator character (/, \, ., space) must be
+# rejected. Codex/Rob H8 fix.
+GHCNH_STATION_ID_RE = re.compile(r"\A[A-Z0-9][A-Z0-9-]{0,31}\Z")
+
+# Year range for timestamp validation
+MIN_YEAR = 1940
+MAX_YEAR = 2100
+
+
+def bounded_int(val: int | None, lo: int, hi: int) -> int | None:
+    """Return val if within [lo, hi], else None."""
+    if val is None:
+        return None
+    return val if lo <= val <= hi else None
+
+
+def bounded_float(val: float | None, lo: float, hi: float, *, field: str = "") -> float | None:
+    """Return val if within [lo, hi], else None. Logs out-of-bounds values."""
+    if val is None:
+        return None
+    if lo <= val <= hi:
+        return val
+    ctx = f" ({field})" if field else ""
+    log.warning(
+        "bounded_float%s: %.4f outside [%.1f, %.1f], setting to None",
+        ctx,
+        val,
+        lo,
+        hi,
+    )
+    return None
+
+
+def bounded_float_min(val: float | None, lo: float) -> float | None:
+    """Return val if >= lo, else None."""
+    if val is None:
+        return None
+    return val if val >= lo else None
+
+
+# ---------------------------------------------------------------------------
+# Path-boundary validators (Rob PR #2 C1/H8 - path traversal hardening)
+# ---------------------------------------------------------------------------
+#
+# Every fetcher and cache helper that uses a caller-supplied station string
+# inside a URL parameter OR a filesystem path goes through one of these
+# validators FIRST. The downstream parsers already use STATION_CODE_RE; the
+# boundary fix is making sure raw fetcher/cache entry points do too.
+#
+# A station value like ``"../../../tmp/evil"`` would otherwise resolve outside
+# the cache root via ``dest_dir / station / file`` -- the validators reject
+# anything that does not match the strict regex.
+
+
+def validate_icao_for_path(value: object, *, field: str = "station") -> str:
+    """Return ``value`` validated as a 3-4 letter uppercase ICAO/IATA code.
+
+    Raises ``ValueError`` with the field name for any input that fails
+    ``STATION_CODE_RE``. Accepts only ``str``; rejects bytes, None, ints,
+    and any value containing path separators, whitespace, or non-ASCII chars.
+
+    Used at every fetcher and cache entry point that puts the station value
+    into a URL param or a filesystem path (Rob PR #2 C1/H8).
+    """
+    if not isinstance(value, str):
+        raise ValueError(
+            f"{field} must be a str (got {type(value).__name__}); "
+            f"unsafe to use in URL or cache path"
+        )
+    if not STATION_CODE_RE.match(value):
+        raise ValueError(
+            f"{field}={value!r} does not match STATION_CODE_RE "
+            f"(3-4 uppercase letters); refusing to use as URL or path component"
+        )
+    return value
+
+
+def validate_ghcnh_id_for_path(value: object, *, field: str = "station_id") -> str:
+    """Return ``value`` validated as a GHCNh station identifier.
+
+    Accepts ``str`` matching ``GHCNH_STATION_ID_RE`` (alphanumeric + hyphen,
+    1-32 chars, first char alphanumeric). Rejects everything else with
+    ``ValueError``. NCEI uses both ICAO-derived (``"744860-94789"``) and 11-
+    char native ids; this pattern covers both while still rejecting path
+    separators, whitespace, and quoting characters (Rob PR #2 H8).
+    """
+    if not isinstance(value, str):
+        raise ValueError(
+            f"{field} must be a str (got {type(value).__name__}); "
+            f"unsafe to use in URL or cache path"
+        )
+    if not GHCNH_STATION_ID_RE.match(value):
+        raise ValueError(
+            f"{field}={value!r} does not match GHCNH_STATION_ID_RE "
+            f"(alphanumeric + hyphen, 1-32 chars); refusing to use as URL "
+            f"or path component"
+        )
+    return value
+
+
+def assert_path_under(path: Path, root: Path, *, field: str = "path") -> Path:
+    """Defense-in-depth: assert ``path`` resolves under ``root``.
+
+    Used after the regex validators above as a second line of defense against
+    path-traversal. ``Path.resolve()`` follows symlinks and ``..`` segments;
+    ``is_relative_to`` then confirms the resolved path is still inside the
+    resolved root. Either filter alone would suffice; both together make a
+    path-escape regression require breaking BOTH defenses.
+
+    Returns the resolved path on success; raises ``ValueError`` on escape
+    (Rob PR #2 C1).
+    """
+    resolved = path.resolve()
+    rroot = root.resolve()
+    if not resolved.is_relative_to(rroot):
+        raise ValueError(
+            f"{field}={path!r} resolves to {resolved!r}, outside root {rroot!r}; "
+            f"refusing path-traversal"
+        )
+    return resolved

mostlyright/_internal/_cache_dir.py

@@ -0,0 +1,90 @@
+"""Resolve the on-disk cache directory.
+
+Resolution order (highest precedence first):
+1. ``MOSTLYRIGHT_CACHE_DIR`` env var (canonical, post-Phase-12).
+2. ``TRADEWINDS_CACHE_DIR`` env var (legacy; emits DeprecationWarning;
+   scheduled for removal in v0.3).
+3. Default: ``~/.mostlyright/cache/v1/``.
+
+In v0.3 the ``TRADEWINDS_CACHE_DIR`` branch will be removed; users on v0.2.x get
+one full release to migrate. Migration is byte-equivalent: ``mv ~/.tradewinds
+~/.mostlyright`` works without schema change.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from pathlib import Path
+from typing import Final
+
+_DEFAULT: Final[Path] = Path.home() / ".mostlyright" / "cache" / "v1"
+_DEFAULT_ROOT: Final[Path] = Path.home() / ".mostlyright" / "cache"  # without /v1
+_LEGACY_ENV: Final[str] = "TRADEWINDS_CACHE_DIR"
+_CANONICAL_ENV: Final[str] = "MOSTLYRIGHT_CACHE_DIR"
+_DEPRECATION_MESSAGE: Final[str] = (
+    f"{_LEGACY_ENV} is deprecated; use {_CANONICAL_ENV}. "
+    f"Support will be removed in v0.3. Run: mv ~/.tradewinds ~/.mostlyright"
+)
+
+
+def _resolve_env_value(stacklevel: int = 2) -> str | None:
+    """Read the env-var override (canonical → legacy + warn), or return None.
+
+    Shared by :func:`resolve_cache_dir` (which appends ``/v1`` for the canonical
+    "full cache dir" callers) and by the 3 legacy ``_cache_root()`` helpers
+    in :mod:`mostlyright.discovery`, :mod:`mostlyright.weather.cache`, and
+    :mod:`mostlyright.markets._trades_cache` (which preserve the legacy
+    "env var = cache ROOT without /v1, callers append CACHE_VERSION" contract).
+
+    Single source of truth for the resolution order + deprecation warning, so a
+    future change to either (e.g. adding XDG fallback, changing the v0.3
+    removal text) propagates to all consumers atomically.
+    """
+    canonical = os.environ.get(_CANONICAL_ENV)
+    if canonical:
+        return canonical
+    legacy = os.environ.get(_LEGACY_ENV)
+    if legacy:
+        warnings.warn(
+            _DEPRECATION_MESSAGE,
+            DeprecationWarning,
+            stacklevel=stacklevel + 1,
+        )
+        return legacy
+    return None
+
+
+def resolve_cache_dir() -> Path:
+    """Return the full cache directory (with ``/v1`` default).
+
+    Resolution order: ``MOSTLYRIGHT_CACHE_DIR`` env > ``TRADEWINDS_CACHE_DIR`` env
+    (DeprecationWarning, removed v0.3) > ``~/.mostlyright/cache/v1``.
+
+    New callers that want the canonical full cache directory should use this
+    function. Existing callers that build paths via ``_cache_root() / CACHE_VERSION``
+    use :func:`resolve_cache_root_without_v1` to preserve the legacy contract.
+    """
+    value = _resolve_env_value(stacklevel=2)
+    if value is not None:
+        return Path(value)
+    return _DEFAULT
+
+
+def resolve_cache_root_without_v1() -> Path:
+    """Return the cache ROOT (without ``/v1``) — the legacy contract.
+
+    Used by the 3 ``_cache_root()`` helpers in ``discovery.py``,
+    ``weather/cache.py``, and ``markets/_trades_cache.py`` which still append
+    ``CACHE_VERSION='v1'`` themselves. Same resolution order as
+    :func:`resolve_cache_dir` (canonical → legacy + warn → default), but the
+    default is ``~/.mostlyright/cache`` (no ``/v1``), and env-var overrides are
+    returned verbatim (legacy semantic: env var IS the cache root).
+
+    v0.3 work: collapse the two helpers into one when the legacy contract is
+    retired alongside ``TRADEWINDS_CACHE_DIR``.
+    """
+    value = _resolve_env_value(stacklevel=2)
+    if value is not None:
+        return Path(value).expanduser()
+    return _DEFAULT_ROOT

mostlyright/_internal/_capabilities.py

@@ -0,0 +1,274 @@
+"""Capabilities and schema introspection for the mostlyright SDK.
+
+Provides:
+  - _METHOD_INDEX: structured summary of all public SDK methods
+  - _SCHEMA_FILES: mapping of entity names to spec filenames
+  - _SCHEMA_CACHE: in-process cache of loaded JSON schemas
+  - load_schema(): load a JSON schema from specs/ by entity name
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Schema file mapping
+# "pairs" is intentionally omitted — specs/settlement-join.json describes the
+# observation-settlement join schema, not the pairs() output columns.
+# A specs/pairs.json spec is deferred to Sprint 4. Until then, use
+# feature_catalog(source_filter="pairs") to inspect pairs columns.
+# ---------------------------------------------------------------------------
+
+_SCHEMA_FILES: dict[str, str] = {
+    "observation": "observation.json",
+    "climate": "climate.json",
+    "snapshot": "snapshot.json",
+    "data_version": "data_version.json",
+    "forecast": "forecast.json",
+    "forecast_series": "forecast_series.json",
+    "candle": "candle.json",
+    "market": "market.json",
+    "market_unified": "market_unified.json",
+    "synoptic_extremes": "synoptic_extremes.json",
+    "omo": "omo.json",
+    # brackets.json is available for bracket/range queries
+    "brackets": "brackets.json",
+    # Phase 3.1 — daily_extreme.v1 resolution schema for daily_extremes() rollup.
+    "daily_extreme": "daily_extreme.json",
+}
+
+# 5 additional specs ship in ``mostlyright/_internal/specs/`` but are intentionally
+# not exposed via ``client.schema()``:
+#   - event.json            — Kalshi event metadata (Sprint 3)
+#   - series.json           — Kalshi series (Sprint 3)
+#   - settlement_record.json — Kalshi settlement records (Sprint 3)
+#   - settlement-join.json  — internal observation↔settlement join contract
+#   - book_snapshot.json    — order-book snapshot (Sprint 3+)
+#
+# They ride in the wheel because validation/ and ingest/ test suites use
+# them, and that's cheaper than maintaining a separate "tests-only" resource
+# bundle. When a Sprint 3 API surfaces them, lift them into ``_SCHEMA_FILES``
+# so ``client.schema()`` can reach them publicly. Until then they're
+# inspectable but not part of the documented SDK contract.
+
+_SCHEMA_CACHE: dict[str, dict[str, Any]] = {}
+
+# Path to the specs/ directory that ships inside the ``mostlyright`` wheel.
+# Before 0.14.1 this pointed at the repo-root ``specs/`` via
+# ``parent.parent.parent``, which works for editable / source installs but
+# broke in every pip-installed environment — the wheel never shipped the
+# specs. Vu caught it with ``client.schema('observation')`` returning
+# FileNotFoundError in a clean PyPI install.
+#
+# Moving specs into the package (``mostlyright/_internal/specs/``) means
+# ``Path(__file__).parent / "specs"`` resolves to the packaged copy in
+# both wheel and source layouts — single path, no fallback logic.
+SPECS_DIR: Path = Path(__file__).parent / "specs"
+
+# Backward-compat alias: the pre-0.14.1 private name. Downstream code
+# still imports this; new code should use ``SPECS_DIR``.
+_SPECS_DIR: Path = SPECS_DIR
+
+
+def load_schema(entity: str) -> dict[str, Any]:
+    """Load and return the JSON Schema for a data entity.
+
+    Args:
+        entity: Entity name (e.g. "observation", "climate").
+
+    Returns:
+        Parsed JSON Schema dict.
+
+    Raises:
+        ValueError: If entity is not in the supported set.
+    """
+    if entity not in _SCHEMA_FILES:
+        valid = sorted(_SCHEMA_FILES)
+        raise ValueError(
+            f"Unknown entity {entity!r}. "
+            f"Supported: {valid}. "
+            f"Note: 'pairs' is not supported — see feature_catalog(source_filter='pairs')."
+        )
+    # Codex review W2-C P2 fix: dict(...) only copies the top-level mapping;
+    # nested objects (properties, $ref blocks) remain shared with _SCHEMA_CACHE.
+    # Caller-side mutations would corrupt every subsequent load_schema() call
+    # process-wide. Deep-copy so the contract holds.
+    if entity in _SCHEMA_CACHE:
+        return copy.deepcopy(_SCHEMA_CACHE[entity])
+
+    spec_path = SPECS_DIR / _SCHEMA_FILES[entity]
+    with spec_path.open() as f:
+        schema = json.load(f)
+    _SCHEMA_CACHE[entity] = schema
+    return copy.deepcopy(schema)
+
+
+# ---------------------------------------------------------------------------
+# Method index — structured summary of all public SDK methods
+# Used by capabilities() to return a machine-readable method index.
+# ---------------------------------------------------------------------------
+
+_METHOD_INDEX: list[dict[str, Any]] = [
+    {
+        "name": "observations",
+        "description": "Get weather observations with optional temporal transform DSL.",
+        "required_params": ["station"],
+        "optional_params": [
+            "from_date",
+            "to_date",
+            "as_of",
+            "obs_type",
+            "resolution",
+            "units",
+            "tz",
+            "format",
+            "columns",
+            "features",
+            "limit",
+            "offset",
+            "as_dataframe",
+            "save_path",
+        ],
+    },
+    {
+        "name": "climate",
+        "description": "Get daily climate reports.",
+        "required_params": ["station"],
+        "optional_params": [
+            "from_date",
+            "to_date",
+            "units",
+            "format",
+            "columns",
+            "limit",
+            "offset",
+            "as_dataframe",
+            "save_path",
+        ],
+    },
+    {
+        "name": "climate_gaps",
+        "description": "Find gaps in climate history.",
+        "required_params": ["station"],
+        "optional_params": ["from_date", "to_date", "as_dataframe"],
+    },
+    {
+        "name": "data_version",
+        "description": "Return a reproducible version token for the dataset at a point in time.",
+        "required_params": ["station", "as_of"],
+        "optional_params": ["from_date", "to_date"],
+    },
+    {
+        "name": "snapshot",
+        "description": "Return everything an AI agent would have known at UTC moment as_of.",
+        "required_params": ["station", "as_of"],
+        "optional_params": [
+            "cli_publication_delay_hours",
+            "include_forecast",
+            "tz_override",
+            "format",
+        ],
+    },
+    {
+        "name": "pairs",
+        "description": "Return one row per settlement date joining observations + climate + forecast.",
+        "required_params": ["station", "from_date", "to_date"],
+        "optional_params": [
+            "include_forecast",
+            "forecast_model",
+            "as_dataframe",
+            "format",
+        ],
+    },
+    {
+        "name": "forecasts",
+        "description": "Historical IEM MOS forecasts (discrete runs with issued_at).",
+        "required_params": ["station"],
+        "optional_params": [
+            "from_date",
+            "to_date",
+            "model",
+            "format",
+            "columns",
+            "as_dataframe",
+            "save_path",
+        ],
+    },
+    {
+        "name": "forecast_series",
+        "description": "Historical Open-Meteo forecast series (seamless hourly).",
+        "required_params": ["station"],
+        "optional_params": [
+            "from_date",
+            "to_date",
+            "model",
+            "format",
+            "columns",
+            "as_dataframe",
+            "save_path",
+        ],
+    },
+    {
+        "name": "feature_catalog",
+        "description": "Return all available features with descriptions and metadata.",
+        "required_params": [],
+        "optional_params": ["include_transforms", "source_filter", "format"],
+    },
+    {
+        "name": "describe",
+        "description": "Return an LLM-ready summary of available features for a station.",
+        "required_params": ["station"],
+        "optional_params": [],
+    },
+    {
+        "name": "availability",
+        "description": "Return actual data availability for a station.",
+        "required_params": ["station"],
+        "optional_params": ["as_of", "data_type"],
+    },
+    {
+        "name": "stations",
+        "description": "Return all stations with active Kalshi markets and SDK support.",
+        "required_params": [],
+        "optional_params": [],
+    },
+    {
+        "name": "station",
+        "description": "Return metadata for a single station by code.",
+        "required_params": ["code"],
+        "optional_params": [],
+    },
+    {
+        "name": "schema",
+        "description": "Return the JSON Schema for a data entity.",
+        "required_params": ["entity"],
+        "optional_params": [],
+    },
+    {
+        "name": "as_tools",
+        "description": "Return Anthropic-compatible tool definitions for all callable SDK methods.",
+        "required_params": [],
+        "optional_params": ["include_market", "include_experimental"],
+    },
+    {
+        "name": "capabilities",
+        "description": "Return a structured summary of all SDK methods and their parameters.",
+        "required_params": [],
+        "optional_params": [],
+    },
+    {
+        "name": "estimate_tokens",
+        "description": "Estimate token count for a data query without fetching records.",
+        "required_params": ["station", "from_date", "to_date"],
+        "optional_params": ["method", "format", "columns"],
+    },
+    {
+        "name": "stream",
+        "description": "Async generator yielding new METAR observations from AWC.",
+        "required_params": ["station"],
+        "optional_params": ["interval", "max_obs", "units", "timeout"],
+    },
+]