README

Synapse TOON is a Laravel-native engine for extreme API payload optimization and LLM cost reduction. It transforms verbose JSON into ultra-dense representations, trimming token consumption by 25–45% while preserving full semantic fidelity—so you ship faster APIs and pay dramatically less for inference.

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

"When every token costs money, compression becomes product strategy." – The Synapse TOON Manifesto 💰

Why Synapse TOON?

• Cost Savings First – Consistently 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 the SynapseToonSseStreamer deliver sub-100 ms response times without manual tuning.
• Observable by Default – SynapseToonLogMetricsDriver, Prometheus, and Datadog integrations expose savings metrics, thresholds, and ROI in real time.
• Production Ready – Queue-aware SynapseToonProcessLLMBatchJob, SynapseToonEdgeCache, and complexity-aware routing keep high-traffic APIs responsive.
• Framework Native – Middleware aliases, response macros, and Octane preloading mean zero friction for Laravel teams.
• Zero Lock-in – Bring your own vector stores, LLM clients, and cache drivers—the contracts stay feather-light yet explicit.

Table of Contents

1. Getting Started
2. Configuration Guide
3. Encoding & Compression
4. Streaming & SSE
5. Metrics & Analytics
6. RAG Integration
7. Batch Processing
8. GraphQL Adapter
9. Edge Cache
10. HTTP/3 Optimization
11. Cost Optimization Guide
12. Performance Tuning
13. Technical Reference
14. Contributing

Quick Peek

💰 Cost Reduction in Action

use VinkiusLabs\SynapseToon\Facades\SynapseToon;

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

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

📊 Real-Time Savings Analytics

SynapseToon::metrics()->record([
    'endpoint' => '/api/products',
    'json_tokens' => 1247,
    'toon_tokens' => 683,
    'savings_percent' => 45.2,
    'compression_algorithm' => 'brotli',
]);

🚀 Streaming LLM Responses

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

🎯 Smart Model Routing

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

SynapseToon::router()->send($payload, [
    'connection' => 'openai.client',
    'batch' => true,
]);

🔍 RAG Context Optimization

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

🧊 Edge Cache Warmups

$payload = SynapseToon::edgeCache()->remember('feeds:new', function () {
    return ProductResource::collection(Product::latest()->take(100)->get());
});

🧪 Batch Job Offloading

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

What's Inside

• SynapseToonEncoder / SynapseToonDecoder – Lossless TOON codec with dictionary support, chunked encoding, and heuristics aware of entropy per token.
• SynapseToonCompressor – Adaptive Brotli (Q8), Gzip, and Deflate selection based on Accept-Encoding and HTTP/3 hints.
• SynapseToonSseStreamer – Server-Sent Events with zero-copy chunking, UUID event IDs, and buffer flush guardrails.
• SynapseToonEdgeCache – Encode-once edge cache helper tuned for Redis/Octane workloads.
• SynapseToonMetrics – Driver-agnostic metrics core speaking to SynapseToonLogMetricsDriver, Prometheus, Datadog, or custom drivers.
• SynapseToonProcessLLMBatchJob – Queue-friendly batch encoder that collapses up to 50 prompts per dispatch while tracking ROI.
• SynapseToonLLMRouter – Complexity-aware model router with pluggable SynapseToonLLMClient implementations.
• SynapseToonRagService – Vector-store abstraction that squeezes context with snippet thresholds and metadata braiding.
• SynapseToonGraphQLAdapter – Drops straight into Lighthouse or Rebing GraphQL pipelines with TOON encoding baked in.
• SynapseToonPayloadAnalyzer – Token analytics and savings calculator powering middleware and dashboards.

💡 Real-World Impact

Average token reduction: 40.7%
At $0.03/1K tokens: $600/month → $356/month = $244 saved monthly

🚀 Installation

composer require vinkius-labs/synapse-toon

Publish configuration:

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

Register middleware in bootstrap/app.php (Laravel 11+):

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

🎯 Core Use Cases

1. LLM API Cost Reduction

Route::middleware(['synapsetoon.compression'])->group(function () {
    Route::post('/ai/complete', [AIController::class, 'complete']);
    Route::post('/ai/embed', [AIController::class, 'embed']);
});

2. Real-Time Streaming

public function streamCompletion(Request $request)
{
    $stream = OpenAI::chat()->createStreamed([
        'model' => 'gpt-4o',
        'messages' => $request->input('messages'),
        'stream' => true,
    ]);

    return response()->synapseToonStream($stream);
}

3. Batch Processing

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

4. RAG Optimization

$optimizedContext = SynapseToon::rag()->buildContext($userQuery, [
    'limit' => 3,
    'max_snippet_length' => 200,
]);

⚙️ Configuration Highlights

'compression' => [
    'prefer' => 'brotli',
    'brotli' => ['quality' => 8, 'mode' => 'generic'],
],

'metrics' => [
    'driver' => 'prometheus',
    'thresholds' => ['minimum_savings_percent' => 8],
],

'batch' => [
    'size' => 50,
    'delimiter' => "\t",
],

'router' => [
    'strategies' => [
        ['name' => 'ultra-light', 'max_tokens' => 512, 'target' => 'gpt-4o-mini'],
        ['name' => 'balanced', 'max_tokens' => 2048, 'target' => 'gpt-4o'],
    ],
    'default_target' => 'o1-preview',
],

🧪 Local Development

docker compose build

docker compose run --rm app bash -lc \
  "composer install && vendor/bin/phpunit"

docker compose run --rm app bash

📊 Compatibility Matrix

🎯 Performance Benchmarks

Encoding Speed:
- 1KB payload: ~0.12ms
- 10KB payload: ~0.87ms
- 100KB payload: ~8.4ms

Compression (Brotli quality 8):
- 10KB → 2.3KB (77% reduction) in ~2.1ms
- 100KB → 18.7KB (81% reduction) in ~19.3ms

Total Overhead:
- Small responses (<5KB): +0.5-1.2ms
- Medium responses (5-50KB): +1.5-4.8ms
- Large responses (50KB+): +8-25ms

ROI Break-Even:
- Token cost savings > overhead at ~200 tokens
- Average API response: 1,500 tokens
- Net savings: ~40% cost reduction