Docs update

Author: ddebowczyk

README.md

@@ -13,6 +13,89 @@ This monorepo contains a set of dev-friendly, framework agnostic components offe
 - Docs website (Mintlify) https://docs.instructorphp.com
 - Docs (Github Pages) https://cognesy.github.io/instructor-php/
 
+## Overview of Capabilities
+
+The library offers a set of small, focused building blocks.
+
+### Structured output
+
+Purpose: turn messy model output into typed PHP data.
+Benefit: you stop hand-parsing JSON or text before using LLM results.
+
+```php
+use Cognesy\Instructor\StructuredOutput;
+
+final class Person {
+    public string $name;
+    public int $age;
+}
+
+$person = StructuredOutput::using('openai')
+    ->with(messages: 'Jason is 28 years old.', responseModel: Person::class)
+    ->get();
+```
+
+Detailed docs: [packages/instructor/docs/](packages/instructor/docs/)
+
+### Unified inference
+
+Purpose: call different LLM providers through one API.
+Benefit: switch providers without rewriting request code.
+
+```php
+use Cognesy\Polyglot\Inference\Inference;
+
+$text = Inference::using('openai')
+    ->withMessages('Say hello in one sentence.')
+    ->get();
+```
+
+Detailed docs: [packages/polyglot/docs/](packages/polyglot/docs/)
+
+### Embeddings
+
+Purpose: generate vectors through the same provider layer.
+Benefit: keep retrieval and inference in one stack.
+
+```php
+use Cognesy\Polyglot\Embeddings\Embeddings;
+
+$vectors = Embeddings::using('openai')
+    ->withInputs(['hello world'])
+    ->vectors();
+```
+
+Detailed docs: [packages/polyglot/docs/](packages/polyglot/docs/)
+
+### Agents SDK
+
+Purpose: build tool-using agents as a simple loop over state.
+Benefit: add tools and control flow without inventing your own agent runtime first.
+
+```php
+use Cognesy\Agents\AgentLoop;
+use Cognesy\Agents\Data\AgentState;
+
+$result = AgentLoop::default()->execute(
+    AgentState::empty()->withUserMessage('What is 2+2?')
+);
+```
+
+Detailed docs: [packages/agents/docs/](packages/agents/docs/)
+
+### Code agent bridges
+
+Purpose: drive external coding agents like Codex, Claude Code, and OpenCode from PHP.
+Benefit: automate reviews, summaries, and coding workflows through one interface.
+
+```php
+use Cognesy\AgentCtrl\AgentCtrl;
+
+$response = AgentCtrl::codex()->execute('Summarize this repository.');
+```
+
+Detailed docs: [packages/agent-ctrl/docs/](packages/agent-ctrl/docs/)
+
 
 ## What is Instructor?
 
