mostlyrightmd 1.1.2__tar.gz → 1.2.0__tar.gz

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: mostlyrightmd
-Version: 1.1.2
-Summary: Local-first Python SDK for prediction-market weather research. Calls AWC, IEM, GHCNh, and NWS CLI directly; no hosted backend. Exposes research(station, from_date, to_date) for joined observation + climate rows. Imports as `mostlyright`.
+Version: 1.2.0
+Summary: Python SDK for quants, ML engineers, and AI agents — one interface to public data. Adapters ship weather + prediction-market settlements (Kalshi NHIGH/NLOW, Polymarket) today; SEC filings, Federal Reserve series, court filings, FDA approvals, and equities are next. Schema-versioned, leakage-free, local-first. Imports as `mostlyright`.
+Project-URL: Homepage, https://mostlyright.md
+Project-URL: Documentation, https://mostlyright.md/docs/sdk/
+Project-URL: Repository, https://github.com/mostlyrightmd/mostlyright-sdk
+Project-URL: Issues, https://github.com/mostlyrightmd/mostlyright-sdk/issues
+Project-URL: Changelog, https://github.com/mostlyrightmd/mostlyright-sdk/blob/main/CHANGELOG.md
 Author-email: Robert Tarabcak <tarabcakr@gmail.com>
 License-Expression: MIT
-Keywords: kalshi,metar,polymarket,quantitative-finance,weather
+Keywords: ai-agents,asos,backtesting,kalshi,local-first,machine-learning,metar,ml-training,nws,polymarket,prediction-markets,quant-research,quantitative-finance,schema-versioned,time-series,weather,weather-data
 Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: License :: OSI Approved :: MIT License
@@ -31,11 +36,11 @@ Description-Content-Type: text/markdown
 
 # mostlyrightmd
 
-**The public data SDK for quants and AI agents.**
+**The public-data SDK for quants, ML pipelines, and AI agents.**
 
-`mostlyrightmd` is the Python entry point: core types, schemas, validators, temporal-safety primitives, and the `research()` join that ties observations × climate into one row per settlement date. Direct calls to public APIs (NOAA, NWS, IEM, GHCNh, Kalshi, Polymarket). No hosted backend, no API key.
+`mostlyrightmd` is the Python entry point: core types, schemas, validators, temporal-safety primitives, and the `research()` join that ties weather observations × climate into one row per settlement date — ready for prediction-market backtests (Kalshi NHIGH/NLOW, Polymarket), ML training pipelines, and AI-agent tool calls. Direct calls to public APIs (NOAA, NWS, IEM, GHCNh, Kalshi, Polymarket). No hosted backend, no API key.
 
-Weather + prediction-markets data are live today. SEC filings (EDGAR) and Federal Reserve economic data (FRED) are next.
+Weather + prediction-markets adapters are live today. SEC filings (EDGAR), equities structured data, Federal Reserve series (FRED), court filings, and FDA approvals are next — and the architecture is built to ship an adapter for any public data source.
 
 ## Install
 

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/README.md

@@ -1,10 +1,10 @@
 # mostlyrightmd
 
-**The public data SDK for quants and AI agents.**
+**The public-data SDK for quants, ML pipelines, and AI agents.**
 
-`mostlyrightmd` is the Python entry point: core types, schemas, validators, temporal-safety primitives, and the `research()` join that ties observations × climate into one row per settlement date. Direct calls to public APIs (NOAA, NWS, IEM, GHCNh, Kalshi, Polymarket). No hosted backend, no API key.
+`mostlyrightmd` is the Python entry point: core types, schemas, validators, temporal-safety primitives, and the `research()` join that ties weather observations × climate into one row per settlement date — ready for prediction-market backtests (Kalshi NHIGH/NLOW, Polymarket), ML training pipelines, and AI-agent tool calls. Direct calls to public APIs (NOAA, NWS, IEM, GHCNh, Kalshi, Polymarket). No hosted backend, no API key.
 
-Weather + prediction-markets data are live today. SEC filings (EDGAR) and Federal Reserve economic data (FRED) are next.
+Weather + prediction-markets adapters are live today. SEC filings (EDGAR), equities structured data, Federal Reserve series (FRED), court filings, and FDA approvals are next — and the architecture is built to ship an adapter for any public data source.
 
 ## Install
 

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/pyproject.toml

@@ -1,12 +1,30 @@
 [project]
 name = "mostlyrightmd"
