flopsindex 0.1.0__tar.gz

flopsindex-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: flopsindex
+Version: 0.1.0
+Summary: Python SDK for FLOPS Index — live GPU compute and inference token pricing reference rates
+Author-email: FLOPS Index <support@flopsindex.com>
+License: MIT
+Project-URL: Homepage, https://app.flopsindex.com
+Project-URL: Documentation, https://app.flopsindex.com/llms.txt
+Project-URL: Source, https://github.com/zeroatflops/flopsindex
+Project-URL: Methodology, https://app.flopsindex.com/v1/methodology
+Keywords: flops,gpu,pricing,compute,inference,benchmark,fintech
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# flopsindex — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+```bash
+pip install flopsindex
+```
+
+Live GPU compute pricing + LLM inference token pricing reference rates
+from the FLOPS Index. Single dependency-free SDK over the FLOPS HTTP
+API.
+
+## 30-second example
+
+```python
+from flopsindex import Client
+
+c = Client()  # picks up FLOPSINDEX_API_KEY if set; works auth-free for public methods
+
+# Public, auth-free — works with no API key
+print(c.price("FLCI-H100"))
+# {'index_id': 'FLCI-H100', 'value': 2.45, 'unit': 'USD/GPU-hr',
+#  'ts': '2026-05-17T14:00:00+00:00', 'tier': 'LIVE',
+#  'confidence': 'HIGH', 'verify_url': '...', 'citation_url': '...'}
+
+print(c.timeseries("FLCI-H100", "7d"))   # ≤200 decimated points
+print(c.search("h100 spot"))             # NL → canonical slugs
+print(c.methodology("flci-h100", "v0.9"))  # versioned methodology + frontmatter
+```
+
+## Authentication
+
+The SDK reads an API key from `FLOPSINDEX_API_KEY`:
+
+```bash
+export FLOPSINDEX_API_KEY="flops_xxxxxxxxx"
+```
+
+Or pass directly:
+
+```python
+c = Client(api_key="flops_xxxxxxxxx")
+```
+
+**Auth-free methods** (work without a key): `price`, `timeseries`,
+`search`, `methodology`, `methodologies`, `verify`.
+
+**Partner-tier methods** (require a key): `catalog`, `index_current`,
+`index_history`, `compute_margin`, `recompute_audit`.
+
+If you call a partner-tier method without a key, you'll get
+`FlopsAuthError`. Public methods always work — the API key just
+unlocks higher rate-limit tiers when you have one.
+
+## Citation in code
+
+When citing a FLOPS price in code, contracts, or research, ALWAYS
+include the methodology version (every response carries it under
+`methodology_version`):
+
+```python
+tick = c.index_current("FLCI-H100")
+print(f"Settled at ${tick['current_value']:.2f}/GPU-hr per "
+      f"{tick['methodology_version']}")
+# Settled at $2.45/GPU-hr per flci-h100@v0.9
+```
+
+The version is the contract anchor — partner replays + recompute
+audits pin against it.
+
+## Methods
+
+| Method                | Auth      | Returns                            |
+|-----------------------|-----------|------------------------------------|
+| `price(index_id)`     | none      | latest tick                        |
+| `timeseries(id, range)` | none    | decimated points (≤200)            |
+| `search(q)`           | none      | NL → slug results                  |
+| `methodologies()`     | none      | list of all methodologies          |
+| `methodology(slug, version)` | none | one methodology doc (markdown + JSON) |
+| `verify(id, value)`   | none      | does the value match our tick?     |
+| `catalog()`           | partner   | full envelope w/ methodology_version |
+| `index_current(id)`   | partner   | partner-tier per-index lookup      |
+| `index_history(id)`   | partner   | up to 720 historical ticks         |
+| `compute_margin(...)` | partner   | derived: price − power − rack      |
+| `recompute_audit(...)`| partner   | audit receipts (IOSCO substrate)   |
+
+## Naming conventions
+
+- `FLCI-{model}` — composite spot+OD+DePIN
+- `FLOPS-{model}-{OD|SPOT|DEPIN}` — single-tier specific
+- `ITPI-{model_id}-{INPUT|OUTPUT}` — inference token pricing
+- `CLRI-{model}-{tenor}` — forward / term rates (partner-tier only)
+
+Use `c.search()` if you don't know the exact slug.
+
+## Errors
+
+```python
+from flopsindex import Client, FlopsNotFoundError, FlopsAuthError
+
+c = Client()
+try:
+    tick = c.price("FLCI-UNKNOWN")
+except FlopsNotFoundError as e:
+    print(f"index not found: {e.detail}")
+```
+
+Hierarchy: `FlopsError` → `FlopsAuthError` / `FlopsNotFoundError` /
+`FlopsRateLimitError` / `FlopsServerError`. All errors carry
+`.status_code` and `.detail`.
+
+## Not the MCP server
+
+`flopsindex` (this package) is a HTTP client SDK. The MCP server for
+AI agents is a separate package: `pip install flopsindex-mcp`. See
+https://github.com/zeroatflops/flopsindex-mcp for that one.
+
+## Methodology
+
+Every published price is backed by a versioned methodology document.
+Citation hooks live at:
+
+```
+https://app.flopsindex.com/v1/methodology/{slug}/{version}
+```
+
+For example, `https://app.flopsindex.com/v1/methodology/flci-h100/v0.9`.

flopsindex-0.1.0/README.md

