Skip to content

README.md

Latest commit

 

History

History
501 lines (395 loc) · 14.5 KB

README.md

File metadata and controls

501 lines (395 loc) · 14.5 KB

🧠 SYMindX - Next-Generation AI Agent Framework

License: MIT TypeScript React Bun AI SDK

Build intelligent AI agents with skill-based architecture, emotional awareness, and enterprise-grade security

Documentation • Quick Start • Features • Architecture • API Reference

✨ Overview

SYMindX is a production-ready AI agent framework that creates intelligent agents with emotional awareness, persistent memory, and multi-platform capabilities. Built with a modular skill-based architecture and powered by AI SDK v5, agents provide sophisticated responses through a reactive design pattern.

Current Version: v2.1.0 - Major architectural refactoring with enhanced security and skill-based extensions

🏗️ Architecture

🎯 Skill-Based Extension System

SYMindX now features a revolutionary skill-based architecture where each extension is composed of specialized skills:

Extensions/
├── 💬 Slack Extension
│   ├── Messaging Skill
│   ├── Channel Management Skill
│   ├── Thread Management Skill
│   ├── Reaction Management Skill
│   └── Workspace Management Skill
│
├── 🐦 Twitter Extension
│   ├── Tweet Skill
│   ├── Engagement Skill
│   ├── Analytics Skill
│   ├── Relationship Skill
│   └── Trends Skill
│
├── 📱 Telegram Extension
│   ├── Direct Messaging Skill
│   ├── Group Management Skill
│   ├── Content Sharing Skill
│   ├── Community Building Skill
│   └── Moderation Skill
│
├── 🎮 RuneLite Extension
│   ├── Skill Trainer
│   ├── Quest Manager
│   ├── Economic Manager
│   ├── PvP Manager
│   └── Social Manager
│
└── 🔌 MCP Server Extension
    ├── Agent Communication Skill
    └── Memory Management Skill

📁 Project Structure

symindx/
├── 🎯 .kiro/                    # Architecture & Steering Documents
│   ├── specs/                   # Technical specifications
│   │   └── symindx-architecture-cleanup/
│   │       ├── design.md       # Architectural design decisions
│   │       ├── requirements.md # System requirements
│   │       └── tasks.md        # Implementation tasks
│   └── steering/               # Project governance
│       ├── product.md          # Product vision & roadmap
│       ├── structure.md        # Organizational structure
│       └── tech.md            # Technical strategy
│
├── 🧠 mind-agents/             # Core Agent Runtime
│   ├── src/
│   │   ├── 🏗️ core/           # Core Systems
│   │   │   ├── runtime.ts      # Main orchestrator
│   │   │   ├── registry.ts     # Enhanced type-safe registry
│   │   │   ├── event-bus.ts    # Improved event system
│   │   │   ├── activity-scheduler.ts # New activity system
│   │   │   ├── cross-platform-learning-engine.ts
│   │   │   ├── goal-management-system.ts
│   │   │   ├── unified-context-system.ts
│   │   │   └── 🛡️ security/   # Enterprise Security
│   │   │       ├── jwt-auth.ts
│   │   │       ├── https-server.ts
│   │   │       ├── input-validator.ts
│   │   │       ├── config-manager.ts
│   │   │       └── secure-server-example.ts
│   │   │
│   │   ├── 🧩 modules/         # AI Modules
│   │   │   ├── 💾 memory/      # Memory Providers
│   │   │   │   ├── agentic-rag-provider.ts # NEW RAG provider
│   │   │   │   └── providers/
│   │   │   ├── 🎭 emotion/     # Streamlined Emotions
│   │   │   │   ├── happy/
│   │   │   │   ├── sad/
│   │   │   │   ├── angry/
│   │   │   │   ├── confident/
│   │   │   │   └── neutral/
│   │   │   └── 🧠 cognition/   # Enhanced Cognition
│   │   │       └── enhanced-unified-cognition.ts
│   │   │
│   │   ├── 🔌 extensions/      # Skill-Based Extensions
│   │   │   ├── 💬 slack/       # Full Slack integration
│   │   │   │   └── skills/
│   │   │   ├── 🐦 twitter/     # Twitter bot with skills
│   │   │   │   └── skills/
│   │   │   ├── 📱 telegram/    # Enhanced Telegram
│   │   │   │   └── skills/
│   │   │   ├── 🎮 runelite/    # Game integration
│   │   │   │   ├── skills/
│   │   │   │   └── communication/
│   │   │   ├── 💬 communication/ # Context management
│   │   │   │   └── skills/
│   │   │   └── 🔌 mcp-server/  # MCP with skills
│   │   │       └── skills/
│   │   │
│   │   ├── 🌐 portals/         # Streamlined AI Providers
│   │   │   ├── streamlined-portal-manager.ts
│   │   │   └── [15+ AI providers]
│   │   │
│   │   └── 📊 types/           # Comprehensive Type System
│   │       └── Enhanced type definitions
│   │
│   └── 📝 scripts/             # Build & Utility Scripts
│       ├── simple-build.ts/cjs/js
│       └── webpack-optimized-build.js
│
├── 🌐 website/                 # React Dashboard
└── 📦 package.json            # Monorepo configuration

