go-llm-specs

An LLM model metadata registry for Go applications. It compiles model IDs, providers, context windows, input/output modalities, tool-use support, JSON mode, aliases, tags, and English/Chinese descriptions into your binary.

English | 中文

Why This Exists

When a Go product supports multiple LLM providers, the same problems tend to show up quickly:

• Users type aliases such as gpt4t, claude sonnet, or qwen3-32b, and your app needs to resolve them to stable model IDs.
• Model pickers, admin consoles, billing rules, and routing policies need names, providers, context windows, and capability labels.
• Your code needs to know whether a model supports image input, function calling, structured output, embedding, reranking, TTS, or ASR.
• You do not want every service startup to depend on a remote model-list endpoint, and you do not want stale model constants scattered across business code.

go-llm-specs packages that metadata as a static, type-safe Go library. Runtime lookups are in-memory and require no network I/O, making it a good fit for API services, agent platforms, model gateways, dashboards, CLI tools, and internal operations systems.

What You Get

• Static registry: hundreds of models, synchronized and generated into models_gen.go.
• Unified model cards: ID, name, provider, family, series, summary, tags, context length, max output, and capabilities.
• Alias resolution: lookup by model ID or alias, with case-insensitive alias matching.
• Capability filters: query Vision, Tool Use, JSON mode, Embedding, Rerank, and other model capabilities with Go constants.
• Fuzzy search: search across model IDs, names, series, tags, summaries, and aliases for model pickers.
• Zero runtime network dependency: the registry is compiled into your binary.
• English and Chinese descriptions: useful for localized product interfaces.

Installation

go get github.com/kingfs/go-llm-specs

Quick Start

package main

import (
	"fmt"

	llmspecs "github.com/kingfs/go-llm-specs"
)

func main() {
	model, ok := llmspecs.Get("gpt4t")
	if !ok {
		return
	}

	fmt.Println(model.ID())                // openai/gpt-4-turbo
	fmt.Println(model.Provider())          // OpenAI
	fmt.Println(model.ContextLength())     // context window
	fmt.Println(model.Features().String()) // TextIn|TextOut|...
}

See examples/basic/main.go for a runnable example.

Common Patterns

Build a model picker

for _, model := range llmspecs.Search("claude sonnet", 10) {
	card := model.Card()
	fmt.Printf("%s: %s [%s]\n", card.Provider, card.Name, card.ID)
}

Find models with image input and tool use

models := llmspecs.Query().
	Has(llmspecs.ModalityImageIn).
	Has(llmspecs.CapFunctionCall).
	List()

List models from one provider

anthropicVisionModels := llmspecs.Query().
	Provider("Anthropic").
	Has(llmspecs.ModalityImageIn).
	List()

Validate configured model names

configured := []string{"gpt4t", "qwen3-32b", "not-exist"}
validModels := llmspecs.GetMany(configured)

Group models by tags

reasoningModels := llmspecs.Query().
	Tag(string(llmspecs.TagReasoning)).
	List()

for _, tag := range llmspecs.KnownTags() {
	fmt.Println(tag.Category, tag.Name, tag.Label)
}

API Overview

Core Model fields include:

• ID(), Name(), Provider(), Family(), Series()
• Description(), DescriptionCN(), Summary()
• ContextLength(), MaxOutput()
• Features(), HasCapability(), Tags(), HasTag(), Aliases()

Capability constants live in capability.go, and tag constants live in tag.go.

Where It Fits

• Model gateways: route by user selection, capability requirements, or provider policy.
• Agent platforms: expose only models that support tool use, structured output, or multimodal input.
• SaaS dashboards: render model lists, tags, context windows, and localized descriptions.
• CLIs and SDKs: validate config files and provide search/autocomplete results.
• Internal platforms: replace hard-coded model tables spread across service code.

Data Source And Updates

The registry records model specifications claimed by model publishers, not constraints of individual deployments. OpenRouter remains the broad primary discovery feed; publisher pages and subscribed official Hugging Face organizations provide enrichment and additional discovery. Human-maintained models/**/*.yaml is the highest-priority append-only fact catalog: automation fills empty fields only and never overwrites an existing value because of provenance or an upstream change.

Maintainer-facing files:

