providers

Documentation

Overview

Package providers is the root of all standard providers.

It contains a registry of all known providers.

Example (All_Full)

package main

import (
	"context"
	"errors"
	"flag"
	"fmt"
	"log"
	"sort"
	"strings"

	"github.com/maruel/genai"
	"github.com/maruel/genai/adapters"
	"github.com/maruel/genai/providers"
)

func main() {
	// This example includes:
	// - Processing <think> tokens for explicit Chain-of-Thoughts models (e.g. Qwen3).
	ctx := context.Background()
	avail := providers.Available(ctx)
	names := make([]string, 0, len(avail))
	for name := range avail {
		names = append(names, name)
	}
	sort.Strings(names)
	s := strings.Join(names, ", ")
	if s == "" {
		s = "set environment variables, e.g. `OPENAI_API_KEY`"
	}
	provider := flag.String("provider", "", "provider to use, "+s)
	model := flag.String("model", "", "model to use; "+string(genai.ModelCheap)+", "+string(genai.ModelGood)+" (default) or "+string(genai.ModelSOTA)+" for automatic model selection")
	remote := flag.String("remote", "", "url to use, e.g. when using ollama or llama-server on another host")
	flag.Parse()

	query := strings.Join(flag.Args(), " ")
	if query == "" {
		log.Print("provide a query")
		return
	}
	var opts []genai.ProviderOption
	if *model != "" {
		opts = append(opts, genai.ProviderOptionModel(*model))
	}
	if *remote != "" {
		opts = append(opts, genai.ProviderOptionRemote(*remote))
	}
	p, err := LoadProvider(ctx, *provider, opts...)
	if p != nil {
		defer func() {
			if err := p.Close(); err != nil {
				log.Printf("Close: %v", err)
			}
		}()
	}
	if err != nil {
		log.Print(err)
		return
	}
	resp, err := p.GenSync(ctx, genai.Messages{genai.NewTextMessage(query)})
	if err != nil {
		log.Printf("failed to use provider %q: %s", *provider, err)
		return
	}
	fmt.Printf("%s\n", resp.String())
}

// LoadProvider loads a provider.
func LoadProvider(ctx context.Context, provider string, opts ...genai.ProviderOption) (genai.Provider, error) {
	if provider == "" {
		return nil, errors.New("no provider specified")
	}
	cfg := providers.All[provider]
	if cfg.Factory == nil {
		return nil, fmt.Errorf("unknown provider %q", provider)
	}
	c, err := cfg.Factory(ctx, opts...)
	if err != nil {
		if c != nil {
			err = errors.Join(err, c.Close())
		}
		return nil, fmt.Errorf("failed to connect to provider %q: %w", provider, err)
	}

	return adapters.WrapReasoning(c), nil
}

Example (All_ListModel)

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/maruel/genai/base"
	"github.com/maruel/genai/providers"
)

func main() {
	ctx := context.Background()
	for name, cfg := range providers.All {
		c, err := cfg.Factory(ctx)
		if err != nil {
			if c != nil {
				if err := c.Close(); err != nil {
					log.Printf("Close: %v", err)
				}
			}
			continue
		}
		models, err := c.ListModels(context.Background())
		if err := c.Close(); err != nil {
			log.Printf("Close: %v", err)
		}
		if _, ok := errors.AsType[*base.ErrNotSupported](err); ok {
			continue
		}
		fmt.Printf("%s:\n", name)
		if err != nil {
			fmt.Printf("  Failed to get models: %v\n", err)
		}
		for _, model := range models {
			fmt.Printf("- %s\n", model)
		}
	}
}

Example (All_Provider)

package main

import (
	"context"
	"errors"
	"fmt"
	"log"

	"github.com/maruel/genai"
	"github.com/maruel/genai/providers"
)

func main() {
	ctx := context.Background()
	for name, cfg := range providers.All {
		c, err := cfg.Factory(ctx, genai.ModelCheap)
		if err != nil {
			if c != nil {
				err = errors.Join(err, c.Close())
			}
			log.Print(err)
			return
		}
		msgs := genai.Messages{
			genai.NewTextMessage("Tell a story in 10 words."),
		}
		// Include options with some unsupported features to demonstrate UnsupportedContinuableError
		opts := &genai.GenOptionText{
			TopK:      50, // Not all providers support this
			MaxTokens: 512,
		}
		response, err := c.GenSync(context.Background(), msgs, opts)
		if err := c.Close(); err != nil {
			log.Printf("Close: %v", err)
		}
		if err != nil {
			fmt.Printf("- %s: %v\n", name, err)
		} else {
			fmt.Printf("- %s: %v\n", name, response)
		}
	}
}

Example (Available)

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"maps"
	"os"
	"slices"
	"strings"

	"github.com/maruel/genai"
	"github.com/maruel/genai/base"
	"github.com/maruel/genai/providers"
)

