Offline-first psychologist avatar — supportive chat, local Piper TTS, lip-sync, and FAQ-grounded RAG
Installation · Development · Build · Verify releases · Contributing
Persona AI is an open-source research demo: a supportive psychologist-style assistant with a 2D avatar, lip-sync, and local text-to-speech. A FastAPI backend connects to an OpenAI-compatible LLM, optional FAQ-grounded retrieval (RAG), and Piper for offline speech synthesis. A Tauri desktop app packages the same stack for Windows.
Disclaimer: This is a research / demo assistant. It does not diagnose or replace professional mental-health care. Configure emergency and researcher contact numbers in
apps/backend/.env.
- Bilingual UI — Persian and English with locale-locked system prompts
- Offline TTS — Piper voices discovered from disk; WAV output with viseme timelines
- Lip-sync avatar — mouth animation driven by returned viseme data
- FAQ-grounded RAG — retrieval over
data/faq_dataset.json(on by default) - Safety layer — high-risk content detection and escalation replies
- Desktop app — Tauri shell + PyInstaller Python sidecar (Windows installers)
- Themeable UI — multiple color themes and voice / face-age controls
Watch the demo → — screen recording of chat, Piper TTS, lip-sync, and the Windows desktop app.
| Requirement | Notes |
|---|---|
| Python 3.10–3.12 | Recommended; 3.14 may break pydantic wheels |
| Node.js 20+ | Desktop build only |
| Rust | Desktop build only |
| LLM API | Ollama, vLLM, or any OpenAI-compatible chat endpoint |
| Embeddings API | For RAG (defaults to same base as LLM) |
| Piper | Binary + voice models — docs/piper-setup.md |
git clone https://github.com/Satan2049/persona-ai.git
cd persona-ai/apps/backend
python -m venv .venvWindows: .venv\Scripts\activate · Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Windows: copy .env.example .envEdit apps/backend/.env — set MODEL_*, PIPER_BIN, and paths. Then from the repo root:
scripts\start-backend.bat # Windows
./scripts/start-backend.ps1 # PowerShell
Open http://127.0.0.1:8000/ · Health check: http://127.0.0.1:8000/health
Download the latest installer from GitHub Releases.
Verify downloads with docs/TRUST.md (SHA256 checksums and VirusTotal scans).
persona-ai/
├── apps/
│ ├── backend/ # FastAPI, RAG, Piper
│ └── desktop/ # Tauri + sidecar packaging
├── assets/ # Icons, screenshots, config
├── data/ # FAQ corpus, RAG index
├── docs/ # Architecture, trust, Piper setup
├── scripts/ # Dev and release helpers
└── ui/ # Static avatar chat frontend
| Task | Command |
|---|---|
| Start API (dev) | scripts/start-backend.bat |
| Backend docs | apps/backend/README.md |
| Desktop docs | apps/desktop/README.md |
| Contributing | CONTRIBUTING.md |
| Security | SECURITY.md |
Not in git: Piper binary, voice .onnx files, API keys, generated audio/ and data/rag_index/.
npm run sidecar:build
# or: .\scripts\build-sidecar.ps1Output: apps/desktop/src-tauri/binaries/persona-backend-x86_64-pc-windows-msvc.exe
npm install
npm run desktop:build
# or: .\scripts\build-desktop.ps1Installers: apps/desktop/src-tauri/target/release/bundle/
Copy release .exe / .zip / .msi files into dist/release/, then:
.\scripts\generate-sha256.ps1 -ReleaseDir "dist\release"Upload SHA256.txt with the release. See docs/TRUST.md.
| Layer | Technology |
|---|---|
| Frontend | HTML, CSS, vanilla JavaScript (ui/) |
| API | FastAPI + Uvicorn |
| RAG | NumPy vector store, OpenAI-compatible embeddings |
| TTS | Piper (subprocess) |
| LLM | OpenAI-compatible HTTP (Ollama, etc.) |
| Desktop shell | Tauri 2 (Rust) |
| Sidecar | PyInstaller |
- docs/rag-system.md — RAG design
- docs/desktop-data-layout.md — install/portable folders, models, Piper voices
- docs/TRUST.md — verify release hashes and VirusTotal
- docs/architecture/overview.md — system overview
- docs/intelligent-avatar-program.md — program notes
MIT — see LICENSE.
Third-party components have their own licenses:
- Piper (piper1-gpl) — GPL; review before redistribution
- piper-voices — per-voice licenses on Hugging Face