README_SPACE.md

---
title: Mindfull AI Wellness Companion
emoji: 🧠
colorFrom: blue
colorTo: slate
sdk: gradio
sdk_version: "5.35.0"
app_file: app.py
pinned: false
license: mit
short_description: Talking-head AI wellness companion. Upload any portrait image.
tags:
  - mental-health
  - wellness
  - avatar
  - tts
  - talking-head
---

# 🧠 Mindfull – AI Wellness Companion

A talking-head AI wellness chatbot. Upload **any portrait image** as the avatar, type your message, and get a spoken video response.

## How it works

| Step | Component | Notes |
|------|-----------|-------|
| 1 – LLM | Ollama (local) or HF Inference API | `mistralai/Mistral-7B-Instruct-v0.3` on Spaces |
| 2 – TTS | `edge-tts` (Microsoft Neural voices) | No GPU needed |
| 3 – Video | SadTalker + Wav2Lip | GPU Space recommended; tick *Skip video* for audio-only |

## Running locally

```bash
git clone https://huggingface.co/spaces/<your-username>/mindfull
cd mindfull
python -m venv venv && venv\Scripts\activate   # Windows
pip install -r requirements_hf.txt
# optionally start Ollama: ollama run mindfull
python app.py
```

## Environment variables (Spaces Secrets)

| Variable | Purpose | Required |
|----------|---------|----------|
| `HF_TOKEN` | HF Inference API token for LLM | Yes (on Spaces) |
| `OLLAMA_MODEL` | Override Ollama model name | No |

## Notes

- Video generation requires SadTalker checkpoints to be present (`sadtalker+wav2lip/sadtalker/checkpoints/`).  
  On a CPU-only Space, tick **Skip video** to get text + audio responses instantly.  
- The trained voice is a fixed neural voice (`en-US-GuyNeural`).  
  Swapping voices is trivial – change `EDGE_TTS_VOICE` in `simple_audio_gen.py`.