Fixing broken build

Author: ddebowczyk

.gitattributes

@@ -21,7 +21,8 @@
 /docs/            export-ignore
 #/evals/          export-ignore # include this one with distribution
 #/examples/       export-ignore # include this one with distribution
-/experimental/    export-ignore
+/src-auxiliary/    export-ignore
+/src-experimental/ export-ignore
 /notes/           export-ignore
 /scratchpad/      export-ignore
 /tests/           export-ignore
@@ -52,6 +53,7 @@
 
 # Linguist overrides (optional for GitHub)
 *.md              linguist-documentation
+*.mdx             linguist-documentation
 *.json            linguist-vendored
 /vendor/          linguist-vendored
 

.github/workflows/php.yml

@@ -27,17 +27,20 @@ jobs:
     - name: Validate composer.json and composer.lock
       run: composer validate --strict
 
-    - name: Cache Composer packages
-      id: composer-cache
-      uses: actions/cache@v3
-      with:
-        path: vendor
-        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
-        restore-keys: |
-          ${{ runner.os }}-php-
+#    - name: Cache Composer packages
+#      id: composer-cache
+#      uses: actions/cache@v3
+#      with:
+#        path: vendor
+#        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
+#        restore-keys: |
+#          ${{ runner.os }}-php-
 
     - name: Install dependencies
       run: composer update --no-interaction --no-suggest ${{ matrix.composer }}
 
+    - name: Regenerate Autoloader
+      run: composer dump-autoload
+
     - name: Run test suite
       run: composer test

bin/sync-ver.sh

@@ -13,17 +13,18 @@ VERSION=${VERSION#v}
 
 # Define packages and their sections based on composer.json
 declare -A REQUIRE_PACKAGES=(
-    ["src-utils"]="cognesy/utils"
-    ["src-addons"]="cognesy/instructor-php-addons"
-    ["src-polyglot"]="cognesy/polyglot-php"
+    ["src-utils"]="cognesy/instructor-utils"
+    ["src-addons"]="cognesy/instructor-addons"
+    ["src-polyglot"]="cognesy/instructor-polyglot"
+    ["src-instructor"]="cognesy/instructor-core"
 )
 
 declare -A REQUIRE_DEV_PACKAGES=(
-    ["src-aux"]="cognesy/aux"
-    ["src-experimental"]="cognesy/experimental"
-    ["src-hub"]="cognesy/instructor-php-hub"
-    ["src-setup"]="cognesy/instructor-php-setup"
-    ["src/Tell"]="cognesy/tell"
+    ["src-aux"]="cognesy/instructor-aux"
+    ["src-experimental"]="cognesy/instructor-experimental"
+    ["src-hub"]="cognesy/instructor-hub"
+    ["src-setup"]="cognesy/instructor-setup"
+    ["src-tell"]="cognesy/tell-cli"
 )
 
 # Update version in each package's composer.json

composer.json

@@ -24,11 +24,11 @@
   ],
   "autoload": {
     "psr-4": {
+      "Cognesy\\Utils\\": "src-utils/",
       "Cognesy\\Addons\\": "src-addons/",
       "Cognesy\\Instructor\\": "src-instructor/",
       "Cognesy\\Polyglot\\": "src-polyglot/",
       "Cognesy\\Setup\\": "src-setup/",
-      "Cognesy\\Utils\\": "src-utils/"
     },
     "files": []
   },

docs/release-notes/v0.12.6.md

@@ -0,0 +1,4 @@
+ - Continued project files reorganization
+ - Created README.md, LICENSE.md, composer.json, .gitattributes for subprojects to be ready for future split
+ - Corrected composer.json, .gitignore and .gitattributes
+ - Docs directory structure cleanup to work with Mintlify

examples/A01_Basics/Basic/run.php

