Proposal: Integrate NanoWait as an Adaptive Replacement for time.sleep() #64
Description
I would like to propose integrating NanoWait as an optional dependency in botcity-framework-core-python to improve the reliability, determinism, and performance of wait operations in automation workflows.
NanoWait is a system-aware, deterministic adaptive wait engine designed to replace Python’s time.sleep(), which is often unreliable in real-world automation environments.
🔍 Problem with time.sleep() in Automation
time.sleep() assumes ideal execution conditions. In practice, automation bots frequently run under:
- High CPU or RAM usage
- Network instability
- Virtualized or shared environments
- UI or backend latency variation
This causes:
- Under-waiting → flaky executions
- Over-waiting → unnecessary performance loss
- Manual tuning of sleep times that doesn't generalize
💡 Proposed Solution: NanoWait
NanoWait dynamically adjusts the effective wait duration based on system context while preserving strict execution guarantees.
Key Guarantees
- ✅ Never waits longer than the requested time
- ✅ Never waits less than 50 ms (prevents busy-waiting)
- ✅ Deterministic and reproducible
- ✅ No busy loops
- ✅ Cross-platform (Windows, macOS, Linux)
- ✅ MIT licensed
📦 Installation
pip install nano-waitOptional visual waiting features:
pip install nano-wait-vision🔧 Minimal Integration Example
Current pattern
import time
time.sleep(5)Proposed drop-in replacement
from nano_wait import wait
wait(5)No behavior change in healthy environments, but significantly more robust under load.
🧠 Smart Context Mode (Recommended)
NanoWait can automatically compute execution speed based on real-time system context:
from nano_wait import wait
wait(5, smart=True)With debug output:
wait(5, smart=True, verbose=True)Example output:
[NanoWait] speed=3.42 factor=2.05 wait=4.878s
🌐 Network-Aware Waiting (Optional)
For bots that depend on backend responses or web UI stability:
wait(5, wifi="Office_Network")If Wi-Fi data cannot be read, NanoWait safely falls back to neutral behavior.
⚙️ Execution Speed Presets
wait(2, speed="fast")
wait(2, speed=2.2)| Preset | Internal Value |
|---|---|
| slow | 0.8 |
| normal | 1.5 |
| fast | 3.0 |
| ultra | 6.0 |
🔬 How NanoWait Works (High Level)
System Context Scores
- PC Score (0–10): CPU and RAM availability
- Wi-Fi Score (0–10): Signal quality (optional)
Adjustment Factor
factor = max(0.2, (10 - risk) / speed)Where:
risk = (pc_score + wifi_score) / 2Final Wait Time
wait_time = clamp(t / factor, 0.05, t)Guarantees
- Never exceeds the requested time
- Never drops below 50 ms
- Deterministic across executions
🧩 Suggested Integration Strategy
- Add NanoWait as an optional dependency
- Internally replace critical
time.sleep()calls - Or expose a helper API, e.g.:
from botcity.wait import adaptive_waitWhich internally delegates to NanoWait when available.
🤝 Why This Fits BotCity
- BotCity focuses on reliable, production-grade automation
- NanoWait directly addresses flaky timing issues
- Zero breaking changes
- Minimal API surface
- Lightweight and deterministic
- Already designed for automation use cases
📎 Project Information
| Field | Value |
|---|---|
| Name | NanoWait |
| Version | 4.0.0 (latest) |
| License | MIT |
| Author | Luiz Filipe Seabra de Marco |
| PyPI | pip install nano-wait |
I would be happy to open a PR or help with a proof-of-concept integration if this proposal aligns with the project’s goals.
Thank you for your time and for maintaining BotCity!