catalogs

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 12, 2026 License: AGPL-3.0 Imports: 31 Imported by: 0

README

catalogs

Package catalogs provides a unified catalog abstraction with pluggable storage backends for managing AI model information.

catalogs

import "github.com/agentstation/starmap/pkg/catalogs"

Package catalogs provides the core catalog system for managing AI model metadata. It offers multiple implementations (embedded, file-based, memory) and supports CRUD operations, merging strategies, and persistence.

The catalog system is designed to be thread-safe and extensible, with support for providers, models, authors, and endpoints. Each catalog implementation can be configured with different storage backends while maintaining a consistent interface.

Example usage:

// Advanced producers construct a draft, then publish an immutable catalog.
builder, err := New(WithEmbedded())
if err != nil {
    log.Fatal(err)
}
catalog, err := builder.Build()
if err != nil {
    log.Fatal(err)
}

// Access models
models := catalog.Models()
for _, model := range models.List() {
    fmt.Printf("Model: %s\n", model.ID)
}

// Create a file-based draft (development use)
builder, err = New(WithFiles("./catalog"))
if err != nil {
    log.Fatal(err)
}
Example

Example demonstrates advanced catalog construction and publication.

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create a memory-based draft.
	builder := catalogs.NewEmpty()

	// Add a provider with a model
	provider := catalogs.Provider{
		ID:   "openai",
		Name: "OpenAI",
		Models: map[string]*catalogs.Model{
			"gpt-4": {
				ID:          "gpt-4",
				Name:        "GPT-4",
				Description: "Advanced language model",
			},
		},
	}
	if err := builder.SetProvider(provider); err != nil {
		log.Fatal(err)
	}
	catalog, err := builder.Build()
	if err != nil {
		log.Fatal(err)
	}

	// List all models
	models := catalog.Models().List()
	fmt.Printf("Found %d models\n", len(models))
}
Output
Found 1 models

Example (Catalog Copy)

Example_catalogCopy demonstrates creating independent copies.

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create original catalog
	original := catalogs.NewEmpty()
	provider := catalogs.Provider{
		ID:   "test",
		Name: "Test Provider",
		Models: map[string]*catalogs.Model{
			"model-1": {
				ID:   "model-1",
				Name: "Original Model",
			},
		},
	}
	_ = original.SetProvider(provider)

	// Create a copy
	copy, err := original.Copy()
	if err != nil {
		log.Fatal(err)
	}

	// Modify the copy by updating the provider
	copiedProvider, _ := copy.Provider("test")
	if copiedProvider.Models == nil {
		copiedProvider.Models = make(map[string]*catalogs.Model)
	}
	copiedProvider.Models["model-2"] = &catalogs.Model{
		ID:   "model-2",
		Name: "Copy Model",
	}
	_ = copy.SetProvider(copiedProvider)

	// Original is unchanged
	fmt.Printf("Original has %d models\n", len(original.Models().List()))
	fmt.Printf("Copy has %d models\n", len(copy.Models().List()))
}
Output
Original has 1 models
Copy has 2 models

Example (Concurrent Access)

Example_concurrentAccess demonstrates thread-safe concurrent usage.

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/agentstation/starmap/pkg/catalogs"
	"github.com/agentstation/starmap/pkg/constants"
)

func main() {
	catalog := catalogs.NewEmpty()
	ctx, cancel := context.WithTimeout(context.Background(), constants.DefaultHTTPTimeout)
	defer cancel()

	// Safe for concurrent reads and writes
	done := make(chan bool, 2)

	// Writer goroutine
	go func() {
		provider := catalogs.Provider{
			ID:     "test-provider",
			Name:   "Test Provider",
			Models: make(map[string]*catalogs.Model),
		}
		for i := range 100 {
			provider.Models[fmt.Sprintf("model-%d", i)] = &catalogs.Model{
				ID:   fmt.Sprintf("model-%d", i),
				Name: fmt.Sprintf("Model %d", i),
			}
		}
		_ = catalog.SetProvider(provider)
		done <- true
	}()

	// Reader goroutine
	go func() {
		for {
			select {
			case <-ctx.Done():
				done <- true
				return
			default:
				_ = catalog.Models().List()
				time.Sleep(10 * time.Millisecond)
			}
		}
	}()

	// Wait for both
	<-done
	<-done

	fmt.Printf("Created %d models concurrently\n", len(catalog.Models().List()))
}

Example (Embedded Catalog)

Example_embeddedCatalog demonstrates using the embedded catalog.

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Load embedded data into a builder, then publish it.
	builder, err := catalogs.New(catalogs.WithEmbedded())
	if err != nil {
		log.Fatal(err)
	}
	catalog, err := builder.Build()
	if err != nil {
		log.Fatal(err)
	}

	// Access pre-loaded models
	models := catalog.Models().List()
	fmt.Printf("Embedded catalog has %d+ models\n", len(models))

	// Find a specific model
	model, err := catalog.FindModel("gpt-4o")
	if err == nil {
		fmt.Printf("Found model: %s\n", model.Name)
	}
}

Example (File Based Catalog)

Example_fileBasedCatalog demonstrates file-based persistence.

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create a file-based builder.
	catalogPath := filepath.Join(".", "my-catalog")
	builder, err := catalogs.New(
		catalogs.WithPath(catalogPath),
		catalogs.WithWritePath(catalogPath),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Add and save data
	provider := catalogs.Provider{
		ID:   "custom",
		Name: "Custom Provider",
		Models: map[string]*catalogs.Model{
			"custom-model": {
				ID:   "custom-model",
				Name: "My Custom Model",
			},
		},
	}
	if err := builder.SetProvider(provider); err != nil {
		log.Fatal(err)
	}

	// Save to disk (would normally use SaveTo method or similar)
	// Since Write is not part of the interface, this example shows the concept
	// In actual usage, you would use catalog.SaveTo(catalogPath)

	fmt.Println("Catalog saved to disk")
}

Example (Merge Catalogs)

Example_mergeCatalogs demonstrates merging two catalogs.

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create base catalog
	base := catalogs.NewEmpty()
	baseProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test Provider",
		Models: map[string]*catalogs.Model{
			"model-1": {
				ID:          "model-1",
				Name:        "Model One",
				Description: "Original description",
			},
		},
	}
	_ = base.SetProvider(baseProvider)

	// Create updates catalog
	updates := catalogs.NewEmpty()
	updateProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test Provider",
		Models: map[string]*catalogs.Model{
			"model-1": {
				ID:          "model-1",
				Name:        "Model One Enhanced",
				Description: "Updated description",
				Pricing: &catalogs.ModelPricing{
					Tokens: &catalogs.ModelTokenPricing{
						Input: &catalogs.ModelTokenCost{
							Per1M: 2.0, // $2 per 1M tokens
						},
						Output: &catalogs.ModelTokenCost{
							Per1M: 4.0, // $4 per 1M tokens
						},
					},
					Currency: "USD",
				},
			},
		},
	}
	_ = updates.SetProvider(updateProvider)

	// Merge with EnrichEmpty strategy (default)
	if err := base.MergeWith(updates); err != nil {
		log.Fatal(err)
	}

	model, _ := base.FindModel("model-1")
	fmt.Printf("Model name: %s\n", model.Name)
}
Output
Model name: Model One Enhanced

Example (Merge Strategies)

Example_mergeStrategies demonstrates different merge strategies.

package main

import (
	"fmt"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	base := catalogs.NewEmpty()
	baseProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test",
		Models: map[string]*catalogs.Model{
			"m1": {ID: "m1", Name: "Original"},
		},
	}
	_ = base.SetProvider(baseProvider)

	updates := catalogs.NewEmpty()
	updateProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test",
		Models: map[string]*catalogs.Model{
			"m1": {ID: "m1", Name: "Updated"},
			"m2": {ID: "m2", Name: "New"},
		},
	}
	_ = updates.SetProvider(updateProvider)

	// Example 1: Append only (keeps existing, adds new)
	cat1, _ := base.Copy()
	cat1.MergeWith(updates, catalogs.WithStrategy(catalogs.MergeAppendOnly))

	m1, _ := cat1.FindModel("m1")
	fmt.Printf("AppendOnly - m1: %s\n", m1.Name) // Original

	// Example 2: Replace all
	cat2, _ := base.Copy()
	cat2.MergeWith(updates, catalogs.WithStrategy(catalogs.MergeReplaceAll))

	m1, _ = cat2.FindModel("m1")
	fmt.Printf("ReplaceAll - m1: %s\n", m1.Name) // Updated

	// Example 3: Enrich empty (smart merge)
	cat3, _ := base.Copy()
	cat3.MergeWith(updates, catalogs.WithStrategy(catalogs.MergeEnrichEmpty))

	m1, _ = cat3.FindModel("m1")
	fmt.Printf("EnrichEmpty - m1: %s\n", m1.Name) // Updated
}

Example (Model Filtering)

Example_modelFiltering demonstrates filtering models.

package main

import (
	"fmt"
	"slices"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	catalog, _ := catalogs.New(catalogs.WithEmbedded())

	// Get all models for a specific provider
	// In practice, models would be linked to providers via naming convention or metadata
	var gptModels []catalogs.Model
	for _, model := range catalog.Models().List() {
		if len(model.ID) > 3 && model.ID[:3] == "gpt" {
			gptModels = append(gptModels, model)
		}
	}
	fmt.Printf("Found %d GPT models\n", len(gptModels))

	// Filter by features
	var visionModels []catalogs.Model
	for _, model := range catalog.Models().List() {
		if model.Features != nil {
			if slices.Contains(model.Features.Modalities.Input, "image") {
				visionModels = append(visionModels, model)
			}
		}
	}
	fmt.Printf("Found %d models with vision\n", len(visionModels))
}

Example (Provider Capabilities)

Example_providerCapabilities demonstrates working with provider features.

package main

import (
	"fmt"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	catalog := catalogs.NewEmpty()

	// Add provider with capabilities
	provider := catalogs.Provider{
		ID:   "openai",
		Name: "OpenAI",
		Catalog: &catalogs.ProviderCatalog{
			Endpoint: catalogs.ProviderEndpoint{
				URL:          "https://api.openai.com/v1/models",
				AuthRequired: true,
			},
		},
	}
	_ = catalog.SetProvider(provider)

	// Check capabilities
	p, _ := catalog.Provider("openai")
	if p.HasAPIKey() {
		fmt.Println("Provider has API key configured")
	}
	if p.Catalog != nil && p.Catalog.Endpoint.AuthRequired {
		fmt.Println("Provider requires API key")
	}
}

Index

Constants

const (
    // CurrentGenerationManifestVersion is the manifest envelope version emitted
    // by this release. It is intentionally independent of the Starmap binary
    // version and the catalog payload schema version.
    CurrentGenerationManifestVersion uint64 = 1

    // CurrentCatalogSchemaVersion identifies the canonical catalog payload
    // schema emitted by this release.
    CurrentCatalogSchemaVersion uint64 = 1

    // CatalogPayloadMediaType identifies the canonical JSON catalog payload.
    CatalogPayloadMediaType = "application/vnd.agentstation.starmap.catalog+json"
)

CurrentBootstrapManifestVersion is the embedded-bootstrap metadata format.

const CurrentBootstrapManifestVersion uint64 = 1


const (
    // LegacyCatalogSchemaVersion identifies the pre-definition/offering bare-ID
    // catalog API exposed by LegacyCatalogV0.
    LegacyCatalogSchemaVersion uint64 = 0
)

func AssertCatalogHasModel

func AssertCatalogHasModel(t testing.TB, catalog Reader, modelID string)

AssertCatalogHasModel asserts that a catalog contains a model with the given ID.

func AssertCatalogHasProvider

func AssertCatalogHasProvider(t testing.TB, catalog Reader, providerID ProviderID)

AssertCatalogHasProvider asserts that a catalog contains a provider with the given ID.

func AssertModelsEqual

func AssertModelsEqual(t testing.TB, expected, actual *Model)

AssertModelsEqual asserts that two models are equal, providing detailed diff on failure.

func AssertProvidersEqual

func AssertProvidersEqual(t testing.TB, expected, actual *Provider)

AssertProvidersEqual asserts that two providers are equal.

func DeepCopyAuthorModels

func DeepCopyAuthorModels(models map[string]*Model) map[string]*Model

DeepCopyAuthorModels creates a deep copy of an author's Models map. Returns nil if the input map is nil.

func DeepCopyProviderModels

func DeepCopyProviderModels(models map[string]*Model) map[string]*Model

DeepCopyProviderModels creates a deep copy of a provider's Models map. Returns nil if the input map is nil.

func EncodeCatalogPayload

func EncodeCatalogPayload(reader Reader) ([]byte, error)

EncodeCatalogPayload deterministically encodes a readable catalog as schema v1.

func NormalizeExtensionFields

func NormalizeExtensionFields(fields map[string]any) map[string]any

NormalizeExtensionFields returns a copy with maps, slices, and numbers normalized to stable dynamic types after JSON/YAML round trips.

func PrintProviderValidationReport

func PrintProviderValidationReport(report *ProviderValidationReport)

PrintProviderValidationReport prints a formatted report of provider validation status This is a convenience function that calls the Print method on the report.

func ShallowCopyAuthorModels

func ShallowCopyAuthorModels(models map[string]*Model) map[string]*Model

ShallowCopyAuthorModels creates a shallow copy of an author's Models map. The map is copied but Model pointers are shared. Returns nil if the input map is nil.

func ShallowCopyProviderModels

func ShallowCopyProviderModels(models map[string]*Model) map[string]*Model

ShallowCopyProviderModels creates a shallow copy of a provider's Models map. The map is copied but Model pointers are shared. Returns nil if the input map is nil.

func TestAPIResponse

func TestAPIResponse(models ...string) map[string]any

TestAPIResponse creates a test API response for provider testing.

func TestTimeNow

func TestTimeNow() time.Time

TestTimeNow returns a consistent time for testing.

type ArchitectureType

ArchitectureType represents the type of model architecture.

type ArchitectureType string

Architecture types.

const (
    ArchitectureTypeTransformer ArchitectureType = "transformer" // Transformer-based models (GPT, BERT, LLaMA, etc.)
    ArchitectureTypeMoE         ArchitectureType = "moe"         // Mixture of Experts (Mixtral, GLaM, Switch Transformer)
    ArchitectureTypeCNN         ArchitectureType = "cnn"         // Convolutional Neural Networks
    ArchitectureTypeRNN         ArchitectureType = "rnn"         // Recurrent Neural Networks
    ArchitectureTypeLSTM        ArchitectureType = "lstm"        // Long Short-Term Memory networks
    ArchitectureTypeGRU         ArchitectureType = "gru"         // Gated Recurrent Unit networks
    ArchitectureTypeVAE         ArchitectureType = "vae"         // Variational Autoencoders
    ArchitectureTypeGAN         ArchitectureType = "gan"         // Generative Adversarial Networks
    ArchitectureTypeDiffusion   ArchitectureType = "diffusion"   // Diffusion models (Stable Diffusion, DALL-E, etc.)
)

func (ArchitectureType) String
func (at ArchitectureType) String() string

String returns the string representation of an ArchitectureType.

type Author

Author represents a known model author or organization.

type Author struct {
    ID          AuthorID   `json:"id" yaml:"id"`                                       // Unique identifier for the author
    Aliases     []AuthorID `json:"aliases,omitempty" yaml:"aliases,omitempty"`         // Alternative IDs this author is known by (e.g., in provider catalogs)
    Name        string     `json:"name" yaml:"name"`                                   // Display name of the author
    Description *string    `json:"description,omitempty" yaml:"description,omitempty"` // Description of what the author is known for

    // Company/organization info
    Headquarters *string `json:"headquarters,omitempty" yaml:"headquarters,omitempty"` // Company headquarters location
    IconURL      *string `json:"icon_url,omitempty" yaml:"icon_url,omitempty"`         // Author icon/logo URL

    // Website, social links, and other relevant URLs
    Website     *string `json:"website,omitempty" yaml:"website,omitempty"`         // Official website URL
    HuggingFace *string `json:"huggingface,omitempty" yaml:"huggingface,omitempty"` // Hugging Face profile/organization URL
    GitHub      *string `json:"github,omitempty" yaml:"github,omitempty"`           // GitHub profile/organization URL
    Twitter     *string `json:"twitter,omitempty" yaml:"twitter,omitempty"`         // X (formerly Twitter) profile URL

    // Catalog and models
    Catalog *AuthorCatalog    `json:"catalog,omitempty" yaml:"catalog,omitempty"` // Primary provider catalog for this author's models
    Models  map[string]*Model `json:"-" yaml:"-"`                                 // Models published by this author - not serialized

    // Timestamps for record keeping and auditing
    CreatedAt utc.Time `json:"created_at" yaml:"created_at"` // Created date (YYYY-MM or YYYY-MM-DD format)
    UpdatedAt utc.Time `json:"updated_at" yaml:"updated_at"` // Last updated date (YYYY-MM or YYYY-MM-DD format)
}

func DeepCopyAuthor
func DeepCopyAuthor(author Author) Author

DeepCopyAuthor creates a deep copy of an Author including its Models map.

func DeepCopyAuthors
func DeepCopyAuthors(authors []Author) []Author

DeepCopyAuthors creates a deep copy of an Author slice.

func TestAuthor
func TestAuthor(t testing.TB) *Author

TestAuthor creates a test author with sensible defaults.

type AuthorAttribution

AuthorAttribution defines how to identify an author's models across providers. Uses standard Go glob pattern syntax for case-insensitive model ID matching.

Supports three modes:

  1. Provider-only: provider_id set, no patterns - all models from that provider belong to this author
  2. Provider + patterns: provider_id + patterns - only matching models from that provider, then cross-provider attribution
  3. Global patterns: patterns only - direct case-insensitive pattern matching across all providers

Glob Pattern Syntax (case-insensitive):

  • matches any sequence of characters (except path separators) ? matches any single character [abc] matches any character in the set [a-z] matches any character in the range

Examples:

"llama*" matches llama-3, Llama3.1-8b, LLAMA-BIG
"*-llama-*" matches deepseek-r1-distill-llama-70b, DeepSeek-R1-Distill-LLAMA-70B
"gpt-*" matches gpt-4, GPT-3.5-turbo, Gpt-4o

type AuthorAttribution struct {
    ProviderID ProviderID `json:"provider_id,omitempty" yaml:"provider_id,omitempty"` // Optional provider to source models from
    Patterns   []string   `json:"patterns,omitempty" yaml:"patterns,omitempty"`       // Glob patterns to match model IDs
}

type AuthorCatalog

AuthorCatalog represents the relationship between an author and their authoritative provider catalog. This contains the attribution configuration for identifying the author's models across providers.

type AuthorCatalog struct {
    Description *string            `json:"description,omitempty" yaml:"description,omitempty"` // Optional description of this mapping relationship
    Attribution *AuthorAttribution `json:"attribution,omitempty" yaml:"attribution,omitempty"` // Model attribution configuration for multi-provider inference
}

type AuthorID

AuthorID is a unique identifier for an author.

type AuthorID string

Author ID constants for compile-time safety and consistency.

const (
    // Major AI Companies.
    AuthorIDOpenAI    AuthorID = "openai"
    AuthorIDAnthropic AuthorID = "anthropic"
    AuthorIDGoogle    AuthorID = "google"
    AuthorIDDeepMind  AuthorID = "deepmind"
    AuthorIDMeta      AuthorID = "meta"
    AuthorIDMicrosoft AuthorID = "microsoft"
    AuthorIDMistralAI AuthorID = "mistral"
    AuthorIDCohere    AuthorID = "cohere"
    // AuthorIDCerebras removed - Cerebras is an inference provider, not a model creator.
    AuthorIDGroq        AuthorID = "groq"
    AuthorIDAlibabaQwen AuthorID = "alibaba"
    AuthorIDQwen        AuthorID = "qwen"
    AuthorIDXAI         AuthorID = "xai"

    // Research Institutions.
    AuthorIDStanford    AuthorID = "stanford"
    AuthorIDMIT         AuthorID = "mit"
    AuthorIDCMU         AuthorID = "cmu"
    AuthorIDUCBerkeley  AuthorID = "uc-berkeley"
    AuthorIDCornell     AuthorID = "cornell"
    AuthorIDPrinceton   AuthorID = "princeton"
    AuthorIDHarvard     AuthorID = "harvard"
    AuthorIDOxford      AuthorID = "oxford"
    AuthorIDCambridge   AuthorID = "cambridge"
    AuthorIDETHZurich   AuthorID = "eth-zurich"
    AuthorIDUWashington AuthorID = "uw"
    AuthorIDUChicago    AuthorID = "uchicago"
    AuthorIDYale        AuthorID = "yale"
    AuthorIDDuke        AuthorID = "duke"
    AuthorIDCaltech     AuthorID = "caltech"

    // Open Source Communities & Platforms.
    AuthorIDHuggingFace AuthorID = "huggingface"
    AuthorIDEleutherAI  AuthorID = "eleutherai"
    AuthorIDTogether    AuthorID = "together"
    AuthorIDMosaicML    AuthorID = "mosaicml"
    AuthorIDStabilityAI AuthorID = "stability"
    AuthorIDRunwayML    AuthorID = "runway"
    AuthorIDMidjourney  AuthorID = "midjourney"
    AuthorIDLAION       AuthorID = "laion"
    AuthorIDBigScience  AuthorID = "bigscience"
    AuthorIDAlignmentRC AuthorID = "alignment-research"
    AuthorIDH2OAI       AuthorID = "h2o.ai"
    AuthorIDMoxin       AuthorID = "moxin"

    // Chinese Organizations.
    AuthorIDBaidu      AuthorID = "baidu"
    AuthorIDTencent    AuthorID = "tencent"
    AuthorIDByteDance  AuthorID = "bytedance"
    AuthorIDDeepSeek   AuthorID = "deepseek"
    AuthorIDBAAI       AuthorID = "baai"
    AuthorID01AI       AuthorID = "01.ai"
    AuthorIDBaichuan   AuthorID = "baichuan"
    AuthorIDMiniMax    AuthorID = "minimax"
    AuthorIDMoonshot   AuthorID = "moonshotai"
    AuthorIDShanghaiAI AuthorID = "shanghai-ai-lab"
    AuthorIDZhipuAI    AuthorID = "zhipu-ai"
    AuthorIDSenseTime  AuthorID = "sensetime"
    AuthorIDHuawei     AuthorID = "huawei"
    AuthorIDTsinghua   AuthorID = "tsinghua"
    AuthorIDPeking     AuthorID = "peking"

    // Other Notable Organizations.
    AuthorIDNVIDIA     AuthorID = "nvidia"
    AuthorIDSalesforce AuthorID = "salesforce"
    AuthorIDIBM        AuthorID = "ibm"
    AuthorIDApple      AuthorID = "apple"
    AuthorIDAmazon     AuthorID = "amazon"
    AuthorIDAdept      AuthorID = "adept"
    AuthorIDAI21       AuthorID = "ai21"
    AuthorIDInflection AuthorID = "inflection"
    AuthorIDCharacter  AuthorID = "character"
    AuthorIDPerplexity AuthorID = "perplexity"
    AuthorIDAnysphere  AuthorID = "anysphere"
    AuthorIDCursor     AuthorID = "cursor"

    // Notable Fine-Tuned Model Creators & Publishers.
    AuthorIDCognitiveComputations AuthorID = "cognitivecomputations"
    AuthorIDEricHartford          AuthorID = "ehartford"
    AuthorIDNousResearch          AuthorID = "nousresearch"
    AuthorIDTeknium               AuthorID = "teknium"
    AuthorIDJonDurbin             AuthorID = "jondurbin"
    AuthorIDLMSYS                 AuthorID = "lmsys"
    AuthorIDVicuna                AuthorID = "vicuna-team"
    AuthorIDAlpacaTeam            AuthorID = "stanford-alpaca"
    AuthorIDWizardLM              AuthorID = "wizardlm"
    AuthorIDOpenOrca              AuthorID = "open-orca"
    AuthorIDPhind                 AuthorID = "phind"
    AuthorIDCodeFuse              AuthorID = "codefuse"
    AuthorIDTHUDM                 AuthorID = "thudm"
    AuthorIDGeorgiaTechRI         AuthorID = "gatech"
    AuthorIDFastChat              AuthorID = "fastchat"

    // Special constant for unknown authors.
    AuthorIDUnknown AuthorID = "unknown"
)

func ParseAuthorID
func ParseAuthorID(s string) AuthorID

ParseAuthorID attempts to parse a string into an AuthorID. It first tries to find the author by exact ID match, then by aliases, and finally normalizes the string if no match is found.

func (AuthorID) String
func (id AuthorID) String() string

String returns the string representation of an AuthorID.

type AuthorMapping

AuthorMapping defines how to extract and normalize authors.

type AuthorMapping struct {
    Field      string              `yaml:"field" json:"field"`           // Field to extract from (e.g., "owned_by")
    Normalized map[string]AuthorID `yaml:"normalized" json:"normalized"` // Normalization map (e.g., "Meta" -> "meta")
}

type Authors

Authors is a concurrent safe map of authors.

type Authors struct {
    // contains filtered or unexported fields
}

func NewAuthors
func NewAuthors(opts ...AuthorsOption) *Authors

NewAuthors creates a new Authors map with optional configuration.

func (*Authors) Add
func (a *Authors) Add(author *Author) error

Add adds an author, returning an error if it already exists.

func (*Authors) AddBatch
func (a *Authors) AddBatch(authors []*Author) map[AuthorID]error

AddBatch adds multiple authors in a single operation. Only adds authors that don't already exist - fails if an author ID already exists. Returns a map of author IDs to errors for any failed additions.

func (*Authors) Clear
func (a *Authors) Clear()

Clear removes all authors.

func (*Authors) Delete
func (a *Authors) Delete(id AuthorID) error

Delete removes an author by id. Returns an error if the author doesn't exist.

func (*Authors) DeleteBatch
func (a *Authors) DeleteBatch(ids []AuthorID) map[AuthorID]error

DeleteBatch removes multiple authors by their IDs. Returns a map of errors for authors that couldn't be deleted (not found).

func (*Authors) EncodeYAML
func (a *Authors) EncodeYAML() (string, error)

EncodeYAML returns formatted author YAML or a typed parse error when an author value cannot be represented safely.

func (*Authors) Exists
func (a *Authors) Exists(id AuthorID) bool

Exists checks if an author exists without returning it.

func (*Authors) ForEach
func (a *Authors) ForEach(fn func(id AuthorID, author *Author) bool)

ForEach applies a function to each author. The function should not modify the author. If the function returns false, iteration stops early.

func (*Authors) FormatYAML
func (a *Authors) FormatYAML() string

FormatYAML returns the authors as formatted YAML sorted alphabetically by ID.

func (*Authors) Get
func (a *Authors) Get(id AuthorID) (*Author, bool)

Get returns an author by id and whether it exists.

func (*Authors) Len
func (a *Authors) Len() int

Len returns the number of authors.

func (*Authors) List
func (a *Authors) List() []Author

List returns a slice of all authors as values (copies).

func (*Authors) Map
func (a *Authors) Map() map[AuthorID]*Author

Map returns a copy of all authors.

func (*Authors) Resolve
func (a *Authors) Resolve(id AuthorID) (*Author, bool)

Resolve returns an author by ID or alias. It first tries an exact ID match, then searches all author aliases. This allows commands to accept both canonical IDs and common aliases silently.

func (*Authors) Set
func (a *Authors) Set(id AuthorID, author *Author) error

Set sets an author by id. Returns an error if author is nil.

func (*Authors) SetBatch
func (a *Authors) SetBatch(authors map[AuthorID]*Author) error

SetBatch sets multiple authors in a single operation. Overwrites existing authors or adds new ones (upsert behavior). Returns an error if any author is nil.

type AuthorsOption

AuthorsOption defines a function that configures an Authors instance.

type AuthorsOption func(*Authors)

func WithAuthorsCapacity
func WithAuthorsCapacity(capacity int) AuthorsOption

WithAuthorsCapacity sets the initial capacity of the authors map.

func WithAuthorsMap
func WithAuthorsMap(authors map[AuthorID]*Author) AuthorsOption

WithAuthorsMap initializes the map with existing authors.

type AuthorsReader

AuthorsReader exposes author collection reads without mutation methods.

type AuthorsReader interface {
    Get(AuthorID) (*Author, bool)
    Resolve(AuthorID) (*Author, bool)
    Exists(AuthorID) bool
    Len() int
    List() []Author
    Map() map[AuthorID]*Author
    ForEach(func(AuthorID, *Author) bool)
    FormatYAML() string
}

type BootstrapManifest

BootstrapManifest binds the offline embedded catalog to exact canonical catalog bytes and a generation time.

type BootstrapManifest struct {
    ManifestVersion uint64            `json:"manifest_version" yaml:"manifest_version"`
    GenerationID    string            `json:"generation_id" yaml:"generation_id"`
    GeneratedAt     time.Time         `json:"generated_at" yaml:"generated_at"`
    SchemaVersion   uint64            `json:"schema_version" yaml:"schema_version"`
    Payload         PayloadDescriptor `json:"payload" yaml:"payload"`
}

func ParseBootstrapManifestJSON
func ParseBootstrapManifestJSON(data []byte) (BootstrapManifest, error)

ParseBootstrapManifestJSON strictly parses embedded-bootstrap metadata.

func (BootstrapManifest) Validate
func (m BootstrapManifest) Validate() error

Validate checks the embedded-bootstrap metadata contract.

type Builder

Builder is the advanced mutable catalog construction type. It is intended for custom update callbacks, source/plugin authors, and persistence pipelines; ordinary consumers should use the immutable *Catalog returned by *starmap.Client.Catalog. It can work as: - Memory catalog (readFS == nil) - Embedded catalog (readFS is embed.FS) - Files catalog (readFS is os.DirFS) - Custom catalog (readFS is any fs.FS implementation).

type Builder struct {
    // contains filtered or unexported fields
}

func New
func New(opt Option, opts ...Option) (*Builder, error)

New creates a new builder with the given options WithEmbedded() = embedded catalog with auto-load WithFiles(path) = files catalog with auto-load.

func NewBuilderFrom
func NewBuilderFrom(source Reader) (*Builder, error)

NewBuilderFrom copies source into a new independent builder.

func NewEmbedded
func NewEmbedded() (*Builder, error)

NewEmbedded creates a catalog backed by embedded files. This is the recommended catalog for production use as it includes all model data compiled into the binary.

func NewEmpty
func NewEmpty() *Builder

NewEmpty creates an in-memory empty catalog. This is useful for testing or temporary catalogs that don't need persistence.

Example:

catalog := NewEmpty()
provider := Provider{ID: "openai", Models: map[string]Model{}}
catalog.SetProvider(provider)

func NewFromFS
func NewFromFS(fsys fs.FS, root string) (*Builder, error)

NewFromFS creates a catalog from a custom filesystem implementation. This allows for advanced use cases like virtual filesystems or custom storage backends.

Example:

var myFS embed.FS
catalog, err := NewFromFS(myFS, "catalog")

func NewFromPath
func NewFromPath(path string) (*Builder, error)

NewFromPath creates a catalog backed by files on disk. This is useful for development when you want to edit catalog files without recompiling the binary.

Example:

catalog, err := NewFromPath("./internal/embedded/catalog")
if err != nil {
    log.Fatal(err)
}

func NewLocal
func NewLocal(path string) (*Builder, error)

NewLocal creates a catalog by merging embedded catalog with local file. - Always loads embedded catalog (latest provider configs) - Merges with file catalog if path provided and file exists - Returns embedded-only if file doesn't exist or path is empty

This ensures that the catalog always has the latest provider configurations from the embedded catalog, while preserving saved model data from files.

func TestCatalog
func TestCatalog(t testing.TB) *Builder

TestCatalog creates a test catalog with sample data.

func (*Builder) Author
func (cat *Builder) Author(id AuthorID) (Author, error)

Author returns an author by ID or alias. Silently resolves aliases to canonical author IDs.

func (*Builder) Authors
func (cat *Builder) Authors() AuthorsReader

Authors returns the authors collection.

func (*Builder) Build
func (cat *Builder) Build() (*Catalog, error)

Build publishes an immutable deep copy of the builder's current state.

func (*Builder) ClearProvenance
func (cat *Builder) ClearProvenance()

ClearProvenance removes catalog provenance.

func (*Builder) Copy
func (cat *Builder) Copy() (*Builder, error)

Copy creates a deep copy of the catalog.

func (*Builder) DeleteAuthor
func (cat *Builder) DeleteAuthor(id AuthorID) error

DeleteAuthor deletes an author.

func (*Builder) DeleteEndpoint
func (cat *Builder) DeleteEndpoint(id string) error

DeleteEndpoint deletes an endpoint.

func (*Builder) DeleteProvider
func (cat *Builder) DeleteProvider(id ProviderID) error

DeleteProvider deletes a provider.

func (*Builder) DeleteProviderModel
func (cat *Builder) DeleteProviderModel(providerID ProviderID, modelID string) error

DeleteProviderModel deletes a model from a provider atomically.

func (*Builder) Endpoint
func (cat *Builder) Endpoint(id string) (Endpoint, error)

Endpoint returns an endpoint by ID.

func (*Builder) Endpoints
func (cat *Builder) Endpoints() EndpointsReader

Endpoints returns the endpoints collection.

func (*Builder) FindModel
func (cat *Builder) FindModel(id string) (Model, error)

FindModel searches for a model by ID.

func (*Builder) Load
func (cat *Builder) Load() error

Load loads the catalog from the configured filesystem.

func (*Builder) MergeProvenance
func (cat *Builder) MergeProvenance(value provenance.Map)

MergeProvenance appends catalog provenance.

func (*Builder) MergeStrategy
func (cat *Builder) MergeStrategy() MergeStrategy

