README

Token-Optimized Object Notation for Laravel Compress your AI prompts, reduce API costs, and optimize LLM contexts seamlessly.

Overview

LaravelToon is a native Laravel package that integrates TOON (Token-Oriented Object Notation) a compact and readable format designed to optimize token usage in LLM contexts.

Why LaravelToon

Cost Savings: Reduces tokens by 60-70%, saving money on APIs
Native Integration: Service providers, Facades, Artisan commands ready to use
Multi-LLM: Supports OpenAI, Claude, Gemini, Mistral with ready-made adapters
Deep Analysis: Token analysis, compression metrics, cost estimation
High Performance: Integrated benchmarking and caching optimizations
Interactive Dashboard: CLI tool to explore and experiment

Quick Start

Installation

composer require squareetlabs/laravel-toon

Configuration (Optional)

php artisan vendor:publish --provider="Squareetlabs\LaravelToon\LaravelToonServiceProvider" --tag=laravel-toon-config

Basic Usage

use Squareetlabs\LaravelToon\Facades\Toon;

// Convert to TOON
$data = [
    'user' => 'John',
    'email' => 'john@example.com',
    'roles' => ['admin', 'user']
];

$toon = Toon::encode($data);
echo $toon;
// user: John
// email: john@example.com
// roles[2]: admin,user

// Or use helpers
echo toon_readable($data);      // Readable format
echo toon_compact($data);       // Compact format
echo toon_tabular($data);       // Tabular format

Documentation

Full Guides

Quick Start Guide - Get started in 5 minutes
Installation Guide - Detailed setup and configuration
Examples - 10+ real-world usage examples
README - Complete reference

Main Features

1. Compression and Conversion

// Complete compression analysis
$metrics = Toon::getMetrics($data);
echo "Bytes saved: " . $metrics['bytes_saved'] . "\n";
echo "Tokens saved: " . $metrics['tokens_saved'] . "\n";
echo "Ratio: " . $metrics['compression_ratio'] . "\n";

// Compare with JSON
$comparison = Toon::compareWithJson($data);

2. Token Analysis

use Squareetlabs\LaravelToon\Services\TokenAnalyzer;

$analyzer = app(TokenAnalyzer::class);

// Estimate tokens
$tokens = $analyzer->estimate($content);
$comparison = $analyzer->compareJsonVsToon($data);

// Token budget
$budget = $analyzer->budgetTokens(10000, $data);
// ['max_tokens' => 10000, 'tokens_used' => 2500, 'within_budget' => true]

3. API Cost Calculation

use Squareetlabs\LaravelToon\Services\CostCalculator;

$calculator = app(CostCalculator::class);

// Estimate cost for GPT-4o
$cost = $calculator->estimateCost('gpt-4o', $data, 'input');
// ['tokens' => 2500, 'cost' => 0.0625, 'cost_formatted' => '$0.0625']

// Compare JSON vs TOON cost
$comparison = $calculator->estimateWithJsonComparison('gpt-4o', $data);

// Compare prices across models
$models = $calculator->compareModels($data);

4. LLM API Adapters

use Squareetlabs\LaravelToon\Adapters\OpenAIAdapter;

$openai = new OpenAIAdapter();

// Send compressed message to OpenAI
$response = $openai->sendMessage(
    'Analyze this compressed JSON...',
    'gpt-4o',
    ['temperature' => 0.7]
);

// Chat with compressed messages
$messages = [
    ['role' => 'user', 'content' => 'First message'],
    ['role' => 'assistant', 'content' => 'Response'],
];

$chatResponse = $openai->chat($messages, 'gpt-4o');

Artisan Commands

toon:convert

Converts JSON files to TOON or vice versa.

# JSON to TOON
php artisan toon:convert data.json --format=readable

# TOON to JSON (decode)
php artisan toon:convert data.toon --decode --pretty

# Save to file
php artisan toon:convert data.json --output=compressed.toon

toon:analyze

Analyzes compression and efficiency.

php artisan toon:analyze data.json --verbose

Shows:

JSON vs TOON size
Estimated tokens
Reduction percentage
Recommendations

toon:benchmark

Runs performance and cost estimation benchmarks.

php artisan toon:benchmark data.json --iterations=100 --model=gpt-4o

Shows:

Encoding/decoding time
Size comparison
Cost estimation

toon:dashboard

Interactive dashboard to explore LaravelToon.

php artisan toon:dashboard

Allows:

Convert JSON TOON
Analyze compression
Estimate costs
View model prices

