ProactiChat 🤖

A proactive AI chat application that engages users with intelligent rules, spontaneous contributions, and socially aware responses. Unlike traditional chatbots that only respond when prompted, ProactiChat actively participates in conversations with contextual insights and reactions.

Features

• Proactive Engagement: AI spontaneously contributes thoughts and observations based on conversation context
• Smart Reactions: Responds to user emoji reactions with social awareness
• Rule-Based System: Multiple intelligent rules for different types of engagement
• Real-time Communication: WebSocket-based chat with connection status indicators
• Responsive UI: Modern React interface with iMessage-style design

Architecture

• Frontend: React + TypeScript + Vite
• Backend: Node.js + Express + WebSocket
• AI: OpenAI GPT-4o integration with contextual prompts
• Rules Engine: Modular system for different types of proactive behavior

Prerequisites

• Node.js 18+
• npm or yarn
• OpenAI API key

Quick Start

1. Clone and Setup

git clone <repository-url>
cd chat-buddy

2. Environment Configuration

Create environment files:

# Backend environment
echo "OPENAI_APIKEY=your_openai_api_key_here" > backend/.env

# Frontend environment (if needed)
echo "VITE_API_URL=http://localhost:3001" > frontend/.env

3. Install Dependencies

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

4. Run Development Mode

# Terminal 1: Start backend
cd backend
npm start

# Terminal 2: Start frontend
cd frontend
npm run dev

The application will be available at:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001

Docker Deployment

Local Development with Docker

# Build and run with docker-compose
docker-compose up --build

# Run in background
docker-compose up -d --build

Access the application:

• Frontend: http://localhost:3000
• Backend: http://localhost:3001

Production Deployment

Option 1: Manual Docker Build

# Build images
docker build -t proactivchat-backend ./backend
docker build -t proactivchat-frontend ./frontend

# Run containers with environment variables
docker run -d -p 3001:3001 \
  -e OPENAI_APIKEY=your_key_here \
  --name proactivchat-backend \
  proactivchat-backend

docker run -d -p 3000:3000 \
  --name proactivchat-frontend \
  proactivchat-frontend

Option 2: Cloud Platform Deployment

Heroku:

# Set environment variable
heroku config:set OPENAI_APIKEY=your_key_here

# Deploy
git push heroku main

Railway/Render/Others:

1. Connect your GitHub repository
2. Set OPENAI_APIKEY in environment variables
3. Deploy automatically

Configuration

Environment Variables

Backend (.env):

OPENAI_APIKEY=your_openai_api_key_here
NODE_ENV=production
PORT=3001

Frontend (.env):

VITE_API_URL=http://localhost:3001

Proactive Behavior Settings

You can adjust the AI's proactive behavior in:

• backend/src/rules/SpontaneousContributionRule.js - Random contributions
• backend/src/rules/AutoReactionRule.js - Emoji reactions
• backend/src/services/contextualAiService.js - AI prompts and behavior

Key parameters:

// Spontaneous contribution frequency
minIntervalMs: 15 * 1000,  // 15 seconds between contributions
shouldContribute: 0.25,    // 25% chance per check

// Maximum contributions per hour
maxExecutions: 8,          // Limit to prevent spam

API Endpoints

WebSocket Connection:

• ws://localhost:3001 - Main chat connection

Message Format:

// Regular message
{ "text": "Hello!" }

// Typing indicator
{ "type": "typing", "isTyping": true }

// AI reaction
{ "type": "ai_reaction", "emoji": "😂", "reason": "funny comment" }

// User reaction
"REACT:👍:messageIndex"

Project Structure

├── backend/
│   ├── src/
│   │   ├── rules/              # Proactive behavior rules
│   │   ├── services/           # AI and chat services
│   │   ├── utils/              # Utility functions
│   │   └── index.js           # Main server
│   ├── Dockerfile
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.tsx            # Main React component
│   │   ├── App.css            # Styling
│   │   └── main.tsx           # Entry point
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
└── README.md

Development

Adding New Rules

1. Create a new rule class in backend/src/rules/
2. Extend the base Rule class
3. Define triggers and execution logic
4. Add to the rules array in index.js

Example:

class MyCustomRule extends Rule {
  constructor(aiService) {
    super("myCustomRule", ["trigger_event"]);
    this.aiService = aiService;
  }

  async execute(event, context) {
    // Your logic here
    return [{ type: "send_message", payload: { text: "Hello!" } }];
  }
}

Customizing AI Behavior

Edit the character prompt in backend/src/services/openAiAdapter.js:

this.characterPrompt = `Your custom AI personality...`;

Troubleshooting

Common Issues:

1. WebSocket Connection Failed

   • Check if backend is running on port 3001
   • Verify firewall settings
   • Check browser console for errors

2. AI Not Responding

   • Verify OPENAI_APIKEY is set correctly
   • Check backend logs for API errors
   • Ensure you have OpenAI API credits

3. No Proactive Messages

   • Check if rules are hitting execution limits
   • Verify conversation has enough context (2+ user messages)
   • Check timer interval settings

4. Rate Limiting

   • OpenAI API has rate limits
   • Reduce proactive behavior frequency
   • Check usage in OpenAI dashboard

License

MIT License - see LICENSE file for details

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Check the troubleshooting section
• Review backend logs for errors
• Open an issue on GitHub