feat: add PSR-3 logging support

Author: CodeWithKyrian

README.md

@@ -136,7 +136,8 @@ Transformers::setup()
     ->setRemotePathTemplate('...') // Set the remote path template for downloading models. Defaults to `{model}/resolve/{revision}/{file}`
     ->setAuthToken('...') // Set the auth token for downloading models. Defaults to `null`
     ->setUserAgent('...') // Set the user agent for downloading models. Defaults to `transformers-php/{version}`
-    ->setImageDriver('...') // Set the image driver for processing images. Defaults to `IMAGICK'
+    ->setImageDriver('...') // Set the image driver for processing images. Defaults to `VIPS`
+    ->setLogger($logger) // Set a PSR-3 compatible logger. Defaults to `NullLogger` if not set
     ->apply(); // Apply the configuration
 ```
 

composer.json

@@ -18,6 +18,7 @@
     "codewithkyrian/jinja-php": "^1.0",
     "codewithkyrian/platform-package-installer": "^1.0",
     "imagine/imagine": "^1.3",
+    "psr/log": "^1.1 || ^2.0 || ^3.0",
     "rindow/rindow-math-matrix": "^2.1",
     "rindow/rindow-matlib-ffi": "^1.1",
     "rindow/rindow-openblas-ffi": "^1.0",
@@ -77,4 +78,4 @@
       "windows-x86_64": "https://github.com/codewithkyrian/transformers-php/releases/download/{version}/dist-windows-x86_64.zip"
     }
   }
-}
+}

docs/configuration.md

@@ -15,14 +15,16 @@ models, and the remote path template. These settings allow you to tailor how and
 ```php
 use Codewithkyrian\Transformers\Transformers;
 use Codewithkyrian\Transformers\Utils\ImageDriver;
+use Psr\Log\LoggerInterface;
 
 Transformers::setup()
         ->setCacheDir('/path/to/models')
         ->setRemoteHost('https://yourmodelshost.com')
         ->setRemotePathTemplate('custom/path/{model}/{file}')
         ->setAuthToken('your-token')
         ->setUserAgent('your-user-agent')
-        ->setImageDriver(ImageDriver::IMAGICK);
+        ->setImageDriver(ImageDriver::IMAGICK)
+        ->setLogger($logger);
 ```
 
 ::: tip
@@ -94,8 +96,7 @@ Transformers::setup()->setUserAgent('your-user-agent');
 ### `setImageDriver(ImageDriver $imageDriver)`
 
 This setting allows you to specify the image backend to use for image processing tasks. By default, the image driver is
-not set and an error will be thrown if you try to perform any image related task. You can change this to `IMAGICK`, `GD`
-or `VIPS` if you prefer, just make sure to have the required extensions installed.
+set to `VIPS`. You can change this to `IMAGICK`, `GD` or `VIPS` if you prefer, just make sure to have the required extensions installed.
 
 ```php
 use Codewithkyrian\Transformers\Utils\ImageDriver;
@@ -105,6 +106,24 @@ Transformers::setup()
     ->apply();
 ```
 
+### `setLogger(LoggerInterface $logger)`
+
+This setting allows you to specify a PSR-3 compatible logger for TransformersPHP. The library will log various events such as model loading, generation progress, warnings, and errors. If no logger is set, a `NullLogger` will be used by default, which discards all log messages.
+
+```php
+use Psr\Log\LoggerInterface;
+use Monolog\Logger;
+use Monolog\Handler\StreamHandler;
+
+// Create a logger instance (example using Monolog)
+$logger = new Logger('transformers');
+$logger->pushHandler(new StreamHandler('logs/transformers.log', Logger::INFO));
+
+Transformers::setup()
+    ->setLogger($logger)
+    ->apply();
+```
+
 ## Standalone PHP Projects
 
 In a standalone PHP project, the best place to add global configuration is in your project's bootstrap or initialization
@@ -138,6 +157,7 @@ set the cache directory to the subdirectory of the `storage` directory, as it's
 
 ```php [AppServiceProvider.php]
 use Codewithkyrian\Transformers\Transformers;
+use Illuminate\Support\Facades\Log;
 
 public function boot()
 {
@@ -147,6 +167,7 @@ public function boot()
         ->setRemotePathTemplate('custom/path/{model}/{file}')
         ->setAuthToken('your-token')
         ->setUserAgent('your-user-agent')
+        ->setLogger(Log::getLogger())
         ->apply();
 }
 ```
@@ -162,15 +183,20 @@ services, making it a good place to set up global configurations.
 
 ```php [Kernel.php]
 use Codewithkyrian\Transformers\Transformers;