� Available Helpers

// Encoding
toon($data)                          // Readable format
toon_compact($data)                  // Compact format
toon_readable($data)                 // Readable format
toon_tabular($data)                  // Tabular format
toon_convert($data, 'compact')       // With specified format

// Decoding
toon_decode($toon)                   // TOON to PHP

// Compression and Metrics
toon_compress($data)                 // Full compression
toon_metrics($data)                  // Detailed metrics
toon_compression_summary($data)      // Summary

// Tokens
toon_estimate_tokens($content)       // Estimate tokens
toon_compare_json_vs_toon($data)     // Compare JSON vs TOON
toon_analyze($content)               // Detailed analysis

// Benchmark
toon_benchmark($data, 100)           // Performance benchmark

// Costs
toon_cost_estimate('gpt-4o', $data)          // Estimate cost
toon_cost_compare_models($data)              // Compare models
toon_cost_with_json_comparison('gpt-4o', $data) // With JSON comparison
toon_budget_analysis('gpt-4o', 100, $data)  // Budget analysis

Integration with Eloquent Models

use Squareetlabs\LaravelToon\Traits\HasToonEncoding;

class User extends Model
{
    use HasToonEncoding;
}

$user = User::first();

// Convert to TOON
echo $user->toToon();                    // Readable format
echo $user->toToonCompact();             // Compact format

// Get metrics
$metrics = $user->getToonMetrics();
$ratio = $user->getToonCompressionRatio();

Validation

use Squareetlabs\LaravelToon\Rules\ValidToonFormat;

$request->validate([
    'compressed_data' => [new ValidToonFormat()],
]);

Advanced Configuration

The config/laravel-toon.php file allows you to configure:

return [
    // Encoding options
    'encoding' => [
        'indent' => 2,
        'delimiter' => ',',
        'min_rows_to_tabular' => 2,
    ],

    // Token analysis
    'token_analysis' => [
        'enabled' => true,
        'estimate_method' => 'character_ratio',
        'cache_results' => true,
    ],

    // LLM model prices
    'cost_calculation' => [
        'models' => [
            'gpt-4o' => ['input' => 0.0025, 'output' => 0.010],
            'claude-3-sonnet' => ['input' => 0.003, 'output' => 0.015],
            // ... more models
        ],
    ],

    // Compression middleware
    'middleware' => [
        'auto_compress' => false,
        'min_response_size' => 1024,
    ],
];

Use Cases

1. ChatGPT Prompt Optimization

$prompt = "Analyze this dataset with millions of records...";
$data = $largeDataset;

$optimized = [
    'system_message' => 'You are an expert data analyst',
    'user_prompt' => $prompt,
    'data' => toon_compact($data),
];

// Save 60% of tokens
$tokens = toon_estimate_tokens(json_encode($optimized));

2. RAG with Optimized Context

$contextData = $database->search('query', 1000);

$ragPrompt = [
    'context' => toon_compact($contextData),
    'query' => 'User question',
];

$cost = toon_cost_estimate('gpt-4o', $ragPrompt);
// Significantly reduces costs

3. Cost Monitoring

// In your controller
public function sendToAI(Request $request)
{
    $data = $request->validated();
    
    $budget = toon_budget_analysis('gpt-4o', 100, $data);
    
    if (!$budget['within_budget']) {
        return response()->json([
            'error' => 'Exceeds token budget'
        ]);
    }
    
    // Proceed...
}

Testing

use Squareetlabs\LaravelToon\Facades\Toon;

class ToonTest extends TestCase
{
    public function test_compression_ratio()
    {
        $data = ['users' => range(1, 1000)];
        $ratio = Toon::calculateCompressionRatio($data);
        
        $this->assertLessThan(0.4, $ratio); // Less than 40%
    }
}

Environment Variables

# LLM APIs
OPENAI_API_KEY=sk-...
OPENAI_API_BASE=https://api.openai.com/v1

ANTHROPIC_API_KEY=sk-ant-...

GEMINI_API_KEY=AIzaSy...

MISTRAL_API_KEY=...

# LaravelToon
LARAVEL_TOON_ENABLED=true

Contributing

Contributions are welcome! Please:

Fork the repository
Create a branch for your feature (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

About

LaravelToon is developed and maintained by SquareetLabs

Support

For support, create an issue in the repository or contact labs@squareet.com

LaravelToon v1.0.0 - November 14, 2025

squareetlabs / laravel-toon

Maintainers

Details