@@ -0,0 +1,66 @@
+---
+title: 'Basic use'
+docname: 'basic_use'
+path: ''
+---
+
+## Overview
+
+Instructor allows you to use large language models to extract information
+from the text (or content of chat messages), while following the structure
+you define.
+
+LLM does not 'parse' the text to find and retrieve the information.
+Extraction leverages LLM ability to comprehend provided text and infer
+the meaning of the information it contains to fill fields of the
+response object with values that match the types and semantics of the
+class fields.
+
+The simplest way to use the Instructor is to call the `respond` method
+on the Instructor instance. This method takes a string (or an array of
+strings in the format of OpenAI chat messages) as input and returns a
+data extracted from provided text (or chat) using the LLM inference.
+
+Returned object will contain the values of fields extracted from the text.
+
+The format of the extracted data is defined by the response model, which
+in this case is a simple PHP class with some public properties.
+
+## Example
+
+```php
+<?php
+require 'examples/boot.php';
+
+use Cognesy\Instructor\Instructor;
+
+// Step 1: Define a class that represents the structure and semantics
+// of the data you want to extract
+class User {
+    public int $age;
+    public string $name;
+}
+
+// Step 2: Get the text (or chat messages) you want to use as context
+$text = "Jason is 25 years old and works as an engineer.";
+print("Input text:\n");
+print($text . "\n\n");
+
+// Step 3: Extract structured data using default language model API (OpenAI)
+print("Extracting structured data using LLM...\n\n");
+$user = (new Instructor)->respond(
+    messages: $text,
+    responseModel: User::class,
+);
+
+// Step 4: Now you can use the extracted data in your application
+print("Extracted data:\n");
+
+dump($user);
+
+assert(isset($user->name));
+assert(isset($user->age));
+assert($user->name === 'Jason');
+assert($user->age === 25);
+?>
+```

examples/A01_Basics/BasicViaMixin/run.php

@@ -0,0 +1,54 @@
+---
+title: 'Basic use via mixin'
+docname: 'basic_use_mixin'
+---
+
+## Overview
+
+Instructor provides `HandlesSelfInference` trait that you can use to enable
+extraction capabilities directly on class via static `infer()` method.
+
+`infer()` method returns an instance of the class with the data extracted
+using the Instructor.
+
+`infer()` method has following signature (you can also find it in the
+`CanSelfInfer` interface):
+
+```php
+static public function infer(
+    string|array $messages, // (required) The message(s) to infer data from
+    string $prompt = '',    // (optional) The prompt to use for inference
+    array $examples = [],   // (optional) Examples to include in the prompt
+    string $model = '',     // (optional) The model to use for inference (otherwise - use default)
+    int $maxRetries = 2,    // (optional) The number of retries in case of validation failure
+    array $options = [],    // (optional) Additional data to pass to the Instructor or LLM API
+    Mode $mode = Mode::Tools, // (optional) The mode to use for inference
+    LLM $llm = null         // (optional) LLM instance to use for inference
+) : static;
+```
+
+## Example
+
+```php
+<?php
+require 'examples/boot.php';
+
+use Cognesy\Instructor\Extras\Mixin\HandlesSelfInference;
+
+class User {
+    use HandlesSelfInference;
+
+    public int $age;
+    public string $name;
+}
+
+$user = User::infer("Jason is 25 years old and works as an engineer.");
+
+dump($user);
+
+assert(isset($user->name));
+assert(isset($user->age));
+assert($user->name === 'Jason');
+assert($user->age === 25);
+?>
+```

examples/A01_Basics/Maybe/run.php

