metergraph-core 0.2.32__tar.gz → 0.2.34__tar.gz

{metergraph_core-0.2.32/src/metergraph_core.egg-info → metergraph_core-0.2.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.2.32
+Version: 0.2.34
 Summary: Reusable MeterGraph catalog and deterministic billing engine
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -12,15 +12,16 @@ Requires-Dist: pytest>=8; extra == "dev"
 
 # metergraph-core
 
-Reusable catalog and deterministic billing engine for MeterGraph.
+Reusable model registry, price catalog, and deterministic billing 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 also owns the pure decision that selects a qualified
-gateway-reported charge or a catalog estimate as the effective call cost.
+`metergraph-core` owns two separate public datasets. `models.yaml` records
+canonical model identity, customer-facing names, executable provider routes,
+and the ordered candidate fields MeterGraph products offer. `prices.yaml`
+records effective-dated rates and billing rules. Core parses and validates both
+datasets, resolves provider aliases and routes, calculates deterministic costs,
+and selects a qualified gateway-reported charge or catalog estimate as the
+effective call cost.
 
 It does not own HTTP routes, database access, migrations, authentication,
 tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
@@ -84,6 +85,31 @@ exists. It never substitutes a direct-provider price for a gateway price.
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+## Model registry
+
+```python
+from metergraph_core import load_model_registry
+
+models = load_model_registry()
+for candidate in models.candidates("gateway"):
+    print(candidate.id, candidate.display_name, candidate.pricing_channel)
+```
+
+`load_model_registry()` reads the packaged `models.yaml`. Execution profiles
+describe every route the pipeline can run, while offer groups describe the
+smaller ordered fields a product exposes for configured credentials. Candidate
+IDs may intentionally repeat across execution profiles when gateway and
+Bedrock use different physical routes; each route therefore also has a unique
+internal `key`.
+
+Use `validate_model_registry(models, load_catalog())` to verify that every
+route's provider-facing model ID is declared on its exact pricing channel,
+resolves to its canonical model, and has an active price on the registry
+version date. The parser also rejects unknown route providers, provider/channel
+mismatches on any route, mismatched offer-group credentials/providers, and duplicate physical routes. Pricing
+remains exclusively in `prices.yaml`; being priceable does not automatically
+make a model an approved analysis candidate.
+
 ## Billing evidence
 
 Servers can pass content-blind, already-extracted gateway fields through the
@@ -123,21 +149,30 @@ from metergraph_core import (
     CostResult,
     GatewayBillingEvidence,
     LoadedCatalog,
+    ModelRegistry,
+    ModelRoute,
     Price,
     ResolvedPrice,
     load_catalog,
+    load_model_registry,
     normalize_gateway_evidence,
     parse_catalog,
     resolve_billing,
+    validate_model_registry,
 )
 ```
 
 ## 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.
+The two manually maintained public datasets live under
+`src/metergraph_core/data/`. Update `models.yaml` when model identity, display,
+routing, or managed candidate policy changes. Update `prices.yaml` when rates
+or billing rules change. Price corrections close or add effective windows;
+they never rewrite historical prices in place. Either data change increments
+its own declared version and produces a patch release of `metergraph-core`.
+Software and data versions remain separate because they have different
+lifecycles.
+
+The model registry version is an ISO date. When more than one registry ships on
+the same date, append a positive revision such as `2026-09-25.2` so consumers
+can distinguish the policies while pricing validation still uses that date.

{metergraph_core-0.2.32 → metergraph_core-0.2.34}/README.md

@@ -1,14 +1,15 @@
 # metergraph-core
 
-Reusable catalog and deterministic billing engine for MeterGraph.
+Reusable model registry, price catalog, and deterministic billing 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 also owns the pure decision that selects a qualified
-gateway-reported charge or a catalog estimate as the effective call cost.
+`metergraph-core` owns two separate public datasets. `models.yaml` records
+canonical model identity, customer-facing names, executable provider routes,
+and the ordered candidate fields MeterGraph products offer. `prices.yaml`
+records effective-dated rates and billing rules. Core parses and validates both
+datasets, resolves provider aliases and routes, calculates deterministic costs,
+and selects a qualified gateway-reported charge or catalog estimate as the
+effective call cost.
 
 It does not own HTTP routes, database access, migrations, authentication,
 tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
@@ -72,6 +73,31 @@ exists. It never substitutes a direct-provider price for a gateway price.
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+## Model registry
+
+```python
+from metergraph_core import load_model_registry
+
+models = load_model_registry()
+for candidate in models.candidates("gateway"):
+    print(candidate.id, candidate.display_name, candidate.pricing_channel)
+```
+
+`load_model_registry()` reads the packaged `models.yaml`. Execution profiles
+describe every route the pipeline can run, while offer groups describe the
+smaller ordered fields a product exposes for configured credentials. Candidate
+IDs may intentionally repeat across execution profiles when gateway and
+Bedrock use different physical routes; each route therefore also has a unique
+internal `key`.
+
+Use `validate_model_registry(models, load_catalog())` to verify that every
+route's provider-facing model ID is declared on its exact pricing channel,
+resolves to its canonical model, and has an active price on the registry
+version date. The parser also rejects unknown route providers, provider/channel
+mismatches on any route, mismatched offer-group credentials/providers, and duplicate physical routes. Pricing
+remains exclusively in `prices.yaml`; being priceable does not automatically
+make a model an approved analysis candidate.
+
 ## Billing evidence
 
 Servers can pass content-blind, already-extracted gateway fields through the
@@ -111,21 +137,30 @@ from metergraph_core import (
     CostResult,
     GatewayBillingEvidence,
     LoadedCatalog,
+    ModelRegistry,
+    ModelRoute,
     Price,
     ResolvedPrice,
     load_catalog,
+    load_model_registry,
     normalize_gateway_evidence,
     parse_catalog,
     resolve_billing,
+    validate_model_registry,
 )
 ```
 
 ## 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.
+The two manually maintained public datasets live under
+`src/metergraph_core/data/`. Update `models.yaml` when model identity, display,
+routing, or managed candidate policy changes. Update `prices.yaml` when rates
+or billing rules change. Price corrections close or add effective windows;
+they never rewrite historical prices in place. Either data change increments
+its own declared version and produces a patch release of `metergraph-core`.
+Software and data versions remain separate because they have different
+lifecycles.
+
+The model registry version is an ISO date. When more than one registry ships on
+the same date, append a positive revision such as `2026-09-25.2` so consumers
+can distinguish the policies while pricing validation still uses that date.

{metergraph_core-0.2.32 → metergraph_core-0.2.34}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.2.32"
+version = "0.2.34"
 description = "Reusable MeterGraph catalog and deterministic billing engine"
 readme = "README.md"
 license = "Apache-2.0"
@@ -20,4 +20,4 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-metergraph_core = ["data/prices.yaml"]
+metergraph_core = ["data/models.yaml", "data/prices.yaml"]

{metergraph_core-0.2.32 → metergraph_core-0.2.34}/src/metergraph_core/__init__.py

@@ -23,6 +23,16 @@ from .loader import (
     parse_catalog,
     parse_retrieval,
 )
+from .models import (
+    ModelDefinition,
+    ModelRegistry,
+    ModelRegistryError,
+    ModelRoute,
+    OfferGroup,
+    load_model_registry,
+    parse_model_registry,
+    validate_model_registry,
+)
 from .retrieval import (
     RetrievalCatalog,
     RetrievalCostResult,
@@ -36,6 +46,11 @@ __all__ = [
     "CatalogSnapshot",
     "CostResult",
     "LoadedCatalog",
+    "ModelDefinition",
+    "ModelRegistry",
+    "ModelRegistryError",
+    "ModelRoute",
+    "OfferGroup",
     "GatewayBillingEvidence",
     "Price",
     "ResolvedPrice",
@@ -46,8 +61,11 @@ __all__ = [
     "direct_channel_for_provider",
     "normalize_provider",
     "load_catalog",
+    "load_model_registry",
     "normalize_gateway_evidence",
     "parse_catalog",
+    "parse_model_registry",
     "parse_retrieval",
     "resolve_billing",
+    "validate_model_registry",
 ]