fix: Tensor topK error when -1 is passed

additional: New tensor method `random`

src/Pipelines/AudioClassificationPipeline.php

@@ -7,6 +7,8 @@
 
 use Codewithkyrian\Transformers\Utils\Audio;
 
+use function Codewithkyrian\Transformers\Utils\array_pop_key;
+
 /**
  * Audio classification pipeline using any `AutoModelForAudioClassification`.
  * This pipeline predicts the class of a raw waveform or an audio file.
@@ -39,7 +41,7 @@ class AudioClassificationPipeline extends Pipeline
 {
     public function __invoke(array|string $inputs, ...$args): array
     {
-        $topK = $args["topK"] ?? 1;
+        $topK = array_pop_key($args, 'topK', 1);
 
         $isBatched = is_array($inputs);
 

src/Pipelines/FillMaskPipeline.php

@@ -9,6 +9,8 @@
 use Codewithkyrian\Transformers\Pipelines\Pipeline;
 use Codewithkyrian\Transformers\Utils\Math;
 
+use function Codewithkyrian\Transformers\Utils\array_pop_key;
+
 /**
  * Masked language modeling prediction pipeline.
  *
@@ -34,7 +36,7 @@ class FillMaskPipeline extends Pipeline
 {
     public function __invoke(array|string $inputs, ...$args): array
     {
-        $topK = $args["topK"] ?? 5;
+        $topK = array_pop_key($args, 'topK', 5);
 
         $modelInputs = $this->tokenizer->__invoke($inputs, padding: true, truncation: true);
 

src/Pipelines/ImageClassificationPipeline.php

@@ -7,6 +7,8 @@
 
 use Codewithkyrian\Transformers\Models\Output\SequenceClassifierOutput;
 use Codewithkyrian\Transformers\Utils\Math;
+
+use function Codewithkyrian\Transformers\Utils\array_pop_key;
 use function Codewithkyrian\Transformers\Utils\prepareImages;
 use function Codewithkyrian\Transformers\Utils\timeUsage;
 
@@ -54,7 +56,7 @@ class ImageClassificationPipeline extends Pipeline
 {
     public function __invoke(array|string $inputs, ...$args): array
     {
-        $topK = $args["topK"] ?? 1;
+        $topK = array_pop_key($args, 'topK', 1);
 
         $isBatched = is_array($inputs);
 

src/Pipelines/QuestionAnsweringPipeline.php

@@ -8,6 +8,8 @@
 use Codewithkyrian\Transformers\Models\Output\QuestionAnsweringModelOutput;
 use Codewithkyrian\Transformers\Utils\Math;
 
+use function Codewithkyrian\Transformers\Utils\array_pop_key;
+
 /**
  * Question answering pipeline
  *
@@ -27,7 +29,7 @@ public function __invoke(array|string $inputs, ...$args): array
     {
         $question = $inputs;
         $context = $args[0] ?? $args["context"];
-        $topK = $args["topK"] ?? 1;
+        $topK = array_pop_key($args, 'topK', 1);
 
         $inputs = $this->tokenizer->__invoke($question, $context, padding: true, truncation: true);
 

src/Pipelines/TextClassificationPipeline.php

@@ -8,6 +8,8 @@
 use Codewithkyrian\Transformers\Models\Output\SequenceClassifierOutput;
 use Codewithkyrian\Transformers\Tensor\Tensor;
 
+use function Codewithkyrian\Transformers\Utils\array_pop_key;
+
 /**
  * Text classification pipeline
  *
@@ -59,7 +61,7 @@ class TextClassificationPipeline extends Pipeline
 {
     public function __invoke(array|string $inputs, ...$args): array
     {
-        $topK = $args["topK"] ?? 1;
+        $topK = array_pop_key($args, 'topK', 1);
 
         $modelInputs = $this->tokenizer->tokenize($inputs, padding: true, truncation: true);
 

src/Pipelines/ZeroShotObjectDetectionPipeline.php

@@ -6,6 +6,8 @@
 namespace Codewithkyrian\Transformers\Pipelines;
 
 use Codewithkyrian\Transformers\Models\Output\ObjectDetectionOutput;
+
+use function Codewithkyrian\Transformers\Utils\array_pop_key;
 use function Codewithkyrian\Transformers\Utils\getBoundingBox;
 use function Codewithkyrian\Transformers\Utils\prepareImages;
 
@@ -51,9 +53,9 @@ class ZeroShotObjectDetectionPipeline extends Pipeline
     public function __invoke(array|string $inputs, ...$args): array
     {
         $candidateLabels = $args[0];
-        $threshold = $args['threshold'] ?? 0.1;
-        $topK = $args['topK'] ?? null;
-        $percentage = $args['percentage'] ?? false;
+        $threshold = array_pop_key($args, 'threshold', 0.1);
+        $topK = array_pop_key($args, 'topK', -1);
+        $percentage = array_pop_key($args, 'percentage', false);
 
         $isBatched = is_array($inputs);
 

src/Tensor/Tensor.php

@@ -16,8 +16,6 @@
 use Rindow\Math\Matrix\Complex;
 use Rindow\Math\Matrix\ComplexUtils;
 use Rindow\Math\Matrix\Drivers\Service;
-
-//use Rindow\Math\Matrix\MatrixOperator;
 use Rindow\Math\Matrix\Range;
 use RuntimeException;
 use Serializable;
@@ -390,6 +388,16 @@ public static function fromString(string $string, int $dtype, array $shape): sta
         return new static($buffer, $dtype, $shape, 0);
     }
 
+    public static function random(array $shape, ?int $dtype = null): static
+    {
+        $dtype ??= NDArray::float32;
+        $size = array_product($shape);
+
+        $buffer = Tensor::newBuffer($size, $dtype);
+        $buffer->load(random_bytes($size * TensorBuffer::$valueSize[$dtype]));
+        return new static($buffer, shape: $shape, offset: 0);
+    }
+
     /**
      * Convert the tensor into an array.
      */