MergeStrategy returns the default merge strategy.

func (*Builder) MergeWith
func (cat *Builder) MergeWith(source Reader, opts ...MergeOption) error

MergeWith merges another catalog into this one.

func (*Builder) Models
func (cat *Builder) Models() ModelsReader

Models returns all models from all providers and authors.

func (*Builder) Provenance
func (cat *Builder) Provenance() ProvenanceReader

Provenance returns the provenance collection.

func (*Builder) Provider
func (cat *Builder) Provider(id ProviderID) (Provider, error)

Provider returns a provider by ID or alias. Silently resolves aliases to canonical provider IDs.

func (*Builder) ProviderModel
func (cat *Builder) ProviderModel(providerID ProviderID, modelID string) (Model, error)

ProviderModel returns one provider-specific model offering without flattening equal model IDs from other providers.

func (*Builder) ProviderModels
func (cat *Builder) ProviderModels(id ProviderID) (ModelsReader, error)

ProviderModels returns the models served by a provider or one of its aliases.

func (*Builder) Providers
func (cat *Builder) Providers() ProvidersReader

Providers returns the providers collection.

func (*Builder) ReplaceWith
func (cat *Builder) ReplaceWith(source Reader) error

ReplaceWith replaces this catalog's contents with another.

func (*Builder) Save
func (cat *Builder) Save(opts ...save.Option) error

Save saves the catalog to the configured filesystem.

func (*Builder) SetAuthor
func (cat *Builder) SetAuthor(author Author) error

SetAuthor sets an author (upsert).

func (*Builder) SetEndpoint
func (cat *Builder) SetEndpoint(endpoint Endpoint) error

SetEndpoint sets an endpoint (upsert).

func (*Builder) SetMergeStrategy
func (cat *Builder) SetMergeStrategy(strategy MergeStrategy)

SetMergeStrategy sets the default merge strategy.

func (*Builder) SetProvenance
func (cat *Builder) SetProvenance(value provenance.Map)

SetProvenance replaces catalog provenance.

func (*Builder) SetProvider
func (cat *Builder) SetProvider(provider Provider) error

SetProvider sets a provider (upsert).

func (*Builder) SetProviderModel
func (cat *Builder) SetProviderModel(providerID ProviderID, model Model) error

SetProviderModel sets a model on a provider atomically.

type Catalog

Catalog is Starmap's immutable canonical catalog. Its state is unexported, safe to retain across goroutines, and accessible only through read methods.

type Catalog struct {
    // contains filtered or unexported fields
}

func NewCatalog
func NewCatalog(source Reader) (*Catalog, error)

NewCatalog copies source into an immutable canonical catalog.

func (*Catalog) Author
func (r *Catalog) Author(id AuthorID) (Author, error)

Author returns a caller-owned copy of an author.

func (*Catalog) Authors
func (r *Catalog) Authors() AuthorsReader

Authors returns the immutable catalog's author collection reader.

func (*Catalog) Definition
func (r *Catalog) Definition(id ModelDefinitionID) (ModelDefinition, error)

Definition returns one caller-owned canonical model definition.

func (*Catalog) Definitions
func (r *Catalog) Definitions() []ModelDefinition

Definitions returns caller-owned canonical definitions in ID order.

func (*Catalog) Endpoint
func (r *Catalog) Endpoint(id string) (Endpoint, error)

Endpoint returns a caller-owned copy of an endpoint.

func (*Catalog) Endpoints
func (r *Catalog) Endpoints() EndpointsReader

Endpoints returns the immutable catalog's endpoint collection reader.

func (*Catalog) FindModel
func (r *Catalog) FindModel(id string) (ModelDefinition, error)

FindModel returns the canonical provider-independent model definition. Use Offering for provider price, limits, availability, and request behavior; use LegacyV0 when migrating code that requires the old flattened Model.

func (*Catalog) LegacyV0
func (r *Catalog) LegacyV0() LegacyCatalogV0

LegacyV0 returns the concrete schema-v0 compatibility adapter.

func (*Catalog) MaterializeRouteAlias
func (r *Catalog) MaterializeRouteAlias(alias RouteAlias) (RouteAliasResolution, error)

MaterializeRouteAlias resolves current eligibility without storing routing policy in source ingestion or the canonical catalog.

func (*Catalog) Models
func (r *Catalog) Models() ModelsReader

Models returns the immutable catalog's legacy bare-ID model reader.

Deprecated: use Definition, Offering, ProviderOfferings, or LegacyV0.

func (*Catalog) Offering
func (r *Catalog) Offering(providerID ProviderID, providerModelID ProviderModelID) (ProviderOffering, error)

Offering returns one caller-owned provider-scoped model offering. Provider aliases resolve to their canonical provider before key lookup.

func (*Catalog) Provenance
func (r *Catalog) Provenance() ProvenanceReader

Provenance returns the immutable catalog's provenance reader.

func (*Catalog) Provider
func (r *Catalog) Provider(id ProviderID) (Provider, error)

Provider returns a caller-owned copy of a provider.

func (*Catalog) ProviderModel
func (r *Catalog) ProviderModel(providerID ProviderID, modelID string) (Model, error)

ProviderModel returns one legacy provider-scoped model record.

Deprecated: use Offering or LegacyV0.

func (*Catalog) ProviderModels
func (r *Catalog) ProviderModels(id ProviderID) (ModelsReader, error)

ProviderModels returns legacy model records for a provider or alias.

Deprecated: use ProviderOfferings or LegacyV0.

func (*Catalog) ProviderOfferings
func (r *Catalog) ProviderOfferings(providerID ProviderID) ([]ProviderOffering, error)

ProviderOfferings returns caller-owned offerings in provider-model-ID order.

func (*Catalog) Providers
func (r *Catalog) Providers() ProvidersReader

Providers returns the immutable catalog's provider collection reader.

type CatalogPayload

CatalogPayload is catalog schema v1's canonical JSON representation. Provider and author models are separate maps because their legacy structs do not serialize runtime model indexes.

type CatalogPayload struct {
    SchemaVersion  uint64             `json:"schema_version"`
    Providers      []Provider         `json:"providers"`
    Authors        []Author           `json:"authors"`
    Endpoints      []Endpoint         `json:"endpoints"`
    ProviderModels map[string][]Model `json:"provider_models"`
    AuthorModels   map[string][]Model `json:"author_models"`
    Provenance     provenance.Map     `json:"provenance"`
}

type ConsumerCompatibility

ConsumerCompatibility declares the catalog schema versions that can consume this generation. It never refers to a Starmap or Starport binary version.

type ConsumerCompatibility struct {
    MinSchemaVersion uint64 `json:"min_schema_version" yaml:"min_schema_version"`
    MaxSchemaVersion uint64 `json:"max_schema_version" yaml:"max_schema_version"`
}

func (ConsumerCompatibility) SupportsSchema
func (c ConsumerCompatibility) SupportsSchema(schemaVersion uint64) bool

SupportsSchema reports whether a consumer catalog schema is compatible.

type Endpoint

Endpoint represents an endpoint configuration.

type Endpoint struct {
    ID          string `json:"id" yaml:"id"`                                       // Unique endpoint identifier
    Name        string `json:"name" yaml:"name"`                                   // Display name (must not be empty)
    Description string `json:"description,omitempty" yaml:"description,omitempty"` // Description of the endpoint and its use cases
}

func DeepCopyEndpoint
func DeepCopyEndpoint(endpoint Endpoint) Endpoint

DeepCopyEndpoint creates a copy of an Endpoint.

func TestEndpoint
func TestEndpoint(t testing.TB) *Endpoint

TestEndpoint creates a test endpoint with sensible defaults.

type EndpointType

EndpointType specifies the API style for model listing.

type EndpointType string


const (
    // EndpointTypeOpenAI represents OpenAI-compatible API.
    EndpointTypeOpenAI EndpointType = "openai"
    // EndpointTypeAnthropic represents Anthropic API format.
    EndpointTypeAnthropic EndpointType = "anthropic"
    // EndpointTypeGoogle represents Google AI Studio.
    EndpointTypeGoogle EndpointType = "google"
    // EndpointTypeGoogleCloud represents Google Vertex AI.
    EndpointTypeGoogleCloud EndpointType = "google-cloud"
)

type Endpoints

Endpoints is a concurrent safe map of endpoints.

type Endpoints struct {
    // contains filtered or unexported fields
}

func NewEndpoints
func NewEndpoints(opts ...EndpointsOption) *Endpoints

NewEndpoints creates a new Endpoints map with optional configuration.

func (*Endpoints) Add
func (e *Endpoints) Add(endpoint *Endpoint) error

Add adds an endpoint, returning an error if it already exists.

func (*Endpoints) AddBatch
func (e *Endpoints) AddBatch(endpoints []*Endpoint) map[string]error

AddBatch adds multiple endpoints in a single operation. Only adds endpoints that don't already exist - fails if an endpoint ID already exists. Returns a map of endpoint IDs to errors for any failed additions.

func (*Endpoints) Clear
func (e *Endpoints) Clear()

Clear removes all endpoints.

func (*Endpoints) Delete
func (e *Endpoints) Delete(id string) error

Delete removes an endpoint by id. Returns an error if the endpoint doesn't exist.

func (*Endpoints) DeleteBatch
func (e *Endpoints) DeleteBatch(ids []string) map[string]error

DeleteBatch removes multiple endpoints by their IDs. Returns a map of errors for endpoints that couldn't be deleted (not found).

func (*Endpoints) Exists
func (e *Endpoints) Exists(id string) bool

Exists checks if an endpoint exists without returning it.

func (*Endpoints) ForEach
func (e *Endpoints) ForEach(fn func(id string, endpoint *Endpoint) bool)

ForEach applies a function to each endpoint. The function should not modify the endpoint. If the function returns false, iteration stops early.

func (*Endpoints) Get
func (e *Endpoints) Get(id string) (*Endpoint, bool)

Get returns an endpoint by id and whether it exists.

func (*Endpoints) Len
func (e *Endpoints) Len() int

Len returns the number of endpoints.

func (*Endpoints) List
func (e *Endpoints) List() []Endpoint

List returns a slice of all endpoints as values (copies).

func (*Endpoints) Map
func (e *Endpoints) Map() map[string]*Endpoint

Map returns a copy of all endpoints.

func (*Endpoints) Set
func (e *Endpoints) Set(id string, endpoint *Endpoint) error

Set sets an endpoint by id. Returns an error if endpoint is nil.

func (*Endpoints) SetBatch
func (e *Endpoints) SetBatch(endpoints map[string]*Endpoint) error

SetBatch sets multiple endpoints in a single operation. Overwrites existing endpoints or adds new ones (upsert behavior). Returns an error if any endpoint is nil.

type EndpointsOption

EndpointsOption defines a function that configures an Endpoints instance.

type EndpointsOption func(*Endpoints)

func WithEndpointsCapacity
func WithEndpointsCapacity(capacity int) EndpointsOption

WithEndpointsCapacity sets the initial capacity of the endpoints map.

func WithEndpointsMap
func WithEndpointsMap(endpoints map[string]*Endpoint) EndpointsOption

WithEndpointsMap initializes the map with existing endpoints.

type EndpointsReader

EndpointsReader exposes endpoint collection reads without mutation methods.

type EndpointsReader interface {
    Get(string) (*Endpoint, bool)
    Exists(string) bool
    Len() int
    List() []Endpoint
    Map() map[string]*Endpoint
    ForEach(func(string, *Endpoint) bool)
}

type FeatureRule

FeatureRule defines conditions for inferring model features.

type FeatureRule struct {
    Field    string   `yaml:"field" json:"field"`       // Field to check (e.g., "id", "owned_by")
    Contains []string `yaml:"contains" json:"contains"` // If field contains any of these strings
    Feature  string   `yaml:"feature" json:"feature"`   // Feature to enable (e.g., "tools", "reasoning")
    Value    bool     `yaml:"value" json:"value"`       // Value to set for the feature
}

type FieldMapping

FieldMapping defines how to map API response fields to model fields. Type conversion is automatic based on the destination field type.

type FieldMapping struct {
    From string `yaml:"from" json:"from"` // Source field path in API response (e.g., "max_model_len")
    To   string `yaml:"to" json:"to"`     // Target field path in Model (e.g., "limits.context_window")
}

type FloatRange

FloatRange represents a range of float values.

type FloatRange struct {
    Min     float64 `json:"min" yaml:"min"`         // Minimum value
    Max     float64 `json:"max" yaml:"max"`         // Maximum value
    Default float64 `json:"default" yaml:"default"` // Default value
}

type GenerationCompleteness

GenerationCompleteness describes whether a generation contains every record expected from the observations used to build it.

type GenerationCompleteness string


const (
    // GenerationCompletenessComplete means the generation contains all expected
    // records. It may still be degraded for another reason, such as stale input.
    GenerationCompletenessComplete GenerationCompleteness = "complete"
    // GenerationCompletenessPartial means at least one expected input or record
    // is absent and the generation must also be marked degraded.
    GenerationCompletenessPartial GenerationCompleteness = "partial"
)

type GenerationManifest

GenerationManifest describes one immutable, validated catalog generation. It is shared by local stores and distribution transports; transport-specific URLs, release tags, and binary versions do not belong in this domain record.

type GenerationManifest struct {
    ManifestVersion       uint64                     `json:"manifest_version" yaml:"manifest_version"`
    SchemaVersion         uint64                     `json:"schema_version" yaml:"schema_version"`
    GenerationID          string                     `json:"generation_id" yaml:"generation_id"`
    GeneratedAt           time.Time                  `json:"generated_at" yaml:"generated_at"`
    Payload               PayloadDescriptor          `json:"payload" yaml:"payload"`
    Validation            GenerationValidationReport `json:"validation" yaml:"validation"`
    SyncRunID             string                     `json:"sync_run_id" yaml:"sync_run_id"`
    SourceObservations    []SourceObservationLink    `json:"source_observations" yaml:"source_observations"`
    Completeness          GenerationCompleteness     `json:"completeness" yaml:"completeness"`
    Degraded              bool                       `json:"degraded" yaml:"degraded"`
    DegradationReasons    []string                   `json:"degradation_reasons,omitempty" yaml:"degradation_reasons,omitempty"`
    ConsumerCompatibility ConsumerCompatibility      `json:"consumer_compatibility" yaml:"consumer_compatibility"`
}

func ParseGenerationManifestJSON
func ParseGenerationManifestJSON(data []byte) (GenerationManifest, error)

ParseGenerationManifestJSON strictly parses and validates a JSON manifest. Unknown members, missing required members (including false/zero-valued members), malformed JSON, and trailing documents are rejected with typed validation errors.

func (GenerationManifest) Copy
func (m GenerationManifest) Copy() GenerationManifest

Copy returns a value whose slices do not alias the original manifest.

func (GenerationManifest) Validate
func (m GenerationManifest) Validate() error

Validate verifies that a manifest is complete and eligible for publication.

type GenerationValidationCheck

GenerationValidationCheck records one deterministic validation decision.

type GenerationValidationCheck struct {
    Name    string                          `json:"name" yaml:"name"`
    Status  GenerationValidationCheckStatus `json:"status" yaml:"status"`
    Message string                          `json:"message,omitempty" yaml:"message,omitempty"`
}

type GenerationValidationCheckStatus

GenerationValidationCheckStatus is the result of one validation check.

type GenerationValidationCheckStatus string


const (
    // GenerationValidationCheckPassed records a successful check.
    GenerationValidationCheckPassed GenerationValidationCheckStatus = "passed"
    // GenerationValidationCheckWarning records a non-fatal validation warning.
    GenerationValidationCheckWarning GenerationValidationCheckStatus = "warning"
    // GenerationValidationCheckFailed records a failed required check.
    GenerationValidationCheckFailed GenerationValidationCheckStatus = "failed"
)

type GenerationValidationReport

GenerationValidationReport records the validator identity and exact outcome that made a candidate eligible (or ineligible) for publication.

type GenerationValidationReport struct {
    ValidatorVersion string                      `json:"validator_version" yaml:"validator_version"`
    ValidatedAt      time.Time                   `json:"validated_at" yaml:"validated_at"`
    Status           GenerationValidationStatus  `json:"status" yaml:"status"`
    ErrorCount       int                         `json:"error_count" yaml:"error_count"`
    WarningCount     int                         `json:"warning_count" yaml:"warning_count"`
    Checks           []GenerationValidationCheck `json:"checks" yaml:"checks"`
}

type GenerationValidationStatus

GenerationValidationStatus is the overall result of generation validation.

type GenerationValidationStatus string


const (
    // GenerationValidationPassed means every required validation check passed.
    GenerationValidationPassed GenerationValidationStatus = "passed"
    // GenerationValidationFailed means at least one required check failed. A
    // failed generation is evidence, but is not eligible for publication.
    GenerationValidationFailed GenerationValidationStatus = "failed"
)

type IntRange

IntRange represents a range of integer values.

type IntRange struct {
    Min     int `json:"min" yaml:"min"`         // Minimum value
    Max     int `json:"max" yaml:"max"`         // Maximum value
    Default int `json:"default" yaml:"default"` // Default value
}

type LegacyCatalogV0

LegacyCatalogV0 is the explicit transition adapter for the pre-split catalog read shape. New consumers should use Catalog.Definition, Catalog.Offering, and Catalog.ProviderOfferings.

type LegacyCatalogV0 struct {
    // contains filtered or unexported fields
}

func (LegacyCatalogV0) FindModel
func (a LegacyCatalogV0) FindModel(id string) (Model, error)

FindModel returns one legacy flattened bare-ID model record.

func (LegacyCatalogV0) Models
func (a LegacyCatalogV0) Models() ModelsReader

Models returns the legacy flattened bare-ID model collection.

func (LegacyCatalogV0) ProviderModel
func (a LegacyCatalogV0) ProviderModel(providerID ProviderID, modelID string) (Model, error)

ProviderModel returns one legacy provider-scoped model record.

func (LegacyCatalogV0) ProviderModels
func (a LegacyCatalogV0) ProviderModels(id ProviderID) (ModelsReader, error)

ProviderModels returns legacy model records scoped to a provider or alias.

type LegacySchemaMigration

LegacySchemaMigration is the loss-accounted result of converting overloaded legacy Model records into canonical definitions and provider offerings.

type LegacySchemaMigration struct {
    Definitions map[ModelDefinitionID]ModelDefinition `json:"definitions" yaml:"definitions"`
    Offerings   map[OfferingKey]ProviderOffering      `json:"-" yaml:"-"`
    Report      LegacySchemaMigrationReport           `json:"report" yaml:"report"`
}

func MigrateLegacySchema
func MigrateLegacySchema(reader Reader) (*LegacySchemaMigration, error)

MigrateLegacySchema deterministically converts every provider model in a legacy catalog. It never mutates the input and reports every default or conflicting canonical-definition choice.

type LegacySchemaMigrationChange

LegacySchemaMigrationChange is one reviewable legacy-to-definition/offering difference.

type LegacySchemaMigrationChange struct {
    Classification MigrationChangeClassification `json:"classification" yaml:"classification"`
    Field          string                        `json:"field" yaml:"field"`
    OfferingKey    OfferingKey                   `json:"offering_key" yaml:"offering_key"`
    Message        string                        `json:"message" yaml:"message"`
}

type LegacySchemaMigrationReport

LegacySchemaMigrationReport summarizes all classified migration differences.

type LegacySchemaMigrationReport struct {
    Exact        int                           `json:"exact" yaml:"exact"`
    Defaulted    int                           `json:"defaulted" yaml:"defaulted"`
    Conflicts    int                           `json:"conflicts" yaml:"conflicts"`
    Missing      int                           `json:"missing" yaml:"missing"`
    Unclassified int                           `json:"unclassified" yaml:"unclassified"`
    Changes      []LegacySchemaMigrationChange `json:"changes" yaml:"changes"`
}

type MergeOption

MergeOption configures how catalogs are merged.

type MergeOption func(*MergeOptions)

func WithStrategy
func WithStrategy(s MergeStrategy) MergeOption

WithStrategy overrides the merge strategy.

type MergeOptions

MergeOptions holds merge configuration.

type MergeOptions struct {
    Strategy MergeStrategy // nil means use source catalog's suggestion
}

func ParseMergeOptions
func ParseMergeOptions(opts ...MergeOption) *MergeOptions

ParseMergeOptions processes merge options and returns the configuration.

type MergeStrategy

MergeStrategy defines how catalogs should be merged.

type MergeStrategy int


const (
    // MergeEnrichEmpty intelligently merges, preserving existing non-empty values.
    MergeEnrichEmpty MergeStrategy = iota
    // MergeReplaceAll completely replaces the target catalog with the source.
    MergeReplaceAll
    // MergeAppendOnly only adds new items, skips existing ones.
    MergeAppendOnly
)

type MigrationChangeClassification

MigrationChangeClassification describes how a legacy field was transformed.

type MigrationChangeClassification string


const (
    // MigrationChangeExact means the value moved without semantic change.
    MigrationChangeExact MigrationChangeClassification = "exact"
    // MigrationChangeDefaulted means the legacy schema had no value and a documented default was used.
    MigrationChangeDefaulted MigrationChangeClassification = "defaulted"
    // MigrationChangeConflict means multiple legacy records disagreed and deterministic precedence was applied.
    MigrationChangeConflict MigrationChangeClassification = "conflict"
    // MigrationChangeMissing means the legacy corpus had no authoritative value and none was invented.
    MigrationChangeMissing MigrationChangeClassification = "missing"
)

type Model

Model represents a model configuration.

type Model struct {
    // Core identity
    ID          string      `json:"id" yaml:"id"`                                       // Unique model identifier
    Name        string      `json:"name" yaml:"name"`                                   // Display name (must not be empty)
    Authors     []Author    `json:"authors,omitempty" yaml:"authors,omitempty"`         // Authors/organizations of the model (if known)
    Description string      `json:"description,omitempty" yaml:"description,omitempty"` // Description of the model and its use cases
    Status      ModelStatus `json:"status,omitempty" yaml:"status,omitempty"`           // Lifecycle status such as active, beta, preview, or deprecated

    // Metadata - version and timing information
    Metadata *ModelMetadata `json:"metadata,omitempty" yaml:"metadata,omitempty"` // Metadata for the model

    // Lineage - model family and derivation information
    Lineage *ModelLineage `json:"lineage,omitempty" yaml:"lineage,omitempty"`

    // Features - what this model can do
    Features *ModelFeatures `json:"features,omitempty" yaml:"features,omitempty"`

    // Attachments - attachment support details
    Attachments *ModelAttachments `json:"attachments,omitempty" yaml:"attachments,omitempty"`

    // Generation - core chat completions generation controls
    Generation *ModelGeneration `json:"generation,omitempty" yaml:"generation,omitempty"`

    // Reasoning - reasoning effort levels
    Reasoning *ModelControlLevels `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`

    // ReasoningTokens - specific token allocation for reasoning processes
    ReasoningTokens *IntRange `json:"reasoning_tokens,omitempty" yaml:"reasoning_tokens,omitempty"`

    // Verbosity - response verbosity levels
    Verbosity *ModelControlLevels `json:"verbosity,omitempty" yaml:"verbosity,omitempty"`

    // Tools - external tool and capability integrations
    Tools *ModelTools `json:"tools,omitempty" yaml:"tools,omitempty"`

    // Delivery - technical response delivery capabilities (formats, protocols, streaming)
    Delivery *ModelDelivery `json:"response,omitempty" yaml:"response,omitempty"`

    // Modes - alternate service modes such as fast/priority variants
    Modes map[string]ModelMode `json:"modes,omitempty" yaml:"modes,omitempty"`

    // Operational characteristics
    Pricing *ModelPricing `json:"pricing,omitempty" yaml:"pricing,omitempty"` // Optional pricing information
    Limits  *ModelLimits  `json:"limits,omitempty" yaml:"limits,omitempty"`   // Model limits

    // Extensions - controlled source-specific fields that are not canonical schema
    Extensions SourceExtensions `json:"extensions,omitempty" yaml:"extensions,omitempty"`

    // Timestamps for record keeping and auditing
    CreatedAt utc.Time `json:"created_at" yaml:"created_at"` // Created date (YYYY-MM or YYYY-MM-DD format)
    UpdatedAt utc.Time `json:"updated_at" yaml:"updated_at"` // Last updated date (YYYY-MM or YYYY-MM-DD format)
}

func DeepCopyModel
func DeepCopyModel(model Model) Model

DeepCopyModel creates a deep copy of a Model.

func MergeModels
func MergeModels(existing, updated Model) Model

MergeModels performs a smart merge of two models, keeping existing values where the updated model has empty/nil values.

func TestModel
func TestModel(t testing.TB) *Model

TestModel creates a test model with sensible defaults.

func TestModelWithOptions
func TestModelWithOptions(t testing.TB, opts ...TestModelOption) *Model

TestModelWithOptions creates a test model with custom options.

func (*Model) EncodeYAML
func (m *Model) EncodeYAML() (string, error)

EncodeYAML returns formatted YAML or a typed parse error when model values cannot be represented safely.

func (*Model) FormatYAML
func (m *Model) FormatYAML() string

FormatYAML returns a well-formatted YAML representation with comments and proper structure.

func (*Model) FormatYAMLHeaderComment
func (m *Model) FormatYAMLHeaderComment() string

FormatYAMLHeaderComment returns a descriptive string for the model header comment.

type ModelArchitecture

ModelArchitecture represents the technical architecture details of a model.

type ModelArchitecture struct {
    ParameterCount string           `json:"parameter_count,omitempty" yaml:"parameter_count,omitempty"` // Model size (e.g., "7B", "70B", "405B")
    Type           ArchitectureType `json:"type,omitempty" yaml:"type,omitempty"`                       // Type of architecture
    Tokenizer      Tokenizer        `json:"tokenizer,omitempty" yaml:"tokenizer,omitempty"`             // Tokenizer type used by the model
    Precision      *string          `json:"precision,omitempty" yaml:"precision,omitempty"`             // Legacy precision format (use Quantization for filtering)
    Quantization   Quantization     `json:"quantization,omitempty" yaml:"quantization,omitempty"`       // Quantization level used by the model
    Quantized      bool             `json:"quantized" yaml:"quantized"`                                 // Whether the model has been quantized
    FineTuned      bool             `json:"fine_tuned" yaml:"fine_tuned"`                               // Whether this is a fine-tuned variant
    BaseModel      *string          `json:"base_model,omitempty" yaml:"base_model,omitempty"`           // Base model ID if fine-tuned
}

type ModelAttachments

ModelAttachments represents the attachment capabilities of a model.

type ModelAttachments struct {
    MimeTypes   []string `json:"mime_types,omitempty" yaml:"mime_types,omitempty"`       // Supported MIME types
    MaxFileSize *int64   `json:"max_file_size,omitempty" yaml:"max_file_size,omitempty"` // Maximum file size in bytes
    MaxFiles    *int     `json:"max_files,omitempty" yaml:"max_files,omitempty"`         // Maximum number of files per request
}

type ModelControlLevel

ModelControlLevel represents an effort/intensity level for model controls.

type ModelControlLevel string

Supported model control levels.

const (
    ModelControlLevelMinimum ModelControlLevel = "minimum"
    ModelControlLevelLow     ModelControlLevel = "low"
    ModelControlLevelMedium  ModelControlLevel = "medium"
    ModelControlLevelHigh    ModelControlLevel = "high"
    ModelControlLevelMaximum ModelControlLevel = "maximum"
)

func (ModelControlLevel) String
func (mcl ModelControlLevel) String() string

String returns the string representation of a ModelControlLevel.

type ModelControlLevels

ModelControlLevels represents a set of effort/intensity levels for model controls.

type ModelControlLevels struct {
    Levels  []ModelControlLevel `json:"levels" yaml:"levels"`   // Which levels this model supports
    Default *ModelControlLevel  `json:"default" yaml:"default"` // Default level
}

type ModelDefinition

ModelDefinition is the canonical provider-independent description of a model. Provider service facts belong to ProviderOffering, never this record.

type ModelDefinition struct {
    ID           ModelDefinitionID           `json:"id" yaml:"id"`
    Name         string                      `json:"name" yaml:"name"`
    AuthorIDs    []AuthorID                  `json:"author_ids" yaml:"author_ids"`
    Description  string                      `json:"description,omitempty" yaml:"description,omitempty"`
    Metadata     ModelDefinitionMetadata     `json:"metadata" yaml:"metadata"`
    Lineage      ModelDefinitionLineage      `json:"lineage" yaml:"lineage"`
    Weights      ModelDefinitionWeights      `json:"weights" yaml:"weights"`
    Capabilities ModelDefinitionCapabilities `json:"capabilities" yaml:"capabilities"`
    CreatedAt    utc.Time                    `json:"created_at" yaml:"created_at"`
    UpdatedAt    utc.Time                    `json:"updated_at" yaml:"updated_at"`
}

func (ModelDefinition) Validate
func (d ModelDefinition) Validate() error

Validate verifies canonical identity and authorship invariants.

type ModelDefinitionCapabilities

ModelDefinitionCapabilities groups intrinsic model behavior independently of any provider's service limits, price, endpoint, or availability.

