test-ai-kit-package-dan

v0.3.0

Published

a month ago

Embeddable AI assistant UI for VeChain dApps

0High
0Medium
0Low

agilulfo

vechain ai assistant chat web3 react

@vechain/ai-kit

A production-ready, embeddable AI assistant UI for VeChain dApps. Built with React 18, Chakra UI, TanStack React Query, and Framer Motion.

AI Kit Preview

Features

🤖 Chat Interface - Natural conversation with AI about portfolio, rewards, and blockchain concepts
📊 Insights Tab - Portfolio analytics and metrics at a glance
⚡ Actions Tab - Quick navigation and recommended actions
✨ Selection Explain - Highlight any text on the page to get AI explanations
🎨 Premium UI - Polished web3 dashboard aesthetic with smooth animations
📱 Responsive - Floating panel on desktop, bottom sheet on mobile
♿ Accessible - Full keyboard navigation, ARIA labels, focus trapping

Installation

npm install @vechain/ai-kit
# or
yarn add @vechain/ai-kit
# or
pnpm add @vechain/ai-kit

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install @chakra-ui/react @emotion/react @emotion/styled @tanstack/react-query framer-motion react react-dom

Quick Start

1. Wrap your app with `AiKitProvider`

// app/providers.tsx (Next.js App Router)
'use client';

import { AiKitProvider, MockAiGatewayAdapter } from '@vechain/ai-kit';
import { useRouter } from 'next/navigation';

// Create adapter instance
const adapter = new MockAiGatewayAdapter();

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();

  return (
    <AiKitProvider
      network="mainnet"
      walletAddress="0x..." // From your wallet connection
      onNavigate={(path) => router.push(path)}
      adapter={adapter}
    >
      {children}
    </AiKitProvider>
  );
}

2. Use in your root layout

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

That's it! The AI widget will appear bottom-right on all pages.

Theme Customization

AI Kit's theme system matches VeChain Kit's design. You can customize the appearance via the theme prop:

Default Theme (matches VeChain Kit)

<AiKitProvider
  network="mainnet"
  onNavigate={(path) => router.push(path)}
  adapter={adapter}
  // Default theme matches VeChain Kit exactly
>
  {children}
</AiKitProvider>

Custom Theme Example

<AiKitProvider
  network="mainnet"
  onNavigate={(path) => router.push(path)}
  adapter={adapter}
  theme={{
    // Modal/Panel styling
    modal: {
      backgroundColor: '#1a1a1a',
      border: '1px solid rgba(255, 255, 255, 0.1)',
      backdropFilter: 'blur(20px)',
      borderRadius: '24px',
    },
    // Cards/Surfaces inside the panel
    cards: {
      backgroundColor: '#2a2a2a',
      border: '1px solid rgba(255, 255, 255, 0.08)',
    },
    // Overlay behind the panel
    overlay: {
      backgroundColor: 'rgba(0, 0, 0, 0.6)',
      blur: 'blur(8px)',
    },
    // Button styles
    buttons: {
      primary: {
        backgroundColor: '#ffffff',
        textColor: '#1a1a1a',
      },
      secondary: {
        backgroundColor: '#2a2a2a',
        textColor: 'rgb(223, 223, 221)',
        border: '1px solid rgba(255, 255, 255, 0.08)',
      },
    },
    // Text and accent
    textColor: 'rgb(223, 223, 221)',
    accentColor: '#8B5CF6',
    // Fonts
    fonts: {
      body: 'Inter, system-ui, sans-serif',
      heading: 'Inter, system-ui, sans-serif',
    },
  }}
>
  {children}
</AiKitProvider>

Glass Morphism Effect

For a frosted glass effect (like VeChain Kit with colorful backgrounds):

theme={{
  modal: {
    backgroundColor: 'rgba(21, 21, 21, 0.8)', // Semi-transparent
    backdropFilter: 'blur(20px)',
    border: '1px solid rgba(255, 255, 255, 0.1)',
  },
  overlay: {
    backgroundColor: 'rgba(0, 0, 0, 0.6)',
    blur: 'blur(8px)',
  },
}}

Provider Props

interface AiKitProviderProps {
  // Required
  network: 'mainnet' | 'testnet';
  onNavigate: (path: string) => void;
  adapter: AiGatewayAdapter;
  
  // Optional
  walletAddress?: string;
  getContext?: () => Promise<Record<string, any>>;
  content?: AiKitContentConfig; // Customize suggestions, insights, actions
  theme?: AiKitTheme; // Full theme configuration
  defaultOpen?: boolean;
  hideWidget?: boolean;
  disableSelectionExplain?: boolean;
  queryClient?: QueryClient;
  children: React.ReactNode;
}

Content Configuration

Customize the chat suggestions, insights, and actions for your specific project:

