# NanoWait: The Adaptive Wait Engine for Python

[![PyPI version](https://img.shields.io/pypi/v/nano_wait.svg)](https://pypi.org/project/nano_wait/)
[![License](https://img.shields.io/pypi/l/nano_wait.svg)](https://github.com/luizfilipe/NanoWait/blob/main/LICENSE)
[![Python Version](https://img.shields.io/pypi/pyversions/nano_wait.svg)](https://pypi.org/project/nano_wait/)

## 🚀 What is NanoWait?

**NanoWait** is a deterministic and adaptive execution wait engine designed to replace Python’s standard `time.sleep()`.

Instead of waiting a fixed amount of time, NanoWait dynamically adjusts the effective wait duration based on **system load (CPU/RAM)** and optionally **Wi‑Fi signal strength**, ensuring automation scripts remain reliable across slow or overloaded environments.

> **In short:** you request a base time (e.g. `wait(5)`), and NanoWait guarantees a *safe, context‑aware wait* that never exceeds the requested time and never drops below a minimal execution floor.

---

## 🛠️ Installation

```bash
pip install nano_wait
```

### Optional Module — Vision Mode

Visual waiting (icon/state detection) was intentionally moved to a dedicated package to keep NanoWait lightweight and deterministic.

```bash
pip install nano-wait-vision
```

If Vision Mode is not installed, NanoWait will raise a clear runtime error when visual features are requested.

---

## 💡 Quick Start

```python
from nano_wait import wait
import time

# Standard sleep
start = time.time()
time.sleep(5)
print(f"time.sleep(): {time.time() - start:.2f}s")

# Adaptive wait
start = time.time()
wait(5)
print(f"nano_wait.wait(): {time.time() - start:.2f}s")
```

NanoWait **never waits longer than the requested base time** and applies a minimum internal delay of **50 ms** to prevent CPU overuse.

---

## ⚙️ Core API

```python
wait(
    t: float | None = None,
    *,
    wifi: str | None = None,
    speed: str | float = "normal",
    smart: bool = False,
    verbose: bool = False,
    log: bool = False
) -> float
```

### Parameters

| Parameter | Description                                             |
| --------- | ------------------------------------------------------- |
| `t`       | Base time in seconds (required for time‑based waiting). |
| `wifi`    | Optional Wi‑Fi SSID used to evaluate signal quality.    |
| `speed`   | Execution speed preset or numeric value.                |
| `smart`   | Enables Smart Context Mode (dynamic speed calculation). |
| `verbose` | Prints debug information to stdout.                     |
| `log`     | Writes execution data to `nano_wait.log`.               |

---

## 🧠 Smart Context Mode (`smart=True`)

When enabled, NanoWait calculates the execution speed automatically based on the **average system context score**.

```python
wait(10, smart=True, verbose=True)
```

Example output:

```
[NanoWait] speed=3.42 factor=2.05 wait=4.878s
```

### How Smart Speed Works

* PC Score → derived from CPU and memory usage
* Wi‑Fi Score → derived from RSSI (if enabled)

The final **Smart Speed** is:

```
speed = clamp( (pc_score + wifi_score) / 2 , 0.5 , 5.0 )
```

This value is used directly as the execution speed factor.

---

## 🌐 Wi‑Fi Awareness

If your automation depends on network stability, NanoWait can adapt waiting behavior based on Wi‑Fi signal strength.

```python
wait(5, wifi="Office_Network")
```

Supported platforms:

* Windows (`pywifi`)
* macOS (`airport`)
* Linux (`nmcli`)

If Wi‑Fi data cannot be read, NanoWait safely falls back to neutral values.

---

## ⚡ Execution Speed Presets

NanoWait supports symbolic speed presets as well as numeric values.

| Preset   | Internal Value |
| -------- | -------------- |
| `slow`   | 0.8            |
| `normal` | 1.5            |
| `fast`   | 3.0            |
| `ultra`  | 6.0            |

```python
wait(2, speed="fast")
wait(2, speed=2.2)
```

Higher speeds reduce the nominal wait more aggressively.

---

## 🔬 How NanoWait Computes Time

### System Context Scores

| Score       | Range | Meaning                |
| ----------- | ----- | ---------------------- |
| PC Score    | 0–10  | CPU & RAM availability |
| Wi‑Fi Score | 0–10  | Signal quality         |

### Adjustment Factor

The adjustment factor is calculated as:

```
factor = max(0.2, (10 - risk) / speed)
```

Where:

```
risk = (pc_score + wifi_score) / 2
```

### Final Wait Time

```
wait_time = clamp( t / factor , 0.05 , t )
```

Guarantees:

* Never waits longer than `t`
* Never waits less than **50 ms**
* Deterministic across executions

---

## 🖥️ Command Line Interface (CLI)

NanoWait can be executed directly from the terminal:

```bash
nano-wait <time> [options]
```

Example:

```bash
nano-wait 5 --smart --verbose
```

Available flags:

* `--wifi SSID`
* `--speed slow|normal|fast|ultra`
* `--smart`
* `--verbose`
* `--log`

---

## 👁️ Visual Wait (Optional)

Visual waiting features (icons, UI states) are lazily loaded and require:

```bash
pip install nano-wait-vision
```

If not installed, NanoWait raises a clear `ImportError` explaining how to enable the feature.

---

## 🧪 Design Guarantees

* Deterministic behavior
* No busy‑waiting
* Safe fallback paths
* Cross‑platform support
* Production‑ready API

---

## 🤝 Contribution & License

NanoWait is open‑source and MIT‑licensed.

Issues, discussions, and pull requests are welcome.

**Author:** Luiz Filipe Seabra de Marco
**License:** MIT