// LoadDefaultProvider loads a provider if there's exactly one available.
func LoadDefaultProvider(ctx context.Context) (genai.Provider, error) {
	avail := providers.Available(ctx)
	if len(avail) == 1 {
		for _, cfg := range avail {
			return cfg.Factory(ctx)
		}
	}
	if len(avail) == 0 {
		return nil, errors.New("no provider available; please set environment variables or specify a provider and API keys or remote URL")
	}
	return nil, fmt.Errorf("multiple providers available, select one of: %s", strings.Join(slices.Sorted(maps.Keys(avail)), ", "))
}

func main() {
	// Automatically select the provider available if there's only one. Asserts that the provider implements
	// Provider.
	ctx := context.Background()
	c, err := LoadDefaultProvider(ctx)
	if c != nil {
		defer func() {
			if err := c.Close(); err != nil {
				log.Printf("Close: %v", err)
			}
		}()
	}
	if err != nil {
		fmt.Fprintf(os.Stderr, "error: %v\n", err)
		return
	}
	msgs := genai.Messages{genai.NewTextMessage("Provide a life tip that sounds good but is actually a bad idea.")}
	opts := genai.GenOptionText{}
	resp, err := c.GenSync(ctx, msgs, &opts, genai.GenOptionSeed(42))
	if err != nil {
		if ent, ok := errors.AsType[*base.ErrNotSupported](err); ok && slices.Contains(ent.Options, "GenOptionSeed") {
			if resp, err = c.GenSync(ctx, msgs, &opts); err != nil {
				fmt.Fprintf(os.Stderr, "error: %v\n", err)
				return
			}
		}
	}
	fmt.Printf("%s\n", resp.String())
}

Index

• Variables
• func Available(ctx context.Context) map[string]Config
• type Config

Examples

• Package (All_Full)
• Package (All_ListModel)
• Package (All_Provider)
• Package (Available)

Variables

var All = map[string]Config{
	"alibaba": {
		APIKeyEnvVar: "DASHSCOPE_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := alibaba.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"anthropic": {
		APIKeyEnvVar: "ANTHROPIC_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := anthropic.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"antigravity": {
		IsCLI: true,
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := antigravity.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"baseten": {
		APIKeyEnvVar: "BASETEN_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := baseten.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"bfl": {
		APIKeyEnvVar: "BFL_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := bfl.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"cerebras": {
		APIKeyEnvVar: "CEREBRAS_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := cerebras.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"claudecode": {
		IsCLI: true,
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := claudecode.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"codex": {
		IsCLI: true,
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := codex.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"cloudflare": {
		APIKeyEnvVar: "CLOUDFLARE_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := cloudflare.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"cohere": {
		APIKeyEnvVar: "COHERE_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := cohere.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"deepseek": {
		APIKeyEnvVar: "DEEPSEEK_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := deepseek.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"gemini": {
		APIKeyEnvVar: "GEMINI_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := gemini.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"groq": {
		APIKeyEnvVar: "GROQ_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := groq.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"huggingface": {
		APIKeyEnvVar: "HUGGINGFACE_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := huggingface.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"llamacpp": {
		APIKeyEnvVar: "",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := llamacpp.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"mistral": {
		APIKeyEnvVar: "MISTRAL_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := mistral.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"ollama": {
		APIKeyEnvVar: "",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := ollama.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"openai": {
		APIKeyEnvVar: "OPENAI_API_KEY",
		Alias:        "openairesponses",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := openairesponses.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"openaichat": {
		APIKeyEnvVar: "OPENAI_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := openaichat.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"openairesponses": {
		APIKeyEnvVar: "OPENAI_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := openairesponses.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"openaicompatible": {
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := openaicompatible.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"opencode": {
		IsCLI: true,
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := opencode.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"pi": {
		IsCLI: true,
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := pi.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"openrouter": {
		APIKeyEnvVar: "OPENROUTER_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := openrouter.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"perplexity": {
		APIKeyEnvVar: "PERPLEXITY_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := perplexity.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"pollinations": {
		APIKeyEnvVar: "POLLINATIONS_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := pollinations.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"togetherai": {
		APIKeyEnvVar: "TOGETHER_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := togetherai.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"typesafe": {
		APIKeyEnvVar: "TYPESAFE_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := typesafe.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
	"xiaomi": {
		APIKeyEnvVar: "MIMO_API_KEY",
		Factory: func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error) {
			p, err := xiaomi.New(ctx, opts...)
			if p == nil {
				return nil, err
			}
			return p, err
		},
	},
}

All is a easy way to propose the user to load any of the supported provider.

The keys are aliases and there can be duplicate aliases. "openai" links to "openairesponses". Use Provider.Name to get the real provider name.

Functions

func Available

func Available(ctx context.Context) map[string]Config

Available returns the factories that are valid.

It probes all factories concurrently and closes each probe client before returning. Close errors are logged and do not affect availability.

Types

type Config

type Config struct {
	APIKeyEnvVar string
	Alias        string
	// IsCLI is true for providers that launch a subprocess instead of making
	// HTTP requests (e.g. claudecode, codex, opencode). CLI providers accept
	// ProviderOptionStarterWrapper but not ProviderOptionTransportWrapper.
	IsCLI   bool
	Factory func(ctx context.Context, opts ...genai.ProviderOption) (genai.Provider, error)
}

Config is a registry entry.