Feature/dataset run items

composer.json

@@ -54,7 +54,7 @@
         "test:lint": "@php vendor/bin/pint --config https://raw.githubusercontent.com/DIJ-digital/pint-config/main/pint.json",
         "test:unit": "pest",
         "test:types": "phpstan",
-        "test:refactor": "rector --dry-run",
+        "test:refactor": "rector",
         "test": [
             "@test:lint",
             "@test:type-coverage",

src/DatasetRunItem.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP;
+
+use DIJ\Langfuse\PHP\Contracts\TransporterInterface;
+use DIJ\Langfuse\PHP\Responses\DatasetRunItemListResponse;
+use DIJ\Langfuse\PHP\Responses\DatasetRunItemResponse;
+use JsonException;
+
+class DatasetRunItem
+{
+    public function __construct(private readonly TransporterInterface $transporter) {}
+
+    /**
+     * @param  array<string, mixed>|null  $metadata
+     *
+     * @throws JsonException
+     */
+    public function create(
+        string $runName,
+        string $datasetItemId,
+        ?string $traceId = null,
+        ?string $observationId = null,
+        ?string $runDescription = null,
+        ?array $metadata = null,
+    ): DatasetRunItemResponse {
+        $response = $this->transporter->postJson(
+            '/api/public/dataset-run-items',
+            array_filter([
+                'runName' => $runName,
+                'datasetItemId' => $datasetItemId,
+                'traceId' => $traceId,
+                'observationId' => $observationId,
+                'runDescription' => $runDescription,
+                'metadata' => $metadata,
+            ], fn ($value) => $value !== null)
+        );
+
+        /** @var array{id: string, datasetRunId: string, datasetRunName: string, datasetItemId: string, traceId: string, createdAt: string, updatedAt: string, observationId?: string|null} $data */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return DatasetRunItemResponse::fromArray($data);
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function list(
+        string $datasetId,
+        string $runName,
+        ?int $page = null,
+        ?int $limit = null,
+    ): DatasetRunItemListResponse {
+        $response = $this->transporter->get(
+            '/api/public/dataset-run-items',
+            ['query' => array_filter([
+                'datasetId' => $datasetId,
+                'runName' => $runName,
+                'page' => $page,
+                'limit' => $limit,
+            ], fn ($value) => $value !== null)]
+        );
+
+        /** @var array{data: array<int, array{id: string, datasetRunId: string, datasetRunName: string, datasetItemId: string, traceId: string, createdAt: string, updatedAt: string, observationId?: string|null}>, meta: array{page: int, limit: int, totalPages: int, totalItems: int}} $data */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return DatasetRunItemListResponse::fromArray($data);
+    }
+}

src/Langfuse.php

@@ -12,8 +12,7 @@ public function __construct(
         private readonly TransporterInterface $transporter,
         private readonly string $environment = 'default',
         private readonly string $label = 'latest',
-    ) {
-    }
+    ) {}
 
     public function prompt(): Prompt
     {
@@ -37,4 +36,11 @@ public function score(): Score
             transporter: $this->transporter,
         );
     }
+
+    public function datasetRunItem(): DatasetRunItem
+    {
+        return new DatasetRunItem(
+            transporter: $this->transporter,
+        );
+    }
 }