@@ -0,0 +1,130 @@
+# flopsindex — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+```bash
+pip install flopsindex
+```
+
+Live GPU compute pricing + LLM inference token pricing reference rates
+from the FLOPS Index. Single dependency-free SDK over the FLOPS HTTP
+API.
+
+## 30-second example
+
+```python
+from flopsindex import Client
+
+c = Client()  # picks up FLOPSINDEX_API_KEY if set; works auth-free for public methods
+
+# Public, auth-free — works with no API key
+print(c.price("FLCI-H100"))
+# {'index_id': 'FLCI-H100', 'value': 2.45, 'unit': 'USD/GPU-hr',
+#  'ts': '2026-05-17T14:00:00+00:00', 'tier': 'LIVE',
+#  'confidence': 'HIGH', 'verify_url': '...', 'citation_url': '...'}
+
+print(c.timeseries("FLCI-H100", "7d"))   # ≤200 decimated points
+print(c.search("h100 spot"))             # NL → canonical slugs
+print(c.methodology("flci-h100", "v0.9"))  # versioned methodology + frontmatter
+```
+
+## Authentication
+
+The SDK reads an API key from `FLOPSINDEX_API_KEY`:
+
+```bash
+export FLOPSINDEX_API_KEY="flops_xxxxxxxxx"
+```
+
+Or pass directly:
+
+```python
+c = Client(api_key="flops_xxxxxxxxx")
+```
+
+**Auth-free methods** (work without a key): `price`, `timeseries`,
+`search`, `methodology`, `methodologies`, `verify`.
+
+**Partner-tier methods** (require a key): `catalog`, `index_current`,
+`index_history`, `compute_margin`, `recompute_audit`.
+
+If you call a partner-tier method without a key, you'll get
+`FlopsAuthError`. Public methods always work — the API key just
+unlocks higher rate-limit tiers when you have one.
+
+## Citation in code
+
+When citing a FLOPS price in code, contracts, or research, ALWAYS
+include the methodology version (every response carries it under
+`methodology_version`):
+
+```python
+tick = c.index_current("FLCI-H100")
+print(f"Settled at ${tick['current_value']:.2f}/GPU-hr per "
+      f"{tick['methodology_version']}")
+# Settled at $2.45/GPU-hr per flci-h100@v0.9
+```
+
+The version is the contract anchor — partner replays + recompute
+audits pin against it.
+
+## Methods
+
+| Method                | Auth      | Returns                            |
+|-----------------------|-----------|------------------------------------|
+| `price(index_id)`     | none      | latest tick                        |
+| `timeseries(id, range)` | none    | decimated points (≤200)            |
+| `search(q)`           | none      | NL → slug results                  |
+| `methodologies()`     | none      | list of all methodologies          |
+| `methodology(slug, version)` | none | one methodology doc (markdown + JSON) |
+| `verify(id, value)`   | none      | does the value match our tick?     |
+| `catalog()`           | partner   | full envelope w/ methodology_version |
+| `index_current(id)`   | partner   | partner-tier per-index lookup      |
+| `index_history(id)`   | partner   | up to 720 historical ticks         |
+| `compute_margin(...)` | partner   | derived: price − power − rack      |
+| `recompute_audit(...)`| partner   | audit receipts (IOSCO substrate)   |
+
+## Naming conventions
+
+- `FLCI-{model}` — composite spot+OD+DePIN
+- `FLOPS-{model}-{OD|SPOT|DEPIN}` — single-tier specific
+- `ITPI-{model_id}-{INPUT|OUTPUT}` — inference token pricing
+- `CLRI-{model}-{tenor}` — forward / term rates (partner-tier only)
+
+Use `c.search()` if you don't know the exact slug.
+
+## Errors
+
+```python
+from flopsindex import Client, FlopsNotFoundError, FlopsAuthError
+
+c = Client()
+try:
+    tick = c.price("FLCI-UNKNOWN")
+except FlopsNotFoundError as e:
+    print(f"index not found: {e.detail}")
+```
+
+Hierarchy: `FlopsError` → `FlopsAuthError` / `FlopsNotFoundError` /
+`FlopsRateLimitError` / `FlopsServerError`. All errors carry
+`.status_code` and `.detail`.
+
+## Not the MCP server
+
+`flopsindex` (this package) is a HTTP client SDK. The MCP server for
+AI agents is a separate package: `pip install flopsindex-mcp`. See
+https://github.com/zeroatflops/flopsindex-mcp for that one.
+
+## Methodology
+
+Every published price is backed by a versioned methodology document.
+Citation hooks live at:
+
+```
+https://app.flopsindex.com/v1/methodology/{slug}/{version}
+```
+
+For example, `https://app.flopsindex.com/v1/methodology/flci-h100/v0.9`.

flopsindex-0.1.0/flopsindex/__init__.py

@@ -0,0 +1,39 @@
+"""flopsindex — Python SDK for the FLOPS Compute Intelligence API.
+
+```python
+from flopsindex import Client
+
+c = Client()  # auth from FLOPSINDEX_API_KEY env var
+tick = c.price("FLCI-H100")              # current price
+hist = c.timeseries("FLCI-H100", "7d")  # 7-day decimated timeseries
+matches = c.search("h100 spot")          # NL → index_id
+catalog = c.catalog()                    # full catalog (partner-tier)
+doc = c.methodology("flci-h100", "v0.9") # raw methodology markdown
+margin = c.compute_margin(sku="h100_sxm5", region="us_west")
+```
+
+The public surface is auth-free (price / timeseries / search /
+methodology) — those work without an API key. catalog +
+compute_margin + recompute_audit need a key.
+
+Set the key via:
+  - `FLOPSINDEX_API_KEY` env var (recommended)
+  - `Client(api_key="flops_xxx")` constructor
+"""
+from flopsindex.client import Client
+from flopsindex.exceptions import (
+    FlopsError,
+    FlopsAuthError,
+    FlopsNotFoundError,
+    FlopsRateLimitError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "FlopsError",
+    "FlopsAuthError",
+    "FlopsNotFoundError",
+    "FlopsRateLimitError",
+    "__version__",
+]

