Metadata-Version: 2.4
Name: flopsindex
Version: 0.6.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)
[![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) · partner write SDK [`flopsindex-partner`](https://pypi.org/project/flopsindex-partner/) · MCP server [`flopsindex-mcp`](https://pypi.org/project/flopsindex-mcp/) (v0.6.0, mcp-publisher ready) · spec [schema.flopsindex.com](https://schema.flopsindex.com/) · adopters [schema.flopsindex.com/adopters](https://schema.flopsindex.com/adopters)

```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`.