<AiKitProvider
  network="mainnet"
  onNavigate={(path) => router.push(path)}
  adapter={adapter}
  content={{
    // Custom title in header
    title: 'VeWorld AI',
    
    // Welcome message when chat is empty
    welcomeMessage: 'Ask me anything about your VeWorld portfolio!',
    
    // Input placeholder
    inputPlaceholder: 'Ask about your NFTs, tokens, or transactions...',
    
    // Custom suggestion chips
    suggestions: [
      { label: "What's my portfolio worth?", icon: 'wallet' },
      { label: 'Show my NFTs', icon: 'nft' },
      { label: 'Recent transactions', icon: 'activity' },
      { label: 'Explain gas fees', icon: 'help' },
    ],
    
    // Default insights in the Insights tab
    insights: [
      {
        id: 'portfolio',
        title: 'Portfolio Value',
        description: 'Total value across all tokens',
        // Dynamic value - called on render
        getValue: async () => {
          const balance = await fetchBalance();
          return `$${balance.toLocaleString()}`;
        },
        icon: 'portfolio',
        trend: 'up',
        change: '+5.2%',
      },
      {
        id: 'nfts',
        title: 'NFT Count',
        value: '12 NFTs', // Static value
        icon: 'nft',
      },
    ],
    
    // Quick actions in the Actions tab
    actions: [
      { id: 'swap', label: 'Swap Tokens', path: '/swap', icon: 'swap', description: 'Exchange tokens' },
      { id: 'send', label: 'Send', path: '/send', icon: 'send' },
      { id: 'stake', label: 'Stake VET', path: '/stake', icon: 'stake', featured: true },
      { id: 'bridge', label: 'Bridge Assets', path: '/bridge', icon: 'bridge' },
    ],
  }}
>
  {children}
</AiKitProvider>

Available Icons

Providing Context

Use getContext to provide the AI with information about your app:

<AiKitProvider
  // ...
  getContext={async () => ({
    currentRoute: window.location.pathname,
    portfolio: await fetchPortfolio(),
    balances: await fetchBalances(),
  })}
>

Creating a Custom Adapter

Implement the AiGatewayAdapter interface to connect to your AI backend:

import type { AiGatewayAdapter, AiMessageInput, AiMessageResponse } from '@vechain/ai-kit';

class MyAiAdapter implements AiGatewayAdapter {
  async sendMessage(input: AiMessageInput): Promise<AiMessageResponse> {
    const response = await fetch('/api/ai/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(input),
    });
    
    return response.json();
  }
  
  getStatus() {
    return 'connected';
  }
}

const adapter = new MyAiAdapter();

Response Format

interface AiMessageResponse {
  reply: string;                    // AI response text (supports markdown)
  suggestions?: string[];           // Follow-up prompt suggestions
  actions?: {                       // Navigation actions
    label: string;
    path: string;
    icon?: string;
    description?: string;
  }[];
  insights?: {                      // Portfolio insights
    title: string;
    value: string;
    description?: string;
    trend?: 'up' | 'down' | 'neutral';
    change?: string;
  }[];
}

Hooks

`useAiKit`

Access AI Kit functionality from any component:

import { useAiKit } from '@vechain/ai-kit';

function MyComponent() {
  const {
    openPanel,
    closePanel,
    togglePanel,
    sendMessage,
    messages,
    isLoading,
    connectionStatus,
    activeTab,
    setActiveTab,
  } = useAiKit();

  return (
    <button onClick={() => sendMessage('Analyze my portfolio')}>
      Analyze
    </button>
  );
}

`useSelectionExplain`

Programmatically trigger selection explanations:

import { useSelectionExplain } from '@vechain/ai-kit';

function MyComponent() {
  const { explain, getSelectedText } = useSelectionExplain();

  return (
    <button onClick={() => explain('What is staking?')}>
      Explain Staking
    </button>
  );
}

Theme Customization

Override theme tokens to match your brand:

<AiKitProvider
  themeOverrides={{
    accentColor: '#8B5CF6',
    panelBackground: 'rgba(17, 17, 27, 0.95)',
    textColor: '#E4E4E7',
    borderRadius: '16px',
    fontFamily: '"Inter", sans-serif',
  }}
>

Components

All components are exported for custom layouts:

import {
  AiWidget,       // Floating orb button
  AiPanel,        // Main panel with tabs
  ChatView,       // Chat messages and input
  InsightsView,   // Portfolio insights cards
  ActionsView,    // Action buttons
} from '@vechain/ai-kit';

Accessibility

Full keyboard navigation
ESC key closes the panel
Focus trapping when panel is open
ARIA labels on all interactive elements
Respects prefers-reduced-motion

Browser Support

Chrome 90+
Firefox 90+
Safari 14+
Edge 90+

Development

# Install dependencies
pnpm install

# Build library
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@vechain/ai-kit

Features

Installation

Peer Dependencies

Quick Start

1. Wrap your app with AiKitProvider

2. Use in your root layout

Theme Customization

Default Theme (matches VeChain Kit)

Custom Theme Example

Glass Morphism Effect

Provider Props

Content Configuration

Available Icons

Providing Context

Creating a Custom Adapter

Response Format

Hooks

useAiKit

useSelectionExplain

Theme Customization

Components

Accessibility

Browser Support

Development

License

1. Wrap your app with `AiKitProvider`

`useAiKit`

`useSelectionExplain`