@@ -680,6 +688,15 @@ public function multiply(Tensor|float|int $value): self
         return new static($ndArray->buffer(), $ndArray->dtype(), $ndArray->shape(), $ndArray->offset());
     }
 
+    public function matmul(Tensor $other, ?bool $transposeA = null, ?bool $transposeB = null): Tensor
+    {
+        $mo = self::mo();
+
+        $result =  $mo->la()->matmul($this, $other, $transposeA, $transposeB);
+
+        return new static($result->buffer(), $result->dtype(), $result->shape(), $result->offset());
+    }
+
     public function log(): self
     {
         $mo = self::mo();
@@ -942,7 +959,7 @@ public function to(int $dtype): static
     /**
      * Returns the mean value of each row of the tensor in the given axis.
      */
-    public function mean(?int $axis = null, bool $keepShape = false): static|float|int
+    public function mean(?int $axis = null, bool $keepShape = false): static|float|int|Tensor
     {
         $mo = self::mo();
 
@@ -1017,7 +1034,7 @@ public function stdMean(?int $axis = null, int $correction = 1, bool $keepShape
                 $num = floor($num / $size);
             }
 
-            $result->buffer[$resultIndex] += pow($this->buffer[$i] - $mean->buffer()[$resultIndex], 2);
+            $result->buffer[$resultIndex] += pow($this->buffer[$i] - $mean->buffer[$resultIndex], 2);
         }
 
         for ($i = 0; $i < count($result->buffer); ++$i) {
@@ -1226,9 +1243,9 @@ protected function softmax2D(): static
      *
      * @return array The top k values and indices of the tensor.
      */
-    public function topk(int $k = null, bool $sorted = true): array
+    public function topk(int $k = -1, bool $sorted = true): array
     {
-        if ($k === null) {
+        if ($k === -1) {
             $k = $this->shape[0];
         }