🚀 Quick Start

Prerequisites

  • Bun (recommended) or Node.js 18+
  • At least one AI provider API key (OpenAI, Anthropic, Groq, etc.)

Installation

# Clone the repository
git clone https://github.com/SYMBaiEX/symindx.git
cd symindx

# Install dependencies
bun install

# Copy configuration
cp mind-agents/src/core/config/runtime.example.json mind-agents/src/core/config/runtime.json

Configuration

Edit mind-agents/src/core/config/runtime.json with your API keys:

{
  "portals": {
    "apiKeys": {
      "openai": "sk-...",
      "groq": "gsk_...",
      "anthropic": "sk-ant-...",
      "google": "your-google-api-key"
    },
    "default": "groq",
    "models": {
      "chat": "llama-3.3-70b-versatile",
      "tools": "llama-3.3-70b-versatile"
    }
  }
}

Running

# Start the agent system
bun start

# Development mode (with auto-reload)
bun dev

# Interactive CLI
bun cli

# Web dashboard
bun dev:website

🎯 Key Features

🏗️ Skill-Based Architecture

  • Modular Skills: Each extension composed of specialized, reusable skills
  • Skill Manager: Centralized skill orchestration and lifecycle management
  • Base Skill Classes: Standardized interfaces for consistent behavior
  • Hot-swappable Skills: Add/remove skills without system restart

🛡️ Enterprise Security

  • JWT Authentication: Secure token-based auth system
  • HTTPS Server: Production-ready secure server implementation
  • Input Validation: Comprehensive request validation
  • Config Management: Secure configuration handling
  • Rate Limiting: Built-in rate limiting and DDoS protection

🎭 Streamlined Emotion System

  • Core Emotions: Happy, Sad, Angry, Confident, Neutral
  • Composite Management: Advanced emotion blending and transitions
  • Context-Aware: Emotions influenced by conversation context
  • Skill Integration: Emotions affect skill execution

🧠 Enhanced Cognition

  • Unified Architecture: Single, powerful cognition system
  • Context Integration: Deep context awareness across all operations
  • Learning Engine: Cross-platform learning capabilities
  • Goal Management: Hierarchical goal planning and execution

💾 Advanced Memory

  • Agentic RAG: New Retrieval-Augmented Generation provider
  • Multi-Provider: SQLite, PostgreSQL, Supabase, Neon support
  • Vector Search: Semantic memory capabilities
  • Context Preservation: Long-term conversation memory

🔌 Production Extensions

Slack Integration 💬

  • Channel and workspace management
  • Thread-based conversations
  • Reaction handling
  • Rich message formatting

Twitter Bot 🐦

  • Tweet composition and scheduling
  • Engagement tracking and analytics
  • Relationship management
  • Trend analysis

Telegram Bot 📱

  • Group management and moderation
  • Content sharing with rich media
  • Community building tools
  • Direct messaging with personality

RuneLite Integration 🎮

  • Skill training automation
  • Quest assistance
  • Economic analysis
  • PvP strategies
  • Social features

Communication System 💬

  • Context management across platforms
  • Expression engine for natural responses
  • Style adaptation per platform
  • Response enhancement

🌐 Streamlined Portal System

  • Unified Manager: Single point of control for all AI providers
  • 15+ Providers: OpenAI, Anthropic, Groq, Google, XAI, and more
  • Automatic Failover: Seamless provider switching on errors
  • Performance Monitoring: Track provider performance and costs

