refactor\!: replace composer suggests with runtime checks

Remove the `suggest` section from composer.json and add explicit runtime checks
that throw exceptions with helpful composer require commands when optional
dependencies are missing.

This provides better developer experience by:
- Giving clear error messages when optional dependencies are needed
- Providing the exact composer command to install missing packages
- Following Symfony's pattern for handling optional dependencies

BREAKING CHANGE: Optional dependencies now throw exceptions instead of
silently failing when the required packages are not installed.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: OskarStark

composer.json

@@ -63,19 +63,6 @@
         "symfony/process": "^6.4 || ^7.1",
         "symfony/var-dumper": "^6.4 || ^7.1"
     },
-    "suggest": {
-        "ext-pdo": "For using MariaDB as retrieval vector store.",
-        "async-aws/bedrock-runtime": "For using the Bedrock platform.",
-        "codewithkyrian/chromadb-php": "For using the ChromaDB as retrieval vector store.",
-        "codewithkyrian/transformers": "For using the TransformersPHP with FFI to run models in PHP.",
-        "doctrine/dbal": "For using MariaDB via Doctrine as retrieval vector store",
-        "mongodb/mongodb": "For using MongoDB Atlas as retrieval vector store.",
-        "mrmysql/youtube-transcript": "For using the YouTube transcription tool.",
-        "probots-io/pinecone-php": "For using the Pinecone as retrieval vector store.",
-        "symfony/dom-crawler": "For using the Crawler tool.",
-        "symfony/http-foundation": "For using the SessionStore as message store.",
-        "psr/cache": "For using the CacheStore as message store."
-    },
     "config": {
         "allow-plugins": {
             "codewithkyrian/transformers-libsloader": true,

src/Chain/Chat/MessageStore/CacheStore.php

@@ -16,6 +16,9 @@ public function __construct(
         private string $cacheKey,
         private int $ttl = 86400,
     ) {
+        if (!interface_exists(CacheItemPoolInterface::class)) {
+            throw new \RuntimeException('For using the CacheStore as message store, the psr/cache package is required. Try running "composer require psr/cache"');
+        }
     }
 
     public function save(MessageBagInterface $messages): void

src/Chain/Chat/MessageStore/SessionStore.php

@@ -18,6 +18,9 @@ public function __construct(
         RequestStack $requestStack,
         private string $sessionKey = 'messages',
     ) {
+        if (!class_exists(RequestStack::class)) {
+            throw new \RuntimeException('For using the SessionStore as message store, the symfony/http-foundation package is required. Try running "composer require symfony/http-foundation"');
+        }
         $this->session = $requestStack->getSession();
     }
 

src/Chain/Toolbox/Tool/Crawler.php

@@ -19,7 +19,7 @@ public function __construct(
         private HttpClientInterface $httpClient,
     ) {
         if (!class_exists(DomCrawler::class)) {
-            throw new RuntimeException('The DomCrawler component is not installed. Please install it using "composer require symfony/dom-crawler".');
+            throw new RuntimeException('For using the Crawler tool, the symfony/dom-crawler package is required. Try running "composer require symfony/dom-crawler"');
         }
     }
 

src/Chain/Toolbox/Tool/YouTubeTranscriber.php

@@ -20,7 +20,7 @@ public function __construct(
         private HttpClientInterface $client,
     ) {
         if (!class_exists(TranscriptListFetcher::class)) {
-            throw new LogicException('The package `mrmysql/youtube-transcript` is required to use this tool. Try running "composer require mrmysql/youtube-transcript".');
+            throw new LogicException('For using the YouTube transcription tool, the mrmysql/youtube-transcript package is required. Try running "composer require mrmysql/youtube-transcript"');
         }
     }
 

src/Platform/Bridge/Bedrock/PlatformFactory.php

@@ -19,6 +19,10 @@ public static function create(
         BedrockRuntimeClient $bedrockRuntimeClient = new BedrockRuntimeClient(),
         ?Contract $contract = null,
     ): Platform {
+        if (!class_exists(BedrockRuntimeClient::class)) {
+            throw new \RuntimeException('For using the Bedrock platform, the async-aws/bedrock-runtime package is required. Try running "composer require async-aws/bedrock-runtime"');
+        }
+
         $modelClient[] = new ClaudeHandler($bedrockRuntimeClient);
         $modelClient[] = new NovaHandler($bedrockRuntimeClient);
         $modelClient[] = new LlamaModelClient($bedrockRuntimeClient);

src/Platform/Bridge/TransformersPHP/PlatformFactory.php

@@ -15,7 +15,7 @@
     public static function create(): Platform
     {
         if (!class_exists(Transformers::class)) {
-            throw new RuntimeException('TransformersPHP is not installed. Please install it using "composer require codewithkyrian/transformers".');
+            throw new RuntimeException('For using the TransformersPHP with FFI to run models in PHP, the codewithkyrian/transformers package is required. Try running "composer require codewithkyrian/transformers"');
         }
 
         return new Platform();

src/Store/Bridge/ChromaDB/Store.php

@@ -20,6 +20,9 @@ public function __construct(
         private Client $client,
         private string $collectionName,
     ) {
+        if (!class_exists(Client::class)) {
+            throw new \RuntimeException('For using the ChromaDB as retrieval vector store, the codewithkyrian/chromadb-php package is required. Try running "composer require codewithkyrian/chromadb-php"');
+        }
     }
 
     public function add(VectorDocument ...$documents): void

src/Store/Bridge/MariaDB/Store.php

@@ -34,6 +34,9 @@ public function __construct(
         private string $indexName,
         private string $vectorFieldName,
     ) {
+        if (!extension_loaded('pdo')) {
+            throw new \RuntimeException('For using MariaDB as retrieval vector store, the PDO extension is required. Try running "composer require ext-pdo"');
+        }
     }
 
     public static function fromPdo(\PDO $connection, string $tableName, string $indexName = 'embedding', string $vectorFieldName = 'embedding'): self
@@ -46,6 +49,10 @@ public static function fromPdo(\PDO $connection, string $tableName, string $inde
      */
     public static function fromDbal(Connection $connection, string $tableName, string $indexName = 'embedding', string $vectorFieldName = 'embedding'): self
     {
+        if (!class_exists(Connection::class)) {
+            throw new \RuntimeException('For using MariaDB via Doctrine as retrieval vector store, the doctrine/dbal package is required. Try running "composer require doctrine/dbal"');
+        }
+
         $pdo = $connection->getNativeConnection();
 
         if (!$pdo instanceof \PDO) {

src/Store/Bridge/MongoDB/Store.php

@@ -59,6 +59,9 @@ public function __construct(
         private bool $bulkWrite = false,
         private LoggerInterface $logger = new NullLogger(),
     ) {
+        if (!class_exists(Client::class)) {
+            throw new \RuntimeException('For using MongoDB Atlas as retrieval vector store, the mongodb/mongodb package is required. Try running "composer require mongodb/mongodb"');
+        }
     }
 
     public function add(VectorDocument ...$documents): void