type ModelDefinitionCapabilities struct {
    Features        *ModelFeatures      `json:"features,omitempty" yaml:"features,omitempty"`
    Attachments     *ModelAttachments   `json:"attachments,omitempty" yaml:"attachments,omitempty"`
    Generation      *ModelGeneration    `json:"generation,omitempty" yaml:"generation,omitempty"`
    Reasoning       *ModelControlLevels `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
    ReasoningTokens *IntRange           `json:"reasoning_tokens,omitempty" yaml:"reasoning_tokens,omitempty"`
    Verbosity       *ModelControlLevels `json:"verbosity,omitempty" yaml:"verbosity,omitempty"`
    Tools           *ModelTools         `json:"tools,omitempty" yaml:"tools,omitempty"`
    Delivery        *ModelDelivery      `json:"delivery,omitempty" yaml:"delivery,omitempty"`
}

type ModelDefinitionID

ModelDefinitionID identifies one provider-independent model definition.

type ModelDefinitionID string

type ModelDefinitionLineage

ModelDefinitionLineage describes canonical model-family relationships.

type ModelDefinitionLineage struct {
    Family string             `json:"family,omitempty" yaml:"family,omitempty"`
    Root   *ModelDefinitionID `json:"root,omitempty" yaml:"root,omitempty"`
    Parent *ModelDefinitionID `json:"parent,omitempty" yaml:"parent,omitempty"`
}

type ModelDefinitionMetadata

ModelDefinitionMetadata contains provider-independent release and discovery metadata.

type ModelDefinitionMetadata struct {
    ReleaseDate     utc.Time   `json:"release_date" yaml:"release_date"`
    KnowledgeCutoff *utc.Time  `json:"knowledge_cutoff,omitempty" yaml:"knowledge_cutoff,omitempty"`
    Tags            []ModelTag `json:"tags,omitempty" yaml:"tags,omitempty"`
}

type ModelDefinitionWeights

ModelDefinitionWeights describes provider-independent model weights and architecture.

type ModelDefinitionWeights struct {
    Open         bool               `json:"open" yaml:"open"`
    Architecture *ModelArchitecture `json:"architecture,omitempty" yaml:"architecture,omitempty"`
}

type ModelDelivery

ModelDelivery represents technical response delivery capabilities.

type ModelDelivery struct {
    // Response delivery mechanisms
    Protocols []ModelResponseProtocol `json:"protocols,omitempty" yaml:"protocols,omitempty"` // Supported delivery protocols (HTTP, gRPC, etc.)
    Streaming []ModelStreaming        `json:"streaming,omitempty" yaml:"streaming,omitempty"` // Supported streaming modes (sse, websocket, chunked)
    Formats   []ModelResponseFormat   `json:"formats,omitempty" yaml:"formats,omitempty"`     // Available response formats (if format_response feature enabled)
}

type ModelFeatures

ModelFeatures represents a set of feature flags that describe what a model can do.

type ModelFeatures struct {
    // Input/Output modalities
    Modalities ModelModalities `json:"modalities" yaml:"modalities"` // Supported input/output modalities

    // Core capabilities
    // Tool calling system - three distinct aspects:
    ToolCalls   bool `json:"tool_calls" yaml:"tool_calls"`   // Can invoke/call tools in responses (model outputs tool_calls)
    Tools       bool `json:"tools" yaml:"tools"`             // Accepts tool definitions in requests (accepts tools parameter)
    ToolChoice  bool `json:"tool_choice" yaml:"tool_choice"` // Supports tool choice strategies (auto/none/required control)
    WebSearch   bool `json:"web_search" yaml:"web_search"`   // Supports web search capabilities
    Attachments bool `json:"attachments" yaml:"attachments"` // Attachment support details

    // Reasoning & Verbosity
    Reasoning        bool `json:"reasoning" yaml:"reasoning"`                 // Supports basic reasoning
    ReasoningEffort  bool `json:"reasoning_effort" yaml:"reasoning_effort"`   // Supports configurable reasoning intensity
    ReasoningTokens  bool `json:"reasoning_tokens" yaml:"reasoning_tokens"`   // Supports specific reasoning token allocation
    IncludeReasoning bool `json:"include_reasoning" yaml:"include_reasoning"` // Supports including reasoning traces in response
    Verbosity        bool `json:"verbosity" yaml:"verbosity"`                 // Supports verbosity control (GPT-5+)

    // Generation control - Core sampling and decoding
    Temperature bool `json:"temperature" yaml:"temperature"` // [Core] Supports temperature parameter
    TopP        bool `json:"top_p" yaml:"top_p"`             // [Core] Supports top_p parameter (nucleus sampling)
    TopK        bool `json:"top_k" yaml:"top_k"`             // [Advanced] Supports top_k parameter
    TopA        bool `json:"top_a" yaml:"top_a"`             // [Advanced] Supports top_a parameter (top-a sampling)
    MinP        bool `json:"min_p" yaml:"min_p"`             // [Advanced] Supports min_p parameter (minimum probability threshold)
    TypicalP    bool `json:"typical_p" yaml:"typical_p"`     // [Advanced] Supports typical_p parameter (typical sampling)
    TFS         bool `json:"tfs" yaml:"tfs"`                 // [Advanced] Supports tail free sampling

    // Generation control - Length and termination
    MaxTokens       bool `json:"max_tokens" yaml:"max_tokens"`               // [Core] Supports max_tokens parameter
    MaxOutputTokens bool `json:"max_output_tokens" yaml:"max_output_tokens"` // [Core] Supports max_output_tokens parameter (some providers distinguish from max_tokens)
    Stop            bool `json:"stop" yaml:"stop"`                           // [Core] Supports stop sequences/words
    StopTokenIDs    bool `json:"stop_token_ids" yaml:"stop_token_ids"`       // [Advanced] Supports stop token IDs (numeric)

    // Generation control - Repetition control
    FrequencyPenalty  bool `json:"frequency_penalty" yaml:"frequency_penalty"`       // [Core] Supports frequency penalty
    PresencePenalty   bool `json:"presence_penalty" yaml:"presence_penalty"`         // [Core] Supports presence penalty
    RepetitionPenalty bool `json:"repetition_penalty" yaml:"repetition_penalty"`     // [Advanced] Supports repetition penalty
    NoRepeatNgramSize bool `json:"no_repeat_ngram_size" yaml:"no_repeat_ngram_size"` // [Niche] Supports n-gram repetition blocking
    LengthPenalty     bool `json:"length_penalty" yaml:"length_penalty"`             // [Niche] Supports length penalty (seq2seq style)

    // Generation control - Token biasing
    LogitBias     bool `json:"logit_bias" yaml:"logit_bias"`         // [Core] Supports token-level bias adjustment
    BadWords      bool `json:"bad_words" yaml:"bad_words"`           // [Advanced] Supports bad words/disallowed tokens
    AllowedTokens bool `json:"allowed_tokens" yaml:"allowed_tokens"` // [Niche] Supports token whitelist

    // Generation control - Determinism
    Seed bool `json:"seed" yaml:"seed"` // [Advanced] Supports deterministic seeding

    // Generation control - Observability
    Logprobs    bool `json:"logprobs" yaml:"logprobs"`         // [Core] Supports returning log probabilities
    TopLogprobs bool `json:"top_logprobs" yaml:"top_logprobs"` // [Core] Supports returning top N log probabilities
    Echo        bool `json:"echo" yaml:"echo"`                 // [Advanced] Supports echoing prompt with completion

    // Generation control - Multiplicity and reranking
    N      bool `json:"n" yaml:"n"`             // [Advanced] Supports generating multiple candidates
    BestOf bool `json:"best_of" yaml:"best_of"` // [Advanced] Supports server-side sampling with best selection

    // Generation control - Alternative sampling strategies (niche)
    Mirostat                      bool `json:"mirostat" yaml:"mirostat"`                                                 // [Niche] Supports Mirostat sampling
    MirostatTau                   bool `json:"mirostat_tau" yaml:"mirostat_tau"`                                         // [Niche] Supports Mirostat tau parameter
    MirostatEta                   bool `json:"mirostat_eta" yaml:"mirostat_eta"`                                         // [Niche] Supports Mirostat eta parameter
    ContrastiveSearchPenaltyAlpha bool `json:"contrastive_search_penalty_alpha" yaml:"contrastive_search_penalty_alpha"` // [Niche] Supports contrastive decoding

    // Generation control - Beam search (niche)
    NumBeams         bool `json:"num_beams" yaml:"num_beams"`                 // [Niche] Supports beam search
    EarlyStopping    bool `json:"early_stopping" yaml:"early_stopping"`       // [Niche] Supports early stopping in beam search
    DiversityPenalty bool `json:"diversity_penalty" yaml:"diversity_penalty"` // [Niche] Supports diversity penalty in beam search

    // Response delivery
    FormatResponse    bool `json:"format_response" yaml:"format_response"`       // Supports alternative response formats (beyond text)
    StructuredOutputs bool `json:"structured_outputs" yaml:"structured_outputs"` // Supports structured outputs (JSON schema validation)
    Streaming         bool `json:"streaming" yaml:"streaming"`                   // Supports response streaming

}

type ModelGeneration

ModelGeneration - core chat completions generation controls.

type ModelGeneration struct {
    // Core sampling and decoding
    Temperature *FloatRange `json:"temperature,omitempty" yaml:"temperature,omitempty"`
    TopP        *FloatRange `json:"top_p,omitempty" yaml:"top_p,omitempty"`
    TopK        *IntRange   `json:"top_k,omitempty" yaml:"top_k,omitempty"`
    TopA        *FloatRange `json:"top_a,omitempty" yaml:"top_a,omitempty"`
    MinP        *FloatRange `json:"min_p,omitempty" yaml:"min_p,omitempty"`
    TypicalP    *FloatRange `json:"typical_p,omitempty" yaml:"typical_p,omitempty"`
    TFS         *FloatRange `json:"tfs,omitempty" yaml:"tfs,omitempty"`

    // Length and termination
    MaxTokens       *int `json:"max_tokens,omitempty" yaml:"max_tokens,omitempty"`
    MaxOutputTokens *int `json:"max_output_tokens,omitempty" yaml:"max_output_tokens,omitempty"`

    // Repetition control
    FrequencyPenalty  *FloatRange `json:"frequency_penalty,omitempty" yaml:"frequency_penalty,omitempty"`
    PresencePenalty   *FloatRange `json:"presence_penalty,omitempty" yaml:"presence_penalty,omitempty"`
    RepetitionPenalty *FloatRange `json:"repetition_penalty,omitempty" yaml:"repetition_penalty,omitempty"`
    NoRepeatNgramSize *IntRange   `json:"no_repeat_ngram_size,omitempty" yaml:"no_repeat_ngram_size,omitempty"`
    LengthPenalty     *FloatRange `json:"length_penalty,omitempty" yaml:"length_penalty,omitempty"`

    // Observability
    TopLogprobs *int `json:"top_logprobs,omitempty" yaml:"top_logprobs,omitempty"` // Number of top log probabilities to return

    // Multiplicity and reranking
    N      *IntRange `json:"n,omitempty" yaml:"n,omitempty"`             // Number of candidates to generate
    BestOf *IntRange `json:"best_of,omitempty" yaml:"best_of,omitempty"` // Server-side sampling with best selection

    // Alternative sampling strategies (niche)
    MirostatTau                   *FloatRange `json:"mirostat_tau,omitempty" yaml:"mirostat_tau,omitempty"`
    MirostatEta                   *FloatRange `json:"mirostat_eta,omitempty" yaml:"mirostat_eta,omitempty"`
    ContrastiveSearchPenaltyAlpha *FloatRange `json:"contrastive_search_penalty_alpha,omitempty" yaml:"contrastive_search_penalty_alpha,omitempty"`

    // Beam search (niche)
    NumBeams         *IntRange   `json:"num_beams,omitempty" yaml:"num_beams,omitempty"`
    DiversityPenalty *FloatRange `json:"diversity_penalty,omitempty" yaml:"diversity_penalty,omitempty"`
}

type ModelLimits

ModelLimits represents the limits for a model.

type ModelLimits struct {
    ContextWindow int64 `json:"context_window" yaml:"context_window"` // Context window size in tokens
    InputTokens   int64 `json:"input_tokens" yaml:"input_tokens"`     // Maximum input tokens
    OutputTokens  int64 `json:"output_tokens" yaml:"output_tokens"`   // Maximum output tokens
}

type ModelLineage

ModelLineage represents model family and derivation metadata.

type ModelLineage struct {
    Family string  `json:"family,omitempty" yaml:"family,omitempty"` // Model family or series, such as gpt-5 or claude
    Root   *string `json:"root,omitempty" yaml:"root,omitempty"`     // Root/base model ID reported by a provider
    Parent *string `json:"parent,omitempty" yaml:"parent,omitempty"` // Parent model ID for derived/fine-tuned models
}

type ModelMetadata

ModelMetadata represents the metadata for a model.

type ModelMetadata struct {
    ReleaseDate     utc.Time           `json:"release_date" yaml:"release_date"`                             // Release date (YYYY-MM or YYYY-MM-DD format)
    OpenWeights     bool               `json:"open_weights" yaml:"open_weights"`                             // Whether model weights are open
    KnowledgeCutoff *utc.Time          `json:"knowledge_cutoff,omitempty" yaml:"knowledge_cutoff,omitempty"` // Knowledge cutoff date (YYYY-MM or YYYY-MM-DD format)
    Tags            []ModelTag         `json:"tags,omitempty" yaml:"tags,omitempty"`                         // Use case tags for categorizing the model
    Architecture    *ModelArchitecture `json:"architecture,omitempty" yaml:"architecture,omitempty"`         // Technical architecture details
}

type ModelModalities

ModelModalities represents the input/output modalities supported by a model.

type ModelModalities struct {
    Input  []ModelModality `json:"input" yaml:"input"`   // Supported input modalities
    Output []ModelModality `json:"output" yaml:"output"` // Supported output modalities
}

type ModelModality

ModelModality represents a supported input or output modality for AI models.

type ModelModality string

Supported model modalities.

const (
    ModelModalityText      ModelModality = "text"
    ModelModalityAudio     ModelModality = "audio"
    ModelModalityImage     ModelModality = "image"
    ModelModalityVideo     ModelModality = "video"
    ModelModalityPDF       ModelModality = "pdf"
    ModelModalityEmbedding ModelModality = "embedding" // Vector embeddings
)

func (ModelModality) String
func (m ModelModality) String() string

String returns the string representation of a ModelModality.

type ModelMode

ModelMode represents an alternate provider service mode for a model.

type ModelMode struct {
    Pricing  *ModelPricing      `json:"pricing,omitempty" yaml:"pricing,omitempty"`   // Mode-specific pricing
    Provider *ModelProviderMode `json:"provider,omitempty" yaml:"provider,omitempty"` // Mode-specific provider request overrides
}

type ModelOperationPricing

ModelOperationPricing represents fixed costs for operations.

type ModelOperationPricing struct {
    // Core operations
    Request *float64 `json:"request,omitempty" yaml:"request,omitempty"` // Cost per API request

    // Media operations
    ImageInput *float64 `json:"image_input,omitempty" yaml:"image_input,omitempty"` // Cost per image processed
    AudioInput *float64 `json:"audio_input,omitempty" yaml:"audio_input,omitempty"` // Cost per audio input
    VideoInput *float64 `json:"video_input,omitempty" yaml:"video_input,omitempty"` // Cost per video input

    // Generation operations
    ImageGen *float64 `json:"image_gen,omitempty" yaml:"image_gen,omitempty"` // Cost per image generated
    AudioGen *float64 `json:"audio_gen,omitempty" yaml:"audio_gen,omitempty"` // Cost per audio generated
    VideoGen *float64 `json:"video_gen,omitempty" yaml:"video_gen,omitempty"` // Cost per video generated

    // Service operations
    WebSearch    *float64 `json:"web_search,omitempty" yaml:"web_search,omitempty"`       // Cost per web search
    FunctionCall *float64 `json:"function_call,omitempty" yaml:"function_call,omitempty"` // Cost per function call
    ToolUse      *float64 `json:"tool_use,omitempty" yaml:"tool_use,omitempty"`           // Cost per tool usage
}

type ModelPricing

ModelPricing represents the pricing structure for a model.

type ModelPricing struct {
    // Token-based costs
    Tokens *ModelTokenPricing `json:"tokens,omitempty" yaml:"tokens,omitempty"`

    // Fixed costs per operation
    Operations *ModelOperationPricing `json:"operations,omitempty" yaml:"operations,omitempty"`

    // Conditional/tiered pricing
    Tiers []ModelPricingTier `json:"tiers,omitempty" yaml:"tiers,omitempty"`

    // Metadata
    Currency ModelPricingCurrency `json:"currency" yaml:"currency"` // "USD", "EUR", etc.

    // Optional half-open validity interval [effective_from, effective_until).
    EffectiveFrom  *utc.Time `json:"effective_from,omitempty" yaml:"effective_from,omitempty"`
    EffectiveUntil *utc.Time `json:"effective_until,omitempty" yaml:"effective_until,omitempty"`
}

func (*ModelPricing) IsEffectiveAt
func (p *ModelPricing) IsEffectiveAt(at time.Time) bool

IsEffectiveAt reports whether pricing applies at the supplied instant.

func (*ModelPricing) Validate
func (p *ModelPricing) Validate() error

Validate verifies that pricing is structurally complete and financially safe to use as an authoritative provider-offering observation.

type ModelPricingCurrency

ModelPricingCurrency represents a currency code for model pricing.

type ModelPricingCurrency string


const (
    // ModelPricingCurrencyUSD is the US Dollar currency constant.
    ModelPricingCurrencyUSD ModelPricingCurrency = "USD" // US Dollar
    // ModelPricingCurrencyEUR is the Euro currency constant.
    ModelPricingCurrencyEUR ModelPricingCurrency = "EUR" // Euro
    // ModelPricingCurrencyJPY is the Japanese Yen currency constant.
    ModelPricingCurrencyJPY ModelPricingCurrency = "JPY" // Japanese Yen
    // ModelPricingCurrencyGBP is the British Pound Sterling currency constant.
    ModelPricingCurrencyGBP ModelPricingCurrency = "GBP" // British Pound Sterling
    // ModelPricingCurrencyAUD is the Australian Dollar currency constant.
    ModelPricingCurrencyAUD ModelPricingCurrency = "AUD" // Australian Dollar
    // ModelPricingCurrencyCAD is the Canadian Dollar currency constant.
    ModelPricingCurrencyCAD ModelPricingCurrency = "CAD" // Canadian Dollar
    // ModelPricingCurrencyCNY is the Chinese Yuan currency constant.
    ModelPricingCurrencyCNY ModelPricingCurrency = "CNY" // Chinese Yuan
    // ModelPricingCurrencyNZD is the New Zealand Dollar currency constant.
    ModelPricingCurrencyNZD ModelPricingCurrency = "NZD" // New Zealand Dollar
)

func (ModelPricingCurrency) String
func (m ModelPricingCurrency) String() string

String returns the string representation of a ModelPricingCurrency.

func (ModelPricingCurrency) Symbol
func (m ModelPricingCurrency) Symbol() string

Symbol returns the symbol for a given currency.

type ModelPricingTier

ModelPricingTier represents conditional pricing for a model.

type ModelPricingTier struct {
    Name       string                 `json:"name,omitempty" yaml:"name,omitempty"`             // Optional source/name, such as context_over_200k
    Type       ModelPricingTierType   `json:"type" yaml:"type"`                                 // Tier dimension, such as context
    Size       int64                  `json:"size,omitempty" yaml:"size,omitempty"`             // Threshold size for the tier dimension
    Tokens     *ModelTokenPricing     `json:"tokens,omitempty" yaml:"tokens,omitempty"`         // Token prices in this tier
    Operations *ModelOperationPricing `json:"operations,omitempty" yaml:"operations,omitempty"` // Operation prices in this tier
}

type ModelPricingTierType

ModelPricingTierType represents the dimension that activates a pricing tier.

type ModelPricingTierType string


const (
    // ModelPricingTierTypeContext means the tier applies above a context-size threshold.
    ModelPricingTierTypeContext ModelPricingTierType = "context"
)

func (ModelPricingTierType) String
func (m ModelPricingTierType) String() string

String returns the string representation of a ModelPricingTierType.

type ModelProviderMode

ModelProviderMode represents provider request overrides for a model mode.

type ModelProviderMode struct {
    Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"` // HTTP headers required by this mode
    Body    map[string]any    `json:"body,omitempty" yaml:"body,omitempty"`       // JSON request body fields required by this mode
}

type ModelResponseFormat

ModelResponseFormat represents a supported response format.

type ModelResponseFormat string

Model response formats.

const (
    // Basic formats.
    ModelResponseFormatText ModelResponseFormat = "text" // Plain text responses (default)

    // JSON formats.
    ModelResponseFormatJSON       ModelResponseFormat = "json"        // JSON encouraged via prompting
    ModelResponseFormatJSONMode   ModelResponseFormat = "json_mode"   // Forced valid JSON (OpenAI style)
    ModelResponseFormatJSONObject ModelResponseFormat = "json_object" // Same as json_mode (OpenAI API name)

    // Structured formats.
    ModelResponseFormatJSONSchema       ModelResponseFormat = "json_schema"       // Schema-validated JSON (OpenAI structured output)
    ModelResponseFormatStructuredOutput ModelResponseFormat = "structured_output" // General structured output support

    // Function calling (alternative to JSON schema).
    ModelResponseFormatFunctionCall ModelResponseFormat = "function_call" // Tool/function calling for structured data
)

func (ModelResponseFormat) String
func (mrf ModelResponseFormat) String() string

String returns the string representation of a ModelResponseFormat.

type ModelResponseProtocol

ModelResponseProtocol represents a supported delivery protocol.

type ModelResponseProtocol string

Model delivery protocols.

const (
    ModelResponseProtocolHTTP      ModelResponseProtocol = "http"      // HTTP/HTTPS REST API
    ModelResponseProtocolGRPC      ModelResponseProtocol = "grpc"      // gRPC protocol
    ModelResponseProtocolWebSocket ModelResponseProtocol = "websocket" // WebSocket protocol
)

type ModelStatus

ModelStatus represents a model lifecycle or availability state.

type ModelStatus string

Model lifecycle states.

const (
    ModelStatusActive     ModelStatus = "active"
    ModelStatusBeta       ModelStatus = "beta"
    ModelStatusPreview    ModelStatus = "preview"
    ModelStatusDeprecated ModelStatus = "deprecated"
    ModelStatusUnknown    ModelStatus = "unknown"
)

func (ModelStatus) String
func (ms ModelStatus) String() string

String returns the string representation of a ModelStatus.

type ModelStreaming

ModelStreaming represents how responses can be delivered.

type ModelStreaming string

Model streaming modes.

const (
    ModelStreamingSSE       ModelStreaming = "sse"       // Server-Sent Events streaming
    ModelStreamingWebSocket ModelStreaming = "websocket" // WebSocket streaming
    ModelStreamingChunked   ModelStreaming = "chunked"   // HTTP chunked transfer encoding
)

func (ModelStreaming) String
func (ms ModelStreaming) String() string

String returns the string representation of a ModelStreaming.

type ModelTag

ModelTag represents a use case or category tag for models.

type ModelTag string

Model tags for categorizing models by use case and capabilities.

const (
    // Core Use Cases.
    ModelTagCoding    ModelTag = "coding"    // Programming and code generation
    ModelTagWriting   ModelTag = "writing"   // Creative and technical writing
    ModelTagReasoning ModelTag = "reasoning" // Logical reasoning and problem solving
    ModelTagMath      ModelTag = "math"      // Mathematical problem solving
    ModelTagChat      ModelTag = "chat"      // Conversational AI
    ModelTagInstruct  ModelTag = "instruct"  // Instruction following
    ModelTagResearch  ModelTag = "research"  // Research and analysis
    ModelTagCreative  ModelTag = "creative"  // Creative content generation
    ModelTagRoleplay  ModelTag = "roleplay"  // Character roleplay and simulation

    // Technical Capabilities.
    ModelTagFunctionCalling ModelTag = "function_calling"   // Tool/function calling
    ModelTagEmbedding       ModelTag = "embedding"          // Text embeddings
    ModelTagSummarization   ModelTag = "summarization"      // Text summarization
    ModelTagTranslation     ModelTag = "translation"        // Language translation
    ModelTagQA              ModelTag = "question_answering" // Question answering

    // Modality-Specific.
    ModelTagVision       ModelTag = "vision"         // Computer vision
    ModelTagMultimodal   ModelTag = "multimodal"     // Multiple input modalities
    ModelTagAudio        ModelTag = "audio"          // Audio processing
    ModelTagTextToImage  ModelTag = "text_to_image"  // Text-to-image generation
    ModelTagTextToSpeech ModelTag = "text_to_speech" // Text-to-speech synthesis
    ModelTagSpeechToText ModelTag = "speech_to_text" // Speech recognition
    ModelTagImageToText  ModelTag = "image_to_text"  // Image captioning/OCR

    // Domain-Specific.
    ModelTagMedical   ModelTag = "medical"   // Medical and healthcare
    ModelTagLegal     ModelTag = "legal"     // Legal document processing
    ModelTagFinance   ModelTag = "finance"   // Financial analysis
    ModelTagScience   ModelTag = "science"   // Scientific applications
    ModelTagEducation ModelTag = "education" // Educational content
)

func (ModelTag) String
func (tag ModelTag) String() string

String returns the string representation of a ModelTag.

type ModelTokenCachePricing

ModelTokenCachePricing represents cache-specific pricing.

type ModelTokenCachePricing struct {
    Read  *ModelTokenCost `json:"read,omitempty" yaml:"read,omitempty"`   // Cache read costs
    Write *ModelTokenCost `json:"write,omitempty" yaml:"write,omitempty"` // Cache write costs
}

type ModelTokenCost

ModelTokenCost represents cost per token with flexible units.

type ModelTokenCost struct {
    PerToken float64 `json:"per_token" yaml:"per_token"`  // Cost per individual token
    Per1M    float64 `json:"per_1m_tokens" yaml:"per_1m"` // Cost per 1M tokens
}

func (*ModelTokenCost) MarshalYAML
func (t *ModelTokenCost) MarshalYAML() (any, error)

MarshalYAML implements custom YAML marshaling for TokenCost to format decimals consistently.

type ModelTokenPricing

ModelTokenPricing represents all token-based costs.

type ModelTokenPricing struct {
    // Core tokens
    Input  *ModelTokenCost `json:"input,omitempty" yaml:"input,omitempty"`   // Input/prompt tokens
    Output *ModelTokenCost `json:"output,omitempty" yaml:"output,omitempty"` // Standard output tokens

    // Advanced token types
    Reasoning *ModelTokenCost         `json:"reasoning,omitempty" yaml:"reasoning,omitempty"` // Internal reasoning tokens
    Cache     *ModelTokenCachePricing `json:"cache,omitempty" yaml:"cache,omitempty"`         // Cache operations

    // Alternative flat cache structure (for backward compatibility)
    CacheRead  *ModelTokenCost `json:"cache_read,omitempty" yaml:"cache_read,omitempty"`   // Cache read costs (flat structure)
    CacheWrite *ModelTokenCost `json:"cache_write,omitempty" yaml:"cache_write,omitempty"` // Cache write costs (flat structure)
}

func (*ModelTokenPricing) MarshalYAML
func (t *ModelTokenPricing) MarshalYAML() (any, error)

MarshalYAML implements custom YAML marshaling for TokenPricing to use flat cache structure.

type ModelTools

ModelTools represents external tool and capability integrations.

type ModelTools struct {
    // Tool calling configuration
    // Specifies which tool choice strategies this model supports.
    // Requires both Tools=true and ToolChoice=true in ModelFeatures.
    // Common values: ["auto"], ["auto", "none"], ["auto", "none", "required"]
    ToolChoices []ToolChoice `json:"tool_choices,omitempty" yaml:"tool_choices,omitempty"` // Supported tool choice strategies

    // Web search configuration
    // Only applicable if WebSearch=true in ModelFeatures
    WebSearch *ModelWebSearch `json:"web_search,omitempty" yaml:"web_search,omitempty"`
}

type ModelWebSearch

ModelWebSearch represents web search configuration for search-enabled models.

type ModelWebSearch struct {
    // Plugin-based web search options (for models using OpenRouter's web plugin)
    MaxResults   *int    `json:"max_results,omitempty" yaml:"max_results,omitempty"`     // Maximum number of search results (defaults to 5)
    SearchPrompt *string `json:"search_prompt,omitempty" yaml:"search_prompt,omitempty"` // Custom prompt for search results

    // Built-in web search options (for models with native web search like GPT-4.1, Perplexity)
    SearchContextSizes []ModelControlLevel `json:"search_context_sizes,omitempty" yaml:"search_context_sizes,omitempty"` // Supported context sizes (low, medium, high)
    DefaultContextSize *ModelControlLevel  `json:"default_context_size,omitempty" yaml:"default_context_size,omitempty"` // Default search context size
}

type Models

Models is a concurrent safe map of models.

type Models struct {
    // contains filtered or unexported fields
}

func NewModels
func NewModels() *Models

NewModels creates a new Models instance.

func (*Models) Add
func (m *Models) Add(model *Model) error

Add adds a model, returning an error if it already exists.

func (*Models) AddBatch
func (m *Models) AddBatch(models []*Model) map[string]error

AddBatch adds multiple models in a single operation. Only adds models that don't already exist - fails if a model ID already exists. Returns a map of model IDs to errors for any failed additions.

func (*Models) Clear
func (m *Models) Clear()

Clear removes all models.

func (*Models) Delete
func (m *Models) Delete(id string) error

Delete removes a model by id. Returns an error if the model doesn't exist.

func (*Models) DeleteBatch
func (m *Models) DeleteBatch(ids []string) map[string]error

DeleteBatch removes multiple models by their IDs. Returns a map of errors for models that couldn't be deleted (not found).

func (*Models) Exists
func (m *Models) Exists(id string) bool

Exists checks if a model exists without returning it.

func (*Models) ForEach
func (m *Models) ForEach(fn func(id string, model *Model) bool)

ForEach applies a function to each model. The function should not modify the model. If the function returns false, iteration stops early.

func (*Models) Get
func (m *Models) Get(id string) (*Model, bool)

Get returns a model by id and whether it exists.

func (*Models) Len
func (m *Models) Len() int

Len returns the number of models.

func (*Models) List
func (m *Models) List() []Model

List returns a slice of all models as values (copies).

func (*Models) Map
func (m *Models) Map() map[string]*Model

Map returns a copy of all models.

func (*Models) Set
func (m *Models) Set(id string, model *Model) error

Set sets a model by id. Returns an error if model is nil.

func (*Models) SetBatch
func (m *Models) SetBatch(models map[string]*Model) error

SetBatch sets multiple models in a single operation. Overwrites existing models or adds new ones (upsert behavior). Returns an error if any model is nil.

type ModelsReader

ModelsReader exposes model collection reads without mutation methods.

type ModelsReader interface {
    Get(string) (*Model, bool)
    Exists(string) bool
    Len() int
    List() []Model
    Map() map[string]*Model
    ForEach(func(string, *Model) bool)
}

type OfferingAvailability

OfferingAvailability describes whether an offering can currently be used.

type OfferingAvailability string


const (
    // OfferingAvailabilityAvailable means the offering is generally available.
    OfferingAvailabilityAvailable OfferingAvailability = "available"
    // OfferingAvailabilityRestricted means access depends on region, account, or allowlisting.
    OfferingAvailabilityRestricted OfferingAvailability = "restricted"
    // OfferingAvailabilityUnavailable means the provider does not currently serve the offering.
    OfferingAvailabilityUnavailable OfferingAvailability = "unavailable"
)

type OfferingKey

OfferingKey is the globally unique identity of a provider model offering.

type OfferingKey struct {
    ProviderID      ProviderID      `json:"provider_id" yaml:"provider_id"`
    ProviderModelID ProviderModelID `json:"provider_model_id" yaml:"provider_model_id"`
}

type OfferingLifecycle

OfferingLifecycle describes the provider-specific lifecycle of an offering.

type OfferingLifecycle string


const (
    // OfferingLifecycleActive means the offering is supported for production use.
    OfferingLifecycleActive OfferingLifecycle = "active"
    // OfferingLifecyclePreview means the offering is preview or beta quality.
    OfferingLifecyclePreview OfferingLifecycle = "preview"
    // OfferingLifecycleDeprecated means callers should migrate away from the offering.
    OfferingLifecycleDeprecated OfferingLifecycle = "deprecated"
    // OfferingLifecycleRetired means the provider no longer accepts new requests.
    OfferingLifecycleRetired OfferingLifecycle = "retired"
)

type OfferingRequestBody

OfferingRequestBody is a typed set of exact JSON request-body values. RawMessage preserves booleans, numbers, strings, arrays, objects, and null without routing values through map[string]any.

type OfferingRequestBody map[string]json.RawMessage

type OfferingRequestHeaders

OfferingRequestHeaders is a typed set of provider request header overrides.

type OfferingRequestHeaders map[string]string

type Option

Option configures a catalog.

type Option func(*options)

func WithEmbedded
func WithEmbedded() Option

WithEmbedded configures the catalog to use embedded files.

func WithFS
func WithFS(fsys fs.FS) Option

WithFS configures the catalog to use a custom fs.FS for reading.

func WithMergeStrategy
func WithMergeStrategy(strategy MergeStrategy) Option

WithMergeStrategy sets the default merge strategy.

func WithPath
func WithPath(path string) Option

WithPath configures the catalog to use a directory path for reading This creates an os.DirFS under the hood.

func WithWritePath
func WithWritePath(path string) Option

WithWritePath sets a specific path for writing catalog files.

type PayloadDescriptor

PayloadDescriptor binds a generation manifest to exact immutable bytes.

type PayloadDescriptor struct {
    Checksum  string `json:"checksum" yaml:"checksum"`
    SizeBytes int64  `json:"size_bytes" yaml:"size_bytes"`
    MediaType string `json:"media_type" yaml:"media_type"`
}

func DescribeCatalogPayload
func DescribeCatalogPayload(payload []byte) PayloadDescriptor

DescribeCatalogPayload returns the descriptor for canonical catalog bytes.

func (PayloadDescriptor) Verify
func (d PayloadDescriptor) Verify(payload []byte) error

Verify checks that payload exactly matches the descriptor.

type Provenance

Provenance is a concurrent-safe container for provenance data. It follows the same pattern as Authors, Models, and Providers containers, using RWMutex for thread safety and returning deep copies to prevent external modification.

type Provenance struct {
    // contains filtered or unexported fields
}

func NewProvenance
func NewProvenance(opts ...ProvenanceOption) *Provenance

NewProvenance creates a new Provenance container with optional configuration.

func (*Provenance) Clear
func (p *Provenance) Clear()

Clear removes all provenance data.

func (*Provenance) EncodeYAML
func (p *Provenance) EncodeYAML() (string, error)

EncodeYAML returns provenance YAML or a typed parse error when evidence values cannot be represented safely.

func (*Provenance) FindByField
func (p *Provenance) FindByField(resourceType catalogmeta.ResourceType, resourceID string, field string) []provenance.Provenance

FindByField retrieves provenance for a specific field of a resource. Returns nil if no provenance is found.

func (*Provenance) FindByResource
func (p *Provenance) FindByResource(resourceType catalogmeta.ResourceType, resourceID string) map[string][]provenance.Provenance

FindByResource retrieves all provenance for a resource. Returns a map of field names to their provenance entries.

func (*Provenance) FormatYAML
func (p *Provenance) FormatYAML() string

FormatYAML returns the provenance data formatted as YAML. This follows the same pattern as Authors and Providers containers.

func (*Provenance) Len
func (p *Provenance) Len() int

Len returns the number of provenance entries.

func (*Provenance) Map
func (p *Provenance) Map() provenance.Map

Map returns a deep copy of the provenance map. This ensures thread safety by preventing external modification of internal state.

func (*Provenance) Merge
func (p *Provenance) Merge(m provenance.Map)

Merge adds new provenance entries to existing data. This appends to existing keys rather than replacing them.

func (*Provenance) Set
func (p *Provenance) Set(m provenance.Map)

Set replaces the entire provenance map with new data. The input map is deep copied to prevent external modification.

type ProvenanceOption

ProvenanceOption defines a function that configures a Provenance instance.

type ProvenanceOption func(*Provenance)

type ProvenanceReader

ProvenanceReader exposes provenance reads without mutation methods.

type ProvenanceReader interface {
    Map() provenance.Map
    Len() int
    FindByField(catalogmeta.ResourceType, string, string) []provenance.Provenance
    FindByResource(catalogmeta.ResourceType, string) map[string][]provenance.Provenance
    FormatYAML() string
}

type Provider

Provider represents a provider configuration.

type Provider struct {
    // Core identification and integration
    ID           ProviderID   `json:"id" yaml:"id"`                                         // Unique provider identifier
    Aliases      []ProviderID `json:"aliases,omitempty" yaml:"aliases,omitempty"`           // Alternative IDs this provider is known by (e.g., in models.dev)
    Name         string       `json:"name" yaml:"name"`                                     // Display name (must not be empty)
    Headquarters *string      `json:"headquarters,omitempty" yaml:"headquarters,omitempty"` // Company headquarters location
    IconURL      *string      `json:"icon_url,omitempty" yaml:"icon_url,omitempty"`         // Provider icon/logo URL

    // API key configuration
    APIKey *ProviderAPIKey `json:"api_key,omitempty" yaml:"api_key,omitempty"` // API key configuration

    // Environment variables configuration
    EnvVars []ProviderEnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"` // Required environment variables

    // Models
    Catalog *ProviderCatalog  `json:"catalog,omitempty" yaml:"catalog,omitempty"` // Models catalog configuration
    Models  map[string]*Model `json:"-" yaml:"-"`                                 // Available models indexed by model ID - not serialized to YAML

    // Status & Health
    StatusPageURL   *string                  `json:"status_page_url,omitempty" yaml:"status_page_url,omitempty"`   // Link to service status page
    ChatCompletions *ProviderChatCompletions `json:"chat_completions,omitempty" yaml:"chat_completions,omitempty"` // Chat completions API configuration

    // Privacy, Retention, and Governance Policies
    PrivacyPolicy    *ProviderPrivacyPolicy    `json:"privacy_policy,omitempty" yaml:"privacy_policy,omitempty"`       // Data collection and usage practices
    RetentionPolicy  *ProviderRetentionPolicy  `json:"retention_policy,omitempty" yaml:"retention_policy,omitempty"`   // Data retention and deletion practices
    GovernancePolicy *ProviderGovernancePolicy `json:"governance_policy,omitempty" yaml:"governance_policy,omitempty"` // Oversight and moderation practices

    // Extensions - controlled source-specific fields that are not canonical schema
    Extensions SourceExtensions `json:"extensions,omitempty" yaml:"extensions,omitempty"`

    EnvVarValues map[string]string `json:"-" yaml:"-"` // Actual environment variable values loaded at runtime
    // contains filtered or unexported fields
}

