nimbus-sdk

Nimbus SDK

AI-powered code orchestration with a 3-phase pipeline: Gemini + mgrep → Claude → Claude

Features

• 3-Phase AI Orchestration: Semantic search → Planning → Execution
• mgrep Integration: Semantic code search that's 2x faster than grep
• Streaming Support: Real-time progress updates via Server-Sent Events
• X402 Micropayments: Built-in payment system for AI operations
• TypeScript Native: Full type safety and IntelliSense support
• Flexible Configuration: Customize agents, tools, and workflows

Installation

npm install nimbus-sdk

Quick Start

import { NimbusSDK } from 'nimbus-sdk';

// Initialize the SDK
const sdk = new NimbusSDK({
  sessionId: 'nb_...', // Get from developer dashboard
  walletAddress: '0x...',
  repoUrl: 'https://github.com/user/repo',
  agentConfig: {
    name: 'My AI Agent',
    description: 'AI-powered development assistant'
  }
});

// Initialize (fetches configuration from backend)
await sdk.initialize();

// Execute AI orchestration with streaming
const result = await sdk.orchestrate({
  userGoal: 'Add a dark mode toggle to the settings page',
  context: {
    currentFile: 'src/App.tsx',
    framework: 'React + Tailwind CSS'
  },
  stream: true,
  onStream: (event) => {
    console.log(`Phase: ${event.phase}, Status: ${event.status}`);
    if (event.message) {
      console.log(event.message);
    }
  }
});

// Check results
console.log('Summary:', result.summary);
console.log('Files Changed:', result.filesChanged);
console.log('Actions:', result.actions);

3-Phase Architecture

Phase 1: Data Collection (Gemini + mgrep)

• mgrep semantic search: Natural language code queries (2x faster than grep)
• Gemini 2.0 Flash: Fast, efficient data gathering
• Tools: readFile, runBash, runGrep, runGlob, runGitCommand

Phase 2: Planning (Claude)

• Claude Sonnet 4.5: Advanced reasoning and architecture design
• Outputs: Step-by-step implementation plan with best practices

Phase 3: Execution (Claude)

• Claude Sonnet 4.5: Code generation and file operations
• Tools: writeFile, editFile, installPackage, runGitCommand

API Reference

NimbusSDK

Constructor

new NimbusSDK(config: NimbusSDKConfig)

Config Options:

• sessionId (required): Session ID from developer dashboard (format: nb_...)
• walletAddress (required): User's wallet address
• repoUrl (required): GitHub repository URL
• apiUrl (optional): API base URL (defaults to https://sonnetprotocol.com)
• agentConfig (required): Agent configuration
  • name: Agent name
  • description: Agent description
  • systemPrompt (optional): Custom system prompt
  • tools (optional): Custom tools array
  • brandingConfig (optional): Logo and color customization

Methods

initialize(): Promise<void>

Fetches developer configuration from backend. Call this after construction.

orchestrate(request: OrchestrationRequest): Promise<OrchestrationResult>

Execute 3-phase AI orchestration.

Request:

• userGoal (required): Natural language description of what to accomplish
• context (optional): Additional context
  • currentFile: Currently open file
  • selectedCode: Selected code snippet
  • additionalInfo: Any other relevant info
• stream (optional): Enable streaming (default: false)
• onStream (optional): Callback for stream events

Result:

• success: Whether orchestration succeeded
• summary: Human-readable summary of what was done
• filesChanged: Array of file paths that were modified
• actions: Array of actions performed (type, file, details)
• error (optional): Error message if failed

processIntent(intent: string, walletAddress: string): Promise<ProcessIntentResult>

Legacy method for processing user intents. Use orchestrate() for new implementations.

getPaymentConfig(): PaymentConfig

Get current payment configuration (pricing, revenue split, etc.)

getPricingInfo(): PricingInfo

Get pricing information for display to users.

Examples

With Custom Tools

const sdk = new NimbusSDK({
  sessionId: 'nb_...',
  walletAddress: '0x...',
  repoUrl: 'https://github.com/user/repo',
  agentConfig: {
    name: 'Custom Agent',
    description: 'Agent with custom capabilities',
    tools: [
      {
        name: 'deploy-to-production',
        description: 'Deploy application to production',
        parameters: {
          environment: 'string',
          branch: 'string'
        },
        handler: async (params) => {
          // Custom deployment logic
          return { success: true, url: 'https://app.example.com' };
        }
      }
    ]
  }
});

Non-Streaming Mode

const result = await sdk.orchestrate({
  userGoal: 'Refactor authentication logic to use JWT tokens',
  context: {
    currentFile: 'src/auth/index.ts',
    additionalInfo: 'Use jsonwebtoken library'
  },
  stream: false
});

if (result.success) {
  console.log('Refactoring complete!');
  console.log('Modified files:', result.filesChanged.join(', '));
} else {
  console.error('Error:', result.error);
}

Progress Tracking with Streaming

const result = await sdk.orchestrate({
  userGoal: 'Add user profile page with avatar upload',
  stream: true,
  onStream: (event) => {
    switch (event.phase) {
      case 'data-collection':
        console.log('📚 Gathering context...');
        break;
      case 'planning':
        console.log('🎯 Planning implementation...');
        if (event.message) console.log('  -', event.message);
        break;
      case 'execution':
        console.log('⚡ Executing...');
        if (event.action) {
          console.log(`  - ${event.action}: ${event.file}`);
        }
        break;
      case 'completed':
        console.log('✅ Complete!', event.message);
        break;
    }
  }
});

Pricing

• Test Mode: $0.05 per prompt (single whitelisted wallet)
• Production Mode: $0.10 per prompt (unlimited wallets)
• Revenue Split: 80% developer, 20% protocol

Payment Configuration

The SDK includes built-in X402 micropayments:

const paymentConfig = sdk.getPaymentConfig();
console.log('Price per prompt:', paymentConfig.pricePerPrompt);
console.log('Developer revenue:', paymentConfig.developerFeePercentage + '%');

TypeScript Types

All types are exported for your convenience:

import type {
  NimbusSDK,
  NimbusSDKConfig,
  OrchestrationRequest,
  OrchestrationResult,
  OrchestrationStreamEvent,
  AgentConfig,
  AgentTool,
  PaymentConfig,
  SDKMode
} from 'nimbus-sdk';

Error Handling

try {
  const result = await sdk.orchestrate({
    userGoal: 'Add search functionality'
  });

  if (!result.success) {
    console.error('Orchestration failed:', result.error);
  }
} catch (error) {
  console.error('SDK error:', error);
}

Best Practices

• Always call initialize() after constructing the SDK
• Use streaming for long-running operations to provide user feedback
• Provide context in the context field for better results
• Handle errors gracefully with try-catch and result.success checks
• Test in test mode before switching to production

Development Dashboard

Get your session ID and manage your SDK settings at: https://sonnetprotocol.com/api-docs

Support

• Documentation: https://sonnetprotocol.com/api-docs
• GitHub: https://github.com/dom2icy/claude-on-chain
• Issues: https://github.com/dom2icy/claude-on-chain/issues

License

MIT