Added new example of language program

Author: ddebowczyk

README.md

@@ -791,6 +791,12 @@ If you want to help, check out some of the issues. All contributions are welcome
 This project is licensed under the terms of the MIT License.
 
 
+## Support
+
+If you have any questions or need help, please reach out to me on [Twitter](https://twitter.com/ddebowczyk) or [GitHub](https://github.com/cognesy/instructor-php/issues).
+
+
+
 ## Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->

examples/02_Advanced/LanguagePrograms/run.php

@@ -38,10 +38,8 @@
 class EmailAnalysis extends SignatureData {
     #[InputField('content of email')]
     public string $text;
-
     #[OutputField('identify most relevant email topic: sales, support, other, spam')]
     public string $topic;
-
     #[OutputField('one word sentiment: positive, neutral, negative')]
     public string $sentiment;
 
@@ -62,19 +60,14 @@ public function __construct(
 class EmailStats extends SignatureData {
     #[InputField('directory containing emails')]
     public string $directory;
-
     #[OutputField('number of emails')]
     public int $emails;
-
     #[OutputField('number of spam emails')]
     public int $spam;
-
     #[OutputField('average sentiment ratio')]
     public float $sentimentRatio;
-
     #[OutputField('spam ratio')]
     public float $spamRatio;
-
     #[OutputField('category counts')]
     public CategoryCount $categories;
 
@@ -83,56 +76,56 @@ static public function for(string $directory) : static {
     }
 }
 
+// MODULE DECLARATIONS ////////////////////////////////////////////////////////////////////
+
 class ReadEmails extends Module {
     public function __construct(
         private array $directoryContents = []
     ) {}
 
     public function signature() : string|Signature {
-        return 'directory -> emails';
+        return 'directory -> emails : string[]';
     }
 
-    public function forward(string $directory) : array {
+    protected function forward(string $directory) : array {
         return $this->directoryContents[$directory];
     }
 }
 
 class ParseEmail extends Module {
     public function signature() : string|Signature {
-        return 'email -> sender, body';
+        return 'email -> sender, subject, body';
     }
 
     protected function forward(string $email) : array {
         $parts = explode(',', $email);
         return [
             'sender' => trim(explode(':', $parts[0])[1]),
-            'body' => trim(explode(':', $parts[1])[1]),
+            'subject' => trim(explode(':', $parts[1])[1]),
+            'body' => trim(explode(':', $parts[2])[1]),
         ];
     }
 }
 
 class GetStats extends Module {
-    private ReadEmails $readEmails;
-    private ParseEmail $parseEmail;
-    private Predict $analyseEmail;
-
-    public function __construct(Instructor $instructor, array $directoryContents = []) {
-        $this->readEmails = new ReadEmails($directoryContents);
-        $this->parseEmail = new ParseEmail();
-        $this->analyseEmail = new Predict(signature: EmailAnalysis::class, instructor: $instructor);
-    }
+    public function __construct(
+        private ReadEmails $readEmails,
+        private ParseEmail $parseEmail,
+        private Predict $analyseEmail,
+    ) {}
 
     public function signature() : string|Signature {
         return EmailStats::class;
     }
 
-    public function forward(string $directory) : EmailStats {
+    protected function forward(string $directory) : EmailStats {
         $emails = $this->readEmails->withArgs(directory: $directory)->get('emails');
         $aggregateSentiment = 0;
         $categories = new CategoryCount;
         foreach ($emails as $email) {
             $parsedEmail = $this->parseEmail->withArgs(email: $email);
-            $emailAnalysis = $this->analyseEmail->with(EmailAnalysis::for($parsedEmail->get('body')));
+            $emailData = EmailAnalysis::for(text: $parsedEmail->get('body'));
+            $emailAnalysis = $this->analyseEmail->with($emailData);
             $topic = $emailAnalysis->get('topic');
             $sentiment = $emailAnalysis->get('sentiment');
             $topic = (in_array($topic, ['sales', 'support', 'spam'])) ? $topic : 'other';
@@ -160,19 +153,26 @@ public function forward(string $directory) : EmailStats {
 }
 
 $directoryContents['inbox'] = [
-    'sender: [email protected], body: I am happy about the discount you offered and accept contract renewal',
-    'sender: xxx, body: Get Viagra and Ozempic for free',
-    'sender: [email protected], body: My internet connection keeps failing',
-    'sender: [email protected], body: How long do I have to wait for the pricing of custom support service?!?',
-    'sender: [email protected], body: 2 weeks of waiting and still no improvement of my connection',
+    'sender: [email protected], subject: Offer, body: I am happy about the discount you offered and accept contract renewal',
+    'sender: xxx, subject: Free!!!, body: Get Ozempic for free',
+    'sender: [email protected], subject: Problem, body: My internet connection keeps failing',
+    'sender: [email protected], subject: Still no pricing, body: How long do I have to wait for the pricing of custom support service?!?',
+    'sender: [email protected], subject: Slow connection, body: 2 weeks of waiting and still no improvement of my connection',
 ];
 
+// PREPARE DEPENDENCIES
+
 $instructor = (new Instructor);
-$getStats = new GetStats($instructor, $directoryContents);
+$readEmails = new ReadEmails($directoryContents);
+$parseEmail = new ParseEmail();
+$analyseEmail = new Predict(signature: EmailAnalysis::class, instructor: $instructor);
+$getStats = new GetStats($readEmails, $parseEmail, $analyseEmail);
+
+// EXECUTE LANGUAGE PROGRAM
+
 $emailStats = $getStats->with(EmailStats::for('inbox'));
 
 echo "Results:\n";
 dump($emailStats->get());
 ?>
 ```
-

examples/02_Advanced/LanguagePrograms2/run.php

@@ -0,0 +1,168 @@
+# Language programs
+
+Instructor provides an addon allowing to implement complex processing flows
+using LLM in a modular way. This addon to Instructor has been inspired by DSPy
+library for Python (https://github.com/stanfordnlp/dspy).
+
+Key components of language program:
+- Module subclasses - encapsulate processing logic
+- Signatures - define input and output for data processed by modules
+
+NOTE: Other concepts from DSPy (optimizer, compiler, evaluator) have not been implemented yet.
+
+Module consists of 3 key parts:
+- __construct() - initialization of module, prepare dependencies, setup submodules
+- signature() - define input and output for data processed by module
+- forward() - processing logic, return output data
+
+`Predict` class is a special module, that uses Instructor's structured processing
+capabilities to execute inference on provided inputs and return output in a requested
+format.
+
+```php
+<?php
+
+use Cognesy\Instructor\Extras\Module\Addons\Predict\Predict;
+use Cognesy\Instructor\Extras\Module\Core\Module;
+use Cognesy\Instructor\Extras\Module\Signature\Attributes\InputField;
+use Cognesy\Instructor\Extras\Module\Signature\Attributes\OutputField;
+use Cognesy\Instructor\Extras\Module\CallData\SignatureData;
+use Cognesy\Instructor\Instructor;
+use Cognesy\Instructor\Schema\Attributes\Description;
+
+$loader = require 'vendor/autoload.php';
+$loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
+
+// DATA MODEL DECLARATIONS ////////////////////////////////////////////////////////////////
+
+//#[Description('extract email details from text')]
+class ParsedEmail extends SignatureData {
+    #[InputField('text containing email')]
+    public string $text;
+
+    #[OutputField('email address of sender')]
+    public string $senderEmail;
+    #[OutputField('subject of the email')]
+    public string $subject;
+    #[OutputField('body of the email')]
+    public string $body;
+}
+
+class FixedEmail extends SignatureData {
+    #[InputField('subject of the email')]
+    public string $subject;
+    #[InputField('body of the email')]
+    public string $body;
+
+    #[OutputField('subject of the email with fixed spelling mistakes')]
+    public string $fixedSubject;
+    #[OutputField('body of the email with fixed spelling mistakes')]
+    public string $fixedBody;
+}
+
+class EmailTranslation extends SignatureData {
+    #[InputField('subject of email')]
+    public string $subject;
+    #[InputField('body of email')]
+    public string $body;
+    #[InputField('language to translate to')]
+    public string $language;
+
+    #[OutputField('translated subject of email')]
+    public string $translatedSubject;
+    #[OutputField('translated body of email')]
+    public string $translatedBody;
+}
+
+class Email {
+    public function __construct(
+        public string $senderEmail,
+        public string $subject,
+        public string $body
+    ) {}
+}
+
+class EmailProcessingResults {
+    public function __construct(
+        public Email $original,
+        public Email $fixed,
+        public Email $translated
+    ) {}
+}
+
+// MODULE DECLARATIONS ////////////////////////////////////////////////////////////////////
+
+class ProcessEmail extends Module {
+    public function __construct(
+        private Predict $parse,
+        private Predict $fix,
+        private Predict $translate
+    ) {}
+
+    public function signature(): string {
+        return 'text: string, language: string -> EmailProcessingResults';
+    }
+
+    public function forward(string $text, string $language): EmailProcessingResults {
+        $parsedEmail = $this->parse->with(
+            ParsedEmail::fromArgs(
+                text: $text
+            )
+        )->result();
+
+        $fixedEmail = $this->fix->with(
+            FixedEmail::fromArgs(
+                subject: $parsedEmail->subject,
+                body: $parsedEmail->body
+            )
+        )->result();
+
+        $translatedEmail = $this->translate->with(
+            EmailTranslation::fromArgs(
+                subject: $fixedEmail->fixedSubject,
+                body: $fixedEmail->fixedBody,
+                language: $language
+            )
+        )->result();
+
+        return new EmailProcessingResults(
+            new Email(
+                $parsedEmail->senderEmail,
+                $parsedEmail->subject,
+                $parsedEmail->body
+            ),
+            new Email(
+                $parsedEmail->senderEmail,
+                $fixedEmail->fixedSubject,
+                $fixedEmail->fixedBody
+            ),
+            new Email(
+                $parsedEmail->senderEmail,
+                $translatedEmail->translatedSubject,
+                $translatedEmail->translatedBody
+            )
+        );
+    }
+}
+
+// PREPARE DEPENDENCIES ///////////////////////////////////////////////////////////////////
+
+$instructor = new Instructor();
+
+$extractEmail = new Predict(signature: ParsedEmail::class, instructor: $instructor);
+$fixEmail = new Predict(signature: FixedEmail::class, instructor: $instructor);
+$translateEmail = new Predict(signature: EmailTranslation::class, instructor: $instructor);
+
+
+// EXECUTE LANGUAGE PROGRAM ///////////////////////////////////////////////////////////////
+
+$text = 'sender: [email protected], subject: Ofer, body: Im hapy abut the discount you offered and accept contract renewal';
+$language = 'French';
+
+$parseAndTranslate = new ProcessEmail($extractEmail, $fixEmail, $translateEmail);
+$result = $parseAndTranslate->withArgs(text: $text, language: $language)->result();
+
+echo "Results:\n";
+dump($result);
+?>
+```

src/Extras/Module/Addons/Predict/Predict.php

@@ -65,6 +65,7 @@ public function forward(array $args, object $targetObject): mixed {
             count($args) === 0 => throw new \Exception('Empty input'),
             count($args) === 1 => reset($args),
             default => match(true) {
+                is_array($args) => $args,
                 is_array($args[0]) => $args[0],
                 is_string($args[0]) => $args[0],
                 default => throw new Exception('Invalid input - should be string or messages array'),