func DeepCopyProvider
func DeepCopyProvider(provider Provider) Provider

DeepCopyProvider creates a deep copy of a Provider including its Models map.

func TestProvider
func TestProvider(t testing.TB) *Provider

TestProvider creates a test provider with sensible defaults. The t.Helper() call ensures stack traces point to the test, not this function.

func TestProviderWithOptions
func TestProviderWithOptions(t testing.TB, opts ...TestProviderOption) *Provider

TestProviderWithOptions creates a test provider with custom options.

func (*Provider) APIKeyValue
func (p *Provider) APIKeyValue() (string, error)

APIKeyValue retrieves and validates the API key for this provider. Uses the loaded apiKeyValue if available, otherwise falls back to environment.

func (*Provider) CatalogEndpointURL
func (p *Provider) CatalogEndpointURL() string

CatalogEndpointURL returns the resolved model catalog endpoint URL.

func (*Provider) EnvVar
func (p *Provider) EnvVar(name string) string

EnvVar returns the value of a specific environment variable.

func (*Provider) HasAPIKey
func (p *Provider) HasAPIKey() bool

HasAPIKey checks if the provider has a valid API key configured. This checks both existence and validation (pattern matching).

func (*Provider) HasRequiredEnvVars
func (p *Provider) HasRequiredEnvVars() bool

HasRequiredEnvVars checks if all required environment variables are set.

func (*Provider) IsAPIKeyRequired
func (p *Provider) IsAPIKeyRequired() bool

IsAPIKeyRequired checks if a provider requires an API key.

func (*Provider) LoadAPIKey
func (p *Provider) LoadAPIKey()

LoadAPIKey loads the API key value from environment into the provider. This should be called when the provider is loaded from the catalog.

func (*Provider) LoadEnvVars
func (p *Provider) LoadEnvVars()

LoadEnvVars loads environment variable values from the system into the provider. This should be called when the provider is loaded from the catalog.

func (*Provider) MissingRequiredEnvVars
func (p *Provider) MissingRequiredEnvVars() []string

MissingRequiredEnvVars returns a list of required environment variables that are not set.

func (*Provider) Model
func (p *Provider) Model(modelID string) (*Model, error)

Model retrieves a specific model from the provider.

func (*Provider) Validate
func (p *Provider) Validate(supportedProviders map[ProviderID]bool) ProviderValidationResult

Validate performs validation checks on this provider and returns the result. The supportedProviders parameter is a set of provider IDs that have client implementations.

type ProviderAPIKey

ProviderAPIKey represents configuration for an API key to access a provider's catalog.

type ProviderAPIKey struct {
    Name       string               `json:"name" yaml:"name"`               // Name of the API key parameter
    Pattern    string               `json:"pattern" yaml:"pattern"`         // Glob pattern to match the API key
    Header     string               `json:"header" yaml:"header"`           // Header name to send the API key in
    Scheme     ProviderAPIKeyScheme `json:"scheme" yaml:"scheme"`           // Authentication scheme (e.g., "Bearer", "Basic", or empty for direct value)
    QueryParam string               `json:"query_param" yaml:"query_param"` // Query parameter name to send the API key in
}

type ProviderAPIKeyScheme

ProviderAPIKeyScheme represents different authentication schemes for API keys.

type ProviderAPIKeyScheme string

API key authentication schemes.

const (
    ProviderAPIKeySchemeBearer ProviderAPIKeyScheme = "Bearer" // Bearer token authentication (OAuth 2.0 style)
    ProviderAPIKeySchemeBasic  ProviderAPIKeyScheme = "Basic"  // Basic authentication
    ProviderAPIKeySchemeDirect ProviderAPIKeyScheme = ""       // Direct value (no scheme prefix)
)

func (ProviderAPIKeyScheme) String
func (paks ProviderAPIKeyScheme) String() string

String returns the string representation of a ProviderAPIKeyScheme.

type ProviderCatalog

ProviderCatalog represents information about a provider's models.

type ProviderCatalog struct {
    Docs     *string          `yaml:"docs" json:"docs"`                           // Documentation URL
    Endpoint ProviderEndpoint `yaml:"endpoint" json:"endpoint"`                   // API endpoint configuration
    Authors  []AuthorID       `json:"authors,omitempty" yaml:"authors,omitempty"` // List of authors to fetch from (for providers like Google Vertex AI)
}

type ProviderChatCompletions

ProviderChatCompletions represents configuration for chat completions API.

type ProviderChatCompletions struct {
    URL              *string                   `json:"url,omitempty" yaml:"url,omitempty"`                             // Chat completions API endpoint URL
    HealthAPIURL     *string                   `json:"health_api_url,omitempty" yaml:"health_api_url,omitempty"`       // URL to health/status API for this service
    HealthComponents []ProviderHealthComponent `json:"health_components,omitempty" yaml:"health_components,omitempty"` // Specific components to monitor for chat completions
}

type ProviderEndpoint

ProviderEndpoint configures how to access the provider's model catalog.

type ProviderEndpoint struct {
    Type          EndpointType   `yaml:"type" json:"type"`                                             // Required: API style
    URL           string         `yaml:"url" json:"url"`                                               // Required: API endpoint
    BaseURLEnvVar string         `yaml:"base_url_env_var,omitempty" json:"base_url_env_var,omitempty"` // Optional env var for overriding the endpoint base URL
    Path          string         `yaml:"path,omitempty" json:"path,omitempty"`                         // Path appended when BaseURLEnvVar is set
    AuthRequired  bool           `yaml:"auth_required" json:"auth_required"`                           // Required: Whether auth needed
    FieldMappings []FieldMapping `yaml:"field_mappings,omitempty" json:"field_mappings,omitempty"`     // Field mappings
    FeatureRules  []FeatureRule  `yaml:"feature_rules,omitempty" json:"feature_rules,omitempty"`       // Feature inference rules
    AuthorMapping *AuthorMapping `yaml:"author_mapping,omitempty" json:"author_mapping,omitempty"`     // Author extraction
}

type ProviderEnvVar

ProviderEnvVar represents an environment variable required by a provider.

type ProviderEnvVar struct {
    Name        string `json:"name" yaml:"name"`                                   // Environment variable name
    Required    bool   `json:"required" yaml:"required"`                           // Whether this env var is required
    Description string `json:"description,omitempty" yaml:"description,omitempty"` // Human-readable description
    Pattern     string `json:"pattern,omitempty" yaml:"pattern,omitempty"`         // Optional validation pattern
}

type ProviderGovernancePolicy

ProviderGovernancePolicy represents oversight and moderation practices.

type ProviderGovernancePolicy struct {
    ModerationRequired *bool   `json:"moderation_required,omitempty" yaml:"moderation_required,omitempty"` // Whether the provider requires moderation
    Moderated          *bool   `json:"moderated,omitempty" yaml:"moderated,omitempty"`                     // Whether provider content is moderated
    Moderator          *string `json:"moderator,omitempty" yaml:"moderator,omitempty"`                     // Who moderates the provider
}

type ProviderHealthComponent

ProviderHealthComponent represents a specific component to monitor in a provider's health API.

type ProviderHealthComponent struct {
    ID   string `json:"id" yaml:"id"`                         // Component ID from the health API
    Name string `json:"name,omitempty" yaml:"name,omitempty"` // Human-readable component name
}

type ProviderID

ProviderID represents a provider identifier type for compile-time safety.

type ProviderID string

Provider ID constants for compile-time safety and consistency.

const (
    ProviderIDAlibabaQwen    ProviderID = "alibaba"
    ProviderIDAlibabaCloud   ProviderID = "alibaba"
    ProviderIDAnthropic      ProviderID = "anthropic"
    ProviderIDAnyscale       ProviderID = "anyscale"
    ProviderIDCerebras       ProviderID = "cerebras"
    ProviderIDCheckstep      ProviderID = "checkstep"
    ProviderIDCohere         ProviderID = "cohere"
    ProviderIDConectys       ProviderID = "conectys"
    ProviderIDCove           ProviderID = "cove"
    ProviderIDDeepMind       ProviderID = "deepmind"
    ProviderIDDeepInfra      ProviderID = "deepinfra"
    ProviderIDDeepSeek       ProviderID = "deepseek"
    ProviderIDFireworksAI    ProviderID = "fireworks-ai"
    ProviderIDGoogleAIStudio ProviderID = "google-ai-studio"
    ProviderIDGoogleVertex   ProviderID = "google-vertex"
    ProviderIDGroq           ProviderID = "groq"
    ProviderIDHuggingFace    ProviderID = "huggingface"
    ProviderIDMeta           ProviderID = "meta"
    ProviderIDMicrosoft      ProviderID = "microsoft"
    ProviderIDMistralAI      ProviderID = "mistral"
    ProviderIDMoonshotAI     ProviderID = "moonshot-ai"
    ProviderIDOpenAI         ProviderID = "openai"
    ProviderIDOpenRouter     ProviderID = "openrouter"
    ProviderIDPerplexity     ProviderID = "perplexity"
    ProviderIDReplicate      ProviderID = "replicate"
    ProviderIDSafetyKit      ProviderID = "safetykit"
    ProviderIDTogetherAI     ProviderID = "together"
    ProviderIDVirtuousAI     ProviderID = "virtuousai"
    ProviderIDWebPurify      ProviderID = "webpurify"
    ProviderIDXAI            ProviderID = "xai"
)

func (ProviderID) String
func (pid ProviderID) String() string

String returns the string representation of a ProviderID.

type ProviderModelID

ProviderModelID is the exact opaque model identifier accepted by a provider.

type ProviderModelID string

type ProviderModerator

ProviderModerator represents a moderator for a provider.

type ProviderModerator string

ProviderModerators.

const (
    // AI Platform Aggregators/Moderators.
    ProviderModeratorAnyscale    ProviderModerator = "anyscale"
    ProviderModeratorHuggingFace ProviderModerator = "huggingface"
    ProviderModeratorOpenRouter  ProviderModerator = "openrouter"
    ProviderModeratorReplicate   ProviderModerator = "replicate"
    ProviderModeratorTogetherAI  ProviderModerator = "together"

    // Specialized AI Safety/Moderation Companies.
    ProviderModeratorCheckstep  ProviderModerator = "checkstep"
    ProviderModeratorConectys   ProviderModerator = "conectys"
    ProviderModeratorCove       ProviderModerator = "cove"
    ProviderModeratorSafetyKit  ProviderModerator = "safetykit"
    ProviderModeratorVirtuousAI ProviderModerator = "virtuousai"
    ProviderModeratorWebPurify  ProviderModerator = "webpurify"

    // Self-Moderated (Major AI Companies).
    ProviderModeratorAnthropic      ProviderModerator = "anthropic"
    ProviderModeratorGoogleAIStudio ProviderModerator = "google-ai-studio"
    ProviderModeratorGoogleVertex   ProviderModerator = "google-vertex"
    ProviderModeratorGroq           ProviderModerator = "groq"
    ProviderModeratorMicrosoft      ProviderModerator = "microsoft"
    ProviderModeratorOpenAI         ProviderModerator = "openai"

    // Unknown/Unspecified.
    ProviderModeratorUnknown ProviderModerator = "unknown"
)

func (ProviderModerator) String
func (pm ProviderModerator) String() string

String returns the string representation of a ProviderModerator.

type ProviderOffering

ProviderOffering is one provider's service contract for a model definition. Provider-specific price, limits, availability, regions, lifecycle, endpoint, modes, and request overrides live here rather than on the definition.

type ProviderOffering struct {
    ProviderID      ProviderID                      `json:"provider_id" yaml:"provider_id"`
    ProviderModelID ProviderModelID                 `json:"provider_model_id" yaml:"provider_model_id"`
    DefinitionID    ModelDefinitionID               `json:"definition_id" yaml:"definition_id"`
    Pricing         *ModelPricing                   `json:"pricing,omitempty" yaml:"pricing,omitempty"`
    Limits          *ModelLimits                    `json:"limits,omitempty" yaml:"limits,omitempty"`
    Availability    OfferingAvailability            `json:"availability" yaml:"availability"`
    Regions         []string                        `json:"regions,omitempty" yaml:"regions,omitempty"`
    Endpoint        ProviderOfferingEndpoint        `json:"endpoint" yaml:"endpoint,omitempty"`
    Lifecycle       OfferingLifecycle               `json:"lifecycle" yaml:"lifecycle"`
    Modes           map[string]ProviderOfferingMode `json:"modes,omitempty" yaml:"modes,omitempty"`
}

func (ProviderOffering) Key
func (o ProviderOffering) Key() OfferingKey

Key returns the provider-scoped immutable offering identity.

func (ProviderOffering) Validate
func (o ProviderOffering) Validate() error

Validate verifies required identity and provider-specific fields.

type ProviderOfferingEndpoint

ProviderOfferingEndpoint describes provider-specific inference endpoint behavior.

type ProviderOfferingEndpoint struct {
    Type    EndpointType `json:"type,omitempty" yaml:"type,omitempty"`
    BaseURL string       `json:"base_url,omitempty" yaml:"base_url,omitempty"`
    Path    string       `json:"path,omitempty" yaml:"path,omitempty"`
}

type ProviderOfferingMode

ProviderOfferingMode describes one named service mode for an offering.

type ProviderOfferingMode struct {
    Pricing *ModelPricing            `json:"pricing,omitempty" yaml:"pricing,omitempty"`
    Limits  *ModelLimits             `json:"limits,omitempty" yaml:"limits,omitempty"`
    Request ProviderRequestOverrides `json:"request" yaml:"request,omitempty"`
}

type ProviderPrivacyPolicy

ProviderPrivacyPolicy represents data collection and usage practices.

type ProviderPrivacyPolicy struct {
    PrivacyPolicyURL  *string `json:"privacy_policy_url,omitempty" yaml:"privacy_policy_url,omitempty"`     // Link to privacy policy
    TermsOfServiceURL *string `json:"terms_of_service_url,omitempty" yaml:"terms_of_service_url,omitempty"` // Link to terms of service
    RetainsData       *bool   `json:"retains_data,omitempty" yaml:"retains_data,omitempty"`                 // Whether provider stores/retains user data
    TrainsOnData      *bool   `json:"trains_on_data,omitempty" yaml:"trains_on_data,omitempty"`             // Whether provider trains models on user data
}

type ProviderRequestOverrides

ProviderRequestOverrides contains provider-specific inference request changes.

type ProviderRequestOverrides struct {
    Headers OfferingRequestHeaders `json:"headers,omitempty" yaml:"headers,omitempty"`
    Body    OfferingRequestBody    `json:"body,omitempty" yaml:"body,omitempty"`
}

type ProviderRetentionPolicy

ProviderRetentionPolicy represents how long data is kept and deletion practices.

type ProviderRetentionPolicy struct {
    Type     ProviderRetentionType `json:"type" yaml:"type"`                             // Type of retention policy
    Duration *time.Duration        `json:"duration,omitempty" yaml:"duration,omitempty"` // nil = forever, 0 = immediate deletion
    Details  *string               `json:"details,omitempty" yaml:"details,omitempty"`   // Human-readable description
}

type ProviderRetentionType

ProviderRetentionType represents different types of data retention policies.

type ProviderRetentionType string

ProviderRetention types.

const (
    ProviderRetentionTypeFixed       ProviderRetentionType = "fixed"       // Specific duration (use Duration field)
    ProviderRetentionTypeNone        ProviderRetentionType = "none"        // No retention (immediate deletion)
    ProviderRetentionTypeIndefinite  ProviderRetentionType = "indefinite"  // Forever (duration = nil)
    ProviderRetentionTypeConditional ProviderRetentionType = "conditional" // Based on conditions (e.g., "until account deletion")
)

func (ProviderRetentionType) String
func (prt ProviderRetentionType) String() string

String returns the string representation of a ProviderRetentionType.

type ProviderValidationEntry

ProviderValidationEntry represents the validation status of a single provider.

type ProviderValidationEntry struct {
    Provider     *Provider
    HasAPIKey    bool
    IsRequired   bool
    IsConfigured bool
    Error        error
}

type ProviderValidationReport

ProviderValidationReport contains the results of validating provider access.

type ProviderValidationReport struct {
    Configured  []ProviderValidationEntry // Providers with configured API keys
    Missing     []ProviderValidationEntry // Providers missing required API keys
    Optional    []ProviderValidationEntry // Providers with optional or no API key requirement
    Unsupported []ProviderValidationEntry // Providers without client implementation
}

func ValidateAllProviders
func ValidateAllProviders(catalog Reader, supportedProviders []ProviderID) (*ProviderValidationReport, error)

ValidateAllProviders checks all providers in the catalog for API key availability. This helps users understand which providers they can use based on their configuration. The supportedProviders parameter should be a list of provider IDs that have client implementations.

func (*ProviderValidationReport) Print
func (r *ProviderValidationReport) Print()

Print outputs a formatted report of provider validation status.

type ProviderValidationResult

ProviderValidationResult contains the result of validating a provider.

type ProviderValidationResult struct {
    Status             ProviderValidationStatus `json:"status"`
    HasAPIKey          bool                     `json:"has_api_key"`
    IsAPIKeyRequired   bool                     `json:"is_api_key_required"`
    HasRequiredEnvVars bool                     `json:"has_required_env_vars"`
    MissingEnvVars     []string                 `json:"missing_env_vars,omitempty"`
    IsConfigured       bool                     `json:"is_configured"`
    IsSupported        bool                     `json:"is_supported"`
    Error              error                    `json:"error,omitempty"`
}

type ProviderValidationStatus

ProviderValidationStatus represents the validation status of a provider.

type ProviderValidationStatus string


const (
    // ProviderValidationStatusConfigured indicates the provider is properly configured and ready to use.
    ProviderValidationStatusConfigured ProviderValidationStatus = "configured"
    // ProviderValidationStatusMissing indicates the provider is missing required API key configuration.
    ProviderValidationStatusMissing ProviderValidationStatus = "missing"
    // ProviderValidationStatusOptional indicates the provider has optional API key that is not configured (still usable).
    ProviderValidationStatusOptional ProviderValidationStatus = "optional"
    // ProviderValidationStatusUnsupported indicates the provider doesn't have client implementation yet.
    ProviderValidationStatusUnsupported ProviderValidationStatus = "unsupported"
)

func (ProviderValidationStatus) String
func (pvs ProviderValidationStatus) String() string

String returns the string representation of ProviderValidationStatus.

type Providers

Providers is a concurrent safe map of providers.

type Providers struct {
    // contains filtered or unexported fields
}

func NewProviders
func NewProviders(opts ...ProvidersOption) *Providers

NewProviders creates a new Providers map with optional configuration.

func (*Providers) Add
func (p *Providers) Add(provider *Provider) error

Add adds a provider, returning an error if it already exists.

func (*Providers) AddBatch
func (p *Providers) AddBatch(providers []*Provider) map[ProviderID]error

AddBatch adds multiple providers in a single operation. Only adds providers that don't already exist - fails if a provider ID already exists. Returns a map of provider IDs to errors for any failed additions.

func (*Providers) Clear
func (p *Providers) Clear()

Clear removes all providers.

func (*Providers) Delete
func (p *Providers) Delete(id ProviderID) error

Delete removes a provider by id. Returns an error if the provider doesn't exist.

func (*Providers) DeleteBatch
func (p *Providers) DeleteBatch(ids []ProviderID) map[ProviderID]error

DeleteBatch removes multiple providers by their IDs. Returns a map of errors for providers that couldn't be deleted (not found).

func (*Providers) DeleteModel
func (p *Providers) DeleteModel(providerID ProviderID, modelID string) error

DeleteModel removes a model from a provider.

func (*Providers) EncodeYAML
func (p *Providers) EncodeYAML() (string, error)

EncodeYAML returns formatted provider YAML or a typed parse error when a provider value cannot be represented safely.

func (*Providers) Exists
func (p *Providers) Exists(id ProviderID) bool

Exists checks if a provider exists without returning it.

func (*Providers) ForEach
func (p *Providers) ForEach(fn func(id ProviderID, provider *Provider) bool)

ForEach applies a function to each provider. The function should not modify the provider. If the function returns false, iteration stops early.

func (*Providers) FormatYAML
func (p *Providers) FormatYAML() string

FormatYAML returns the providers as formatted YAML with enhanced formatting, comments, and structure.

func (*Providers) Get
func (p *Providers) Get(id ProviderID) (*Provider, bool)

Get returns a provider by id and whether it exists.

func (*Providers) Len
func (p *Providers) Len() int

Len returns the number of providers.

func (*Providers) List
func (p *Providers) List() []Provider

List returns a slice of all providers as values (copies).

func (*Providers) Map
func (p *Providers) Map() map[ProviderID]*Provider

Map returns a copy of all providers.

func (*Providers) Resolve
func (p *Providers) Resolve(id ProviderID) (*Provider, bool)

Resolve returns a provider by ID or alias. It first tries an exact ID match, then searches all provider aliases. This allows commands to accept both canonical IDs and common aliases silently.

func (*Providers) Set
func (p *Providers) Set(id ProviderID, provider *Provider) error

Set sets a provider by id. Returns an error if provider is nil.

func (*Providers) SetBatch
func (p *Providers) SetBatch(providers map[ProviderID]*Provider) error

SetBatch sets multiple providers in a single operation. Overwrites existing providers or adds new ones (upsert behavior). Returns an error if any provider is nil.

func (*Providers) SetModel
func (p *Providers) SetModel(providerID ProviderID, model Model) error

SetModel adds or updates a model in a provider.

type ProvidersOption

ProvidersOption defines a function that configures a Providers instance.

type ProvidersOption func(*Providers)

func WithProvidersCapacity
func WithProvidersCapacity(capacity int) ProvidersOption

WithProvidersCapacity sets the initial capacity of the providers map.

func WithProvidersMap
func WithProvidersMap(providers map[ProviderID]*Provider) ProvidersOption

WithProvidersMap initializes the map with existing providers.

type ProvidersReader

ProvidersReader exposes provider collection reads without mutation methods.

type ProvidersReader interface {
    Get(ProviderID) (*Provider, bool)
    Resolve(ProviderID) (*Provider, bool)
    Exists(ProviderID) bool
    Len() int
    List() []Provider
    Map() map[ProviderID]*Provider
    ForEach(func(ProviderID, *Provider) bool)
    FormatYAML() string
}

type Quantization

Quantization represents the quantization level used by a model. Quantization reduces model size and computational requirements while aiming to preserve performance.

type Quantization string

Quantization levels.

const (
    QuantizationINT4    Quantization = "int4"    // Integer (4 bit)
    QuantizationINT8    Quantization = "int8"    // Integer (8 bit)
    QuantizationFP4     Quantization = "fp4"     // Floating point (4 bit)
    QuantizationFP6     Quantization = "fp6"     // Floating point (6 bit)
    QuantizationFP8     Quantization = "fp8"     // Floating point (8 bit)
    QuantizationFP16    Quantization = "fp16"    // Floating point (16 bit)
    QuantizationBF16    Quantization = "bf16"    // Brain floating point (16 bit)
    QuantizationFP32    Quantization = "fp32"    // Floating point (32 bit)
    QuantizationUnknown Quantization = "unknown" // Unknown quantization
)

func (Quantization) String
func (q Quantization) String() string

String returns the string representation of a Quantization.

type Reader

Reader provides read-only access to catalog data.

type Reader interface {
    // Lists all providers, authors, and endpoints
    Providers() ProvidersReader
    Authors() AuthorsReader
    Endpoints() EndpointsReader
    Models() ModelsReader
    Provenance() ProvenanceReader

    // Gets a provider, author, or endpoint by id
    Provider(id ProviderID) (Provider, error)
    Author(id AuthorID) (Author, error)
    Endpoint(id string) (Endpoint, error)
    ProviderModels(id ProviderID) (ModelsReader, error)
    ProviderModel(providerID ProviderID, modelID string) (Model, error)
}

type RouteAlias

RouteAlias names a set of candidate offering identities. It intentionally contains no weights, fallback order, tenancy, or routing strategy.

type RouteAlias struct {
    ID      RouteAliasID  `json:"id" yaml:"id"`
    Targets []OfferingKey `json:"targets" yaml:"targets"`
}

func (RouteAlias) Validate
func (a RouteAlias) Validate() error

Validate verifies route identity and exact target uniqueness.

type RouteAliasID

RouteAliasID is a Starport-facing routing identity independent of provider IDs.

type RouteAliasID string

type RouteAliasRejection

RouteAliasRejection records one ineligible target without hiding it.

type RouteAliasRejection struct {
    Key    OfferingKey               `json:"key" yaml:"key"`
    Reason RouteAliasRejectionReason `json:"reason" yaml:"reason"`
}

type RouteAliasRejectionReason

RouteAliasRejectionReason classifies why a target is not currently eligible.

type RouteAliasRejectionReason string


const (
    // RouteAliasRejectedMissing means the offering key is absent from the catalog.
    RouteAliasRejectedMissing RouteAliasRejectionReason = "missing"
    // RouteAliasRejectedUnavailable means the provider marks the offering unavailable.
    RouteAliasRejectedUnavailable RouteAliasRejectionReason = "unavailable"
    // RouteAliasRejectedRetired means the provider has retired the offering.
    RouteAliasRejectedRetired RouteAliasRejectionReason = "retired"
)

type RouteAliasResolution

RouteAliasResolution is a point-in-time materialization against one catalog generation.

type RouteAliasResolution struct {
    AliasID  RouteAliasID          `json:"alias_id" yaml:"alias_id"`
    Eligible []ProviderOffering    `json:"eligible" yaml:"eligible"`
    Rejected []RouteAliasRejection `json:"rejected,omitempty" yaml:"rejected,omitempty"`
}

type SourceExtension

SourceExtension stores controlled non-canonical fields reported by one source.

type SourceExtension struct {
    Fields map[string]any `json:"fields,omitempty" yaml:"fields,omitempty"` // Preserved source-specific fields
}

func (SourceExtension) Copy
func (se SourceExtension) Copy() SourceExtension

Copy returns a deep copy of the source extension.

func (*SourceExtension) UnmarshalJSON
func (se *SourceExtension) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes dynamic extension field types after JSON decoding.

func (*SourceExtension) UnmarshalYAML
func (se *SourceExtension) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML normalizes dynamic extension field types after YAML decoding.

type SourceExtensions

SourceExtensions stores source-specific attributes that Starmap preserves without treating as canonical schema fields.

type SourceExtensions map[string]SourceExtension

func NormalizeSourceExtensions
func NormalizeSourceExtensions(extensions SourceExtensions) SourceExtensions

NormalizeSourceExtensions returns a copy with JSON/YAML-stable dynamic value types for equality checks and sync idempotency.

func (SourceExtensions) Copy
func (se SourceExtensions) Copy() SourceExtensions

Copy returns a deep copy of the source extension map.

SourceObservationLink binds a generation to one immutable source observation. The observation schema and retention policy are defined by the source pipeline; this link is deliberately small and replay-oriented.

type SourceObservationLink struct {
    Source           catalogmeta.SourceID                `json:"source" yaml:"source"`
    ObservationID    string                              `json:"observation_id" yaml:"observation_id"`
    ObservedAt       time.Time                           `json:"observed_at" yaml:"observed_at"`
    Revision         catalogmeta.ObservationRevision     `json:"revision" yaml:"revision"`
    Completeness     catalogmeta.ObservationCompleteness `json:"completeness" yaml:"completeness"`
    Status           catalogmeta.ObservationStatus       `json:"status" yaml:"status"`
    EvidenceChecksum string                              `json:"evidence_checksum" yaml:"evidence_checksum"`
}


func (o SourceObservationLink) Validate() error

Validate verifies one complete source-observation link.

type TestModelOption

TestModelOption is a functional option for configuring a test model.

type TestModelOption func(*Model)

func WithModelID
func WithModelID(id string) TestModelOption

WithModelID sets a custom ID for the test model.

func WithModelName
func WithModelName(name string) TestModelOption

WithModelName sets a custom name for the test model.

type TestProviderOption

TestProviderOption is a functional option for configuring a test provider.

type TestProviderOption func(*Provider)

func WithProviderAPIKey
func WithProviderAPIKey(name, pattern string) TestProviderOption

WithProviderAPIKey sets a custom API key configuration.

func WithProviderEnvVars
func WithProviderEnvVars(envVars []ProviderEnvVar) TestProviderOption

WithProviderEnvVars sets environment variables for the test provider.

func WithProviderID
func WithProviderID(id ProviderID) TestProviderOption

WithProviderID sets a custom ID for the test provider.

type Tokenizer

Tokenizer represents the tokenizer type used by a model.

type Tokenizer string

Tokenizer types.

const (
    TokenizerClaude   Tokenizer = "claude"   // Claude tokenizer
    TokenizerCohere   Tokenizer = "cohere"   // Cohere tokenizer
    TokenizerDeepSeek Tokenizer = "deepseek" // DeepSeek tokenizer
    TokenizerGPT      Tokenizer = "gpt"      // GPT tokenizer (OpenAI)
    TokenizerGemini   Tokenizer = "gemini"   // Gemini tokenizer (Google)
    TokenizerGrok     Tokenizer = "grok"     // Grok tokenizer (xAI)
    TokenizerLlama2   Tokenizer = "llama2"   // LLaMA 2 tokenizer
    TokenizerLlama3   Tokenizer = "llama3"   // LLaMA 3 tokenizer
    TokenizerLlama4   Tokenizer = "llama4"   // LLaMA 4 tokenizer
    TokenizerMistral  Tokenizer = "mistral"  // Mistral tokenizer
    TokenizerNova     Tokenizer = "nova"     // Nova tokenizer (Amazon)
    TokenizerQwen     Tokenizer = "qwen"     // Qwen tokenizer
    TokenizerQwen3    Tokenizer = "qwen3"    // Qwen 3 tokenizer
    TokenizerRouter   Tokenizer = "router"   // Router-based tokenizer
    TokenizerYi       Tokenizer = "yi"       // Yi tokenizer
    TokenizerUnknown  Tokenizer = "unknown"  // Unknown tokenizer type
)

func (Tokenizer) String
func (t Tokenizer) String() string

String returns the string representation of a Tokenizer.

type ToolChoice

ToolChoice represents the strategy for selecting tools. Used in API requests as the "tool_choice" parameter value.

type ToolChoice string

Tool choice strategies for controlling tool usage behavior.

const (
    ToolChoiceAuto     ToolChoice = "auto"     // Model autonomously decides whether to call tools based on context
    ToolChoiceNone     ToolChoice = "none"     // Model will never call tools, even if tool definitions are provided
    ToolChoiceRequired ToolChoice = "required" // Model must call at least one tool before responding

)

func (ToolChoice) String
func (tc ToolChoice) String() string

String returns the string representation of a ToolChoice.

Generated by gomarkdoc

Documentation

Overview

Package catalogs provides the core catalog system for managing AI model metadata. It offers multiple implementations (embedded, file-based, memory) and supports CRUD operations, merging strategies, and persistence.

The catalog system is designed to be thread-safe and extensible, with support for providers, models, authors, and endpoints. Each catalog implementation can be configured with different storage backends while maintaining a consistent interface.

Example usage: 

// Advanced producers construct a draft, then publish an immutable catalog.
builder, err := New(WithEmbedded())
if err != nil {
    log.Fatal(err)
}
catalog, err := builder.Build()
if err != nil {
    log.Fatal(err)
}

// Access models
models := catalog.Models()
for _, model := range models.List() {
    fmt.Printf("Model: %s\n", model.ID)
}

// Create a file-based draft (development use)
builder, err = New(WithFiles("./catalog"))
if err != nil {
    log.Fatal(err)
}
Example

Example demonstrates advanced catalog construction and publication. 

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create a memory-based draft.
	builder := catalogs.NewEmpty()

	// Add a provider with a model
	provider := catalogs.Provider{
		ID:   "openai",
		Name: "OpenAI",
		Models: map[string]*catalogs.Model{
			"gpt-4": {
				ID:          "gpt-4",
				Name:        "GPT-4",
				Description: "Advanced language model",
			},
		},
	}
	if err := builder.SetProvider(provider); err != nil {
		log.Fatal(err)
	}
	catalog, err := builder.Build()
	if err != nil {
		log.Fatal(err)
	}

	// List all models
	models := catalog.Models().List()
	fmt.Printf("Found %d models\n", len(models))
}

Output:
Found 1 models
Example (CatalogCopy)

Example_catalogCopy demonstrates creating independent copies. 

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create original catalog
	original := catalogs.NewEmpty()
	provider := catalogs.Provider{
		ID:   "test",
		Name: "Test Provider",
		Models: map[string]*catalogs.Model{
			"model-1": {
				ID:   "model-1",
				Name: "Original Model",
			},
		},
	}
	_ = original.SetProvider(provider)

	// Create a copy
	copy, err := original.Copy()
	if err != nil {
		log.Fatal(err)
	}

	// Modify the copy by updating the provider
	copiedProvider, _ := copy.Provider("test")
	if copiedProvider.Models == nil {
		copiedProvider.Models = make(map[string]*catalogs.Model)
	}
	copiedProvider.Models["model-2"] = &catalogs.Model{
		ID:   "model-2",
		Name: "Copy Model",
	}
	_ = copy.SetProvider(copiedProvider)

	// Original is unchanged
	fmt.Printf("Original has %d models\n", len(original.Models().List()))
	fmt.Printf("Copy has %d models\n", len(copy.Models().List()))
}

