MetaRoleWidget

A React component for creating role-based chatbots with SillyTavern compatibility and CCV2 (Character Card V2) specification support.

Features

• 🤖 Complete Chatbot Interface: Full chat UI with message list, input, and send functionality
• 📝 CCV2 Specification Support: Compatible with Character Card V2 format
• 🔌 OpenAI-Compatible APIs: Works with OpenAI and other compatible chat APIs
• 🎨 Modern UI: Beautiful, responsive design with dark mode support
• ⚡ Real-time Streaming: Support for streaming responses
• 🧠 SillyTavern Logic: Built-in prompt building based on SillyTavern's chat completion process
• 📱 Mobile Friendly: Responsive design that works on all devices

Installation

npm install meta-role-widget

Usage

import React from 'react';
import { MetaRoleWidget, CharacterCardV2, ApiConfig } from 'meta-role-widget';

const roleConfig: CharacterCardV2 = {
  spec: 'chara_card_v2',
  spec_version: '2.0',
  data: {
    name: 'AI Assistant',
    description: 'A helpful AI assistant',
    personality: 'Friendly and knowledgeable',
    scenario: 'A casual conversation',
    first_mes: 'Hello! How can I help you today?',
    mes_example: '<START>\n{{user}}: Hi!\n{{char}}: Hello there!\n<END>',
    creator_notes: 'General purpose assistant',
    system_prompt: 'You are a helpful AI assistant.',
    post_history_instructions: 'Continue naturally.',
    alternate_greetings: ['Hi there!', 'Good day!'],
    tags: ['assistant', 'helpful'],
    creator: 'Developer',
    character_version: '1.0',
    extensions: {}
  }
};

const apiConfig: ApiConfig = {
  apiBaseUrl: 'https://api.openai.com/v1',
  apiKey: 'your-api-key-here',
  chatModel: 'gpt-3.5-turbo'
};

export default function Demo() {
  return (
    <MetaRoleWidget
      roleConfig={roleConfig}
      apiConfig={apiConfig}
      style={{ height: 600 }}
    />
  );
}

Notes:

• The widget initializes with the first message from the character card.
• Interactions will call your API based on apiConfig and stream responses.
• Import @chatui/core/dist/index.css is handled inside the component.

Storybook

Run the component in isolation with Storybook:

npm run storybook

This starts Storybook at http://localhost:6006/ with example stories under Components/MetaRoleWidget.

Quick Start

import React from 'react';
import { MetaRoleWidget, CharacterCardV2, ApiConfig } from 'meta-role-widget';

function App() {
  const roleConfig: CharacterCardV2 = {
    spec: 'chara_card_v2',
    spec_version: '2.0',
    data: {
      name: 'AI Assistant',
      description: 'A helpful AI assistant',
      personality: 'Friendly and knowledgeable',
      scenario: 'A casual conversation',
      first_mes: 'Hello! How can I help you today?',
      mes_example: '<START>\n{{user}}: Hi!\n{{char}}: Hello there!\n<END>',
      creator_notes: 'General purpose assistant',
      system_prompt: 'You are a helpful AI assistant.',
      post_history_instructions: 'Continue naturally.',
      alternate_greetings: ['Hi there!', 'Good day!'],
      tags: ['assistant', 'helpful'],
      creator: 'Developer',
      character_version: '1.0',
      extensions: {}
    }
  };

  const apiConfig: ApiConfig = {
    apiBaseUrl: 'https://api.openai.com/v1',
    apiKey: 'your-api-key-here',
    chatModel: 'gpt-3.5-turbo'
  };

  return (
    <MetaRoleWidget
      roleConfig={roleConfig}
      apiConfig={apiConfig}
      onMessageSend={(userMsg, aiResponse) => {
        console.log('Chat:', { userMsg, aiResponse });
      }}
      onError={(error) => {
        console.error('Error:', error);
      }}
      style={{ height: '600px', width: '100%' }}
    />
  );
}

API Reference

MetaRoleWidget Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | roleConfig | CharacterCardV2 | ✅ | Character configuration following CCV2 spec | | apiConfig | ApiConfig | ✅ | API configuration for chat service | | onMessageSend | (userMessage: string, aiResponse: string) => void | ❌ | Callback when messages are sent | | onError | (error: Error) => void | ❌ | Error handling callback | | className | string | ❌ | Additional CSS class | | style | React.CSSProperties | ❌ | Inline styles |

CharacterCardV2

Follows the Character Card V2 specification:

interface CharacterCardV2 {
  spec: 'chara_card_v2';
  spec_version: '2.0';
  data: {
    name: string;
    description: string;
    personality: string;
    scenario: string;
    first_mes: string;
    mes_example: string;
    creator_notes: string;
    system_prompt: string;
    post_history_instructions: string;
    alternate_greetings: string[];
    tags: string[];
    creator: string;
    character_version: string;
    extensions: Record<string, any>;
  };
}

ApiConfig

Simple configuration for OpenAI-compatible APIs:

interface ApiConfig {
  apiBaseUrl: string;  // e.g., 'https://api.openai.com/v1'
  apiKey: string;      // Your API key
  chatModel: string;   // e.g., 'gpt-3.5-turbo'
}

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Type check
npm run type-check

SillyTavern Compatibility

This component implements SillyTavern's chat completion logic:

1. Prompt Building: Constructs prompts using character description, personality, scenario, and example dialogue
2. Message Processing: Handles placeholder replacement ({{char}}, {{user}})
3. Context Management: Manages chat history and system prompts
4. Token Management: Efficient prompt construction for API limits

Styling

The component comes with built-in styles but can be customized:

/* Override default styles */
.meta-role-widget {
  --primary-color: #your-color;
  --background-color: #your-bg;
}

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request