Laravel Toon Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require squareetlabs/laravel-toon
   php artisan vendor:publish --provider="SquareETLabs\LaravelToon\LaravelToonServiceProvider"
   

   Publish the config file to config/toon.php and update your .env with API keys if needed.

2. First Use Case Convert a standard JSON payload to TOON format before sending to an LLM:

   use SquareETLabs\LaravelToon\Facades\Toon;
   
   $data = [
       'user' => 'John Doe',
       'context' => 'Analyze this user data for sentiment',
       'metadata' => ['age' => 30, 'preferences' => ['tech', 'sports']]
   ];
   
   $toonString = Toon::encode($data);
   // Output: "U:John Doe,C:Analyze this user data for sentiment,M:{age:30,preferences:[tech,sports]}"
   

3. Where to Look First

   • Facade: SquareETLabs\LaravelToon\Facades\Toon (for quick encoding/decoding).
   • Config: config/toon.php (customize compression rules, token thresholds, or LLM-specific optimizations).
   • Artisan Command: php artisan toon:analyze (test token savings on existing JSON payloads).

Implementation Patterns

Core Workflows

1. Prompt Optimization Pipeline

   // Before sending to LLM (e.g., OpenAI)
   $optimizedPrompt = Toon::encode($rawPrompt)
       ->compress() // Apply TOON rules
       ->setMaxTokens(1000) // Enforce budget
       ->toString();
   

2. Model Serialization/Deserialization

   // Serialize Eloquent model to TOON for API payloads
   $user = User::find(1);
   $toonData = Toon::modelToToon($user, ['name', 'email', 'posts']);
   
   // Later, decode back to array/object
   $decodedData = Toon::decode($toonData);
   

3. Middleware for API Requests

   // app/Http/Middleware/OptimizeLLMPayload.php
   public function handle($request, Closure $next) {
       if ($request->isLlmEndpoint()) {
           $request->merge(['data' => Toon::encode($request->data)]);
       }
       return $next($request);
   }
   

4. Batch Processing

   // Optimize a collection of prompts (e.g., for batch LLM calls)
   $prompts = Prompt::where('needs_optimization', true)->get();
   $optimized = $prompts->map(fn($p) => Toon::encode($p->content));
   

Integration Tips

• LLM Service Integration: Use the toon() helper in service classes to auto-optimize payloads:

  class OpenAIService {
      public function analyze($data) {
          $optimized = Toon::encode($data);
          return $this->client->chat()->create([
              'messages' => [['content' => $optimized]],
          ]);
      }
  }
  

• Caching Optimized Payloads: Cache TOON-encoded strings to avoid reprocessing:

  $cacheKey = 'toon:prompt:' . md5($rawPrompt);
  $optimized = Cache::remember($cacheKey, now()->addHours(1), function() use ($rawPrompt) {
      return Toon::encode($rawPrompt);
  });
  

• Custom Rules: Extend default TOON rules via config or service providers:

  // config/toon.php
  'custom_rules' => [
      'date' => fn($value) => $value->format('Y-m-d'), // Normalize dates
      'array' => fn($value) => array_filter($value), // Remove empty values
  ],
  

Gotchas and Tips

Pitfalls

1. Token Count Mismatches

   • TOON reduces tokens, but always validate with the LLM’s tokenizer:

     $tokenCount = Toon::tokenCount($toonString); // Estimate
     $actualCount = $llmClient->countTokens($toonString); // Verify
     

   • Fix: Use Toon::setMaxTokens() to enforce budgets pre-encoding.

2. Data Loss in Compression

   • TOON drops null/empty values by default. Explicitly whitelist critical fields:

     Toon::encode($data, ['keep_nulls' => ['id', 'created_at']]);
     

3. Performance Overhead

   • Encoding/decoding adds ~5-10ms per operation. Cache aggressively for high-throughput systems.

4. LLM-Specific Quirks

   • Some LLMs (e.g., Claude) handle TOON differently. Test with:

     Toon::setLLM('claude')->encode($data);
     

Debugging

• Inspect TOON Output:

  Toon::debug($data); // Shows raw JSON + TOON + token counts
  

• Token Breakdown:

  $analysis = Toon::analyze($data);
  // Returns: ['original_tokens' => 1200, 'toon_tokens' => 400, 'savings' => 66.67]
  

Extension Points

1. Custom Encoders/Decoders:

   // Register a custom encoder for your domain objects
   Toon::extend('User', function($user) {
       return Toon::encode([
           'id' => $user->id,
           'name' => $user->name,
           'roles' => $user->roles->pluck('name'),
       ]);
   });
   

2. Hooks for Pre/Post Processing:

   Toon::macro('beforeEncode', function($callback) {
       $this->data = $callback($this->data);
       return $this;
   });
   
   // Usage:
   Toon::encode($data)->beforeEncode(fn($d) => array_map('strtolower', $d));
   

3. Event Listeners: Listen for toon.encoded/toon.decoded events to log or transform data:

   Toon::listen('encoded', function($toonString, $originalData) {
       Log::debug("TOON encoded", ['original_size' => strlen(json_encode($originalData))]);
   });
   

Config Quirks

• Default Compression Level: Set in config/toon.php ('compression_level'). Higher values = more aggressive token reduction but risk data loss.
• Reserved Keys: TOON reserves keys like U: (user), C: (context). Avoid using these as array keys in your data.
• Fallback to JSON: If TOON fails (e.g., unsupported data type), it falls back to JSON. Check logs for warnings.