👻 kwami

An independent, reusable 3D Interactive AI Companion Library for creating engaging AI companions with visual (blob), audio, and AI capabilities.

Version 1.5.12 - Core library for the KWAMI ecosystem

✨ Features

Mind-Body-Soul Architecture

• 🎨 Body - 3D audio-reactive blob with real-time animations and touch interaction
• 🧠 Mind - AI capabilities (TTS, STT, Conversations) with multi-provider support
• 🎭 Soul - Personality system with 10-dimensional emotional intelligence

Key Features

• ✅ Audio-Reactive 3D Blob - Real-time visualization with WebGL
• ✅ Multiple Shader Skins - 3Colors collection (Poles, Donut, Vintage)
• ✅ Interactive Touch Effects - Liquid-like ripples on click
• ✅ Animation States - Idle, listening, thinking, speaking
• ✅ AI Voice Integration - ElevenLabs & OpenAI TTS support
• ✅ ElevenLabs Agents - Full agent management with Tools & Knowledge Base APIs
• ✅ Emotional Personalities - Rich personality system with emotional traits
• ✅ TypeScript First - Fully typed for excellent DX
• ✅ Framework Agnostic - Use with React, Vue, Svelte, or vanilla JS

📦 Installation

npm install kwami
# or
bun add kwami
# or
deno add npm:kwami

🚀 Quick Start

import { Kwami } from "kwami";

const canvas = document.querySelector("canvas") as HTMLCanvasElement;

const kwami = new Kwami(canvas, {
  body: {
    audioFiles: ["/audio/track.mp3"],
    initialSkin: "Poles",
    blob: {
      resolution: 180,
      colors: { x: "#ff0066", y: "#00ff66", z: "#6600ff" },
    },
  },
  mind: {
    provider: "elevenlabs",
    apiKey: "your-api-key",
    voiceId: "your-voice-id",
  },
  soul: {
    name: "Kaya",
    emotionalTraits: {
      happiness: 75,
      empathy: 95,
      energy: 60,
    },
  },
});

// Play audio and animate
await kwami.body.audio.play();

// Speak with AI voice
await kwami.speak("Hello! I am Kwami.");

// Randomize appearance
kwami.body.blob.setRandomBlob();

📚 Documentation

For complete documentation, see the main repository documentation.

Quick Links

• API Reference
• Getting Started Guide
• Architecture Overview
• Mind System
• Body System
• Soul System

🔗 Links

• 🌐 Live Demo: kwami.io
• 📦 npm Package: npmjs.com/package/kwami
• 💻 GitHub: github.com/alexcolls/kwami
• 📚 Full Docs: Main Repository

📄 License

MIT License - See LICENSE for details.

🙏 Credits

Built with THREE.js, simplex-noise, ElevenLabs, and TypeScript.

Made with ❤️ by the KWAMI team

Part of the KWAMI ecosystem - see main repository for all projects.