Configuration

Configuration

The AIConfig class provides comprehensive configuration options for AI requests.

Basic Configuration

final config = AIConfig(
  apiKey: 'your-api-key',
  model: 'gpt-5.5',
);

All Configuration Options

Core Settings

Parameter	Type	Description	Default
apiKey	String	Required. API key for authentication	-
model	String?	Model to use (e.g., 'gpt-5.5', 'claude-opus-4-8')	Provider default
systemPrompt	String?	System instructions for the AI	null
maxTokens	int?	Maximum tokens to generate	null

Generation Parameters

Parameter	Type	Range	Description
temperature	double?	0.0 - 2.0	Controls randomness. Higher = more creative
topP	double?	0.0 - 1.0	Nucleus sampling parameter
frequencyPenalty	double?	-2.0 - 2.0	Reduces repetition of frequent tokens
presencePenalty	double?	-2.0 - 2.0	Reduces repetition of any used tokens
stopSequences	List<String>?	-	Sequences that stop generation

Tools & Response

Parameter	Type	Description
tools	List<Tool>?	Available tools/functions
toolChoice	ToolChoice?	How the model should use tools
responseFormat	ResponseFormat?	Output format (text, JSON, etc.)

Network Settings

Parameter	Type	Description	Default
baseUrl	String?	Custom API base URL	Provider default
timeout	Duration?	Request timeout	60 seconds
headers	Map<String, String>?	Custom HTTP headers	null

Additional

Parameter	Type	Description
metadata	Map<String, dynamic>?	Custom metadata

Examples

Focused Assistant

final config = AIConfig(
  apiKey: 'your-key',
  model: 'gpt-5.5',
  temperature: 0.3,  // More deterministic
  maxTokens: 500,    // Concise responses
  systemPrompt: 'You are a helpful coding assistant. Be concise and accurate.',
);

Creative Writer

final config = AIConfig(
  apiKey: 'your-key',
  model: 'claude-opus-4-8',
  temperature: 1.2,  // More creative
  topP: 0.95,
  systemPrompt: 'You are a creative storyteller with a vivid imagination.',
);

Code Generator

final config = AIConfig(
  apiKey: 'your-key',
  model: 'gpt-5.5',
  temperature: 0.0,  // Deterministic
  maxTokens: 2000,
  stopSequences: ['```\n\n'],  // Stop after code block
  systemPrompt: 'You are a code generator. Output only valid Dart code.',
);

JSON Output

final config = AIConfig(
  apiKey: 'your-key',
  model: 'gpt-5.5',
  responseFormat: ResponseFormat.jsonObject,
  systemPrompt: 'Always respond with valid JSON.',
);

With Custom Timeout

final config = AIConfig(
  apiKey: 'your-key',
  model: 'gpt-5.5',
  timeout: Duration(seconds: 120),
  baseUrl: 'https://your-proxy.com/v1',
  headers: {
    'X-Custom-Header': 'value',
  },
);

Copying Configuration

Use copyWith to create modified configurations:

final baseConfig = AIConfig(
  apiKey: 'your-key',
  model: 'gpt-5.5',
  temperature: 0.7,
);

// Create a variation with different temperature
final creativeConfig = baseConfig.copyWith(
  temperature: 1.2,
  maxTokens: 2000,
);

// Create a variation with different model
final fastConfig = baseConfig.copyWith(
  model: 'gpt-5.4-mini',
  maxTokens: 500,
);

Temperature Guide

Temperature	Use Case
0.0 - 0.3	Factual responses, code generation, structured data
0.4 - 0.7	General conversation, balanced creativity
0.8 - 1.2	Creative writing, brainstorming
1.3 - 2.0	Very creative, experimental outputs

Prompt Caching

Enable provider-side caching of the repeated prompt prefix (up to ~90% cheaper on cached tokens):

AIConfig(
  apiKey: '...',
  promptCaching: PromptCaching(), // TTL 5 min (or PromptCacheTtl.oneHour)
)

Anthropic uses explicit caching (driven by this setting); OpenAI and Google AI cache automatically — hits are reported in usage.cachedTokens in all cases, cache writes in usage.cacheWriteTokens (Anthropic).

Structured Outputs

ResponseFormat.json(schema: ...) guarantees the response matches your JSON schema, using each provider's native mechanism:

responseFormat: ResponseFormat.json(
  schema: {
    'type': 'object',
    'properties': {'name': {'type': 'string'}},
    'required': ['name'],
  },
  strict: true, // strict validation (OpenAI)
),

Without a schema, ResponseFormat.json() enables plain JSON mode (valid JSON, no schema guarantee; not supported by Anthropic).

Model Recommendations

OpenAI

Model	Best For
gpt-5.5	Complex tasks, coding, analysis
gpt-5.4	Affordable all-rounder, multimodal
gpt-5.4-mini	Fast, cost-effective tasks
gpt-5.4-nano	Lowest latency and cost

Anthropic

Model	Best For
claude-opus-4-8	Maximum capability
claude-sonnet-5	Balanced performance, coding
claude-haiku-4-5	Speed and efficiency

Google AI

Model	Best For
gemini-3.5-flash	Fast responses, general use
gemini-3.1-pro-preview	Long context, complex tasks
gemini-3.1-flash-lite	High volume, lowest cost

Related

• Providers - Provider-specific settings
• API-AIConfig - Full API reference