AuraFrame — Local AI Image Enhancement Suite

AuraFrame is a Linux desktop application for AI-powered image enhancement, built with PyQt6. It provides local inference pipelines for upscaling, face restoration, face swapping, and full image editing using ONNX Runtime models.

Tech Stack

• Python 3.10+
• PyQt6 — desktop GUI
• ONNX Runtime — local model inference (CPU default, CUDA / ROCm optional)
• OpenCV + NumPy — image processing
• Requests — model downloads

Getting Started

git clone https://forgejo.tail018ac4.ts.net/Mark/kimi_agent_local_ai_image_enhancer.git
cd kimi_agent_local_ai_image_enhancer
pip install -r requirements.txt
./run.sh

Or install as a package:

pip install -e .
python -m auraframe.main

Deployment

Modern packaging (PEP 621)

The project ships a declarative pyproject.toml. The legacy setup.py is kept only for compatibility with the existing Forgejo CI step that calls python setup.py check and is no longer required for installation.

# Core (CPU ONNX Runtime)
pip install .

# With NVIDIA CUDA acceleration
pip install .[gpu-cuda]

# With AMD ROCm acceleration
pip install .[gpu-rocm]

# Everything + test dependencies
pip install .[all]

After install the auraframe console script is on PATH:

auraframe            # launches the GUI
python -m auraframe.main   # equivalent

Container (Docker / Podman)

A multi-stage Dockerfile (and a symlink-friendly Containerfile) is provided. The default build uses the CPU ONNX Runtime; pass ORT_VARIANT=gpu-cuda for an NVIDIA build.

# CPU build
podman build -t auraframe:latest .

# CUDA build (requires NVIDIA container runtime on the host)
podman build --build-arg ORT_VARIANT=gpu-cuda -t auraframe:gpu .

# Run with display forwarding
podman run --rm \
    -e DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -v "$HOME/.auraframe:/home/auraframe/.auraframe" \
    auraframe:latest

# Headless smoke test (offscreen Qt platform)
podman run --rm -e QT_QPA_PLATFORM=offscreen auraframe:latest --help

The runtime stage installs the Qt xcb platform plugin libraries (libxcb-*, libxkbcommon-x11-0, libfontconfig1) plus libgl1, libglib2.0-0, and libsm6 for OpenCV. When no DISPLAY is set, the container falls back to Qt's offscreen platform so the GUI modules can be imported in CI without a graphical session.

System runtime dependencies

These are not provided by PyPI wheels and must be present on the host or in the container image:

Dependency	Required by	Debian / Ubuntu package
Qt xcb platform plugin	PyQt6 GUI	libxcb-cursor0, libxcb-icccm4, libxcb-image0, libxcb-keysyms1, libxcb-randr0, libxcb-render-util0, libxcb-shape0, libxcb-sync1, libxcb-util1, libxcb-xkb1, libxkbcommon-x11-0
Font config	PyQt6 text rendering	libfontconfig1, libdbus-1-3
OpenGL / X11	OpenCV GUI helpers	libgl1, libglib2.0-0, libsm6, libxrender1
CUDA 12.x toolkit + driver	onnxruntime-gpu	NVIDIA driver + cuda (≥12.1 for onnxruntime>=1.16)
ROCm 5.6+ runtime	onnxruntime-rocm	rocm-libs (and matching kernel-mode driver)

Install on Debian / Ubuntu:

sudo apt install -y \
    libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
    libxcb-randr0 libxcb-render-util0 libxcb-shape0 libxcb-sync1 \
    libxcb-util1 libxcb-xkb1 libxkbcommon-x11-0 \
    libfontconfig1 libdbus-1-3 \
    libgl1 libglib2.0-0 libsm6 libxrender1

GPU backends

• CUDA — install the matching wheel via pip install .[gpu-cuda]. Ensure the host NVIDIA driver supports CUDA 12.1 or newer.

• ROCm — the onnxruntime-rocm wheel is not published to PyPI. Install from Microsoft's index:

  pip install .[gpu-rocm] \
      --extra-index-url https://pkgs.dev.azure.com/onnxruntime/onnxruntime/_packaging/onnxruntime-rocm-feed/pypi/simple/
  

  Host must have ROCm 5.6+ (rocm-smi should list the GPU).

AppImage (planned)

Building a redistributable AppImage requires linuxdeploy plus the PyQt6 plugin from the linuxdeploy-qt project. A reference build script will live at scripts/build-appimage.sh in a follow-up; the container image above is the supported deployment target today.

Project Structure

.
├── run.sh                  # Standalone launcher
├── pyproject.toml          # PEP 621 package metadata
├── setup.py                # Legacy shim (CI compatibility)
├── requirements.txt        # Pinned subset of core deps
├── Dockerfile              # Multi-stage container build
├── Containerfile           # Podman alias of Dockerfile
├── .forgejo/workflows/ci.yml  # CI configuration
└── auraframe/
    ├── main.py             # Application entry point
    ├── config.py           # Global configuration and paths
    ├── gui/                # PyQt6 widgets and windows
    ├── models/             # Model wrappers, registry, and manager
    ├── pipeline/           # Node-based processing engine
    ├── processors/         # Image processing primitives
    ├── utils/              # I/O, preview, path, and async helpers
    └── workflows/          # Pre-built processing workflows

Scripts / Commands

Command	Description
./run.sh	Launch the application without installing
pip install -e .	Install AuraFrame as an editable package
pip install .[gpu-cuda]	Install with NVIDIA CUDA support
pip install .[gpu-rocm]	Install with AMD ROCm support
python -m auraframe.main	Run the application after installation
auraframe	Console script installed by pip install .
podman build -t auraframe .	Build the container image

Configuration

Application data, cached models, and logs are stored under ~/.auraframe/ by default. Edit auraframe/config.py or implement a settings dialog to change defaults.

License

Proprietary — see pyproject.toml. License file is not yet specified.