Output:
Original has 1 models
Copy has 2 models
Example (ConcurrentAccess)

Example_concurrentAccess demonstrates thread-safe concurrent usage. 

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/agentstation/starmap/pkg/catalogs"
	"github.com/agentstation/starmap/pkg/constants"
)

func main() {
	catalog := catalogs.NewEmpty()
	ctx, cancel := context.WithTimeout(context.Background(), constants.DefaultHTTPTimeout)
	defer cancel()

	// Safe for concurrent reads and writes
	done := make(chan bool, 2)

	// Writer goroutine
	go func() {
		provider := catalogs.Provider{
			ID:     "test-provider",
			Name:   "Test Provider",
			Models: make(map[string]*catalogs.Model),
		}
		for i := range 100 {
			provider.Models[fmt.Sprintf("model-%d", i)] = &catalogs.Model{
				ID:   fmt.Sprintf("model-%d", i),
				Name: fmt.Sprintf("Model %d", i),
			}
		}
		_ = catalog.SetProvider(provider)
		done <- true
	}()

	// Reader goroutine
	go func() {
		for {
			select {
			case <-ctx.Done():
				done <- true
				return
			default:
				_ = catalog.Models().List()
				time.Sleep(10 * time.Millisecond)
			}
		}
	}()

	// Wait for both
	<-done
	<-done

	fmt.Printf("Created %d models concurrently\n", len(catalog.Models().List()))
}
Example (EmbeddedCatalog)

Example_embeddedCatalog demonstrates using the embedded catalog. 

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Load embedded data into a builder, then publish it.
	builder, err := catalogs.New(catalogs.WithEmbedded())
	if err != nil {
		log.Fatal(err)
	}
	catalog, err := builder.Build()
	if err != nil {
		log.Fatal(err)
	}

	// Access pre-loaded models
	models := catalog.Models().List()
	fmt.Printf("Embedded catalog has %d+ models\n", len(models))

	// Find a specific model
	model, err := catalog.FindModel("gpt-4o")
	if err == nil {
		fmt.Printf("Found model: %s\n", model.Name)
	}
}
Example (FileBasedCatalog)

Example_fileBasedCatalog demonstrates file-based persistence. 

package main

import (
	"fmt"
	"log"
	"path/filepath"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create a file-based builder.
	catalogPath := filepath.Join(".", "my-catalog")
	builder, err := catalogs.New(
		catalogs.WithPath(catalogPath),
		catalogs.WithWritePath(catalogPath),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Add and save data
	provider := catalogs.Provider{
		ID:   "custom",
		Name: "Custom Provider",
		Models: map[string]*catalogs.Model{
			"custom-model": {
				ID:   "custom-model",
				Name: "My Custom Model",
			},
		},
	}
	if err := builder.SetProvider(provider); err != nil {
		log.Fatal(err)
	}

	// Save to disk (would normally use SaveTo method or similar)
	// Since Write is not part of the interface, this example shows the concept
	// In actual usage, you would use catalog.SaveTo(catalogPath)

	fmt.Println("Catalog saved to disk")
}
Example (MergeCatalogs)

Example_mergeCatalogs demonstrates merging two catalogs. 

package main

import (
	"fmt"
	"log"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	// Create base catalog
	base := catalogs.NewEmpty()
	baseProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test Provider",
		Models: map[string]*catalogs.Model{
			"model-1": {
				ID:          "model-1",
				Name:        "Model One",
				Description: "Original description",
			},
		},
	}
	_ = base.SetProvider(baseProvider)

	// Create updates catalog
	updates := catalogs.NewEmpty()
	updateProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test Provider",
		Models: map[string]*catalogs.Model{
			"model-1": {
				ID:          "model-1",
				Name:        "Model One Enhanced",
				Description: "Updated description",
				Pricing: &catalogs.ModelPricing{
					Tokens: &catalogs.ModelTokenPricing{
						Input: &catalogs.ModelTokenCost{
							Per1M: 2.0, // $2 per 1M tokens
						},
						Output: &catalogs.ModelTokenCost{
							Per1M: 4.0, // $4 per 1M tokens
						},
					},
					Currency: "USD",
				},
			},
		},
	}
	_ = updates.SetProvider(updateProvider)

	// Merge with EnrichEmpty strategy (default)
	if err := base.MergeWith(updates); err != nil {
		log.Fatal(err)
	}

	model, _ := base.FindModel("model-1")
	fmt.Printf("Model name: %s\n", model.Name)
}

Output:
Model name: Model One Enhanced
Example (MergeStrategies)

Example_mergeStrategies demonstrates different merge strategies. 

package main

import (
	"fmt"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	base := catalogs.NewEmpty()
	baseProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test",
		Models: map[string]*catalogs.Model{
			"m1": {ID: "m1", Name: "Original"},
		},
	}
	_ = base.SetProvider(baseProvider)

	updates := catalogs.NewEmpty()
	updateProvider := catalogs.Provider{
		ID:   "test",
		Name: "Test",
		Models: map[string]*catalogs.Model{
			"m1": {ID: "m1", Name: "Updated"},
			"m2": {ID: "m2", Name: "New"},
		},
	}
	_ = updates.SetProvider(updateProvider)

	// Example 1: Append only (keeps existing, adds new)
	cat1, _ := base.Copy()
	cat1.MergeWith(updates, catalogs.WithStrategy(catalogs.MergeAppendOnly))

	m1, _ := cat1.FindModel("m1")
	fmt.Printf("AppendOnly - m1: %s\n", m1.Name) // Original

	// Example 2: Replace all
	cat2, _ := base.Copy()
	cat2.MergeWith(updates, catalogs.WithStrategy(catalogs.MergeReplaceAll))

	m1, _ = cat2.FindModel("m1")
	fmt.Printf("ReplaceAll - m1: %s\n", m1.Name) // Updated

	// Example 3: Enrich empty (smart merge)
	cat3, _ := base.Copy()
	cat3.MergeWith(updates, catalogs.WithStrategy(catalogs.MergeEnrichEmpty))

	m1, _ = cat3.FindModel("m1")
	fmt.Printf("EnrichEmpty - m1: %s\n", m1.Name) // Updated
}
Example (ModelFiltering)

Example_modelFiltering demonstrates filtering models. 

package main

import (
	"fmt"
	"slices"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	catalog, _ := catalogs.New(catalogs.WithEmbedded())

	// Get all models for a specific provider
	// In practice, models would be linked to providers via naming convention or metadata
	var gptModels []catalogs.Model
	for _, model := range catalog.Models().List() {
		if len(model.ID) > 3 && model.ID[:3] == "gpt" {
			gptModels = append(gptModels, model)
		}
	}
	fmt.Printf("Found %d GPT models\n", len(gptModels))

	// Filter by features
	var visionModels []catalogs.Model
	for _, model := range catalog.Models().List() {
		if model.Features != nil {
			if slices.Contains(model.Features.Modalities.Input, "image") {
				visionModels = append(visionModels, model)
			}
		}
	}
	fmt.Printf("Found %d models with vision\n", len(visionModels))
}
Example (ProviderCapabilities)

Example_providerCapabilities demonstrates working with provider features. 

package main

import (
	"fmt"

	"github.com/agentstation/starmap/pkg/catalogs"
)

func main() {
	catalog := catalogs.NewEmpty()

	// Add provider with capabilities
	provider := catalogs.Provider{
		ID:   "openai",
		Name: "OpenAI",
		Catalog: &catalogs.ProviderCatalog{
			Endpoint: catalogs.ProviderEndpoint{
				URL:          "https://api.openai.com/v1/models",
				AuthRequired: true,
			},
		},
	}
	_ = catalog.SetProvider(provider)

	// Check capabilities
	p, _ := catalog.Provider("openai")
	if p.HasAPIKey() {
		fmt.Println("Provider has API key configured")
	}
	if p.Catalog != nil && p.Catalog.Endpoint.AuthRequired {
		fmt.Println("Provider requires API key")
	}
}

Index

Examples

Constants

View Source 
const (
	// CurrentGenerationManifestVersion is the manifest envelope version emitted
	// by this release. It is intentionally independent of the Starmap binary
	// version and the catalog payload schema version.
	CurrentGenerationManifestVersion uint64 = 1

	// CurrentCatalogSchemaVersion identifies the canonical catalog payload
	// schema emitted by this release.
	CurrentCatalogSchemaVersion uint64 = 1

	// CatalogPayloadMediaType identifies the canonical JSON catalog payload.
	CatalogPayloadMediaType = "application/vnd.agentstation.starmap.catalog+json"
)
View Source 
const CurrentBootstrapManifestVersion uint64 = 1

CurrentBootstrapManifestVersion is the embedded-bootstrap metadata format.

View Source 
const (
	// LegacyCatalogSchemaVersion identifies the pre-definition/offering bare-ID
	// catalog API exposed by LegacyCatalogV0.
	LegacyCatalogSchemaVersion uint64 = 0
)

Variables

This section is empty.

Functions

func AssertCatalogHasModel 

func AssertCatalogHasModel(t testing.TB, catalog Reader, modelID string)

AssertCatalogHasModel asserts that a catalog contains a model with the given ID.

func AssertCatalogHasProvider 

func AssertCatalogHasProvider(t testing.TB, catalog Reader, providerID ProviderID)

AssertCatalogHasProvider asserts that a catalog contains a provider with the given ID.

func AssertModelsEqual 

func AssertModelsEqual(t testing.TB, expected, actual *Model)

AssertModelsEqual asserts that two models are equal, providing detailed diff on failure.

func AssertProvidersEqual 

func AssertProvidersEqual(t testing.TB, expected, actual *Provider)

AssertProvidersEqual asserts that two providers are equal.

func DeepCopyAuthorModels added in v0.0.15 

func DeepCopyAuthorModels(models map[string]*Model) map[string]*Model

DeepCopyAuthorModels creates a deep copy of an author's Models map. Returns nil if the input map is nil.

func DeepCopyProviderModels added in v0.0.15 

func DeepCopyProviderModels(models map[string]*Model) map[string]*Model

DeepCopyProviderModels creates a deep copy of a provider's Models map. Returns nil if the input map is nil.

func EncodeCatalogPayload added in v0.1.0 

func EncodeCatalogPayload(reader Reader) ([]byte, error)

EncodeCatalogPayload deterministically encodes a readable catalog as schema v1.

func NormalizeExtensionFields added in v0.1.0 

func NormalizeExtensionFields(fields map[string]any) map[string]any

NormalizeExtensionFields returns a copy with maps, slices, and numbers normalized to stable dynamic types after JSON/YAML round trips.

func PrintProviderValidationReport 

func PrintProviderValidationReport(report *ProviderValidationReport)

PrintProviderValidationReport prints a formatted report of provider validation status This is a convenience function that calls the Print method on the report.

func ShallowCopyAuthorModels added in v0.0.15 

func ShallowCopyAuthorModels(models map[string]*Model) map[string]*Model

ShallowCopyAuthorModels creates a shallow copy of an author's Models map. The map is copied but Model pointers are shared. Returns nil if the input map is nil.

func ShallowCopyProviderModels added in v0.0.15 

func ShallowCopyProviderModels(models map[string]*Model) map[string]*Model

ShallowCopyProviderModels creates a shallow copy of a provider's Models map. The map is copied but Model pointers are shared. Returns nil if the input map is nil.

func TestAPIResponse 

func TestAPIResponse(models ...string) map[string]any

TestAPIResponse creates a test API response for provider testing.

func TestTimeNow 

func TestTimeNow() time.Time

TestTimeNow returns a consistent time for testing.

Types

type ArchitectureType 

type ArchitectureType string

ArchitectureType represents the type of model architecture. 

const (
	ArchitectureTypeTransformer ArchitectureType = "transformer" // Transformer-based models (GPT, BERT, LLaMA, etc.)
	ArchitectureTypeMoE         ArchitectureType = "moe"         // Mixture of Experts (Mixtral, GLaM, Switch Transformer)
	ArchitectureTypeCNN         ArchitectureType = "cnn"         // Convolutional Neural Networks
	ArchitectureTypeRNN         ArchitectureType = "rnn"         // Recurrent Neural Networks
	ArchitectureTypeLSTM        ArchitectureType = "lstm"        // Long Short-Term Memory networks
	ArchitectureTypeGRU         ArchitectureType = "gru"         // Gated Recurrent Unit networks
	ArchitectureTypeVAE         ArchitectureType = "vae"         // Variational Autoencoders
	ArchitectureTypeGAN         ArchitectureType = "gan"         // Generative Adversarial Networks
	ArchitectureTypeDiffusion   ArchitectureType = "diffusion"   // Diffusion models (Stable Diffusion, DALL-E, etc.)
)

Architecture types.

func (ArchitectureType) String 

func (at ArchitectureType) String() string

String returns the string representation of an ArchitectureType.

type Author 

type Author struct {
	ID          AuthorID   `json:"id" yaml:"id"`                                       // Unique identifier for the author
	Aliases     []AuthorID `json:"aliases,omitempty" yaml:"aliases,omitempty"`         // Alternative IDs this author is known by (e.g., in provider catalogs)
	Name        string     `json:"name" yaml:"name"`                                   // Display name of the author
	Description *string    `json:"description,omitempty" yaml:"description,omitempty"` // Description of what the author is known for

	// Company/organization info
	Headquarters *string `json:"headquarters,omitempty" yaml:"headquarters,omitempty"` // Company headquarters location
	IconURL      *string `json:"icon_url,omitempty" yaml:"icon_url,omitempty"`         // Author icon/logo URL

	// Website, social links, and other relevant URLs
	Website     *string `json:"website,omitempty" yaml:"website,omitempty"`         // Official website URL
	HuggingFace *string `json:"huggingface,omitempty" yaml:"huggingface,omitempty"` // Hugging Face profile/organization URL
	GitHub      *string `json:"github,omitempty" yaml:"github,omitempty"`           // GitHub profile/organization URL
	Twitter     *string `json:"twitter,omitempty" yaml:"twitter,omitempty"`         // X (formerly Twitter) profile URL

	// Catalog and models
	Catalog *AuthorCatalog    `json:"catalog,omitempty" yaml:"catalog,omitempty"` // Primary provider catalog for this author's models
	Models  map[string]*Model `json:"-" yaml:"-"`                                 // Models published by this author - not serialized

	// Timestamps for record keeping and auditing
	CreatedAt utc.Time `json:"created_at" yaml:"created_at"` // Created date (YYYY-MM or YYYY-MM-DD format)
	UpdatedAt utc.Time `json:"updated_at" yaml:"updated_at"` // Last updated date (YYYY-MM or YYYY-MM-DD format)
}

Author represents a known model author or organization.

func DeepCopyAuthor added in v0.0.15 

func DeepCopyAuthor(author Author) Author

DeepCopyAuthor creates a deep copy of an Author including its Models map.

func DeepCopyAuthors added in v0.1.0 

func DeepCopyAuthors(authors []Author) []Author

DeepCopyAuthors creates a deep copy of an Author slice.

func TestAuthor 

func TestAuthor(t testing.TB) *Author

TestAuthor creates a test author with sensible defaults.

type AuthorAttribution added in v0.0.15 

type AuthorAttribution struct {
	ProviderID ProviderID `json:"provider_id,omitempty" yaml:"provider_id,omitempty"` // Optional provider to source models from
	Patterns   []string   `json:"patterns,omitempty" yaml:"patterns,omitempty"`       // Glob patterns to match model IDs
}

AuthorAttribution defines how to identify an author's models across providers. Uses standard Go glob pattern syntax for case-insensitive model ID matching.

Supports three modes:

  1. Provider-only: provider_id set, no patterns - all models from that provider belong to this author
  2. Provider + patterns: provider_id + patterns - only matching models from that provider, then cross-provider attribution
  3. Global patterns: patterns only - direct case-insensitive pattern matching across all providers

Glob Pattern Syntax (case-insensitive):

  • matches any sequence of characters (except path separators) ? matches any single character [abc] matches any character in the set [a-z] matches any character in the range

Examples: 

"llama*" matches llama-3, Llama3.1-8b, LLAMA-BIG
"*-llama-*" matches deepseek-r1-distill-llama-70b, DeepSeek-R1-Distill-LLAMA-70B
"gpt-*" matches gpt-4, GPT-3.5-turbo, Gpt-4o

type AuthorCatalog 

type AuthorCatalog struct {
	Description *string            `json:"description,omitempty" yaml:"description,omitempty"` // Optional description of this mapping relationship
	Attribution *AuthorAttribution `json:"attribution,omitempty" yaml:"attribution,omitempty"` // Model attribution configuration for multi-provider inference
}

AuthorCatalog represents the relationship between an author and their authoritative provider catalog. This contains the attribution configuration for identifying the author's models across providers.

type AuthorID 

type AuthorID string

AuthorID is a unique identifier for an author. 

const (
	// Major AI Companies.
	AuthorIDOpenAI    AuthorID = "openai"
	AuthorIDAnthropic AuthorID = "anthropic"
	AuthorIDGoogle    AuthorID = "google"
	AuthorIDDeepMind  AuthorID = "deepmind"
	AuthorIDMeta      AuthorID = "meta"
	AuthorIDMicrosoft AuthorID = "microsoft"
	AuthorIDMistralAI AuthorID = "mistral"
	AuthorIDCohere    AuthorID = "cohere"
	// AuthorIDCerebras removed - Cerebras is an inference provider, not a model creator.
	AuthorIDGroq        AuthorID = "groq"
	AuthorIDAlibabaQwen AuthorID = "alibaba"
	AuthorIDQwen        AuthorID = "qwen"
	AuthorIDXAI         AuthorID = "xai"

	// Research Institutions.
	AuthorIDStanford    AuthorID = "stanford"
	AuthorIDMIT         AuthorID = "mit"
	AuthorIDCMU         AuthorID = "cmu"
	AuthorIDUCBerkeley  AuthorID = "uc-berkeley"
	AuthorIDCornell     AuthorID = "cornell"
	AuthorIDPrinceton   AuthorID = "princeton"
	AuthorIDHarvard     AuthorID = "harvard"
	AuthorIDOxford      AuthorID = "oxford"
	AuthorIDCambridge   AuthorID = "cambridge"
	AuthorIDETHZurich   AuthorID = "eth-zurich"
	AuthorIDUWashington AuthorID = "uw"
	AuthorIDUChicago    AuthorID = "uchicago"
	AuthorIDYale        AuthorID = "yale"
	AuthorIDDuke        AuthorID = "duke"
	AuthorIDCaltech     AuthorID = "caltech"

	// Open Source Communities & Platforms.
	AuthorIDHuggingFace AuthorID = "huggingface"
	AuthorIDEleutherAI  AuthorID = "eleutherai"
	AuthorIDTogether    AuthorID = "together"
	AuthorIDMosaicML    AuthorID = "mosaicml"
	AuthorIDStabilityAI AuthorID = "stability"
	AuthorIDRunwayML    AuthorID = "runway"
	AuthorIDMidjourney  AuthorID = "midjourney"
	AuthorIDLAION       AuthorID = "laion"
	AuthorIDBigScience  AuthorID = "bigscience"
	AuthorIDAlignmentRC AuthorID = "alignment-research"
	AuthorIDH2OAI       AuthorID = "h2o.ai"
	AuthorIDMoxin       AuthorID = "moxin"

	// Chinese Organizations.
	AuthorIDBaidu      AuthorID = "baidu"
	AuthorIDTencent    AuthorID = "tencent"
	AuthorIDByteDance  AuthorID = "bytedance"
	AuthorIDDeepSeek   AuthorID = "deepseek"
	AuthorIDBAAI       AuthorID = "baai"
	AuthorID01AI       AuthorID = "01.ai"
	AuthorIDBaichuan   AuthorID = "baichuan"
	AuthorIDMiniMax    AuthorID = "minimax"
	AuthorIDMoonshot   AuthorID = "moonshotai"
	AuthorIDShanghaiAI AuthorID = "shanghai-ai-lab"
	AuthorIDZhipuAI    AuthorID = "zhipu-ai"
	AuthorIDSenseTime  AuthorID = "sensetime"
	AuthorIDHuawei     AuthorID = "huawei"
	AuthorIDTsinghua   AuthorID = "tsinghua"
	AuthorIDPeking     AuthorID = "peking"

	// Other Notable Organizations.
	AuthorIDNVIDIA     AuthorID = "nvidia"
	AuthorIDSalesforce AuthorID = "salesforce"
	AuthorIDIBM        AuthorID = "ibm"
	AuthorIDApple      AuthorID = "apple"
	AuthorIDAmazon     AuthorID = "amazon"
	AuthorIDAdept      AuthorID = "adept"
	AuthorIDAI21       AuthorID = "ai21"
	AuthorIDInflection AuthorID = "inflection"
	AuthorIDCharacter  AuthorID = "character"
	AuthorIDPerplexity AuthorID = "perplexity"
	AuthorIDAnysphere  AuthorID = "anysphere"
	AuthorIDCursor     AuthorID = "cursor"

	// Notable Fine-Tuned Model Creators & Publishers.
	AuthorIDCognitiveComputations AuthorID = "cognitivecomputations"
	AuthorIDEricHartford          AuthorID = "ehartford"
	AuthorIDNousResearch          AuthorID = "nousresearch"
	AuthorIDTeknium               AuthorID = "teknium"
	AuthorIDJonDurbin             AuthorID = "jondurbin"
	AuthorIDLMSYS                 AuthorID = "lmsys"
	AuthorIDVicuna                AuthorID = "vicuna-team"
	AuthorIDAlpacaTeam            AuthorID = "stanford-alpaca"
	AuthorIDWizardLM              AuthorID = "wizardlm"
	AuthorIDOpenOrca              AuthorID = "open-orca"
	AuthorIDPhind                 AuthorID = "phind"
	AuthorIDCodeFuse              AuthorID = "codefuse"
	AuthorIDTHUDM                 AuthorID = "thudm"
	AuthorIDGeorgiaTechRI         AuthorID = "gatech"
	AuthorIDFastChat              AuthorID = "fastchat"

	// Special constant for unknown authors.
	AuthorIDUnknown AuthorID = "unknown"
)

Author ID constants for compile-time safety and consistency.

func ParseAuthorID added in v0.0.15 

func ParseAuthorID(s string) AuthorID

ParseAuthorID attempts to parse a string into an AuthorID. It first tries to find the author by exact ID match, then by aliases, and finally normalizes the string if no match is found.

func (AuthorID) String 

func (id AuthorID) String() string

String returns the string representation of an AuthorID.

type AuthorMapping added in v0.0.15 

type AuthorMapping struct {
	Field      string              `yaml:"field" json:"field"`           // Field to extract from (e.g., "owned_by")
	Normalized map[string]AuthorID `yaml:"normalized" json:"normalized"` // Normalization map (e.g., "Meta" -> "meta")
}

AuthorMapping defines how to extract and normalize authors.

type Authors 

type Authors struct {
	// contains filtered or unexported fields
}

Authors is a concurrent safe map of authors.

func NewAuthors 

func NewAuthors(opts ...AuthorsOption) *Authors

NewAuthors creates a new Authors map with optional configuration.

func (*Authors) Add 

func (a *Authors) Add(author *Author) error

Add adds an author, returning an error if it already exists.

func (*Authors) AddBatch 

func (a *Authors) AddBatch(authors []*Author) map[AuthorID]error

AddBatch adds multiple authors in a single operation. Only adds authors that don't already exist - fails if an author ID already exists. Returns a map of author IDs to errors for any failed additions.

func (*Authors) Clear 

func (a *Authors) Clear()

Clear removes all authors.

func (*Authors) Delete 

func (a *Authors) Delete(id AuthorID) error

Delete removes an author by id. Returns an error if the author doesn't exist.

func (*Authors) DeleteBatch 

func (a *Authors) DeleteBatch(ids []AuthorID) map[AuthorID]error

DeleteBatch removes multiple authors by their IDs. Returns a map of errors for authors that couldn't be deleted (not found).

func (*Authors) EncodeYAML added in v0.1.0 

func (a *Authors) EncodeYAML() (string, error)

EncodeYAML returns formatted author YAML or a typed parse error when an author value cannot be represented safely.

func (*Authors) Exists 

func (a *Authors) Exists(id AuthorID) bool

Exists checks if an author exists without returning it.

func (*Authors) ForEach 

func (a *Authors) ForEach(fn func(id AuthorID, author *Author) bool)

ForEach applies a function to each author. The function should not modify the author. If the function returns false, iteration stops early.

func (*Authors) FormatYAML added in v0.0.13 

func (a *Authors) FormatYAML() string

FormatYAML returns the authors as formatted YAML sorted alphabetically by ID.

func (*Authors) Get 

func (a *Authors) Get(id AuthorID) (*Author, bool)

Get returns an author by id and whether it exists.

func (*Authors) Len 

func (a *Authors) Len() int

Len returns the number of authors.

func (*Authors) List 

func (a *Authors) List() []Author

List returns a slice of all authors as values (copies).

func (*Authors) Map 

func (a *Authors) Map() map[AuthorID]*Author

Map returns a copy of all authors.

func (*Authors) Resolve added in v0.0.21 

func (a *Authors) Resolve(id AuthorID) (*Author, bool)

Resolve returns an author by ID or alias. It first tries an exact ID match, then searches all author aliases. This allows commands to accept both canonical IDs and common aliases silently.

func (*Authors) Set 

func (a *Authors) Set(id AuthorID, author *Author) error

Set sets an author by id. Returns an error if author is nil.

func (*Authors) SetBatch 

func (a *Authors) SetBatch(authors map[AuthorID]*Author) error

SetBatch sets multiple authors in a single operation. Overwrites existing authors or adds new ones (upsert behavior). Returns an error if any author is nil.

type AuthorsOption 

type AuthorsOption func(*Authors)

AuthorsOption defines a function that configures an Authors instance.

func WithAuthorsCapacity 

func WithAuthorsCapacity(capacity int) AuthorsOption

WithAuthorsCapacity sets the initial capacity of the authors map.

func WithAuthorsMap 

func WithAuthorsMap(authors map[AuthorID]*Author) AuthorsOption

WithAuthorsMap initializes the map with existing authors.

type AuthorsReader added in v0.1.0 

type AuthorsReader interface {
	Get(AuthorID) (*Author, bool)
	Resolve(AuthorID) (*Author, bool)
	Exists(AuthorID) bool
	Len() int
	List() []Author
	Map() map[AuthorID]*Author
	ForEach(func(AuthorID, *Author) bool)
	FormatYAML() string
}

AuthorsReader exposes author collection reads without mutation methods.

type BootstrapManifest added in v0.1.0 

type BootstrapManifest struct {
	ManifestVersion uint64            `json:"manifest_version" yaml:"manifest_version"`
	GenerationID    string            `json:"generation_id" yaml:"generation_id"`
	GeneratedAt     time.Time         `json:"generated_at" yaml:"generated_at"`
	SchemaVersion   uint64            `json:"schema_version" yaml:"schema_version"`
	Payload         PayloadDescriptor `json:"payload" yaml:"payload"`
}

BootstrapManifest binds the offline embedded catalog to exact canonical catalog bytes and a generation time.

func ParseBootstrapManifestJSON added in v0.1.0 

func ParseBootstrapManifestJSON(data []byte) (BootstrapManifest, error)

ParseBootstrapManifestJSON strictly parses embedded-bootstrap metadata.

func (BootstrapManifest) Validate added in v0.1.0 

func (m BootstrapManifest) Validate() error

Validate checks the embedded-bootstrap metadata contract.

type Builder added in v0.1.0 

type Builder struct {
	// contains filtered or unexported fields
}

Builder is the advanced mutable catalog construction type. It is intended for custom update callbacks, source/plugin authors, and persistence pipelines; ordinary consumers should use the immutable *Catalog returned by *starmap.Client.Catalog. It can work as: - Memory catalog (readFS == nil) - Embedded catalog (readFS is embed.FS) - Files catalog (readFS is os.DirFS) - Custom catalog (readFS is any fs.FS implementation).

func New 

func New(opt Option, opts ...Option) (*Builder, error)

New creates a new builder with the given options WithEmbedded() = embedded catalog with auto-load WithFiles(path) = files catalog with auto-load.

func NewBuilderFrom added in v0.1.0 

func NewBuilderFrom(source Reader) (*Builder, error)

NewBuilderFrom copies source into a new independent builder.

func NewEmbedded 

func NewEmbedded() (*Builder, error)

NewEmbedded creates a catalog backed by embedded files. This is the recommended catalog for production use as it includes all model data compiled into the binary.

func NewEmpty added in v0.0.16 

func NewEmpty() *Builder

NewEmpty creates an in-memory empty catalog. This is useful for testing or temporary catalogs that don't need persistence.

Example: 

catalog := NewEmpty()
provider := Provider{ID: "openai", Models: map[string]Model{}}
catalog.SetProvider(provider)

func NewFromFS 

func NewFromFS(fsys fs.FS, root string) (*Builder, error)

NewFromFS creates a catalog from a custom filesystem implementation. This allows for advanced use cases like virtual filesystems or custom storage backends.

Example: 

var myFS embed.FS
catalog, err := NewFromFS(myFS, "catalog")

func NewFromPath added in v0.0.16 

func NewFromPath(path string) (*Builder, error)

NewFromPath creates a catalog backed by files on disk. This is useful for development when you want to edit catalog files without recompiling the binary.

Example: 

catalog, err := NewFromPath("./internal/embedded/catalog")
if err != nil {
    log.Fatal(err)
}

func NewLocal added in v0.0.15 

func NewLocal(path string) (*Builder, error)

NewLocal creates a catalog by merging embedded catalog with local file. - Always loads embedded catalog (latest provider configs) - Merges with file catalog if path provided and file exists - Returns embedded-only if file doesn't exist or path is empty

This ensures that the catalog always has the latest provider configurations from the embedded catalog, while preserving saved model data from files.

func TestCatalog 

func TestCatalog(t testing.TB) *Builder

TestCatalog creates a test catalog with sample data.

func (*Builder) Author added in v0.1.0 

func (cat *Builder) Author(id AuthorID) (Author, error)

Author returns an author by ID or alias. Silently resolves aliases to canonical author IDs.

func (*Builder) Authors added in v0.1.0 

func (cat *Builder) Authors() AuthorsReader

Authors returns the authors collection.

func (*Builder) Build added in v0.1.0 

func (cat *Builder) Build() (*Catalog, error)

Build publishes an immutable deep copy of the builder's current state.

func (*Builder) ClearProvenance added in v0.1.0 

func (cat *Builder) ClearProvenance()

ClearProvenance removes catalog provenance.

func (*Builder) Copy added in v0.1.0 

func (cat *Builder) Copy() (*Builder, error)

Copy creates a deep copy of the catalog.

func (*Builder) DeleteAuthor added in v0.1.0 

func (cat *Builder) DeleteAuthor(id AuthorID) error

DeleteAuthor deletes an author.

func (*Builder) DeleteEndpoint added in v0.1.0 

func (cat *Builder) DeleteEndpoint(id string) error

DeleteEndpoint deletes an endpoint.

func (*Builder) DeleteProvider added in v0.1.0 

func (cat *Builder) DeleteProvider(id ProviderID) error

DeleteProvider deletes a provider.

func (*Builder) DeleteProviderModel added in v0.1.0 

func (cat *Builder) DeleteProviderModel(providerID ProviderID, modelID string) error

DeleteProviderModel deletes a model from a provider atomically.

func (*Builder) Endpoint added in v0.1.0 

func (cat *Builder) Endpoint(id string) (Endpoint, error)

Endpoint returns an endpoint by ID.

func (*Builder) Endpoints added in v0.1.0 

func (cat *Builder) Endpoints() EndpointsReader

Endpoints returns the endpoints collection.

func (*Builder) FindModel added in v0.1.0 

func (cat *Builder) FindModel(id string) (Model, error)

FindModel searches for a model by ID.

func (*Builder) Load added in v0.1.0 

func (cat *Builder) Load() error

Load loads the catalog from the configured filesystem.

func (*Builder) MergeProvenance added in v0.1.0 

func (cat *Builder) MergeProvenance(value provenance.Map)

MergeProvenance appends catalog provenance.

func (*Builder) MergeStrategy added in v0.1.0 

func (cat *Builder) MergeStrategy() MergeStrategy

MergeStrategy returns the default merge strategy.

func (*Builder) MergeWith added in v0.1.0 

func (cat *Builder) MergeWith(source Reader, opts ...MergeOption) error

MergeWith merges another catalog into this one.

func (*Builder) Models added in v0.1.0 

func (cat *Builder) Models() ModelsReader

Models returns all models from all providers and authors.

func (*Builder) Provenance added in v0.1.0 

func (cat *Builder) Provenance() ProvenanceReader

Provenance returns the provenance collection.

func (*Builder) Provider added in v0.1.0 

func (cat *Builder) Provider(id ProviderID) (Provider, error)

Provider returns a provider by ID or alias. Silently resolves aliases to canonical provider IDs.

func (*Builder) ProviderModel added in v0.1.0 

func (cat *Builder) ProviderModel(providerID ProviderID, modelID string) (Model, error)

ProviderModel returns one provider-specific model offering without flattening equal model IDs from other providers.

func (*Builder) ProviderModels added in v0.1.0 

func (cat *Builder) ProviderModels(id ProviderID) (ModelsReader, error)

ProviderModels returns the models served by a provider or one of its aliases.

func (*Builder) Providers added in v0.1.0 

func (cat *Builder) Providers() ProvidersReader

