Seshat AIDocumentation

Documentation / SDK and API

Providers and authentication

Choose a model provider, point it at your own endpoint, set fallbacks, and manage keys and sign-in from your application.

A provider is a company or server that runs a model. Seshat talks to all of them through one interface, so changing provider is a change of configuration.

Choose a model

cfg := sdk.DefaultClientConfig()
cfg.Model = sdk.ModelIdentifier{
    Provider: sdk.APIProviderOpenAI,
    Model:    "gpt-5",
}

The provider constants are APIProviderAnthropic, APIProviderOpenAI, APIProviderMistral, APIProviderGemini, APIProviderDeepSeek, APIProviderOllama, APIProviderCodex, APIProviderMiniMax, APIProviderOpenCode and more. The full list of providers and models is in Configuration.

To discover what is available at run time, use the github.com/KPO-Tech/seshat-runtime/pkg/providers package:

info := providers.AllProvidersInfo()                 // the built-in providers, each with the models of the catalog (default large first, small last)
models, err := providers.FetchModels(ctx, "ollama", providers.DefaultBaseURL("ollama"), "")

Keys

NewStoredCredentialResolver, one ready-made resolversdk.NewClient(cfg)the provider of cfg.ModelResolver gives a key ?Use the resolver keyCredentialResolver winsClientConfig.APIKeyalso used if the resolver failsEnvFirst: the variableof the provider, if setand EnvFirst is trueThe auth fileauth.json, or SESHAT_AUTH_PATHan API key or an OAuth tokenRefreshedan expired OAuth tokenwith its refresh tokenyesno, or no resolverelseOAuthThe stored resolver is one way to build a resolver.A server writes its own, one key per user.
A resolver that returns a key wins over APIKey. If the resolver fails, the failure is logged and APIKey is used.

Give the key in the config:

cfg.APIKey = os.Getenv("ANTHROPIC_API_KEY")

For a server that serves many users, implement CredentialResolver. It is asked for the key of a provider when the client is created, and its answer wins over APIKey:

type resolver struct{ db *DB }

func (r resolver) ResolveAPIKey(ctx context.Context, provider string) (string, error) {
    return r.db.KeyFor(ctx, currentUser(ctx), provider)
}

cfg.CredentialResolver = resolver{db}

For a desktop or command-line host, sdk.NewStoredCredentialResolver reads keys from the environment and from the local sign-in store:

cfg.CredentialResolver = sdk.NewStoredCredentialResolver(sdk.StoredCredentialResolverConfig{
    EnvFirst: true, // a variable in the environment wins over the stored key
})

More providers, from the models.dev catalog

Beyond the providers Seshat has built in, about 190 more speak the OpenAI chat completions protocol, and Seshat calls them with one generic client: siliconflow, together, nvidia, huggingface, fireworks and many gateways. Their list, their base URLs, the environment variable of each key and the context window, image support and price of each model come from the public models.dev catalog, embedded in the program so nothing needs the network.

Name one in a model string, set the variable it names, and you are done:

client, err := sdk.NewClient(&sdk.ClientConfig{
    Model: sdk.ModelIdentifier{Provider: "siliconflow", Model: "some-model"},
    APIKey: os.Getenv("SILICONFLOW_API_KEY"),
})

