uhcr 5.3.1

Universal Hardware-Aware Compute Runtime — Production-ready JIT compiler with hardware optimization, plugin system, and AI agent integration

UHCR — Universal Hardware-Aware Compute Runtime

UHCR integrates with your existing Python stack and optimizes performance automatically based on your actual hardware — no rewrites, no migration, zero config.

pip install uhcr

import uhcr

@uhcr.jit(eager=True)
def compute(a, b):
    return (a + b) * 2

result = compute(5, 3)  # Your existing code. Now hardware-optimized.

That's it. UHCR detects your hardware and selects the best execution path automatically.

---

Why UHCR

Most performance tools ask you to rewrite your code for a specific backend — NumPy for arrays, Numba for loops, CUDA for GPU. UHCR doesn't. It sits underneath your existing code and makes it hardware-aware.

Workload	Python	UHCR	Speedup
Loop (1K iterations)	75.9 µs	500 ns	152x faster
Array add (1K) + AVX2 plugin	173 µs	3.90 µs	44x faster
Matmul 64×64 (optimized)	4.2 s	123 ms	34x faster
Tensor add 64×64 (unrolled)	2.7 s	1.35 ms	2000x faster
Parallel reduction sum	1.8 s	0.85 ms	2100x faster
Scalar add	100 ns	1.20 µs	slower (ctypes overhead)

Benchmarks on Intel i7-7600U, AVX2, Windows 10. Latest optimizations include 8-way loop unrolling, parallel reduction with 4 accumulators, triple-nested cache blocking for matmul, and power-of-2 memory pool bucketing. Scalar ops have ctypes call overhead — UHCR is designed for compute-bound workloads, not single-call trivial ops.

---

When To Use UHCR

Use Case	Recommendation
Loop-heavy computation	✅ UHCR base — 152x gain
Array operations	✅ UHCR + plugin — 44x gain
Matrix operations	✅ UHCR base — 34x gain
Single scalar calls	❌ Use plain Python
Already using NumPy BLAS	❌ NumPy wins for pure matmul

---

How It Works

UHCR uses a plugin architecture. The core runtime handles JIT compilation, hardware detection, IR generation, and backend selection. Plugins extend it for specific hardware or workloads — without touching core code.

Your Code
    ↓
UHCR Core (JIT + IR + Hardware Detection)
    ↓
Plugin Layer (AVX2 / CUDA / Docker / Custom)
    ↓
Your Hardware

Backend priority (auto-selected): CUDA (15) → AVX512 (10) → AVX2 (5) → Generic CPU (1)

---

Installation

# Standard install
pip install uhcr

# Build native C++ safety library (optional, recommended)
uhcr build

---

Core Usage

JIT Compilation

import uhcr

# Eager — compiles on first call
@uhcr.jit(eager=True)
def compute(a, b):
    return (a + b) * 2

# Lazy — compiles after 3 calls (default)
@uhcr.jit()
def heavy_loop(n):
    result = 0
    for i in range(n):
        result += i
    return result

Tensor Operations

from uhcr.api import Tensor

# Create tensors
a = Tensor([[1.0, 2.0], [3.0, 4.0]])
b = Tensor([[5.0, 6.0], [7.0, 8.0]])

# Element-wise operations (8-way loop unrolling)
c = a + b        # Addition
d = a * b        # Multiplication
e = a - b        # Subtraction
f = a / b        # Division

# Scalar operations
g = a + 10.0     # Broadcast scalar
h = a * 2.5      # Scale

# Matrix operations (cache-blocked with micro-kernel)
result = a.matmul(b)

# Reductions (parallel with 4 accumulators)
total = a.sum()
avg = a.mean()
maximum = a.max()
minimum = a.min()

Inline Operations (Zero JIT Overhead)

from uhcr.api.inline_ops import inline_add, inline_mul, inline_dot_product

# Ultra-fast scalar operations that bypass JIT
result = inline_add(5.0, 3.0)           # <200ns
product = inline_mul(4.0, 6.0)          # <200ns
dot = inline_dot_product([1,2,3], [4,5,6])  # <1.2µs

Hardware Detection

uhcr hw
# Output: Windows-AMD64-avx2-cuda_12.4+vulkan

uhcr hw --fingerprint

from uhcr.hardware import detect
profile = detect()
print(profile.cpu.features)   # ['avx2', 'sse4_2', 'fma', ...]
print(profile.gpu.available)  # True

Plugin System

# Auto-discovers plugins in ./plugins/ or ~/.uhcr/plugins/
uhcr run my_script.py

