catalogs

package
v0.0.25 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2025 License: AGPL-3.0 Imports: 21 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:

// Create an embedded catalog (production use)
catalog, err := New(WithEmbedded())
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 catalog (development use)
catalog, err := New(WithFiles("./catalog"))
if err != nil {
    log.Fatal(err)
}
Example

Example demonstrates basic catalog creation and usage.

package main

import (
	"fmt"
	"log"

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

func main() {
	// Create a memory-based catalog
	catalog := 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 := catalog.SetProvider(provider); 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 := 0; i < 100; i++ {
			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() {
	// Create catalog with embedded data
	catalog, err := catalogs.New(catalogs.WithEmbedded())
	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 catalog
	catalogPath := filepath.Join(".", "my-catalog")
	catalog, 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 := catalog.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"

	"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 {
			for _, modality := range model.Features.Modalities.Input {
				if modality == "image" {
					visionModels = append(visionModels, model)
					break
				}
			}
		}
	}
	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

func AssertCatalogHasModel

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

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

func AssertCatalogHasProvider

func AssertCatalogHasProvider(t testing.TB, catalog Catalog, 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 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 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) 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 Catalog

Catalog is the complete interface combining all catalog capabilities. This interface is composed of smaller, focused interfaces following the Interface Segregation Principle.

type Catalog interface {
    Reader
    Writer
    Merger
    Copier
    Persistence
}

func New
func New(opt Option, opts ...Option) (Catalog, error)

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

func NewEmbedded
func NewEmbedded() (Catalog, 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() Catalog

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) (Catalog, 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) (Catalog, 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) (Catalog, 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 NewReadOnly
func NewReadOnly(source Catalog) Catalog

NewReadOnly creates a read-only wrapper around an existing catalog. Write operations will return errors.

Example:

embedded, _ := NewEmbedded()
readOnly := NewReadOnly(embedded)
err := readOnly.SetProvider(provider) // Returns error

func TestCatalog
func TestCatalog(t testing.TB) Catalog

TestCatalog creates a test catalog with sample data.

type Copier

Copier provides catalog copying capabilities.

type Copier interface {
    // Return a copy of the catalog
    Copy() (Catalog, error)
}

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 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 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 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 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 MergeableCatalog

MergeableCatalog provides full catalog functionality.

type MergeableCatalog interface {
    Catalog
}

type Merger

Merger provides catalog merging capabilities.

type Merger interface {
    // Replace this catalog's contents with another catalog
    // The source only needs to be readable
    ReplaceWith(source Reader) error

    // Merge another catalog into this one
    // The source only needs to be readable
    // Use WithStrategy option to specify merge strategy (defaults to MergeEnrichEmpty)
    MergeWith(source Reader, opts ...MergeOption) error

    // MergeStrategy returns the default merge strategy for this catalog
    MergeStrategy() MergeStrategy

    // SetMergeStrategy sets the default merge strategy for this catalog
    SetMergeStrategy(strategy MergeStrategy)
}

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

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

    // 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"`

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

    // 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 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) 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 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
    OutputTokens  int64 `json:"output_tokens" yaml:"output_tokens"`   // Maximum output tokens
}

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 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"`

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

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 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 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 MutableCatalog

MutableCatalog provides read-write access without merge capabilities.

type MutableCatalog interface {
    Reader
    Writer
    Copier
}

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 Persistence

Persistence provides catalog persistence capabilities.

type Persistence interface {
    // Save saves the catalog to persistent storage
    Save(opts ...save.Option) error
}

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) FindByField
func (p *Provenance) FindByField(resourceType types.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 types.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 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

    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) 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
    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"
    ProviderIDAnthropic      ProviderID = "anthropic"
    ProviderIDAnyscale       ProviderID = "anyscale"
    ProviderIDCerebras       ProviderID = "cerebras"
    ProviderIDCheckstep      ProviderID = "checkstep"
    ProviderIDCohere         ProviderID = "cohere"
    ProviderIDConectys       ProviderID = "conectys"
    ProviderIDCove           ProviderID = "cove"
    ProviderIDDeepMind       ProviderID = "deepmind"
    ProviderIDDeepSeek       ProviderID = "deepseek"
    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 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 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 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 Catalog, 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) 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 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 ReadOnlyCatalog

ReadOnlyCatalog provides read-only access to a catalog.

type ReadOnlyCatalog interface {
    Reader
    Copier
}

type Reader

Reader provides read-only access to catalog data.

type Reader interface {
    // Lists all providers, authors, and endpoints
    Providers() *Providers
    Authors() *Authors
    Endpoints() *Endpoints
    Models() *Models
    Provenance() *Provenance

    // Gets a provider, author, or endpoint by id
    Provider(id ProviderID) (Provider, error)
    Author(id AuthorID) (Author, error)
    Endpoint(id string) (Endpoint, error)

    // Helper methods for accessing models through providers/authors
    FindModel(id string) (Model, error)
}

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.

type Writer

Writer provides write operations for catalog data.

type Writer interface {
    // Sets a provider, author, or endpoint (upsert semantics)
    SetProvider(provider Provider) error
    SetAuthor(author Author) error
    SetEndpoint(endpoint Endpoint) error

    // Deletes a provider, author, or endpoint by id
    DeleteProvider(id ProviderID) error
    DeleteAuthor(id AuthorID) error
    DeleteEndpoint(id string) error
}

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: 