Providers returns the providers collection.

func (*Builder) ReplaceWith added in v0.1.0 

func (cat *Builder) ReplaceWith(source Reader) error

ReplaceWith replaces this catalog's contents with another.

func (*Builder) Save added in v0.1.0 

func (cat *Builder) Save(opts ...save.Option) error

Save saves the catalog to the configured filesystem.

func (*Builder) SetAuthor added in v0.1.0 

func (cat *Builder) SetAuthor(author Author) error

SetAuthor sets an author (upsert).

func (*Builder) SetEndpoint added in v0.1.0 

func (cat *Builder) SetEndpoint(endpoint Endpoint) error

SetEndpoint sets an endpoint (upsert).

func (*Builder) SetMergeStrategy added in v0.1.0 

func (cat *Builder) SetMergeStrategy(strategy MergeStrategy)

SetMergeStrategy sets the default merge strategy.

func (*Builder) SetProvenance added in v0.1.0 

func (cat *Builder) SetProvenance(value provenance.Map)

SetProvenance replaces catalog provenance.

func (*Builder) SetProvider added in v0.1.0 

func (cat *Builder) SetProvider(provider Provider) error

SetProvider sets a provider (upsert).

func (*Builder) SetProviderModel added in v0.1.0 

func (cat *Builder) SetProviderModel(providerID ProviderID, model Model) error

SetProviderModel sets a model on a provider atomically.

type Catalog 

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog is Starmap's immutable canonical catalog. Its state is unexported, safe to retain across goroutines, and accessible only through read methods.

func NewCatalog added in v0.1.0 

func NewCatalog(source Reader) (*Catalog, error)

NewCatalog copies source into an immutable canonical catalog.

func (*Catalog) Author added in v0.1.0 

func (r *Catalog) Author(id AuthorID) (Author, error)

Author returns a caller-owned copy of an author.

func (*Catalog) Authors added in v0.1.0 

func (r *Catalog) Authors() AuthorsReader

Authors returns the immutable catalog's author collection reader.

func (*Catalog) Definition added in v0.1.0 

func (r *Catalog) Definition(id ModelDefinitionID) (ModelDefinition, error)

Definition returns one caller-owned canonical model definition.

func (*Catalog) Definitions added in v0.1.0 

func (r *Catalog) Definitions() []ModelDefinition

Definitions returns caller-owned canonical definitions in ID order.

func (*Catalog) Endpoint added in v0.1.0 

func (r *Catalog) Endpoint(id string) (Endpoint, error)

Endpoint returns a caller-owned copy of an endpoint.

func (*Catalog) Endpoints added in v0.1.0 

func (r *Catalog) Endpoints() EndpointsReader

Endpoints returns the immutable catalog's endpoint collection reader.

func (*Catalog) FindModel added in v0.1.0 

func (r *Catalog) FindModel(id string) (ModelDefinition, error)

FindModel returns the canonical provider-independent model definition. Use Offering for provider price, limits, availability, and request behavior; use LegacyV0 when migrating code that requires the old flattened Model.

func (*Catalog) LegacyV0 added in v0.1.0 

func (r *Catalog) LegacyV0() LegacyCatalogV0

LegacyV0 returns the concrete schema-v0 compatibility adapter.

func (*Catalog) MaterializeRouteAlias added in v0.1.0 

func (r *Catalog) MaterializeRouteAlias(alias RouteAlias) (RouteAliasResolution, error)

MaterializeRouteAlias resolves current eligibility without storing routing policy in source ingestion or the canonical catalog.

func (*Catalog) Models deprecated added in v0.1.0 

func (r *Catalog) Models() ModelsReader

Models returns the immutable catalog's legacy bare-ID model reader.

Deprecated: use Definition, Offering, ProviderOfferings, or LegacyV0.

func (*Catalog) Offering added in v0.1.0 

func (r *Catalog) Offering(providerID ProviderID, providerModelID ProviderModelID) (ProviderOffering, error)

Offering returns one caller-owned provider-scoped model offering. Provider aliases resolve to their canonical provider before key lookup.

func (*Catalog) Provenance added in v0.1.0 

func (r *Catalog) Provenance() ProvenanceReader

Provenance returns the immutable catalog's provenance reader.

func (*Catalog) Provider added in v0.1.0 

func (r *Catalog) Provider(id ProviderID) (Provider, error)

Provider returns a caller-owned copy of a provider.

func (*Catalog) ProviderModel deprecated added in v0.1.0 

func (r *Catalog) ProviderModel(providerID ProviderID, modelID string) (Model, error)

ProviderModel returns one legacy provider-scoped model record.

Deprecated: use Offering or LegacyV0.

func (*Catalog) ProviderModels deprecated added in v0.1.0 

func (r *Catalog) ProviderModels(id ProviderID) (ModelsReader, error)

ProviderModels returns legacy model records for a provider or alias.

Deprecated: use ProviderOfferings or LegacyV0.

func (*Catalog) ProviderOfferings added in v0.1.0 

func (r *Catalog) ProviderOfferings(providerID ProviderID) ([]ProviderOffering, error)

ProviderOfferings returns caller-owned offerings in provider-model-ID order.

func (*Catalog) Providers added in v0.1.0 

func (r *Catalog) Providers() ProvidersReader

Providers returns the immutable catalog's provider collection reader.

type CatalogPayload added in v0.1.0 

type CatalogPayload struct {
	SchemaVersion  uint64             `json:"schema_version"`
	Providers      []Provider         `json:"providers"`
	Authors        []Author           `json:"authors"`
	Endpoints      []Endpoint         `json:"endpoints"`
	ProviderModels map[string][]Model `json:"provider_models"`
	AuthorModels   map[string][]Model `json:"author_models"`
	Provenance     provenance.Map     `json:"provenance"`
}

CatalogPayload is catalog schema v1's canonical JSON representation. Provider and author models are separate maps because their legacy structs do not serialize runtime model indexes.

type ConsumerCompatibility added in v0.1.0 

type ConsumerCompatibility struct {
	MinSchemaVersion uint64 `json:"min_schema_version" yaml:"min_schema_version"`
	MaxSchemaVersion uint64 `json:"max_schema_version" yaml:"max_schema_version"`
}

ConsumerCompatibility declares the catalog schema versions that can consume this generation. It never refers to a Starmap or Starport binary version.

func (ConsumerCompatibility) SupportsSchema added in v0.1.0 

func (c ConsumerCompatibility) SupportsSchema(schemaVersion uint64) bool

SupportsSchema reports whether a consumer catalog schema is compatible.

type Endpoint 

type Endpoint struct {
	ID          string `json:"id" yaml:"id"`                                       // Unique endpoint identifier
	Name        string `json:"name" yaml:"name"`                                   // Display name (must not be empty)
	Description string `json:"description,omitempty" yaml:"description,omitempty"` // Description of the endpoint and its use cases
}

Endpoint represents an endpoint configuration.

func DeepCopyEndpoint added in v0.1.0 

func DeepCopyEndpoint(endpoint Endpoint) Endpoint

DeepCopyEndpoint creates a copy of an Endpoint.

func TestEndpoint 

func TestEndpoint(t testing.TB) *Endpoint

TestEndpoint creates a test endpoint with sensible defaults.

type EndpointType added in v0.0.15 

type EndpointType string

EndpointType specifies the API style for model listing. 

const (
	// EndpointTypeOpenAI represents OpenAI-compatible API.
	EndpointTypeOpenAI EndpointType = "openai"
	// EndpointTypeAnthropic represents Anthropic API format.
	EndpointTypeAnthropic EndpointType = "anthropic"
	// EndpointTypeGoogle represents Google AI Studio.
	EndpointTypeGoogle EndpointType = "google"
	// EndpointTypeGoogleCloud represents Google Vertex AI.
	EndpointTypeGoogleCloud EndpointType = "google-cloud"
)

type Endpoints 

type Endpoints struct {
	// contains filtered or unexported fields
}

Endpoints is a concurrent safe map of endpoints.

func NewEndpoints 

func NewEndpoints(opts ...EndpointsOption) *Endpoints

NewEndpoints creates a new Endpoints map with optional configuration.

func (*Endpoints) Add 

func (e *Endpoints) Add(endpoint *Endpoint) error

Add adds an endpoint, returning an error if it already exists.

func (*Endpoints) AddBatch 

func (e *Endpoints) AddBatch(endpoints []*Endpoint) map[string]error

AddBatch adds multiple endpoints in a single operation. Only adds endpoints that don't already exist - fails if an endpoint ID already exists. Returns a map of endpoint IDs to errors for any failed additions.

func (*Endpoints) Clear 

func (e *Endpoints) Clear()

Clear removes all endpoints.

func (*Endpoints) Delete 

func (e *Endpoints) Delete(id string) error

Delete removes an endpoint by id. Returns an error if the endpoint doesn't exist.

func (*Endpoints) DeleteBatch 

func (e *Endpoints) DeleteBatch(ids []string) map[string]error

DeleteBatch removes multiple endpoints by their IDs. Returns a map of errors for endpoints that couldn't be deleted (not found).

func (*Endpoints) Exists 

func (e *Endpoints) Exists(id string) bool

Exists checks if an endpoint exists without returning it.

func (*Endpoints) ForEach 

func (e *Endpoints) ForEach(fn func(id string, endpoint *Endpoint) bool)

ForEach applies a function to each endpoint. The function should not modify the endpoint. If the function returns false, iteration stops early.

func (*Endpoints) Get 

func (e *Endpoints) Get(id string) (*Endpoint, bool)

Get returns an endpoint by id and whether it exists.

func (*Endpoints) Len 

func (e *Endpoints) Len() int

Len returns the number of endpoints.

func (*Endpoints) List 

func (e *Endpoints) List() []Endpoint

List returns a slice of all endpoints as values (copies).

func (*Endpoints) Map 

func (e *Endpoints) Map() map[string]*Endpoint

Map returns a copy of all endpoints.

func (*Endpoints) Set 

func (e *Endpoints) Set(id string, endpoint *Endpoint) error

Set sets an endpoint by id. Returns an error if endpoint is nil.

func (*Endpoints) SetBatch 

func (e *Endpoints) SetBatch(endpoints map[string]*Endpoint) error

SetBatch sets multiple endpoints in a single operation. Overwrites existing endpoints or adds new ones (upsert behavior). Returns an error if any endpoint is nil.

type EndpointsOption 

type EndpointsOption func(*Endpoints)

EndpointsOption defines a function that configures an Endpoints instance.

func WithEndpointsCapacity 

func WithEndpointsCapacity(capacity int) EndpointsOption

WithEndpointsCapacity sets the initial capacity of the endpoints map.

func WithEndpointsMap 

func WithEndpointsMap(endpoints map[string]*Endpoint) EndpointsOption

WithEndpointsMap initializes the map with existing endpoints.

type EndpointsReader added in v0.1.0 

type EndpointsReader interface {
	Get(string) (*Endpoint, bool)
	Exists(string) bool
	Len() int
	List() []Endpoint
	Map() map[string]*Endpoint
	ForEach(func(string, *Endpoint) bool)
}

EndpointsReader exposes endpoint collection reads without mutation methods.

type FeatureRule added in v0.0.15 

type FeatureRule struct {
	Field    string   `yaml:"field" json:"field"`       // Field to check (e.g., "id", "owned_by")
	Contains []string `yaml:"contains" json:"contains"` // If field contains any of these strings
	Feature  string   `yaml:"feature" json:"feature"`   // Feature to enable (e.g., "tools", "reasoning")
	Value    bool     `yaml:"value" json:"value"`       // Value to set for the feature
}

FeatureRule defines conditions for inferring model features.

type FieldMapping added in v0.0.15 

type FieldMapping struct {
	From string `yaml:"from" json:"from"` // Source field path in API response (e.g., "max_model_len")
	To   string `yaml:"to" json:"to"`     // Target field path in Model (e.g., "limits.context_window")
}

FieldMapping defines how to map API response fields to model fields. Type conversion is automatic based on the destination field type.

type FloatRange 

type FloatRange struct {
	Min     float64 `json:"min" yaml:"min"`         // Minimum value
	Max     float64 `json:"max" yaml:"max"`         // Maximum value
	Default float64 `json:"default" yaml:"default"` // Default value
}

FloatRange represents a range of float values.

type GenerationCompleteness added in v0.1.0 

type GenerationCompleteness string

GenerationCompleteness describes whether a generation contains every record expected from the observations used to build it. 

const (
	// GenerationCompletenessComplete means the generation contains all expected
	// records. It may still be degraded for another reason, such as stale input.
	GenerationCompletenessComplete GenerationCompleteness = "complete"
	// GenerationCompletenessPartial means at least one expected input or record
	// is absent and the generation must also be marked degraded.
	GenerationCompletenessPartial GenerationCompleteness = "partial"
)

type GenerationManifest added in v0.1.0 

type GenerationManifest struct {
	ManifestVersion       uint64                     `json:"manifest_version" yaml:"manifest_version"`
	SchemaVersion         uint64                     `json:"schema_version" yaml:"schema_version"`
	GenerationID          string                     `json:"generation_id" yaml:"generation_id"`
	GeneratedAt           time.Time                  `json:"generated_at" yaml:"generated_at"`
	Payload               PayloadDescriptor          `json:"payload" yaml:"payload"`
	Validation            GenerationValidationReport `json:"validation" yaml:"validation"`
	SyncRunID             string                     `json:"sync_run_id" yaml:"sync_run_id"`
	SourceObservations    []SourceObservationLink    `json:"source_observations" yaml:"source_observations"`
	Completeness          GenerationCompleteness     `json:"completeness" yaml:"completeness"`
	Degraded              bool                       `json:"degraded" yaml:"degraded"`
	DegradationReasons    []string                   `json:"degradation_reasons,omitempty" yaml:"degradation_reasons,omitempty"`
	ConsumerCompatibility ConsumerCompatibility      `json:"consumer_compatibility" yaml:"consumer_compatibility"`
}

GenerationManifest describes one immutable, validated catalog generation. It is shared by local stores and distribution transports; transport-specific URLs, release tags, and binary versions do not belong in this domain record.

func ParseGenerationManifestJSON added in v0.1.0 

func ParseGenerationManifestJSON(data []byte) (GenerationManifest, error)

ParseGenerationManifestJSON strictly parses and validates a JSON manifest. Unknown members, missing required members (including false/zero-valued members), malformed JSON, and trailing documents are rejected with typed validation errors.

func (GenerationManifest) Copy added in v0.1.0 

func (m GenerationManifest) Copy() GenerationManifest

Copy returns a value whose slices do not alias the original manifest.

func (GenerationManifest) Validate added in v0.1.0 

func (m GenerationManifest) Validate() error

Validate verifies that a manifest is complete and eligible for publication.

type GenerationValidationCheck added in v0.1.0 

type GenerationValidationCheck struct {
	Name    string                          `json:"name" yaml:"name"`
	Status  GenerationValidationCheckStatus `json:"status" yaml:"status"`
	Message string                          `json:"message,omitempty" yaml:"message,omitempty"`
}

GenerationValidationCheck records one deterministic validation decision.

type GenerationValidationCheckStatus added in v0.1.0 

type GenerationValidationCheckStatus string

GenerationValidationCheckStatus is the result of one validation check. 

const (
	// GenerationValidationCheckPassed records a successful check.
	GenerationValidationCheckPassed GenerationValidationCheckStatus = "passed"
	// GenerationValidationCheckWarning records a non-fatal validation warning.
	GenerationValidationCheckWarning GenerationValidationCheckStatus = "warning"
	// GenerationValidationCheckFailed records a failed required check.
	GenerationValidationCheckFailed GenerationValidationCheckStatus = "failed"
)

type GenerationValidationReport added in v0.1.0 

type GenerationValidationReport struct {
	ValidatorVersion string                      `json:"validator_version" yaml:"validator_version"`
	ValidatedAt      time.Time                   `json:"validated_at" yaml:"validated_at"`
	Status           GenerationValidationStatus  `json:"status" yaml:"status"`
	ErrorCount       int                         `json:"error_count" yaml:"error_count"`
	WarningCount     int                         `json:"warning_count" yaml:"warning_count"`
	Checks           []GenerationValidationCheck `json:"checks" yaml:"checks"`
}

GenerationValidationReport records the validator identity and exact outcome that made a candidate eligible (or ineligible) for publication.

type GenerationValidationStatus added in v0.1.0 

type GenerationValidationStatus string

GenerationValidationStatus is the overall result of generation validation. 

const (
	// GenerationValidationPassed means every required validation check passed.
	GenerationValidationPassed GenerationValidationStatus = "passed"
	// GenerationValidationFailed means at least one required check failed. A
	// failed generation is evidence, but is not eligible for publication.
	GenerationValidationFailed GenerationValidationStatus = "failed"
)

type IntRange 

type IntRange struct {
	Min     int `json:"min" yaml:"min"`         // Minimum value
	Max     int `json:"max" yaml:"max"`         // Maximum value
	Default int `json:"default" yaml:"default"` // Default value
}

IntRange represents a range of integer values.

type LegacyCatalogV0 added in v0.1.0 

type LegacyCatalogV0 struct {
	// contains filtered or unexported fields
}

LegacyCatalogV0 is the explicit transition adapter for the pre-split catalog read shape. New consumers should use Catalog.Definition, Catalog.Offering, and Catalog.ProviderOfferings.

func (LegacyCatalogV0) FindModel added in v0.1.0 

func (a LegacyCatalogV0) FindModel(id string) (Model, error)

FindModel returns one legacy flattened bare-ID model record.

func (LegacyCatalogV0) Models added in v0.1.0 

func (a LegacyCatalogV0) Models() ModelsReader

Models returns the legacy flattened bare-ID model collection.

func (LegacyCatalogV0) ProviderModel added in v0.1.0 

func (a LegacyCatalogV0) ProviderModel(providerID ProviderID, modelID string) (Model, error)

ProviderModel returns one legacy provider-scoped model record.

func (LegacyCatalogV0) ProviderModels added in v0.1.0 

func (a LegacyCatalogV0) ProviderModels(id ProviderID) (ModelsReader, error)

ProviderModels returns legacy model records scoped to a provider or alias.

type LegacySchemaMigration added in v0.1.0 

type LegacySchemaMigration struct {
	Definitions map[ModelDefinitionID]ModelDefinition `json:"definitions" yaml:"definitions"`
	Offerings   map[OfferingKey]ProviderOffering      `json:"-" yaml:"-"`
	Report      LegacySchemaMigrationReport           `json:"report" yaml:"report"`
}

LegacySchemaMigration is the loss-accounted result of converting overloaded legacy Model records into canonical definitions and provider offerings.

func MigrateLegacySchema added in v0.1.0 

func MigrateLegacySchema(reader Reader) (*LegacySchemaMigration, error)

MigrateLegacySchema deterministically converts every provider model in a legacy catalog. It never mutates the input and reports every default or conflicting canonical-definition choice.

type LegacySchemaMigrationChange added in v0.1.0 

type LegacySchemaMigrationChange struct {
	Classification MigrationChangeClassification `json:"classification" yaml:"classification"`
	Field          string                        `json:"field" yaml:"field"`
	OfferingKey    OfferingKey                   `json:"offering_key" yaml:"offering_key"`
	Message        string                        `json:"message" yaml:"message"`
}

LegacySchemaMigrationChange is one reviewable legacy-to-definition/offering difference.

type LegacySchemaMigrationReport added in v0.1.0 

type LegacySchemaMigrationReport struct {
	Exact        int                           `json:"exact" yaml:"exact"`
	Defaulted    int                           `json:"defaulted" yaml:"defaulted"`
	Conflicts    int                           `json:"conflicts" yaml:"conflicts"`
	Missing      int                           `json:"missing" yaml:"missing"`
	Unclassified int                           `json:"unclassified" yaml:"unclassified"`
	Changes      []LegacySchemaMigrationChange `json:"changes" yaml:"changes"`
}

LegacySchemaMigrationReport summarizes all classified migration differences.

type MergeOption 

type MergeOption func(*MergeOptions)

MergeOption configures how catalogs are merged.

func WithStrategy 

func WithStrategy(s MergeStrategy) MergeOption

WithStrategy overrides the merge strategy.

type MergeOptions 

type MergeOptions struct {
	Strategy MergeStrategy // nil means use source catalog's suggestion
}

MergeOptions holds merge configuration.

func ParseMergeOptions 

func ParseMergeOptions(opts ...MergeOption) *MergeOptions

ParseMergeOptions processes merge options and returns the configuration.

type MergeStrategy 

type MergeStrategy int

MergeStrategy defines how catalogs should be merged. 

const (
	// MergeEnrichEmpty intelligently merges, preserving existing non-empty values.
	MergeEnrichEmpty MergeStrategy = iota
	// MergeReplaceAll completely replaces the target catalog with the source.
	MergeReplaceAll
	// MergeAppendOnly only adds new items, skips existing ones.
	MergeAppendOnly
)

type MigrationChangeClassification added in v0.1.0 

type MigrationChangeClassification string

MigrationChangeClassification describes how a legacy field was transformed. 

const (
	// MigrationChangeExact means the value moved without semantic change.
	MigrationChangeExact MigrationChangeClassification = "exact"
	// MigrationChangeDefaulted means the legacy schema had no value and a documented default was used.
	MigrationChangeDefaulted MigrationChangeClassification = "defaulted"
	// MigrationChangeConflict means multiple legacy records disagreed and deterministic precedence was applied.
	MigrationChangeConflict MigrationChangeClassification = "conflict"
	// MigrationChangeMissing means the legacy corpus had no authoritative value and none was invented.
	MigrationChangeMissing MigrationChangeClassification = "missing"
)

type Model 

type Model struct {
	// Core identity
	ID          string      `json:"id" yaml:"id"`                                       // Unique model identifier
	Name        string      `json:"name" yaml:"name"`                                   // Display name (must not be empty)
	Authors     []Author    `json:"authors,omitempty" yaml:"authors,omitempty"`         // Authors/organizations of the model (if known)
	Description string      `json:"description,omitempty" yaml:"description,omitempty"` // Description of the model and its use cases
	Status      ModelStatus `json:"status,omitempty" yaml:"status,omitempty"`           // Lifecycle status such as active, beta, preview, or deprecated

	// Metadata - version and timing information
	Metadata *ModelMetadata `json:"metadata,omitempty" yaml:"metadata,omitempty"` // Metadata for the model

	// Lineage - model family and derivation information
	Lineage *ModelLineage `json:"lineage,omitempty" yaml:"lineage,omitempty"`

	// Features - what this model can do
	Features *ModelFeatures `json:"features,omitempty" yaml:"features,omitempty"`

	// Attachments - attachment support details
	Attachments *ModelAttachments `json:"attachments,omitempty" yaml:"attachments,omitempty"`

	// Generation - core chat completions generation controls
	Generation *ModelGeneration `json:"generation,omitempty" yaml:"generation,omitempty"`

	// Reasoning - reasoning effort levels
	Reasoning *ModelControlLevels `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`

	// ReasoningTokens - specific token allocation for reasoning processes
	ReasoningTokens *IntRange `json:"reasoning_tokens,omitempty" yaml:"reasoning_tokens,omitempty"`

	// Verbosity - response verbosity levels
	Verbosity *ModelControlLevels `json:"verbosity,omitempty" yaml:"verbosity,omitempty"`

	// Tools - external tool and capability integrations
	Tools *ModelTools `json:"tools,omitempty" yaml:"tools,omitempty"`

	// Delivery - technical response delivery capabilities (formats, protocols, streaming)
	Delivery *ModelDelivery `json:"response,omitempty" yaml:"response,omitempty"`

	// Modes - alternate service modes such as fast/priority variants
	Modes map[string]ModelMode `json:"modes,omitempty" yaml:"modes,omitempty"`

	// Operational characteristics
	Pricing *ModelPricing `json:"pricing,omitempty" yaml:"pricing,omitempty"` // Optional pricing information
	Limits  *ModelLimits  `json:"limits,omitempty" yaml:"limits,omitempty"`   // Model limits

	// Extensions - controlled source-specific fields that are not canonical schema
	Extensions SourceExtensions `json:"extensions,omitempty" yaml:"extensions,omitempty"`

	// Timestamps for record keeping and auditing
	CreatedAt utc.Time `json:"created_at" yaml:"created_at"` // Created date (YYYY-MM or YYYY-MM-DD format)
	UpdatedAt utc.Time `json:"updated_at" yaml:"updated_at"` // Last updated date (YYYY-MM or YYYY-MM-DD format)
}

Model represents a model configuration.

func DeepCopyModel added in v0.1.0 

func DeepCopyModel(model Model) Model

DeepCopyModel creates a deep copy of a Model.

func MergeModels 

func MergeModels(existing, updated Model) Model

MergeModels performs a smart merge of two models, keeping existing values where the updated model has empty/nil values.

func TestModel 

func TestModel(t testing.TB) *Model

TestModel creates a test model with sensible defaults.

func TestModelWithOptions 

func TestModelWithOptions(t testing.TB, opts ...TestModelOption) *Model

TestModelWithOptions creates a test model with custom options.

func (*Model) EncodeYAML added in v0.1.0 

func (m *Model) EncodeYAML() (string, error)

EncodeYAML returns formatted YAML or a typed parse error when model values cannot be represented safely.

func (*Model) FormatYAML 

func (m *Model) FormatYAML() string

FormatYAML returns a well-formatted YAML representation with comments and proper structure.

func (*Model) FormatYAMLHeaderComment 

func (m *Model) FormatYAMLHeaderComment() string

FormatYAMLHeaderComment returns a descriptive string for the model header comment.

type ModelArchitecture 

type ModelArchitecture struct {
	ParameterCount string           `json:"parameter_count,omitempty" yaml:"parameter_count,omitempty"` // Model size (e.g., "7B", "70B", "405B")
	Type           ArchitectureType `json:"type,omitempty" yaml:"type,omitempty"`                       // Type of architecture
	Tokenizer      Tokenizer        `json:"tokenizer,omitempty" yaml:"tokenizer,omitempty"`             // Tokenizer type used by the model
	Precision      *string          `json:"precision,omitempty" yaml:"precision,omitempty"`             // Legacy precision format (use Quantization for filtering)
	Quantization   Quantization     `json:"quantization,omitempty" yaml:"quantization,omitempty"`       // Quantization level used by the model
	Quantized      bool             `json:"quantized" yaml:"quantized"`                                 // Whether the model has been quantized
	FineTuned      bool             `json:"fine_tuned" yaml:"fine_tuned"`                               // Whether this is a fine-tuned variant
	BaseModel      *string          `json:"base_model,omitempty" yaml:"base_model,omitempty"`           // Base model ID if fine-tuned
}

ModelArchitecture represents the technical architecture details of a model.

type ModelAttachments 

type ModelAttachments struct {
	MimeTypes   []string `json:"mime_types,omitempty" yaml:"mime_types,omitempty"`       // Supported MIME types
	MaxFileSize *int64   `json:"max_file_size,omitempty" yaml:"max_file_size,omitempty"` // Maximum file size in bytes
	MaxFiles    *int     `json:"max_files,omitempty" yaml:"max_files,omitempty"`         // Maximum number of files per request
}

ModelAttachments represents the attachment capabilities of a model.

type ModelControlLevel 

type ModelControlLevel string

ModelControlLevel represents an effort/intensity level for model controls. 

const (
	ModelControlLevelMinimum ModelControlLevel = "minimum"
	ModelControlLevelLow     ModelControlLevel = "low"
	ModelControlLevelMedium  ModelControlLevel = "medium"
	ModelControlLevelHigh    ModelControlLevel = "high"
	ModelControlLevelMaximum ModelControlLevel = "maximum"
)

Supported model control levels.

func (ModelControlLevel) String 

func (mcl ModelControlLevel) String() string

String returns the string representation of a ModelControlLevel.

type ModelControlLevels 

type ModelControlLevels struct {
	Levels  []ModelControlLevel `json:"levels" yaml:"levels"`   // Which levels this model supports
	Default *ModelControlLevel  `json:"default" yaml:"default"` // Default level
}

ModelControlLevels represents a set of effort/intensity levels for model controls.

type ModelDefinition added in v0.1.0 

type ModelDefinition struct {
	ID           ModelDefinitionID           `json:"id" yaml:"id"`
	Name         string                      `json:"name" yaml:"name"`
	AuthorIDs    []AuthorID                  `json:"author_ids" yaml:"author_ids"`
	Description  string                      `json:"description,omitempty" yaml:"description,omitempty"`
	Metadata     ModelDefinitionMetadata     `json:"metadata" yaml:"metadata"`
	Lineage      ModelDefinitionLineage      `json:"lineage" yaml:"lineage"`
	Weights      ModelDefinitionWeights      `json:"weights" yaml:"weights"`
	Capabilities ModelDefinitionCapabilities `json:"capabilities" yaml:"capabilities"`
	CreatedAt    utc.Time                    `json:"created_at" yaml:"created_at"`
	UpdatedAt    utc.Time                    `json:"updated_at" yaml:"updated_at"`
}

ModelDefinition is the canonical provider-independent description of a model. Provider service facts belong to ProviderOffering, never this record.

func (ModelDefinition) Validate added in v0.1.0 

func (d ModelDefinition) Validate() error

Validate verifies canonical identity and authorship invariants.

type ModelDefinitionCapabilities added in v0.1.0 

type ModelDefinitionCapabilities struct {
	Features        *ModelFeatures      `json:"features,omitempty" yaml:"features,omitempty"`
	Attachments     *ModelAttachments   `json:"attachments,omitempty" yaml:"attachments,omitempty"`
	Generation      *ModelGeneration    `json:"generation,omitempty" yaml:"generation,omitempty"`
	Reasoning       *ModelControlLevels `json:"reasoning,omitempty" yaml:"reasoning,omitempty"`
	ReasoningTokens *IntRange           `json:"reasoning_tokens,omitempty" yaml:"reasoning_tokens,omitempty"`
	Verbosity       *ModelControlLevels `json:"verbosity,omitempty" yaml:"verbosity,omitempty"`
	Tools           *ModelTools         `json:"tools,omitempty" yaml:"tools,omitempty"`
	Delivery        *ModelDelivery      `json:"delivery,omitempty" yaml:"delivery,omitempty"`
}

ModelDefinitionCapabilities groups intrinsic model behavior independently of any provider's service limits, price, endpoint, or availability.

type ModelDefinitionID added in v0.1.0 

type ModelDefinitionID string

ModelDefinitionID identifies one provider-independent model definition.

type ModelDefinitionLineage added in v0.1.0 

type ModelDefinitionLineage struct {
	Family string             `json:"family,omitempty" yaml:"family,omitempty"`
	Root   *ModelDefinitionID `json:"root,omitempty" yaml:"root,omitempty"`
	Parent *ModelDefinitionID `json:"parent,omitempty" yaml:"parent,omitempty"`
}

ModelDefinitionLineage describes canonical model-family relationships.

type ModelDefinitionMetadata added in v0.1.0 

type ModelDefinitionMetadata struct {
	ReleaseDate     utc.Time   `json:"release_date" yaml:"release_date"`
	KnowledgeCutoff *utc.Time  `json:"knowledge_cutoff,omitempty" yaml:"knowledge_cutoff,omitempty"`
	Tags            []ModelTag `json:"tags,omitempty" yaml:"tags,omitempty"`
}

ModelDefinitionMetadata contains provider-independent release and discovery metadata.

type ModelDefinitionWeights added in v0.1.0 

type ModelDefinitionWeights struct {
	Open         bool               `json:"open" yaml:"open"`
	Architecture *ModelArchitecture `json:"architecture,omitempty" yaml:"architecture,omitempty"`
}

ModelDefinitionWeights describes provider-independent model weights and architecture.

type ModelDelivery 

type ModelDelivery struct {
	// Response delivery mechanisms
	Protocols []ModelResponseProtocol `json:"protocols,omitempty" yaml:"protocols,omitempty"` // Supported delivery protocols (HTTP, gRPC, etc.)
	Streaming []ModelStreaming        `json:"streaming,omitempty" yaml:"streaming,omitempty"` // Supported streaming modes (sse, websocket, chunked)
	Formats   []ModelResponseFormat   `json:"formats,omitempty" yaml:"formats,omitempty"`     // Available response formats (if format_response feature enabled)
}

ModelDelivery represents technical response delivery capabilities.

type ModelFeatures 

