Issues configuration

Configuration issues typically surface when Polyglot cannot find a preset file, when the file is missing required fields, or when field values have the wrong type. These problems usually produce clear error messages that point directly to the cause.

Symptoms

InvalidArgumentException with “No preset directory found” or “Invalid configuration”
Unexpected driver or model being used
Type errors mentioning maxTokens, dimensions, or maxInputs

Preset File Location

When you call Inference::using('openai'), Polyglot searches for a file named openai.yaml in these directories (in order):

config/llm/presets/ — relative to your project root
packages/polyglot/resources/config/llm/presets/ — monorepo layout
vendor/cognesy/instructor-php/packages/polyglot/resources/config/llm/presets/ — installed via Composer as part of instructor-php
vendor/cognesy/instructor-polyglot/resources/config/llm/presets/ — installed via Composer as standalone package

For embeddings, the equivalent paths use config/embed/presets/ instead of config/llm/presets/. If none of these directories exist, Polyglot throws an InvalidArgumentException. To override the search path, pass a basePath argument:

<?php

use Cognesy\Polyglot\Inference\Inference;

$inference = Inference::using('my-custom-preset', basePath: '/app/config/llm');
// @doctest id="e486"

Required Preset Fields

A minimal LLM preset YAML file must include:

driver: openai
apiUrl: 'https://api.openai.com/v1'
apiKey: '${OPENAI_API_KEY}'
endpoint: /chat/completions
model: gpt-4.1-nano
maxTokens: 1024
contextLength: 128000
maxOutputLength: 16384
# @doctest id="0e24"

The following fields are required or strongly recommended:

Field	Type	Description
`driver`	string	The driver name (e.g. `openai`, `anthropic`, `gemini`, `ollama`)
`apiUrl`	string	Base URL of the provider API
`apiKey`	string	API key, usually referencing an env var via `${VAR_NAME}`
`endpoint`	string	API endpoint path (e.g. `/chat/completions`, `/messages`)
`model`	string	Default model identifier
`maxTokens`	integer	Maximum tokens for the response
`contextLength`	integer	Maximum context window size
`maxOutputLength`	integer	Maximum output length in tokens

Optional fields include metadata (an associative array for provider-specific values like organization or apiVersion), queryParams, options, and pricing.

Integer Field Validation

The fields maxTokens, contextLength, and maxOutputLength must be valid integers. If these values are provided as strings in YAML (e.g. "1024" instead of 1024), Polyglot coerces them automatically. However, non-numeric strings or floats will cause an InvalidArgumentException. For embeddings presets, the same rule applies to dimensions and maxInputs.

Building Configuration Programmatically

If your configuration is dynamic — for example, when the user selects a model at runtime — prefer building LLMConfig directly instead of relying on preset files:

<?php

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Config\LLMConfig;
use Cognesy\Polyglot\Inference\Inference;

$config = new LLMConfig(
    driver: 'openai',
    apiUrl: 'https://api.openai.com/v1',
    apiKey: (string) getenv('OPENAI_API_KEY'),
    endpoint: '/chat/completions',
    model: 'gpt-4.1-nano',
    maxTokens: 2048,
);

$text = Inference::fromConfig($config)
    ->withMessages(Messages::fromString('Hello'))
    ->get();
// @doctest id="cd31"

You can also create a config from an associative array:

<?php

use Cognesy\Polyglot\Inference\Config\LLMConfig;

$config = LLMConfig::fromArray([
    'driver' => 'anthropic',
    'apiUrl' => 'https://api.anthropic.com/v1',
    'apiKey' => getenv('ANTHROPIC_API_KEY'),
    'endpoint' => '/messages',
    'model' => 'claude-haiku-4-5-20251001',
    'maxTokens' => 1024,
]);
// @doctest id="28dc"

Overriding Preset Values

To start from a preset and change specific values, use withOverrides():

<?php

use Cognesy\Messages\Messages;
use Cognesy\Polyglot\Inference\Config\LLMConfig;
use Cognesy\Polyglot\Inference\Inference;

$config = LLMConfig::fromPreset('openai')
    ->withOverrides(['model' => 'gpt-4.1', 'maxTokens' => 4096]);

$text = Inference::fromConfig($config)
    ->withMessages(Messages::fromString('Hello'))
    ->get();
// @doctest id="8a93"

Verify a Configuration

To check that a preset loads correctly without making a request, instantiate the config and inspect it:

<?php

use Cognesy\Polyglot\Inference\Config\LLMConfig;

try {
    $config = LLMConfig::fromPreset('openai');
    echo "Driver: {$config->driver}\n";
    echo "API URL: {$config->apiUrl}\n";
    echo "Model: {$config->model}\n";
    echo "Max Tokens: {$config->maxTokens}\n";
} catch (\InvalidArgumentException $e) {
    echo "Configuration error: " . $e->getMessage() . "\n";
}
// @doctest id="acba"

Common Pitfalls

Preset name does not match the filename. Inference::using('gpt4') looks for gpt4.yaml, not openai.yaml.
YAML indentation errors. Malformed YAML will cause the config loader to fail silently or return unexpected values.
Retry policy in options. Polyglot explicitly forbids placing retryPolicy inside the options array of LLMConfig. Use withRetryPolicy() on the inference builder instead.
Environment variable not expanded. If the apiKey field contains the literal string ${OPENAI_API_KEY} at runtime, the environment variable was not resolved. Ensure the variable is set before the preset is loaded.

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Symptoms

Preset File Location

Required Preset Fields

Integer Field Validation

Building Configuration Programmatically

Overriding Preset Values

Verify a Configuration

Common Pitfalls

​Symptoms

​Preset File Location

​Required Preset Fields

​Integer Field Validation

​Building Configuration Programmatically

​Overriding Preset Values

​Verify a Configuration

​Common Pitfalls

Symptoms

Preset File Location

Required Preset Fields

Integer Field Validation

Building Configuration Programmatically

Overriding Preset Values

Verify a Configuration

Common Pitfalls