-version = "1.1.2"
-description = "Local-first Python SDK for prediction-market weather research. Calls AWC, IEM, GHCNh, and NWS CLI directly; no hosted backend. Exposes research(station, from_date, to_date) for joined observation + climate rows. Imports as `mostlyright`."
+version = "1.2.0"
+description = "Python SDK for quants, ML engineers, and AI agents — one interface to public data. Adapters ship weather + prediction-market settlements (Kalshi NHIGH/NLOW, Polymarket) today; SEC filings, Federal Reserve series, court filings, FDA approvals, and equities are next. Schema-versioned, leakage-free, local-first. Imports as `mostlyright`."
 readme = "README.md"
 license = "MIT"
 authors = [{ name = "Robert Tarabcak", email = "tarabcakr@gmail.com" }]
 requires-python = ">=3.11"
-keywords = ["weather", "quantitative-finance", "kalshi", "polymarket", "metar"]
+keywords = [
+    "weather",
+    "weather-data",
+    "prediction-markets",
+    "kalshi",
+    "polymarket",
+    "machine-learning",
+    "ml-training",
+    "ai-agents",
+    "backtesting",
+    "quant-research",
+    "quantitative-finance",
+    "metar",
+    "asos",
+    "nws",
+    "time-series",
+    "schema-versioned",
+    "local-first",
+]
 classifiers = [
     "Development Status :: 2 - Pre-Alpha",
     "Intended Audience :: Financial and Insurance Industry",
@@ -15,6 +33,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
 ]
