upscalex 0.1.0__tar.gz

upscalex-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# RealESRGAN engine downloads & binaries
+realesrgan-ncnn-vulkan*
+realesrgan.zip
+models/
+*.pth
+*.bin
+*.param
+*.dll
+
+# Pytest / Cache
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+Thumbs.db

upscalex-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,133 @@
+# Contributing to UpscaleX
+
+Thank you for your interest in contributing to UpscaleX. This project maintains a strict engineering standard focused on high-performance image processing, robust CLI ergonomics, and reliable Model Context Protocol (MCP) server integration.
+
+All contributions, whether bug fixes, documentation improvements, model integrations, or architectural enhancements, are welcome.
+
+---
+
+## Code of Conduct
+
+Contributors are expected to adhere to professional communication and collaboration standards:
+- Maintain technical, constructive, and objective dialogue in issues and pull requests.
+- Respect differing perspectives and technical approaches.
+- Focus on performance, memory safety, test coverage, and documentation accuracy.
+
+---
+
+## Development Environment Setup
+
+UpscaleX uses [`uv`](https://github.com/astral-sh/uv) as its package manager and execution environment.
+
+### Prerequisites
+
+- Python 3.10 or later
+- Vulkan-compatible GPU (NVIDIA, AMD, or Intel) with up-to-date graphics drivers
+- Git
+
+### Initializing the Workspace
+
+1. Fork the repository on GitHub and clone your fork:
+   ```bash
+   git clone https://github.com/<your-username>/upscalex.git
+   cd upscalex
+   ```
+
+2. Create a virtual environment using `uv`:
+   ```bash
+   uv venv
+   ```
+
+3. Install editable dependencies, including development tools:
+   ```bash
+   uv pip install -e ".[dev]"
+   ```
+
+4. Verify your setup by running the test suite:
+   ```bash
+   uv run pytest -v
+   ```
+
+---
+
+## Project Structure
+
+```
+upscalex/
+├── src/
+│   └── upscalex/
+│       ├── __init__.py       # Package initialization and public API
+│       ├── cli.py            # Command-line interface implementation
+│       ├── engine.py         # Subprocess runner, tiling logic, Lanczos resampler
+│       ├── server.py         # FastMCP server and tool registrations
+│       └── utils.py          # Binary fetcher, platform resolvers, formatters
+├── tests/
+│   ├── test_cli.py           # CLI invocation and runner tests
+│   └── test_engine.py        # Core processing, mathematical sizing, and GPU tests
+├── docs/                     # Technical documentation
+│   ├── architecture.md       # Pipeline architecture and memory management
+│   ├── cli-guide.md          # Command-line interface reference
+│   └── mcp-guide.md          # Model Context Protocol integration reference
+├── pyproject.toml            # PEP 621 package metadata and entry points
+├── uv.lock                   # Pinned dependency lockfile
+└── LICENSE                   # MIT License
+```
+
+---
+
+## Coding Standards
+
+### Python Style
+
+- Adhere to PEP 8 standards with modern typing annotations (`from __future__ import annotations`).
+- Ensure all public functions, classes, and methods have comprehensive docstrings explaining arguments, return types, and exceptions raised.
+- Avoid emoji usage in commit messages, documentation, terminal outputs, and code comments. Maintain a clean, professional technical tone.
+- Do not introduce dependencies that require CUDA compilation unless behind optional build flags. The core engine relies on Vulkan runtime binaries.
+
+### Memory & Stability Rules
+
+- When interacting with high-resolution image decoders (such as Pillow), always account for ultra-large resolutions exceeding 100 Megapixels.
+- Set `Image.MAX_IMAGE_PIXELS = None` in modules handling raw bitmaps to avoid decompression bomb exceptions during multi-gigapixel print jobs.
+- Always guarantee temporary files created during supersampling or tile processing are safely unlinked in `finally` blocks.
+
+---
+
+## Testing Workflow
+
+All pull requests must maintain 100% pass rate on existing and new tests.
+
+Run tests locally using pytest:
+```bash
+uv run pytest -v
+```
+
+When contributing new features:
+1. Add corresponding unit tests in `tests/test_engine.py` or `tests/test_cli.py`.
+2. Verify that CLI commands exit with code `0` on success and appropriate non-zero error codes on failure.
+3. Test edge cases such as missing binaries, invalid image paths, non-standard aspect ratios, and extreme resolutions.
+
+---
+
+## Pull Request Process
+
+1. Create a descriptive feature branch from `main`:
+   ```bash
+   git checkout -b feature/tiling-optimization
+   ```
+
+2. Format commits using Conventional Commit style:
+   - `feat: add support for custom tile padding`
+   - `fix: handle missing models directory in custom paths`
+   - `docs: update mcp configuration guide for cursor`
+   - `perf: optimize memory consumption during lanczos downscaling`
+
+3. Ensure `uv.lock` is kept up to date if dependencies are modified:
+   ```bash
+   uv lock
+   ```
+
+4. Push your branch to your fork and submit a Pull Request against the `main` branch.
+5. Provide a clear summary in your pull request description detailing:
+   - The rationale for the change.
+   - Any benchmarks or performance impacts.
+   - Verification steps taken.

upscalex-0.1.0/INSTALLATION.md

@@ -0,0 +1,190 @@
+# UpscaleX Installation Guide
+
+This document provides two installation paths for UpscaleX:
+1. **Agent Autonomous Setup Prompt**: A ready-to-use prompt that can be pasted into any AI coding assistant (Antigravity, Claude Code, Cursor, Windsurf) to automatically install, test, and configure the MCP server.
+2. **Manual Installation Guide**: Step-by-step terminal instructions for Windows, Linux, and macOS.
+
+See the complete guide in [`docs/installation.md`](docs/installation.md) or read the self-contained instructions below.
+
+---
+
+## 1. Agent Autonomous Setup Prompt
+
+Copy and paste the following prompt directly into your AI coding assistant:
+
+```markdown
+Please install and configure the UpscaleX MCP and CLI tool in this environment.
+
+Repository: https://github.com/The-Open-Source-Founder/upscalex.git
+
+Instructions:
+1. Verify Python 3.10+ and git are available.
+2. Clone the repository into an appropriate local tools or workspace directory:
+   git clone https://github.com/The-Open-Source-Founder/upscalex.git
+3. Using uv (or python venv):
+   - Create a virtual environment: uv venv (or python -m venv .venv)
+   - Install the package in editable mode with development dependencies:
+     uv pip install -e ".[dev]"
+4. Execute the test suite to ensure the engine and CLI are operational:
+   uv run pytest -v
+5. Register the MCP server in the client configuration (e.g. claude_desktop_config.json or mcp_config.json):
+   {
+     "mcpServers": {
+       "upscalex": {
+         "command": "<ABSOLUTE_PATH_TO_VENV_PYTHON>",
+         "args": ["-m", "upscalex.server"]
+       }
+     }
+   }
+6. Run "upscalex models" and report confirmation once completed.
+```
+
+---
+
+## 2. Quick Installation via PyPI
+
+For standalone CLI and MCP server usage, install directly via `pip`:
+
+```bash
+pip install upscalex
+```
+
+Verify the installation:
+```bash
+upscalex doctor
+upscalex models
+```
+
+---
+
+## 3. Manual Installation from Source
+
+### Prerequisites
+
+- **Python**: Version 3.10 or higher.
+- **Package Manager**: [`uv`](https://github.com/astral-sh/uv) (recommended) or standard `pip`.
+- **GPU Driver**: Vulkan-compatible GPU drivers (NVIDIA GeForce/RTX, AMD Radeon, or Intel Arc/Iris).
+
+---
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/The-Open-Source-Founder/upscalex.git
+cd upscalex
+```
+
+---
+
+### Step 2: Create a Virtual Environment and Install
+
+#### Option A: Using `uv` (Recommended)
+
+```bash
+# Create the virtual environment
+uv venv
+
+# Install in editable mode with development dependencies
+uv pip install -e ".[dev]"
+```
+
+#### Option B: Using Standard Python and Pip
+
+```bash
+# Windows
+python -m venv .venv
+.\.venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Linux / macOS
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+---
+
+### Step 3: Run the Verification Suite
+
+Run pytest to verify the engine, CLI commands, and Vulkan inference:
+
+```bash
+uv run pytest -v
+# Or with standard venv:
+pytest -v
+```
+
+Expected result: `8 passed`.
+
+---
+
+### Step 4: Verify Available Models
+
+```bash
+upscalex models
+```
+
+The tool will display the pre-trained model matrix (`realesrgan-x4plus`, `realesrgan-x4plus-anime`, etc.).
+
+---
+
+### Step 5: Configure the MCP Server
+
+To enable AI agents to execute upscaling jobs autonomously, add UpscaleX to your MCP client configuration.
+
+#### Claude Desktop
+
+Configuration file paths:
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+Add the following entry under `"mcpServers"`:
+
+```json
+{
+  "mcpServers": {
+    "upscalex": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/upscalex",
+        "upscalex-mcp"
+      ]
+    }
+  }
+}
+```
+
+#### Cursor IDE
+
+Add to `.cursor/mcp.json` or your project settings:
+
+```json
+{
+  "mcpServers": {
+    "upscalex": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/upscalex",
+        "upscalex-mcp"
+      ]
+    }
+  }
+}
+```
+
+---
+
+### Step 6: Test Upscaling
+
+Run a test upscale on any image:
+
+```bash
+upscalex upscale input.png --target 16k
+```
+
+Output file `input_16k.png` will be generated in the same directory.

upscalex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arunmozhi Varman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

upscalex-0.1.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.5
+Name: upscalex
+Version: 0.1.0
+Summary: UpscaleX MCP/CLI: Production-grade 8K/16K image upscaler CLI and Model Context Protocol (MCP) server powered by RealESRGAN, Vulkan GPU acceleration, and Lanczos supersampling.
+Project-URL: Homepage, https://github.com/The-Open-Source-Founder/upscalex
+Project-URL: Documentation, https://github.com/The-Open-Source-Founder/upscalex#readme
+Project-URL: Repository, https://github.com/The-Open-Source-Founder/upscalex.git
+Project-URL: Issues, https://github.com/The-Open-Source-Founder/upscalex/issues
+Project-URL: Changelog, https://github.com/The-Open-Source-Founder/upscalex/releases
+Author-email: Arunmozhi Varman <arunmozhi@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: 16k,8k,ai,cli,image-processing,mcp,realesrgan,super-resolution,upscale,upscalex,vulkan
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/The-Open-Source-Founder/upscalex/main/assets/banner.png" alt="UpscaleX Banner" width="100%">
+</p>
+
+# UpscaleX MCP/CLI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP: Enabled](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
+[![Acceleration: Vulkan GPU](https://img.shields.io/badge/Acceleration-Vulkan%20GPU-orange.svg)](https://www.khronos.org/vulkan/)
+
+UpscaleX is a production-grade 8K and 16K image upscaler CLI and Model Context Protocol (MCP) server powered by RealESRGAN, Vulkan GPU hardware acceleration, and Lanczos supersampling.
+
+Engineered for digital print workflows, large-format poster production, fine art reproductions, and autonomous AI coding agents in Claude Desktop, Antigravity, and Cursor.
+
+> Looking for quick setup? Read the [Installation Guide](INSTALLATION.md) for a copy-paste AI Agent setup prompt and manual instructions, or provide your AI coding assistant with the [UpscaleX Agent Skill](SKILLS.md).
+
+---
+
+## Table of Contents
+
+- [Key Features](#key-features)
+- [Installation Guide](INSTALLATION.md)
+- [AI Agent Skill](SKILLS.md)
+- [Visual Quality Comparison](#visual-quality-comparison)
+- [Documentation Directory](#documentation-directory)
+- [Quickstart with uv](#quickstart-with-uv)
+- [Command-Line Interface](#command-line-interface)
+- [Model Context Protocol (MCP) Integration](#model-context-protocol-mcp-integration)
+- [Model Matrix](#model-matrix)
+- [Testing and Verification](#testing-and-verification)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Key Features
+
+- **Dual-Mode Operation**: Interactive command-line interface (`upscalex`) and standard Model Context Protocol server (`upscalex-mcp`).
+- **8K and 16K Presets**:
+  - **16K**: Native 4x RealESRGAN deep-learning model upscale producing master files up to 400+ Megapixels.
+  - **8K**: 4x deep-learning inference followed by Lanczos-3 downsampling (Supersampling Anti-Aliasing / SSAA) for sharp edges and zero noise.
+  - **Custom Dimensions**: Proportional scaling to arbitrary resolutions or physical print aspect ratios.
+- **Cross-Platform Architecture**: Tested and supported across **Windows**, **Linux** (Ubuntu, Debian, Fedora), and **macOS** (Apple Silicon arm64 & Intel x86_64).
+- **GPU Acceleration with Seamless CPU Fallback**: Automatically discovers and utilizes discrete Vulkan GPUs (NVIDIA RTX/GeForce, AMD Radeon, Intel Arc/Iris, Apple Silicon via MoltenVK). In headless Docker containers or environments without GPU drivers, the engine falls back to multi-threaded CPU Lanczos super-resolution with zero crashes.
+- **Hardware Diagnostics**: Integrated `upscalex doctor` command inspects system compute devices, Vulkan support, and recommended tile dimensions.
+- **Memory-Safe Tiling**: Sliding-window spatial tile decomposition (`--tile-size 256`) processes ultra-gigapixel images without Out-Of-Memory (OOM) failures on 4GB to 8GB GPUs.
+- **Automated Engine Provisioning**: Downloads and validates the precompiled platform binary automatically if not found locally.
+- **Print Fidelity Analysis**: Automatically calculates physical print dimensions in inches and centimeters at 300 DPI, 150 DPI, and 72 DPI.
+
+---
+
+## Visual Quality Comparison
+
+Below is an empirical comparison demonstrating UpscaleX 4x super-resolution reconstruction on a low-resolution pixelated source (`663 × 531` px, 0.35 MP) upscaled to high-definition print fidelity (`2,652 × 2,124` px, 5.63 MP) using the `realesrgan-x4plus` model.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/The-Open-Source-Founder/upscalex/main/assets/comparison.png" alt="UpscaleX Quality Comparison" width="100%">
+</p>
+
+| Metric | Original Source | UpscaleX 4x Output |
+| :--- | :--- | :--- |
+| **Pixel Dimensions** | `663 × 531` | **`2,652 × 2,124`** |
+| **Total Megapixels** | 0.35 MP | **5.63 MP** (16× Pixel Multiplication) |
+| **Edge Reconstruction** | Heavy block pixelation, ringing | Reconstructed circular spokes, sharp contours |
+| **Max 300 DPI Print Size** | 2.2 × 1.8 inches | **8.8 × 7.1 inches** |
+| **Model** | — | `realesrgan-x4plus` |
+| **Hardware** | — | NVIDIA GeForce RTX 3050 Laptop GPU (10.8s) |
+
+---
+
+## Documentation Directory
+
+Comprehensive technical guides are available in the [`docs/`](docs/) directory and repository root:
+
+- [Installation Guide](INSTALLATION.md): AI Agent autonomous copy-paste prompt and manual installation procedures.
+- [AI Agent Skill Specification](SKILLS.md): Standard agent skill definition for Claude, Cursor, and Antigravity.
+- [CLI Reference Guide](docs/cli-guide.md): Complete flag documentation, tiling strategies, and execution examples.
+- [Model Context Protocol (MCP) Guide](docs/mcp-guide.md): JSON-RPC tool contracts, parameter schemas, and multi-client configuration.
+- [Architecture & Mathematics Specification](docs/architecture.md): Deep-learning foundations, RRDB networks, Lanczos kernels, and memory bounds.
+- [Contributing Guide](CONTRIBUTING.md): Code standards, test procedures, and pull request workflow.
+
+---
+
+## Quickstart
+
+### Option 1: Install from PyPI (Simplest for CLI & MCP)
+
+```bash
+pip install upscalex
+```
+
+### Option 2: Clone and Install from Source (with uv)
+
+```bash
+git clone https://github.com/The-Open-Source-Founder/upscalex.git
+cd upscalex
+
+# Create virtual environment and install package
+uv venv
+uv pip install -e .
+```
+
+### Inspect Available Models
+
+```bash
+upscalex models
+```
+
+---
+
+## Command-Line Interface
+
+### 16K Upscale (Default 4x Model)
+
+```bash
+upscalex upscale input.png --target 16k
+```
+
+### 8K Supersampled Upscale
+
+```bash
+upscalex upscale poster.png --target 8k -o poster_8k.png
+```
+
+### 2D Illustration / Anime Artwork
+
+```bash
+upscalex upscale graphic.png --model realesrgan-x4plus-anime --target 8k
+```
+
+### Image and Print Sizing Inspection
+
+```bash
+upscalex info input.png
+```
+
+### Hardware and Content-Aware Model Recommendation
+
+```bash
+upscalex recommend input.png
+```
+
+For complete options and arguments, see the [CLI Guide](docs/cli-guide.md).
+
+---
+
+## Model Context Protocol (MCP) Integration
+
+UpscaleX runs as a native MCP server, enabling LLM agents to inspect image properties, evaluate print viability, and execute upscaling autonomously.
+
+### Server Invocation
+
+```bash
+upscalex-mcp
+# or
+upscalex serve
+```
+
+### Client Configuration
+
+Add this entry to your MCP client configuration file:
+
+```json
+{
+  "mcpServers": {
+    "upscalex": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/path/to/upscalex",
+        "upscalex-mcp"
+      ]
+    }
+  }
+}
+```
+
+Detailed configuration instructions for Claude Desktop, Antigravity, and Cursor are provided in the [MCP Guide](docs/mcp-guide.md).
+
+---
+
+## Model Matrix and Catalog
+
+UpscaleX supports both pre-packaged core models and on-demand downloadable community models:
+
+| Model ID | Scale | Target Media | VRAM Requirement | Status | Description |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| `realesrgan-x4plus` | 4x | Photos / Fine Art | Medium (4GB VRAM) | **Installed** | Flagship model for high-fidelity photography, art, and exhibition posters. |
+| `realesrgan-x4plus-anime` | 4x | Anime / Illustration | Medium (4GB VRAM) | **Installed** | Preserves flat colors, sharp contours, and line definition in 2D illustrations. |
+| `realesr-animevideov3-x4` | 4x | Video / Fast Previews | Low (1GB-2GB / CPU) | **Installed** | Lightweight 4x feed-forward model for fast turnaround and low-spec systems. |
+| `realesr-animevideov3-x2` | 2x | Animation / Video | Low (1GB-2GB / CPU) | **Installed** | Fast 2x model for video frames, icons, and lightweight web assets. |
+| `realesr-animevideov3-x3` | 3x | Animation / Video | Low (1GB-2GB / CPU) | **Installed** | Fast 3x model for intermediate scaling. |
+| `realesr-general-x4v3` | 4x | General / Compact | Low (2GB VRAM) | **Installed** | Official compact general model with low memory consumption. |
+| `4x-ultrasharp` | 4x | Portraits / Ultra-Detail | Medium-High (4GB-6GB) | Downloadable | Community champion for micro-textures, portraits, fabrics, and skin. |
+| `4x-nmkd-superscale` | 4x | Clean Photorealistic | Medium-High (4GB-6GB) | Downloadable | Trained on clean photography; preserves hair, threads, and foliage. |
+| `realesrgan-anime-6b` | 4x | Anime / Fast | Low (1GB-2GB / CPU) | Downloadable | 6-block lightweight anime model for rapid processing. |
+
+### Download Additional Models
+
+Download models through the CLI or via the `download_model` MCP tool:
+
+```bash
+# Download 4x UltraSharp for portraits
+upscalex download-model 4x-ultrasharp
+
+# Download NMKD clean photo model
+upscalex download-model 4x-nmkd-superscale
+```
+
+---
+
+## Testing and Verification
+
+Run the test suite to verify model resolution calculation, CLI exit codes, and live GPU inference:
+
+```bash
+uv pip install -e ".[dev]"
+uv run pytest -v
+```
+
+All tests must pass prior to submitting changes.
+
+---
+
+## Contributing
+
+Contributions to UpscaleX are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards, pull request processes, and development guidelines.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.