@@ -0,0 +1,64 @@
+---
+title: 'Handling errors with `Maybe` helper class'
+docname: 'maybe'
+---
+
+## Overview
+
+You can create a wrapper class to hold either the result of an operation or an error message.
+This allows you to remain within a function call even if an error occurs, facilitating
+better error handling without breaking the code flow.
+
+## Example
+
+```php
+<?php
+require 'examples/boot.php';
+
+use Cognesy\Instructor\Extras\Maybe\Maybe;
+use Cognesy\Instructor\Instructor;
+use Cognesy\Polyglot\LLM\Enums\Mode;
+
+class User
+{
+    public string $name;
+    public int $age;
+}
+
+
+$text = 'We have no information about our new developer.';
+echo "\nINPUT:\n$text\n";
+
+$maybeUser = (new Instructor)->respond(
+    messages: [['role' => 'user', 'content' => $text]],
+    responseModel: Maybe::is(User::class),
+    model: 'gpt-4o-mini',
+    mode: Mode::MdJson,
+);
+
+echo "\nOUTPUT:\n";
+
+dump($maybeUser->get());
+
+assert($maybeUser->hasValue() === false);
+assert(!empty($maybeUser->error()));
+assert($maybeUser->get() === null);
+
+$text = "Jason is our new developer, he is 25 years old.";
+echo "\nINPUT:\n$text\n";
+
+$maybeUser = (new Instructor)->respond(
+    messages: [['role' => 'user', 'content' => $text]],
+    responseModel: Maybe::is(User::class)
+);
+
+echo "\nOUTPUT:\n";
+
+dump($maybeUser->get());
+
+assert($maybeUser->hasValue() === true);
+assert(empty($maybeUser->error()));
+assert($maybeUser->get() != null);
+assert($maybeUser->get() instanceof User);
+?>
+```

examples/A01_Basics/Modes/run.php

@@ -0,0 +1,91 @@
+---
+title: 'Modes'
+docname: 'modes'
+---
+
+## Overview
+
+Instructor supports several ways to extract data from the response:
+
+ - `Mode::Tools` - uses OpenAI-style tool calls to get the language
+   model to generate JSON following the schema,
+ - `Mode::JsonSchema` - guarantees output matching JSON Schema via
+   Context Free Grammar, does not support optional properties,
+ - `Mode::Json` - JSON mode, response follows provided JSON Schema,
+ - `Mode::MdJson` - uses prompting to get the language model to
+   generate JSON following the schema.
+
+Note: not all modes are supported by all models or providers.
+
+Mode can be set via parameter of `Instructor::response()` or `Instructor::request()`
+methods.
+
+## Example
+
+```php
+<?php
+require 'examples/boot.php';
+
+use Cognesy\Instructor\Instructor;
+use Cognesy\Polyglot\LLM\Enums\Mode;
+
+class User {
+    public int $age;
+    public string $name;
+}
+
+$text = "Jason is 25 years old and works as an engineer.";
+
+print("Input text:\n");
+print($text . "\n\n");
+
+$instructor = new Instructor;
+
+// CASE 1 - Mode::Tools
+print("\n1. Extracting structured data using LLM - Mode::Tools\n");
+$user = $instructor->respond(
+    messages: $text,
+    responseModel: User::class,
+    mode: Mode::Tools,
+);
+check($user);
+dump($user);
+
+// CASE 2 - Mode::JsonSchema
+print("\n2. Extracting structured data using LLM - Mode::JsonSchema\n");
+$user = $instructor->respond(
+    messages: $text,
+    responseModel: User::class,
+    mode: Mode::JsonSchema,
+);
+check($user);
+dump($user);
+
+// CASE 3 - Mode::Json
+print("\n3. Extracting structured data using LLM - Mode::Json\n");
+$user = $instructor->respond(
+    messages: $text,
+    responseModel: User::class,
+    mode: Mode::Json,
+);
+check($user);
+dump($user);
+
+// CASE 4 - Mode::MdJson
+print("\n4. Extracting structured data using LLM - Mode::MdJson\n");
+$user = $instructor->respond(
+    messages: $text,
+    responseModel: User::class,
+    mode: Mode::MdJson,
+);
+check($user);
+dump($user);
+
+function check(User $user) {
+    assert(isset($user->name));
+    assert(isset($user->age));
+    assert($user->name === 'Jason');
+    assert($user->age === 25);
+}
+?>
+```