Skip to content

Commit d0d8b24

Browse files
ddebowczykddebowczyk
committed
Major refactoring - new StructuredOutput class, deprecation of Instructor class and respond() and request() methods
1 parent 112a392 commit d0d8b24

File tree

262 files changed

+1840
-1434
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

262 files changed

+1840
-1434
lines changed

‎README.md‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ This is a simple example demonstrating how Instructor retrieves structured infor
9191
Response model class is a plain PHP class with typehints specifying the types of fields of the object.
9292

9393
```php
94-
use Cognesy\Instructor\Instructor;
94+
use Cognesy\Instructor\StructuredOutput;
9595

9696
// Step 0: Create .env file in your project root:
9797
// OPENAI_API_KEY=your_api_key
@@ -106,10 +106,10 @@ class Person {
106106
$text = "His name is Jason and he is 28 years old.";
107107

108108
// Step 3: Use Instructor to run LLM inference
109-
$person = (new Instructor)->respond(
109+
$person = (new StructuredOutput)->create(
110110
messages: $text,
111111
responseModel: Person::class,
112-
);
112+
)->get();
113113

114114
// Step 4: Work with structured response data
115115
assert($person instanceof Person); // true
@@ -144,10 +144,10 @@ class Person {
144144
}
145145

146146
$text = "His name is Jason, he is -28 years old.";
147-
$person = (new Instructor)->respond(
147+
$person = (new StructuredOutput)->create(
148148
messages: [['role' => 'user', 'content' => $text]],
149149
responseModel: Person::class,
150-
);
150+
)->get();
151151

152152
// if the resulting object does not validate, Instructor throws an exception
153153
```
@@ -170,11 +170,11 @@ class Person {
170170
}
171171

172172
$text = "His name is JX, aka Jason, he is -28 years old.";
173-
$person = (new Instructor)->respond(
173+
$person = (new StructuredOutput)->create(
174174
messages: [['role' => 'user', 'content' => $text]],
175175
responseModel: Person::class,
176176
maxRetries: 3,
177-
);
177+
)->get();
178178

179179
// if all LLM's attempts to self-correct the results fail, Instructor throws an exception
180180
```

‎README.md.bak‎

Lines changed: 51 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ This is a simple example demonstrating how Instructor retrieves structured infor
160160
Response model class is a plain PHP class with typehints specifying the types of fields of the object.
161161

162162
```php
163-
use Cognesy\Instructor\Instructor;
163+
use Cognesy\Instructor\StructuredOutput;
164164

