README

Laravel SDK for the EchoIntel AI API -- forecasting, customer segmentation, inventory optimization, anomaly detection, credit risk, NLP, and more.

Packagist: https://packagist.org/packages/echointel/laravel-sdk

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x, or 12.x
• Composer

Installation

composer require echointel/laravel-sdk

The service provider and facade are registered automatically via Laravel auto-discovery.

Publish Configuration

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

Environment Variables

Add the following to your .env file:

ECHOINTEL_CUSTOMER_API_ID=your-customer-api-id
ECHOINTEL_SECRET=your-secret-key

Sandbox / Production

The SDK defaults to sandbox mode when ECHOINTEL_SANDBOX is absent.

# Sandbox (default) - https://ai.echosistema.dev
ECHOINTEL_SANDBOX=true

# Production - https://ai.echosistema.live
ECHOINTEL_SANDBOX=false

You can also override the URLs directly:

ECHOINTEL_API_URL=https://ai.echosistema.live
ECHOINTEL_SANDBOX_API_URL=https://ai.echosistema.dev

Optional

ECHOINTEL_ADMIN_SECRET=your-admin-secret
ECHOINTEL_TIMEOUT=30

Quick Start

Using the Facade

use EchoIntel\Facades\EchoIntel;

// Health check
$health = EchoIntel::health();

// Forecast revenue
$result = EchoIntel::forecastRevenue([
    'forecast_period' => 12,
    'data' => [
        ['date' => '2024-01-01', 'revenue' => 10000],
        ['date' => '2024-02-01', 'revenue' => 12000],
    ],
]);

// Customer segmentation
$segments = EchoIntel::customerSegmentation([
    'data' => $customerRecords,
    'max_clusters' => 5,
]);

Using Dependency Injection

use EchoIntel\EchoIntelClient;

class ForecastController extends Controller
{
    public function __construct(
        private EchoIntelClient $echointel
    ) {}

    public function revenue(Request $request)
    {
        $result = $this->echointel->forecastRevenue([
            'forecast_period' => $request->period,
            'data' => $request->data,
        ]);

        return response()->json($result);
    }
}

Using the Helper

$result = echointel()->forecastRevenue($data);

Available Methods

System

Forecasting

Inventory

Customer Analytics

Churn Analysis

NPS

Propensity Modeling

Recommendations

Cross-Sell & Upsell

Dynamic Pricing

Sentiment Analysis

Anomaly Detection

Credit Risk

Marketing Attribution

Customer Journey

NLP & Text Processing

Advanced Segmentation (Admin)

Reporting (Admin)

Async ML Jobs

Dead Letter Queue (Admin)

Route Resolver

The SDK includes a RouteResolver for semantic route permissions using dot notation. This is used when creating or updating customers via the Admin API.

use EchoIntel\RouteResolver;

// Wildcard: all non-admin routes
RouteResolver::resolve(['*']);

// Entire category
RouteResolver::resolve(['forecasting']);

// Specific endpoint
RouteResolver::resolve(['forecasting.revenue', 'customer.segmentation']);

// List available categories
RouteResolver::categories();
// ['system', 'forecasting', 'inventory', 'customer', ...]

// List endpoints in a category
RouteResolver::endpoints('forecasting');
// ['revenue', 'cost', 'cost_improved', 'units', 'cost_totus']

Error Handling

use EchoIntel\Facades\EchoIntel;
use EchoIntel\Exceptions\EchoIntelException;
use EchoIntel\Exceptions\EchoIntelValidationException;
use EchoIntel\Exceptions\EchoIntelAuthenticationException;

try {
    $result = EchoIntel::forecastRevenue($data);
} catch (EchoIntelValidationException $e) {
    // HTTP 422
    $errors = $e->getErrors();
} catch (EchoIntelAuthenticationException $e) {
    // HTTP 401 / 403
    $message = $e->getMessage();
} catch (EchoIntelException $e) {
    // Other API errors
    $statusCode = $e->getStatusCode();
    $message = $e->getMessage();
}

Configuration

After publishing, edit config/echointel.php:

return [
    // Sandbox mode (default: true)
    // Set to false for production
    'sandbox' => filter_var(env('ECHOINTEL_SANDBOX', true), FILTER_VALIDATE_BOOLEAN),

    // Production URL
    'api_url' => env('ECHOINTEL_API_URL', 'https://ai.echosistema.live'),

    // Sandbox URL
    'sandbox_api_url' => env('ECHOINTEL_SANDBOX_API_URL', 'https://ai.echosistema.dev'),

    // Credentials
    'customer_api_id' => env('ECHOINTEL_CUSTOMER_API_ID'),
    'secret' => env('ECHOINTEL_SECRET'),
    'admin_secret' => env('ECHOINTEL_ADMIN_SECRET'),

    // Request timeout (seconds)
    'timeout' => env('ECHOINTEL_TIMEOUT', 30),

    // Retry on failure
    'retry' => [
        'attempts' => 3,
        'delay' => 100, // milliseconds
    ],
];

Upgrading from v1.x to v2.0

Breaking Changes

API endpoint URLs changed from snake_case to kebab-case.

This is a server-side change. The SDK methods remain the same -- no code changes are needed in your application. However, the underlying HTTP requests now target kebab-case URLs:

Default API URL changed. The SDK now defaults to sandbox mode (https://ai.echosistema.dev). To use production, set ECHOINTEL_SANDBOX=false in your .env.

New in v2.0

• Sandbox mode toggle via ECHOINTEL_SANDBOX environment variable
• Separate ECHOINTEL_API_URL (production) and ECHOINTEL_SANDBOX_API_URL (sandbox) configuration

Testing

composer test

Security

If you discover any security-related issues, please email security@echosistema.email instead of using the issue tracker.

Credits

• EchoSistema

License

Proprietary. See License File for details.