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

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.4
File	Size	Uploaded
metergraph_core-0.1.4.tar.gz	13.9 kB	Aug 26, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for metergraph-core 0.1.4
File	Interpreter	ABI	Platform	Reset
metergraph_core-0.1.4-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.4.tar.gz

Download URL	metergraph_core-0.1.4.tar.gz
Size	13.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`b6a9e568b8e6f15a3b780a4aae490c2b10feaa17844e5cc92d91ea68f104c612`
BLAKE2b-256 checksum How to use checksums	`1632a6802e6f1bd184ff68090d55558478d3921d583d500c8a27a14271caa401`
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/60c52adfdcf407f201a3b256bc00795e088f982c

Workflow

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

Artifact

Subject: metergraph_core-0.1.4.tar.gz
SHA-256 checksum: b6a9e568b8e6f15a3b780a4aae490c2b10feaa17844e5cc92d91ea68f104c612 Verifying attestations

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

Download URL	metergraph_core-0.1.4-py3-none-any.whl
Size	13.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aa51b772826da8e8b710fd8f2e020570c6eec408d9b1b9379d8fd39f2a3bda7f`
BLAKE2b-256 checksum How to use checksums	`0f4f2e010698877c09ae3a1efd8c150c8a4d13da1a30bc6e395d865f17774581`
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/60c52adfdcf407f201a3b256bc00795e088f982c

Workflow

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

Artifact

Subject: metergraph_core-0.1.4-py3-none-any.whl
SHA-256 checksum: aa51b772826da8e8b710fd8f2e020570c6eec408d9b1b9379d8fd39f2a3bda7f Verifying attestations