src/Responses/DatasetRunItemListResponse.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+use DIJ\Langfuse\PHP\ValueObjects\MetaData;
+
+readonly class DatasetRunItemListResponse
+{
+    /**
+     * @param  array<int, DatasetRunItemResponse>  $data
+     */
+    public function __construct(
+        public array $data,
+        public MetaData $meta,
+    ) {}
+
+    /**
+     * @param array{
+     *     data: array<int, array{id: string, datasetRunId: string, datasetRunName: string, datasetItemId: string, traceId: string, createdAt: string, updatedAt: string, observationId?: string|null}>,
+     *     meta: array{page: int, limit: int, totalPages: int, totalItems: int}
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            data: array_map(
+                fn (array $item): DatasetRunItemResponse => DatasetRunItemResponse::fromArray($item),
+                $data['data']
+            ),
+            meta: MetaData::fromArray($data['meta']),
+        );
+    }
+}

src/Responses/DatasetRunItemResponse.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+readonly class DatasetRunItemResponse
+{
+    public function __construct(
+        public string $id,
+        public string $datasetRunId,
+        public string $datasetRunName,
+        public string $datasetItemId,
+        public string $traceId,
+        public string $createdAt,
+        public string $updatedAt,
+        public ?string $observationId = null,
+    ) {}
+
+    /**
+     * @param array{
+     *     id: string,
+     *     datasetRunId: string,
+     *     datasetRunName: string,
+     *     datasetItemId: string,
+     *     traceId: string,
+     *     createdAt: string,
+     *     updatedAt: string,
+     *     observationId?: string|null
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            datasetRunId: $data['datasetRunId'],
+            datasetRunName: $data['datasetRunName'],
+            datasetItemId: $data['datasetItemId'],
+            traceId: $data['traceId'],
+            createdAt: $data['createdAt'],
+            updatedAt: $data['updatedAt'],
+            observationId: $data['observationId'] ?? null,
+        );
+    }
+}

src/Testing/Responses/GetDatasetRunItemListResponse.php

@@ -0,0 +1,57 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class GetDatasetRunItemListResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     * @param  array<string, mixed>  $data
+     */
+    public function __construct(int $status = 200, array $headers = [], string $version = '1.1', ?string $reason = null, array $data = [])
+    {
+        parent::__construct($status, $headers, (string) json_encode($this->payload($data)), $version, $reason);
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
+    public function payload(array $data = []): array
+    {
+        return array_merge([
+            'data' => [
+                [
+                    'id' => 'run-item-123',
+                    'datasetRunId' => 'run-456',
+                    'datasetRunName' => 'test-run',
+                    'datasetItemId' => 'item-789',
+                    'traceId' => 'trace-abc',
+                    'createdAt' => '2025-01-15T10:00:00.000Z',
+                    'updatedAt' => '2025-01-15T10:00:00.000Z',
+                    'observationId' => null,
+                ],
+                [
+                    'id' => 'run-item-456',
+                    'datasetRunId' => 'run-456',
+                    'datasetRunName' => 'test-run',
+                    'datasetItemId' => 'item-012',
+                    'traceId' => 'trace-def',
+                    'createdAt' => '2025-01-16T10:00:00.000Z',
+                    'updatedAt' => '2025-01-16T10:00:00.000Z',
+                    'observationId' => 'obs-xyz',
+                ],
+            ],
+            'meta' => [
+                'page' => 1,
+                'limit' => 50,
+                'totalPages' => 1,
+                'totalItems' => 2,
+            ],
+        ], $data);
+    }
+}

src/Testing/Responses/GetDatasetRunItemResponse.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Testing\Responses;
+
+use GuzzleHttp\Psr7\Response;
+
+class GetDatasetRunItemResponse extends Response
+{
+    /**
+     * @param  array<array<string>|string>  $headers
+     * @param  array<string, mixed>  $data
+     */
+    public function __construct(int $status = 200, array $headers = [], string $version = '1.1', ?string $reason = null, array $data = [])
+    {
+        parent::__construct($status, $headers, (string) json_encode($this->payload($data)), $version, $reason);
+    }
+
+    /**
+     * @param  array<string, mixed>  $data
+     * @return array<string, mixed>
+     */
+    public function payload(array $data = []): array
+    {
+        return array_merge([
+            'id' => 'run-item-123',
+            'datasetRunId' => 'run-456',
+            'datasetRunName' => 'test-run',
+            'datasetItemId' => 'item-789',
+            'traceId' => 'trace-abc',
+            'createdAt' => '2025-01-15T10:00:00.000Z',
+            'updatedAt' => '2025-01-15T10:00:00.000Z',
+            'observationId' => null,
+        ], $data);
+    }
+}