Settings

Use GenerationOptions for controls that should stay the same when you change providers. Use providerOptions when you need a setting that belongs to one provider only.

Set portable generation options

This example sets temperature and a token limit without tying the request to one provider’s request format.

import std/[options, os]
import nimgent
import nimgent/providers/openai

let model = openAI(getEnv("OPENAI_API_KEY")).model("gpt-4.1-mini")
let response = generateText(
  model,
  prompt = "Explain Nim in one paragraph.",
  maxTokens = 200,
  generationOptions = GenerationOptions(
    temperature: some(0.3),
    topP: some(0.9))
)

echo response.text

GenerationOptions supports temperature, topP, topK, presence and frequency penalties, stopSequences, seed, and reasoning. maxTokens, tools, messages, and streaming are also portable nimgent arguments.

Providers translate these controls to their own API format. A provider can still reject a setting that its selected model does not support.

Set a provider-specific option

Put settings that only apply to one provider in its ProviderOptions namespace.

import std/[options, os]
import nimgent
import nimgent/providers/openai

let model = openAI(getEnv("OPENAI_API_KEY")).model("gpt-4.1-mini")
let response = generateText(
  model,
  prompt = "Explain this code.",
  providerOptions = ProviderOptions(
    openai: OpenAIOptions(store: some(false)))
)

echo response.text

Only the namespace for the selected provider is used. For example, OpenAIOptions does not configure an Anthropic or Google request.

All typed provider fields are optional. Leave a field unset to omit it. Use some(false), some(0), or some(@[]) when you need to send an explicit false, zero, or empty list.

Use an option nimgent does not type yet

Use ProviderOptions.extra for a native provider setting without a typed option.

import std/json
import nimgent

let settings = ProviderOptions(
  extra: %*{
    "google": {
      "generationConfig": {"responseMimeType": "text/plain"}
    }
  }
)

The key must match the provider name, such as google, openai, or anthropic. Pass settings as providerOptions in a generation or embedding call.

Portable generationOptions win when both option types set the same behavior.

Next steps

See the setup page for your provider, or use Structured output for schema-specific output settings.