type ModelFeatures struct {
	// Input/Output modalities
	Modalities ModelModalities `json:"modalities" yaml:"modalities"` // Supported input/output modalities

	// Core capabilities
	// Tool calling system - three distinct aspects:
	ToolCalls   bool `json:"tool_calls" yaml:"tool_calls"`   // Can invoke/call tools in responses (model outputs tool_calls)
	Tools       bool `json:"tools" yaml:"tools"`             // Accepts tool definitions in requests (accepts tools parameter)
	ToolChoice  bool `json:"tool_choice" yaml:"tool_choice"` // Supports tool choice strategies (auto/none/required control)
	WebSearch   bool `json:"web_search" yaml:"web_search"`   // Supports web search capabilities
	Attachments bool `json:"attachments" yaml:"attachments"` // Attachment support details

	// Reasoning & Verbosity
	Reasoning        bool `json:"reasoning" yaml:"reasoning"`                 // Supports basic reasoning
	ReasoningEffort  bool `json:"reasoning_effort" yaml:"reasoning_effort"`   // Supports configurable reasoning intensity
	ReasoningTokens  bool `json:"reasoning_tokens" yaml:"reasoning_tokens"`   // Supports specific reasoning token allocation
	IncludeReasoning bool `json:"include_reasoning" yaml:"include_reasoning"` // Supports including reasoning traces in response
	Verbosity        bool `json:"verbosity" yaml:"verbosity"`                 // Supports verbosity control (GPT-5+)

	// Generation control - Core sampling and decoding
	Temperature bool `json:"temperature" yaml:"temperature"` // [Core] Supports temperature parameter
	TopP        bool `json:"top_p" yaml:"top_p"`             // [Core] Supports top_p parameter (nucleus sampling)
	TopK        bool `json:"top_k" yaml:"top_k"`             // [Advanced] Supports top_k parameter
	TopA        bool `json:"top_a" yaml:"top_a"`             // [Advanced] Supports top_a parameter (top-a sampling)
	MinP        bool `json:"min_p" yaml:"min_p"`             // [Advanced] Supports min_p parameter (minimum probability threshold)
	TypicalP    bool `json:"typical_p" yaml:"typical_p"`     // [Advanced] Supports typical_p parameter (typical sampling)
	TFS         bool `json:"tfs" yaml:"tfs"`                 // [Advanced] Supports tail free sampling

	// Generation control - Length and termination
	MaxTokens       bool `json:"max_tokens" yaml:"max_tokens"`               // [Core] Supports max_tokens parameter
	MaxOutputTokens bool `json:"max_output_tokens" yaml:"max_output_tokens"` // [Core] Supports max_output_tokens parameter (some providers distinguish from max_tokens)
	Stop            bool `json:"stop" yaml:"stop"`                           // [Core] Supports stop sequences/words
	StopTokenIDs    bool `json:"stop_token_ids" yaml:"stop_token_ids"`       // [Advanced] Supports stop token IDs (numeric)

	// Generation control - Repetition control
	FrequencyPenalty  bool `json:"frequency_penalty" yaml:"frequency_penalty"`       // [Core] Supports frequency penalty
	PresencePenalty   bool `json:"presence_penalty" yaml:"presence_penalty"`         // [Core] Supports presence penalty
	RepetitionPenalty bool `json:"repetition_penalty" yaml:"repetition_penalty"`     // [Advanced] Supports repetition penalty
	NoRepeatNgramSize bool `json:"no_repeat_ngram_size" yaml:"no_repeat_ngram_size"` // [Niche] Supports n-gram repetition blocking
	LengthPenalty     bool `json:"length_penalty" yaml:"length_penalty"`             // [Niche] Supports length penalty (seq2seq style)

	// Generation control - Token biasing
	LogitBias     bool `json:"logit_bias" yaml:"logit_bias"`         // [Core] Supports token-level bias adjustment
	BadWords      bool `json:"bad_words" yaml:"bad_words"`           // [Advanced] Supports bad words/disallowed tokens
	AllowedTokens bool `json:"allowed_tokens" yaml:"allowed_tokens"` // [Niche] Supports token whitelist

	// Generation control - Determinism
	Seed bool `json:"seed" yaml:"seed"` // [Advanced] Supports deterministic seeding

	// Generation control - Observability
	Logprobs    bool `json:"logprobs" yaml:"logprobs"`         // [Core] Supports returning log probabilities
	TopLogprobs bool `json:"top_logprobs" yaml:"top_logprobs"` // [Core] Supports returning top N log probabilities
	Echo        bool `json:"echo" yaml:"echo"`                 // [Advanced] Supports echoing prompt with completion

	// Generation control - Multiplicity and reranking
	N      bool `json:"n" yaml:"n"`             // [Advanced] Supports generating multiple candidates
	BestOf bool `json:"best_of" yaml:"best_of"` // [Advanced] Supports server-side sampling with best selection

	// Generation control - Alternative sampling strategies (niche)
	Mirostat                      bool `json:"mirostat" yaml:"mirostat"`                                                 // [Niche] Supports Mirostat sampling
	MirostatTau                   bool `json:"mirostat_tau" yaml:"mirostat_tau"`                                         // [Niche] Supports Mirostat tau parameter
	MirostatEta                   bool `json:"mirostat_eta" yaml:"mirostat_eta"`                                         // [Niche] Supports Mirostat eta parameter
	ContrastiveSearchPenaltyAlpha bool `json:"contrastive_search_penalty_alpha" yaml:"contrastive_search_penalty_alpha"` // [Niche] Supports contrastive decoding

	// Generation control - Beam search (niche)
	NumBeams         bool `json:"num_beams" yaml:"num_beams"`                 // [Niche] Supports beam search
	EarlyStopping    bool `json:"early_stopping" yaml:"early_stopping"`       // [Niche] Supports early stopping in beam search
	DiversityPenalty bool `json:"diversity_penalty" yaml:"diversity_penalty"` // [Niche] Supports diversity penalty in beam search

	// Response delivery
	FormatResponse    bool `json:"format_response" yaml:"format_response"`       // Supports alternative response formats (beyond text)
	StructuredOutputs bool `json:"structured_outputs" yaml:"structured_outputs"` // Supports structured outputs (JSON schema validation)
	Streaming         bool `json:"streaming" yaml:"streaming"`                   // Supports response streaming

}

ModelFeatures represents a set of feature flags that describe what a model can do.

type ModelGeneration 

type ModelGeneration struct {
	// Core sampling and decoding
	Temperature *FloatRange `json:"temperature,omitempty" yaml:"temperature,omitempty"`
	TopP        *FloatRange `json:"top_p,omitempty" yaml:"top_p,omitempty"`
	TopK        *IntRange   `json:"top_k,omitempty" yaml:"top_k,omitempty"`
	TopA        *FloatRange `json:"top_a,omitempty" yaml:"top_a,omitempty"`
	MinP        *FloatRange `json:"min_p,omitempty" yaml:"min_p,omitempty"`
	TypicalP    *FloatRange `json:"typical_p,omitempty" yaml:"typical_p,omitempty"`
	TFS         *FloatRange `json:"tfs,omitempty" yaml:"tfs,omitempty"`

	// Length and termination
	MaxTokens       *int `json:"max_tokens,omitempty" yaml:"max_tokens,omitempty"`
	MaxOutputTokens *int `json:"max_output_tokens,omitempty" yaml:"max_output_tokens,omitempty"`

	// Repetition control
	FrequencyPenalty  *FloatRange `json:"frequency_penalty,omitempty" yaml:"frequency_penalty,omitempty"`
	PresencePenalty   *FloatRange `json:"presence_penalty,omitempty" yaml:"presence_penalty,omitempty"`
	RepetitionPenalty *FloatRange `json:"repetition_penalty,omitempty" yaml:"repetition_penalty,omitempty"`
	NoRepeatNgramSize *IntRange   `json:"no_repeat_ngram_size,omitempty" yaml:"no_repeat_ngram_size,omitempty"`
	LengthPenalty     *FloatRange `json:"length_penalty,omitempty" yaml:"length_penalty,omitempty"`

	// Observability
	TopLogprobs *int `json:"top_logprobs,omitempty" yaml:"top_logprobs,omitempty"` // Number of top log probabilities to return

	// Multiplicity and reranking
	N      *IntRange `json:"n,omitempty" yaml:"n,omitempty"`             // Number of candidates to generate
	BestOf *IntRange `json:"best_of,omitempty" yaml:"best_of,omitempty"` // Server-side sampling with best selection

	// Alternative sampling strategies (niche)
	MirostatTau                   *FloatRange `json:"mirostat_tau,omitempty" yaml:"mirostat_tau,omitempty"`
	MirostatEta                   *FloatRange `json:"mirostat_eta,omitempty" yaml:"mirostat_eta,omitempty"`
	ContrastiveSearchPenaltyAlpha *FloatRange `json:"contrastive_search_penalty_alpha,omitempty" yaml:"contrastive_search_penalty_alpha,omitempty"`

	// Beam search (niche)
	NumBeams         *IntRange   `json:"num_beams,omitempty" yaml:"num_beams,omitempty"`
	DiversityPenalty *FloatRange `json:"diversity_penalty,omitempty" yaml:"diversity_penalty,omitempty"`
}

ModelGeneration - core chat completions generation controls.

type ModelLimits 

type ModelLimits struct {
	ContextWindow int64 `json:"context_window" yaml:"context_window"` // Context window size in tokens
	InputTokens   int64 `json:"input_tokens" yaml:"input_tokens"`     // Maximum input tokens
	OutputTokens  int64 `json:"output_tokens" yaml:"output_tokens"`   // Maximum output tokens
}

ModelLimits represents the limits for a model.

type ModelLineage added in v0.1.0 

type ModelLineage struct {
	Family string  `json:"family,omitempty" yaml:"family,omitempty"` // Model family or series, such as gpt-5 or claude
	Root   *string `json:"root,omitempty" yaml:"root,omitempty"`     // Root/base model ID reported by a provider
	Parent *string `json:"parent,omitempty" yaml:"parent,omitempty"` // Parent model ID for derived/fine-tuned models
}

ModelLineage represents model family and derivation metadata.

type ModelMetadata 

type ModelMetadata struct {
	ReleaseDate     utc.Time           `json:"release_date" yaml:"release_date"`                             // Release date (YYYY-MM or YYYY-MM-DD format)
	OpenWeights     bool               `json:"open_weights" yaml:"open_weights"`                             // Whether model weights are open
	KnowledgeCutoff *utc.Time          `json:"knowledge_cutoff,omitempty" yaml:"knowledge_cutoff,omitempty"` // Knowledge cutoff date (YYYY-MM or YYYY-MM-DD format)
	Tags            []ModelTag         `json:"tags,omitempty" yaml:"tags,omitempty"`                         // Use case tags for categorizing the model
	Architecture    *ModelArchitecture `json:"architecture,omitempty" yaml:"architecture,omitempty"`         // Technical architecture details
}

ModelMetadata represents the metadata for a model.

type ModelModalities 

type ModelModalities struct {
	Input  []ModelModality `json:"input" yaml:"input"`   // Supported input modalities
	Output []ModelModality `json:"output" yaml:"output"` // Supported output modalities
}

ModelModalities represents the input/output modalities supported by a model.

type ModelModality 

type ModelModality string

ModelModality represents a supported input or output modality for AI models. 

const (
	ModelModalityText      ModelModality = "text"
	ModelModalityAudio     ModelModality = "audio"
	ModelModalityImage     ModelModality = "image"
	ModelModalityVideo     ModelModality = "video"
	ModelModalityPDF       ModelModality = "pdf"
	ModelModalityEmbedding ModelModality = "embedding" // Vector embeddings
)

Supported model modalities.

func (ModelModality) String 

func (m ModelModality) String() string

String returns the string representation of a ModelModality.

type ModelMode added in v0.1.0 

type ModelMode struct {
	Pricing  *ModelPricing      `json:"pricing,omitempty" yaml:"pricing,omitempty"`   // Mode-specific pricing
	Provider *ModelProviderMode `json:"provider,omitempty" yaml:"provider,omitempty"` // Mode-specific provider request overrides
}

ModelMode represents an alternate provider service mode for a model.

type ModelOperationPricing 

type ModelOperationPricing struct {
	// Core operations
	Request *float64 `json:"request,omitempty" yaml:"request,omitempty"` // Cost per API request

	// Media operations
	ImageInput *float64 `json:"image_input,omitempty" yaml:"image_input,omitempty"` // Cost per image processed
	AudioInput *float64 `json:"audio_input,omitempty" yaml:"audio_input,omitempty"` // Cost per audio input
	VideoInput *float64 `json:"video_input,omitempty" yaml:"video_input,omitempty"` // Cost per video input

	// Generation operations
	ImageGen *float64 `json:"image_gen,omitempty" yaml:"image_gen,omitempty"` // Cost per image generated
	AudioGen *float64 `json:"audio_gen,omitempty" yaml:"audio_gen,omitempty"` // Cost per audio generated
	VideoGen *float64 `json:"video_gen,omitempty" yaml:"video_gen,omitempty"` // Cost per video generated

	// Service operations
	WebSearch    *float64 `json:"web_search,omitempty" yaml:"web_search,omitempty"`       // Cost per web search
	FunctionCall *float64 `json:"function_call,omitempty" yaml:"function_call,omitempty"` // Cost per function call
	ToolUse      *float64 `json:"tool_use,omitempty" yaml:"tool_use,omitempty"`           // Cost per tool usage
}

ModelOperationPricing represents fixed costs for operations.

type ModelPricing 

type ModelPricing struct {
	// Token-based costs
	Tokens *ModelTokenPricing `json:"tokens,omitempty" yaml:"tokens,omitempty"`

	// Fixed costs per operation
	Operations *ModelOperationPricing `json:"operations,omitempty" yaml:"operations,omitempty"`

	// Conditional/tiered pricing
	Tiers []ModelPricingTier `json:"tiers,omitempty" yaml:"tiers,omitempty"`

	// Metadata
	Currency ModelPricingCurrency `json:"currency" yaml:"currency"` // "USD", "EUR", etc.

	// Optional half-open validity interval [effective_from, effective_until).
	EffectiveFrom  *utc.Time `json:"effective_from,omitempty" yaml:"effective_from,omitempty"`
	EffectiveUntil *utc.Time `json:"effective_until,omitempty" yaml:"effective_until,omitempty"`
}

ModelPricing represents the pricing structure for a model.

func (*ModelPricing) IsEffectiveAt added in v0.1.0 

func (p *ModelPricing) IsEffectiveAt(at time.Time) bool

IsEffectiveAt reports whether pricing applies at the supplied instant.

func (*ModelPricing) Validate added in v0.1.0 

func (p *ModelPricing) Validate() error

Validate verifies that pricing is structurally complete and financially safe to use as an authoritative provider-offering observation.

type ModelPricingCurrency 

type ModelPricingCurrency string

ModelPricingCurrency represents a currency code for model pricing. 

const (
	// ModelPricingCurrencyUSD is the US Dollar currency constant.
	ModelPricingCurrencyUSD ModelPricingCurrency = "USD" // US Dollar
	// ModelPricingCurrencyEUR is the Euro currency constant.
	ModelPricingCurrencyEUR ModelPricingCurrency = "EUR" // Euro
	// ModelPricingCurrencyJPY is the Japanese Yen currency constant.
	ModelPricingCurrencyJPY ModelPricingCurrency = "JPY" // Japanese Yen
	// ModelPricingCurrencyGBP is the British Pound Sterling currency constant.
	ModelPricingCurrencyGBP ModelPricingCurrency = "GBP" // British Pound Sterling
	// ModelPricingCurrencyAUD is the Australian Dollar currency constant.
	ModelPricingCurrencyAUD ModelPricingCurrency = "AUD" // Australian Dollar
	// ModelPricingCurrencyCAD is the Canadian Dollar currency constant.
	ModelPricingCurrencyCAD ModelPricingCurrency = "CAD" // Canadian Dollar
	// ModelPricingCurrencyCNY is the Chinese Yuan currency constant.
	ModelPricingCurrencyCNY ModelPricingCurrency = "CNY" // Chinese Yuan
	// ModelPricingCurrencyNZD is the New Zealand Dollar currency constant.
	ModelPricingCurrencyNZD ModelPricingCurrency = "NZD" // New Zealand Dollar
)

func (ModelPricingCurrency) String 

func (m ModelPricingCurrency) String() string

String returns the string representation of a ModelPricingCurrency.

func (ModelPricingCurrency) Symbol 

func (m ModelPricingCurrency) Symbol() string

Symbol returns the symbol for a given currency.

type ModelPricingTier added in v0.1.0 

type ModelPricingTier struct {
	Name       string                 `json:"name,omitempty" yaml:"name,omitempty"`             // Optional source/name, such as context_over_200k
	Type       ModelPricingTierType   `json:"type" yaml:"type"`                                 // Tier dimension, such as context
	Size       int64                  `json:"size,omitempty" yaml:"size,omitempty"`             // Threshold size for the tier dimension
	Tokens     *ModelTokenPricing     `json:"tokens,omitempty" yaml:"tokens,omitempty"`         // Token prices in this tier
	Operations *ModelOperationPricing `json:"operations,omitempty" yaml:"operations,omitempty"` // Operation prices in this tier
}

ModelPricingTier represents conditional pricing for a model.

type ModelPricingTierType added in v0.1.0 

type ModelPricingTierType string

ModelPricingTierType represents the dimension that activates a pricing tier. 

const (
	// ModelPricingTierTypeContext means the tier applies above a context-size threshold.
	ModelPricingTierTypeContext ModelPricingTierType = "context"
)

func (ModelPricingTierType) String added in v0.1.0 

func (m ModelPricingTierType) String() string

String returns the string representation of a ModelPricingTierType.

type ModelProviderMode added in v0.1.0 

type ModelProviderMode struct {
	Headers map[string]string `json:"headers,omitempty" yaml:"headers,omitempty"` // HTTP headers required by this mode
	Body    map[string]any    `json:"body,omitempty" yaml:"body,omitempty"`       // JSON request body fields required by this mode
}

ModelProviderMode represents provider request overrides for a model mode.

type ModelResponseFormat 

type ModelResponseFormat string

ModelResponseFormat represents a supported response format. 

const (
	// Basic formats.
	ModelResponseFormatText ModelResponseFormat = "text" // Plain text responses (default)

	// JSON formats.
	ModelResponseFormatJSON       ModelResponseFormat = "json"        // JSON encouraged via prompting
	ModelResponseFormatJSONMode   ModelResponseFormat = "json_mode"   // Forced valid JSON (OpenAI style)
	ModelResponseFormatJSONObject ModelResponseFormat = "json_object" // Same as json_mode (OpenAI API name)

	// Structured formats.
	ModelResponseFormatJSONSchema       ModelResponseFormat = "json_schema"       // Schema-validated JSON (OpenAI structured output)
	ModelResponseFormatStructuredOutput ModelResponseFormat = "structured_output" // General structured output support

	// Function calling (alternative to JSON schema).
	ModelResponseFormatFunctionCall ModelResponseFormat = "function_call" // Tool/function calling for structured data
)

Model response formats.

func (ModelResponseFormat) String 

func (mrf ModelResponseFormat) String() string

String returns the string representation of a ModelResponseFormat.

type ModelResponseProtocol 

type ModelResponseProtocol string

ModelResponseProtocol represents a supported delivery protocol. 

const (
	ModelResponseProtocolHTTP      ModelResponseProtocol = "http"      // HTTP/HTTPS REST API
	ModelResponseProtocolGRPC      ModelResponseProtocol = "grpc"      // gRPC protocol
	ModelResponseProtocolWebSocket ModelResponseProtocol = "websocket" // WebSocket protocol
)

Model delivery protocols.

type ModelStatus added in v0.1.0 

type ModelStatus string

ModelStatus represents a model lifecycle or availability state. 

const (
	ModelStatusActive     ModelStatus = "active"
	ModelStatusBeta       ModelStatus = "beta"
	ModelStatusPreview    ModelStatus = "preview"
	ModelStatusDeprecated ModelStatus = "deprecated"
	ModelStatusUnknown    ModelStatus = "unknown"
)

Model lifecycle states.

func (ModelStatus) String added in v0.1.0 

func (ms ModelStatus) String() string

String returns the string representation of a ModelStatus.

type ModelStreaming 

type ModelStreaming string

ModelStreaming represents how responses can be delivered. 

const (
	ModelStreamingSSE       ModelStreaming = "sse"       // Server-Sent Events streaming
	ModelStreamingWebSocket ModelStreaming = "websocket" // WebSocket streaming
	ModelStreamingChunked   ModelStreaming = "chunked"   // HTTP chunked transfer encoding
)

Model streaming modes.

func (ModelStreaming) String 

func (ms ModelStreaming) String() string

String returns the string representation of a ModelStreaming.

type ModelTag 

type ModelTag string

ModelTag represents a use case or category tag for models. 

const (
	// Core Use Cases.
	ModelTagCoding    ModelTag = "coding"    // Programming and code generation
	ModelTagWriting   ModelTag = "writing"   // Creative and technical writing
	ModelTagReasoning ModelTag = "reasoning" // Logical reasoning and problem solving
	ModelTagMath      ModelTag = "math"      // Mathematical problem solving
	ModelTagChat      ModelTag = "chat"      // Conversational AI
	ModelTagInstruct  ModelTag = "instruct"  // Instruction following
	ModelTagResearch  ModelTag = "research"  // Research and analysis
	ModelTagCreative  ModelTag = "creative"  // Creative content generation
	ModelTagRoleplay  ModelTag = "roleplay"  // Character roleplay and simulation

	// Technical Capabilities.
	ModelTagFunctionCalling ModelTag = "function_calling"   // Tool/function calling
	ModelTagEmbedding       ModelTag = "embedding"          // Text embeddings
	ModelTagSummarization   ModelTag = "summarization"      // Text summarization
	ModelTagTranslation     ModelTag = "translation"        // Language translation
	ModelTagQA              ModelTag = "question_answering" // Question answering

	// Modality-Specific.
	ModelTagVision       ModelTag = "vision"         // Computer vision
	ModelTagMultimodal   ModelTag = "multimodal"     // Multiple input modalities
	ModelTagAudio        ModelTag = "audio"          // Audio processing
	ModelTagTextToImage  ModelTag = "text_to_image"  // Text-to-image generation
	ModelTagTextToSpeech ModelTag = "text_to_speech" // Text-to-speech synthesis
	ModelTagSpeechToText ModelTag = "speech_to_text" // Speech recognition
	ModelTagImageToText  ModelTag = "image_to_text"  // Image captioning/OCR

	// Domain-Specific.
	ModelTagMedical   ModelTag = "medical"   // Medical and healthcare
	ModelTagLegal     ModelTag = "legal"     // Legal document processing
	ModelTagFinance   ModelTag = "finance"   // Financial analysis
	ModelTagScience   ModelTag = "science"   // Scientific applications
	ModelTagEducation ModelTag = "education" // Educational content
)

Model tags for categorizing models by use case and capabilities.

func (ModelTag) String 

func (tag ModelTag) String() string

String returns the string representation of a ModelTag.

type ModelTokenCachePricing 

type ModelTokenCachePricing struct {
	Read  *ModelTokenCost `json:"read,omitempty" yaml:"read,omitempty"`   // Cache read costs
	Write *ModelTokenCost `json:"write,omitempty" yaml:"write,omitempty"` // Cache write costs
}

ModelTokenCachePricing represents cache-specific pricing.

type ModelTokenCost 

type ModelTokenCost struct {
	PerToken float64 `json:"per_token" yaml:"per_token"`  // Cost per individual token
	Per1M    float64 `json:"per_1m_tokens" yaml:"per_1m"` // Cost per 1M tokens
}

ModelTokenCost represents cost per token with flexible units.

func (*ModelTokenCost) MarshalYAML 

func (t *ModelTokenCost) MarshalYAML() (any, error)

MarshalYAML implements custom YAML marshaling for TokenCost to format decimals consistently.

type ModelTokenPricing 

type ModelTokenPricing struct {
	// Core tokens
	Input  *ModelTokenCost `json:"input,omitempty" yaml:"input,omitempty"`   // Input/prompt tokens
	Output *ModelTokenCost `json:"output,omitempty" yaml:"output,omitempty"` // Standard output tokens

	// Advanced token types
	Reasoning *ModelTokenCost         `json:"reasoning,omitempty" yaml:"reasoning,omitempty"` // Internal reasoning tokens
	Cache     *ModelTokenCachePricing `json:"cache,omitempty" yaml:"cache,omitempty"`         // Cache operations

	// Alternative flat cache structure (for backward compatibility)
	CacheRead  *ModelTokenCost `json:"cache_read,omitempty" yaml:"cache_read,omitempty"`   // Cache read costs (flat structure)
	CacheWrite *ModelTokenCost `json:"cache_write,omitempty" yaml:"cache_write,omitempty"` // Cache write costs (flat structure)
}

ModelTokenPricing represents all token-based costs.

func (*ModelTokenPricing) MarshalYAML 

func (t *ModelTokenPricing) MarshalYAML() (any, error)

MarshalYAML implements custom YAML marshaling for TokenPricing to use flat cache structure.

type ModelTools 

type ModelTools struct {
	// Tool calling configuration
	// Specifies which tool choice strategies this model supports.
	// Requires both Tools=true and ToolChoice=true in ModelFeatures.
	// Common values: ["auto"], ["auto", "none"], ["auto", "none", "required"]
	ToolChoices []ToolChoice `json:"tool_choices,omitempty" yaml:"tool_choices,omitempty"` // Supported tool choice strategies

	// Web search configuration
	// Only applicable if WebSearch=true in ModelFeatures
	WebSearch *ModelWebSearch `json:"web_search,omitempty" yaml:"web_search,omitempty"`
}

ModelTools represents external tool and capability integrations.

type ModelWebSearch 

type ModelWebSearch struct {
	// Plugin-based web search options (for models using OpenRouter's web plugin)
	MaxResults   *int    `json:"max_results,omitempty" yaml:"max_results,omitempty"`     // Maximum number of search results (defaults to 5)
	SearchPrompt *string `json:"search_prompt,omitempty" yaml:"search_prompt,omitempty"` // Custom prompt for search results

	// Built-in web search options (for models with native web search like GPT-4.1, Perplexity)
	SearchContextSizes []ModelControlLevel `json:"search_context_sizes,omitempty" yaml:"search_context_sizes,omitempty"` // Supported context sizes (low, medium, high)
	DefaultContextSize *ModelControlLevel  `json:"default_context_size,omitempty" yaml:"default_context_size,omitempty"` // Default search context size
}

ModelWebSearch represents web search configuration for search-enabled models.

type Models 

type Models struct {
	// contains filtered or unexported fields
}

Models is a concurrent safe map of models.

func NewModels added in v0.0.15 

func NewModels() *Models

NewModels creates a new Models instance.

func (*Models) Add 

func (m *Models) Add(model *Model) error

Add adds a model, returning an error if it already exists.

func (*Models) AddBatch 

func (m *Models) AddBatch(models []*Model) map[string]error

AddBatch adds multiple models in a single operation. Only adds models that don't already exist - fails if a model ID already exists. Returns a map of model IDs to errors for any failed additions.

func (*Models) Clear 

func (m *Models) Clear()

Clear removes all models.

func (*Models) Delete 

func (m *Models) Delete(id string) error

Delete removes a model by id. Returns an error if the model doesn't exist.

func (*Models) DeleteBatch 

func (m *Models) DeleteBatch(ids []string) map[string]error

DeleteBatch removes multiple models by their IDs. Returns a map of errors for models that couldn't be deleted (not found).

func (*Models) Exists 

func (m *Models) Exists(id string) bool

Exists checks if a model exists without returning it.

func (*Models) ForEach 

func (m *Models) ForEach(fn func(id string, model *Model) bool)

ForEach applies a function to each model. The function should not modify the model. If the function returns false, iteration stops early.

func (*Models) Get 

func (m *Models) Get(id string) (*Model, bool)

Get returns a model by id and whether it exists.

func (*Models) Len 

func (m *Models) Len() int

Len returns the number of models.

func (*Models) List 

func (m *Models) List() []Model

List returns a slice of all models as values (copies).

func (*Models) Map 

func (m *Models) Map() map[string]*Model

Map returns a copy of all models.

func (*Models) Set 

func (m *Models) Set(id string, model *Model) error

Set sets a model by id. Returns an error if model is nil.

func (*Models) SetBatch 

func (m *Models) SetBatch(models map[string]*Model) error

SetBatch sets multiple models in a single operation. Overwrites existing models or adds new ones (upsert behavior). Returns an error if any model is nil.

type ModelsReader added in v0.1.0 

type ModelsReader interface {
	Get(string) (*Model, bool)
	Exists(string) bool
	Len() int
	List() []Model
	Map() map[string]*Model
	ForEach(func(string, *Model) bool)
}

ModelsReader exposes model collection reads without mutation methods.

type OfferingAvailability added in v0.1.0 

type OfferingAvailability string

OfferingAvailability describes whether an offering can currently be used. 

const (
	// OfferingAvailabilityAvailable means the offering is generally available.
	OfferingAvailabilityAvailable OfferingAvailability = "available"
	// OfferingAvailabilityRestricted means access depends on region, account, or allowlisting.
	OfferingAvailabilityRestricted OfferingAvailability = "restricted"
	// OfferingAvailabilityUnavailable means the provider does not currently serve the offering.
	OfferingAvailabilityUnavailable OfferingAvailability = "unavailable"
)

type OfferingKey added in v0.1.0 

type OfferingKey struct {
	ProviderID      ProviderID      `json:"provider_id" yaml:"provider_id"`
	ProviderModelID ProviderModelID `json:"provider_model_id" yaml:"provider_model_id"`
}

OfferingKey is the globally unique identity of a provider model offering.

type OfferingLifecycle added in v0.1.0 

type OfferingLifecycle string

OfferingLifecycle describes the provider-specific lifecycle of an offering. 

const (
	// OfferingLifecycleActive means the offering is supported for production use.
	OfferingLifecycleActive OfferingLifecycle = "active"
	// OfferingLifecyclePreview means the offering is preview or beta quality.
	OfferingLifecyclePreview OfferingLifecycle = "preview"
	// OfferingLifecycleDeprecated means callers should migrate away from the offering.
	OfferingLifecycleDeprecated OfferingLifecycle = "deprecated"
	// OfferingLifecycleRetired means the provider no longer accepts new requests.
	OfferingLifecycleRetired OfferingLifecycle = "retired"
)

type OfferingRequestBody added in v0.1.0 

type OfferingRequestBody map[string]json.RawMessage

OfferingRequestBody is a typed set of exact JSON request-body values. RawMessage preserves booleans, numbers, strings, arrays, objects, and null without routing values through map[string]any.

type OfferingRequestHeaders added in v0.1.0 

type OfferingRequestHeaders map[string]string

OfferingRequestHeaders is a typed set of provider request header overrides.

type Option 

type Option func(*options)

Option configures a catalog.

func WithEmbedded 

func WithEmbedded() Option

WithEmbedded configures the catalog to use embedded files.

func WithFS 

func WithFS(fsys fs.FS) Option

WithFS configures the catalog to use a custom fs.FS for reading.

func WithMergeStrategy 

func WithMergeStrategy(strategy MergeStrategy) Option

WithMergeStrategy sets the default merge strategy.

func WithPath 

func WithPath(path string) Option

WithPath configures the catalog to use a directory path for reading This creates an os.DirFS under the hood.

func WithWritePath 

func WithWritePath(path string) Option

WithWritePath sets a specific path for writing catalog files.

type PayloadDescriptor added in v0.1.0 

type PayloadDescriptor struct {
	Checksum  string `json:"checksum" yaml:"checksum"`
	SizeBytes int64  `json:"size_bytes" yaml:"size_bytes"`
	MediaType string `json:"media_type" yaml:"media_type"`
}

PayloadDescriptor binds a generation manifest to exact immutable bytes.

func DescribeCatalogPayload added in v0.1.0 

func DescribeCatalogPayload(payload []byte) PayloadDescriptor

DescribeCatalogPayload returns the descriptor for canonical catalog bytes.

func (PayloadDescriptor) Verify added in v0.1.0 

func (d PayloadDescriptor) Verify(payload []byte) error

Verify checks that payload exactly matches the descriptor.

type Provenance added in v0.0.23 

type Provenance struct {
	// contains filtered or unexported fields
}

Provenance is a concurrent-safe container for provenance data. It follows the same pattern as Authors, Models, and Providers containers, using RWMutex for thread safety and returning deep copies to prevent external modification.

func NewProvenance added in v0.0.23 

func NewProvenance(opts ...ProvenanceOption) *Provenance

NewProvenance creates a new Provenance container with optional configuration.

func (*Provenance) Clear added in v0.0.23 

func (p *Provenance) Clear()

Clear removes all provenance data.

func (*Provenance) EncodeYAML added in v0.1.0 

func (p *Provenance) EncodeYAML() (string, error)

EncodeYAML returns provenance YAML or a typed parse error when evidence values cannot be represented safely.

func (*Provenance) FindByField added in v0.0.23 

func (p *Provenance) FindByField(resourceType catalogmeta.ResourceType, resourceID string, field string) []provenance.Provenance

FindByField retrieves provenance for a specific field of a resource. Returns nil if no provenance is found.

func (*Provenance) FindByResource added in v0.0.23 

func (p *Provenance) FindByResource(resourceType catalogmeta.ResourceType, resourceID string) map[string][]provenance.Provenance

FindByResource retrieves all provenance for a resource. Returns a map of field names to their provenance entries.

func (*Provenance) FormatYAML added in v0.0.23 

func (p *Provenance) FormatYAML() string

FormatYAML returns the provenance data formatted as YAML. This follows the same pattern as Authors and Providers containers.

func (*Provenance) Len added in v0.0.23 

func (p *Provenance) Len() int

Len returns the number of provenance entries.

func (*Provenance) Map added in v0.0.23 

func (p *Provenance) Map() provenance.Map

Map returns a deep copy of the provenance map. This ensures thread safety by preventing external modification of internal state.

func (*Provenance) Merge added in v0.0.23 

func (p *Provenance) Merge(m provenance.Map)

Merge adds new provenance entries to existing data. This appends to existing keys rather than replacing them.

func (*Provenance) Set added in v0.0.23 

func (p *Provenance) Set(m provenance.Map)

Set replaces the entire provenance map with new data. The input map is deep copied to prevent external modification.

type ProvenanceOption added in v0.0.23 

type ProvenanceOption func(*Provenance)

ProvenanceOption defines a function that configures a Provenance instance.

type ProvenanceReader added in v0.1.0 

type ProvenanceReader interface {
	Map() provenance.Map
	Len() int
	FindByField(catalogmeta.ResourceType, string, string) []provenance.Provenance
	FindByResource(catalogmeta.ResourceType, string) map[string][]provenance.Provenance
	FormatYAML() string
}

ProvenanceReader exposes provenance reads without mutation methods.

type Provider 