sdk.CatalogProviders() lists them with their key variables. Four things to know:

  • The catalog never decides where a key goes. The base URL and key variable of a provider come from the catalog embedded in the program. A catalog you download adds models, and adds providers marked Unverified: such a provider gets no configuration of its own, so show its URL to the user and build the ProviderConfig with the URL they confirmed.
  • The built-in providers follow the catalog too, and no model is written by hand. For Anthropic, OpenAI, Gemini, Mistral, Z.ai, Kimi, DeepSeek, OpenRouter, OpenCode and MiniMax, the list is the catalog’s, newest first, without deprecated models and without models a chat client cannot use (speech, realtime, image, embeddings, deep-research agents). The first model is the default large one and the last the default small one. Updating the lists is rebuilding the embedded snapshot (go run scripts/build_catalog_snapshot.go https://models.dev/api.json), not editing code. An output limit equal to the context window is treated as unknown, and the prompt limit of a model, when the catalog gives one below its window, is what the window is counted against. A model the catalog says rejects a temperature never receives one.
  • Some providers have no URL in the catalog: Groq, xAI, Cerebras, Together AI, DeepInfra and Cohere are listed there under their own SDK. A small table reviewed by hand (internal/catalog/overrides.go) gives their OpenAI-compatible endpoint; it applies to the embedded catalog only, so a refresh never moves it.
  • Refreshing is your choice. ClientConfig.CatalogCacheDir reads a catalog downloaded earlier. ClientConfig.RefreshCatalog (or sdk.RefreshCatalog(ctx, dir) by hand) downloads the public one, at most once a day. It is off by default and sends nothing about the user.

Which model by default

When the user has not chosen a model, the runtime picks one per provider. Its choice is a small table of families of the catalog (claude-sonnet and claude-haiku for Anthropic, glm and glm-flash for Z.ai…), never a model identifier: the newest stable model of the family is taken, so a new version is picked up by the next catalog. A provider the table does not cover gets the dearest of its ten newest stable models as the large one and the cheapest as the small one.

Your application can complete or change that, and only has to write what it changes. A ModelPolicy maps a provider to its default large and small model, each entry a family or an exact model identifier, tried in order. Yours are tried first and the runtime’s after them, so an entry that names a model the catalog no longer has falls back to the runtime’s choice instead of failing.

policy := providers.DefaultModelPolicy() // a copy of the runtime's own, to read
policy["minimax"] = providers.ModelDefaults{
    Large: []string{"MiniMax-M3"},
    Small: []string{"MiniMax-M3.1-Flash"},
}

info, _ := providers.ProviderInfoWithPolicy("minimax", policy) // first model: large, last: small
large, _ := providers.DefaultModelWithPolicy("minimax", policy)
small, _ := providers.SmallModelWithPolicy("minimax", policy)

A policy is a plain value you pass in: the package keeps none, so two hosts, or two clients, in the same process never see each other’s choices. The terminal application reads the same thing from options.model_defaults in its configuration file, at the next start.

Trying a provider with your own key

go run scripts/check_providers.go groq zai (in the runtime repository) sends a short question to the cheapest model of each provider you name, with the key from its environment variable, and prints the answer, the reasoning when there is some, the time and any error. Without arguments it checks every provider whose key variable is set; -all-models -limit 5 tries several models of each.

Your own endpoint

Use ProviderConfig to point a provider at another base URL, add headers, or map model aliases. This is how you reach a gateway, a self-hosted server or an OpenAI-compatible service.

cfg.ProviderConfig = &providers.Config{
    Provider: sdk.APIProviderOpenAI,
    BaseURL:  "https://llm-gateway.internal.example/v1",
    CustomHeaders: map[string]string{"X-Team": "platform"},
}

providers.GetProviderConfig(provider) returns the defaults for a provider, a good starting point to copy.

Fallbacks

A provider configuration can name other models and providers to try when the first one fails. The loop tries the fallback models first (same provider), then the fallback providers. A circuit breaker stops calling a provider that keeps failing and tries it again after a delay.

By default, only models of the same provider are tried: for Anthropic, claude-sonnet-5-5 and then claude-haiku-5-5. A prompt is never sent to another vendor unless you list one in Routing.FallbackProviders, so picking a provider is enough to keep your data with that provider.

Cross-vendor fallback is opt-in. Start from the defaults and add the providers you accept, or set the list to empty for none:

pc := providers.GetProviderConfig(sdk.APIProviderAnthropic)
if pc.Routing != nil {
    pc.Routing.FallbackModels = []sdk.ModelIdentifier{
        {Provider: sdk.APIProviderAnthropic, Model: "claude-haiku-5-5"},
    }
    pc.Routing.FallbackProviders = []sdk.APIProvider{sdk.APIProviderOpenRouter}
}
cfg.ProviderConfig = pc

Signing in with a ChatGPT subscription

Codex and OpenAI can use a ChatGPT subscription instead of an API key, through a device flow. The CLI does it with seshat login. From Go:

flow, err := sdk.NewOAuthDeviceFlow(sdk.OAuthDeviceFlowConfig{Provider: "codex", Persist: true})
if err != nil {
    log.Fatal(err)
}

challenge, err := flow.Start(ctx)          // show challenge.UserCode and challenge.VerificationURL
if err != nil {
    log.Fatal(err)
}
token, err := flow.Wait(ctx, challenge)    // blocks until the user has approved
if err != nil {
    log.Fatal(err)
}
if err := flow.SaveToken(ctx, token); err != nil {
    log.Fatal(err)
}

cfg.CredentialResolver = flow.CredentialResolver()

The resolver refreshes the access token when it expires.

Updated on 2026-10-14