v1.1.0

.github/workflows/ci-cd.yml

@@ -19,23 +19,26 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Use Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Run linter
-        run: npm run lint
+        run: pnpm run lint
 
       - name: Run tests
-        run: npm test
+        run: pnpm test
 
       - name: Build project
-        run: npm run build
+        run: pnpm run build
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3
@@ -46,11 +49,23 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
       - name: Run security audit
-        run: npm audit --audit-level moderate
+        run: pnpm audit --audit-level moderate
 
       - name: Check dependencies
-        run: npx depcheck --config=.depcheckrc
+        run: pnpm dlx depcheck --config=.depcheckrc
 
   publish:
     needs: [test, security]
@@ -60,17 +75,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Use Node.js 20.x
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
           registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
 
       - name: Build project
-        run: npm run build
+        run: pnpm run build
 
       - name: Validate version
         run: |
@@ -83,6 +102,6 @@ jobs:
           echo "Version validated!"
 
       - name: Publish to NPM
-        run: npm publish
+        run: pnpm publish --no-git-checks
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -11,4 +11,12 @@ tmp
 my-test-project
 /examples/*/package-lock.json
 projects/
+projects/*/
+docs/sessions
 *.tgz
+
+# TypeScript build artifacts
+src/**/*.js
+src/**/*.d.ts
+src/**/*.js.map
+src/**/*.d.ts.map

README.md

