README

This library provides an AI ToolCall integration for querying Packagist package information using the adachsoft/packagist-api-client.

It exposes SPI tools that can be registered in the adachsoft/ai-tool-call ecosystem and used by higher-level agents to fetch package metadata, download statistics, search for packages and manage package registrations on Packagist.

Features

• SPI tool for retrieving Packagist package data and download statistics (packagist_package_info).
• SPI tool for creating a new Packagist package from a VCS repository URL (packagist_package_create).
• SPI tool for triggering an update of an existing Packagist package by repository URL (packagist_package_update).
• SPI tool for searching Packagist packages by query and optional filters (packagist_package_search).
• SPI tool for retrieving recent versions, per-version metadata and download statistics for a Packagist package (packagist_package_versions).
• Simple configuration via AI ToolCall SPI ConfigMap (Packagist API username and API token).
• Ready-made factories for wiring the tools into an AiToolCallFacade.

Installation

Install via Composer:

composer require adachsoft/packagist-tool

Usage

1. Register the SPI tool factories in your AI ToolCall facade:

use AdachSoft\AiToolCall\PublicApi\Builder\AiToolCallFacadeBuilder;
use AdachSoft\AiToolCall\SPI\Collection\ConfigMap;
use App\PackagistTool\Factory\PackagistPackageInfoToolFactory;
use App\PackagistTool\Factory\PackagistPackageCreateToolFactory;
use App\PackagistTool\Factory\PackagistPackageUpdateToolFactory;
use App\PackagistTool\Factory\PackagistPackageSearchToolFactory;
use App\PackagistTool\Factory\PackagistPackageVersionsToolFactory;

$facade = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new PackagistPackageInfoToolFactory(),
        new PackagistPackageCreateToolFactory(),
        new PackagistPackageUpdateToolFactory(),
        new PackagistPackageSearchToolFactory(),
        new PackagistPackageVersionsToolFactory(),
    ])
    ->withToolConfigs([
        'packagist_package_info' => new ConfigMap([
            'username' => 'your-packagist-username',
            'api_token' => 'your-api-token',
        ]),
        'packagist_package_create' => new ConfigMap([
            'username' => 'your-packagist-username',
            'api_token' => 'your-api-token',
        ]),
        'packagist_package_update' => new ConfigMap([
            'username' => 'your-packagist-username',
            'api_token' => 'your-api-token',
        ]),
        'packagist_package_search' => new ConfigMap([
            'username' => 'your-packagist-username',
            'api_token' => 'your-api-token',
        ]),
        'packagist_package_versions' => new ConfigMap([
            'username' => 'your-packagist-username',
            'api_token' => 'your-api-token',
            'versions_limit' => 5,
        ]),
    ])
    ->build();

1. Call the tools from your application:

use AdachSoft\AiToolCall\PublicApi\Dto\ToolCallRequestDto;

// Fetch package info
$infoRequest = new ToolCallRequestDto(
    toolName: 'packagist_package_info',
    parameters: [
        'package_name' => 'vendor/package',
    ],
);

$infoResult = $facade->callTool($infoRequest);

// Create a new package from repository URL
$createRequest = new ToolCallRequestDto(
    toolName: 'packagist_package_create',
    parameters: [
        'repository_url' => 'https://github.com/vendor/package.git',
    ],
);

$createResult = $facade->callTool($createRequest);

// Update an existing package by repository URL
$updateRequest = new ToolCallRequestDto(
    toolName: 'packagist_package_update',
    parameters: [
        'repository_url' => 'https://github.com/vendor/package.git',
    ],
);

$updateResult = $facade->callTool($updateRequest);

// Search for packages
$searchRequest = new ToolCallRequestDto(
    toolName: 'packagist_package_search',
    parameters: [
        'query' => 'symfony',
        'filters' => [
            'type' => 'library',
        ],
    ],
);

$searchResult = $facade->callTool($searchRequest);

// Fetch recent versions and version metadata
$versionsRequest = new ToolCallRequestDto(
    toolName: 'packagist_package_versions',
    parameters: [
        'package_name' => 'vendor/package',
    ],
);

$versionsResult = $facade->callTool($versionsRequest);

/** @var array{
 *   package_name: string,
 *   downloads: array{total: int, monthly: int, daily: int},
 *   versions: array<int, string>,
 *   versions_data: array<string, array{name: string, time: ?string, version: ?string, version_normalized: ?string}>,
 *   average: string,
 *   date: string,
 * } $versionsData
 */
$versionsData = $versionsResult->result;

// $infoResult->result, $createResult->result, $updateResult->result, $searchResult->result
// and $versionsData contain structured data returned by the Packagist API via the SPI tools

Testing

This library is covered by unit and functional tests. To run the tests locally use:

composer install
vendor/bin/phpunit

For static analysis and code style checks:

composer stan
composer cs:check