Add AI Package with OpenAI and Anthropic integrations

composer.json

@@ -131,6 +131,7 @@
     "prefer-stable": true,
     "autoload": {
         "psr-4": {
+            "Tempest\\AI\\": "packages/ai/src",
             "Tempest\\Auth\\": "packages/auth/src",
             "Tempest\\Cache\\": "packages/cache/src",
             "Tempest\\Clock\\": "packages/clock/src",
@@ -165,6 +166,7 @@
             "Tempest\\Vite\\": "packages/vite/src"
         },
         "files": [
+            "packages/ai/src/functions.php",
             "packages/clock/src/functions.php",
             "packages/command-bus/src/functions.php",
             "packages/container/src/functions.php",
@@ -202,6 +204,7 @@
     },
     "autoload-dev": {
         "psr-4": {
+            "Tempest\\AI\\Tests\\": "packages/ai/tests",
             "Tempest\\Auth\\Tests\\": "packages/auth/tests",
             "Tempest\\Cache\\Tests\\": "packages/cache/tests",
             "Tempest\\Clock\\Tests\\": "packages/clock/tests",

packages/ai/.gitattributes

@@ -0,0 +1,14 @@
+# Exclude build/test files from the release
+.github/                  export-ignore
+tests/                    export-ignore
+.gitattributes            export-ignore
+.gitignore                export-ignore
+phpunit.xml               export-ignore
+README.md                 export-ignore
+
+# Configure diff output
+*.view.php diff=html
+*.php diff=php
+*.css diff=css
+*.html diff=html
+*.md diff=markdown

packages/ai/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Brent Roose brendt@stitcher.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/ai/composer.json

@@ -0,0 +1,28 @@
+{
+    "name": "tempest/ai",
+    "description": "A component for integrating AI capabilities into Tempest applications.",
+    "license": "MIT",
+    "minimum-stability": "dev",
+    "require": {
+        "php": "^8.4",
+        "tempest/container": "dev-main",
+        "tempest/http-client": "dev-main",
+        "tempest/support": "dev-main"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^12.2.3"
+    },
+    "autoload": {
+        "psr-4": {
+            "Tempest\\AI\\": "src"
+        },
+        "files": [
+            "src/functions.php"
+        ]
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Tempest\\AI\\Tests\\": "tests"
+        }
+    }
+}

packages/ai/src/AIChat.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+interface AIChat
+{
+    /**
+     * Send a simple prompt and get a response.
+     */
+    public function prompt(string $prompt): AIResponse;
+
+    /**
+     * Send multiple messages as a conversation.
+     *
+     * @param AIMessage[] $messages
+     */
+    public function chat(array $messages): AIResponse;
+
+    /**
+     * Set the model to use for this request.
+     */
+    public function withModel(string $model): self;
+
+    /**
+     * Set the temperature for this request.
+     */
+    public function withTemperature(float $temperature): self;
+
+    /**
+     * Set the max tokens for this request.
+     */
+    public function withMaxTokens(int $maxTokens): self;
+
+    /**
+     * Set a system prompt for this request.
+     */
+    public function withSystemPrompt(string $systemPrompt): self;
+
+    /**
+     * Use a specific AI provider.
+     */
+    public function using(AIProvider $provider): self;
+}

packages/ai/src/AIChatInitializer.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+use Tempest\AI\Driver\AnthropicDriver;
+use Tempest\AI\Driver\OpenAIDriver;
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+use Tempest\HttpClient\HttpClient;
+
+final class AIChatInitializer implements Initializer
+{
+    #[Singleton]
+    public function initialize(Container $container): AIChat|GenericAIChat
+    {
+        $config = $container->get(AIConfig::class);
+        $httpClient = $container->get(HttpClient::class);
+
+        $chat = new GenericAIChat($config);
+
+        // Register available drivers
+        $chat->addDriver(new OpenAIDriver($httpClient, $config));
+        $chat->addDriver(new AnthropicDriver($httpClient, $config));
+
+        return $chat;
+    }
+}

packages/ai/src/AIConfig.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+use Tempest\AI\Config\AnthropicConfig;
+use Tempest\AI\Config\OpenAIConfig;
+
+final class AIConfig
+{
+    public function __construct(
+        public AIProvider $defaultProvider = AIProvider::OPENAI,
+        public ?OpenAIConfig $openai = null,
+        public ?AnthropicConfig $anthropic = null,
+        public ?string $defaultModel = null,
+        public float $defaultTemperature = 0.7,
+        public int $defaultMaxTokens = 1024,
+    ) {
+        $this->openai ??= new OpenAIConfig();
+        $this->anthropic ??= new AnthropicConfig();
+    }
+}

packages/ai/src/AIConfigInitializer.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+use Tempest\Container\Container;
+use Tempest\Container\Initializer;
+use Tempest\Container\Singleton;
+
+final class AIConfigInitializer implements Initializer
+{
+    #[Singleton]
+    public function initialize(Container $container): AIConfig
+    {
+        return new AIConfig();
+    }
+}

packages/ai/src/AIDriver.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+interface AIDriver
+{
+    /**
+     * Send messages to the AI provider and get a response.
+     *
+     * @param AIMessage[] $messages
+     */
+    public function chat(
+        array $messages,
+        ?string $model = null,
+        ?float $temperature = null,
+        ?int $maxTokens = null,
+    ): AIResponse;
+
+    /**
+     * Get the provider this driver handles.
+     */
+    public function getProvider(): AIProvider;
+}

packages/ai/src/AIMessage.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+final readonly class AIMessage
+{
+    public function __construct(
+        public MessageRole $role,
+        public string $content,
+    ) {}
+
+    public static function system(string $content): self
+    {
+        return new self(MessageRole::SYSTEM, $content);
+    }
+
+    public static function user(string $content): self
+    {
+        return new self(MessageRole::USER, $content);
+    }
+
+    public static function assistant(string $content): self
+    {
+        return new self(MessageRole::ASSISTANT, $content);
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'role' => $this->role->value,
+            'content' => $this->content,
+        ];
+    }
+}

packages/ai/src/AIProvider.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+enum AIProvider: string
+{
+    case OPENAI = 'openai';
+    case ANTHROPIC = 'anthropic';
+}

packages/ai/src/AIResponse.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI;
+
+final readonly class AIResponse
+{
+    public function __construct(
+        public string $content,
+        public ?string $model = null,
+        public ?int $promptTokens = null,
+        public ?int $completionTokens = null,
+        public ?int $totalTokens = null,
+        public ?string $finishReason = null,
+        public array $raw = [],
+    ) {}
+
+    public function __toString(): string
+    {
+        return $this->content;
+    }
+}

packages/ai/src/Attribute/AIHandler.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI\Attribute;
+
+use Attribute;
+
+/**
+ * Mark a method as an AI-powered handler.
+ *
+ * The method's return type and docblock will be used to instruct the AI
+ * on how to structure the response.
+ *
+ * Usage:
+ * ```php
+ * #[AIHandler]
+ * public function summarize(string $text): string
+ * {
+ *     return $this->ai->prompt("Summarize: {$text}")->content;
+ * }
+ * ```
+ */
+#[Attribute(Attribute::TARGET_METHOD)]
+final readonly class AIHandler
+{
+    public function __construct(
+        public ?string $model = null,
+        public ?float $temperature = null,
+        public ?int $maxTokens = null,
+    ) {}
+}

packages/ai/src/Attribute/CacheAIResponse.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI\Attribute;
+
+use Attribute;
+
+/**
+ * Cache AI responses to avoid redundant API calls.
+ *
+ * Usage:
+ * ```php
+ * #[CacheAIResponse(ttl: 3600)]
+ * public function getFactAbout(string $topic): string
+ * {
+ *     return $this->ai->prompt("Give me a fact about {$topic}")->content;
+ * }
+ * ```
+ */
+#[Attribute(Attribute::TARGET_METHOD)]
+final readonly class CacheAIResponse
+{
+    public function __construct(
+        /** Time to live in seconds */
+        public int $ttl = 3600,
+        /** Custom cache key prefix */
+        public ?string $key = null,
+    ) {}
+}

packages/ai/src/Attribute/JsonOutput.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tempest\AI\Attribute;
+
+use Attribute;
+
+/**
+ * Request structured JSON output from the AI.
+ *
+ * Usage:
+ * ```php
+ * #[JsonOutput]
+ * public function getColors(): array
+ * {
+ *     $response = $this->ai->prompt('List 3 primary colors with hex codes');
+ *     return json_decode($response->content, true);
+ * }
+ * ```
+ *
+ * With schema:
+ * ```php
+ * #[JsonOutput(schema: ['name' => 'string', 'hex' => 'string'])]
+ * public function getColor(): array
+ * ```
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_PARAMETER)]
+final readonly class JsonOutput
+{
+    public function __construct(
+        public ?array $schema = null,
+    ) {}
+}