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

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.2
File	Size	Uploaded
metergraph_core-0.1.2.tar.gz	11.9 kB	Aug 25, 2026	Details

Built distribution (wheel)

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

Total release size: 22.9 kB

Release files / metergraph_core-0.1.2.tar.gz

Download URL	metergraph_core-0.1.2.tar.gz
Size	11.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`8a2095cc3a73b44c9a4bbab2b04004bb7f801a39ec6cc76523cfcffbb813d5fe`
BLAKE2b-256 checksum How to use checksums	`482e4d3f2c48629b7c4df35ae1f6fa449bbb3bc91db9f86c5ad6c79c77a08785`
Upload date	Aug 25, 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/b050dff5578fc0c487aea7d300bed0c5a899826a

Workflow

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

Artifact

Subject: metergraph_core-0.1.2.tar.gz
SHA-256 checksum: 8a2095cc3a73b44c9a4bbab2b04004bb7f801a39ec6cc76523cfcffbb813d5fe Verifying attestations

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

Download URL	metergraph_core-0.1.2-py3-none-any.whl
Size	11.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`09c22037468bdcf3f8ac3b7a0dab5a04efc7f695e6a0f3514c3ee13788139d98`
BLAKE2b-256 checksum How to use checksums	`d706d0dbbc7783142bc882f2d30afb8f7630b1bee15758d1c28adafb81edea9a`
Upload date	Aug 25, 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/b050dff5578fc0c487aea7d300bed0c5a899826a

Workflow

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

Artifact

Subject: metergraph_core-0.1.2-py3-none-any.whl
SHA-256 checksum: 09c22037468bdcf3f8ac3b7a0dab5a04efc7f695e6a0f3514c3ee13788139d98 Verifying attestations