Metadata-Version: 2.4
Name: fasthardware
Version: 2.1.0
Summary: A zero-configuration hardware acceleration library for Python.
Home-page: https://github.com/yourusername/fasthardware
Author: 최운교
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: System :: Hardware
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: psutil
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ⚡ fasthardware

**A zero-configuration hardware acceleration library for Python.**  
Squeeze every last FPS out of your system with a single function call — covering OS scheduling, CPU threading, GPU inference, and memory management.

---

## 🚀 Installation

```bash
pip install fasthardware
```

---

## 🔥 Quick Start

```python
from fasthardware import fasthardware

# Call once at startup — automatically detects and optimizes your hardware
fasthardware.speedup()

# Your code here
...

# Periodically sweep RAM fragmentation (recommended every 60s)
fasthardware.manual_sweep()
```

---

## 🧠 What does it do?

`fasthardware` automatically detects your hardware and applies the most effective low-level optimizations — no manual configuration needed.

### `speedup(mode="DEFAULT")`

| Layer | Optimization | Description |
|---|---|---|
| **OS** | Process Priority Elevation | Calls kernel APIs directly to set process to HIGH priority |
| **CPU** | C Library Thread Binding | Sets `OMP / MKL / OPENBLAS / NUMEXPR` threads to max cores |
| **GC** | Stutter Prevention | Disables Python GC to eliminate random frame drops |
| **CUDA** | cuDNN Benchmark + TF32 | Auto-selects optimal kernels; enables TF32 on Ampere+ GPUs |
| **OpenVINO** | iGPU LATENCY hint + Model Cache | Minimizes inference latency; caches compiled models to disk |
| **OpenCV** | SIMD + OpenCL | Forces AVX/SSE acceleration and OpenCL parallel backend |

> Only installed libraries are optimized — missing ones are silently skipped.

#### ULTIMATE mode
```python
fasthardware.speedup(mode="ULTIMATE")
```
Additionally detects all child processes (multiprocessing workers) and:
- Elevates their OS priority
- Pins each worker to a dedicated CPU core for zero cache contention

---

### `get_core()` — OpenVINO Core Singleton

After calling `speedup()`, fasthardware holds an optimized OpenVINO `Core` instance internally.  
Instead of creating your own `ov.Core()`, reuse this to inherit all applied optimizations:

```python
from fasthardware import fasthardware
import openvino as ov

fasthardware.speedup()

# ✅ Reuse the pre-optimized Core — LATENCY hint + model cache already applied
core = fasthardware.get_core()

compiled_model = core.compile_model("model.xml", "GPU")
```

> If you create `ov.Core()` manually after `speedup()`, the `PERFORMANCE_HINT` set by fasthardware will not carry over. Use `get_core()` to avoid this.

---

### `manual_sweep()`

Goes beyond Python's `gc.collect()` — performs a full 3-generation GC sweep and calls OS-level memory APIs to return fragmented RAM back to the system.

| Platform | Method |
|---|---|
| **Windows** | `SetProcessWorkingSetSize(-1, -1)` via `kernel32` |
| **Linux** | `malloc_trim(0)` via `libc` |

Recommended: call every 60 seconds in long-running inference loops.

---

## 🎯 Designed For

- Real-time computer vision pipelines (YOLOv8, OpenVINO, OpenCV)
- High-FPS webcam inference loops
- Edge AI on Intel iGPU / N-series / Core Ultra
- Multiprocessing workloads needing tight CPU affinity control
- Any Python app where consistent, stutter-free performance matters

---

## 📊 Real-World Results

Tested on **Intel N100 (integrated GPU)** running YOLOv8n-pose with OpenVINO:

| Metric | Without fasthardware | With fasthardware |
|---|---|---|
| Peak FPS | baseline | +5 ~ 15 FPS |
| Frame stutters | frequent | eliminated |
| Memory creep (long runs) | gradual degradation | suppressed |

---

## ⚙️ Full API Reference

```python
# Initialize — call once at startup
fasthardware.speedup(mode="DEFAULT")   # Standard optimization
fasthardware.speedup(mode="ULTIMATE")  # + child process supercharging

# Get the pre-optimized OpenVINO Core singleton
core = fasthardware.get_core()  # Call after speedup()

# Sweep memory — call periodically
fasthardware.manual_sweep()
```

---

## 🛡️ Safety

- Priority set to **HIGH** (not REALTIME) — system stability preserved
- GC disabled during runtime; call `gc.enable()` on exit if needed
- All kernel API calls wrapped in try/except — fails silently without permissions
- Tested on Windows 11 and Ubuntu 22.04

---

## 📄 License

MIT License

---

## 🤝 Contributing

Issues and PRs are welcome.  
If fasthardware helped your project hit a new FPS record, feel free to share it!