flopsindex-0.1.0/flopsindex/client.py

@@ -0,0 +1,390 @@
+"""flopsindex consumer SDK — read-side client for the FLOPS API.
+
+Architecture:
+  - All methods are synchronous (most consumers are scripts /
+    notebooks / finance pipelines, not async services). An async
+    wrapper can be added in v0.2 without breaking the sync surface.
+  - HTTP via stdlib `urllib` so the SDK has ZERO third-party
+    dependencies for the basic read path. `httpx` would be nicer
+    but locks consumers into a specific async runtime.
+  - API key resolved from constructor → FLOPSINDEX_API_KEY env var.
+  - Public-surface methods (price / timeseries / search / methodology)
+    work without an API key.
+  - Partner-tier methods (catalog / compute_margin / recompute_audit /
+    indices) require an API key; raise FlopsAuthError if missing.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+import urllib.parse
+import urllib.request
+import urllib.error
+from typing import Any, Dict, List, Optional, Union
+
+from flopsindex.exceptions import (
+    FlopsAuthError,
+    FlopsError,
+    FlopsNotFoundError,
+    FlopsRateLimitError,
+    FlopsServerError,
+)
+
+logger = logging.getLogger("flopsindex")
+
+_DEFAULT_BASE_URL = "https://app.flopsindex.com"
+_DEFAULT_TIMEOUT = 30
+_USER_AGENT_TEMPLATE = "flopsindex/{version} (+https://flopsindex.com)"
+
+
+class Client:
+    """The FLOPS API consumer client.
+
+    Most users want the no-arg form::
+
+        from flopsindex import Client
+        c = Client()  # FLOPSINDEX_API_KEY from env
+
+    Override base_url to hit a staging instance::
+
+        c = Client(base_url="https://staging.flopsindex.com")
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = _DEFAULT_TIMEOUT,
+        user_agent: Optional[str] = None,
+    ):
+        self._api_key = api_key or os.environ.get("FLOPSINDEX_API_KEY")
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        # Lazy import to avoid circular ref
+        from flopsindex import __version__ as _v
+        self._user_agent = user_agent or _USER_AGENT_TEMPLATE.format(version=_v)
+
+    # -----------------------------------------------------------------
+    # PUBLIC (auth-free) — works without an API key
+    # -----------------------------------------------------------------
+
+    def price(self, index_id: str) -> Dict[str, Any]:
+        """Latest published price for one SPOT index. Auth-free.
+
+        Returns ``{index_id, value, unit, ts, tier, confidence,
+        verify_url, citation_url}``.
+
+        Raises FlopsNotFoundError if the slug is unknown or is not on
+        the public spot surface (forwards / derived stay partner-tier).
+        """
+        return self._get(f"/v1/price/{urllib.parse.quote(index_id, safe='')}",
+                         require_auth=False)
+
+    def timeseries(self, index_id: str, range: str = "7d") -> Dict[str, Any]:
+        """Decimated timeseries (≤200 points). Auth-free.
+
+        ``range`` ∈ {"24h", "7d", "30d", "90d", "1y"}.
+        """
+        return self._get(
+            f"/v1/ts/{urllib.parse.quote(index_id, safe='')}",
+            params={"range": range}, require_auth=False,
+        )
+
+    def search(self, q: str, limit: int = 10) -> Dict[str, Any]:
+        """Natural-language → canonical index_id. Auth-free.
+
+        Returns ``{q, count, results: [{index_id, family,
+        citation_url}, ...]}``.
+        """
+        return self._get("/v1/search",
+                         params={"q": q, "limit": str(limit)},
+                         require_auth=False)
+
+    def methodology(
+        self, slug: str, version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Versioned methodology document (with parsed frontmatter).
+
+        Auth-free. If ``version`` is None, returns the version history
+        list. Otherwise returns the doc with body_md + frontmatter.
+
+        ``slug`` is the lower-kebab methodology_id (e.g. "flci-h100",
+        "itpi-canonical", "flops-h100-od").
+        """
+        if version is None:
+            return self._get(
+                f"/v1/methodology/{urllib.parse.quote(slug)}/versions",
+                require_auth=False)
+        return self._get(
+            f"/v1/methodology/{urllib.parse.quote(slug)}/"
+            f"{urllib.parse.quote(version)}.json",
+            require_auth=False)
+
+    def methodologies(self) -> Dict[str, Any]:
+        """List every published methodology + active version. Auth-free."""
+        return self._get("/v1/methodology", require_auth=False)
+
+    def verify(self, index_id: str, value: float) -> Dict[str, Any]:
+        """Verify whether the given value matches our latest published
+        tick for the index_id (within tolerance). Auth-free citation
+        check. Raises on non-2xx upstream — use ``verify_handshake`` if
+        you want a defensive envelope instead."""
+        return self._get(
+            "/v1/verify",
+            params={"index_id": index_id, "value": str(value)},
+            require_auth=False)
+
+    def verify_handshake(
+        self,
+        index_id: str,
+        value: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Defensive verify — returns either the canonical record OR a
+        structured ``{ok: false, reason, upstream_status}`` envelope on
+        any non-2xx response. Never raises for HTTP errors.
+
+        This is the citation handshake idiom Track D promotes::
+
+            tick = client.price("FLCI-H100")
+            check = client.verify_handshake("FLCI-H100", tick["value"])
+            if check.get("ok") is False:
+                # upstream broken / endpoint pending — caller decides
+                ...
+            elif check.get("verified"):
+                cite(tick, source_url=check["source_url"])
+
+        Mirrors the MCP server's ``_defensive_get`` shape so an agent
+        switching between MCP and direct SDK gets the same error envelope.
+
+        ``value`` is optional — omit to ask "what's the latest tick"
+        without committing a value to verify against.
+        """
+        params: Dict[str, str] = {"index_id": index_id}
+        if value is not None:
+            params["value"] = str(value)
+        url = self._base_url + "/v1/verify?" + urllib.parse.urlencode(params)
+        headers = {"User-Agent": self._user_agent, "Accept": "application/json"}
+        try:
+            req = urllib.request.Request(url, headers=headers)
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                body = resp.read().decode("utf-8")
+                try:
+                    return json.loads(body)
+                except ValueError:
+                    return {"ok": False, "reason": "invalid_json",
+                            "upstream_status": resp.status, "url": url}
+        except urllib.error.HTTPError as e:
+            code = e.code
+            if code in (401, 403):
+                return {"ok": False, "reason": "auth_required",
+                        "upstream_status": code, "url": url}
+            if code == 404:
+                return {"ok": False, "reason": "endpoint_pending",
+                        "upstream_status": code, "url": url}
+            if code >= 500:
+                return {"ok": False, "reason": "upstream_http_error",
+                        "upstream_status": code, "url": url}
+            return {"ok": False, "reason": "client_error",
+                    "upstream_status": code, "url": url}
+        except urllib.error.URLError as exc:
+            return {"ok": False, "reason": "network_error",
+                    "url": url, "detail": str(exc.reason)[:300]}
+        except Exception as exc:  # noqa: BLE001
+            return {"ok": False, "reason": "network_error",
+                    "url": url, "detail": str(exc)[:300]}
+
+    # -----------------------------------------------------------------
+    # PARTNER-TIER (X-FLOPS-Api-Key required)
+    # -----------------------------------------------------------------
+
+    def catalog(self) -> Dict[str, Any]:
+        """Full index catalog with methodology_version stamps + tier
+        labels. Partner-tier — requires API key.
+
+        For an auth-free subset filtered to spot only, use the public
+        catalog mirror at GET /v2/catalog/public (no SDK method —
+        agents discover via /llms.txt).
+        """
+        return self._get("/v1/catalog", require_auth=True)
+
+    def index_current(self, index_id: str) -> Dict[str, Any]:
+        """Partner-tier per-index lookup with full envelope (value,
+        as_of, num_sources, data_tier, methodology_version,
+        verify_url). Returns 404 for unknown index_ids; differs from
+        ``price()`` in that the partner-tier surface knows about
+        non-spot families (forwards, derived, etc.) too."""
+        return self._get(
+            f"/v1/indices/{urllib.parse.quote(index_id, safe='')}/current",
+            require_auth=True)
+
+    def index_history(
+        self, index_id: str, limit: int = 24,
+    ) -> Dict[str, Any]:
+        """Partner-tier per-index history. ``limit`` capped at 720."""
+        return self._get(
+            f"/v1/indices/{urllib.parse.quote(index_id, safe='')}/history",
+            params={"limit": str(min(limit, 720))},
+            require_auth=True)
+
+    def compute_margin(
+        self, sku: str, region: str = "us_east",
+        pue: float = 1.3, kwh_source: str = "live_lmp",
+        kwh_override: Optional[float] = None,
+        rack_amortization: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """Compute-margin endpoint (Tier 2 #5). Partner-tier.
+
+        Returns the full margin decomposition:
+          {price, power_cost, rack_amortization, margin, margin_pct,
+          inputs: {chip_power_kw, pue, kwh_source, kwh_usd, ...}}
+        """
+        params = {"sku": sku, "region": region,
+                  "pue": str(pue), "kwh_source": kwh_source}
+        if kwh_override is not None:
+            params["kwh_override"] = str(kwh_override)
+        if rack_amortization is not None:
+            params["rack_amortization"] = str(rack_amortization)
+        return self._get("/v1/derived/compute-margin",
+                         params=params, require_auth=True)
+
+    def recompute_audit(
+        self,
+        methodology_id: Optional[str] = None,
+        index_id: Optional[str] = None,
+        status: Optional[str] = None,
+        since_hours: int = 168,
+        limit: int = 100,
+    ) -> Dict[str, Any]:
+        """Recompute audit receipts (Tier 2 #4). Partner-tier.
+
+        Returns ``{count, receipts: [...]}`` with each receipt
+        carrying methodology_version, window, shipped vs recomputed
+        values, variance_bps, inputs_hash + receipt_hash for
+        external citation.
+        """
+        params: Dict[str, str] = {"since_hours": str(since_hours),
+                                  "limit": str(limit)}
+        if methodology_id:
+            params["methodology_id"] = methodology_id
+        if index_id:
+            params["index_id"] = index_id
+        if status:
+            params["status"] = status
+        return self._get("/v1/audit/recompute",
+                         params=params, require_auth=True)
+
+    def gpu_capex(self, sku: Optional[str] = None) -> Dict[str, Any]:
+        """Per-SKU GPU module reference price — 3-tier LIVE cascade.
+
+        Cascade per SKU:
+          T2 LIVE_USASPENDING — federal procurement median (real new),
+                                preferred when >=3 awards in 180d
+          T1 LIVE_EBAY_X1.15  — eBay completed-listings trimmed-median × 1.15
+          T3 SEED             — quarterly reference fallback
+
+        Returns the single-SKU envelope (price_usd, tier, source,
+        effective, secondary_market_range_usd, plus live_observations +
+        also_seed when LIVE). With ``sku=None`` returns the full seed
+        map with meta.live_api_status.
+
+        No auth required. Methodology:
+        https://app.flopsindex.com/methodology/GPU_CAPEX_LIVE_METHODOLOGY.md
+
+        NOTE: there is no public LIVE MSRP API for datacenter GPUs —
+        NVIDIA/AMD/Huawei are channel-priced through OEMs. The LIVE
+        tiers here are federal-procurement (T2) or secondary-market ×
+        markup (T1), not chip-new MSRP.
+        """
+        if sku:
+            return self._get(f"/v1/refdata/gpu-capex/{sku}", require_auth=False)
+        return self._get("/v1/refdata/gpu-capex", require_auth=False)
+
+    def gpu_capex_observations(
+        self,
+        sku: str,
+        limit: int = 50,
+    ) -> Dict[str, Any]:
+        """Audit-trail surface — raw gpu_capex_observations rows for a SKU.
+
+        Returns the rows that feed the LIVE-tier cascade — partners +
+        auditors can drill from a published LIVE value back to the
+        underlying federal-contract / eBay-listing records.
+
+        Returns ``{sku, count, limit, rows, by_source, methodology}``.
+        Limit clamped server-side to [1, 500]. No auth required;
+        503 if migration 012 hasn't been applied to this Neon branch.
+        """
+        return self._get(
+            f"/v1/refdata/gpu-capex/{sku}/observations",
+            params={"limit": str(int(limit))},
+            require_auth=False,
+        )
+
+    # -----------------------------------------------------------------
+    # HTTP plumbing
+    # -----------------------------------------------------------------
+
+    def _get(
+        self,
+        path: str,
+        *,
+        params: Optional[Dict[str, str]] = None,
+        require_auth: bool = False,
+    ) -> Dict[str, Any]:
+        url = self._base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+
+        headers = {"User-Agent": self._user_agent, "Accept": "application/json"}
+        if require_auth:
+            if not self._api_key:
+                raise FlopsAuthError(
+                    f"{path} requires an API key. Set FLOPSINDEX_API_KEY "
+                    f"or pass api_key= to Client()."
+                )
+            headers["X-FLOPS-Api-Key"] = self._api_key
+        elif self._api_key:
+            # Send the key on public paths too — gives the server
+            # higher rate-limit allowance for keyed callers.
+            headers["X-FLOPS-Api-Key"] = self._api_key
+
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                body = resp.read().decode("utf-8")
+                return json.loads(body)
+        except urllib.error.HTTPError as e:
+            self._raise_for_status(e.code, e.read().decode("utf-8", "replace"),
+                                   e.headers)
+        except urllib.error.URLError as e:
+            raise FlopsError(f"network error: {e.reason}")
+        # unreachable
+        raise FlopsError(f"unexpected: {path}")
+
+    def _raise_for_status(
+        self, status_code: int, body: str, headers,
+    ) -> None:
+        try:
+            detail = json.loads(body)
+        except Exception:
+            detail = body
+        msg = f"HTTP {status_code}"
+        if isinstance(detail, dict) and "detail" in detail:
+            msg += f": {detail['detail']}"
+        if status_code in (401, 403):
+            raise FlopsAuthError(msg, status_code=status_code, detail=detail)
+        if status_code == 404:
+            raise FlopsNotFoundError(msg, status_code=status_code, detail=detail)
+        if status_code == 429:
+            retry_after = 60
+            try:
+                retry_after = int(headers.get("Retry-After", "60"))
+            except (ValueError, TypeError, AttributeError):
+                pass
+            raise FlopsRateLimitError(msg, retry_after_seconds=retry_after,
+                                      status_code=status_code, detail=detail)
+        if 500 <= status_code < 600:
+            raise FlopsServerError(msg, status_code=status_code, detail=detail)
+        raise FlopsError(msg, status_code=status_code, detail=detail)

flopsindex-0.1.0/flopsindex/exceptions.py

@@ -0,0 +1,39 @@
+"""flopsindex SDK exception hierarchy.
+
+All SDK errors descend from `FlopsError` so callers can catch one
+thing if they don't care about the distinction.
+"""
+
+
+class FlopsError(Exception):
+    """Base SDK error. Carries (status_code, detail) when raised from
+    an HTTP response."""
+
+    def __init__(self, message: str, status_code: int = 0, detail=None):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(message)
+
+
+class FlopsAuthError(FlopsError):
+    """401 / 403 — bad or missing API key, or scope insufficient."""
+
+
+class FlopsNotFoundError(FlopsError):
+    """404 — index_id / methodology slug doesn't exist OR is not on
+    the public surface (forwards/term-rates/derived) and you're
+    calling an unauthenticated method."""
+
+
+class FlopsRateLimitError(FlopsError):
+    """429 — rate limit exceeded. `retry_after_seconds` populated
+    when the response carries the standard header."""
+
+    def __init__(self, message: str, retry_after_seconds: int = 60,
+                 status_code: int = 429, detail=None):
+        self.retry_after_seconds = retry_after_seconds
+        super().__init__(message, status_code, detail)
+
+
+class FlopsServerError(FlopsError):
+    """5xx — server-side fault. Usually transient; retry with backoff."""

flopsindex-0.1.0/flopsindex.egg-info/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: flopsindex
+Version: 0.1.0
+Summary: Python SDK for FLOPS Index — live GPU compute and inference token pricing reference rates
+Author-email: FLOPS Index <support@flopsindex.com>
+License: MIT
+Project-URL: Homepage, https://app.flopsindex.com
+Project-URL: Documentation, https://app.flopsindex.com/llms.txt
+Project-URL: Source, https://github.com/zeroatflops/flopsindex
+Project-URL: Methodology, https://app.flopsindex.com/v1/methodology
+Keywords: flops,gpu,pricing,compute,inference,benchmark,fintech
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# flopsindex — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/flopsindex.svg)](https://pypi.org/project/flopsindex/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+```bash
+pip install flopsindex
+```
+
+Live GPU compute pricing + LLM inference token pricing reference rates
+from the FLOPS Index. Single dependency-free SDK over the FLOPS HTTP
+API.
+
+## 30-second example
+
+```python
+from flopsindex import Client
+
+c = Client()  # picks up FLOPSINDEX_API_KEY if set; works auth-free for public methods
+
+# Public, auth-free — works with no API key
+print(c.price("FLCI-H100"))
+# {'index_id': 'FLCI-H100', 'value': 2.45, 'unit': 'USD/GPU-hr',
+#  'ts': '2026-05-17T14:00:00+00:00', 'tier': 'LIVE',
+#  'confidence': 'HIGH', 'verify_url': '...', 'citation_url': '...'}
+
+print(c.timeseries("FLCI-H100", "7d"))   # ≤200 decimated points
+print(c.search("h100 spot"))             # NL → canonical slugs
+print(c.methodology("flci-h100", "v0.9"))  # versioned methodology + frontmatter
+```
+
+## Authentication
+
+The SDK reads an API key from `FLOPSINDEX_API_KEY`:
+
+```bash
+export FLOPSINDEX_API_KEY="flops_xxxxxxxxx"
+```
+
+Or pass directly:
+
+```python
+c = Client(api_key="flops_xxxxxxxxx")
+```
+
+**Auth-free methods** (work without a key): `price`, `timeseries`,
+`search`, `methodology`, `methodologies`, `verify`.
+
+**Partner-tier methods** (require a key): `catalog`, `index_current`,
+`index_history`, `compute_margin`, `recompute_audit`.
+
+If you call a partner-tier method without a key, you'll get
+`FlopsAuthError`. Public methods always work — the API key just
+unlocks higher rate-limit tiers when you have one.
+
+## Citation in code
+
+When citing a FLOPS price in code, contracts, or research, ALWAYS
+include the methodology version (every response carries it under
+`methodology_version`):
+
+```python
+tick = c.index_current("FLCI-H100")
+print(f"Settled at ${tick['current_value']:.2f}/GPU-hr per "
+      f"{tick['methodology_version']}")
+# Settled at $2.45/GPU-hr per flci-h100@v0.9
+```
+
+The version is the contract anchor — partner replays + recompute
+audits pin against it.
+
+## Methods
+
+| Method                | Auth      | Returns                            |
+|-----------------------|-----------|------------------------------------|
+| `price(index_id)`     | none      | latest tick                        |
+| `timeseries(id, range)` | none    | decimated points (≤200)            |
+| `search(q)`           | none      | NL → slug results                  |
+| `methodologies()`     | none      | list of all methodologies          |
+| `methodology(slug, version)` | none | one methodology doc (markdown + JSON) |
+| `verify(id, value)`   | none      | does the value match our tick?     |
+| `catalog()`           | partner   | full envelope w/ methodology_version |
+| `index_current(id)`   | partner   | partner-tier per-index lookup      |
+| `index_history(id)`   | partner   | up to 720 historical ticks         |
+| `compute_margin(...)` | partner   | derived: price − power − rack      |
+| `recompute_audit(...)`| partner   | audit receipts (IOSCO substrate)   |
+
+## Naming conventions
+
+- `FLCI-{model}` — composite spot+OD+DePIN
+- `FLOPS-{model}-{OD|SPOT|DEPIN}` — single-tier specific
+- `ITPI-{model_id}-{INPUT|OUTPUT}` — inference token pricing
+- `CLRI-{model}-{tenor}` — forward / term rates (partner-tier only)
+
+Use `c.search()` if you don't know the exact slug.
+
+## Errors
+
+```python
+from flopsindex import Client, FlopsNotFoundError, FlopsAuthError
+
+c = Client()
+try:
+    tick = c.price("FLCI-UNKNOWN")
+except FlopsNotFoundError as e:
+    print(f"index not found: {e.detail}")
+```
+
+Hierarchy: `FlopsError` → `FlopsAuthError` / `FlopsNotFoundError` /
+`FlopsRateLimitError` / `FlopsServerError`. All errors carry
+`.status_code` and `.detail`.
+
+## Not the MCP server
+
+`flopsindex` (this package) is a HTTP client SDK. The MCP server for
+AI agents is a separate package: `pip install flopsindex-mcp`. See
+https://github.com/zeroatflops/flopsindex-mcp for that one.
+
+## Methodology
+
+Every published price is backed by a versioned methodology document.
+Citation hooks live at:
+
+```
+https://app.flopsindex.com/v1/methodology/{slug}/{version}
+```
+
+For example, `https://app.flopsindex.com/v1/methodology/flci-h100/v0.9`.

flopsindex-0.1.0/flopsindex.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+flopsindex/__init__.py
+flopsindex/client.py
+flopsindex/exceptions.py
+flopsindex.egg-info/PKG-INFO
+flopsindex.egg-info/SOURCES.txt
+flopsindex.egg-info/dependency_links.txt
+flopsindex.egg-info/requires.txt
+flopsindex.egg-info/top_level.txt
+tests/test_client.py

flopsindex-0.1.0/flopsindex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flopsindex-0.1.0/flopsindex.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7.0

flopsindex-0.1.0/flopsindex.egg-info/top_level.txt

@@ -0,0 +1 @@
+flopsindex

flopsindex-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flopsindex"
+version = "0.1.0"
+description = "Python SDK for FLOPS Index — live GPU compute and inference token pricing reference rates"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "FLOPS Index", email = "support@flopsindex.com"}]
+keywords = ["flops", "gpu", "pricing", "compute", "inference", "benchmark", "fintech"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+# Zero external dependencies for the basic read path (urllib stdlib).
+# httpx etc. are deliberately omitted so the SDK can drop into a
+# finance-team Excel-add-in-VBA-host or a notebook without
+# pulling a transitive dependency tree.
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+]
+
+[project.urls]
+Homepage = "https://app.flopsindex.com"
+Documentation = "https://app.flopsindex.com/llms.txt"
+Source = "https://github.com/zeroatflops/flopsindex"
+Methodology = "https://app.flopsindex.com/v1/methodology"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["flopsindex*"]

