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.Fatal("provide a query")
}
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 err != nil {
log.Fatal(err)
}
resp, err := p.GenSync(ctx, genai.Messages{genai.NewTextMessage(query)})
if err != nil {
log.Fatalf("failed to use provider %q: %s", *provider, err)
}
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 {
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"
"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 {
continue
}
models, err := c.ListModels(context.Background())
var ent *base.ErrNotSupported
if errors.As(err, &ent) {
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"
"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 {
log.Fatal(err)
}
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 != nil {
fmt.Printf("- %s: %v\n", name, err)
} else {
fmt.Printf("- %s: %v\n", name, response)
}
}
}
Example (Available) ¶
package main
import (
"context"
"errors"
"fmt"
"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 err != nil {
fmt.Fprintf(os.Stderr, "error: %v\n", err)
}
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 {
var ent *base.ErrNotSupported
if errors.As(err, &ent) && 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 ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
View Source
var All = map[string]Config{ "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 }, }, "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 }, }, "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 }, }, "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 }, }, }
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 ¶
Types ¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package anthropic implements a client for the Anthropic API, to use Claude.
|
Package anthropic implements a client for the Anthropic API, to use Claude. |
|
Package bfl implements a client for Black Forest Labs API.
|
Package bfl implements a client for Black Forest Labs API. |
|
Package cerebras implements a client for the Cerebras API.
|
Package cerebras implements a client for the Cerebras API. |
|
Package cloudflare implements a client for the Cloudflare AI API.
|
Package cloudflare implements a client for the Cloudflare AI API. |
|
Package cohere implements a client for the Cohere API.
|
Package cohere implements a client for the Cohere API. |
|
Package deepseek implements a client for the DeepSeek API.
|
Package deepseek implements a client for the DeepSeek API. |
|
Package gemini implements a client for Google's Gemini API.
|
Package gemini implements a client for Google's Gemini API. |
|
Package groq implements a client for the Groq API.
|
Package groq implements a client for the Groq API. |
|
Package huggingface implements a client for the HuggingFace serverless inference API.
|
Package huggingface implements a client for the HuggingFace serverless inference API. |
|
Package llamacpp implements a client for the llama-server native API, not the OpenAI compatible one.
|
Package llamacpp implements a client for the llama-server native API, not the OpenAI compatible one. |
|
llamacppsrv
Package llamacppsrv downloads and starts llama-server from llama.cpp, directly from GitHub releases.
|
Package llamacppsrv downloads and starts llama-server from llama.cpp, directly from GitHub releases. |
|
Package mistral implements a client for the Mistral API.
|
Package mistral implements a client for the Mistral API. |
|
Package ollama implements a client for the Ollama API.
|
Package ollama implements a client for the Ollama API. |
|
ollamasrv
Package ollamasrv downloads and starts ollama directly from GitHub releases.
|
Package ollamasrv downloads and starts ollama directly from GitHub releases. |
|
Package openaichat implements a client for the OpenAI Chat Completion API.
|
Package openaichat implements a client for the OpenAI Chat Completion API. |
|
Package openaicompatible implements a minimal client for "OpenAI-compatible" providers.
|
Package openaicompatible implements a minimal client for "OpenAI-compatible" providers. |
|
Package openairesponses implements a client for the OpenAI Responses API.
|
Package openairesponses implements a client for the OpenAI Responses API. |
|
Package perplexity implements a client for the Perplexity API.
|
Package perplexity implements a client for the Perplexity API. |
|
Package pollinations implements a client for the Pollinations API.
|
Package pollinations implements a client for the Pollinations API. |
|
Package togetherai implements a client for the Together.ai API.
|
Package togetherai implements a client for the Together.ai API. |
Click to show internal directories.
Click to hide internal directories.