modelsdev

README

modelsdev Package

The modelsdev package provides model pricing lookup backed by the public models.dev catalog.

Overview

This package downloads and parses https://models.dev/catalog.json, normalizes provider/model identifiers, and exposes per-token pricing for callers that need cost-aware behavior.

The catalog is loaded once per process via a singleton cache (syncutil.OnceLoader) to avoid repeated network fetches.

Public API

Functions

Function	Signature	Description
FindPricing	func(ctx context.Context, provider, model string) (map[string]float64, bool)	Returns normalized per-token pricing for a provider/model pair. Falls back to cross-provider matching when provider lookup fails. Returns (nil, false) when no pricing is available
NormalizeProvider	func(provider string) string	Normalizes provider aliases such as github, copilot, and github_models to github-copilot, and lower-cases other provider identifiers
NormalizeComparableModelID	func(value string) string	Lower-cases a model identifier, trims surrounding whitespace, and replaces . and _ with - so equivalent model IDs compare consistently

Usage Examples

import "github.com/github/gh-aw/pkg/modelsdev"

pricing, ok := modelsdev.FindPricing(ctx, "github", "gpt-4.1")
if !ok {
    // pricing unavailable
    return
}

inputUSD := pricing["input"]  // per token
outputUSD := pricing["output"] // per token
_ = inputUSD
_ = outputUSD

Dependencies

Internal:

• github.com/github/gh-aw/pkg/logger — debug logging
• github.com/github/gh-aw/pkg/syncutil — one-time catalog load/cache primitive

Design Notes

• Provider aliases such as github, copilot, and github_models are normalized to github-copilot.
• Comparable model matching normalizes separators (. and _ to -) to improve lookup robustness.
• Numeric catalog costs are interpreted as per-million-token values and converted to per-token units.
• String catalog costs are treated as already normalized per-token values.
• Network or parsing failures degrade gracefully to an empty cache so callers can continue without pricing data.

Source Synchronization

Reviewed against recent source updates on 2026-07-17; no additional public-contract deltas were identified beyond the sections above.

---

This specification is automatically maintained by the spec-extractor workflow.

Documentation

Index

• func NormalizeComparableModelID(value string) string
• func NormalizeProvider(provider string) string

Functions

func NormalizeComparableModelID

func NormalizeComparableModelID(value string) string

NormalizeComparableModelID lower-cases the value and replaces "." and "_" with "-" so that model IDs differing only in those separators compare equal.

func NormalizeProvider

func NormalizeProvider(provider string) string

NormalizeProvider maps provider aliases (e.g. "github", "copilot", "github_models") to their canonical form ("github-copilot") and lower-cases all other values.