.
├── cmd/
│   ├── generator/      # sync upstream metadata and generate the static registry
│   ├── translator/     # incrementally fill Chinese descriptions
│   ├── enricher/       # collect rich metadata from structured sources
│   ├── catalogsync/    # audit publishers and discover official HF candidates
│   ├── codexgen/       # generate Codex models.json
│   └── suggestionctl/ # review evidence-backed AI suggestions
├── data/
│   └── models.json     # cached upstream payload
├── models/             # human-maintained YAML model definitions
├── providers/          # official publisher entry points and subscribed organizations
├── models_gen.go       # generated file, do not edit manually
└── Taskfile.yml        # go-task entry point

Contributing

PRs are welcome for missing models, better aliases, corrected capabilities, and improved metadata. The common maintenance flow is:

task generator
task test

Useful commands:

task fmt
task lint
task test
task build
task generator
task translator
task cardextract -- -model qwen/qwen3.6-27b -ai-model <local-model>
task suggestion -- list
task codexsuggest -- -model qwen/qwen3.6-27b
task codexsuggest -- -allowlist codex-models.yaml -report .cache/codex-selection.json
task codexsuggest -- -since 180d -serving-provider openrouter -report .cache/codex-recent.json
task enrich
task catalog-audit
task catalog-discover
task catalog-promote
task codexgen
task releasecheck
task sync

The daily workflow fetches OpenRouter once and fully paginates subscribed official Hugging Face organizations. New HF discoveries begin as candidate YAML excluded from the Go registry; they are promoted only after structured enrichment and safe high-confidence official model-card claims provide the required facts. Identical inputs generate identical code, so commits and releases represent real model-fact changes.

When changing model metadata, edit models/**/*.yaml and regenerate instead of hand-editing models_gen.go. See docs/DEVELOPMENT.md for maintainer details and AGENTS.md for AI collaboration notes.

Newly discovered or explicitly selected models can use schema v2 for source-attributed OpenRouter and Hugging Face metadata, official links, and identity mappings. See Model catalog architecture for the trust boundary and incremental workflow, and the Codex metadata pipeline for export details.

Codex third-party model catalog

Codex can load third-party-models.json. When the configured model matches a catalog slug, Codex no longer uses fallback metadata and the corresponding warning is eliminated. Because model_catalog_json replaces rather than extends the bundled catalog, the installer is recommended. It downloads the latest release, exports the installed Codex CLI's bundled models, merges and validates against the local schema, then backs up and updates ~/.codex/config.toml.

curl -fsSL https://raw.githubusercontent.com/kingfs/go-llm-specs/master/scripts/install-codex-catalog.sh | sh

From a repository checkout, you can instead run:

task codexinstall

The default output is ~/.codex/models.json; use --config and --output for other locations. The script only edits the top-level model_catalog_json and creates config.toml.bak before updating an existing configuration. If the local Codex schema is still incompatible with the release artifact, it stops before changing the configuration and reports Codex's parser error.

For a manual merge, always export the bundled catalog from the same machine and Codex version:

codex debug models --bundled > bundled-models.json
task codexgen -- -bundled-catalog bundled-models.json -output merged-models.json

For a reviewed deployment set, create an allowlist whose slugs exactly match the API model names:

models:
  - id: qwen/qwen3.6-27b
    slugs: [qwen3.6-27b]
  - id: deepseek/deepseek-v3.2
    slugs: [deepseek-v3.2]

task codexsuggest -- -allowlist codex-models.yaml -report .cache/codex-selection.json
task suggestion -- list
task suggestion -- -fields codex.enabled,codex.slugs,codex.shell_type,codex.apply_patch_tool_type,codex.supports_parallel_tool_calls,codex.input_modalities apply data/suggestions/<provider>/<model>.codex.json
task codexgen
task codexcheck

OpenRouter users can select candidates by their actual upstream creation time:

task codexsuggest -- -since 180d -serving-provider openrouter \
  -report .cache/codex-recent.json

“Recent” only selects candidates. Records that are not schema v2 chat/tool models with text input/output and a positive context window are listed as skipped. For vLLM, SGLang, or another provider, do not assume the OpenRouter ID is the serving slug; convert the candidates into an explicit allowlist first. After review and apply, task codexgen packages every eligible enabled model into one catalog. Exporting the entire registry is unsafe because it also contains embedding, reranking, audio, and records whose serving names or tool policies are not confirmed.

The Release catalog also uses data/codex/default-open-models.yaml to include these open-weight families by default: Qwen 3.5+, DeepSeek V3/R1+, GLM-5+, and Kimi K2.7+. In addition to static capability checks, a model must have a cataloged publisher, a Hugging Face identity owned by that publisher's configured organization, an exact model-card URL, and a pinned revision. Historical collection alone never makes a model eligible for Codex export.

License

Apache 2.0 License