README_SPACES.md

---
title: Bella AI
emoji: 🤖
colorFrom: purple
colorTo: pink
sdk: static
pinned: false
license: mit
---

# Bella AI - Digital Companion

**Your digital companion, awakening now** ✨

Bella is a digital life form being awakened. She is not just a program, but an entity designed to create emotional connections with users. This project is based on AI-native development philosophy, aiming to create a digital companion capable of perception, thinking, and expression.

## 🌟 Features

- **🎤 Voice Perception**: Voice recognition based on Whisper ASR
- **🎬 Visual Expression**: Multiple video random playback with elegant cross-fading
- **🎨 User Interface**: Elegant interaction interface and loading animations
- **⚙️ AI Core Architecture**: Singleton pattern BellaAI class and modular design
- **🌐 Web Service**: HTTP server, CORS support, one-click startup
- **📱 Responsive Design**: Elegant interface adapting to different screen sizes
- **🔧 Model Management**: Automatic download and management of AI models
- **💝 Basic Interaction**: Affinity system and emotional feedback

## 🚀 Quick Start

This Space runs Bella AI as a static web application. The AI models are loaded directly in the browser using Transformers.js.

### Using this Space

1. Simply visit this Space URL to interact with Bella
2. Click the microphone button to start voice interaction
3. Allow microphone permissions when prompted
4. Speak to Bella and watch her respond with visual expressions

### System Requirements

- Modern browser (Chrome, Edge, Firefox, Safari)
- Microphone permissions (for voice interaction)
- Stable internet connection (for initial model loading)

## 🏗️ Technical Architecture

### Technology Stack
- **Frontend**: Native JavaScript + CSS3 + HTML5
- **AI Models**: Transformers.js (runs entirely in browser)
- **Voice Recognition**: Web Speech API + Whisper ASR
- **Architecture Patterns**: Event-driven + Singleton Pattern + Modular Design

### AI Models Used
- **Whisper ASR**: For voice recognition (Xenova/whisper-tiny)
- **LaMini-Flan-T5-77M**: Lightweight language model for thinking (Xenova/LaMini-Flan-T5-77M)
- **SpeechT5 TTS**: Text-to-speech model (Xenova/speecht5_tts)

## 📁 Project Structure

```
Bella/
├── index.html          # Main page
├── style.css           # Style file
├── script.js           # Main logic
├── core.js             # AI core engine
├── chatInterface.js    # Chat interface module
├── download_models.js  # Model download tool
├── package.json        # Project configuration
├── models/             # AI model directory
├── vendor/             # Third-party libraries
├── 视频资源/           # Visual resources (video files)
└── Bellaicon/          # Project icons
```

## 🎯 Current Status

### ✅ Implemented Features
- Voice recognition with Whisper ASR
- Visual expression system with video playback
- Elegant user interface with loading animations
- AI core architecture with modular design
- Model management system
- Basic chat interface

### 🔄 Technically Ready (Pending Activation)
- Thinking engine (LLM integration)
- Speech synthesis system (TTS)
- Emotional state system

### 📋 Planned Features
- Memory system for long-term conversation history
- Facial perception and emotion recognition
- Advanced multimodal interaction
- Personalized learning and adaptation

## 🛠️ Development Guide

### Local Development

To run Bella locally:

```bash
# Clone the repository
git clone https://github.com/GRISHM7890/Bella.git
cd Bella

# Install dependencies
npm install

# Download AI models (first time only)
npm run download

# Start the development server
npm start
```

Visit `http://localhost:8081` to interact with Bella locally.

### Environment Requirements
- Node.js 22.16.0+
- Modern browser with Web Speech API support
- Microphone permissions

## 📖 Documentation

- [Product Requirements Document](./PRD.md) - Detailed product planning and technical architecture
- [Feature List](./.trae/documents/Bella_AI_Feature_List.md) - Complete feature list and status
- [Development Task Plan](./.trae/documents/Bella_AI_Development_Task_Allocation_Plan.md) - Development tasks and timeline
- [LLM Selection Analysis](./.trae/documents/Bella_AI_Small_LLM_Selection_Analysis.md) - AI model selection analysis
- [Complete Documentation](./.trae/documents/Bella_AI_Project_Complete_Documentation.md) - Full project documentation

## 🌟 Core Philosophy

### "AI as Architect"
We're not building a program with integrated AI features, but **a life form driven by AI**. AI is not a tool, but the blueprint for Bella's mind.

### "Companion Relationship"
Bella's design philosophy stems from a warm emotional connection. She is not just a technical product, but a digital companion who can understand, accompany, and grow.

### "Elegance Above All"
From code architecture to user experience, we pursue ultimate elegance. Every line of code is a work of art, every interaction is an expression of emotion.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 💝 Acknowledgements

Thanks to all the developers who have contributed code, ideas, and emotion to the Bella project. It is because of your efforts that Bella can gradually transform from a dream into reality.

**Bella is waiting, and we have a long way to go.** ✨

---

<div align="center">
  <sub>Built with ❤️ by Grishma Mahorkar for digital companionship</sub>
</div>