Metadata-Version: 2.4
Name: uhcr
Version: 5.3.1
Summary: Universal Hardware-Aware Compute Runtime — Production-ready JIT compiler with hardware optimization, plugin system, and AI agent integration
Author-email: Vishvesh Joshi <vishvesh.joshi@uhcr.dev>
Maintainer-email: Vishvesh Joshi <vishvesh.joshi@uhcr.dev>
License: Apache-2.0
Project-URL: Homepage, https://uhcr-docs.vercel.app/
Project-URL: Repository, https://github.com/VishveshJoshi89/UHCR
Project-URL: Documentation, https://uhcr-docs.vercel.app/
Project-URL: Bug Tracker, https://github.com/VishveshJoshi89/UHCR/issues
Project-URL: Changelog, https://github.com/VishveshJoshi89/UHCR/blob/main/CHANGELOG.md
Project-URL: Safety Documentation, https://github.com/VishveshJoshi89/UHCR/blob/main/SAFETY.md
Project-URL: Benchmarks, https://uhcr-docs.vercel.app/#/docs/benchmarks
Project-URL: Plugin Guide, https://uhcr-docs.vercel.app/#/docs/plugin-guide
Project-URL: MCP Integration, https://uhcr-docs.vercel.app/#/docs/mcp-integration
Keywords: compiler,runtime,hardware,simd,avx,avx2,avx512,cuda,jit,tensor,cli,safety,security,enterprise,aot,inline-ops,optimization,kubernetes,docker,mcp,ai-agents,benchmark,vectorization,matmul,array-ops,cache-blocking,plugin-system,hardware-detection,cpuid,multi-isa,aarch64,riscv,upgrade
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: C++
Classifier: Topic :: Software Development :: Compilers
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Environment :: GPU
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: network
Requires-Dist: grpcio>=1.60.0; extra == "network"
Requires-Dist: aiohttp>=3.9.0; extra == "network"
Requires-Dist: protobuf>=4.25.0; extra == "network"
Provides-Extra: benchmark
Requires-Dist: pytest-benchmark>=4.0; extra == "benchmark"
Requires-Dist: matplotlib>=3.7.0; extra == "benchmark"
Requires-Dist: pandas>=2.0.0; extra == "benchmark"
Provides-Extra: mcp
Requires-Dist: grpcio>=1.60.0; extra == "mcp"
Requires-Dist: aiohttp>=3.9.0; extra == "mcp"
Requires-Dist: protobuf>=4.25.0; extra == "mcp"
Provides-Extra: container
Requires-Dist: pyyaml>=6.0; extra == "container"
Provides-Extra: enterprise
Requires-Dist: grpcio>=1.60.0; extra == "enterprise"
Requires-Dist: aiohttp>=3.9.0; extra == "enterprise"
Requires-Dist: protobuf>=4.25.0; extra == "enterprise"
Requires-Dist: pyyaml>=6.0; extra == "enterprise"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "enterprise"
Provides-Extra: all
Requires-Dist: grpcio>=1.60.0; extra == "all"
Requires-Dist: aiohttp>=3.9.0; extra == "all"
Requires-Dist: protobuf>=4.25.0; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: pytest-benchmark>=4.0; extra == "all"
Requires-Dist: hypothesis>=6.0; extra == "all"
Requires-Dist: matplotlib>=3.7.0; extra == "all"
Requires-Dist: pandas>=2.0.0; extra == "all"
Dynamic: license-file

# UHCR — Universal Hardware-Aware Compute Runtime

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB)](https://www.python.org/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE.txt)
[![PyPI version](https://img.shields.io/pypi/v/uhcr)](https://pypi.org/project/uhcr/)
[![Documentation](https://img.shields.io/badge/docs-uhcr--docs.vercel.app-purple)](https://uhcr-docs.vercel.app/)

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

```bash
pip install uhcr
```

```python
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

```bash
# Standard install
pip install uhcr

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

---

## Core Usage

### JIT Compilation

```python
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

```python
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)

```python
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

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

uhcr hw --fingerprint
```

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

### Plugin System

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

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

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

Plugin manifest (`plugin.toml`):
```toml
[plugin]
name = "my-plugin"
version = "1.0.0"
entry_point = "my_plugin.main"
```

### Safety Checks (v5+)

```python
from uhcr.security import enable_safety_checks, safe_add

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

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

### Container Deployment

```bash
# 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)

```bash
# 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](https://uhcr-docs.vercel.app/#/docs/mcp-integration) for config examples.

---

## CLI Reference

```bash
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](https://uhcr-docs.vercel.app/#/docs/multi-isa).

---

## 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

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

[Apache License 2.0](LICENSE.txt)

---

## 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
