@phantasy/sheesh-agent

Sheesh Agent Framework

AI Agent Framework for real-time broadcasting and multi-provider support

✨ Features

• 🤖 Multi-Provider AI Support - OpenAI, Maho, Alkahest, Akash with automatic fallback
• 📡 Real-Time Broadcasting - WebSocket-based agent communication
• 🎭 VRM Character Control - Animations, expressions, poses, and gestures
• 🎙️ Text-to-Speech - Multiple voice providers with streaming
• 💎 Tip Management - Goals, milestones, and rewards system
• 📊 Admin Dashboard - Optional real-time monitoring and control
• 🔌 Plugin Architecture - Extensible design for custom features
• 🚀 CLI Tool - Easy agent management and deployment

📦 Installation

npm install @phantasy/sheesh-agent
# or
yarn add @phantasy/sheesh-agent
# or
pnpm add @phantasy/sheesh-agent

🚀 Quick Start

1. Initialize a new project

npx @phantasy/sheesh-agent init

This creates:

• .env file for configuration
• my-agent.js example agent

2. Configure your API keys

Edit .env and add at least one provider:

OPENAI_API_KEY=sk-...
# or
MAHO_API_KEY=...
# or
ALKAHEST_API_KEY=...
# or
AKASH_API_KEY=...

3. Run your agent

# With admin panel
npx @phantasy/sheesh-agent start my-agent.js --admin

# Without admin panel (headless)
npx @phantasy/sheesh-agent start my-agent.js

📖 Usage

Basic Agent

import { AgentController } from '@phantasy/sheesh-agent';
import { createSheeshPlugin } from '@phantasy/sheesh-agent/plugins/sheesh';
import { MahoText } from '@phantasy/sheesh-agent/providers/text/maho';

// Initialize AI provider
const textProvider = new MahoText();
await textProvider.initialize({
  apiKey: process.env.MAHO_API_KEY,
  model: 'gpt-4-turbo'
});

// Create agent controller
const agent = new AgentController({
  providers: { text: textProvider },
  personality: {
    name: 'Assistant',
    traits: ['helpful', 'friendly'],
    tone: 'professional'
  }
});

// Connect to platform
const plugin = createSheeshPlugin({
  partyKitUrl: 'ws://localhost:1999',
  roomId: 'main',
  agentId: 'assistant-001',
  agentName: 'Assistant',
  onUserMessage: async (userId, message) => {
    const response = await agent.processUserMessage(userId, message);
    plugin.broadcastResponse(response);
  }
});

await plugin.initialize();
console.log('Agent is online!');

With VRM Animations

const response = await agent.processUserMessage(userId, message);

// Add animations
response.actions = [
  {
    type: 'vrm',
    action: 'animation',
    value: 'wave',
    duration: 3000
  },
  {
    type: 'vrm',
    action: 'expression',
    value: 'happy',
    duration: 5000
  }
];

plugin.broadcastResponse(response);

With Tip Goals

const agent = new AgentController({
  providers: { text: textProvider },
  personality: { /* ... */ },
  tipGoals: [
    {
      id: 'dance',
      title: 'Unlock Dance',
      targetAmount: 5,
      reward: {
        type: 'animation',
        value: 'special-dance'
      }
    }
  ]
});

// Handle tips
plugin.on('tip:received', async (data) => {
  const goals = await agent.processTip(data.userId, data.amount);
  plugin.updateTipGoals(goals);
});

🛠️ CLI Commands

# Start agent with options
sheesh-agent start <agent-file> [options]
  -a, --admin          Start admin panel
  -p, --admin-port     Admin panel port (default: 8080)
  --no-build          Skip building

# Start only admin panel
sheesh-agent admin [options]
  -p, --port          Port to run on (default: 8080)

# Build framework
sheesh-agent build

# Initialize new project
sheesh-agent init

🔧 Configuration

Environment Variables

# Admin Panel
ADMIN_TOKEN=your-secure-token

# AI Providers (at least one required)
OPENAI_API_KEY=sk-...
MAHO_API_KEY=...
ALKAHEST_API_KEY=...
AKASH_API_KEY=...

# Provider Selection
AI_TEXT_PROVIDER=maho
AI_TTS_PROVIDER=openai

# PartyKit Connection
PARTYKIT_URL=ws://localhost:1999

# Optional
NODE_ENV=development
DEBUG=false

Provider Configuration

// OpenAI
const openai = new OpenAIText();
await openai.initialize({
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4-turbo'
});

// Maho (OpenRouter Alternative)
const maho = new MahoText();
await maho.initialize({
  apiKey: process.env.MAHO_API_KEY,
  baseUrl: 'https://maho.sh/api/v1'
});

// Alkahest (Privacy-focused)
const alkahest = new AlkahestText();
await alkahest.initialize({
  apiKey: process.env.ALKAHEST_API_KEY,
  baseUrl: 'https://alkahest.ai/api/v1'
});

📊 Admin Panel

The optional admin panel provides:

• Real-time agent monitoring
• Feature toggles (broadcasting, TTS, animations)
• Activity logging
• Metrics dashboard
• Remote control capabilities

Access at http://localhost:8080 when running with --admin flag.

🏗️ Architecture

@phantasy/sheesh-agent
├── core/           # Core framework
│   ├── agent-controller.ts
│   └── types.ts
├── providers/      # AI providers
│   ├── text/
│   ├── tts/
│   └── image/
├── services/       # Feature services
│   ├── vrm-integration.ts
│   ├── canvas-integration.ts
│   └── tip-management.ts
├── plugins/        # Plugin system
│   └── sheesh/
└── admin/          # Admin panel

🧪 Development

# Clone repository
git clone https://github.com/phantasy-bot/sheesh-agent.git
cd sheesh-agent

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Development mode
npm run dev

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Guidelines

• Fork the repository
• Create feature branch (git checkout -b feature/amazing)
• Commit changes (git commit -m 'feat: add amazing feature')
• Push to branch (git push origin feature/amazing)
• Open Pull Request

📄 License

MIT License - see LICENSE for details.

🔗 Links

• Documentation
• Examples
• Discord Community
• Twitter

🙏 Acknowledgments

Built with ❤️ by the Sheesh team and contributors.

Special thanks to all our contributors!