Implement AI Provider Configuration & Loader for Vercel AI SDK Integration

[Copilot]

This PR implements the AI provider configuration and loader functionality requested in issue #37, providing a complete solution for integrating multiple AI providers with the SuperDapp Agents SDK.

Problem

The releases/v1.1.0 branch contained a basic AI scaffold with placeholder implementations for generateText(), streamText(), and runAgent() functions. These were designed to eventually integrate with real AI providers through the Vercel AI SDK, but the critical loadModel() function that maps environment variables to actual AI models was missing.

Solution

This PR adds a comprehensive AI provider configuration system that:

Core Functionality

loadModel() Function: The centerpiece that loads and configures AI model instances from environment variables or programmatic configuration:

import { loadModel } from '@superdapp/agents';

// Load from environment variables
const model = await loadModel();

// Or configure programmatically  
const model = await loadModel({
  provider: 'openai',
  model: 'gpt-4',
  apiKey: 'sk-your-key',
  baseUrl: 'https://api.custom.com' // Optional
});

Multi-Provider Support: Seamlessly integrates with three major AI providers:

• OpenAI: GPT-4, GPT-3.5, and other OpenAI models
• Anthropic: Claude 3 Sonnet, Opus, and Haiku models
• Google: Gemini Pro and other Google AI models

Environment Variable Configuration: Reads standard environment variables:

AI_PROVIDER=openai          # Provider: openai, anthropic, or google
AI_MODEL=gpt-4             # Model name
AI_API_KEY=sk-your-key     # API key for the provider
AI_BASE_URL=https://...    # Optional: Custom API base URL

Technical Implementation

Provider Mapping: Dynamically imports and configures the appropriate AI SDK packages:

• openai → @ai-sdk/openai
• anthropic → @ai-sdk/anthropic
• google → @ai-sdk/google

Model Wrapping: All models are wrapped with aisdk() from @openai/agents-extensions for compatibility with the Agents SDK.

Comprehensive Error Handling: Custom AIConfigError class provides specific error codes and helpful messages:

• INVALID_CONFIG: Missing or invalid configuration
• UNSUPPORTED_PROVIDER: Provider not supported
• PROVIDER_LOAD_ERROR: Failed to load AI SDK package

Integration with Existing Scaffold

This implementation perfectly complements the existing AI scaffold by providing the missing functionality that the placeholder functions were designed to use. The integration is seamless and backward-compatible:

import { SuperDappAgent, loadModel } from '@superdapp/agents';
import { generateText } from 'ai';

const agent = new SuperDappAgent(config);
const model = await loadModel();

agent.addCommand('/ask', async (message, replyMessage, roomId) => {
  const { text } = await generateText({
    model,
    prompt: userQuery,
  });
  await agent.sendConnectionMessage(roomId, text);
});

Changes Made

• Added src/ai/config.ts: Core implementation with loadModel(), loadAIConfig(), and error handling
• Updated src/ai/index.ts: Export new configuration functions while maintaining existing API
• Added comprehensive tests: 24 new tests covering all scenarios and edge cases
• Updated package.json: Added required AI SDK dependencies (@ai-sdk/anthropic, @ai-sdk/google)
• Added documentation: Complete usage guide in docs/ai-configuration.md
• Added examples: Practical usage examples in examples/ai-config-example.ts

Testing

• 183 total tests pass (including 24 new tests specifically for AI configuration)
• Comprehensive coverage of all providers, error scenarios, and edge cases
• Integration testing validates compatibility with existing AI scaffold
• TypeScript compilation verified with zero errors

Breaking Changes

None. This is a purely additive change that enhances the existing AI scaffold without modifying any existing APIs.

Dependencies

Adds two optional AI SDK packages that users can install as needed:

• @ai-sdk/anthropic for Claude models
• @ai-sdk/google for Gemini models

The core OpenAI support (@ai-sdk/openai) was already present in the releases/v1.1.0 branch.

---

This implementation resolves issue #37 by providing the complete AI provider configuration system that was originally attempted in PR #48, but now properly based from the releases/v1.1.0 branch as requested.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[Copilot]

Pull Request Overview

This PR implements a comprehensive AI provider configuration and loader system for the SuperDapp Agents SDK, enabling seamless integration with multiple AI providers through the Vercel AI SDK. The implementation provides the missing loadModel() function that was previously a placeholder in the AI scaffold.

Key changes include:

• Complete AI provider configuration system with support for OpenAI, Anthropic, and Google providers
• Environment variable and programmatic configuration options
• Comprehensive error handling with specific error codes
• Full test coverage with 24 new tests

Reviewed Changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/ai/index.ts	Exports new AI configuration functions and types
src/ai/config.ts	Core implementation of AI provider configuration and model loading
src/tests/ai/config.test.ts	Comprehensive test suite for AI configuration functionality
package.json	Adds optional AI SDK dependencies for Anthropic and Google providers
examples/ai-config-example.ts	Practical usage examples demonstrating AI configuration
docs/ai-configuration.md	Complete documentation for AI provider configuration