Lucie-AI - GitLite

KO | EN

gitlite — search

#list #python #automation #self-hosted #mcp #framework #github #android #windows #bash

Lucie-AI

(★ 33)

A real-time 2D Live AI companion powered by Groq (LLaMA 3.3 & Whisper) and Live2D Hiyori Pro.

File Explorer

ZIP Download

- - ci.yml
- dependabot.yml
- __init__.py
- audio_utils.py
- config.py
- emotion_engine.py
- groq_client.py
- main.py
- memory.py
- requirements.txt
- tts_engine.py
- - style.css
- - audio-handler.js
  - emotion-animator.js
  - live2d-loader.js
  - main.js
  - ui-controller.js
  - websocket.js
- index.html
.env.example
.gitignore
build.sh
CODE_OF_CONDUCT.md
CONTRIBUTING.md
LICENSE
Procfile
README.md
SECURITY.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`uvicorn`

View Details ▼

Python ASGI HTTP Server, for asynchronous projects.

uvicorn {{import.path:app_object}}

Run Python web app:

uvicorn --host {{localhost}} --port {{8080}} {{import.path:app_object}}

Listen on port 8080 on localhost:

uvicorn --reload {{import.path:app_object}}

Turn on live reload:

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Lucie-AI is a next-generation AI companion that combines state-of-the-art Large Language Models (LLMs) with high-fidelity Live2D animation. It features a real-time, voice-driven interaction system with low-latency responses, expressive emotions, and dynamic physical gestures.

## 🌟 Key Features

- **Live2D Hiyori Pro Integration**: Fully rigged Cubism 4 model with idle motions, blinking, breathing, and head sway.
- **Emotion-Driven Expressivity**: AI-detected emotions (happy, sad, blush, etc.) trigger specific Live2D parameter changes and expressive gestures.
- **Voice-First Interaction**: Real-time audio recording and streaming with Groq Whisper STT and ultra-fast TTS fallback.
- **Intelligent Lip-Sync**: Real-time audio waveform analysis drives the Live2D model's mouth movements for natural speech synchronization.
- **Groq-Powered Intelligence**: Leverages LLaMA 3.3 70B for affectionate, context-aware conversations with persistent memory.
- **Production-Ready Backend**: FastAPI-based architecture with WebSocket support, optimized for deployment on Render.

## 🏗️ Architecture

```mermaid
graph TD
    A[User Browser] -- WebSocket --> B[FastAPI Backend]
    A -- Audio Stream --> B
    B -- Whisper STT --> C[Groq AI]
    C -- LLaMA 3.3 70B --> B
    B -- TTS Engine --> D[Voice Audio]
    B -- Live2D Params --> A
    D -- Audio Stream --> A
    A -- Lip-Sync Analysis --> E[Live2D Model]
```

## 🚀 Quick Start

### Prerequisites

- Python 3.11+
- [Groq API Key](https://console.groq.com/)
- Modern web browser with Microphone access

### Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/vincenzo-afk/Lucie-AI.git
   cd Lucie-AI
   ```

2. **Set up the environment:**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r backend/requirements.txt
   ```

3. **Configure Environment Variables:**
   Create a `.env` file in the root directory:
   ```env
   GROQ_API_KEY=your_groq_api_key_here
   PORT=8000
   ```

4. **Run the application:**
   ```bash
   python -m backend.main
   ```
   Open `http://localhost:8000` in your browser.

## 🛠️ Technical Stack

- **Frontend**: Vanilla ES Modules, PixiJS v8, Live2D Cubism 4 Core.
- **Backend**: FastAPI, Uvicorn, WebSockets.
- **AI/ML**: Groq Cloud (LLaMA 3.3 70B, Whisper-large-v3-turbo).
- **TTS**: edge-tts (Primary), gTTS (Fallback).
- **Deployment**: Render (Free/Starter Tier).

## 📂 Project Structure

- `/backend`: FastAPI application, AI clients, and TTS logic.
- `/frontend`: Web interface, Live2D assets, and animation engine.
- `/frontend/js`: Core animation and communication logic.
- `/frontend/model/Hiyori`: Hiyori Pro Live2D runtime assets.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## 📄 License

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

---
*Created by [vincenzo-afk](https://github.com/vincenzo-afk)*