metergraph-core

Reusable catalog and deterministic token-cost pricing engine for MeterGraph.

metergraph-core owns the public effective-dated model catalog and the pricing logic shared across MeterGraph systems: catalog parsing and validation, provider and model alias resolution, channel and region selection, input/output/cache/ batch/long-context pricing rules, deterministic cost calculation with reason codes, stable logical price identifiers, and catalog version and content-hash reporting.

It does not own HTTP routes, database access, migrations, authentication, tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads server environment variables.

Install

python -m pip install metergraph-core

Usage

from datetime import datetime, timezone

from metergraph_core import load_catalog

catalog = load_catalog(region="global")
result = catalog.snapshot.cost(
    provider="openai",
    model="gpt-5.4-mini",
    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
    input_tokens=1000,
    output_tokens=200,
)
print(result.canonical_model, result.price_id, result.cost_usd, result.status)

load_catalog() loads the catalog bundled in the installed package. Pass an explicit path for tests or a self-hosted catalog replacement. The returned LoadedCatalog exposes the declared catalog version, the SHA-256 content_hash of the loaded bytes, the parsed document, and the immutable snapshot used for pricing.

Planning and evaluation systems that know the deployment channel before making a call can resolve the exact effective price without emulating a provider response:

price = catalog.snapshot.resolve_price(
    model="openai/gpt-5.6-luna",
    channel="vercel-ai-gateway",
    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
)
if price is not None:
    print(
        price.canonical_model,
        price.price.id,
        price.price.input_per_mtok,
        price.price.source_url,
    )

Resolution accepts canonical IDs and channel-scoped aliases, normalizes case and surrounding whitespace, applies the configured region fallback and effective-date windows, and returns None when no exact model/channel price exists. It never substitutes a direct-provider price for a gateway price.

LoadedCatalog.currency is currently always USD, and LoadedCatalog.pricing_verified_at records when the bundled catalog was last checked against its linked provider sources.

Public API

from metergraph_core import (
    Alias,
    CatalogError,
    CatalogSnapshot,
    CostResult,
    LoadedCatalog,
    Price,
    ResolvedPrice,
    load_catalog,
    parse_catalog,
)

Catalog maintenance

The only manually maintained public catalog lives at src/metergraph_core/data/prices.yaml. Every record requires its provider source URL and effective date. Corrections close or add effective windows; they never rewrite historical prices in place. A catalog change updates the declared catalog version and produces a patch release of metergraph-core. Software version and catalog version are separate values because code and price data have different lifecycles.

Release files for metergraph-core 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for metergraph-core 0.1.3
File	Size	Uploaded
metergraph_core-0.1.3.tar.gz	13.9 kB	Aug 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for metergraph-core 0.1.3
File	Interpreter	ABI	Platform	Reset
metergraph_core-0.1.3-py3-none-any.whl 13.0 kB Aug 26, 2026	Python 3	none	any	Details

Total release size: 26.9 kB

Release files / metergraph_core-0.1.3.tar.gz

Download URL	metergraph_core-0.1.3.tar.gz
Size	13.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`22979de13c5700b04164afe2ff0a9ca1f7848c713ded6c5ca04fa0fd0883ee29`
BLAKE2b-256 checksum How to use checksums	`7563643ff341f4fe1c42aba2033549dc8063aeb494071bd7d072fda519fb7f2a`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/PioneerSquareLabs/metergraph
Publishing commit: github.com/PioneerSquareLabs/metergraph/tree/ab988bca0247b4f3deddcd3c602c491f27a770a7

Workflow

Publishing configuration: github.com/PioneerSquareLabs/metergraph/blob/ab988bca0247b4f3deddcd3c602c491f27a770a7/.github/workflows/core-release.yml
Publishing logs: github.com/PioneerSquareLabs/metergraph/actions/runs/32914140866/attempts/1

Artifact

Subject: metergraph_core-0.1.3.tar.gz
SHA-256 checksum: 22979de13c5700b04164afe2ff0a9ca1f7848c713ded6c5ca04fa0fd0883ee29 Verifying attestations

Release files / metergraph_core-0.1.3-py3-none-any.whl

Download URL	metergraph_core-0.1.3-py3-none-any.whl
Size	13.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b80775db1e531e2949590cc9583a665a48bb97ec633735cb5f0926ddba9295c0`
BLAKE2b-256 checksum How to use checksums	`f04bbe77d7587702698b22a02503ff49b44a80b6b935fefe319e2aa1f9ee36e9`
Upload date	Aug 26, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/PioneerSquareLabs/metergraph
Publishing commit: github.com/PioneerSquareLabs/metergraph/tree/ab988bca0247b4f3deddcd3c602c491f27a770a7

Workflow

Publishing configuration: github.com/PioneerSquareLabs/metergraph/blob/ab988bca0247b4f3deddcd3c602c491f27a770a7/.github/workflows/core-release.yml
Publishing logs: github.com/PioneerSquareLabs/metergraph/actions/runs/32914140866/attempts/1

Artifact

Subject: metergraph_core-0.1.3-py3-none-any.whl
SHA-256 checksum: b80775db1e531e2949590cc9583a665a48bb97ec633735cb5f0926ddba9295c0 Verifying attestations