🔧 Development

Development Commands

# Root level commands
bun dev              # Start development environment
bun build            # Build all components
bun test             # Run test suite
bun lint             # Run linting
bun typecheck        # TypeScript checking

# Component-specific
bun dev:agent        # Agent system only
bun dev:website      # Dashboard only
bun build:agent      # Build agent system
bun build:website    # Build dashboard

Creating Custom Skills

// 1. Create skill class
export class MyCustomSkill extends BaseSkill {
  async execute(context: SkillContext): Promise<SkillResult> {
    // Skill implementation
  }
}

// 2. Register with extension
extension.skillManager.registerSkill('mySkill', new MyCustomSkill());

// 3. Use in agent responses
agent.useSkill('mySkill', { parameters });

Creating Custom Extensions

// 1. Create extension directory
src/extensions/my-extension/
├── index.ts         # Extension entry point
├── package.json     # Extension metadata
├── skills/          # Extension skills
│   ├── index.ts
│   └── my-skill.ts
└── types.ts         # Type definitions

// 2. Implement extension
export class MyExtension implements Extension {
  private skillManager: SkillManager;
  
  async init(agent: Agent): Promise<void> {
    this.skillManager = new SkillManager(agent);
    // Register skills
  }
}

// 3. Auto-discovery handles registration!

📊 API Reference

Core APIs

// Agent Management
const agent = await runtime.createAgent({
  character: 'nyx',
  memory: { type: 'sqlite' },
  emotion: { type: 'composite' },
  cognition: { type: 'unified' }
});

// Skill Execution
const result = await agent.executeSkill('tweet', {
  content: 'Hello from SYMindX!',
  media: ['image.png']
});

// Context Management
const context = await agent.getContext();
context.addMemory('user_preference', preference);

REST Endpoints

GET  /api/agents              # List all agents
POST /api/agents              # Create new agent
GET  /api/agents/:id          # Get agent details
POST /api/agents/:id/chat     # Send message
GET  /api/agents/:id/skills   # List agent skills
POST /api/agents/:id/skills/:skillId  # Execute skill
GET  /api/system/health       # System health
GET  /api/system/metrics      # Performance metrics

WebSocket Events

// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8000/ws');

// Listen for events
ws.on('message', (data) => {
  const event = JSON.parse(data);
  switch(event.type) {
    case 'agent_message':
    case 'skill_executed':
    case 'emotion_changed':
    case 'goal_completed':
      // Handle events
  }
});

🧪 Testing

Test Structure

# Unit tests
bun test:unit        # Fast unit tests

# Integration tests  
bun test:integration # Full integration tests

# Skill tests
bun test:skills      # Test individual skills

# Security tests
bun test:security    # Security validation

# Performance tests
bun test:performance # Performance benchmarks

Coverage Requirements

  • Unit Tests: 80% minimum
  • Integration Tests: 70% minimum
  • Critical Paths: 95% minimum
  • Security Tests: 100% required

🚀 Deployment

Production Configuration

# Environment variables
NODE_ENV=production
LOG_LEVEL=info
PORT=8000

# Security
JWT_SECRET=your-secret-key
HTTPS_CERT=/path/to/cert.pem
HTTPS_KEY=/path/to/key.pem

# Database
DATABASE_URL=postgresql://user:pass@host/db

# AI Providers (configure multiple for failover)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...

Docker Deployment

# Build image
docker build -t symindx:latest .

# Run container
docker run -d \
  -p 8000:8000 \
  -v ./data:/app/data \
  --env-file .env \
  symindx:latest

Scaling Considerations

  • Horizontal Scaling: Agent instances can be distributed
  • Load Balancing: Built-in support for multiple instances
  • Caching: Redis support for distributed caching
  • Message Queue: RabbitMQ/Kafka for event distribution

🤝 Contributing

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

Development Process

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Implement with tests
  4. Ensure all tests pass (bun test)
  5. Submit pull request

Code Standards

  • TypeScript strict mode enforced
  • Comprehensive JSDoc comments
  • Unit tests for all new features
  • Follow existing patterns

📄 License

MIT License - see LICENSE file for details.

Build the future of AI agents with skill-based architecture!

Get Started • Documentation • API Reference • Contributing

SYMindX v2.1.0 | Skill-Based Architecture | Enterprise Security | Production Ready