Llm Sdk Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require 1tomany/llm-sdk
   

   For Laravel, consider using the Symfony bundle for autowiring and configuration.

2. First Use Case: Generate a simple LLM response using OpenAI:

   use OneToMany\LlmSdk\Clients\OpenAI\Client;
   use OneToMany\LlmSdk\Requests\GenerateOutputRequest;
   
   $client = new Client('your-api-key');
   $request = new GenerateOutputRequest(
       model: 'gpt-4',
       prompt: 'Hello, world!'
   );
   $response = $client->generateOutput($request);
   echo $response->getResponse();
   

3. Key Files to Review:

   • examples/outputs/generate.php for basic usage.
   • src/Clients for platform-specific clients.
   • src/Requests for request classes.

Implementation Patterns

Core Workflows

1. Direct Client Usage (Simple Integration)

• Instantiate a client and call methods directly.
• Best for one-off scripts or small projects.

$client = new Client('api-key');
$request = new GenerateOutputRequest(model: 'gpt-4', prompt: 'Explain Laravel');
$response = $client->generateOutput($request);

2. Action-Based Workflow (Laravel-Friendly)

• Register clients with a ClientFactory and inject actions into services.
• Ideal for Laravel apps with dependency injection.

// Register clients (e.g., in a service provider)
$factory = new ClientFactory();
$factory->register('openai', new OpenAI\Client('api-key'));

// Inject into a service
$service = new MyService($factory);

// Use actions
$action = $factory->getAction('openai', 'generate-output');
$response = $action->execute($request);

3. Query Compilation (Advanced Use Cases)

• Build complex queries with prompts, files, schemas, and system instructions.
• Useful for RAG (Retrieval-Augmented Generation) or batch processing.

$query = new Query();
$query->addPrompt('Explain Laravel');
$query->addSystemInstruction('Be concise.');
$compiled = $client->compileQuery($query);
$response = $client->processQuery($compiled);

4. File Handling

• Upload/delete files for multimodal models (e.g., Gemini).

$fileRequest = new FileRequest(
    file: fopen('document.pdf', 'r'),
    purpose: 'assistants'
);
$client->uploadFile($fileRequest);

5. Embeddings

• Generate vectors for semantic search or similarity tasks.

$embeddingRequest = new CreateEmbeddingRequest(
    model: 'text-embedding-ada-002',
    input: 'Laravel is a PHP framework.'
);
$response = $client->createEmbedding($embeddingRequest);

6. Search Stores (Gemini-Specific)

• Create and query vector stores for RAG.

$store = $client->createSearchStore('my-store', 'gemini-1.5-pro');
$results = $client->searchStore($store->getId(), 'Explain Laravel');

Integration Tips

Laravel-Specific

• Service Providers: Bind the ClientFactory to the container for easy access.

  $this->app->singleton(ClientFactory::class, function ($app) {
      $factory = new ClientFactory();
      $factory->register('openai', new OpenAI\Client(config('services.openai.key')));
      return $factory;
  });
  

• Configuration: Use Laravel’s config system to manage API keys.

  // config/services.php
  'openai' => [
      'key' => env('OPENAI_KEY'),
  ],
  

• Jobs/Queues: Offload LLM calls to background jobs for async processing.

  use OneToMany\LlmSdk\Actions\GenerateOutputAction;
  
  class GenerateContentJob implements ShouldQueue
  {
      public function handle(ClientFactory $factory) {
          $action = $factory->getAction('openai', 'generate-output');
          $response = $action->execute(new GenerateOutputRequest(...));
      }
  }
  

Testing

• Use the Mock client for unit tests.

  $mockClient = new Mock\Client();
  $factory->register('mock', $mockClient);
  

• Mock actions in Laravel tests:

  $this->partialMock(ClientFactory::class, function ($mock) {
      $mock->shouldReceive('getAction')
           ->with('openai', 'generate-output')
           ->andReturn(new MockGenerateOutputAction());
  });
  

Error Handling

• Catch OneToMany\LlmSdk\Exceptions\LlmSdkException for generic errors.
• Handle platform-specific exceptions (e.g., OpenAI\Exceptions\RateLimitException).

  try {
      $response = $client->generateOutput($request);
  } catch (RateLimitException $e) {
      // Retry or notify user
  }
  

Gotchas and Tips

Pitfalls

1. Platform Feature Gaps:

   • Not all platforms support the same features (e.g., Anthropic lacks batch operations).
   • Fix: Check the feature matrix before implementation.
   • Workaround: Use the Mock client for unsupported features during prototyping.

2. File Handling Limitations:

   • Most platforms only support upload/delete, not listing/download.
   • Fix: Track file metadata locally if needed.

3. Query Compilation Overhead:

   • Compiling queries adds complexity for simple use cases.
   • Tip: Use direct methods (e.g., generateOutput) for straightforward requests.

4. Rate Limiting:

   • Platforms like OpenAI enforce strict rate limits.
   • Tip: Implement exponential backoff in your retry logic:

     use Symfony\Component\Retry\Retry;
     
     $retry = Retry::create(3, function ($attempt) {
         return $attempt > 1 ? 2 ** $attempt * 100 : 0;
     });
     

5. Model Availability:

   • Some models (e.g., gpt-5.4) may not be available to all users.
   • Tip: Validate model support before use:

     if (!$client->supportsModel('gpt-5.4')) {
         throw new \RuntimeException('Model not available');
     }
     

6. Hash Collisions:

   • Request hashing (for caching/batching) uses sha256.
   • Tip: Avoid identical requests with different non-hashed parameters (e.g., timestamps).

Debugging Tips

1. Log Requests/Responses:

   • Enable logging in the Client constructor:

     $client = new Client('api-key', [
         'logger' => new \Monolog\Logger('llm'),
     ]);
     

   • Or manually log compiled queries:

     $compiled = $client->compileQuery($query);
     \Log::debug('Query hash:', [$compiled->getHash(), $compiled->toArray()]);
     

2. Validate API Keys:

   • Test with the Mock client first to rule out key issues:

     $mockClient = new Mock\Client();
     $mockClient->setMockResponse(['choices' => [['text' => 'Mock response']]]);
     

3. Check Response Types:

   • Some methods return objects, others arrays. Refer to the response interfaces.
   • Example:

     $response = $client->generateOutput($request);
     if ($response instanceof GenerateOutputResponse) {
         $output = $response->getResponse(); // string or array
     }
     

4. Batch Processing:

   • Batches require platform-specific IDs. Use readBatch to track status:

     $batch = $client->createBatch([$request1, $request2]);
     $status = $client->readBatch($batch->getId());
     

Extension Points

1. Custom Clients:
   • Extend OneToMany\LlmSdk\Clients\BaseClient for unsupported platforms.
   • Example:

     class CustomClient extends BaseClient {
         public function generateOutput(GenerateOutputRequest $request) {