# Getting started

This guide covers the quickest path to running `boru/ai` with either Gemini or OpenAI.

If you want a broader map of the documentation set first, see `index.md`.

## Install

```bash
composer require boru/ai
```

If you need legacy BoruAI-style tool compatibility via `AI::addLegacyTool()`, install the optional bridge package as well:

```bash
composer require boru/boruai
```

## Bootstrap the library

```php
<?php

use boru\ai\Bootstrap;

require __DIR__ . '/../vendor/autoload.php';

$config = require __DIR__ . '/../examples/config.php';
Bootstrap::registerDefaults($config);
```

`Bootstrap::registerDefaults($config)` registers the built-in providers, model-prefix mappings, and persistence wiring when enabled.

For configuration details, see `configuration.md`.

## Your first request

```php
<?php

use boru\ai\AI;
use boru\ai\Bootstrap;

require __DIR__ . '/../vendor/autoload.php';

$config = require __DIR__ . '/../examples/config.php';
Bootstrap::registerDefaults($config);

$response = AI::provider('gemini')
    ->model('gemini-2.5-pro')
    ->addMessage('Write one short sentence about Atlanta.')
    ->run();

echo $response->text() . PHP_EOL;
```

You can swap Gemini for OpenAI as needed:

```php
$response = AI::provider('openai')
    ->model('gpt-5.1')
    ->addMessage('Write one short sentence about Atlanta.')
    ->run();
```

## Reasoning settings

For OpenAI reasoning models, use the fluent `reasoning()` helper. Additional reasoning settings are merged into the nested Responses API `reasoning` object:

```php
$response = AI::provider('openai')
    ->model('gpt-5.6-sol')
    ->reasoning('high', array(
        'mode' => 'pro',
        'context' => 'all_turns',
    ))
    ->addMessage('Review this migration plan for operational risks.')
    ->run();
```

For other request-level provider options, use `option()` or replace the complete option set with `options()`:

```php
$ai->option('store', false);
$ai->options(array(
    'store' => false,
    'max_output_tokens' => 2000,
));
```

Reasoning settings are model-specific. Unsupported values are passed to the provider, which will return its normal validation error.

## Choosing a provider

Choose the provider explicitly:

```php
$ai = AI::provider('openai')->model('gpt-5.1');
```

or:

```php
$ai = AI::provider('gemini')->model('gemini-2.5-pro');
```

The runtime/provider registry also supports model-prefix resolution when configured through bootstrap defaults.

## Basic streaming

For simple streaming output, use `onStreamDelta(...)`:

```php
$response = AI::provider('gemini')
    ->model('gemini-2.5-pro')
    ->addMessage('Write a short paragraph about the ocean.')
    ->onStreamDelta(function ($delta) {
        echo $delta;
    })
    ->run();
```

You can also use the lower-level `onEvent(...)` or `eventDispatcher(...)` APIs when you need direct access to all stream/runtime events.

For the full chat-oriented callback surface, see `chat.md`.

## Tools

Define inline tools directly on the fluent AI facade:

```php
$response = AI::provider('gemini')
    ->model('gemini-2.5-pro')
    ->setToolContextValue('temp', 69)
    ->defineTool(
        'get_current_temperature',
        'Get the current temperature for a city',
        array(
            'type' => 'object',
            'properties' => array(
                'location' => array('type' => 'string'),
            ),
            'required' => array('location'),
        ),
        function (array $arguments) {
            return array(
                'location' => $arguments['location'],
                'temperature' => 69,
                'unit' => 'F',
            );
        }
    )
    ->addMessage('What is the temperature in Atlanta?')
    ->run();
```

For larger real-world usage, class-based tools via `ToolInterface` or `AbstractTool` are usually cleaner.

See `tools.md` for more.

## Conversation continuity

If persistence and replay are enabled, `boru/ai` can resume prior conversations using a shared `ConversationReference` and provider-aware replay behavior.

See `replay.md` for details.

## Assets and persistence

If you plan to work with uploaded files or persistent conversations, also review:

- `assets.md`
- `persistence.md`

## Where to go next

- `configuration.md`
- `chat.md`
- `tools.md`
- `replay.md`
- `assets.md`
- `persistence.md`
- `architecture.md`
- `cli.md`
