README

Composer plugin that auto-discovers AI model providers (SPI) for the adachsoft/ai-model-list core library by scanning installed packages and generating a deterministic registry. The registry is read at runtime to instantiate providers without any application code changes after install/update/remove.

Key goals:

Plugin-and-play for lib-ext providers via Composer plugin (no app code changes when adding/removing providers)
Fast runtime (no vendor scanning): discovery runs only during composer install/update/remove
Clean SPI contract: providers are created through factories with explicit configuration validation

Requirements

PHP 8.3+
Composer 2.x
adachsoft/ai-model-list (installed automatically as a dependency)

Installation

composer require adachsoft/ai-model-list-plugin:^0.3

If your Composer config restricts plugins, enable this plugin explicitly:

{
  "config": {
    "allow-plugins": {
      "adachsoft/ai-model-list-plugin": true
    }
  }
}

How it works

During composer install/update/remove the plugin scans installed packages and looks for an entry file declaring providers.
Supported entry file locations (first match wins): 1) composer.json extra key: extra.ai-model-list.entry-file (relative path within package) 2) Fallback: resources/ai-model-list.php
The entry file MUST return an array with a providers key, where each provider entry contains a factory FQCN implementing the SPI factory interface from the core library.
The plugin writes a generated registry file under this plugin package directory:
- vendor/adachsoft/ai-model-list-plugin/.generated/ai-model-list-registry.php

Runtime usage (global modes)

Use the factory provided by this plugin to build providers according to a global mode. The API returns a DTO with providers and collected errors.

use AdachSoft\AIModelListPlugin\Factory\ProviderCollectionFactory;
use AdachSoft\AIModelListPlugin\Factory\ProviderCollectionFactoryInterface;
use AdachSoft\AIModelListPlugin\Enum\ProviderCreationModeEnum;
use AdachSoft\AIModelListPlugin\Dto\ProviderCreationOptionsDto;
use AdachSoft\AIModelListPlugin\Dto\ProviderCreationResultDto;
use AdachSoft\AIModelListPlugin\Exception\PluginConfigurationException;
use AdachSoft\AIModelList\Spi\Config\EnvConfigurationProvider;
use Psr\Log\LoggerInterface;

// 1) Build your global configuration provider (env-based example)
$globalConfig = new EnvConfigurationProvider();

// 2) Choose mode and (optionally) pass a PSR-3 logger
$options = new ProviderCreationOptionsDto(ProviderCreationModeEnum::FAIL_SOFT /*, $logger */);

// 3) Create providers according to the selected mode
/** @var ProviderCollectionFactoryInterface $factory */
$factory = new ProviderCollectionFactory();

// FAIL_SOFT — returns valid providers and collects errors (no exceptions)
$result = $factory->create($globalConfig, $options);

// DRY_RUN — validates configuration only; does not return providers; collects errors
$dryRun = $factory->create($globalConfig, new ProviderCreationOptionsDto(ProviderCreationModeEnum::DRY_RUN));

// FAIL_FAST — throws on the first configuration error with a precise message
try {
    $fast = $factory->create($globalConfig, new ProviderCreationOptionsDto(ProviderCreationModeEnum::FAIL_FAST));
} catch (PluginConfigurationException $e) {
    // Example message:
    // "Missing required environment variable: ADACHSOFT_AI_MODEL_LIST_PROVIDER_ANTHROPIC_API_KEY."
    // "Set ENV ADACHSOFT_AI_MODEL_LIST_PROVIDER_ANTHROPIC_API_KEY or configuration key adachsoft/ai-model-list-provider-anthropic.api_key."
}

Notes:

The factory hides internal registry paths. Your application does not need to reference plugin internals.
Error messages include the exact ENV name and an alternative dotted configuration key for quick fixes.
If you pass a PSR-3 logger in options, FAIL_FAST logs errors (error level) and FAIL_SOFT/DRY_RUN log warnings.

Entry file format (lib-ext package)

Entry file MUST return an array with providers only. No side-effects.

<?php
return [
    'providers' => [
        ['factory' => 'Vendor\\Pkg\\Factory\\YourProviderFactory'],
        // more providers...
    ],
];

Each factory MUST implement:

AdachSoft\\AIModelList\\Spi\\AiModelProvider\\Factory\\AiModelProviderFactoryInterface

Factory contract (from core library) requires:

public static function make(ConfigurationProviderInterface $config): AiModelProviderInterface
MUST validate config (throw ProviderConfigurationException on missing/invalid values)

Global modes and errors

FAIL_FAST: throws PluginConfigurationException on the first provider configuration error.
FAIL_SOFT: no exception; valid providers are returned, errors are collected in the result DTO.
DRY_RUN: no providers are returned; configuration is validated and errors are collected.
All configuration errors are normalized to messages that MUST contain the exact ENV name and a dotted key alternative.

Development

Run coding standard fixes:
```
composer cs:fix
```
Run static analysis:
```
composer phpstan
```
Run tests:
```
composer test
```

License

MIT

adachsoft / ai-model-list-plugin

Maintainers

Details