Consistent structured output, inference, embeddings, http client facades/builders

Author: ddebowczyk

bin/clean-composer.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e  # stops script on first error
+
+for dir in packages/*; do
+  if [ -f "$dir/composer.json" ]; then
+    echo "🔍 Removing composer caches and ./vendor/* in $dir"
+    composer --working-dir="$dir" clear-cache
+    composer --working-dir="$dir" dump-autoload
+    rm -rf "$dir/vendor/"*
+  fi
+done

config/llm.php

@@ -147,6 +147,20 @@
             'contextLength' => 128_000,
             'maxOutputLength' => 2048,
         ],
+        'huggingface' => [
+            'providerType' => 'huggingface',
+            'apiUrl' => 'https://router.huggingface.co/{providerId}/v1',
+            'apiKey' => Env::get('HUGGINGFACE_API_KEY', ''),
+            'endpoint' => '/chat/completions',
+            'metadata' => [
+                'providerId' => 'hf-inference/models/microsoft/phi-4',
+            ],
+            'defaultModel' => 'microsoft/phi-4',
+            'defaultOutputMode' => 'text',
+            'defaultMaxTokens' => 1024,
+            'contextLength' => 32_000,
+            'maxOutputLength' => 4096,
+        ],
         'meta' => [
             'providerType' => 'meta',
             'apiUrl' => 'https://openrouter.ai/api/v1',

docs/release-notes/v1.0.0.mdx

@@ -1,6 +1,6 @@
  - (all) Multiple breaking changes - proceed with caution
- - (all) Common conventions for working with StructuredOutput, Inference, and Embeddings classes
  - (instructor) the `Instructor` class is being replaced with `StructuredOutput` class; the old class will be kept for some time to allow for a smooth transition.
+ - (all) Common conventions for working with StructuredOutput, Inference, and Embeddings classes
  - (examples) All examples have been updated to use the new `StructuredOutput` class and recommended create(), generate() methods
  - (docs) Updated documentation to reflect the new `StructuredOutput` class and its usage
  - (instructor) Extracted structured output config into a separate file config/structured.php (and removed from config/llm.php)
@@ -15,5 +15,6 @@
  - (polyglot) Corrections in inference drivers, fixed defects in JSON/JSON Schema modes
  - (polyglot) Fixed error in selection of embeddings driver
  - (polyglot) Added `withDebug()` support to Embeddings class
+ - (polyglot) Added experimental support for HuggingFace inference API
  - (all) Multiple changes, improvements and refactorings in the codebase
  - (all) Updated docs and examples to reflect the latest changes

examples/A02_Advanced/CustomClientParameters/run.php

@@ -17,7 +17,7 @@
 
 use Cognesy\Http\Data\HttpClientConfig;
 use Cognesy\Http\Drivers\SymfonyDriver;
-use Cognesy\Http\HttpClientFactory;
+use Cognesy\Http\HttpClient;
 use Cognesy\Instructor\StructuredOutput;
 use Cognesy\Polyglot\LLM\Data\LLMConfig;
 use Cognesy\Polyglot\LLM\Enums\OutputMode;
@@ -30,19 +30,9 @@ class User {
     public string $name;
 }
 
-// Create instance of LLM connection preset initialized with custom parameters
-$llmConfig = new LLMConfig(
-    apiUrl: 'https://api.deepseek.com',
-    apiKey: Env::get('DEEPSEEK_API_KEY'),
-    endpoint: '/chat/completions',
-    model: 'deepseek-chat',
-    maxTokens: 128,
-    httpClient: 'symfony',
-    providerType: 'openai-compatible',
-);
-
 // Build fully customized HTTP client
 $events = new EventDispatcher();
+
 $httpConfig = new HttpClientConfig(
     httpClientType: 'symfony',
     connectTimeout: 5,
@@ -52,15 +42,31 @@ class User {
     poolTimeout: 60,
     failOnError: true,
 );
-$driver = new SymfonyDriver(
-    config: $httpConfig,
-    clientInstance: SymfonyHttpClient::create(['http_version' => '2.0']),
-    events: $events,
+
+$customClient = (new HttpClient)
+    ->withEventDispatcher($events)
+    ->withEventListener($events)
+    ->withDriver(new SymfonyDriver(
+        config: $httpConfig,
+        clientInstance: SymfonyHttpClient::create(['http_version' => '2.0']),
+        events: $events,
+    ));
+
+// Create instance of LLM connection preset initialized with custom parameters
+$llmConfig = new LLMConfig(
+    apiUrl: 'https://api.deepseek.com',
+    apiKey: Env::get('DEEPSEEK_API_KEY'),
+    endpoint: '/chat/completions',
+    model: 'deepseek-chat',
+    maxTokens: 128,
+    httpClient: 'symfony',
+    providerType: 'openai-compatible',
 );
-$customClient = (new HttpClientFactory($events))->fromDriver($driver);
 
 // Get Instructor with the default client component overridden with your own
 $structuredOutput = (new StructuredOutput)
+    ->withEventDispatcher($events)
+    ->withEventListener($events)
     ->withLLMConfig($llmConfig)
     ->withHttpClient($customClient);
 
@@ -74,6 +80,7 @@ class User {
     )
     ->withStreaming()
     ->get();
+
 dump($user);
 
 assert(isset($user->name));

examples/A02_Advanced/ProvidingExamples/run.php

@@ -32,7 +32,7 @@ class User {
 $user = (new StructuredOutput)
     // let's dump the request data to see how examples are used in requests
     ->onEvent(HttpRequestSent::class, fn($event) => dump($event))
-    ->withMessage("Our user Jason is 25 years old.")
+    ->withMessages("Our user Jason is 25 years old.")
     ->withResponseClass(User::class)
     ->withExamples([
         new Example(

examples/A04_APISupport/HuggingFace/run.php

@@ -0,0 +1,74 @@
+---
+title: 'Hugging Face'
+docname: 'huggingface'
+---
+
+## Overview
+
+You can use Instructor to parse structured output from LLMs using Hugging Face API.
+This example demonstrates how to parse user data into a structured model using
+JSON Schema.
+
+## Example
+
+```php
+<?php
+require 'examples/boot.php';
+
+use Cognesy\Instructor\StructuredOutput;
+use Cognesy\Polyglot\LLM\Enums\OutputMode;
+
+enum UserType : string {
+    case Guest = 'guest';
+    case User = 'user';
+    case Admin = 'admin';
+}
+
+class User {
+    public string $firstName;
+    public UserType $role;
+    /** @var string[] */
+    public array $hobbies;
+    public string $username;
+    public ?int $age;
+}
+
+// Get Instructor with specified LLM client connection
+// See: /config/llm.php to check or change LLM client connection configuration details
+$structuredOutput = (new StructuredOutput)->using('huggingface')->withDebug();
+
+$user = $structuredOutput
+    ->with(
+        messages: "Jason (@jxnlco) is 25 years old. He is the admin of this project. He likes playing football and reading books.",
+        responseModel: User::class,
+        prompt: 'Parse the user data to JSON, respond using following JSON Schema: <|json_schema|>',
+        examples: [[
+                      'input' => 'Ive got email Frank - their developer, who\'s 30. He asked to come back to him frank@hk.ch. Btw, he plays on drums!',
+                      'output' => ['firstName' => 'Frank', 'age' => 30, 'username' => 'frank@hk.ch', 'role' => 'user', 'hobbies' => ['playing drums'],],
+                  ],[
+                      'input' => 'We have a meeting with John, our new admin who likes surfing. He is 19 years old - check his profile: @jx90.',
+                      'output' => ['firstName' => 'John', 'role' => 'admin', 'hobbies' => ['surfing'], 'username' => 'jx90', 'age' => 19],
+                  ]],
+        //model: 'deepseek-ai/DeepSeek-R1-0528-Qwen3-8B',
+        maxRetries: 2,
+        options: ['temperature' => 0.5],
+        mode: OutputMode::Json,
+    )->get();
+
+print("Completed response model:\n\n");
+
+dump($user);
+
+assert(isset($user->firstName));
+assert(isset($user->role));
+assert(isset($user->age));
+assert(isset($user->hobbies));
+assert(isset($user->username));
+assert(is_array($user->hobbies));
+assert(count($user->hobbies) > 0);
+assert($user->role === UserType::Admin);
+assert($user->age === 25);
+assert($user->firstName === 'Jason');
+assert(in_array($user->username, ['jxnlco', '@jxnlco']));
+?>
+```

examples/B02_LLMAdvanced/CustomClientParameters/run.php

@@ -16,11 +16,10 @@
 
 use Cognesy\Http\Data\HttpClientConfig;
 use Cognesy\Http\Drivers\SymfonyDriver;
-use Cognesy\Http\HttpClientFactory;
+use Cognesy\Http\HttpClient;
 use Cognesy\Polyglot\LLM\Data\LLMConfig;
 use Cognesy\Polyglot\LLM\Inference;
 use Cognesy\Utils\Env;
-use Cognesy\Utils\Events\EventDispatcher;
 use Cognesy\Utils\Str;
 use Symfony\Component\HttpClient\HttpClient as SymfonyHttpClient;
 
@@ -36,7 +35,6 @@
 );
 
 // Build fully customized HTTP client
-$events = new EventDispatcher();
 $httpConfig = new HttpClientConfig(
     httpClientType: 'symfony',
     connectTimeout: 5,
@@ -49,9 +47,8 @@
 $driver = new SymfonyDriver(
     config: $httpConfig,
     clientInstance: SymfonyHttpClient::create(['http_version' => '2.0']),
-    events: $events,
 );
-$customClient = (new HttpClientFactory($events))->fromDriver($driver);
+$customClient = (new HttpClient)->withDriver($driver);
 
 $answer = (new Inference)
     ->withConfig($config)

examples/B02_LLMAdvanced/CustomLLMDriver/run.php

@@ -18,22 +18,20 @@
 use Cognesy\Polyglot\LLM\Data\LLMConfig;
 use Cognesy\Polyglot\LLM\Drivers\OpenAI\OpenAIDriver;
 use Cognesy\Polyglot\LLM\Inference;
-use Cognesy\Polyglot\LLM\LLM;
 use Cognesy\Polyglot\LLM\InferenceRequest;
 use Cognesy\Utils\Env;
 use Cognesy\Utils\Str;
 
 // we will use existing, bundled driver as an example, but you can provide any class that implements
 // a required interface (CanHandleInference)
 
-LLM::registerDriver('custom-driver', fn($config, $httpClient, $events) => new class($config, $httpClient, $events) extends OpenAIDriver {
+Inference::registerDriver('custom-driver', fn($config, $httpClient, $events) => new class($config, $httpClient, $events) extends OpenAIDriver {
     public function handle(InferenceRequest $request): HttpClientResponse {
         // some extra functionality to demonstrate our driver is being used
         echo ">>> Handling request...\n";
         return parent::handle($request);
     }
-}
-);
+});
 
 // Create instance of LLM client initialized with custom parameters
 $config = new LLMConfig(
@@ -48,7 +46,7 @@ public function handle(InferenceRequest $request): HttpClientResponse {
 
 $answer = (new Inference)
     ->withConfig($config)
-    ->withMessage(['role' => 'user', 'content' => 'What is the capital of France'])
+    ->withMessages([['role' => 'user', 'content' => 'What is the capital of France']])
     ->withOptions(['max_tokens' => 64])
     ->get();
 

examples/B02_LLMAdvanced/DSN/run.php

@@ -18,8 +18,8 @@
 use Cognesy\Polyglot\LLM\Inference;
 use Cognesy\Utils\Str;
 
-$answer = Inference
-    ::fromDSN('preset=xai,model=grok-2')
+$answer = (new Inference)
+    ->withDSN('preset=xai,model=grok-2')
     ->with(
         messages: [['role' => 'user', 'content' => 'What is the capital of France']],
         options: ['max_tokens' => 64]

examples/B02_LLMAdvanced/ReasoningContent/run.php

@@ -25,9 +25,10 @@
     ->using('deepseek-r') // optional, default is set in /config/llm.php
     ->with(
         messages: [['role' => 'user', 'content' => 'What is the capital of France. Answer with just a name.']],
-        options: ['max_tokens' => 64]
+        options: ['max_tokens' => 128]
     )
     ->response();
+dd($response);
 echo "\nCASE #1: Sync response\n";
 echo "USER: What is capital of France\n";
 echo "ASSISTANT: {$response->content()}\n";
@@ -39,11 +40,11 @@
 // EXAMPLE 2: streaming response
 $stream = (new Inference)
     ->using('deepseek-r') // optional, default is set in /config/llm.php
-    ->withStreaming()
     ->with(
         messages: [['role' => 'user', 'content' => 'What is capital of Brasil. Answer with just a name.']],
         options: ['max_tokens' => 128]
     )
+    ->withStreaming()
     ->stream();
 
 echo "\nCASE #2: Streamed response\n";