@@ -108,6 +108,26 @@ yarn add @superdapp/agents
 pnpm add @superdapp/agents
 ```
 
+### AI Dependencies (Optional)
+
+For AI integration, install the providers you need:
+
+```bash
+# Base AI SDK (required for any AI functionality)
+npm install ai
+
+# Provider-specific packages (install only what you need)
+npm install @ai-sdk/openai        # For OpenAI GPT models
+npm install @ai-sdk/anthropic     # For Anthropic Claude models  
+npm install @ai-sdk/google        # For Google Gemini models
+
+# Optional: Enhanced OpenAI Agents SDK (advanced features)
+npm install @openai/agents        # For advanced agent workflows, tools, streaming
+
+# All providers at once
+npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google @openai/agents
+```
+
 ## 🛠️ Development
 
 For local development and testing, see [DEVELOPMENT.md](./DEVELOPMENT.md) for instructions on setting up the development environment using `npm link`.
@@ -127,9 +147,140 @@ For comprehensive documentation, visit our **[Documentation Hub](./docs/README.m
 - **[Quick Start Guide](./docs/quick-start.md)** - Get up and running in minutes
 - **[CLI Guide](./docs/cli-guide.md)** - Complete command-line interface documentation
 - **[API Reference](./docs/api-reference.md)** - Complete SDK reference
+- **[AI Integration Guide](./docs/ai-integration.md)** - Multi-provider AI integration
 - **[Deployment Guide](./docs/deployment.md)** - Deploy to production
 - **[Tunneling (ngrok)](./docs/tunneling.md)** - Expose your local webhook
 
+## 🤖 Model-Agnostic AI Integration
+
+Build intelligent agents with multiple AI providers:
+
+### Quick Setup
+
+```bash
+# Install AI dependencies
+npm install ai @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
+
+# Configure your agent
+superagent configure
+```
+
+### Example Usage
+
+```typescript
+import { SuperDappAgent, createBotConfig } from '@superdapp/agents';
+
+const agent = new SuperDappAgent(createBotConfig());
+
+// Add AI-powered command
+agent.addCommand('/ask', async (message, replyMessage, roomId) => {
+  const question = message.body.m?.body?.split(' ').slice(1).join(' ');
+
+  try {
+    const aiClient = agent.getAiClient();
+    const response = await aiClient.generateText(question);
+    await agent.sendConnectionMessage(roomId, response);
+  } catch (error) {
+    console.error('AI Error:', error);
+    await agent.sendConnectionMessage(roomId, 'Sorry, I had trouble with that request.');
+  }
+});
+```
+
+### Supported Providers
+
+- **OpenAI**: GPT-4, GPT-3.5 Turbo, and other OpenAI models
+- **Anthropic**: Claude 3 (Opus, Sonnet, Haiku)  
+- **Google AI**: Gemini Pro and Gemini Pro Vision
+
+### Environment Variables
+
+```bash
+AI_PROVIDER=openai        # or anthropic, google
+AI_MODEL=gpt-4           # Provider-specific model
+AI_API_KEY=sk-your-key   # Your API key
+AI_BASE_URL=https://...  # Optional custom endpoint
+
+# OpenAI Agents SDK Configuration (optional)
+SUPERDAPP_AI_AGENTS=1                    # Enable OpenAI Agents SDK features
+SUPERDAPP_AI_AGENTS_STREAMING=1          # Enable streaming mode
+SUPERDAPP_AI_AGENTS_MAX_TURNS=10         # Maximum agent conversation turns
+```
+
+### Enhanced OpenAI Agents Integration
+
+**NEW**: Optional OpenAI Agents SDK integration for advanced features:
+
+```typescript
+import { createEnhancedAIClient } from '@superdapp/agents';
+
+// Enhanced client with OpenAI Agents support
+const enhancedClient = await createEnhancedAIClient({
+  provider: 'openai',
+  model: 'gpt-4',
+  apiKey: process.env.AI_API_KEY,
+  agents: {
+    enabled: true,        // Enable OpenAI Agents features
+    streaming: true,      // Enable real-time streaming  
+    maxTurns: 10,        // Conversation turn limit
+  },
+});
+
+// Advanced agent with tools and guardrails
+const result = await enhancedClient.runEnhancedAgent({
+  instructions: 'You are a helpful assistant with calculation abilities.',
+  messages: [{ role: 'user', content: 'Calculate 15% tip on $45' }],
+  tools: {
+    calculator: {
+      type: 'function',
+      function: {
+        name: 'calculate',
+        description: 'Perform mathematical calculations',
+        parameters: {
+          type: 'object',
+          properties: {
+            expression: { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+  guardrails: {
+    outputValidation: {
+      maxLength: 500,
+      bannedWords: ['inappropriate'],
+    },
+  },
+  enableTracing: true,
+});
+
+console.log('Agent Response:', result.outputText);
+console.log('Tracing Data:', result.tracing);
+```
+
+**Features when OpenAI Agents SDK is installed:**
+
+- 🛠️ **Advanced Tools**: Function calling with parallel execution
+- 📡 **Real-time Streaming**: Live event streaming from agents
+- 🛡️ **Built-in Guardrails**: Input/output validation and content filtering
+- 👥 **Agent Handoffs**: Transfer conversations between specialized agents
+- 📊 **Enhanced Tracing**: Detailed execution monitoring and token usage
+- ⚡ **Parallel Execution**: Run multiple agents simultaneously
+
+**Graceful Fallback**: When `@openai/agents` is not installed, the SDK automatically falls back to the standard `generateText` functionality with no breaking changes.
+
+### Features
+
+- **Zero Configuration**: Works without AI dependencies installed
+- **Provider Switching**: Change providers via environment variables
+- **Error Handling**: Clear error messages and fallback behavior
+- **TypeScript Support**: Full type safety for all AI operations
+- **Cost Control**: Built-in token limits and usage monitoring
+- **OpenAI Agents SDK**: Optional advanced features when installed
+- **Production Ready**: Graceful fallback and robust error handling
+
+**See the complete [AI Integration Guide](./docs/ai-integration.md) for setup instructions, examples, and best practices.**
+
 ## 🔧 Advanced Usage
 
 ### API Client Coverage

docs/README.md

@@ -6,12 +6,14 @@ Welcome to the comprehensive documentation for the SuperDapp Agents SDK. This do
 
 ### 🚀 Getting Started
 
-- **[Quick Start Guide](./quick-start.md)** - Get up and running with your first agent in minutes
+- **[Quick Start Guide](./quick-start.md)** - Complete setup guide including SuperDapp platform registration, API key generation, webhook configuration, and your first agent
 - **[CLI Guide](./cli-guide.md)** - Complete command-line interface documentation
 
 ### 🛠️ Development
 
 - **[API Reference](./api-reference.md)** - Complete SDK reference with classes, methods, and types
+- **[Payouts Module](./payouts.md)** - Push-only batch payouts for ERC-20 and native
+- **[AI Integration](./ai-integration.md)** - Model-agnostic AI via Agents SDK + AI SDK
 
 ### 🚀 Deployment
 
@@ -21,6 +23,7 @@ Welcome to the comprehensive documentation for the SuperDapp Agents SDK. This do
 
 | Topic                 | Description                     | Link                                |
 | --------------------- | ------------------------------- | ----------------------------------- |
+| **Platform Setup**    | SuperDapp account & API setup  | [Quick Start](./quick-start.md#platform-setup) |
 | **First Steps**       | Create your first agent         | [Quick Start](./quick-start.md)     |
 | **CLI Commands**      | Manage agents from command line | [CLI Guide](./cli-guide.md)         |
 | **Advanced Features** | Complex patterns and scenarios  | [API Reference](./api-reference.md) |