+use Psr\Log\LoggerInterface;
 
 public function boot()
 {
+    // Get the logger from the container
+    $logger = $this->getContainer()->get(LoggerInterface::class);
+    
     Transformers::setup()
         ->setCacheDir('/path/to/models')
         ->setRemoteHost('https://yourmodelshost.com')
         ->setRemotePathTemplate('custom/path/{model}/{file}')
         ->setAuthToken('your-token')
         ->setUserAgent('your-user-agent')
+        ->setLogger($logger)
         ->apply();
 }
 ```

examples/bootstrap.php

@@ -4,11 +4,26 @@
 
 use Codewithkyrian\Transformers\Transformers;
 use Codewithkyrian\Transformers\Utils\ImageDriver;
+use Psr\Log\AbstractLogger;
 
 require_once './vendor/autoload.php';
 
 $cacheDir = '/Volumes/KYRIAN SSD/Transformers';
 
+class FileLogger extends AbstractLogger
+{
+    public function __construct(protected string $filename) {}
+
+    public function log($level, $message, array $context = []): void
+    {
+        $line = sprintf("[%s][%s] %s %s\n", date('Y-m-d H:i:s'), strtoupper($level), $message, empty($context) ? '' : json_encode($context));
+        file_put_contents($this->filename, $line, FILE_APPEND);
+    }
+}
+
+$logger = new FileLogger(__DIR__ . '/transformers.log');
+
 Transformers::setup()
     ->setCacheDir($cacheDir)
+    ->setLogger($logger)
     ->setImageDriver(ImageDriver::VIPS);

examples/transformers.log

@@ -7,6 +7,7 @@
 use ArrayAccess;
 use Codewithkyrian\Transformers\Utils\Hub;
 use function Codewithkyrian\Transformers\Utils\array_pick;
+use Codewithkyrian\Transformers\Transformers;
 
 /**
  * The base class that implements the common methods for loading a configuration either from a local file or directory,
@@ -40,8 +41,7 @@ public static function fromPretrained(
         ?string   $cacheDir = null,
         string    $revision = 'main',
         ?callable $onProgress = null
-    ): self
-    {
+    ): self {
         $config ??= Hub::getJson(
             $modelNameOrPath,
             fileName: 'config.json',
@@ -50,7 +50,10 @@ public static function fromPretrained(
             fatal: false,
             onProgress: $onProgress
         );
-
+        if ($config === null) {
+            $logger = Transformers::getLogger();
+            $logger->warning('Config loading returned null, using fallback/defaults');
+        }
         return new self($config);
     }
 

src/Configs/PretrainedConfig.php

@@ -6,6 +6,7 @@
 namespace Codewithkyrian\Transformers\Decoders;
 
 use Codewithkyrian\Transformers\Tokenizers\AddedToken;
+use Codewithkyrian\Transformers\Transformers;
 
 /**
  * The base class for token decoders.
@@ -35,9 +36,11 @@ public function __construct(protected array $config)
      */
     public static function fromConfig(?array $config): ?self
     {
+        $logger = Transformers::getLogger();
         if ($config === null) {
             return null;
         }
+        $logger->debug('Creating decoder', ['type' => $config['type'] ?? 'unknown']);
 
         return match ($config['type']) {
             'WordPiece' => new WordPieceDecoder($config),
@@ -83,6 +86,4 @@ public function __invoke(array $tokens): string
     {
         return $this->decode($tokens);
     }
-
-
-}
+}

src/Decoders/Decoder.php

@@ -7,7 +7,7 @@
 
 use Codewithkyrian\Transformers\Tensor\Tensor;
 use Codewithkyrian\Transformers\Utils\Audio;
-use function Codewithkyrian\Transformers\Utils\timeUsage;
+use Codewithkyrian\Transformers\Transformers;
 
 class WhisperFeatureExtractor extends FeatureExtractor
 {
@@ -38,9 +38,10 @@ public function __construct(array $config)
     public function __invoke(Tensor $waveform): array
     {
         if ($waveform->size() > $this->config['n_samples']) {
-            trigger_error('Attempting to extract features for audio longer than 30 seconds.' .
+            $logger = Transformers::getLogger();
+            $logger->warning('Attempting to extract features for audio longer than 30 seconds.' .
                 'If using a pipeline to extract transcript from a long audio clip,' .
-                'remember to specify `chunkLengthSecs` and/or `strideLengthSecs` in the pipeline options.', E_USER_WARNING);
+                'remember to specify `chunkLengthSecs` and/or `strideLengthSecs` in the pipeline options.');
 
             $waveform = $waveform->sliceWithBounds([0], [$this->config['n_samples']]);
         } else if ($waveform->size() < $this->config['n_samples']) {
@@ -71,4 +72,4 @@ public function __invoke(Tensor $waveform): array
             'input_features' => $features->unsqueeze(0)
         ];
     }
-}
+}

src/FeatureExtractors/WhisperFeatureExtractor.php

@@ -17,4 +17,4 @@ abstract class LogitsProcessor
      * @return Tensor The processed logits.
      */
     abstract public function __invoke(array $inputIds, Tensor $logits): Tensor;
-}
+}

src/Generation/LogitsProcessors/LogitsProcessor.php

@@ -30,18 +30,18 @@ public function __construct(protected int $maxLength, protected ?int $maxPositio
      */
     public function __invoke(array $inputIds, array $scores): array
     {
-//        return array_map(fn ($ids) => count($ids) >= $this->maxLength, $inputIds);
         $results = [];
         foreach ($inputIds as $ids) {
             $currentLength = count($ids);
             $isDone = $currentLength >= $this->maxLength;
 
             if ($this->maxPositionEmbeddings !== null && !$isDone && $currentLength >= $this->maxPositionEmbeddings) {
-                echo
+                $logger = Transformers::getLogger();
+                $logger->warning(
                     "This is a friendly reminder - the current text generation call will exceed the model's predefined " .
-                    "maximum length ({$this->maxPositionEmbeddings}). Depending on the model, you may observe " .
-                    "exceptions, performance degradation, or nothing at all."
-                ;
+                        "maximum length ({$this->maxPositionEmbeddings}). Depending on the model, you may observe " .
+                        "exceptions, performance degradation, or nothing at all."
+                );
             }
 
             $results[] = $isDone;