// Create an embedded catalog (production use)
catalog, err := New(WithEmbedded())
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 catalog (development use)
catalog, err := New(WithFiles("./catalog"))
if err != nil {
    log.Fatal(err)
}
Example

Example demonstrates basic catalog creation and usage. 

package main

import (
	"fmt"
	"log"

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

func main() {
	// Create a memory-based catalog
	catalog := 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 := catalog.SetProvider(provider); 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 := 0; i < 100; i++ {
			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() {
	// Create catalog with embedded data
	catalog, err := catalogs.New(catalogs.WithEmbedded())
	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 catalog
	catalogPath := filepath.Join(".", "my-catalog")
	catalog, 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 := catalog.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"

	"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 {
			for _, modality := range model.Features.Modalities.Input {
				if modality == "image" {
					visionModels = append(visionModels, model)
					break
				}
			}
		}
	}
	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

This section is empty.

Variables

This section is empty.

Functions

func AssertCatalogHasModel 

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

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

func AssertCatalogHasProvider 

func AssertCatalogHasProvider(t testing.TB, catalog Catalog, 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 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 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) 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 Catalog 

type Catalog interface {
	Reader
	Writer
	Merger
	Copier
	Persistence
}

Catalog is the complete interface combining all catalog capabilities. This interface is composed of smaller, focused interfaces following the Interface Segregation Principle.

func New 

func New(opt Option, opts ...Option) (Catalog, error)

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

func NewEmbedded 

func NewEmbedded() (Catalog, 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() Catalog

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) (Catalog, 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) (Catalog, 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) (Catalog, 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 NewReadOnly 

func NewReadOnly(source Catalog) Catalog

NewReadOnly creates a read-only wrapper around an existing catalog. Write operations will return errors.

Example: 

embedded, _ := NewEmbedded()
readOnly := NewReadOnly(embedded)
err := readOnly.SetProvider(provider) // Returns error

func TestCatalog 

func TestCatalog(t testing.TB) Catalog

TestCatalog creates a test catalog with sample data.

type Copier 

type Copier interface {
	// Return a copy of the catalog
	Copy() (Catalog, error)
}

Copier provides catalog copying capabilities.

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 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 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 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 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 MergeableCatalog 

type MergeableCatalog interface {
	Catalog
}

MergeableCatalog provides full catalog functionality.

type Merger 

type Merger interface {
	// Replace this catalog's contents with another catalog
	// The source only needs to be readable
	ReplaceWith(source Reader) error

	// Merge another catalog into this one
	// The source only needs to be readable
	// Use WithStrategy option to specify merge strategy (defaults to MergeEnrichEmpty)
	MergeWith(source Reader, opts ...MergeOption) error

	// MergeStrategy returns the default merge strategy for this catalog
	MergeStrategy() MergeStrategy

	// SetMergeStrategy sets the default merge strategy for this catalog
	SetMergeStrategy(strategy MergeStrategy)
}

Merger provides catalog merging capabilities.

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

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

	// 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"`

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

	// 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 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) 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 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
	OutputTokens  int64 `json:"output_tokens" yaml:"output_tokens"`   // Maximum output tokens
}

ModelLimits represents the limits for a model.

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 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"`

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

ModelPricing represents the pricing structure for a model.

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 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 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 MutableCatalog 

type MutableCatalog interface {
	Reader
	Writer
	Copier
}

MutableCatalog provides read-write access without merge capabilities.

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 Persistence added in v0.0.15 

type Persistence interface {
	// Save saves the catalog to persistent storage
	Save(opts ...save.Option) error
}

Persistence provides catalog persistence capabilities.

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) FindByField added in v0.0.23 

func (p *Provenance) FindByField(resourceType types.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 types.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 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

	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) 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
	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"
	ProviderIDAnthropic      ProviderID = "anthropic"
	ProviderIDAnyscale       ProviderID = "anyscale"
	ProviderIDCerebras       ProviderID = "cerebras"
	ProviderIDCheckstep      ProviderID = "checkstep"
	ProviderIDCohere         ProviderID = "cohere"
	ProviderIDConectys       ProviderID = "conectys"
	ProviderIDCove           ProviderID = "cove"
	ProviderIDDeepMind       ProviderID = "deepmind"
	ProviderIDDeepSeek       ProviderID = "deepseek"
	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 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 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 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 Catalog, 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) 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 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 ReadOnlyCatalog 

type ReadOnlyCatalog interface {
	Reader
	Copier
}

ReadOnlyCatalog provides read-only access to a catalog.

type Reader 

type Reader interface {
	// Lists all providers, authors, and endpoints
	Providers() *Providers
	Authors() *Authors
	Endpoints() *Endpoints
	Models() *Models
	Provenance() *Provenance

	// Gets a provider, author, or endpoint by id
	Provider(id ProviderID) (Provider, error)
	Author(id AuthorID) (Author, error)
	Endpoint(id string) (Endpoint, error)

	// Helper methods for accessing models through providers/authors
	FindModel(id string) (Model, error)
}

Reader provides read-only access to catalog data.

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.

type Writer 

type Writer interface {
	// Sets a provider, author, or endpoint (upsert semantics)
	SetProvider(provider Provider) error
	SetAuthor(author Author) error
	SetEndpoint(endpoint Endpoint) error

	// Deletes a provider, author, or endpoint by id
	DeleteProvider(id ProviderID) error
	DeleteAuthor(id AuthorID) error
	DeleteEndpoint(id string) error
}

Writer provides write operations for catalog data.

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.