flopsindex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

flopsindex-0.1.0/tests/test_client.py

@@ -0,0 +1,362 @@
+"""Tests for the flopsindex Python SDK.
+
+Network-free: every HTTP call is monkeypatched. Tests pin the
+exception mapping + URL construction + auth gating.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from unittest import mock
+
+import pytest
+
+# Add SDK to path (test runs from repo root)
+SDK_DIR = Path(__file__).parent.parent
+sys.path.insert(0, str(SDK_DIR))
+
+from flopsindex import Client  # noqa: E402
+from flopsindex.exceptions import (  # noqa: E402
+    FlopsAuthError,
+    FlopsError,
+    FlopsNotFoundError,
+    FlopsRateLimitError,
+    FlopsServerError,
+)
+
+
+# ---------------------------------------------------------------------------
+# Auth gating
+# ---------------------------------------------------------------------------
+
+
+def test_public_methods_work_without_api_key(monkeypatch):
+    """price / timeseries / search / methodology must work without
+    an API key — that's the whole point of the public surface."""
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    # Stub _get so we don't hit the network
+    with mock.patch.object(c, "_get", return_value={"ok": True}) as m:
+        c.price("FLCI-H100")
+        m.assert_called_once()
+        # require_auth must be False on the call
+        assert m.call_args.kwargs.get("require_auth", True) is False
+
+
+def test_partner_methods_raise_without_api_key(monkeypatch):
+    """catalog / compute_margin / index_current need a key. Without
+    one, the SDK must raise FlopsAuthError BEFORE making the HTTP
+    call — saves a wasted round-trip and gives a clearer error."""
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    # _get does the auth check
+    with pytest.raises(FlopsAuthError):
+        c.catalog()
+
+    with pytest.raises(FlopsAuthError):
+        c.compute_margin(sku="h100_sxm5")
+
+    with pytest.raises(FlopsAuthError):
+        c.index_current("FLCI-H100")
+
+
+def test_api_key_from_env(monkeypatch):
+    monkeypatch.setenv("FLOPSINDEX_API_KEY", "flops_test_key")
+    c = Client()
+    assert c._api_key == "flops_test_key"
+
+
+def test_api_key_from_constructor_wins(monkeypatch):
+    monkeypatch.setenv("FLOPSINDEX_API_KEY", "from_env")
+    c = Client(api_key="from_arg")
+    assert c._api_key == "from_arg"
+
+
+# ---------------------------------------------------------------------------
+# URL construction
+# ---------------------------------------------------------------------------
+
+
+def test_price_url(monkeypatch):
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        captured["headers"] = dict(req.headers)
+        return _FakeResp(json.dumps({"ok": True}).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+    c.price("FLCI-H100")
+    assert captured["url"] == "https://app.flopsindex.com/v1/price/FLCI-H100"
+    # No API key header (we didn't set one)
+    assert "X-flops-api-key" not in captured["headers"]
+
+
+def test_timeseries_url_includes_range(monkeypatch):
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        return _FakeResp(json.dumps({"ok": True}).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+    c.timeseries("FLCI-H100", range="30d")
+    assert "/v1/ts/FLCI-H100" in captured["url"]
+    assert "range=30d" in captured["url"]
+
+
+def test_api_key_attached_when_present(monkeypatch):
+    monkeypatch.setenv("FLOPSINDEX_API_KEY", "flops_xxx")
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["headers"] = dict(req.headers)
+        return _FakeResp(json.dumps({"ok": True}).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+    c.catalog()
+    # urllib lowercases header names in the .headers dict
+    assert "X-flops-api-key" in captured["headers"] or \
+           "X-Flops-Api-Key" in captured["headers"]
+
+
+def test_methodology_versions_when_no_version(monkeypatch):
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        return _FakeResp(json.dumps({"ok": True}).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+    c.methodology("flci-h100")
+    assert "/v1/methodology/flci-h100/versions" in captured["url"]
+
+
+def test_methodology_specific_version_uses_json_suffix(monkeypatch):
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        return _FakeResp(json.dumps({"ok": True}).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+    c.methodology("flci-h100", "v0.9")
+    assert "/v1/methodology/flci-h100/v0.9.json" in captured["url"]
+
+
+# ---------------------------------------------------------------------------
+# Error mapping
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("status,exc_class", [
+    (401, FlopsAuthError),
+    (403, FlopsAuthError),
+    (404, FlopsNotFoundError),
+    (429, FlopsRateLimitError),
+    (500, FlopsServerError),
+    (502, FlopsServerError),
+    (503, FlopsServerError),
+])
+def test_http_error_maps_to_exception(monkeypatch, status, exc_class):
+    """Each HTTP status code maps to the right exception class."""
+    import urllib.error
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.HTTPError(
+            req.full_url, status, "err",
+            {"Retry-After": "120"},
+            _FakeReader(json.dumps({"detail": f"status {status}"}).encode("utf-8")),
+        )
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    with pytest.raises(exc_class) as exc_info:
+        c.price("FLCI-H100")
+    assert exc_info.value.status_code == status
+
+    if status == 429:
+        assert exc_info.value.retry_after_seconds == 120
+
+
+def test_network_error_raises_flops_error(monkeypatch):
+    import urllib.error
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.URLError("connection refused")
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    with pytest.raises(FlopsError) as exc_info:
+        c.price("FLCI-H100")
+    assert "connection refused" in str(exc_info.value)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _FakeReader:
+    """urllib.error.HTTPError needs a file-like object as `fp`."""
+    def __init__(self, body: bytes):
+        self._body = body
+
+    def read(self, *args):
+        return self._body
+
+
+class _FakeResp:
+    """Minimal context-manager fake for urllib.request.urlopen()."""
+    def __init__(self, body: bytes, status: int = 200):
+        self._body = body
+        self.status = status
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def read(self):
+        return self._body
+
+
+# ---------------------------------------------------------------------------
+# verify_handshake — defensive citation helper (Lane 5 R6 PB)
+# ---------------------------------------------------------------------------
+
+
+def test_verify_handshake_happy_path_returns_canonical_record(monkeypatch):
+    """2xx → return the JSON record as-is (the verify endpoint's success
+    shape). Caller checks .get('verified') / .get('actual_value')."""
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        return _FakeResp(json.dumps({
+            "verified": True, "index_id": "FLCI-H100",
+            "actual_value": 2.45, "delta_pct": 0.0,
+            "source_url": "https://app.flopsindex.com/i/FLCI-H100",
+        }).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    out = c.verify_handshake("FLCI-H100", value=2.45)
+    assert out["verified"] is True
+    assert out["actual_value"] == 2.45
+    assert "value=2.45" in captured["url"]
+    assert "index_id=FLCI-H100" in captured["url"]
+
+
+def test_verify_handshake_omits_value_when_none(monkeypatch):
+    """value=None → just ask 'what's the latest tick?' without committing."""
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+    captured = {}
+
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        return _FakeResp(json.dumps({"actual_value": 2.45}).encode("utf-8"))
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    c.verify_handshake("FLCI-H100")
+    assert "value=" not in captured["url"]
+    assert "index_id=FLCI-H100" in captured["url"]
+
+
+def test_verify_handshake_500_returns_upstream_http_error(monkeypatch):
+    """Per 2026-05-19 grounding /v1/verify was 500'ing. The handshake
+    MUST NOT raise — it returns the defensive envelope so the
+    price→verify→cite idiom never explodes downstream while Lane 4
+    fixes upstream."""
+    import urllib.error
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.HTTPError(
+            req.full_url, 500, "boom", {},
+            _FakeReader(json.dumps({"detail": "internal"}).encode("utf-8")),
+        )
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    out = c.verify_handshake("FLCI-H100", value=2.45)
+    assert out["ok"] is False
+    assert out["reason"] == "upstream_http_error"
+    assert out["upstream_status"] == 500
+
+
+@pytest.mark.parametrize("status,expected_reason", [
+    (401, "auth_required"),
+    (403, "auth_required"),
+    (404, "endpoint_pending"),
+    (400, "client_error"),
+    (502, "upstream_http_error"),
+    (503, "upstream_http_error"),
+])
+def test_verify_handshake_maps_status_to_reason(monkeypatch, status, expected_reason):
+    """Each HTTP status code maps to the right defensive reason — the
+    same shape MCP's _defensive_get emits, so an agent switching between
+    MCP and direct SDK gets identical error envelopes."""
+    import urllib.error
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.HTTPError(
+            req.full_url, status, "err", {},
+            _FakeReader(b'{"detail":"x"}'),
+        )
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    out = c.verify_handshake("FLCI-H100", value=2.45)
+    assert out["ok"] is False
+    assert out["reason"] == expected_reason
+    assert out["upstream_status"] == status
+
+
+def test_verify_handshake_network_error_returns_envelope(monkeypatch):
+    """URLError (DNS, connection refused, timeout) → defensive envelope,
+    not a raised exception. The handshake must survive a network blip."""
+    import urllib.error
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.URLError("connection refused")
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    out = c.verify_handshake("FLCI-H100", value=2.45)
+    assert out["ok"] is False
+    assert out["reason"] == "network_error"
+    assert "connection refused" in out["detail"]
+
+
+def test_verify_legacy_method_still_raises(monkeypatch):
+    """Backward-compat: existing .verify(index_id, value) still raises on
+    non-2xx. Anyone who wants the defensive envelope opts in via
+    .verify_handshake() — no silent shape change for legacy callers."""
+    import urllib.error
+    monkeypatch.delenv("FLOPSINDEX_API_KEY", raising=False)
+    c = Client()
+
+    def fake_urlopen(req, timeout=None):
+        raise urllib.error.HTTPError(
+            req.full_url, 500, "boom", {},
+            _FakeReader(b'{"detail":"internal"}'),
+        )
+    monkeypatch.setattr("flopsindex.client.urllib.request.urlopen", fake_urlopen)
+
+    with pytest.raises(FlopsServerError):
+        c.verify("FLCI-H100", value=2.45)