165165
// Step 0: Create .env file in your project root:
166166
// OPENAI_API_KEY=your_api_key
@@ -175,10 +175,10 @@ class Person {
175175
$text = "His name is Jason and he is 28 years old.";
176176

177177
// Step 3: Use Instructor to run LLM inference
178-
$person = (new Instructor)->respond(
178+
$person = (new StructuredOutput)->create(
179179
messages: $text,
180180
responseModel: Person::class,
181-
);
181+
)->get();
182182

183183
// Step 4: Work with structured response data
184184
assert($person instanceof Person); // true
@@ -248,12 +248,12 @@ method with the connection name.
248248
```php
249249
<?php
250250
// ...
251-
$user = (new Instructor)
251+
$user = (new StructuredOutput)
252252
->withConnection('ollama')
253-
->respond(
253+
->create(
254254
messages: "His name is Jason and he is 28 years old.",
255255
responseModel: Person::class,
256-
);
256+
)->get();
257257
// ...
258258
```
259259

@@ -269,12 +269,12 @@ Instructor offers a way to use structured data as an input. This is
269269
useful when you want to use object data as input and get another object
270270
with a result of LLM inference.
271271

272-
The `input` field of Instructor's `respond()` and `request()` methods
272+
The `input` field of Instructor's `create()` and `request()` methods
273273
can be an object, but also an array or just a string.
274274

275275
```php
276276
<?php
277-
use Cognesy\Instructor\Instructor;
277+
use Cognesy\Instructor\StructuredOutput;
278278

279279
class Email {
280280
public function __construct(
@@ -290,11 +290,11 @@ $email = new Email(
290290
body: 'Your account has been updated.'
291291
);
292292

293-
$translation = (new Instructor)->respond(
293+
$translation = (new StructuredOutput)->create(
294294
input: $email,
295295
responseModel: Email::class,
296296
prompt: 'Translate the text fields of email to Spanish. Keep other fields unchanged.',
297-
);
297+
)->get();
298298

299299
assert($translation instanceof Email); // true
300300
dump($translation);
@@ -323,10 +323,10 @@ class Person {
323323
}
324324

325325
$text = "His name is Jason, he is -28 years old.";
326-
$person = (new Instructor)->respond(
326+
$person = (new StructuredOutput)->create(
327327
messages: [['role' => 'user', 'content' => $text]],
328328
responseModel: Person::class,
329-
);
329+
)->get();
330330

331331
// if the resulting object does not validate, Instructor throws an exception
332332
```
@@ -349,11 +349,11 @@ class Person {
349349
}
350350

351351
$text = "His name is JX, aka Jason, he is -28 years old.";
352-
$person = (new Instructor)->respond(
352+
$person = (new StructuredOutput)->create(
353353
messages: [['role' => 'user', 'content' => $text]],
354354
responseModel: Person::class,
355355
maxRetries: 3,
356-
);
356+
)->get();
357357

358358
// if all LLM's attempts to self-correct the results fail, Instructor throws an exception
359359
```
@@ -364,13 +364,13 @@ $person = (new Instructor)->respond(
364364
You can call `request()` method to set the parameters of the request and then call `get()` to get the response.
365365

366366
```php
367-
use Cognesy\Instructor\Instructor;
367+
use Cognesy\Instructor\StructuredOutput;
368368

369-
$instructor = (new Instructor)->request(
369+
$structuredOutput = (new StructuredOutput)->request(
370370
messages: "His name is Jason, he is 28 years old.",
371371
responseModel: Person::class,
372372
);
373-
$person = $instructor->get();
373+
$person = $structuredOutput->get();
374374
```
375375

376376

@@ -381,9 +381,9 @@ processing the data as soon as it is available.
381381

382382
```php
383383
<?php
384-
use Cognesy\Instructor\Instructor;
384+
use Cognesy\Instructor\StructuredOutput;
385385

386-
$stream = (new Instructor)->request(
386+
$stream = (new StructuredOutput)->request(
387387
messages: "His name is Jason, he is 28 years old.",
388388
responseModel: Person::class,
389389
options: ['stream' => true]
@@ -411,13 +411,13 @@ You can define `onPartialUpdate()` callback to receive partial results that can
411411
> NOTE: Partial updates are not validated. The response is only validated after it is fully received.
412412

413413
```php
414-
use Cognesy\Instructor\Instructor;
414+
use Cognesy\Instructor\StructuredOutput;
415415

416416
function updateUI($person) {
417417
// Here you get partially completed Person object update UI with the partial result
418418
}
419419

420-
$person = (new Instructor)->request(
420+
$person = (new StructuredOutput)->request(
421421
messages: "His name is Jason, he is 28 years old.",
422422
responseModel: Person::class,
423423
options: ['stream' => true]
@@ -440,17 +440,17 @@ You can provide a string instead of an array of messages. This is useful when yo
440440
```php
441441
// Usually, you work with sequences of messages:
442442

443-
$value = (new Instructor)->respond(
443+
$value = (new StructuredOutput)->create(
444444
messages: [['role' => 'user', 'content' => "His name is Jason, he is 28 years old."]],
445445
responseModel: Person::class,
446-
);
446+
)->get();
447447

448448
// ...but if you want to keep it simple, you can just pass a string:
449449

450-
$value = (new Instructor)->respond(
450+
$value = (new StructuredOutput)->create(
451451
messages: "His name is Jason, he is 28 years old.",
452452
responseModel: Person::class,
453-
);
453+
)->get();
454454
```
455455

456456

@@ -460,12 +460,12 @@ Sometimes we just want to get quick results without defining a class for the res
460460

461461
```php
462462
use Cognesy\Instructor\Extras\Scalar\Scalar;
463-
use Cognesy\Instructor\Instructor;
463+
use Cognesy\Instructor\StructuredOutput;
464464

465-
$value = (new Instructor)->respond(
465+
$value = (new StructuredOutput)->create(
466466
messages: "His name is Jason, he is 28 years old.",
467467
responseModel: Scalar::integer('age'),
468-
);
468+
)->getInt();
469469

470470
var_dump($value);
471471
// int(28)
@@ -480,7 +480,7 @@ Additionally, you can use Scalar adapter to extract one of the provided options
480480

481481
```php
482482
use Cognesy\Instructor\Extras\Scalar\Scalar;
483-
use Cognesy\Instructor\Instructor;
483+
use Cognesy\Instructor\StructuredOutput;
484484

485485
enum ActivityType : string {
486486
case Work = 'work';
@@ -489,10 +489,10 @@ enum ActivityType : string {
489489
case Other = 'other';
490490
}
491491

492-
$value = (new Instructor)->respond(
492+
$value = (new StructuredOutput)->create(
493493
messages: "His name is Jason, he currently plays Doom Eternal.",
494494
responseModel: Scalar::enum(ActivityType::class, 'activityType'),
495-
);
495+
)->getInstanceOf(ActivityType::class);
496496

497497
var_dump($value);
498498
// enum(ActivityType:Entertainment)
@@ -522,11 +522,11 @@ $text = <<<TEXT
522522
and Anna is 2 years younger than him.
523523
TEXT;
524524

525-
$list = (new Instructor)->respond(
525+
$list = (new StructuredOutput)->create(
526526
messages: [['role' => 'user', 'content' => $text]],
527527
responseModel: Sequence::of(Person::class),
528528
options: ['stream' => true]
529-
);
529+
)->get();
530530
```
531531

532532
See more about sequences in the [Sequences](docs/sequences.md) section.
@@ -592,7 +592,7 @@ class Event {
592592
Instructor can retrieve complex data structures from text. Your response model can contain nested objects, arrays, and enums.
593593

594594
```php
595-
use Cognesy\Instructor\Instructor;
595+
use Cognesy\Instructor\StructuredOutput;
596596

597597
// define a data structures to extract data into
598598
class Person {
@@ -615,10 +615,10 @@ enum SkillType {
615615

616616
$text = "Alex is 25 years old software engineer, who knows PHP, Python and can play the guitar.";
617617

618-
$person = (new Instructor)->respond(
618+
$person = (new StructuredOutput)->create(
619619
messages: [['role' => 'user', 'content' => $text]],
620620
responseModel: Person::class,
621-
); // client is passed explicitly, can specify e.g. different base URL
621+
)->get(); // client is passed explicitly, can specify e.g. different base URL
622622

623623
// data is extracted into an object of given class
624624
assert($person instanceof Person); // true
@@ -684,10 +684,10 @@ $structure = Structure::define('person', [
684684
Field::enum('role', Role::class),
685685
]);
686686

687-
$person = (new Instructor)->respond(
687+
$person = (new StructuredOutput)->create(
688688
messages: 'Jason is 25 years old and is a manager.',
689689
responseModel: $structure,
690-
);
690+
)->get();
691691

692692
// you can access structure data via field API...
693693
assert($person->field('name') === 'Jason');
@@ -707,7 +707,7 @@ You can specify model and other options that will be passed to OpenAI / LLM endp
707707

708708
```php
709709
use Cognesy\Instructor\Features\LLM\Drivers\OpenAIDriver;
710-
use Cognesy\Instructor\Instructor;
710+
use Cognesy\Instructor\StructuredOutput;
711711
use Cognesy\LLM\LLM\Data\LLMConfig;
712712

713713
// OpenAI auth params
@@ -724,14 +724,14 @@ $driver = new OpenAIDriver(new LLMConfig(
724724
));
725725

726726
/// Get Instructor with the default client component overridden with your own
727-
$instructor = (new Instructor)->withDriver($driver);
727+
$structuredOutput = (new StructuredOutput)->withDriver($driver);
728728

729-
$user = $instructor->respond(
729+
$user = $structuredOutput->create(
730730
messages: "Jason (@jxnlco) is 25 years old and is the admin of this project. He likes playing football and reading books.",
731731
responseModel: User::class,
732732
model: 'gpt-3.5-turbo',
733733
options: ['stream' => true ]
734-
);
734+
)->get();
735735
```
736736

737737

@@ -809,7 +809,7 @@ class User {
809809
Instructor uses Symfony validation component to validate extracted data. You can use #[Assert/Callback] annotation to build fully customized validation logic.
810810

811811
```php
812-
use Cognesy\Instructor\Instructor;
812+
use Cognesy\Instructor\StructuredOutput;
813813
use Symfony\Component\Validator\Constraints as Assert;
814814
use Symfony\Component\Validator\Context\ExecutionContextInterface;
815815

@@ -829,11 +829,11 @@ class UserDetails
829829
}
830830
}
831831

832-
$user = (new Instructor)->respond(
832+
$user = (new StructuredOutput)->create(
833833
messages: [['role' => 'user', 'content' => 'jason is 25 years old']],
834834
responseModel: UserDetails::class,
835835
maxRetries: 2
836-
);
836+
)->get();
837837

838838
assert($user->name === "JASON");
839839
```
@@ -866,32 +866,32 @@ As Instructor for PHP processes your request, it goes through several stages:
866866

867867
Instructor allows you to receive detailed information at every stage of request and response processing via events.
868868

869-
* `(new Instructor)->onEvent(string $class, callable $callback)` method - receive callback when specified type of event is dispatched
870-
* `(new Instructor)->wiretap(callable $callback)` method - receive any event dispatched by Instructor, may be useful for debugging or performance analysis
869+
* `(new StructuredOutput)->onEvent(string $class, callable $callback)` method - receive callback when specified type of event is dispatched
870+
* `(new StructuredOutput)->wiretap(callable $callback)` method - receive any event dispatched by Instructor, may be useful for debugging or performance analysis
871871

872872
Receiving events can help you to monitor the execution process and makes it easier for a developer to understand and resolve any processing issues.
873873

874874
```php
875-
$instructor = (new Instructor)
875+
$structuredOutput = (new StructuredOutput)
876876
// see requests to LLM
877877
->onEvent(HttpRequestSent::class, fn($e) => dump($e))
878878
// see responses from LLM
879879
->onEvent(HttpResponseReceived::class, fn($event) => dump($event))
880880
// see all events in console-friendly format
881881
->wiretap(fn($event) => dump($event->toConsole()));
882882

883-
$instructor->respond(
883+
$structuredOutput->create(
884884
messages: "What is the population of Paris?",
885885
responseModel: Scalar::integer(),
886-
);
886+
)->getInt();
887887
// check your console for the details on the Instructor execution
888888
```
889889

890890
### Response Models
891891

892892
Instructor is able to process several types of input provided as response model, giving you more flexibility on how you interact with the library.
893893

894-
The signature of `respond()` method of Instructor states the `responseModel` can be either string, object or array.
894+
The `responseModel` can be either string, object or array.
895895

896896
#### Handling string $responseModel value
897897

bin/bootstrap.php renamed to bin/bootstrap.php.bak

File renamed without changes.

0 commit comments

Comments
 (0)