System
OS
Windows 11 (primary)
Linux supported
Python
3.13 (asyncio-heavy)
GPU
NVIDIA (CUDA 12+)
More VRAM = bigger models
PyTorch
Nightly cu130
(for sm_120 / RTX 50xx)
RAM
16 GB minimum
32 GB recommended
Disk
20+ GB for models
(GGUF files)
RTX 50xx (Blackwell) users: PyTorch stable does not support sm_120 yet. You must use PyTorch nightly cu130. See Step 2.
git clone https://github.com/isundahl/amina-core-public.git
cd amina-core-public
This is the public mirror. The repo is organized as:
src/ — all Python source modulesmodels/ — place your GGUF model files heredata/ — user profiles and memory stores (auto-created)tests/ — pytest test suite
Windows
python -m venv venv
venv\Scripts\activate
Linux / macOS
python3.13 -m venv venv
source venv/bin/activate
Python 3.13 is required. The asyncio architecture uses features not available in older versions.
PyTorch (CUDA)
For RTX 50xx (Blackwell / sm_120), install the nightly build:
pip install --pre torch torchvision torchaudio \
--index-url https://download.pytorch.org/whl/nightly/cu130
For older NVIDIA cards (RTX 30xx / 40xx):
pip install torch torchvision torchaudio \
--index-url https://download.pytorch.org/whl/cu124
Core Requirements
pip install -r src/requirements.txt
Pinned packages — do NOT freely upgrade:
transformers — pinned to 4.57.x (qwen-tts / nemo dep chain)
numpy — must be < 2.4 (numba compatibility)
llama-cpp-python must be compiled with CUDA support for GPU inference:
set CMAKE_ARGS=-DGGML_CUDA=on
pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python \
--upgrade --force-reinstall --no-cache-dir
For sm_120 (RTX 50xx), you may need to build llama.cpp from source with -DCMAKE_CUDA_ARCHITECTURES=120.
Amina uses GGUF models. Download one from HuggingFace and place it in models/.
Recommended starting points (Q5 quantizations):
- Qwen 3.5 9B — 7 GB VRAM, fast, smart
- Qwen 3.6 27B MoE — 18 GB VRAM, excellent reasoning
- Gemma 4 31B — 22 GB VRAM, best for creative tasks
For vision support, also download a matching mmproj-*.gguf file into models/. Amina auto-detects the correct projector by filename.
Copy the example env file and fill in your values:
cp .env.example .env
Key settings in .env:
DEFAULT_MODEL — filename of the brain model in models/TELEGRAM_BOT_TOKEN — optional, for Telegram messagingTELEGRAM_CHAT_ID — your Telegram user IDSENDGRID_API_KEY — optional, for email outbound
The .env file is gitignored. Never commit it — it contains API keys and personal data.
Windows
.\run.bat
Direct (any platform)
python src/main_service.py
The web UI will be available at http://localhost:8000.
Verify CUDA
python -c "import torch; print(torch.cuda.is_available())"
Run Tests
python -m pytest tests/ -m "not live" -v --tb=short
Amina uses OmniVoice for zero-shot voice cloning. It runs as a separate microservice on port 8998 in its own Python 3.12 environment.
- Server:
models/OmniVoice/fast_api.py
- Environment:
models/OmniVoice/omni_env/ (Python 3.12)
- Voice config:
models/OmniVoice/voices_config.json
Amina auto-starts the TTS microservice when voice is enabled in settings. No manual startup needed.
If you skip TTS setup, Amina still works fully — voice output is just disabled. You can enable it later via Settings → Voice in the web UI.
Quick Reference
- Web UI:
http://localhost:8000
- API docs:
http://localhost:8000/docs
- TTS service:
http://localhost:8998
- Ollama (optional):
http://localhost:11434
- Test suite:
python -m pytest tests/ -m "not live"
- Model config: Settings → Brain Model in the web UI