Metadata-Version: 2.4
Name: flopsindex
Version: 0.7.2
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
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)
[![Live API](https://img.shields.io/website?label=app.flopsindex.com&url=https%3A%2F%2Fapp.flopsindex.com%2Fv2%2Fcatalog%2Fpublic)](https://app.flopsindex.com/v2/catalog/public)
[![Spec](https://img.shields.io/badge/JSON--LD-v0.1-blue)](https://schema.flopsindex.com/compute-index-spec/v0.1/)
[![Docs](https://img.shields.io/badge/docs-docs.flopsindex.com-blue)](https://docs.flopsindex.com/)

**See also** — full docs [docs.flopsindex.com](https://docs.flopsindex.com/sdk/python-read) · MCP server [`flopsindex-mcp`](https://pypi.org/project/flopsindex-mcp/) · spec [schema.flopsindex.com](https://schema.flopsindex.com/)

```bash
pip install flopsindex
```

The public read SDK for the FLOPS Index — the delayed GLOBAL GPU
compute and inference-token pricing reference rates. Single,
dependency-free client over the FLOPS public HTTP API.

## 30-second example

```python
from flopsindex import Client

c = Client()  # public delayed surface; no API key required

# Latest published GLOBAL price (delayed for anonymous callers)
print(c.price("FLOPS-H100-OD"))
# {'index_id': 'FLOPS-H100-OD', '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.search("h100 spot"))   # NL → canonical slugs
print(c.list_indices())        # public catalog of every index
```

## Public surface

This SDK exposes ONLY the FLOPS public/anonymous read surface: the
delayed GLOBAL price plus the citation + discovery helpers. Every
method works without an API key.

| Method                          | Returns                                  |
|---------------------------------|------------------------------------------|
| `price(index_id)`               | latest GLOBAL price (delayed for anon)   |
| `search(q)`                     | NL → slug results                        |
| `list_indices()` / `catalog()`  | public catalog (`/v2/catalog/public`)    |
| `verify(id, value)`             | does the value match our tick?           |
| `verify_handshake(id, value)`   | defensive citation check (never raises)  |

## API key (optional — upgrades delayed → real-time)

No key is required. If you have one, the SDK reads it from
`FLOPSINDEX_API_KEY`:

```bash
export FLOPSINDEX_API_KEY="flops_xxxxxxxxx"
```

Or pass it directly:

```python
c = Client(api_key="flops_xxxxxxxxx")
```

When a key is configured it is forwarded as the `X-FLOPS-Api-Key`
header on every request, which transparently upgrades the public
delayed GLOBAL price to real-time, full precision server-side. The
method surface is identical with or without a key.

A partner programmatic tier (real-time data, deeper history, and
more) is available separately — contact partners@flopsindex.com.

## Citation handshake

The Track-D citation idiom — price, then verify, then cite:

```python
tick = c.price("FLOPS-H100-OD")
check = c.verify_handshake("FLOPS-H100-OD", 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"])
```

`verify_handshake` never raises on HTTP errors — it returns a
structured `{ok: false, reason, upstream_status}` envelope so the
citation flow never explodes downstream. Use `verify` if you want the
raising variant instead.

## Naming conventions

- `FLOPS-{model}-{OD|SPOT|DEPIN}` — GPU rental by market type
- `FLOPS-{model}-INFERENCE_{INPUT|OUTPUT}` — inference token pricing

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("FLOPS-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`.
