feat(structured-output): add schema-driven response formatting

- Implement StructuredOutput helper class for JSON schema definitions
- Add generateStructured() method to Chat endpoint
- Support both array and class-based schema definitions
- Enable automatic response validation and hydration
- Include PHP attribute system for IDE-friendly schema creation
- Added a new test suite

Author: AlvinCoded

.github/workflows/test.yml

@@ -0,0 +1,53 @@
+name: Run Tests
+
+on:
+  push:
+    branches:
+      - main
+      - 'release/*'
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        php-version: ['8.1', '8.2']
+        dependency-version: ['latest', 'lowest']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          tools: composer
+
+      - name: Get Composer Cache Directory
+        id: composer-cache
+        run: |
+          echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache Composer dependencies
+        uses: actions/cache@v3
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ matrix.php-version }}-${{ matrix.dependency-version }}
+          restore-keys: ${{ runner.os }}-composer-${{ matrix.php-version }}-
+
+      - name: Install dependencies
+        run: |
+          if [ "${{ matrix.dependency-version }}" == "lowest" ]; then
+            composer update --prefer-lowest --prefer-stable --no-progress --no-suggest
+          else
+            composer install --no-progress --no-suggest
+          fi
+
+      - name: Run tests
+        run: composer test

README.md

@@ -180,10 +180,78 @@ echo $config->modelSupportsStreaming($model) // true
 echo $config->modelSupportsFunctions($model) // false
 ```
 
+#### _Structured Output_
+
+```php
+<?php
+
+use GrokPHP\Client\GrokClient;
+use GrokPHP\Enums\Model;
+
+// 1. Define schema once
+$jsonSchema = [
+    "type" => "object",
+    "properties" => [
+        "title" => ["type" => "string"],
+        "authors" => ["type" => "array", "items" => ["type" => "string"]],
+        "publication_year" => ["type" => "integer"],
+        "doi" => ["type" => "string"],
+        "keywords" => ["type" => "array", "items" => ["type" => "string"]],
+        "citation_count" => ["type" => "integer"]
+    ],
+    "required" => ["title", "authors"]
+];
+
+
+// 2. Process documents
+$client = new GrokClient();
+
+foreach ($researchPapers as $paperText) {
+    $metadata = $client->chat()->generateStructured($paperText, $jsonSchema);
+    
+    // 3. Directly store structured data
+    $this->database->insertPaper(
+        title: $metadata['title'],
+        authors: $metadata['authors'],
+        year: $metadata['publication_year'] ?? null,
+        doi: $metadata['doi'] ?? '',
+        keywords: $metadata['keywords'] ?? []
+    );
+}
+```
+
+#### _Structured Output (alt. option with PHP class)_
+
+```php
+// Define your schema as a PHP class
+class ResearchPaper extends \GrokPHP\Utils\DataModel 
+{
+    #[SchemaProperty(type: 'string', description: 'Paper title')]
+    public string $title;
+    
+    #[SchemaProperty(type: 'array', description: 'List of authors')]
+    public array $authors;
+    
+    #[SchemaProperty(type: 'string', description: 'Abstract text')]
+    public string $abstract;
+}
+
+// ...then, in your application code
+$result = $client->chat()->generateStructured(
+            "Extract research paper details", 
+             ResearchPaper::class
+          );
+
+// ...and finally, get typed properties
+echo $result->title;
+echo $result->authors[0];
+
+```
+
 
 ## Response Handling
 
-### Chat/Completion Response Methods
+#### _Chat/Completion Response Methods_
 
 ```php
 $response->getContent();       // Get response content
@@ -194,7 +262,7 @@ $response->getModel();         // Get model used
 $response->getUsage();         // Get token usage statistics
 ```
 
-### Image Analysis Response Methods
+#### _Image Analysis Response Methods_
 
 ```php
 $response->getAnalysis();      // Get analysis text
@@ -203,6 +271,12 @@ $response->getMetadata();      // Get image metadata
 $response->getUsage();         // Get token usage
 ```
 
+#### _Embedding Response Methods_
+```php
+$response->getEmbeddings();    // Get embeddings
+$response->getUsage();         // Get token usage
+```
+
 ## Error Handling
 
 ```php

src/Client/GrokClient.php

@@ -63,12 +63,24 @@ public function __construct(array $options = [])
         $this->config = new Config(array_merge($options, ['api_key' => $apiKey]));
     }
 
+    /**
+     * Sets the current model to be used by the client.
+     *
+     * @param Model $model
+     * @return self
+     */
     public function model(Model $model): self
     {
         $this->currentModel = $model;
         return $this;
     }
 