+
 dependencies = [
     # Pinned to v0.14.1 mostlyright deps for inherited test coverage (per TODOS.md item 1)
     "httpx>=0.27",
@@ -27,6 +46,13 @@ dependencies = [
     # (or `mostlyrightmd-weather` directly, which depends on core transitively).
 ]
 
+[project.urls]
+Homepage = "https://mostlyright.md"
+Documentation = "https://mostlyright.md/docs/sdk/"
+Repository = "https://github.com/mostlyrightmd/mostlyright-sdk"
+Issues = "https://github.com/mostlyrightmd/mostlyright-sdk/issues"
+Changelog = "https://github.com/mostlyrightmd/mostlyright-sdk/blob/main/CHANGELOG.md"
+
 [project.optional-dependencies]
 # DataFrame return + parquet cache. Matches v0.14.1's [parquet] extra.
 # Phase 6 (PANDAS3-02): the pandas<3.0 cap is dropped. Pandas 3 byte-

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/src/mostlyright/core/exceptions.py

@@ -25,6 +25,9 @@ from typing import Any
 from ._json_safe import to_json_safe
 
 __all__ = [
+    "DATA_AVAILABILITY_REASONS",
+    "DataAvailabilityError",
+    "DataAvailabilityReason",
     "DeprecatedModelWarning",
     "GribIntegrityError",
     "HistoricalDepthError",
@@ -48,6 +51,26 @@ __all__ = [
 ]
 
 
+#: Shared reason enum — MUST match TS lockstep (Phase 21 D-04). The TS
+#: exception in ``packages-ts/core/src/exceptions/index.ts`` defines an
+#: identical array under ``DATA_AVAILABILITY_REASONS``. Drift here invalidates
+#: every cross-SDK ``except DataAvailabilityError as e: if e.reason == ...``
+#: branch a consumer writes.
+DATA_AVAILABILITY_REASONS: tuple[str, ...] = (
+    "model_unavailable",
+    "out_of_window",
+    "cache_miss",
+    "source_404",
+    "source_5xx",
+    "rate_limited",
+)
+
+#: Type alias kept loose (``str``) rather than ``typing.Literal`` so callers
+#: passing a string variable don't need to ``cast()``. Construction-time
+#: validation in ``DataAvailabilityError.__init__`` enforces the enum.
+DataAvailabilityReason = str
+
+
 class TradewindsError(Exception):
     """Base class for all mostlyright structured errors.
 
@@ -141,6 +164,72 @@ class SourceUnavailableError(TradewindsError):
         return payload
 
 
+class DataAvailabilityError(TradewindsError):
+    """Typed exception for "I tried to fetch and got nothing usable".
+
+    Phase 21 21-09 (Issue #26): replaces overloaded ``SourceUnavailableError``
+    raise sites across at least 3 paths (forecast model unavailable, AWC
+    outside 168h, IEM cache miss, fetcher 404/5xx, rate-limit). Consumers
+    branch on ``reason`` instead of string-matching ``message``:
+
+        try:
+            df = tw.research(...)
+        except DataAvailabilityError as e:
+            if e.reason == "out_of_window":
+                ...  # widen the window
+            elif e.reason == "rate_limited":
+                ...  # back off
+            else:
+                raise
+
+    The reason enum is shared lockstep with the TypeScript SDK — see
+    ``DATA_AVAILABILITY_REASONS`` and the matching const array in
+    ``packages-ts/core/src/exceptions/index.ts``. Drift between SDKs is the
+    load-bearing risk.
+
+    ``SourceUnavailableError`` remains in place for back-compat; new code
+    prefers ``DataAvailabilityError``.
+    """
+
+    default_error_code = "DATA_AVAILABILITY"
+
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        reason: str,
+        hint: str,
+        source: str | None = None,
+        request_id: str | None = None,
+        error_code: str | None = None,
+    ) -> None:
+        if reason not in DATA_AVAILABILITY_REASONS:
+            valid = ", ".join(DATA_AVAILABILITY_REASONS)
+            raise ValueError(
+                f"DataAvailabilityError: unknown reason {reason!r}. Valid: {valid}",
+            )
+        if not isinstance(hint, str) or not hint:
+            raise TypeError(
+                "DataAvailabilityError: hint is required and must be a non-empty string",
+            )
+        super().__init__(
+            message or f"[{reason}] {hint}",
+            error_code=error_code,
+            source=source,
+            request_id=request_id,
+        )
+        self.reason: str = reason
+        self.hint: str = hint
+
+    def _payload(self) -> dict[str, Any]:
+        payload = super()._payload()
+        payload.update(
+            reason=self.reason,
+            hint=self.hint,
+        )
+        return payload
+
+
 class SchemaValidationError(TradewindsError):
     """A DataFrame failed schema validation. Carries the full violation list
     (capped at 10,000 — surplus written to file via §Q file-path mode by the

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/src/mostlyright/forecasts.py

@@ -32,7 +32,6 @@ from typing import TYPE_CHECKING
 from mostlyright.core.exceptions import (
     DeprecatedModelWarning,
     NwpModelNotAvailableError,
-    SourceUnavailableError,
 )
 from mostlyright.core.schemas.forecast_nwp import NWP_MODEL_VALUES
 
@@ -247,12 +246,19 @@ def forecast_nwp(
             forecast_nwp as _impl,
         )
     except ImportError as exc:
-        raise SourceUnavailableError(
-            f"mostlyright.weather.forecast_nwp is not available: {exc}. "
-            "Install mostlyrightmd-weather: pip install mostlyrightmd-weather",
+        # Phase 21 21-09: migrated from SourceUnavailableError to the structural
+        # DataAvailabilityError so consumers can dispatch on `e.reason ==
+        # "model_unavailable"` rather than parsing the install hint out of the
+        # message. The hint is still operator-actionable.
+        from mostlyright.core.exceptions import DataAvailabilityError
+
+        raise DataAvailabilityError(
+            reason="model_unavailable",
+            hint=(
+                f"mostlyright.weather.forecast_nwp is not available: {exc}. "
+                "Install mostlyrightmd-weather: pip install mostlyrightmd-weather"
+            ),
             source=f"nwp.{model}",
-            retryable=False,
-            underlying=str(exc),
         ) from None
 
     return _impl(

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/src/mostlyright/research.py

@@ -1336,6 +1336,49 @@ def _run_qc_and_write_sidecar(
     return summary
 
 
+def _validate_research_kwargs(
+    *,
+    sources: object,
+    source: object,
+    forecast_model: object,
+    forecast_models: object,
+    include_forecast: bool,
+) -> None:
+    """Phase 21 21-01: tighten kwarg validation on `research()`.
+
+    Raises ``TypeError`` early (before any network fetch) when:
+
+    1. Both ``sources=`` and ``source=`` are provided (mutually exclusive —
+       ``sources`` is the LIVE_V1 plural multi-source selector; ``source``
+       is the single-source filter for exact_window).
+    2. Both ``forecast_model=`` and ``forecast_models=`` are provided
+       (mutually exclusive — ``forecast_models`` is the plural multi-model
+       form; supplying both is ambiguous).
+    3. A forecast model is requested but ``include_forecast=False`` (silent
+       no-op would mislead the caller into thinking forecast attached).
+
+    These guards match the TS ``ResearchOptions`` runtime checks lockstep
+    so a cross-SDK consumer sees the same TypeError shape on either side.
+    """
+    if sources is not None and source is not None:
+        raise TypeError(
+            "research(): sources= and source= are mutually exclusive — "
+            "use `sources=` for the LIVE_V1 multi-source selector or "
+            "`source=` for a single-source exact_window query, not both",
+        )
+    if forecast_model is not None and forecast_models is not None:
+        raise TypeError(
+            "research(): forecast_model= and forecast_models= are mutually exclusive — "
+            "use `forecast_models=` for multi-model fan-out or `forecast_model=` for "
+            "a single model, not both",
+        )
+    if (forecast_model is not None or forecast_models is not None) and not include_forecast:
+        raise TypeError(
+            "research(): forecast_model=/forecast_models= require include_forecast=True; "
+            "the model filter is otherwise silently ignored",
+        )
+
+
 def research(
     station: str | None = None,
     from_date: str | None = None,
@@ -1425,6 +1468,19 @@ def research(
     >>> list(df.columns)[:4]  # doctest: +SKIP
     ['station', 'cli_high_f', 'cli_low_f', 'cli_report_type']
     """
+    # Phase 21 21-01: tighten kwarg validation BEFORE any backend dispatch.
+    # Surfaces mutually-exclusive misuses (sources/source, forecast_model/
+    # forecast_models) and silent-no-op cases (forecast_model without
+    # include_forecast=True) up-front. Matches the TS `ResearchOptions`
+    # runtime checks lockstep.
+    _validate_research_kwargs(
+        sources=sources,
+        source=source,
+        forecast_model=forecast_model,
+        forecast_models=forecast_models,
+        include_forecast=include_forecast,
+    )
+
     # Phase 6 codex iter-2 P2 fix: validate backend / return_type kwargs
     # BEFORE any network fetch or cache write. A typo in the new kwargs
     # otherwise hits live APIs + mutates the parquet cache before raising.

{mostlyrightmd-1.1.2 → mostlyrightmd-1.2.0}/tests/test_compose.py

@@ -275,7 +275,10 @@ class TestResearchSignatureValidation:
     def test_sources_and_source_mutually_exclusive(self):
         from mostlyright import research
 
-        with pytest.raises(ValueError, match="mutually exclusive"):
+        # Phase 21 21-01 tightened the validation to raise TypeError (matches
+        # the TS lockstep contract); pre-21-01 raised ValueError. Accept
+        # either to keep the test resilient if 21-01 reverts.
+        with pytest.raises((TypeError, ValueError), match="mutually exclusive"):
             research(
                 station="NYC",
                 from_date="2025-01-06",

mostlyrightmd-1.2.0/tests/test_exceptions_data_availability.py

@@ -0,0 +1,82 @@
+"""Phase 21 21-09: DataAvailabilityError typed exception.
+
+Tests follow the existing exception pattern in mostlyright.core.exceptions:
+``to_dict()`` returns a JSON-safe payload keyed on ``error_code`` /
+``message`` / ``source`` / per-subclass fields. The ``reason`` enum is
+shared lockstep with the TypeScript SDK — drift would invalidate every
+cross-SDK ``except DataAvailabilityError as e: if e.reason == ...`` branch.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from mostlyright.core import exceptions as exc_mod
+from mostlyright.core.exceptions import (
+    DATA_AVAILABILITY_REASONS,
+    DataAvailabilityError,
+    TradewindsError,
+)
+
+
+def test_data_availability_error_constructs_with_all_fields() -> None:
+    exc = DataAvailabilityError(
+        reason="out_of_window",
+        hint="AWC only serves last 168h",
+        source="awc",
+    )
+    assert exc.reason == "out_of_window"
+    assert exc.hint == "AWC only serves last 168h"
+    assert exc.source == "awc"
+
+
+def test_data_availability_error_to_dict_payload() -> None:
+    exc = DataAvailabilityError(
+        reason="model_unavailable",
+        hint="hosted ingest API ships in v0.2.x",
+        source="nwp-stub",
+    )
+    d = exc.to_dict()
+    assert d["error_code"] == "DATA_AVAILABILITY"
+    assert d["reason"] == "model_unavailable"
+    assert d["hint"] == "hosted ingest API ships in v0.2.x"
+    assert d["source"] == "nwp-stub"
+    # Default message derives from reason + hint when not explicitly passed.
+    assert d["message"] == "[model_unavailable] hosted ingest API ships in v0.2.x"
+    # JSON round-trip safe.
+    assert json.loads(json.dumps(d))["reason"] == "model_unavailable"
+
+
+def test_data_availability_error_is_tradewinds_subclass() -> None:
+    """Back-compat: code that catches TradewindsError catches this too."""
+    exc = DataAvailabilityError(reason="rate_limited", hint="back off")
+    assert isinstance(exc, TradewindsError)
+    assert isinstance(exc, Exception)
+
+
+def test_data_availability_error_rejects_unknown_reason() -> None:
+    with pytest.raises(ValueError, match="unknown reason"):
+        DataAvailabilityError(reason="totally_made_up", hint="x")
+
+
+def test_data_availability_error_defaults_source_to_none() -> None:
+    exc = DataAvailabilityError(reason="cache_miss", hint="no cached value")
+    assert exc.source is None
+    # Empty hint rejected.
+    with pytest.raises(TypeError, match="hint is required"):
+        DataAvailabilityError(reason="cache_miss", hint="")
+
+
+def test_data_availability_error_exported_in_all() -> None:
+    assert "DataAvailabilityError" in exc_mod.__all__
+    assert "DATA_AVAILABILITY_REASONS" in exc_mod.__all__
+    # Reason enum matches TS lockstep — drift here invalidates cross-SDK branches.
+    assert DATA_AVAILABILITY_REASONS == (
+        "model_unavailable",
+        "out_of_window",
+        "cache_miss",
+        "source_404",
+        "source_5xx",
+        "rate_limited",
+    )

mostlyrightmd-1.2.0/tests/test_research_kwarg_validation.py

@@ -0,0 +1,81 @@
+"""Phase 21 21-01: tighter kwarg validation on `research()`.
+
+Asserts that mutually-exclusive misuses and silent-no-op cases raise
+`TypeError` BEFORE any network fetch. Matches the TS `ResearchOptions`
+runtime checks lockstep — cross-SDK consumers see the same shape on
+either side.
+"""
+
+from __future__ import annotations
+
+import pytest
+from mostlyright import research
+
+
+def test_sources_and_source_mutually_exclusive() -> None:
+    with pytest.raises(TypeError, match="mutually exclusive"):
+        research(
+            "KNYC",
+            "2025-01-06",
+            "2025-01-12",
+            sources=["awc"],
+            source="iem",
+        )
+
+
+def test_forecast_model_and_forecast_models_mutually_exclusive() -> None:
+    with pytest.raises(TypeError, match="mutually exclusive"):
+        research(
+            "KNYC",
+            "2025-01-06",
+            "2025-01-12",
+            include_forecast=True,
+            forecast_model="gfs",
+            forecast_models=["gfs", "nbm"],
+        )
+
+
+def test_forecast_model_requires_include_forecast() -> None:
+    with pytest.raises(TypeError, match="include_forecast=True"):
+        research(
+            "KNYC",
+            "2025-01-06",
+            "2025-01-12",
+            forecast_model="gfs",
+        )
+
+
+def test_forecast_models_requires_include_forecast() -> None:
+    with pytest.raises(TypeError, match="include_forecast=True"):
+        research(
+            "KNYC",
+            "2025-01-06",
+            "2025-01-12",
+            forecast_models=["gfs"],
+        )
+
+
+def test_validator_fires_before_network_fetch(monkeypatch) -> None:
+    """The validator must run BEFORE any HTTP or cache I/O — a typo in
+    kwargs should not first hit AWC / IEM / GHCNh.
+
+    We assert this by stubbing the backend-dispatch validator to raise a
+    sentinel exception. If the kwarg validator runs first, we see TypeError;
+    if it runs after the backend validator, we see RuntimeError.
+    """
+
+    def _sentinel(_backend, _return_type):
+        raise RuntimeError("backend validator ran too early")
+
+    monkeypatch.setattr(
+        "mostlyright.core._backend_dispatch.validate_backend_kwargs",
+        _sentinel,
+    )
+    with pytest.raises(TypeError):
+        research(
+            "KNYC",
+            "2025-01-06",
+            "2025-01-12",
+            sources=["awc"],
+            source="iem",
+        )