Metadata-Version: 2.4
Name: airunner
Version: 4.1.2
Summary: Run local opensource AI models (Stable Diffusion, LLMs, TTS, STT, chatbots) in a lightweight Python GUI
Home-page: https://github.com/Capsize-Games/airunner
Author: Capsize LLC
Author-email: contact@capsizegames.com
License: Apache-2.0
Keywords: llm,pyside6,gui,local llm,stable diffusion,generative ai,local chatgpt,text-to-speech,speech-to-text,open source chatbot,python ai runner
Requires-Python: >=3.10.12,<3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch==2.6.0
Requires-Dist: torchvision==0.21.0
Requires-Dist: torchaudio==2.6.0
Requires-Dist: accelerate==1.3.0
Requires-Dist: huggingface-hub<1.0,>=0.24.0
Requires-Dist: tokenizers==0.21.1
Requires-Dist: optimum==1.24.0
Requires-Dist: numpy==1.26.4
Requires-Dist: pillow==10.4.0
Requires-Dist: alembic==1.14.1
Requires-Dist: aiosqlite==0.21.0
Requires-Dist: sqlalchemy==2.0.38
Requires-Dist: setuptools==78.1.0
Requires-Dist: facehuggershield==0.1.13
Provides-Extra: nvidia
Requires-Dist: nvidia-pyindex==1.0.9; extra == "nvidia"
Requires-Dist: nvidia-cuda-runtime-cu12; extra == "nvidia"
Provides-Extra: gui
Requires-Dist: PySide6==6.7.0; extra == "gui"
Requires-Dist: PySide6_Addons==6.7.0; extra == "gui"
Requires-Dist: PySide6_Essentials==6.7.0; extra == "gui"
Provides-Extra: linux
Requires-Dist: faiss-gpu==1.7.2; extra == "linux"
Requires-Dist: tensorrt==10.9.0.34; extra == "linux"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: python-dotenv==1.0.1; extra == "dev"
Requires-Dist: coverage==7.8.0; extra == "dev"
Requires-Dist: black==25.1.0; extra == "dev"
Requires-Dist: pyinstaller==6.12.0; extra == "dev"
Provides-Extra: art
Requires-Dist: DeepCache==0.1.1; extra == "art"
Requires-Dist: diffusers==0.32.2; extra == "art"
Requires-Dist: controlnet_aux==0.0.9; extra == "art"
Requires-Dist: safetensors==0.5.2; extra == "art"
Requires-Dist: compel==2.0.3; extra == "art"
Requires-Dist: tomesd==0.1.3; extra == "art"
Requires-Dist: timm<=0.6.7; extra == "art"
Provides-Extra: llm
Requires-Dist: transformers==4.48.1; extra == "llm"
Requires-Dist: auto-gptq==0.7.1; extra == "llm"
Requires-Dist: bitsandbytes==0.45.2; extra == "llm"
Requires-Dist: datasets==3.2.0; extra == "llm"
Requires-Dist: sentence_transformers==3.4.1; extra == "llm"
Requires-Dist: sounddevice==0.5.1; extra == "llm"
Requires-Dist: pyttsx3==2.91; extra == "llm"
Requires-Dist: cryptography==44.0.0; extra == "llm"
Requires-Dist: llama-index==0.12.14; extra == "llm"
Requires-Dist: llama-index-readers-file==0.4.4; extra == "llm"
Requires-Dist: llama-index-readers-web==0.3.5; extra == "llm"
Requires-Dist: llama-index-llms-huggingface==0.4.2; extra == "llm"
Requires-Dist: llama-index-llms-groq==0.3.1; extra == "llm"
Requires-Dist: llama-index-embeddings-mistralai==0.3.0; extra == "llm"
Requires-Dist: llama-index-vector-stores-faiss==0.3.0; extra == "llm"
Requires-Dist: llama-index-embeddings-huggingface==0.5.1; extra == "llm"
Requires-Dist: llama-index-llms-openrouter==0.3.1; extra == "llm"
Requires-Dist: langchain-community==0.3.17; extra == "llm"
Requires-Dist: EbookLib==0.18; extra == "llm"
Requires-Dist: html2text==2024.2.26; extra == "llm"
Requires-Dist: rake_nltk==1.0.6; extra == "llm"
Requires-Dist: tf-keras==2.18.0; extra == "llm"
Requires-Dist: peft==0.14.0; extra == "llm"
Requires-Dist: lxml_html_clean==0.4.1; extra == "llm"
Requires-Dist: sumy==0.11.0; extra == "llm"
Provides-Extra: llm-weather
Requires-Dist: requests-cache==1.2.1; extra == "llm-weather"
Requires-Dist: retry-requests==2.0.0; extra == "llm-weather"
Requires-Dist: openmeteo_requests==1.4.0; extra == "llm-weather"
Provides-Extra: tts
Requires-Dist: inflect==7.5.0; extra == "tts"
Requires-Dist: pycountry==24.6.1; extra == "tts"
Requires-Dist: librosa==0.11.0; extra == "tts"
Provides-Extra: rabbitmq
Requires-Dist: pika; extra == "rabbitmq"
Provides-Extra: all
Requires-Dist: nvidia-pyindex==1.0.9; extra == "all"
Requires-Dist: nvidia-cuda-runtime-cu12; extra == "all"
Requires-Dist: PySide6==6.7.0; extra == "all"
Requires-Dist: PySide6_Addons==6.7.0; extra == "all"
Requires-Dist: PySide6_Essentials==6.7.0; extra == "all"
Requires-Dist: faiss-gpu==1.7.2; extra == "all"
Requires-Dist: tensorrt==10.9.0.34; extra == "all"
Requires-Dist: DeepCache==0.1.1; extra == "all"
Requires-Dist: diffusers==0.32.2; extra == "all"
Requires-Dist: controlnet_aux==0.0.9; extra == "all"
Requires-Dist: safetensors==0.5.2; extra == "all"
Requires-Dist: compel==2.0.3; extra == "all"
Requires-Dist: tomesd==0.1.3; extra == "all"
Requires-Dist: timm<=0.6.7; extra == "all"
Requires-Dist: transformers==4.48.1; extra == "all"
Requires-Dist: auto-gptq==0.7.1; extra == "all"
Requires-Dist: bitsandbytes==0.45.2; extra == "all"
Requires-Dist: datasets==3.2.0; extra == "all"
Requires-Dist: sentence_transformers==3.4.1; extra == "all"
Requires-Dist: sounddevice==0.5.1; extra == "all"
Requires-Dist: pyttsx3==2.91; extra == "all"
Requires-Dist: cryptography==44.0.0; extra == "all"
Requires-Dist: llama-index==0.12.14; extra == "all"
Requires-Dist: llama-index-readers-file==0.4.4; extra == "all"
Requires-Dist: llama-index-readers-web==0.3.5; extra == "all"
Requires-Dist: llama-index-llms-huggingface==0.4.2; extra == "all"
Requires-Dist: llama-index-llms-groq==0.3.1; extra == "all"
Requires-Dist: llama-index-embeddings-mistralai==0.3.0; extra == "all"
Requires-Dist: llama-index-vector-stores-faiss==0.3.0; extra == "all"
Requires-Dist: llama-index-embeddings-huggingface==0.5.1; extra == "all"
Requires-Dist: llama-index-llms-openrouter==0.3.1; extra == "all"
Requires-Dist: langchain-community==0.3.17; extra == "all"
Requires-Dist: EbookLib==0.18; extra == "all"
Requires-Dist: html2text==2024.2.26; extra == "all"
Requires-Dist: rake_nltk==1.0.6; extra == "all"
Requires-Dist: tf-keras==2.18.0; extra == "all"
Requires-Dist: peft==0.14.0; extra == "all"
Requires-Dist: lxml_html_clean==0.4.1; extra == "all"
Requires-Dist: sumy==0.11.0; extra == "all"
Requires-Dist: requests-cache==1.2.1; extra == "all"
Requires-Dist: retry-requests==2.0.0; extra == "all"
Requires-Dist: openmeteo_requests==1.4.0; extra == "all"
Requires-Dist: inflect==7.5.0; extra == "all"
Requires-Dist: pycountry==24.6.1; extra == "all"
Requires-Dist: librosa==0.11.0; extra == "all"
Requires-Dist: pika; extra == "all"
Requires-Dist: nvidia-pyindex==1.0.9; extra == "all"
Requires-Dist: nvidia-cuda-runtime-cu12; extra == "all"
Requires-Dist: PySide6==6.7.0; extra == "all"
Requires-Dist: PySide6_Addons==6.7.0; extra == "all"
Requires-Dist: PySide6_Essentials==6.7.0; extra == "all"
Requires-Dist: faiss-gpu==1.7.2; extra == "all"
Requires-Dist: tensorrt==10.9.0.34; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: python-dotenv==1.0.1; extra == "all"
Requires-Dist: coverage==7.8.0; extra == "all"
Requires-Dist: black==25.1.0; extra == "all"
Requires-Dist: pyinstaller==6.12.0; extra == "all"
Requires-Dist: DeepCache==0.1.1; extra == "all"
Requires-Dist: diffusers==0.32.2; extra == "all"
Requires-Dist: controlnet_aux==0.0.9; extra == "all"
Requires-Dist: safetensors==0.5.2; extra == "all"
Requires-Dist: compel==2.0.3; extra == "all"
Requires-Dist: tomesd==0.1.3; extra == "all"
Requires-Dist: timm<=0.6.7; extra == "all"
Requires-Dist: transformers==4.48.1; extra == "all"
Requires-Dist: auto-gptq==0.7.1; extra == "all"
Requires-Dist: bitsandbytes==0.45.2; extra == "all"
Requires-Dist: datasets==3.2.0; extra == "all"
Requires-Dist: sentence_transformers==3.4.1; extra == "all"
Requires-Dist: sounddevice==0.5.1; extra == "all"
Requires-Dist: pyttsx3==2.91; extra == "all"
Requires-Dist: cryptography==44.0.0; extra == "all"
Requires-Dist: llama-index==0.12.14; extra == "all"
Requires-Dist: llama-index-readers-file==0.4.4; extra == "all"
Requires-Dist: llama-index-readers-web==0.3.5; extra == "all"
Requires-Dist: llama-index-llms-huggingface==0.4.2; extra == "all"
Requires-Dist: llama-index-llms-groq==0.3.1; extra == "all"
Requires-Dist: llama-index-embeddings-mistralai==0.3.0; extra == "all"
Requires-Dist: llama-index-vector-stores-faiss==0.3.0; extra == "all"
Requires-Dist: llama-index-embeddings-huggingface==0.5.1; extra == "all"
Requires-Dist: llama-index-llms-openrouter==0.3.1; extra == "all"
Requires-Dist: langchain-community==0.3.17; extra == "all"
Requires-Dist: EbookLib==0.18; extra == "all"
Requires-Dist: html2text==2024.2.26; extra == "all"
Requires-Dist: rake_nltk==1.0.6; extra == "all"
Requires-Dist: tf-keras==2.18.0; extra == "all"
Requires-Dist: peft==0.14.0; extra == "all"
Requires-Dist: lxml_html_clean==0.4.1; extra == "all"
Requires-Dist: sumy==0.11.0; extra == "all"
Requires-Dist: requests-cache==1.2.1; extra == "all"
Requires-Dist: retry-requests==2.0.0; extra == "all"
Requires-Dist: openmeteo_requests==1.4.0; extra == "all"
Requires-Dist: inflect==7.5.0; extra == "all"
Requires-Dist: pycountry==24.6.1; extra == "all"
Requires-Dist: librosa==0.11.0; extra == "all"
Requires-Dist: pika; extra == "all"
Provides-Extra: all-dev
Requires-Dist: nvidia-pyindex==1.0.9; extra == "all-dev"
Requires-Dist: nvidia-cuda-runtime-cu12; extra == "all-dev"
Requires-Dist: PySide6==6.7.0; extra == "all-dev"
Requires-Dist: PySide6_Addons==6.7.0; extra == "all-dev"
Requires-Dist: PySide6_Essentials==6.7.0; extra == "all-dev"
Requires-Dist: faiss-gpu==1.7.2; extra == "all-dev"
Requires-Dist: tensorrt==10.9.0.34; extra == "all-dev"
Requires-Dist: pytest; extra == "all-dev"
Requires-Dist: python-dotenv==1.0.1; extra == "all-dev"
Requires-Dist: coverage==7.8.0; extra == "all-dev"
Requires-Dist: black==25.1.0; extra == "all-dev"
Requires-Dist: pyinstaller==6.12.0; extra == "all-dev"
Requires-Dist: DeepCache==0.1.1; extra == "all-dev"
Requires-Dist: diffusers==0.32.2; extra == "all-dev"
Requires-Dist: controlnet_aux==0.0.9; extra == "all-dev"
Requires-Dist: safetensors==0.5.2; extra == "all-dev"
Requires-Dist: compel==2.0.3; extra == "all-dev"
Requires-Dist: tomesd==0.1.3; extra == "all-dev"
Requires-Dist: timm<=0.6.7; extra == "all-dev"
Requires-Dist: transformers==4.48.1; extra == "all-dev"
Requires-Dist: auto-gptq==0.7.1; extra == "all-dev"
Requires-Dist: bitsandbytes==0.45.2; extra == "all-dev"
Requires-Dist: datasets==3.2.0; extra == "all-dev"
Requires-Dist: sentence_transformers==3.4.1; extra == "all-dev"
Requires-Dist: sounddevice==0.5.1; extra == "all-dev"
Requires-Dist: pyttsx3==2.91; extra == "all-dev"
Requires-Dist: cryptography==44.0.0; extra == "all-dev"
Requires-Dist: llama-index==0.12.14; extra == "all-dev"
Requires-Dist: llama-index-readers-file==0.4.4; extra == "all-dev"
Requires-Dist: llama-index-readers-web==0.3.5; extra == "all-dev"
Requires-Dist: llama-index-llms-huggingface==0.4.2; extra == "all-dev"
Requires-Dist: llama-index-llms-groq==0.3.1; extra == "all-dev"
Requires-Dist: llama-index-embeddings-mistralai==0.3.0; extra == "all-dev"
Requires-Dist: llama-index-vector-stores-faiss==0.3.0; extra == "all-dev"
Requires-Dist: llama-index-embeddings-huggingface==0.5.1; extra == "all-dev"
Requires-Dist: llama-index-llms-openrouter==0.3.1; extra == "all-dev"
Requires-Dist: langchain-community==0.3.17; extra == "all-dev"
Requires-Dist: EbookLib==0.18; extra == "all-dev"
Requires-Dist: html2text==2024.2.26; extra == "all-dev"
Requires-Dist: rake_nltk==1.0.6; extra == "all-dev"
Requires-Dist: tf-keras==2.18.0; extra == "all-dev"
Requires-Dist: peft==0.14.0; extra == "all-dev"
Requires-Dist: lxml_html_clean==0.4.1; extra == "all-dev"
Requires-Dist: sumy==0.11.0; extra == "all-dev"
Requires-Dist: requests-cache==1.2.1; extra == "all-dev"
Requires-Dist: retry-requests==2.0.0; extra == "all-dev"
Requires-Dist: openmeteo_requests==1.4.0; extra == "all-dev"
Requires-Dist: inflect==7.5.0; extra == "all-dev"
Requires-Dist: pycountry==24.6.1; extra == "all-dev"
Requires-Dist: librosa==0.11.0; extra == "all-dev"
Requires-Dist: pika; extra == "all-dev"
Requires-Dist: nvidia-pyindex==1.0.9; extra == "all-dev"
Requires-Dist: nvidia-cuda-runtime-cu12; extra == "all-dev"
Requires-Dist: PySide6==6.7.0; extra == "all-dev"
Requires-Dist: PySide6_Addons==6.7.0; extra == "all-dev"
Requires-Dist: PySide6_Essentials==6.7.0; extra == "all-dev"
Requires-Dist: faiss-gpu==1.7.2; extra == "all-dev"
Requires-Dist: tensorrt==10.9.0.34; extra == "all-dev"
Requires-Dist: pytest; extra == "all-dev"
Requires-Dist: python-dotenv==1.0.1; extra == "all-dev"
Requires-Dist: coverage==7.8.0; extra == "all-dev"
Requires-Dist: black==25.1.0; extra == "all-dev"
Requires-Dist: pyinstaller==6.12.0; extra == "all-dev"
Requires-Dist: DeepCache==0.1.1; extra == "all-dev"
Requires-Dist: diffusers==0.32.2; extra == "all-dev"
Requires-Dist: controlnet_aux==0.0.9; extra == "all-dev"
Requires-Dist: safetensors==0.5.2; extra == "all-dev"
Requires-Dist: compel==2.0.3; extra == "all-dev"
Requires-Dist: tomesd==0.1.3; extra == "all-dev"
Requires-Dist: timm<=0.6.7; extra == "all-dev"
Requires-Dist: transformers==4.48.1; extra == "all-dev"
Requires-Dist: auto-gptq==0.7.1; extra == "all-dev"
Requires-Dist: bitsandbytes==0.45.2; extra == "all-dev"
Requires-Dist: datasets==3.2.0; extra == "all-dev"
Requires-Dist: sentence_transformers==3.4.1; extra == "all-dev"
Requires-Dist: sounddevice==0.5.1; extra == "all-dev"
Requires-Dist: pyttsx3==2.91; extra == "all-dev"
Requires-Dist: cryptography==44.0.0; extra == "all-dev"
Requires-Dist: llama-index==0.12.14; extra == "all-dev"
Requires-Dist: llama-index-readers-file==0.4.4; extra == "all-dev"
Requires-Dist: llama-index-readers-web==0.3.5; extra == "all-dev"
Requires-Dist: llama-index-llms-huggingface==0.4.2; extra == "all-dev"
Requires-Dist: llama-index-llms-groq==0.3.1; extra == "all-dev"
Requires-Dist: llama-index-embeddings-mistralai==0.3.0; extra == "all-dev"
Requires-Dist: llama-index-vector-stores-faiss==0.3.0; extra == "all-dev"
Requires-Dist: llama-index-embeddings-huggingface==0.5.1; extra == "all-dev"
Requires-Dist: llama-index-llms-openrouter==0.3.1; extra == "all-dev"
Requires-Dist: langchain-community==0.3.17; extra == "all-dev"
Requires-Dist: EbookLib==0.18; extra == "all-dev"
Requires-Dist: html2text==2024.2.26; extra == "all-dev"
Requires-Dist: rake_nltk==1.0.6; extra == "all-dev"
Requires-Dist: tf-keras==2.18.0; extra == "all-dev"
Requires-Dist: peft==0.14.0; extra == "all-dev"
Requires-Dist: lxml_html_clean==0.4.1; extra == "all-dev"
Requires-Dist: sumy==0.11.0; extra == "all-dev"
Requires-Dist: requests-cache==1.2.1; extra == "all-dev"
Requires-Dist: retry-requests==2.0.0; extra == "all-dev"
Requires-Dist: openmeteo_requests==1.4.0; extra == "all-dev"
Requires-Dist: inflect==7.5.0; extra == "all-dev"
Requires-Dist: pycountry==24.6.1; extra == "all-dev"
Requires-Dist: librosa==0.11.0; extra == "all-dev"
Requires-Dist: pika; extra == "all-dev"
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

