jkudish / laravel-ai-librarium

v1.0.0 2026-10-27 22:59 UTC

Requires

• php: ^8.4
• illuminate/cache: ^13.30
• illuminate/console: ^13.30
• illuminate/contracts: ^13.30
• illuminate/database: ^13.30
• illuminate/encryption: ^13.30
• illuminate/filesystem: ^13.30
• illuminate/http: ^13.30
• illuminate/redis: ^13.30
• illuminate/routing: ^13.30
• illuminate/support: ^13.30
• illuminate/validation: ^13.30
• jkudish/laravel-ai-pricing: ^0.3.1 || ^0.4.1
• jkudish/librarium-spec: ^1.0
• laravel/ai: ^1.0.1
• laravel/prompts: ^0.3.15
• league/commonmark: ^2.10.2
• opis/json-schema: ^2.6
• standard-webhooks/standard-webhooks: ^1.0

Requires (Dev)

• larastan/larastan: ^3.13
• laravel/pint: ^1.32.1
• orchestra/testbench: ^11.0
• pestphp/pest: ^4.4.1 || ^5.3.1
• pestphp/pest-plugin-arch: ^4.0 || ^5.0
• pestphp/pest-plugin-laravel: ^4.1 || ^5.0.1
• phpstan/extension-installer: ^1.4.3
• predis/predis: ^3.4

MIT

• Joey Kudish

• laravel
• research
• ai

Published on Packagist.org on 2026-10-27 22:59 UTC

README

Laravel AI Librarium sends one research question to the search APIs, research APIs, and AI answer engines you configure, then stores the answers, citations, and costs as a Run.

It is built on the official Laravel AI SDK. Full documentation lives at librarium.si/docs/php.

Requirements

• PHP 8.4 or newer
• Laravel 13.30 or newer
• Laravel AI SDK ^1.0.1, installed by Composer
• A key for at least one source. The example below uses the Laravel AI SDK's OPENAI_API_KEY.

Install

composer require jkudish/laravel-ai-librarium
php artisan vendor:publish --tag=librarium-config

Credentials come from config/ai.php and config/services.php. A per-source key override belongs in config/librarium.php, never in request options.

First research Run

Add OPENAI_API_KEY to .env, then preview and run one source:

use Jkudish\LaravelAiLibrarium\Facades\Librarium;

$question = 'Which PHP version does Laravel 13 require?';

$plan = Librarium::research($question)->only(['openai'])->dryRun();
$plan->status(); // "planned"

$run = Librarium::research($question)->only(['openai'])->run();
$run->status();                   // "done"
$run->result('openai')['answer']; // The answer text
$run->citations();                // [['url' => 'https://...', 'title' => '...'], ...]
$run->id();                       // "run_01..."

dryRun() makes no provider call and stores nothing. run() saves the Run, makes one paid OpenAI web-search request, and waits up to librarium.timeout (6900 seconds by default). Runs are saved encrypted under librarium/ on your default filesystem disk, which must be a local disk. Read one later with Librarium::find($id).

A Run's status is done when every source succeeded, partial when some failed, failed when none succeeded, or running when a durable task outlives the wait.

What it does

• Selects sources with only(), skip(), and saved groups. The shared catalog has 16 research sources and 5 AI answer engines, such as chatgpt and google-ai-overview.
• Uses deep() to choose research-report variants for Exa, Gemini, OpenAI, Parallel, Perplexity, Valyu, and You.com.
• Previews selection and price hints offline with dryRun() and Librarium::sources().
• Admits sources under a USD cap with maxCost().
• Queues research with queue() and resumes durable provider tasks with Librarium::find($id)?->refresh().
• Stores Runs on a local disk, in a database table, in a cache, in memory, or in your own RunStore.
• Uses the same librarium.run/1 Run JSON as the Librarium JavaScript CLI and library.
• Adds librarium:research, librarium:show, librarium:sources, and librarium:prune Artisan commands, plus a Tools\RunEvidence tool for Laravel AI SDK agents.
• Fakes research in tests with Librarium::fake().

Limits

• maxCost() is an admission cap, not a provider-enforced ceiling. Accepted calls can finish and bill above it. Sources without a bounded estimate are skipped as unpriced under a cap. A cost the provider did not report stays null, never zero.
• Librarium never resubmits paid work or falls back to another source automatically. Inline work cannot resume after the process dies. Durable tasks with a saved handle can.
• Built-in file storage supports local Laravel disks only. Built-in cache storage supports process-local ArrayStore or standalone Redis 7+. Other backends need a custom RunStore.
• The database store's migration is optional and never runs automatically.
• AI answer engines need a collector: SearchAPI, DataForSEO, or the separate Firecrawl adapter. Engine results are observations of a consumer AI product (observation: surface), not API answers.
• Provider text and URLs are untrusted. Escape rendered content and verify consequential claims. Agreement between sources is not independent confirmation.
• Your application owns queue workers, authorization, retention, and evidence policy.

Learn more

• Laravel guide: library API, configuration and storage, Artisan commands, costs and limits, and testing
• Sources and options, including Anthropic prompt caching
• Budget and cost
• Runs, storage, and recovery
• Writing a source driver and writing a RunStore
• Librarium spec: the shared source catalog, Run schemas, and fixtures
• Changelog

Report bugs and ask questions in GitHub issues.

The Librarium family

• Librarium: the JavaScript CLI, MCP server and library (npm install -g librarium).
• Laravel AI Librarium: Firecrawl: collects AI answer engine results for the Laravel package through Firecrawl browser sessions.
• librarium-spec: the shared Run schemas, source catalog and conformance fixtures.
• librarium.si: documentation for all of them.

Sponsoring

If you find Laravel AI Librarium useful, consider becoming a sponsor or donating.

Contributing and security

See CONTRIBUTING.md to work on the code. To report a vulnerability, see SECURITY.md.

License

MIT