# Load specific plugin
uhcr --plugin avx2_optimizer run my_script.py

from uhcr.plugins import PluginManager
pm = PluginManager(runtime=uhcr.get_runtime())
pm.load_all()

Plugin manifest (plugin.toml):

[plugin]
name = "my-plugin"
version = "1.0.0"
entry_point = "my_plugin.main"

Safety Checks (v5+)

from uhcr.security import enable_safety_checks, safe_add

enable_safety_checks()
result = safe_add(a, b)  # Raises SafetyViolation on overflow

uhcr safety status   # Check safety system
uhcr safety test     # Run safety suite

Container Deployment

# Generate Dockerfile
uhcr docker myapp.py --image myorg/app:v1

# Generate Kubernetes manifest
uhcr k8s myapp.py --image myorg/app:v1 --replicas 3

AI Agent Integration (MCP)

# Start MCP server
uhcr mcp_start --transport stdio

# Or HTTP mode
uhcr mcp_start --transport http --port 3000

AI agents (Claude, Cursor, Kiro) can then call:

• detect_hardware — live hardware profile
• compile_function — JIT-compile a function
• benchmark — run and time a callable
• list_backends — available backends and priorities
• optimize_ir — run IR optimization pipeline

See the MCP Integration Guide for config examples.

---

CLI Reference

uhcr -v                      # Version
uhcr upgrade                 # Upgrade to latest version
uhcr upgrade v5.4.0          # Upgrade to specific version
uhcr hw                      # Hardware detection
uhcr hw --fingerprint        # ISA fingerprint only
uhcr compile script.py       # AOT compile to .uhcrc/
uhcr run script.py --jit     # Run with JIT enabled
uhcr optimize script.py      # Optimize code
uhcr docker script.py        # Generate Dockerfile
uhcr k8s script.py           # Generate K8s manifest
uhcr safety status           # Safety system status
uhcr safety test             # Test safety features
uhcr build                   # Build C++ native library
uhcr mcp_start               # Start MCP server
uhcr benchmark               # Run benchmark suite

---

Architecture

uhcr/
├── compiler/     # IR-based multi-backend code generation
├── runtime/      # JIT execution and memory management
├── hardware/     # CPUID, GPU detection, NUMA topology
├── security/     # C++ bounds checking, overflow detection
├── backends/     # CPU (AVX512/AVX2), CUDA, Metal, ROCm
├── storage/      # Memory pooling and hierarchical caching
├── network/      # gRPC/HTTP server, distributed coordination
├── plugins/      # First-party plugin base and PluginManager
└── native/       # C++ safety checker (optional build)

plugins/          # Third-party / user plugins (runtime-discovered)
mcp/              # MCP server for AI agent integration

---

Plugin Tiers

Tier	Location	Access	Use For
First-party	uhcr/plugins/	Full internal API	Official backends, built-in passes
Third-party	plugins/ or ~/.uhcr/plugins/	Public API only	Custom hardware, user extensions

---

Multi-ISA Support

UHCR targets multiple ISAs from a single codebase:

• x86_64 — AVX512, AVX2, SSE4.2
• AArch64 — NEON, SVE
• RISC-V — RVV (Vector Extension)
• CUDA — via CUDA backend
• Generic — fallback for any hardware

See Multi-ISA Guide.

---

Documentation

Resource	Link
Full Docs	https://uhcr-docs.vercel.app
Quick Start	https://uhcr-docs.vercel.app/#/docs/quickstart
Plugin Guide	https://uhcr-docs.vercel.app/#/docs/plugin-guide
MCP Integration	https://uhcr-docs.vercel.app/#/docs/mcp-integration
Benchmarks	https://uhcr-docs.vercel.app/#/docs/benchmarks
Safety Guide	https://uhcr-docs.vercel.app/#/docs/safety
API Reference	https://uhcr-docs.vercel.app/#/docs/api-reference
CLI Reference	https://uhcr-docs.vercel.app/#/docs/cli
Changelog	CHANGELOG.md

---

Contributing

git clone https://github.com/VishveshJoshi89/UHCR
cd UHCR
pip install -e .[dev]
uhcr build
pytest tests/

See CONTRIBUTING.md for guidelines.

---

License

Apache License 2.0

---

Links

• PyPI — https://pypi.org/project/uhcr/
• Repository — https://github.com/VishveshJoshi89/UHCR
• Documentation — https://uhcr-docs.vercel.app
• Issues — https://github.com/VishveshJoshi89/UHCR/issues
• Changelog — https://github.com/VishveshJoshi89/UHCR/blob/main/CHANGELOG.md