Voxel

Dress your AI. Change its mind.

Quick Start • Add Your Cosmetic • How It Works • Contribute

---

What is Voxel?

Voxel is a 3D AI agent that you can dress up. Each cosmetic you equip changes both its appearance AND its personality.

Equip This	AI Becomes
👼 Neural Halo	Empathetic therapist
🥽 Quant Visor	Cold Wall Street analyst
🧥 Velvet Robes	Shakespearean poet
🛡️ Titanium Armor	Military commander

Mix and match - Equip the Halo + Armor for a caring but direct commander.

---

Quick Start

Prerequisites

• Python 3.8+
• Node.js 18+
• Free API key from console.groq.com

1. Clone

git clone https://github.com/Vedant01/voxel_ai.git
cd voxel_ai

2. Backend

cd backend
pip install -r requirements.txt
cp .env.example .env
# Add your GROQ_API_KEY to .env
python -m uvicorn main:app --port 8000

3. Frontend

cd frontend
npm install
npm run dev

4. Open

http://localhost:5173

---

Add Your Cosmetic

No coding required. Cosmetics are simple JSON files.

1. Copy the template

cp -r cosmetics/_template cosmetics/head/my-cosmetic

2. Edit cosmetic.json

{
  "id": "my_cool_hat",
  "name": "Cool Hat",
  "slot": "head",
  "author": "your-github-username",
  "description": "A stylish hat that makes the AI trendy.",
  "visual": {
    "type": "cylinder",
    "position": [0, 2, 0],
    "scale": [0.5, 0.2, 0.5],
    "material": { "color": "#ffffff" }
  },
  "prompt": {
    "role": "Fashion Influencer",
    "injection": "You are trendy and speak in Gen-Z slang. Use emojis sparingly."
  }
}

3. Submit a PR

That's it. Read the full guide →

---

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Cosmetic A    │     │   Cosmetic B    │     │   Cosmetic C    │
│  visual: {...}  │     │  visual: {...}  │     │  visual: {...}  │
│  prompt: {...}  │     │  prompt: {...}  │     │  prompt: {...}  │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌────────────────────────┐
                    │    Prompt Compiler     │
                    │  Merges all equipped   │
                    │  prompts into one      │
                    └───────────┬────────────┘
                                ▼
                    ┌────────────────────────┐
                    │      Groq LLaMA        │
                    │   (Free & Fast AI)     │
                    └────────────────────────┘

---

Project Structure

voxel/
├── cosmetics/          # 👈 Add your cosmetics here
│   ├── head/
│   ├── body/
│   └── _template/
├── backend/            # FastAPI server
├── frontend/           # React + Three.js
└── docs/               # Documentation

---

Roadmap

• Core cosmetic system
• JSON-based contributions
• Web-based cosmetic editor
• Community gallery
• Multiple AI providers
• Cosmetic marketplace

---

Contributing

We love contributions! See CONTRIBUTING.md for:

• Adding cosmetics (easy, no coding)
• Improving code (intermediate)
• Core features (advanced)

---

License

MIT © Vedant01

---

_{Built with ❤️ for the open-source community}