@@ -149,6 +232,7 @@ Instructor validates results of LLM response against validation rules specified
 > For further details on available validation rules, check [Symfony Validation constraints](https://symfony.com/doc/current/validation.html#constraints).
 
 ```php
+use Cognesy\Instructor\StructuredOutput;
 use Symfony\Component\Validator\Constraints as Assert;
 
 class Person {
@@ -226,8 +310,9 @@ Polyglot takes care of translation of familiar OpenAI chat completion API conven
 ### Example (using sync API)
 
 ```php
-$answer = (new Inference)
-    ->using('openai') // specify LLM connection preset (defined in config)
+use Cognesy\Polyglot\Inference\Inference;
+
+$answer = Inference::using('openai') // specify LLM connection preset (defined in config)
     ->with(messages: 'What is capital of Germany')
     ->get();
 
@@ -237,8 +322,9 @@ echo $answer;
 ### Example (using streaming API)
 
 ```php
-$stream = (new Inference)
-    ->using('anthropic') // specify LLM connection preset (defined in config)
+use Cognesy\Polyglot\Inference\Inference;
+
+$stream = Inference::using('anthropic') // specify LLM connection preset (defined in config)
     ->withMessages([['role' => 'user', 'content' => 'Describe capital of Brasil']])
     ->withOptions(['max_tokens' => 256])
     ->withStreaming()
@@ -253,20 +339,17 @@ foreach ($stream as $delta) {
 ### Example (customize LLM connection)
 
 ```php
-$config = new LLMConfig(
-    apiUrl  : 'https://api.deepseek.com',
-    apiKey  : Env::get('DEEPSEEK_API_KEY'),
-    endpoint: '/chat/completions',
-    model: 'deepseek-chat',
-    maxTokens: 128,
-    driver: 'deepseek',
-);
-
-$answer = (new Inference)
-    ->withConfig($config)
+use Cognesy\Polyglot\Inference\Config\LLMConfig;
+use Cognesy\Polyglot\Inference\Inference;
+
+$answer = Inference::fromConfig(LLMConfig::fromArray([
+    'driver' => 'deepseek',
+    'apiUrl' => 'https://api.deepseek.com',
+    'endpoint' => '/chat/completions',
+    'model' => 'deepseek-chat',
+]))
     ->withMessages([['role' => 'user', 'content' => 'What is the capital of France']])
     ->withOptions(['max_tokens' => 64])
-    ->withStreaming()
     ->get();
 
 echo $answer;

builds/docs-build/cookbook/examples/A01_Basics/basic_use_mixin.mdx

@@ -1,35 +1,12 @@
 ---
-title: 'Basic use via mixin'
+title: 'Basic use via StructuredOutput'
 docname: 'basic_use_mixin'
 id: '068c'
 ---
 ## Overview
 
-`HandlesSelfInference` is deprecated in 2.0.
-Prefer runtime-first usage via `StructuredOutput::using('openai')->with(...)->getObject()`.
-
-Legacy mixin usage is still available and shown below for migration reference.
-
-`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 = OutputMode::Tools, // (optional) The mode to use for inference
-    ?LLM $llm = null         // (optional) LLM instance to use for inference
-) : static;
-```
-
-Recommended replacement:
+Mixin-based inference was removed in 2.0.
+Use `StructuredOutput` directly:
 
 ```php
 use Cognesy\Instructor\StructuredOutput;
@@ -48,20 +25,19 @@ $user = StructuredOutput::using('openai')
 <?php
 require 'examples/boot.php';
 
-use Cognesy\Instructor\Extras\Mixin\HandlesSelfInference;
-use Cognesy\Polyglot\Inference\LLMProvider;
+use Cognesy\Instructor\StructuredOutput;
 
 class User {
-    use HandlesSelfInference;
-
     public int $age;
     public string $name;
 }
 
-$user = User::infer(
-    messages: "Jason is 25 years old and works as an engineer.",
-    llm: LLMProvider::fromLLMConfig(ExampleConfig::llmPreset('openai')),
-);
+$user = StructuredOutput::using('openai')
+    ->with(
+        messages: "Jason is 25 years old and works as an engineer.",
+        responseModel: User::class,
+    )
+    ->getObject();
 
 dump($user);
 

builds/docs-build/cookbook/examples/A01_Basics/constructor_parameters.mdx

@@ -56,7 +56,6 @@ $text = <<<TEXT
     Jason is 25 years old.
     TEXT;
 
-
 $user = StructuredOutput::using('openai')
     ->withMessages($text)
     ->withResponseClass(UserWithConstructor::class)

builds/docs-build/cookbook/examples/A01_Basics/custom_validation.mdx

@@ -16,6 +16,8 @@ offers you #[Assert/Callback] annotation to build fully customized validation lo
 require 'examples/boot.php';
 
 use Cognesy\Instructor\StructuredOutput;
+use Cognesy\Instructor\StructuredOutputRuntime;
+use Cognesy\Polyglot\Inference\LLMProvider;
 use Symfony\Component\Validator\Constraints as Assert;
 use Symfony\Component\Validator\Context\ExecutionContextInterface;
 
@@ -35,12 +37,14 @@ class UserDetails
     }
 }
 
-$user = StructuredOutput::using('openai')
-    ->wiretap(fn($e) => $e->print())
+$runtime = StructuredOutputRuntime::fromProvider(LLMProvider::using('openai'))
+    ->withMaxRetries(2)
+    ->wiretap(fn($e) => $e->print());
+
+$user = (new StructuredOutput($runtime))
     ->with(
         messages: [['role' => 'user', 'content' => 'jason is 25 years old']],
         responseModel: UserDetails::class,
-        maxRetries: 2
     )
     ->get();
 

builds/docs-build/cookbook/examples/A01_Basics/getters_and_setters.mdx

@@ -19,6 +19,8 @@ and default value to determine if property is required.
 require 'examples/boot.php';
 
 use Cognesy\Instructor\StructuredOutput;
+use Cognesy\Instructor\StructuredOutputRuntime;
+use Cognesy\Polyglot\Inference\LLMProvider;
 use Cognesy\Schema\Attributes\Description;
 
 class UserWithSetter
@@ -72,10 +74,12 @@ $text = <<<TEXT
     TEXT;
 
 
-$user = StructuredOutput::using('openai')
+$user = new StructuredOutput(
+        StructuredOutputRuntime::fromProvider(LLMProvider::using('openai'))
+            ->withMaxRetries(2)
+    )
     ->withMessages($text)
     ->withResponseClass(UserWithSetter::class)
-    ->withMaxRetries(2)
     ->get();
 
 dump($user);

builds/docs-build/cookbook/examples/A01_Basics/maybe.mdx

@@ -17,7 +17,9 @@ require 'examples/boot.php';
 
 use Cognesy\Instructor\Extras\Maybe\Maybe;
 use Cognesy\Instructor\StructuredOutput;
-use Cognesy\Polyglot\Inference\Enums\OutputMode;
+use Cognesy\Instructor\StructuredOutputRuntime;
+use Cognesy\Instructor\Enums\OutputMode;
+use Cognesy\Polyglot\Inference\LLMProvider;
 
 class User
 {
@@ -29,11 +31,13 @@ class User
 $text = 'We have no information about our new developer.';
 echo "\nINPUT:\n$text\n";
 
-$maybeUser = StructuredOutput::using('openai')->with(
+$maybeUser = (new StructuredOutput(
+    StructuredOutputRuntime::fromProvider(LLMProvider::using('openai'))
+        ->withOutputMode(OutputMode::MdJson)
+))->with(
     messages: [['role' => 'user', 'content' => $text]],
     responseModel: Maybe::is(User::class),
     model: 'gpt-4o-mini',
-    mode: OutputMode::MdJson,
 )->get();
 
 echo "\nOUTPUT:\n";

builds/docs-build/cookbook/examples/A01_Basics/messages_api.mdx

@@ -16,9 +16,11 @@ messages and their sequences.
 require 'examples/boot.php';
 
 use Cognesy\Instructor\StructuredOutput;
+use Cognesy\Instructor\StructuredOutputRuntime;
 use Cognesy\Messages\Message;
 use Cognesy\Messages\Messages;
-use Cognesy\Polyglot\Inference\Enums\OutputMode;
+use Cognesy\Instructor\Enums\OutputMode;
+use Cognesy\Polyglot\Inference\LLMProvider;
 use Cognesy\Utils\Str;
 
 class Code {
@@ -43,10 +45,12 @@ $lastMessageId = $messages->last()->id()->toString();
 print("Last message ID: {$lastMessageId}\n");
 
 print("Extracting structured data using LLM...\n\n");
-$code = StructuredOutput::using('openai')
+$code = (new StructuredOutput(
+    StructuredOutputRuntime::fromProvider(LLMProvider::using('openai'))
+        ->withOutputMode(OutputMode::MdJson)
+))
     ->withMessages($messages)
     ->withResponseModel(Code::class)
-    ->withOutputMode(OutputMode::MdJson)
     ->get();
 
 print("Extracted data:\n");