upscalex 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,268 @@
1
+ Metadata-Version: 2.5
2
+ Name: upscalex
3
+ Version: 0.1.0
4
+ 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.
5
+ Project-URL: Homepage, https://github.com/The-Open-Source-Founder/upscalex
6
+ Project-URL: Documentation, https://github.com/The-Open-Source-Founder/upscalex#readme
7
+ Project-URL: Repository, https://github.com/The-Open-Source-Founder/upscalex.git
8
+ Project-URL: Issues, https://github.com/The-Open-Source-Founder/upscalex/issues
9
+ Project-URL: Changelog, https://github.com/The-Open-Source-Founder/upscalex/releases
10
+ Author-email: Arunmozhi Varman <arunmozhi@example.com>
11
+ License: MIT
12
+ License-File: LICENSE
13
+ Keywords: 16k,8k,ai,cli,image-processing,mcp,realesrgan,super-resolution,upscale,upscalex,vulkan
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: End Users/Desktop
17
+ Classifier: License :: OSI Approved :: MIT License
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Multimedia :: Graphics
25
+ Requires-Python: >=3.10
26
+ Requires-Dist: click>=8.1.0
27
+ Requires-Dist: fastmcp>=0.4.0
28
+ Requires-Dist: pillow>=10.0.0
29
+ Requires-Dist: rich>=13.0.0
30
+ Provides-Extra: dev
31
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
32
+ Description-Content-Type: text/markdown
33
+
34
+ <p align="center">
35
+ <img src="https://raw.githubusercontent.com/The-Open-Source-Founder/upscalex/main/assets/banner.png" alt="UpscaleX Banner" width="100%">
36
+ </p>
37
+
38
+ # UpscaleX MCP/CLI
39
+
40
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
41
+ [![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
42
+ [![MCP: Enabled](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
43
+ [![Acceleration: Vulkan GPU](https://img.shields.io/badge/Acceleration-Vulkan%20GPU-orange.svg)](https://www.khronos.org/vulkan/)
44
+
45
+ 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.
46
+
47
+ Engineered for digital print workflows, large-format poster production, fine art reproductions, and autonomous AI coding agents in Claude Desktop, Antigravity, and Cursor.
48
+
49
+ > 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).
50
+
51
+ ---
52
+
53
+ ## Table of Contents
54
+
55
+ - [Key Features](#key-features)
56
+ - [Installation Guide](INSTALLATION.md)
57
+ - [AI Agent Skill](SKILLS.md)
58
+ - [Visual Quality Comparison](#visual-quality-comparison)
59
+ - [Documentation Directory](#documentation-directory)
60
+ - [Quickstart with uv](#quickstart-with-uv)
61
+ - [Command-Line Interface](#command-line-interface)
62
+ - [Model Context Protocol (MCP) Integration](#model-context-protocol-mcp-integration)
63
+ - [Model Matrix](#model-matrix)
64
+ - [Testing and Verification](#testing-and-verification)
65
+ - [Contributing](#contributing)
66
+ - [License](#license)
67
+
68
+ ---
69
+
70
+ ## Key Features
71
+
72
+ - **Dual-Mode Operation**: Interactive command-line interface (`upscalex`) and standard Model Context Protocol server (`upscalex-mcp`).
73
+ - **8K and 16K Presets**:
74
+ - **16K**: Native 4x RealESRGAN deep-learning model upscale producing master files up to 400+ Megapixels.
75
+ - **8K**: 4x deep-learning inference followed by Lanczos-3 downsampling (Supersampling Anti-Aliasing / SSAA) for sharp edges and zero noise.
76
+ - **Custom Dimensions**: Proportional scaling to arbitrary resolutions or physical print aspect ratios.
77
+ - **Cross-Platform Architecture**: Tested and supported across **Windows**, **Linux** (Ubuntu, Debian, Fedora), and **macOS** (Apple Silicon arm64 & Intel x86_64).
78
+ - **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.
79
+ - **Hardware Diagnostics**: Integrated `upscalex doctor` command inspects system compute devices, Vulkan support, and recommended tile dimensions.
80
+ - **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.
81
+ - **Automated Engine Provisioning**: Downloads and validates the precompiled platform binary automatically if not found locally.
82
+ - **Print Fidelity Analysis**: Automatically calculates physical print dimensions in inches and centimeters at 300 DPI, 150 DPI, and 72 DPI.
83
+
84
+ ---
85
+
86
+ ## Visual Quality Comparison
87
+
88
+ 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.
89
+
90
+ <p align="center">
91
+ <img src="https://raw.githubusercontent.com/The-Open-Source-Founder/upscalex/main/assets/comparison.png" alt="UpscaleX Quality Comparison" width="100%">
92
+ </p>
93
+
94
+ | Metric | Original Source | UpscaleX 4x Output |
95
+ | :--- | :--- | :--- |
96
+ | **Pixel Dimensions** | `663 × 531` | **`2,652 × 2,124`** |
97
+ | **Total Megapixels** | 0.35 MP | **5.63 MP** (16× Pixel Multiplication) |
98
+ | **Edge Reconstruction** | Heavy block pixelation, ringing | Reconstructed circular spokes, sharp contours |
99
+ | **Max 300 DPI Print Size** | 2.2 × 1.8 inches | **8.8 × 7.1 inches** |
100
+ | **Model** | — | `realesrgan-x4plus` |
101
+ | **Hardware** | — | NVIDIA GeForce RTX 3050 Laptop GPU (10.8s) |
102
+
103
+ ---
104
+
105
+ ## Documentation Directory
106
+
107
+ Comprehensive technical guides are available in the [`docs/`](docs/) directory and repository root:
108
+
109
+ - [Installation Guide](INSTALLATION.md): AI Agent autonomous copy-paste prompt and manual installation procedures.
110
+ - [AI Agent Skill Specification](SKILLS.md): Standard agent skill definition for Claude, Cursor, and Antigravity.
111
+ - [CLI Reference Guide](docs/cli-guide.md): Complete flag documentation, tiling strategies, and execution examples.
112
+ - [Model Context Protocol (MCP) Guide](docs/mcp-guide.md): JSON-RPC tool contracts, parameter schemas, and multi-client configuration.
113
+ - [Architecture & Mathematics Specification](docs/architecture.md): Deep-learning foundations, RRDB networks, Lanczos kernels, and memory bounds.
114
+ - [Contributing Guide](CONTRIBUTING.md): Code standards, test procedures, and pull request workflow.
115
+
116
+ ---
117
+
118
+ ## Quickstart
119
+
120
+ ### Option 1: Install from PyPI (Simplest for CLI & MCP)
121
+
122
+ ```bash
123
+ pip install upscalex
124
+ ```
125
+
126
+ ### Option 2: Clone and Install from Source (with uv)
127
+
128
+ ```bash
129
+ git clone https://github.com/The-Open-Source-Founder/upscalex.git
130
+ cd upscalex
131
+
132
+ # Create virtual environment and install package
133
+ uv venv
134
+ uv pip install -e .
135
+ ```
136
+
137
+ ### Inspect Available Models
138
+
139
+ ```bash
140
+ upscalex models
141
+ ```
142
+
143
+ ---
144
+
145
+ ## Command-Line Interface
146
+
147
+ ### 16K Upscale (Default 4x Model)
148
+
149
+ ```bash
150
+ upscalex upscale input.png --target 16k
151
+ ```
152
+
153
+ ### 8K Supersampled Upscale
154
+
155
+ ```bash
156
+ upscalex upscale poster.png --target 8k -o poster_8k.png
157
+ ```
158
+
159
+ ### 2D Illustration / Anime Artwork
160
+
161
+ ```bash
162
+ upscalex upscale graphic.png --model realesrgan-x4plus-anime --target 8k
163
+ ```
164
+
165
+ ### Image and Print Sizing Inspection
166
+
167
+ ```bash
168
+ upscalex info input.png
169
+ ```
170
+
171
+ ### Hardware and Content-Aware Model Recommendation
172
+
173
+ ```bash
174
+ upscalex recommend input.png
175
+ ```
176
+
177
+ For complete options and arguments, see the [CLI Guide](docs/cli-guide.md).
178
+
179
+ ---
180
+
181
+ ## Model Context Protocol (MCP) Integration
182
+
183
+ UpscaleX runs as a native MCP server, enabling LLM agents to inspect image properties, evaluate print viability, and execute upscaling autonomously.
184
+
185
+ ### Server Invocation
186
+
187
+ ```bash
188
+ upscalex-mcp
189
+ # or
190
+ upscalex serve
191
+ ```
192
+
193
+ ### Client Configuration
194
+
195
+ Add this entry to your MCP client configuration file:
196
+
197
+ ```json
198
+ {
199
+ "mcpServers": {
200
+ "upscalex": {
201
+ "command": "uv",
202
+ "args": [
203
+ "run",
204
+ "--directory",
205
+ "/path/to/upscalex",
206
+ "upscalex-mcp"
207
+ ]
208
+ }
209
+ }
210
+ }
211
+ ```
212
+
213
+ Detailed configuration instructions for Claude Desktop, Antigravity, and Cursor are provided in the [MCP Guide](docs/mcp-guide.md).
214
+
215
+ ---
216
+
217
+ ## Model Matrix and Catalog
218
+
219
+ UpscaleX supports both pre-packaged core models and on-demand downloadable community models:
220
+
221
+ | Model ID | Scale | Target Media | VRAM Requirement | Status | Description |
222
+ | :--- | :--- | :--- | :--- | :--- | :--- |
223
+ | `realesrgan-x4plus` | 4x | Photos / Fine Art | Medium (4GB VRAM) | **Installed** | Flagship model for high-fidelity photography, art, and exhibition posters. |
224
+ | `realesrgan-x4plus-anime` | 4x | Anime / Illustration | Medium (4GB VRAM) | **Installed** | Preserves flat colors, sharp contours, and line definition in 2D illustrations. |
225
+ | `realesr-animevideov3-x4` | 4x | Video / Fast Previews | Low (1GB-2GB / CPU) | **Installed** | Lightweight 4x feed-forward model for fast turnaround and low-spec systems. |
226
+ | `realesr-animevideov3-x2` | 2x | Animation / Video | Low (1GB-2GB / CPU) | **Installed** | Fast 2x model for video frames, icons, and lightweight web assets. |
227
+ | `realesr-animevideov3-x3` | 3x | Animation / Video | Low (1GB-2GB / CPU) | **Installed** | Fast 3x model for intermediate scaling. |
228
+ | `realesr-general-x4v3` | 4x | General / Compact | Low (2GB VRAM) | **Installed** | Official compact general model with low memory consumption. |
229
+ | `4x-ultrasharp` | 4x | Portraits / Ultra-Detail | Medium-High (4GB-6GB) | Downloadable | Community champion for micro-textures, portraits, fabrics, and skin. |
230
+ | `4x-nmkd-superscale` | 4x | Clean Photorealistic | Medium-High (4GB-6GB) | Downloadable | Trained on clean photography; preserves hair, threads, and foliage. |
231
+ | `realesrgan-anime-6b` | 4x | Anime / Fast | Low (1GB-2GB / CPU) | Downloadable | 6-block lightweight anime model for rapid processing. |
232
+
233
+ ### Download Additional Models
234
+
235
+ Download models through the CLI or via the `download_model` MCP tool:
236
+
237
+ ```bash
238
+ # Download 4x UltraSharp for portraits
239
+ upscalex download-model 4x-ultrasharp
240
+
241
+ # Download NMKD clean photo model
242
+ upscalex download-model 4x-nmkd-superscale
243
+ ```
244
+
245
+ ---
246
+
247
+ ## Testing and Verification
248
+
249
+ Run the test suite to verify model resolution calculation, CLI exit codes, and live GPU inference:
250
+
251
+ ```bash
252
+ uv pip install -e ".[dev]"
253
+ uv run pytest -v
254
+ ```
255
+
256
+ All tests must pass prior to submitting changes.
257
+
258
+ ---
259
+
260
+ ## Contributing
261
+
262
+ Contributions to UpscaleX are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards, pull request processes, and development guidelines.
263
+
264
+ ---
265
+
266
+ ## License
267
+
268
+ This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,10 @@
1
+ upscalex/__init__.py,sha256=YZ8yw8hMk3Cj8MAjiiLqX2O0dSBijlCJxm21vyIzsGI,261
2
+ upscalex/cli.py,sha256=QtuqCjqq6qVtrCp6LT0b8UFUp-ZQp441JKfKR3gsbl0,12152
3
+ upscalex/engine.py,sha256=Dvos6FhA8ohqfeAzabKC3FUksbVrrLf4NaDskkVgS50,29641
4
+ upscalex/server.py,sha256=QoTY3Rj9ssyOMldk3yGNUraqe8D3O4l6NqHF9lyXuxc,8261
5
+ upscalex/utils.py,sha256=aySedZBY9uMrhIkVkV-SniF8TwzqCivQ5QmpQZsIVCY,6936
6
+ upscalex-0.1.0.dist-info/METADATA,sha256=kypryysql5FPMRBHL3EZe4M5Nrx5g49ZsoMwRTzW2gE,11004
7
+ upscalex-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
8
+ upscalex-0.1.0.dist-info/entry_points.txt,sha256=0nFVDvlksZDXc5a6UU2N0Y6HK4H_r3aELmvJ_BqKmk8,83
9
+ upscalex-0.1.0.dist-info/licenses/LICENSE,sha256=elQj-rrobIEPAYk4RFLHqtytjvGRm82hUqb_2Zlzif4,1073
10
+ upscalex-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ upscalex = upscalex.cli:main
3
+ upscalex-mcp = upscalex.server:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arunmozhi Varman
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.