README

A high-performance, strictly-typed, and enterprise-grade Laravel wrapper for the Exa.ai v2.1 API.

Features

🚀 PHP 8.2+ with Asymmetric Visibility and Property Hooks (PHP 8.4)
🔧 Fluent Builder Pattern for maximum IDE discoverability
🛡️ Strictly Typed DTOs - No raw arrays reach the end-user
🔄 Automatic Retries with exponential backoff for 429 and 5xx errors
📊 Laravel Context Integration for enterprise observability
🔑 Multi-Connection Support for managing multiple API keys
✅ PHPStan Level 9 compliant

Requirements

PHP 8.2 or higher
Laravel 10.x, 11.x, or 12.x

Installation

composer require sepehr-mohseni/exaravel

Publish the configuration file:

php artisan vendor:publish --tag=exaravel-config

Add your API key to your .env file:

EXA_API_KEY=your-api-key-here

Usage

Search

use Sepehr_Mohseni\Exaravel\Facades\Exa;
use Sepehr_Mohseni\Exaravel\Enums\SearchType;
use Sepehr_Mohseni\Exaravel\Enums\Category;

// Basic search
$results = Exa::search('Laravel best practices')->get();

// Advanced search with fluent builder
$results = Exa::search('Machine learning frameworks')
    ->type(SearchType::Neural)
    ->category(Category::GitHub)
    ->numResults(20)
    ->includeDomains(['github.com', 'gitlab.com'])
    ->excludeDomains(['stackoverflow.com'])
    ->startPublishedDate('2024-01-01')
    ->endPublishedDate(new DateTime('now'))
    ->withContents(text: true, highlights: true)
    ->withAutoprompt()
    ->get();

// Iterate over results
foreach ($results as $result) {
    echo $result->title . ' - ' . $result->url . PHP_EOL;
}

// Get first result directly
$firstResult = Exa::search('PHP 8.4 features')->first();

Find Similar

// Find content similar to a URL
$results = Exa::findSimilar('https://laravel.com/docs/eloquent')
    ->numResults(10)
    ->excludeSourceDomain()
    ->category(Category::ResearchPaper)
    ->withContents(text: true, summary: true)
    ->get();

Get Contents

// Retrieve full content for specific document IDs
$contents = Exa::contents(['doc-id-1', 'doc-id-2', 'doc-id-3'])
    ->withText(maxCharacters: 10000)
    ->withMarkdown()
    ->withHighlights(perUrl: 3)
    ->withSummary('What are the key points?')
    ->get();

foreach ($contents as $content) {
    echo $content->title . PHP_EOL;
    echo $content->getPreferredContent(); // Returns markdown if available, otherwise text
}

Answer (Agentic Endpoint)

// Get a direct answer with citations
$response = Exa::answer('What are the new features in PHP 8.4?')
    ->numResults(5)
    ->neural()
    ->includeDomains(['php.net', 'wiki.php.net'])
    ->systemPrompt('You are a PHP expert. Provide detailed technical explanations.')
    ->get();

echo $response->answer;

foreach ($response->citations as $citation) {
    echo "Source: {$citation->url}" . PHP_EOL;
}

// Get just the answer text
$answerText = Exa::answer('Explain Laravel service providers')->text();

Working with Results

$results = Exa::search('Laravel packages')->get();

// Collection-like methods
$urls = $results->urls();
$titles = $results->titles();

// Filter results
$highScoring = $results->filter(fn ($result) => $result->score > 0.8);

// Map results
$summaries = $results->map(fn ($result) => [
    'title' => $result->title,
    'url' => $result->url,
]);

// Check results
if ($results->isEmpty()) {
    echo 'No results found';
}

echo "Found {$results->count()} results";

Multiple Connections

Configure multiple API keys in config/exaravel.php:

'connections' => [
    'default' => [
        'api_key' => env('EXA_API_KEY'),
    ],
    'premium' => [
        'api_key' => env('EXA_PREMIUM_API_KEY'),
        'timeout' => 60,
    ],
],

Use a specific connection:

$results = Exa::using('premium')
    ->search('Complex query')
    ->get();

// Or use a custom API key on the fly
$results = Exa::withApiKey('custom-key')
    ->search('Query')
    ->get();

Error Handling

use Sepehr_Mohseni\Exaravel\Exceptions\AuthenticationException;
use Sepehr_Mohseni\Exaravel\Exceptions\RateLimitException;
use Sepehr_Mohseni\Exaravel\Exceptions\InsufficientCreditsException;
use Sepehr_Mohseni\Exaravel\Exceptions\ValidationException;

try {
    $results = Exa::search('query')->get();
} catch (AuthenticationException $e) {
    // Invalid API key
} catch (RateLimitException $e) {
    // Rate limit exceeded
    $retryAfter = $e->retryAfter; // seconds to wait
} catch (InsufficientCreditsException $e) {
    // Need more API credits
} catch (ValidationException $e) {
    // Invalid request parameters
    $errors = $e->errors;
}

Livecrawl Mode

use Sepehr_Mohseni\Exaravel\Enums\LivecrawlMode;

$results = Exa::search('Latest tech news')
    ->livecrawl(LivecrawlMode::Always, timeout: 10000)
    ->get();

Configuration

// config/exaravel.php

return [
    'api_key' => env('EXA_API_KEY'),
    'base_url' => env('EXA_BASE_URL', 'https://api.exa.ai'),
    'timeout' => env('EXA_TIMEOUT', 30),
    'connect_timeout' => env('EXA_CONNECT_TIMEOUT', 10),
    
    'retry' => [
        'times' => env('EXA_RETRY_TIMES', 3),
        'sleep_milliseconds' => env('EXA_RETRY_SLEEP', 500),
        'when' => [429, 500, 502, 503, 504],
    ],
    
    'default_search_type' => env('EXA_DEFAULT_SEARCH_TYPE', 'auto'),
    'default_num_results' => env('EXA_DEFAULT_NUM_RESULTS', 10),
    
    'logging' => [
        'enabled' => env('EXA_LOGGING_ENABLED', false),
        'channel' => env('EXA_LOGGING_CHANNEL', 'stack'),
    ],
];

Testing

composer test

Run static analysis:

composer analyse

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

sepehr-mohseni / exaravel

Maintainers

Details