# Assets and files

`boru/ai` uses a provider-agnostic core asset model with provider-specific asset bindings.

This means:

- one core asset may be reused across multiple providers
- OpenAI and Gemini bindings stay separate
- provider binding lifecycle can vary without changing core asset identity

For config details behind asset binding policy, see `configuration.md`. For storage details, see `persistence.md`.

## Core idea

A core asset represents the file or image itself.

A provider asset binding represents that asset's remote representation for a specific provider, such as an uploaded OpenAI file or a provider-specific URI.

## Creating or reusing an asset from a local file

Use:

```php
$asset = AI::assetFromFile('/path/to/example.pdf', 'file');
```

This convenience method:

- reads file metadata
- calculates sha256
- checks persistence for an existing matching asset
- reuses the core asset if found
- otherwise creates and saves a new one

## Attaching an asset

```php
$response = AI::provider('gemini')
    ->model('gemini-2.5-pro')
    ->attachAsset($asset, 'user_data', 'file')
    ->addMessage('Please summarize the attached PDF.')
    ->run();
```

## Example: Gemini PDF summary

```php
$asset = AI::assetFromFile('/path/to/file.pdf', 'file');

$response = AI::provider('gemini')
    ->model('gemini-2.5-pro')
    ->instructions('You are a precise document summarizer.')
    ->attachAsset($asset, 'user_data', 'file')
    ->addMessage('Please summarize the attached PDF. Include key conclusions.')
    ->run();

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

## Asset binding lifecycle

Asset reuse and cleanup behavior is controlled by `AssetBindingPolicy`, which resolves settings from:

- `persistence.asset_bindings.*`
- `providers.{name}.asset_bindings.*`
- env overrides using the same dotted-path-to-env normalization pattern

Supported keys:

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

## Provider-specific asset preparation

Provider-specific file compatibility logic belongs in the provider layer.

For example, a provider can normalize unsupported but text-like files into a provider-compatible upload format while preserving the original core asset identity.

## Design note

Core assets are library-owned and provider agnostic.

Provider file ids and URIs are binding data, not core asset identity.

## See also

- `configuration.md`
- `persistence.md`
- `architecture.md`
