Feature/observations

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/Contracts/TransporterInterface.php

@@ -9,34 +9,34 @@
 interface TransporterInterface
 {
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function request(string $method, string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function get(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function post(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      */
     public function postJson(string $uri, array $data = [], array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $options
      */
     public function delete(string $uri, array $options = []): ResponseInterface;
 
     /**
-     * @param array<string, mixed> $data
-     * @param array<string, mixed> $options
+     * @param  array<string, mixed>  $data
+     * @param  array<string, mixed>  $options
      */
     public function patchJson(string $uri, array $data = [], array $options = []): ResponseInterface;
 }

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 observation(): Observation
+    {
+        return new Observation(
+            transporter: $this->transporter,
+        );
+    }
 }

src/Observation.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP;
+
+use DIJ\Langfuse\PHP\Contracts\TransporterInterface;
+use DIJ\Langfuse\PHP\Responses\ObservationListResponse;
+use DIJ\Langfuse\PHP\Responses\ObservationResponse;
+use JsonException;
+
+class Observation
+{
+    public function __construct(private readonly TransporterInterface $transporter) {}
+
+    /**
+     * @throws JsonException
+     */
+    public function get(string $observationId): ObservationResponse
+    {
+        $response = $this->transporter->get(
+            uri: sprintf('/api/public/observations/%s', urlencode($observationId)),
+        );
+
+        /** @var array{
+         *     id: string,
+         *     traceId: string|null,
+         *     type: string,
+         *     name: string|null,
+         *     startTime: string,
+         *     endTime: string|null,
+         *     completionStartTime: string|null,
+         *     model: string|null,
+         *     modelParameters: array<string, mixed>|null,
+         *     input: mixed,
+         *     output: mixed,
+         *     metadata: mixed,
+         *     version: string|null,
+         *     parentObservationId: string|null,
+         *     level: string|null,
+         *     statusMessage: string|null,
+         *     promptId: string|null,
+         *     promptName: string|null,
+         *     promptVersion: int|null,
+         *     usage: array{input: int|null, output: int|null, total: int|null, unit: string|null, inputCost: float|null, outputCost: float|null, totalCost: float|null}|null,
+         *     calculatedInputCost: float|null,
+         *     calculatedOutputCost: float|null,
+         *     calculatedTotalCost: float|null,
+         *     latency: float|null,
+         *     timeToFirstToken: float|null,
+         *     projectId: string,
+         *     createdAt: string,
+         *     updatedAt: string,
+         *     environment: string|null
+         * } $data
+         */
+        $data = json_decode($response->getBody()->getContents(), true, flags: JSON_THROW_ON_ERROR);
+
+        return ObservationResponse::fromArray($data);
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function list(
+        ?int $page = null,
+        ?int $limit = null,
+        ?string $name = null,
+        ?string $userId = null,
+        ?string $type = null,
+        ?string $traceId = null,
+        ?string $level = null,
+        ?string $parentObservationId = null,
+        ?array $environment = null,
+        ?string $fromStartTime = null,
+        ?string $toStartTime = null,
+        ?string $version = null,
+        ?string $filter = null,
+    ): ObservationListResponse {
+        $response = $this->transporter->get(
+            uri: '/api/public/observations',
+            options: ['query' => array_filter([
+                'page' => $page,
+                'limit' => $limit,
+                'name' => $name,
+                'userId' => $userId,
+                'type' => $type,
+                'traceId' => $traceId,
+                'level' => $level,
+                'parentObservationId' => $parentObservationId,
+                'environment' => $environment,
+                'fromStartTime' => $fromStartTime,
+                'toStartTime' => $toStartTime,
+                'version' => $version,
+                'filter' => $filter,
+            ])]
+        );
+
+        /** @var array{
+         *     data: array<int, array{
+         *         id: string,
+         *         traceId: string|null,
+         *         type: string,
+         *         name: string|null,
+         *         startTime: string,
+         *         endTime: string|null,
+         *         completionStartTime: string|null,
+         *         model: string|null,
+         *         modelParameters: array<string, mixed>|null,
+         *         input: mixed,
+         *         output: mixed,
+         *         metadata: mixed,
+         *         version: string|null,
+         *         parentObservationId: string|null,
+         *         level: string|null,
+         *         statusMessage: string|null,
+         *         promptId: string|null,
+         *         promptName: string|null,
+         *         promptVersion: int|null,
+         *         usage: array{input: int|null, output: int|null, total: int|null, unit: string|null, inputCost: float|null, outputCost: float|null, totalCost: float|null}|null,
+         *         calculatedInputCost: float|null,
+         *         calculatedOutputCost: float|null,
+         *         calculatedTotalCost: float|null,
+         *         latency: float|null,
+         *         timeToFirstToken: float|null,
+         *         projectId: string,
+         *         createdAt: string,
+         *         updatedAt: string,
+         *         environment: 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 ObservationListResponse::fromArray($data);
+    }
+}

src/Responses/ObservationListResponse.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+use DIJ\Langfuse\PHP\ValueObjects\MetaData;
+
+readonly class ObservationListResponse
+{
+    /**
+     * @param  array<int, ObservationResponse>  $data
+     */
+    public function __construct(
+        public array $data,
+        public MetaData $meta,
+    ) {}
+
+    /**
+     * @param array{
+     *     data: array<int, array{
+     *         id: string,
+     *         traceId: string|null,
+     *         type: string,
+     *         name: string|null,
+     *         startTime: string,
+     *         endTime: string|null,
+     *         completionStartTime: string|null,
+     *         model: string|null,
+     *         modelParameters: array<string, mixed>|null,
+     *         input: mixed,
+     *         output: mixed,
+     *         metadata: mixed,
+     *         version: string|null,
+     *         parentObservationId: string|null,
+     *         level: string|null,
+     *         statusMessage: string|null,
+     *         promptId: string|null,
+     *         promptName: string|null,
+     *         promptVersion: int|null,
+     *         usage?: array{input: int|null, output: int|null, total: int|null, unit: string|null, inputCost: float|null, outputCost: float|null, totalCost: float|null}|null,
+     *         calculatedInputCost?: float|null,
+     *         calculatedOutputCost?: float|null,
+     *         calculatedTotalCost?: float|null,
+     *         latency?: float|null,
+     *         timeToFirstToken?: float|null,
+     *         projectId: string,
+     *         createdAt: string,
+     *         updatedAt: string,
+     *         environment?: 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): ObservationResponse => ObservationResponse::fromArray($item), $data['data']),
+            meta: MetaData::fromArray($data['meta']),
+        );
+    }
+}

src/Responses/ObservationResponse.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DIJ\Langfuse\PHP\Responses;
+
+readonly class ObservationResponse
+{
+    /**
+     * @param  array<string, mixed>|null  $modelParameters
+     * @param  array{input: int|null, output: int|null, total: int|null, unit: string|null, inputCost: float|null, outputCost: float|null, totalCost: float|null}|null  $usage
+     */
+    public function __construct(
+        public string $id,
+        public ?string $traceId,
+        public string $type,
+        public ?string $name,
+        public string $startTime,
+        public ?string $endTime,
+        public ?string $completionStartTime,
+        public ?string $model,
+        public ?array $modelParameters,
+        public mixed $input,
+        public mixed $output,
+        public mixed $metadata,
+        public ?string $version,
+        public ?string $parentObservationId,
+        public ?string $level,
+        public ?string $statusMessage,
+        public ?string $promptId,
+        public ?string $promptName,
+        public ?int $promptVersion,
+        public ?array $usage,
+        public ?float $calculatedInputCost,
+        public ?float $calculatedOutputCost,
+        public ?float $calculatedTotalCost,
+        public ?float $latency,
+        public ?float $timeToFirstToken,
+        public string $projectId,
+        public string $createdAt,
+        public string $updatedAt,
+        public ?string $environment = null,
+    ) {}
+
+    /**
+     * @param array{
+     *     id: string,
+     *     traceId: string|null,
+     *     type: string,
+     *     name: string|null,
+     *     startTime: string,
+     *     endTime: string|null,
+     *     completionStartTime: string|null,
+     *     model: string|null,
+     *     modelParameters: array<string, mixed>|null,
+     *     input: mixed,
+     *     output: mixed,
+     *     metadata: mixed,
+     *     version: string|null,
+     *     parentObservationId: string|null,
+     *     level: string|null,
+     *     statusMessage: string|null,
+     *     promptId: string|null,
+     *     promptName: string|null,
+     *     promptVersion: int|null,
+     *     usage?: array{input: int|null, output: int|null, total: int|null, unit: string|null, inputCost: float|null, outputCost: float|null, totalCost: float|null}|null,
+     *     calculatedInputCost?: float|null,
+     *     calculatedOutputCost?: float|null,
+     *     calculatedTotalCost?: float|null,
+     *     latency?: float|null,
+     *     timeToFirstToken?: float|null,
+     *     projectId: string,
+     *     createdAt: string,
+     *     updatedAt: string,
+     *     environment?: string|null
+     * } $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            traceId: $data['traceId'],
+            type: $data['type'],
+            name: $data['name'],
+            startTime: $data['startTime'],
+            endTime: $data['endTime'],
+            completionStartTime: $data['completionStartTime'],
+            model: $data['model'],
+            modelParameters: $data['modelParameters'],
+            input: $data['input'],
+            output: $data['output'],
+            metadata: $data['metadata'],
+            version: $data['version'],
+            parentObservationId: $data['parentObservationId'],
+            level: $data['level'],
+            statusMessage: $data['statusMessage'],
+            promptId: $data['promptId'],
+            promptName: $data['promptName'],
+            promptVersion: $data['promptVersion'],
+            usage: $data['usage'] ?? null,
+            calculatedInputCost: $data['calculatedInputCost'] ?? null,
+            calculatedOutputCost: $data['calculatedOutputCost'] ?? null,
+            calculatedTotalCost: $data['calculatedTotalCost'] ?? null,
+            latency: $data['latency'] ?? null,
+            timeToFirstToken: $data['timeToFirstToken'] ?? null,
+            projectId: $data['projectId'],
+            createdAt: $data['createdAt'],
+            updatedAt: $data['updatedAt'],
+            environment: $data['environment'] ?? null,
+        );
+    }
+}