Toolkit: набір багаторазових інструментів для Laravel AI SDK

Toolkit від Ship Fast Labs — це каталог готових інструментів для Laravel AI SDK. Хоча проєкт ведеться в одному monorepo, інструменти розповсюджуються як окремі пакети Composer, що дозволяє встановлювати лише необхідні компоненти для конкретного агента.

# Один пакет — один інструмент, без Service Providers

Кожен інструмент — це клас, що реалізує інтерфейс Laravel\Ai\Contracts\Tool з методами description(), handle() та schema(). Тут немає спільного ядра, реєстрації service providers чи публікації конфігів. Достатньо встановити потрібний пакет, створити екземпляр класу та передати його в метод tools() агента:

composer require shipfastlabs/toolkit-calculator
composer require shipfastlabs/toolkit-database

use Shipfastlabs\Toolkit\Calculator\CalculatorTool;
use Shipfastlabs\Toolkit\Database\DatabaseQueryTool;
 
$tools = [
    new CalculatorTool,
    new DatabaseQueryTool,
];

Кожен інструмент описує своє призначення через description() та параметри через schema(), а модель сама вирішує, коли їх викликати. Результати, включно з помилками, повертаються у вигляді рядків. Це дозволяє моделі опрацьовувати збої та коригувати запити замість того, щоб програма переривалася винятком (exception).

# Калькулятор без eval()

Інструмент Calculator обробляє рядок expression за допомогою парсера рекурсивного спуску, уникаючи небезпечного PHP eval(). Він підтримує +, -, *, /, %, ^ (піднесення до степеня), дужки, унарні знаки та десяткові дроби. Некоректні дані, ділення на нуль або нескінченні результати повертаються моделі як звичайні рядки. Це «чистий» інструмент: жодних конфігурацій чи реєстрацій.

# Безпечні запити до бази даних (Read-Only)

Інструмент Database виконує SQL-запити SELECT і повертає результат у форматі JSON. Основний акцент зроблено на безпеці:

• Дозволено лише один оператор, що починається з SELECT (або WITH … SELECT для CTE).
• Ключові слова INSERT, UPDATE, DELETE, DROP, ALTER відхиляються навіть у підзапитах.
• Запити з роздільником ; не допускаються.
• До будь-якого запиту автоматично додається LIMIT, якщо він відсутній.

Конфігурація здійснюється через ключ ai.toolkit.* у стандартному файлі config/ai.php від Laravel AI SDK — окремий файл налаштувань не потрібен:

// config/ai.php
 
'toolkit' => [
    'database' => [
        'connection' => env('TOOLKIT_DATABASE_CONNECTION'),
        'max_rows' => (int) env('TOOLKIT_DATABASE_MAX_ROWS', 100),
    ],
],

Використання read-only репліки через параметр connection забезпечує додатковий рівень захисту, а max_rows обмежує обсяг отриманих даних.

# Провайдери для вебпошуку та досліджень

Три пакети інтегрують популярні API для пошуку. Кожен має хелпер для реєстрації всіх інструментів одразу або можливість вибору окремих класів:

• Exa (toolkit-exa): ExaSearch, ExaFindSimilar, ExaGetContents та ExaAnswer для семантичного пошуку, вилучення контенту та отримання відповідей із посиланнями на джерела.
• Perplexity (toolkit-perplexity): PerplexitySearch та PerplexityAsk для роботи з моделями Sonar у режимах web, academic та sec.
• Tavily (toolkit-tavily): TavilySearch, TavilyExtract, TavilyCrawl та TavilyMap для пошуку, парсингу та мапінгу сайтів.

use Shipfastlabs\Toolkit\Exa\Exa;
 
$tools = Exa::all(); // Collection<int, Tool>

API-ключі беруться з конфігу services, а налаштування за замовчуванням — з ai.toolkit.*. Числові параметри автоматично обмежуються допустимими діапазонами, а помилки API повертаються у вигляді тексту.

# Бібліотека ендпоінтів JigsawStack

Пакет JigsawStack (toolkit-jigsawstack) надає інструменти для роботи з різними категоріями API: переклад, вебсканування, комп'ютерний зір, аудіо та валідація. Сюди входять: аналіз настрою, сумаризація, text-to-SQL, OCR, детекція об'єктів, перетворення мовлення в текст та перевірка на спам чи нецензурну лексику.

Кожен інструмент відповідає одному ендпоінту та повертає відформатований JSON-відповідь. Тайм-аут запитів становить 60 секунд, а за відсутності API-ключа модель отримає зрозуміле повідомлення про помилку налаштування.

# Встановлення

Виберіть потрібні інструменти та встановіть їх окремо:

composer require shipfastlabs/toolkit-calculator
composer require shipfastlabs/toolkit-tavily

Для роботи з зовнішніми API додайте ключі у config/services.php та відповідні змінні в .env. Детальні налаштування для кожного інструмента доступні в документації.

Повний каталог доступний на сайті Toolkit, а вихідний код — на GitHub.