@phantasy/sheesh-agent/README.md

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

# Sheesh Agent Framework

<p align="center">
  <img src="https://sheesh.sh/logo.png" alt="Sheesh Logo" width="200" />
</p>

<p align="center">
  <strong>AI Agent Framework for real-time broadcasting and multi-provider support</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@phantasy/sheesh-agent"><img src="https://img.shields.io/npm/v/@phantasy/sheesh-agent.svg" alt="npm version"></a>
  <a href="https://github.com/phantasy-bot/sheesh-agent/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@phantasy/sheesh-agent.svg" alt="license"></a>
  <a href="https://github.com/phantasy-bot/sheesh-agent/actions"><img src="https://github.com/phantasy-bot/sheesh-agent/workflows/CI/badge.svg" alt="build status"></a>
  <a href="https://discord.gg/sheesh"><img src="https://img.shields.io/discord/1234567890?label=discord" alt="discord"></a>
</p>

## ✨ 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

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

## 🚀 Quick Start

### 1. Initialize a new project

```bash
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:

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

### 3. Run your agent

```bash
# 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

```javascript
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

```javascript
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

```javascript
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

```bash
# 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

```env
# 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

```javascript
// 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

```bash
# 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](CONTRIBUTING.md) for details.

### Quick Guidelines

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

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🔗 Links

- [Documentation](https://docs.sheesh.sh)
- [Examples](https://github.com/phantasy-bot/sheesh-agent/tree/main/examples)
- [Discord Community](https://discord.gg/sheesh)
- [Twitter](https://twitter.com/sheesh_sh)

## 🙏 Acknowledgments

Built with ❤️ by the Sheesh team and contributors.

Special thanks to all our [contributors](https://github.com/phantasy-bot/sheesh-agent/graphs/contributors)!