README

Synapse TOON
High-performance API payload optimization engine for Laravel

Synapse TOON transforms verbose JSON API responses into ultra-dense representations, reducing token consumption by 25–45% while preserving full semantic fidelity. Ship faster APIs and pay dramatically less for LLM inference.

Every runtime surface ships with an explicit SynapseToon prefix, making package ownership obvious in your codebase and eliminating class-name collisions.

Highlights

• Cost Savings First — Reduce LLM API bills by 25–45% through entropy-aware encoding, adaptive compression, and smart routing.
• Performance Native — HTTP/3 detection, Brotli/Gzip negotiation, and SSE streaming deliver sub-100 ms response times.
• Observable by Default — Log, Prometheus, and Datadog drivers expose savings metrics and ROI in real time.
• Production Ready — Queue-aware batch jobs, edge caching, and complexity-aware routing keep high-traffic APIs responsive.
• Framework Native — Middleware aliases, response macros, and Octane preloading for zero-friction Laravel integration.
• Zero Lock-in — Bring your own vector stores, LLM clients, and cache drivers via lightweight contracts.

Requirements

Installation

composer require vinkius-labs/synapse-toon

Publish the configuration file:

php artisan vendor:publish --tag=synapse-toon-config

Register middleware in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->api(append: [
        \VinkiusLabs\SynapseToon\Http\Middleware\SynapseToonCompressionMiddleware::class,
        \VinkiusLabs\SynapseToon\Http\Middleware\SynapseToonHttp3Middleware::class,
    ]);
})

Quick Start

Encode a response

use VinkiusLabs\SynapseToon\Facades\SynapseToon;

// Before: 1,247 tokens → After: 683 tokens (45% reduction)
$encoded = SynapseToon::encoder()->encode([
    'products' => Product::with('category', 'reviews')->get(),
    'meta' => ['page' => 1, 'per_page' => 50],
]);

return response()->synapseToon($encoded);

Stream an LLM response

return response()->synapseToonStream($llmStream, function ($chunk) {
    return [
        'delta' => $chunk['choices'][0]['delta']['content'],
        'usage' => $chunk['usage'] ?? null,
    ];
});

Route by complexity

$target = SynapseToon::router()->route($payload, [
    'complexity' => 0.4,
    'tokens' => 512,
]);

Build RAG context

$context = SynapseToon::rag()->buildContext(
    'How do I implement OAuth2 in Laravel?',
    ['user_id' => auth()->id()]
);

Dispatch a batch job

use VinkiusLabs\SynapseToon\Jobs\SynapseToonProcessLLMBatchJob;

SynapseToonProcessLLMBatchJob::dispatch($prompts, [
    'queue'      => 'llm-batch',
    'connection' => 'openai',
    'batch_size' => 50,
]);

Architecture Overview

Real-World Impact

Average token reduction: 40.7%

Documentation

Testing

Run the test suite locally via Docker:

docker compose build
docker compose run --rm app bash -c "composer install --no-interaction && vendor/bin/phpunit"

Or, if you have PHP 8.2+ installed locally:

composer install
vendor/bin/phpunit

Compatibility

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a pull request.

Security

If you discover a security vulnerability, please review our Security Policy. Do not open a public issue.

Changelog

All notable changes are documented in the Changelog.

License

Copyright 2026 Vinkius Labs

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.