type Provider struct {
	// Core identification and integration
	ID           ProviderID   `json:"id" yaml:"id"`                                         // Unique provider identifier
	Aliases      []ProviderID `json:"aliases,omitempty" yaml:"aliases,omitempty"`           // Alternative IDs this provider is known by (e.g., in models.dev)
	Name         string       `json:"name" yaml:"name"`                                     // Display name (must not be empty)
	Headquarters *string      `json:"headquarters,omitempty" yaml:"headquarters,omitempty"` // Company headquarters location
	IconURL      *string      `json:"icon_url,omitempty" yaml:"icon_url,omitempty"`         // Provider icon/logo URL

	// API key configuration
	APIKey *ProviderAPIKey `json:"api_key,omitempty" yaml:"api_key,omitempty"` // API key configuration

	// Environment variables configuration
	EnvVars []ProviderEnvVar `json:"env_vars,omitempty" yaml:"env_vars,omitempty"` // Required environment variables

	// Models
	Catalog *ProviderCatalog  `json:"catalog,omitempty" yaml:"catalog,omitempty"` // Models catalog configuration
	Models  map[string]*Model `json:"-" yaml:"-"`                                 // Available models indexed by model ID - not serialized to YAML

	// Status & Health
	StatusPageURL   *string                  `json:"status_page_url,omitempty" yaml:"status_page_url,omitempty"`   // Link to service status page
	ChatCompletions *ProviderChatCompletions `json:"chat_completions,omitempty" yaml:"chat_completions,omitempty"` // Chat completions API configuration

	// Privacy, Retention, and Governance Policies
	PrivacyPolicy    *ProviderPrivacyPolicy    `json:"privacy_policy,omitempty" yaml:"privacy_policy,omitempty"`       // Data collection and usage practices
	RetentionPolicy  *ProviderRetentionPolicy  `json:"retention_policy,omitempty" yaml:"retention_policy,omitempty"`   // Data retention and deletion practices
	GovernancePolicy *ProviderGovernancePolicy `json:"governance_policy,omitempty" yaml:"governance_policy,omitempty"` // Oversight and moderation practices

	// Extensions - controlled source-specific fields that are not canonical schema
	Extensions SourceExtensions `json:"extensions,omitempty" yaml:"extensions,omitempty"`

	EnvVarValues map[string]string `json:"-" yaml:"-"` // Actual environment variable values loaded at runtime
	// contains filtered or unexported fields
}

Provider represents a provider configuration.

func DeepCopyProvider added in v0.0.15 

func DeepCopyProvider(provider Provider) Provider

DeepCopyProvider creates a deep copy of a Provider including its Models map.

func TestProvider 

func TestProvider(t testing.TB) *Provider

TestProvider creates a test provider with sensible defaults. The t.Helper() call ensures stack traces point to the test, not this function.

func TestProviderWithOptions 

func TestProviderWithOptions(t testing.TB, opts ...TestProviderOption) *Provider

TestProviderWithOptions creates a test provider with custom options.

func (*Provider) APIKeyValue 

func (p *Provider) APIKeyValue() (string, error)

APIKeyValue retrieves and validates the API key for this provider. Uses the loaded apiKeyValue if available, otherwise falls back to environment.

func (*Provider) CatalogEndpointURL added in v0.1.0 

func (p *Provider) CatalogEndpointURL() string

CatalogEndpointURL returns the resolved model catalog endpoint URL.

func (*Provider) EnvVar 

func (p *Provider) EnvVar(name string) string

EnvVar returns the value of a specific environment variable.

func (*Provider) HasAPIKey 

func (p *Provider) HasAPIKey() bool

HasAPIKey checks if the provider has a valid API key configured. This checks both existence and validation (pattern matching).

func (*Provider) HasRequiredEnvVars 

func (p *Provider) HasRequiredEnvVars() bool

HasRequiredEnvVars checks if all required environment variables are set.

func (*Provider) IsAPIKeyRequired 

func (p *Provider) IsAPIKeyRequired() bool

IsAPIKeyRequired checks if a provider requires an API key.

func (*Provider) LoadAPIKey 

func (p *Provider) LoadAPIKey()

LoadAPIKey loads the API key value from environment into the provider. This should be called when the provider is loaded from the catalog.

func (*Provider) LoadEnvVars 

func (p *Provider) LoadEnvVars()

LoadEnvVars loads environment variable values from the system into the provider. This should be called when the provider is loaded from the catalog.

func (*Provider) MissingRequiredEnvVars added in v0.0.15 

func (p *Provider) MissingRequiredEnvVars() []string

MissingRequiredEnvVars returns a list of required environment variables that are not set.

func (*Provider) Model 

func (p *Provider) Model(modelID string) (*Model, error)

Model retrieves a specific model from the provider.

func (*Provider) Validate 

func (p *Provider) Validate(supportedProviders map[ProviderID]bool) ProviderValidationResult

Validate performs validation checks on this provider and returns the result. The supportedProviders parameter is a set of provider IDs that have client implementations.

type ProviderAPIKey 

type ProviderAPIKey struct {
	Name       string               `json:"name" yaml:"name"`               // Name of the API key parameter
	Pattern    string               `json:"pattern" yaml:"pattern"`         // Glob pattern to match the API key
	Header     string               `json:"header" yaml:"header"`           // Header name to send the API key in
	Scheme     ProviderAPIKeyScheme `json:"scheme" yaml:"scheme"`           // Authentication scheme (e.g., "Bearer", "Basic", or empty for direct value)
	QueryParam string               `json:"query_param" yaml:"query_param"` // Query parameter name to send the API key in
}

ProviderAPIKey represents configuration for an API key to access a provider's catalog.

type ProviderAPIKeyScheme 

type ProviderAPIKeyScheme string

ProviderAPIKeyScheme represents different authentication schemes for API keys. 

const (
	ProviderAPIKeySchemeBearer ProviderAPIKeyScheme = "Bearer" // Bearer token authentication (OAuth 2.0 style)
	ProviderAPIKeySchemeBasic  ProviderAPIKeyScheme = "Basic"  // Basic authentication
	ProviderAPIKeySchemeDirect ProviderAPIKeyScheme = ""       // Direct value (no scheme prefix)
)

API key authentication schemes.

func (ProviderAPIKeyScheme) String 

func (paks ProviderAPIKeyScheme) String() string

String returns the string representation of a ProviderAPIKeyScheme.

type ProviderCatalog 

type ProviderCatalog struct {
	Docs     *string          `yaml:"docs" json:"docs"`                           // Documentation URL
	Endpoint ProviderEndpoint `yaml:"endpoint" json:"endpoint"`                   // API endpoint configuration
	Authors  []AuthorID       `json:"authors,omitempty" yaml:"authors,omitempty"` // List of authors to fetch from (for providers like Google Vertex AI)
}

ProviderCatalog represents information about a provider's models.

type ProviderChatCompletions 

type ProviderChatCompletions struct {
	URL              *string                   `json:"url,omitempty" yaml:"url,omitempty"`                             // Chat completions API endpoint URL
	HealthAPIURL     *string                   `json:"health_api_url,omitempty" yaml:"health_api_url,omitempty"`       // URL to health/status API for this service
	HealthComponents []ProviderHealthComponent `json:"health_components,omitempty" yaml:"health_components,omitempty"` // Specific components to monitor for chat completions
}

ProviderChatCompletions represents configuration for chat completions API.

type ProviderEndpoint added in v0.0.15 

type ProviderEndpoint struct {
	Type          EndpointType   `yaml:"type" json:"type"`                                             // Required: API style
	URL           string         `yaml:"url" json:"url"`                                               // Required: API endpoint
	BaseURLEnvVar string         `yaml:"base_url_env_var,omitempty" json:"base_url_env_var,omitempty"` // Optional env var for overriding the endpoint base URL
	Path          string         `yaml:"path,omitempty" json:"path,omitempty"`                         // Path appended when BaseURLEnvVar is set
	AuthRequired  bool           `yaml:"auth_required" json:"auth_required"`                           // Required: Whether auth needed
	FieldMappings []FieldMapping `yaml:"field_mappings,omitempty" json:"field_mappings,omitempty"`     // Field mappings
	FeatureRules  []FeatureRule  `yaml:"feature_rules,omitempty" json:"feature_rules,omitempty"`       // Feature inference rules
	AuthorMapping *AuthorMapping `yaml:"author_mapping,omitempty" json:"author_mapping,omitempty"`     // Author extraction
}

ProviderEndpoint configures how to access the provider's model catalog.

type ProviderEnvVar 

type ProviderEnvVar struct {
	Name        string `json:"name" yaml:"name"`                                   // Environment variable name
	Required    bool   `json:"required" yaml:"required"`                           // Whether this env var is required
	Description string `json:"description,omitempty" yaml:"description,omitempty"` // Human-readable description
	Pattern     string `json:"pattern,omitempty" yaml:"pattern,omitempty"`         // Optional validation pattern
}

ProviderEnvVar represents an environment variable required by a provider.

type ProviderGovernancePolicy 

type ProviderGovernancePolicy struct {
	ModerationRequired *bool   `json:"moderation_required,omitempty" yaml:"moderation_required,omitempty"` // Whether the provider requires moderation
	Moderated          *bool   `json:"moderated,omitempty" yaml:"moderated,omitempty"`                     // Whether provider content is moderated
	Moderator          *string `json:"moderator,omitempty" yaml:"moderator,omitempty"`                     // Who moderates the provider
}

ProviderGovernancePolicy represents oversight and moderation practices.

type ProviderHealthComponent 

type ProviderHealthComponent struct {
	ID   string `json:"id" yaml:"id"`                         // Component ID from the health API
	Name string `json:"name,omitempty" yaml:"name,omitempty"` // Human-readable component name
}

ProviderHealthComponent represents a specific component to monitor in a provider's health API.

type ProviderID 

type ProviderID string

ProviderID represents a provider identifier type for compile-time safety. 

const (
	ProviderIDAlibabaQwen    ProviderID = "alibaba"
	ProviderIDAlibabaCloud   ProviderID = "alibaba"
	ProviderIDAnthropic      ProviderID = "anthropic"
	ProviderIDAnyscale       ProviderID = "anyscale"
	ProviderIDCerebras       ProviderID = "cerebras"
	ProviderIDCheckstep      ProviderID = "checkstep"
	ProviderIDCohere         ProviderID = "cohere"
	ProviderIDConectys       ProviderID = "conectys"
	ProviderIDCove           ProviderID = "cove"
	ProviderIDDeepMind       ProviderID = "deepmind"
	ProviderIDDeepInfra      ProviderID = "deepinfra"
	ProviderIDDeepSeek       ProviderID = "deepseek"
	ProviderIDFireworksAI    ProviderID = "fireworks-ai"
	ProviderIDGoogleAIStudio ProviderID = "google-ai-studio"
	ProviderIDGoogleVertex   ProviderID = "google-vertex"
	ProviderIDGroq           ProviderID = "groq"
	ProviderIDHuggingFace    ProviderID = "huggingface"
	ProviderIDMeta           ProviderID = "meta"
	ProviderIDMicrosoft      ProviderID = "microsoft"
	ProviderIDMistralAI      ProviderID = "mistral"
	ProviderIDMoonshotAI     ProviderID = "moonshot-ai"
	ProviderIDOpenAI         ProviderID = "openai"
	ProviderIDOpenRouter     ProviderID = "openrouter"
	ProviderIDPerplexity     ProviderID = "perplexity"
	ProviderIDReplicate      ProviderID = "replicate"
	ProviderIDSafetyKit      ProviderID = "safetykit"
	ProviderIDTogetherAI     ProviderID = "together"
	ProviderIDVirtuousAI     ProviderID = "virtuousai"
	ProviderIDWebPurify      ProviderID = "webpurify"
	ProviderIDXAI            ProviderID = "xai"
)

Provider ID constants for compile-time safety and consistency.

func (ProviderID) String 

func (pid ProviderID) String() string

String returns the string representation of a ProviderID.

type ProviderModelID added in v0.1.0 

type ProviderModelID string

ProviderModelID is the exact opaque model identifier accepted by a provider.

type ProviderModerator 

type ProviderModerator string

ProviderModerator represents a moderator for a provider. 

const (
	// AI Platform Aggregators/Moderators.
	ProviderModeratorAnyscale    ProviderModerator = "anyscale"
	ProviderModeratorHuggingFace ProviderModerator = "huggingface"
	ProviderModeratorOpenRouter  ProviderModerator = "openrouter"
	ProviderModeratorReplicate   ProviderModerator = "replicate"
	ProviderModeratorTogetherAI  ProviderModerator = "together"

	// Specialized AI Safety/Moderation Companies.
	ProviderModeratorCheckstep  ProviderModerator = "checkstep"
	ProviderModeratorConectys   ProviderModerator = "conectys"
	ProviderModeratorCove       ProviderModerator = "cove"
	ProviderModeratorSafetyKit  ProviderModerator = "safetykit"
	ProviderModeratorVirtuousAI ProviderModerator = "virtuousai"
	ProviderModeratorWebPurify  ProviderModerator = "webpurify"

	// Self-Moderated (Major AI Companies).
	ProviderModeratorAnthropic      ProviderModerator = "anthropic"
	ProviderModeratorGoogleAIStudio ProviderModerator = "google-ai-studio"
	ProviderModeratorGoogleVertex   ProviderModerator = "google-vertex"
	ProviderModeratorGroq           ProviderModerator = "groq"
	ProviderModeratorMicrosoft      ProviderModerator = "microsoft"
	ProviderModeratorOpenAI         ProviderModerator = "openai"

	// Unknown/Unspecified.
	ProviderModeratorUnknown ProviderModerator = "unknown"
)

ProviderModerators.

func (ProviderModerator) String 

func (pm ProviderModerator) String() string

String returns the string representation of a ProviderModerator.

type ProviderOffering added in v0.1.0 

type ProviderOffering struct {
	ProviderID      ProviderID                      `json:"provider_id" yaml:"provider_id"`
	ProviderModelID ProviderModelID                 `json:"provider_model_id" yaml:"provider_model_id"`
	DefinitionID    ModelDefinitionID               `json:"definition_id" yaml:"definition_id"`
	Pricing         *ModelPricing                   `json:"pricing,omitempty" yaml:"pricing,omitempty"`
	Limits          *ModelLimits                    `json:"limits,omitempty" yaml:"limits,omitempty"`
	Availability    OfferingAvailability            `json:"availability" yaml:"availability"`
	Regions         []string                        `json:"regions,omitempty" yaml:"regions,omitempty"`
	Endpoint        ProviderOfferingEndpoint        `json:"endpoint" yaml:"endpoint,omitempty"`
	Lifecycle       OfferingLifecycle               `json:"lifecycle" yaml:"lifecycle"`
	Modes           map[string]ProviderOfferingMode `json:"modes,omitempty" yaml:"modes,omitempty"`
}

ProviderOffering is one provider's service contract for a model definition. Provider-specific price, limits, availability, regions, lifecycle, endpoint, modes, and request overrides live here rather than on the definition.

func (ProviderOffering) Key added in v0.1.0 

func (o ProviderOffering) Key() OfferingKey

Key returns the provider-scoped immutable offering identity.

func (ProviderOffering) Validate added in v0.1.0 

func (o ProviderOffering) Validate() error

Validate verifies required identity and provider-specific fields.

type ProviderOfferingEndpoint added in v0.1.0 

type ProviderOfferingEndpoint struct {
	Type    EndpointType `json:"type,omitempty" yaml:"type,omitempty"`
	BaseURL string       `json:"base_url,omitempty" yaml:"base_url,omitempty"`
	Path    string       `json:"path,omitempty" yaml:"path,omitempty"`
}

ProviderOfferingEndpoint describes provider-specific inference endpoint behavior.

type ProviderOfferingMode added in v0.1.0 

type ProviderOfferingMode struct {
	Pricing *ModelPricing            `json:"pricing,omitempty" yaml:"pricing,omitempty"`
	Limits  *ModelLimits             `json:"limits,omitempty" yaml:"limits,omitempty"`
	Request ProviderRequestOverrides `json:"request" yaml:"request,omitempty"`
}

ProviderOfferingMode describes one named service mode for an offering.

type ProviderPrivacyPolicy 

type ProviderPrivacyPolicy struct {
	PrivacyPolicyURL  *string `json:"privacy_policy_url,omitempty" yaml:"privacy_policy_url,omitempty"`     // Link to privacy policy
	TermsOfServiceURL *string `json:"terms_of_service_url,omitempty" yaml:"terms_of_service_url,omitempty"` // Link to terms of service
	RetainsData       *bool   `json:"retains_data,omitempty" yaml:"retains_data,omitempty"`                 // Whether provider stores/retains user data
	TrainsOnData      *bool   `json:"trains_on_data,omitempty" yaml:"trains_on_data,omitempty"`             // Whether provider trains models on user data
}

ProviderPrivacyPolicy represents data collection and usage practices.

type ProviderRequestOverrides added in v0.1.0 

type ProviderRequestOverrides struct {
	Headers OfferingRequestHeaders `json:"headers,omitempty" yaml:"headers,omitempty"`
	Body    OfferingRequestBody    `json:"body,omitempty" yaml:"body,omitempty"`
}

ProviderRequestOverrides contains provider-specific inference request changes.

type ProviderRetentionPolicy 

type ProviderRetentionPolicy struct {
	Type     ProviderRetentionType `json:"type" yaml:"type"`                             // Type of retention policy
	Duration *time.Duration        `json:"duration,omitempty" yaml:"duration,omitempty"` // nil = forever, 0 = immediate deletion
	Details  *string               `json:"details,omitempty" yaml:"details,omitempty"`   // Human-readable description
}

ProviderRetentionPolicy represents how long data is kept and deletion practices.

type ProviderRetentionType 

type ProviderRetentionType string

ProviderRetentionType represents different types of data retention policies. 

const (
	ProviderRetentionTypeFixed       ProviderRetentionType = "fixed"       // Specific duration (use Duration field)
	ProviderRetentionTypeNone        ProviderRetentionType = "none"        // No retention (immediate deletion)
	ProviderRetentionTypeIndefinite  ProviderRetentionType = "indefinite"  // Forever (duration = nil)
	ProviderRetentionTypeConditional ProviderRetentionType = "conditional" // Based on conditions (e.g., "until account deletion")
)

ProviderRetention types.

func (ProviderRetentionType) String 

func (prt ProviderRetentionType) String() string

String returns the string representation of a ProviderRetentionType.

type ProviderValidationEntry 

type ProviderValidationEntry struct {
	Provider     *Provider
	HasAPIKey    bool
	IsRequired   bool
	IsConfigured bool
	Error        error
}

ProviderValidationEntry represents the validation status of a single provider.

type ProviderValidationReport 

type ProviderValidationReport struct {
	Configured  []ProviderValidationEntry // Providers with configured API keys
	Missing     []ProviderValidationEntry // Providers missing required API keys
	Optional    []ProviderValidationEntry // Providers with optional or no API key requirement
	Unsupported []ProviderValidationEntry // Providers without client implementation
}

ProviderValidationReport contains the results of validating provider access.

func ValidateAllProviders 

func ValidateAllProviders(catalog Reader, supportedProviders []ProviderID) (*ProviderValidationReport, error)

ValidateAllProviders checks all providers in the catalog for API key availability. This helps users understand which providers they can use based on their configuration. The supportedProviders parameter should be a list of provider IDs that have client implementations.

func (*ProviderValidationReport) Print 

func (r *ProviderValidationReport) Print()

Print outputs a formatted report of provider validation status.

type ProviderValidationResult 

type ProviderValidationResult struct {
	Status             ProviderValidationStatus `json:"status"`
	HasAPIKey          bool                     `json:"has_api_key"`
	IsAPIKeyRequired   bool                     `json:"is_api_key_required"`
	HasRequiredEnvVars bool                     `json:"has_required_env_vars"`
	MissingEnvVars     []string                 `json:"missing_env_vars,omitempty"`
	IsConfigured       bool                     `json:"is_configured"`
	IsSupported        bool                     `json:"is_supported"`
	Error              error                    `json:"error,omitempty"`
}

ProviderValidationResult contains the result of validating a provider.

type ProviderValidationStatus 

type ProviderValidationStatus string

ProviderValidationStatus represents the validation status of a provider. 

const (
	// ProviderValidationStatusConfigured indicates the provider is properly configured and ready to use.
	ProviderValidationStatusConfigured ProviderValidationStatus = "configured"
	// ProviderValidationStatusMissing indicates the provider is missing required API key configuration.
	ProviderValidationStatusMissing ProviderValidationStatus = "missing"
	// ProviderValidationStatusOptional indicates the provider has optional API key that is not configured (still usable).
	ProviderValidationStatusOptional ProviderValidationStatus = "optional"
	// ProviderValidationStatusUnsupported indicates the provider doesn't have client implementation yet.
	ProviderValidationStatusUnsupported ProviderValidationStatus = "unsupported"
)

func (ProviderValidationStatus) String 

func (pvs ProviderValidationStatus) String() string

String returns the string representation of ProviderValidationStatus.

type Providers 

type Providers struct {
	// contains filtered or unexported fields
}

Providers is a concurrent safe map of providers.

func NewProviders 

func NewProviders(opts ...ProvidersOption) *Providers

NewProviders creates a new Providers map with optional configuration.

func (*Providers) Add 

func (p *Providers) Add(provider *Provider) error

Add adds a provider, returning an error if it already exists.

func (*Providers) AddBatch 

func (p *Providers) AddBatch(providers []*Provider) map[ProviderID]error

AddBatch adds multiple providers in a single operation. Only adds providers that don't already exist - fails if a provider ID already exists. Returns a map of provider IDs to errors for any failed additions.

func (*Providers) Clear 

func (p *Providers) Clear()

Clear removes all providers.

func (*Providers) Delete 

func (p *Providers) Delete(id ProviderID) error

Delete removes a provider by id. Returns an error if the provider doesn't exist.

func (*Providers) DeleteBatch 

func (p *Providers) DeleteBatch(ids []ProviderID) map[ProviderID]error

DeleteBatch removes multiple providers by their IDs. Returns a map of errors for providers that couldn't be deleted (not found).

func (*Providers) DeleteModel 

func (p *Providers) DeleteModel(providerID ProviderID, modelID string) error

DeleteModel removes a model from a provider.

func (*Providers) EncodeYAML added in v0.1.0 

func (p *Providers) EncodeYAML() (string, error)

EncodeYAML returns formatted provider YAML or a typed parse error when a provider value cannot be represented safely.

func (*Providers) Exists 

func (p *Providers) Exists(id ProviderID) bool

Exists checks if a provider exists without returning it.

func (*Providers) ForEach 

func (p *Providers) ForEach(fn func(id ProviderID, provider *Provider) bool)

ForEach applies a function to each provider. The function should not modify the provider. If the function returns false, iteration stops early.

func (*Providers) FormatYAML 

func (p *Providers) FormatYAML() string

FormatYAML returns the providers as formatted YAML with enhanced formatting, comments, and structure.

func (*Providers) Get 

func (p *Providers) Get(id ProviderID) (*Provider, bool)

Get returns a provider by id and whether it exists.

func (*Providers) Len 

func (p *Providers) Len() int

Len returns the number of providers.

func (*Providers) List 

func (p *Providers) List() []Provider

List returns a slice of all providers as values (copies).

func (*Providers) Map 

func (p *Providers) Map() map[ProviderID]*Provider

Map returns a copy of all providers.

func (*Providers) Resolve added in v0.0.21 

func (p *Providers) Resolve(id ProviderID) (*Provider, bool)

Resolve returns a provider by ID or alias. It first tries an exact ID match, then searches all provider aliases. This allows commands to accept both canonical IDs and common aliases silently.

func (*Providers) Set 

func (p *Providers) Set(id ProviderID, provider *Provider) error

Set sets a provider by id. Returns an error if provider is nil.

func (*Providers) SetBatch 

func (p *Providers) SetBatch(providers map[ProviderID]*Provider) error

SetBatch sets multiple providers in a single operation. Overwrites existing providers or adds new ones (upsert behavior). Returns an error if any provider is nil.

func (*Providers) SetModel 

func (p *Providers) SetModel(providerID ProviderID, model Model) error

SetModel adds or updates a model in a provider.

type ProvidersOption 

type ProvidersOption func(*Providers)

ProvidersOption defines a function that configures a Providers instance.

func WithProvidersCapacity 

func WithProvidersCapacity(capacity int) ProvidersOption

WithProvidersCapacity sets the initial capacity of the providers map.

func WithProvidersMap 

func WithProvidersMap(providers map[ProviderID]*Provider) ProvidersOption

WithProvidersMap initializes the map with existing providers.

type ProvidersReader added in v0.1.0 

type ProvidersReader interface {
	Get(ProviderID) (*Provider, bool)
	Resolve(ProviderID) (*Provider, bool)
	Exists(ProviderID) bool
	Len() int
	List() []Provider
	Map() map[ProviderID]*Provider
	ForEach(func(ProviderID, *Provider) bool)
	FormatYAML() string
}

ProvidersReader exposes provider collection reads without mutation methods.

type Quantization 

type Quantization string

Quantization represents the quantization level used by a model. Quantization reduces model size and computational requirements while aiming to preserve performance. 

const (
	QuantizationINT4    Quantization = "int4"    // Integer (4 bit)
	QuantizationINT8    Quantization = "int8"    // Integer (8 bit)
	QuantizationFP4     Quantization = "fp4"     // Floating point (4 bit)
	QuantizationFP6     Quantization = "fp6"     // Floating point (6 bit)
	QuantizationFP8     Quantization = "fp8"     // Floating point (8 bit)
	QuantizationFP16    Quantization = "fp16"    // Floating point (16 bit)
	QuantizationBF16    Quantization = "bf16"    // Brain floating point (16 bit)
	QuantizationFP32    Quantization = "fp32"    // Floating point (32 bit)
	QuantizationUnknown Quantization = "unknown" // Unknown quantization
)

Quantization levels.

func (Quantization) String 

func (q Quantization) String() string

String returns the string representation of a Quantization.

type Reader 

type Reader interface {
	// Lists all providers, authors, and endpoints
	Providers() ProvidersReader
	Authors() AuthorsReader
	Endpoints() EndpointsReader
	Models() ModelsReader
	Provenance() ProvenanceReader

	// Gets a provider, author, or endpoint by id
	Provider(id ProviderID) (Provider, error)
	Author(id AuthorID) (Author, error)
	Endpoint(id string) (Endpoint, error)
	ProviderModels(id ProviderID) (ModelsReader, error)
	ProviderModel(providerID ProviderID, modelID string) (Model, error)
}

Reader provides read-only access to catalog data.

type RouteAlias added in v0.1.0 

type RouteAlias struct {
	ID      RouteAliasID  `json:"id" yaml:"id"`
	Targets []OfferingKey `json:"targets" yaml:"targets"`
}

RouteAlias names a set of candidate offering identities. It intentionally contains no weights, fallback order, tenancy, or routing strategy.

func (RouteAlias) Validate added in v0.1.0 

func (a RouteAlias) Validate() error

Validate verifies route identity and exact target uniqueness.

type RouteAliasID added in v0.1.0 

type RouteAliasID string

RouteAliasID is a Starport-facing routing identity independent of provider IDs.

type RouteAliasRejection added in v0.1.0 

type RouteAliasRejection struct {
	Key    OfferingKey               `json:"key" yaml:"key"`
	Reason RouteAliasRejectionReason `json:"reason" yaml:"reason"`
}

RouteAliasRejection records one ineligible target without hiding it.

type RouteAliasRejectionReason added in v0.1.0 

type RouteAliasRejectionReason string

RouteAliasRejectionReason classifies why a target is not currently eligible. 

const (
	// RouteAliasRejectedMissing means the offering key is absent from the catalog.
	RouteAliasRejectedMissing RouteAliasRejectionReason = "missing"
	// RouteAliasRejectedUnavailable means the provider marks the offering unavailable.
	RouteAliasRejectedUnavailable RouteAliasRejectionReason = "unavailable"
	// RouteAliasRejectedRetired means the provider has retired the offering.
	RouteAliasRejectedRetired RouteAliasRejectionReason = "retired"
)

type RouteAliasResolution added in v0.1.0 

type RouteAliasResolution struct {
	AliasID  RouteAliasID          `json:"alias_id" yaml:"alias_id"`
	Eligible []ProviderOffering    `json:"eligible" yaml:"eligible"`
	Rejected []RouteAliasRejection `json:"rejected,omitempty" yaml:"rejected,omitempty"`
}

RouteAliasResolution is a point-in-time materialization against one catalog generation.

type SourceExtension added in v0.1.0 

type SourceExtension struct {
	Fields map[string]any `json:"fields,omitempty" yaml:"fields,omitempty"` // Preserved source-specific fields
}

SourceExtension stores controlled non-canonical fields reported by one source.

func (SourceExtension) Copy added in v0.1.0 

func (se SourceExtension) Copy() SourceExtension

Copy returns a deep copy of the source extension.

func (*SourceExtension) UnmarshalJSON added in v0.1.0 

func (se *SourceExtension) UnmarshalJSON(data []byte) error

UnmarshalJSON normalizes dynamic extension field types after JSON decoding.

func (*SourceExtension) UnmarshalYAML added in v0.1.0 

func (se *SourceExtension) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML normalizes dynamic extension field types after YAML decoding.

type SourceExtensions added in v0.1.0 

type SourceExtensions map[string]SourceExtension

SourceExtensions stores source-specific attributes that Starmap preserves without treating as canonical schema fields.

func NormalizeSourceExtensions added in v0.1.0 

func NormalizeSourceExtensions(extensions SourceExtensions) SourceExtensions

NormalizeSourceExtensions returns a copy with JSON/YAML-stable dynamic value types for equality checks and sync idempotency.

func (SourceExtensions) Copy added in v0.1.0 

func (se SourceExtensions) Copy() SourceExtensions

Copy returns a deep copy of the source extension map. 

type SourceObservationLink struct {
	Source           catalogmeta.SourceID                `json:"source" yaml:"source"`
	ObservationID    string                              `json:"observation_id" yaml:"observation_id"`
	ObservedAt       time.Time                           `json:"observed_at" yaml:"observed_at"`
	Revision         catalogmeta.ObservationRevision     `json:"revision" yaml:"revision"`
	Completeness     catalogmeta.ObservationCompleteness `json:"completeness" yaml:"completeness"`
	Status           catalogmeta.ObservationStatus       `json:"status" yaml:"status"`
	EvidenceChecksum string                              `json:"evidence_checksum" yaml:"evidence_checksum"`
}

SourceObservationLink binds a generation to one immutable source observation. The observation schema and retention policy are defined by the source pipeline; this link is deliberately small and replay-oriented.

func (SourceObservationLink) Validate added in v0.1.0 

func (o SourceObservationLink) Validate() error

Validate verifies one complete source-observation link.

type TestModelOption 

type TestModelOption func(*Model)

TestModelOption is a functional option for configuring a test model.

func WithModelID 

func WithModelID(id string) TestModelOption

WithModelID sets a custom ID for the test model.

func WithModelName 

func WithModelName(name string) TestModelOption

WithModelName sets a custom name for the test model.

type TestProviderOption 

type TestProviderOption func(*Provider)

TestProviderOption is a functional option for configuring a test provider.

func WithProviderAPIKey 

func WithProviderAPIKey(name, pattern string) TestProviderOption

WithProviderAPIKey sets a custom API key configuration.

func WithProviderEnvVars 

func WithProviderEnvVars(envVars []ProviderEnvVar) TestProviderOption

WithProviderEnvVars sets environment variables for the test provider.

func WithProviderID 

func WithProviderID(id ProviderID) TestProviderOption

WithProviderID sets a custom ID for the test provider.

type Tokenizer 

type Tokenizer string

Tokenizer represents the tokenizer type used by a model. 

const (
	TokenizerClaude   Tokenizer = "claude"   // Claude tokenizer
	TokenizerCohere   Tokenizer = "cohere"   // Cohere tokenizer
	TokenizerDeepSeek Tokenizer = "deepseek" // DeepSeek tokenizer
	TokenizerGPT      Tokenizer = "gpt"      // GPT tokenizer (OpenAI)
	TokenizerGemini   Tokenizer = "gemini"   // Gemini tokenizer (Google)
	TokenizerGrok     Tokenizer = "grok"     // Grok tokenizer (xAI)
	TokenizerLlama2   Tokenizer = "llama2"   // LLaMA 2 tokenizer
	TokenizerLlama3   Tokenizer = "llama3"   // LLaMA 3 tokenizer
	TokenizerLlama4   Tokenizer = "llama4"   // LLaMA 4 tokenizer
	TokenizerMistral  Tokenizer = "mistral"  // Mistral tokenizer
	TokenizerNova     Tokenizer = "nova"     // Nova tokenizer (Amazon)
	TokenizerQwen     Tokenizer = "qwen"     // Qwen tokenizer
	TokenizerQwen3    Tokenizer = "qwen3"    // Qwen 3 tokenizer
	TokenizerRouter   Tokenizer = "router"   // Router-based tokenizer
	TokenizerYi       Tokenizer = "yi"       // Yi tokenizer
	TokenizerUnknown  Tokenizer = "unknown"  // Unknown tokenizer type
)

Tokenizer types.

func (Tokenizer) String 

func (t Tokenizer) String() string

String returns the string representation of a Tokenizer.

type ToolChoice 

type ToolChoice string

ToolChoice represents the strategy for selecting tools. Used in API requests as the "tool_choice" parameter value. 

const (
	ToolChoiceAuto     ToolChoice = "auto"     // Model autonomously decides whether to call tools based on context
	ToolChoiceNone     ToolChoice = "none"     // Model will never call tools, even if tool definitions are provided
	ToolChoiceRequired ToolChoice = "required" // Model must call at least one tool before responding

)

Tool choice strategies for controlling tool usage behavior.

func (ToolChoice) String 

func (tc ToolChoice) String() string

String returns the string representation of a ToolChoice.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.