# Configuration

Configuration in `boru/ai` is centered around `boru\ai\Config\Config`.

If you are new to the library, start with `getting-started.md` first. For the full docs map, see `index.md`.

## Main config sections

- `defaults`
- `runtime`
- `providers.openai`
- `providers.gemini`
- `persistence`
- `db`

## Full example config

```php
use boru\ai\Config\Config;

$config = new Config();

$config->defaults(array(
    'provider' => 'gemini',
    'model' => 'gemini-2.5-pro',
));

$config->runtime(array(
    'replay' => array(
        'enabled' => false,
        'strategy' => 'full',
        'max_turns' => 10,
        'summary' => array(
            'keep_turns' => 3,
            'max_chars' => 4000,
        ),
        'tool_data' => array(
            'enabled' => false,
            'max_chars' => 2000,
            'args_max_chars' => 600,
            'output_max_chars' => 1000,
        ),
    ),
    'conversation_memory' => array(
        'tools' => array(
            'enabled' => false,
            'title' => true,
            'summary' => true,
            'append_note' => true,
            'replace_notes' => false,
            'require_persistence' => true,
            'only_after_turn' => 2,
        ),
    ),
));

$config->provider('gemini', array(
    'api_key' => getenv('GEMINI_API_KEY'),
    'base_url' => 'https://generativelanguage.googleapis.com/v1beta',
    'timeout' => 60,
    'raw_http_debug' => false,
    'stream_read_size' => 1024,
    'replay' => array(
        'enabled' => true,
        'strategy' => 'summarize_history',
        'max_turns' => 10,
        'summary' => array(
            'keep_turns' => 2,
            'max_chars' => 1200,
        ),
        'tool_data' => array(
            'enabled' => true,
            'max_chars' => 1200,
            'args_max_chars' => 300,
            'output_max_chars' => 500,
        ),
    ),
    'asset_bindings' => array(
        'reuse' => true,
        'max_age_seconds' => null,
        'delete_remote_on_cleanup' => false,
        'track_last_used_at' => true,
    ),
));

$config->provider('openai', array(
    'api_key' => getenv('OPENAI_API_KEY'),
    'base_url' => 'https://api.openai.com/v1',
    'timeout' => 60,
    'raw_http_debug' => false,
    'stream_read_size' => 1024,
    'replay' => array(
        'enabled' => false,
        'strategy' => 'full',
        'max_turns' => 10,
        'summary' => array(
            'keep_turns' => 3,
            'max_chars' => 4000,
        ),
        'tool_data' => array(
            'enabled' => false,
            'max_chars' => 2000,
            'args_max_chars' => 600,
            'output_max_chars' => 1000,
        ),
    ),
    'asset_bindings' => array(
        'reuse' => true,
        'max_age_seconds' => null,
        'delete_remote_on_cleanup' => false,
        'track_last_used_at' => true,
    ),
));

$config->persistence(array(
    'enabled' => false,
    'driver' => 'db',
    'auto_schema' => false,
    'persist_tool_calls' => false,
    'tables' => array(
        'conversations' => 'ai_conversations',
        'turns' => 'ai_turns',
        'assets' => 'ai_assets',
        'provider_asset_bindings' => 'ai_provider_asset_bindings',
        'tool_calls' => 'ai_tool_calls',
        'embeddings' => 'ai_embeddings',
        'conversation_notes' => 'ai_conversation_notes',
    ),
    'asset_bindings' => array(
        'reuse' => true,
        'max_age_seconds' => null,
        'delete_remote_on_cleanup' => false,
        'track_last_used_at' => true,
    ),
));

$config->db(array(
    'use' => true,
    'dbhost' => '127.0.0.1',
    'dbport' => 3306,
    'dbname' => 'ai',
    'dbuser' => 'root',
    'dbpass' => '',
    'dbtype' => 'mysql',
));

return $config;
```

## Config precedence

The library uses a shared config resolution pattern for provider/runtime knobs.

For settings that support layered resolution, precedence is:

1. provider default
2. global setting
3. provider-specific setting
4. env override

Last one wins.

Examples of provider-aware settings already using this model include:

- replay settings
- conversation-memory tool policy settings
- `timeout`
- `raw_http_debug`
- `stream_read_size`
- asset binding policy settings

## Defaults section

### `defaults.provider`
Default provider used by bootstrap/runtime helpers.

### `defaults.model`
Default model used when the request does not specify one.

## Runtime config knobs

### `runtime.replay`
Global replay defaults shared across providers unless overridden.

Supported keys:

- `enabled`
- `strategy`
- `max_turns`
- `summary.keep_turns`
- `summary.max_chars`
- `tool_data.enabled`
- `tool_data.max_chars`
- `tool_data.args_max_chars`
- `tool_data.output_max_chars`

For more on replay behavior and strategies, see `replay.md`.

### `runtime.conversation_memory`
Global conversation-memory defaults.

Supported keys under `runtime.conversation_memory.tools`:

- `enabled`
- `title`
- `summary`
- `append_note`
- `replace_notes`
- `require_persistence`
- `only_after_turn`

These control when the built-in conversation-memory tools are auto-exposed.

Default behavior is intentionally conservative:

- memory tools are disabled by default
- when enabled, persistence is required by default
- when enabled, tools are auto-exposed starting on turn 2 by default

For the full memory model and built-in tools, see `conversation-memory.md`.

## Provider config knobs

These are configured under `providers.openai` and `providers.gemini`.

### `api_key`
Provider API key.

### `base_url`
Base API URL for the provider.

### `timeout`
HTTP timeout for provider requests.

### `raw_http_debug`
When enabled, provider clients may echo low-level HTTP and streaming diagnostics. This is intended for local debugging.

### `stream_read_size`
Controls transport read size used while consuming streaming responses. Smaller values may produce more granular perceived streaming.

### `replay`
Provider-specific replay overrides using the same nested structure as `runtime.replay`.

### `asset_bindings`
Provider-specific asset binding lifecycle overrides.

Supported keys:

- `reuse`
- `max_age_seconds`
- `delete_remote_on_cleanup`
- `track_last_used_at`

For more on asset binding behavior, see `assets.md`.

## Persistence config knobs

These are configured under `persistence`.

### `persistence.enabled`
Enable persistence integration.

### `persistence.driver`
Persistence driver. Current supported value is `db`.

### `persistence.auto_schema`
Automatically ensure DB schema during bootstrap.

### `persistence.persist_tool_calls`
Persist tool lifecycle rows in the tool calls table.

### `persistence.tables`
Override table names.

Supported keys:

- `conversations`
- `turns`
- `assets`
- `provider_asset_bindings`
- `tool_calls`
- `embeddings`
- `conversation_notes`

### `persistence.asset_bindings`
Global asset binding lifecycle policy.

Supported keys:

- `reuse`
- `max_age_seconds`
- `delete_remote_on_cleanup`
- `track_last_used_at`

For persistence behavior and bootstrap wiring details, see `persistence.md`.

## DB config knobs

These are configured under `db`.

### `db.use`
Whether DB connectivity should be used.

### `db.dbhost`
Database host.

### `db.dbport`
Database port.

### `db.dbname`
Database name.

### `db.dbuser`
Database username.

### `db.dbpass`
Database password.

### `db.dbtype`
Database adapter/driver name. Current default is `mysql`.

## See also

- `getting-started.md`
- `replay.md`
- `conversation-memory.md`
- `assets.md`
- `persistence.md`