[![AI Runner Logo](images/banner.png)](https://github.com/Capsize-Games/airunner)

[![Discord](https://img.shields.io/discord/839511291466219541?color=5865F2&logo=discord&logoColor=white)](https://discord.gg/PUVDDCJ7gz)
[![PyPi](https://github.com/Capsize-Games/airunner/actions/workflows/pypi-dispatch.yml/badge.svg)](https://github.com/Capsize-Games/airunner/actions/workflows/pypi-dispatch.yml)
[![Docker Release](https://github.com/Capsize-Games/airunner/actions/workflows/docker-release.yml/badge.svg)](https://github.com/Capsize-Games/airunner/actions/workflows/docker-release.yml)
[![Linux Build](https://github.com/Capsize-Games/airunner/actions/workflows/linux-dispatch.yml/badge.svg)](https://github.com/Capsize-Games/airunner/actions/workflows/linux-dispatch.yml)
![GitHub](https://img.shields.io/github/license/Capsize-Games/airunner)
![GitHub last commit](https://img.shields.io/github/last-commit/Capsize-Games/airunner)
![GitHub issues](https://img.shields.io/github/issues/Capsize-Games/airunner)
![GitHub closed issues](https://img.shields.io/github/issues-closed/Capsize-Games/airunner)
![GitHub pull requests](https://img.shields.io/github/issues-pr/Capsize-Games/airunner)
![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Capsize-Games/airunner)

---

# AI Runner 

**Run local AI models for text, images, text-to-speech, and speech-to-text—all in one open-source tool.**  
No cloud dependency. No complicated setup. Just install, run, and create.

![image](https://github.com/user-attachments/assets/392375c8-a7f6-4e6e-8662-511cffc608aa)

## Table of Contents
- [Overview](#overview)
- [Why Developers Use AI Runner](#why-developers-use-ai-runner)
- [Features](#features)
- [System Requirements](#system-requirements)
- [Quick Start (Docker)](#quick-start-docker)
- [Installation Details](#installation-details)
- [AI Models](#ai-models)
- [Unit Tests](#unit-tests)
- [Database](#database)
- [Advanced Features](#advanced-features)
- [Missing or Planned Features](#missing-or-planned-features)
- [Contributing](#contributing)

---

## Overview

AI Runner is a local-first, **open-source** application built with HuggingFace and Llama-index libraries that enables you to run:

- **Large Language Models (LLMs)** for chat and text generation  
- **Stable Diffusion** for image generation and manipulation
- **Text-to-Speech (TTS)**  
- **Speech-to-Text (STT)**  

Originally created as a GUI-centric AI art and chatbot tool for end users, AI Runner has evolved into a **developer-friendly** platform. With Docker support, an extension API, and a pure Python codebase, you can integrate AI Runner into your own apps or use it as an all-in-one offline inference engine.

![interface/img.png](images/interface.png)

**Typical Uses:**
- AI prototyping: Quickly test local LLMs and image generation.  
- Offline scenarios: Work behind firewalls or without internet.  
- Custom UI/UX: Build plugins/extensions for your particular domain.  
- End-user tools: Hand off a no-code (GUI) solution for less technical stakeholders.

---

## Why Developers Use AI Runner

![images/img.png](images/img.png)

1. **Fast Setup with Docker**  
   No need to configure Python environments manually—just pull and run. AI Runner includes all major dependencies, plus GPU support (with [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)).

2. **Local LLM & Stable Diffusion in One**  
   Stop juggling separate repos for text generation and image generation. AI Runner unifies them under one interface.

3. **Plugin & Extension System**  
   Extend or modify AI Runner’s GUI or back-end with custom plugins. Add new model workflows, custom UI panels, or special logic without forking the entire codebase.

4. **Python Library**  
   Install from PyPi and **import** AI Runner directly into your Python project (e.g., a game in Pygame or a PySide6 desktop app).

5. **Offline / Private Data**  
   Keep data on-premise or behind a firewall—great for enterprise or regulated environments that can’t rely on external cloud inference.

If you find it helpful, please **star this repo** and share it with others—it helps the project grow and signals demand for local AI solutions.

---

## Features

Below is a high-level list of capabilities in AI Runner:

| Feature                                  | Description                                                                                  |
|------------------------------------------|----------------------------------------------------------------------------------------------|
| **LLMs & Communication**                 |                                                                                              |
| Voice-based chatbot conversations        | Have real-time voice-chat sessions with an LLM (speech-to-text + text-to-speech)            |
| Text-to-speech (TTS)                     | Convert text to spoken audio using Espeak or SpeechT5                                       |
| Speech-to-text (STT)                     | Convert spoken audio to text with Whisper                                                   |
| Customizable chatbots                    | Create AI personalities and moods for more engaging conversations                            |
| Retrieval-Augmented Generation           | Use local doc or website data to enrich chat responses                                      |
| **Image Generation**                     |                                                                                              |
| Stable Diffusion (1.5, SDXL, Turbo)      | Generate images from textual prompts, sketches, or existing images                           |
| Drawing tools & ControlNet              | Fine-tune image outputs with extra input or guides                                          |
| LoRA & Embeddings                        | Load LoRA models or textual embeddings for specialized image generation                     |
| **Image Manipulation**                   |                                                                                              |
| Inpaint & Outpaint                       | Modify portions of generated images while keeping context                                   |
| Image filters                            | Blur, film grain, pixel art, etc.                                                            |
| **Utility**                              |                                                                                              |
| **Offline**                              | Everything runs locally, no external API required                                           |
| Fast generation                          | E.g., ~2 seconds on an RTX 2080s for stable diffusion                                        |
| Docker-based approach                    | Simplifies setup & ensures GPU acceleration works out of the box                            |
| Dark mode                                | Built-in theming (Light / Dark / System)                                                    |
| NSFW toggles                             | Enable or disable NSFW detection for images                                                 |
| Ethical guardrails                       | Basic guardrails for safe LLM usage (optional)                                              |
| **Extensions**                           | Build your own feature add-ons via the extension API                                        |
| **Python Library**                       | `pip install airunner` and embed it in your own projects                                    |
| **API Support**                          | Optionally use OpenRouter or other external LLMs                                            |

---

## System Requirements

### Minimum Specs

- **OS**: Ubuntu 22.04
- **CPU**: Ryzen 2700K or Intel Core i7-8700K
- **Memory**: 16 GB RAM  
- **GPU**: NVIDIA RTX 3060 or better
- **Network**: Broadband (used to download models)  
- **Storage**: 36 GB

### Recommended Specs

- **OS**: Ubuntu 22.04  
- **CPU**: Ryzen 5800X or Intel Core i7-11700K
- **Memory**: 32 GB RAM  
- **GPU**: NVIDIA RTX 4090 or better
- **Network**: Broadband (used to download models)  
- **Storage**: 50 GB

---

## Quick Start (Docker)

**Recommended for most developers**—it avoids Python environment headaches and streamlines GPU access.

1. **Install NVIDIA Container Toolkit**  
   Follow the [official guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) to enable GPU passthrough for Docker.
2. **Clone AI Runner and Run Setup**  
   ```bash
   git clone https://github.com/Capsize-Games/airunner.git
   cd airunner
   python3 -m venv venv
   source venv/bin/activate
   ./src/airunner/bin/setup.sh
   ```
   - _Choose option **1** (Setup xhost)_
   - _Choose option **2** (Install AI Runner scripts)_
3. ```bash
   docker pull ghcr.io/capsize-games/airunner/airunner:linux
   ./src/airunner/bin/docker.sh airunner
   ```
This starts the GUI with stable diffusion, LLM, TTS/STT, and more.

For detailed steps, see the [Installation Wiki](https://github.com/Capsize-Games/airunner/wiki/Installation-instructions).

---

## Installation Details

If you prefer **not** to use Docker, see the [Installation Wiki for more information](https://github.com/Capsize-Games/airunner/wiki/Installation-instructions).

---

## AI Models

By default, AI Runner installs essential TTS/STT and minimal LLM components.  
You **must supply** additional Stable Diffusion models (e.g., from [Hugging Face](https://huggingface.co/) or [Civitai](https://civitai.com/)).

Organize them under your local AI Runner data directory:
```plaintext
~/.local/share/airunner
├── art
│   └── models
│       ├── SD 1.5
│       │   ├── lora
│       │   └── embeddings
│       ├── SDXL 1.0
│       │   ├── lora
│       │   └── embeddings
│       └── SDXL Turbo
│           ├── lora
│           └── embeddings
```

---

## Unit Tests

To run all tests:

```bash
python -m unittest discover -s src/airunner/tests
```

Or a single test:

```bash
python -m unittest src/airunner/tests/test_prompt_weight_convert.py
```

---

## Database

AI Runner supports a simple database system. See the [Wiki](https://github.com/Capsize-Games/airunner/wiki/Database) for how to:
- Switch engines (SQLite, etc.)
- Make schema changes
- Run migrations

---

## Advanced Features

- **Memory Optimization**: TF32 Mode, VAE/Attention Slicing, Torch 2.0, sequential CPU offload, ToMe token merging.  
- **Experimental Integrations**: Weather-based chatbot prompts, advanced command-line arguments (`--perform-llm-analysis`, `--disable-setup-wizard`, etc.).  
- **Safety & Guardrails**: Optional NSFW content detection and adjustable guardrails for LLMs.  

---

## Contributing

We welcome pull requests for new features, bug fixes, or documentation improvements. You can also build and share **extensions** to expand AI Runner’s functionality. For details, see the [Extensions Wiki](https://github.com/Capsize-Games/airunner/wiki/Extensions).

Take a look at the [Contributing document](https://github.com/Capsize-Games/airunner/CONTRIBUTING.md) and the [Development wiki page](https://github.com/Capsize-Games/airunner/wiki/Development) for detailed instructions.

**If you find this project useful**, please consider giving us a ⭐ on GitHub—it really helps with visibility and encourages further development.

---

## Thank You!

Thanks for checking out AI Runner.  
**Get started** with local AI inference in minutes—no more endless environment setup.  
Questions or ideas? Join our [Discord](https://discord.gg/PUVDDCJ7gz) or open a [GitHub Issue](https://github.com/Capsize-Games/airunner/issues).  

**Happy building!**
