Larapanda: типізований Lightpanda Browser SDK для Laravel

Larapanda — це Laravel SDK для Lightpanda, headless-браузера, написаного на Zig. Пакет автоматизує вибір між CLI та Docker, дозволяє керувати інстансами через профілі, надає типізовані результати запитів та має адаптери для Laravel AI SDK і MCP-сервера.

# Керування інстансами через профілі

Конфігурація організована у вигляді іменованих профілів. Для кожного профілю можна перевизначити глобальні налаштування середовища (runtime), шлях до бінарного файлу та параметри Docker. Це дозволяє легко розділяти сесії для звичайних запитів, веб-краулінгу чи роботи AI-інструментів.

// config/larapanda.php
'instances' => [
    'default' => [],
    'crawler' => [
        'runtime' => 'cli',
        'binary_path' => '/absolute/path/to/lightpanda',
    ],
    'mcp' => [
        'runtime' => 'docker',
    ],
],

Вибір профілю під час виклику реалізовано через інтерфейс менеджера:

use Ferdiunal\Larapanda\Contracts\LarapandaManagerInterface;
 
$manager = app(LarapandaManagerInterface::class);
 
$defaultClient = $manager->instance('default');
$crawlerClient = $manager->instance('crawler');

# Визначення середовища виконання

Режим auto надає пріоритет CLI, якщо вказано коректний binary_path і файл є виконуваним. У зворотному випадку система автоматично перемикається на Docker. Також можна чітко закріпити профіль за cli або docker.

# Типізовані результати запитів

Метод fetchRequest() повертає об'єкт FetchResult із суворими аксесорами для обраного формату даних. Якщо викликати метод, що не відповідає формату (наприклад, очікувати Markdown від JSON), пакет видасть виключення UnexpectedFetchOutputFormatException замість некоректних даних.

use Ferdiunal\Larapanda\Enums\FetchDumpFormat;
 
$result = $client->fetchRequest('https://example.com')
    ->withOptions(
        dump: FetchDumpFormat::Markdown,
        obeyRobots: true,
        waitMs: 2000,
    )
    ->run();
 
$markdown = $result->asMarkdown();
 
// Формати семантичного дерева
$treeResult = $client->fetchRequest('https://example.com')
    ->withOptions(dump: FetchDumpFormat::SemanticTree)
    ->run();
 
$tree = $treeResult->asSemanticTree(); // array<string, mixed>

Підтримка проксі налаштовується для кожного окремого запиту:

$result = $client->fetchRequest('https://example.com')
    ->withOptions(
        dump: FetchDumpFormat::Markdown,
        httpProxy: 'http://127.0.0.1:3000',
        proxyBearerToken: 'MY-TOKEN',
    )
    ->run();

# Інтеграція з Laravel AI SDK

Larapanda додає можливості Lightpanda як інструменти (tools) для Laravel AI SDK. Адаптер підтримує роботу із сесіями: передача одного й того самого session_id дозволяє зберігати стан браузера між різними викликами, що критично для багатокрокових завдань.

composer require laravel/ai laravel/mcp

use Ferdiunal\Larapanda\Integrations\Ai\LarapandaAiTools;
use Illuminate\Support\Facades\AI;
 
$response = AI::provider('openai')
    ->model('gpt-5-mini')
    ->prompt('Open laravel.com and return the main headings.')
    ->tools(app(LarapandaAiTools::class)->make())
    ->text();

Назви інструментів використовують префікс (за замовчуванням lightpanda_): lightpanda_markdown, lightpanda_semantic_tree, lightpanda_click тощо. Список доступних для моделі інструментів можна обмежити в конфігурації:

'integrations' => [
    'ai' => [
        'exposed_tools' => ['goto', 'markdown', 'semantic_tree'],
    ],
],

# Адаптер для MCP-сервера

Для застосунків, що використовують Laravel MCP server, Larapanda пропонує адаптер, який реєструє інструменти Lightpanda у контейнері Laravel. Він автоматично керує середовищем виконання та використовує спільний пул сесій і політику проксі разом із AI SDK.

// routes/ai.php
use Ferdiunal\Larapanda\Integrations\Mcp\LarapandaMcpServer;
 
LarapandaMcpServer::registerLocal(name: 'lightpanda');

Час життя сесії та розмір пулу налаштовуються у конфігу:

'integrations' => [
    'mcp' => [
        'session_ttl_seconds' => 300,
        'max_sessions' => 32,
        'obey_robots' => true,
    ],
],

Вихідний код та повна документація доступні на GitHub.