+    /**
+     * Begin a conversation with Grok AI, optionally with a pre-existing chat history.
+     * 
+     * @param array $history
+     * @return Chat
+     */
     public function beginConvo(array $history = []): Chat
     {
         return $this->chat()->withHistory($history);

src/Endpoints/Chat.php

@@ -11,8 +11,10 @@
 use GrokPHP\Enums\Model;
 use GrokPHP\Traits\HasApiOperations;
 use GrokPHP\Traits\ValidatesInput;
+use GrokPHP\Utils\DataModel;
 use GrokPHP\Utils\RequestBuilder;
 use GrokPHP\Utils\ResponseParser;
+use GrokPHP\Utils\StructuredOutput;
 use GuzzleHttp\Client;
 
 /**
@@ -113,7 +115,7 @@ public function send(string $message, ?Params $params = null): ChatMessage
      */
     public function generate(string|array $prompt, ?Params $params = null): ChatMessage
     {
-        $messages = $this->formatPrompt($prompt);
+        $messages = $this->formatPrompt(prompt: $prompt);
         $payload = $this->requestBuilder->buildChatRequest(
             $messages,
             $params?->toArray() ?? [],
@@ -128,6 +130,52 @@ public function generate(string|array $prompt, ?Params $params = null): ChatMess
         return $this->responseParser->parse($response, 'chat');
     }
 
+    /**
+     * Generates a structured response using the specified JSON Schema.
+     * The API response is automatically parsed into an associative array.
+     *
+     * @param string|array $prompt
+     * @param array|string $jsonSchema The JSON Schema that constrains the output.
+     * @param Params|null $params Additional parameters.
+     * @return array|string Parsed JSON structure or raw text if parsing fails.
+     * @throws GrokException
+     */
+    public function generateStructured(string|array $prompt, array|string $jsonSchema, ?Params $params = null): array|string
+    {
+        if (is_string($jsonSchema) && class_exists($jsonSchema)) {
+            if (!is_subclass_of($jsonSchema, DataModel::class)) {
+                throw new GrokException('Invalid schema class');
+            }
+            $schema = $jsonSchema::schema();
+        } else {
+            $schema = $jsonSchema;
+        }
+
+        $structuredOutput = new StructuredOutput($schema);
+        $messages = $this->formatPrompt($prompt);
+        $payload = $this->requestBuilder->buildChatRequest(
+            $messages,
+            $params?->toArray() ?? [],
+            $this->model->value
+        );
+
+        $payload['response_format'] = $structuredOutput->toArray();
+
+        $response = $this->client->post(self::CHAT_ENDPOINT, [
+            'json' => $payload,
+            'headers' => $this->requestBuilder->buildHeaders($this->config->getApiKey()),
+        ]);
+
+        $chatMessage = $this->responseParser->parse($response, 'chat');
+        $decoded = json_decode($chatMessage->getContent(), true);
+
+        if (is_string($schema) && class_exists($schema)) {
+            return (new $schema())->fromArray($decoded);
+        }
+        
+        return $decoded;
+    }
+
     /**
      * Sets the chat history.
      *

src/Utils/DataModel.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GrokPHP\Utils;
+
+use ReflectionClass;
+
+/**
+ * Abstract base class for data models
+ * 
+ * This class serves as a foundation for creating data models in the application.
+ * It provides common structure and functionality that all data models should inherit.
+ *
+ * @abstract DataModel
+ * @package GrokPHP\Utils
+ * @author Alvin Panford <[email protected]>
+ */
+abstract class DataModel
+{
+    /**
+     * Returns the schema definition for the data model.
+     * 
+     * The schema defines the structure and validation rules for the model's data fields.
+     * 
+     * @return array
+     */
+    public static function schema(): array
+    {
+        $schema = [
+            'type' => 'object',
+            'properties' => [],
+            'required' => []
+        ];
+
+        $reflection = new ReflectionClass(static::class);
+        
+        foreach ($reflection->getProperties() as $property) {
+            $attributes = $property->getAttributes(SchemaProperty::class);
+            
+            if (!empty($attributes)) {
+                $attr = $attributes[0]->newInstance();
+                $schema['properties'][$property->name] = $attr->toArray();
+                
+                if ($attr->required) {
+                    $schema['required'][] = $property->name;
+                }
+            }
+        }
+
+        return $schema;
+    }
+
+    /**
+     * Creates a new instance of the model from an array of data.
+     * 
+     * @param array $data
+     * @return static
+     */
+    public function fromArray(array $data): static
+    {
+        foreach ($data as $key => $value) {
+            if (property_exists($this, $key)) {
+                $this->{$key} = $value;
+            }
+        }
+        return $this;
+    }
+}

src/Utils/SchemaProperty.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GrokPHP\Utils;
+
+use Attribute;
+
+/**
+ * Attribute class for marking class properties as schema properties.
+ * This attribute can only be applied to properties.
+ * 
+ * @see \Attribute
+ * @package GrokPHP\Utils
+ * @author Alvin Panford <[email protected]>
+ */
+#[Attribute(Attribute::TARGET_PROPERTY)]
+
+class SchemaProperty
+{
+    /**
+     * Constructs a new instance of the SchemaProperty class.
+     * 
+     * @param mixed ...$params 
+     * @return void
+     */
+    public function __construct(
+        public string $type = 'string',
+        public bool $required = true,
+        public ?string $description = null
+    ) {}
+
+    /**
+     * Converts the SchemaProperty object to an associative array.
+     *
+     * @return array
+     */
+    public function toArray(): array
+    {
+        return array_filter([
+            'type' => $this->type,
+            'description' => $this->description
+        ]);
+    }
+}