Structured extraction support (#14)

* Structured extraction support

* Fix styling

---------

Co-authored-by: avvertix <5672748+avvertix@users.noreply.github.com>

Author: avvertix

src/Connectors/LibrarianConnector.php

@@ -7,6 +7,7 @@
 use OneOffTech\LibrarianClient\Resources\LibraryResource;
 use OneOffTech\LibrarianClient\Resources\PromptResource;
 use OneOffTech\LibrarianClient\Resources\QuestionResource;
+use OneOffTech\LibrarianClient\Resources\StructuredExtractionResource;
 use OneOffTech\LibrarianClient\Resources\SummaryResource;
 use OneOffTech\LibrarianClient\Responses\LibrarianResponse;
 use Saloon\Http\Auth\TokenAuthenticator;
@@ -114,4 +115,9 @@ public function classifiers(string $library_id): ClassifierResource
     {
         return new ClassifierResource($library_id, $this);
     }
+
+    public function extractions(string $library_id): StructuredExtractionResource
+    {
+        return new StructuredExtractionResource($library_id, $this);
+    }
 }

src/Dto/Extraction.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace OneOffTech\LibrarianClient\Dto;
+
+use Saloon\Contracts\DataObjects\WithResponse;
+use Saloon\Traits\Responses\HasResponse;
+
+class Extraction implements WithResponse
+{
+    use HasResponse;
+
+    public function __construct(
+        public readonly array $content,
+    ) {}
+}

src/Dto/ResponseSchema.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace OneOffTech\LibrarianClient\Dto;
+
+class ResponseSchema
+{
+    public function __construct(
+        public readonly array $schema,
+    ) {}
+
+    public static function fromString(string $schema): static
+    {
+        return new static(json_decode($schema, associative: true));
+    }
+
+    public static function fromArray(array $schema): static
+    {
+        return new static($schema);
+    }
+}

src/Requests/StructuredExtraction/ExtractRequest.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace OneOffTech\LibrarianClient\Requests\StructuredExtraction;
+
+use OneOffTech\LibrarianClient\Dto\Document;
+use OneOffTech\LibrarianClient\Dto\Extraction;
+use OneOffTech\LibrarianClient\Dto\ResponseSchema;
+use Saloon\Contracts\Body\HasBody;
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+use Saloon\Http\Response;
+use Saloon\Traits\Body\HasJsonBody;
+
+class ExtractRequest extends Request implements HasBody
+{
+    use HasJsonBody;
+
+    protected Method $method = Method::POST;
+
+    public function __construct(
+        protected readonly string $library_id,
+        protected readonly Document $document,
+        protected readonly ResponseSchema $responseSchema,
+        protected readonly ?array $sections = null,
+        protected readonly ?string $instructions = null,
+    ) {
+        //
+    }
+
+    public function resolveEndpoint(): string
+    {
+        return "/library/{$this->library_id}/structured_extract";
+    }
+
+    protected function defaultBody(): array
+    {
+        return [
+            'doc' => $this->document->data,
+            'response_model' => $this->responseSchema->schema,
+            'instructions' => $this->instructions ?? '',
+            'sections' => $this->sections,
+        ];
+    }
+
+    public function createDtoFromResponse(Response $response): Extraction
+    {
+        $data = $response->json();
+
+        return (new Extraction(
+            content: $data,
+        ))->setResponse($response);
+    }
+}

src/Resources/StructuredExtractionResource.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace OneOffTech\LibrarianClient\Resources;
+
+use OneOffTech\LibrarianClient\Dto\Document;
+use OneOffTech\LibrarianClient\Dto\Extraction;
+use OneOffTech\LibrarianClient\Dto\ResponseSchema;
+use OneOffTech\LibrarianClient\Requests\StructuredExtraction\ExtractRequest;
+use Saloon\Http\BaseResource;
+use Saloon\Http\Connector;
+
+class StructuredExtractionResource extends BaseResource
+{
+    /**
+     * Constructor
+     */
+    public function __construct(
+        readonly protected string $library_id,
+        Connector $connector
+    ) {
+        parent::__construct($connector);
+    }
+
+    public function extract(string $structuredResponseModel, Document $from, ?array $sections = null, ?string $instructions = null): Extraction
+    {
+        return $this->connector->send(new ExtractRequest(
+            library_id: $this->library_id,
+            document: $from,
+            responseSchema: ResponseSchema::fromString($structuredResponseModel),
+            sections: $sections,
+            instructions: $instructions,
+        ))
+            ->dto();
+    }
+}

tests/Fixtures/Saloon/structured-extract-instructions.json

@@ -0,0 +1,8 @@
+{
+    "statusCode": 200,
+    "headers": {
+        "content-length": "235",
+        "content-type": "application\/json"
+    },
+    "data": "{\"dates\":[{\"date\":\"2025-03-22\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"},{\"date\":\"2025-04-15\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"}]}"
+}

tests/Fixtures/Saloon/structured-extract-missing-section-attribute.json

@@ -0,0 +1,8 @@
+{
+    "statusCode": 200,
+    "headers": {
+        "content-length": "235",
+        "content-type": "application\/json"
+    },
+    "data": "{\"dates\":[{\"date\":\"2025-03-22\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"},{\"date\":\"2025-04-15\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"}]}"
+}

tests/Fixtures/Saloon/structured-extract-specific-section.json

@@ -0,0 +1,8 @@
+{
+    "statusCode": 200,
+    "headers": {
+        "content-length": "235",
+        "content-type": "application\/json"
+    },
+    "data": "{\"dates\":[{\"date\":\"2025-03-22\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"},{\"date\":\"2025-04-15\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"}]}"
+}

tests/Fixtures/Saloon/structured-extract-whole-document.json

@@ -0,0 +1,8 @@
+{
+    "statusCode": 200,
+    "headers": {
+        "content-length": "235",
+        "content-type": "application\/json"
+    },
+    "data": "{\"dates\":[{\"date\":\"2025-03-22\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"},{\"date\":\"2025-04-15\",\"context\":\"We have some dates 22 march 2025, 15\/04\/2025 of relevance for the extraction.\"}]}"
+}