🎲 random-casual

PyPI version 1.0.0

random-casual is an evolving, mutant Linear Concurrencial Generator (LCG) built from scratch. Unlike standard pseudo-random number generators that rely on static formulas, this engine morphs its own mathematical coefficients dynamically with every single draw.

It executes lighting-fast operations in RAM while ensuring long-term state persistence by writing back to an encrypted binary file (stato_generatore.bin) on the hard drive only upon reaching a specific threshold, thereby preserving your SSD's lifespan [0.1.2, cite: 1].

🚀 Key Features in V2

• Mutant LCG Engine: Uses a fixed 2³¹ modulus core where the seed, multiplier, and increment variables mutate recursively after every extraction, making external prediction virtually impossible.
• Fully Bilingual Interface (EN/IT): Natively supports dual syntax layouts. You can invoke functions and variables in English (generate_number, decimals) or use legacy Italian terms (genera_numero, decimali) for perfect backwards compatibility.
• Encrypted State & Persistence: The generator automatically secures its inner mathematical formula by writing an encrypted binary file to the disk [0.1.2, cite: 1]. Even between script restarts, the system remembers its exact mutation history without losing entropy [0.1.2, cite: 1].
• Dynamic String Extension (Infinite Decimals): When requesting high decimal precision that exceeds standard LCG bit limits, a dedicated boundary safeguard diverts the logic to generate a secondary isolated random block, combining them via protected string interpolation.
• Logarithmic Zero Padding: Implements advanced math.log10 structural alignment to calculate missing leading zeros down to the millimeter, preventing Python from stripping significant fractional values (e.g., ensuring .005 stays .005 instead of collapsing into .5).
• Advanced Anti-Repetition Shield: Features a global non-repeatable state switcher (non_repeatable). When enabled, it triggers a continuous while True loop to automatically discard duplicates.
• Public History Billboard & Controls: Keeps a globally accessible list_drawn_numbers array for analytics, paired with a dedicated clear_history() utility to flush the ledger for fresh sessions.
• Hardware Entropy Injection: Seamlessly captures micro-fluctuations in CPU clock latency (time.perf_counter_ns()) and hardware cache behavior to cook the initial Zero Seed, mixing physical noise directly into the bitwise operations [0.1.2, cite: 1].
• Dynamic Anti-Freeze Safety Breaks: Automatically calculates total range capacity ((Interval \times 10^{\text{decimals}})) and gracefully returns None if the pool is exhausted. For pure integers, a strict 75% capacity ceiling stops the wheel before rapid looping drains CPU entropy or hits hardware resonance.
• Tamper Resistance: The local state file is encrypted byte-by-byte via a secret XOR key (0x5F). If the file is modified or corrupted externally, the engine discards it and self-resets using fresh hardware entropy [0.1.2, cite: 1].

🛠️ Installation

Install the package directly from PyPI:

pip install random-casual

⚙️ Project Specifications & Architecture

• Bilingual Architecture Mapping: Internal function bindings translate parameter routing on the fly, allowing seamless cross-usage of English and Italian variables without performance drops.
• Universal Parameter Ordering: The entire library strictly enforces the layout, eliminating position-based parameters crashes.
• Absolute Operational Ranges: Built-in abs(maximum - minimo) safeguards ensure the engine never crashes with negative ranges or inverted inputs.
• Float-to-Integer Type enforcement: Internal mathematical steps explicitly cast variables to raw integers (int()) before bitwise operations, wiping away type crashes between float and integer processing.
• Optimized Write-Back Caching: Physical disk writes only happen every 100 iterations (save_threshold = 100), keeping intermediate state updates confined to memory [0.1.2, cite: 1].

🔧 Development Notes & Changelog (V2.0.1)

Every evolutionary leap brings massive architectural updates. The transition from V1 to V2 involved rewriting core mechanics, which naturally introduced minor structural friction that has now been fully resolved:

• Bilingual Variables Deployment: Added complete structural definitions for English function naming conventions (generate_number) alongside the original Italian commands.
• Secure XOR Encryption Deployment: Successfully integrated a dedicated binary writeback sequence [0.1.2, cite: 1]. The generation state is fully encrypted via a byte-level XOR mechanism (0x5F) before hit storage, preventing external reverse-engineering of the seed sequence [0.1.2, cite: 1].
• Fixed Zero-Decimal Refusal: Fixed a legacy code fragment inherited from earlier prototypes that caused execution failures specifically when decimals=0 due to unaligned capacity variables (capienza_max). Pure integers now compute flawlessly.
• Type Safety Optimization: Resolved a structural TypeError crash by ensuring explicit int() wrapping during mutant parameter shifts inside genera_stato, bridging bitwise tasks between integers and floats.
• Range Normalization: Blinded the boundary handler to execute dynamic routing even with inverted range limits, removing structural mean deviations.

💻 Usage Example

The library standardizes the signature architecture and supports both English and Italian naming conventions (both as positional and keyword arguments) for smooth integration.

Basic Generation

from random_casual import generate_number, genera_numero

#  English function name with positional arguments
num_int = generate_number(1, 100, 0)
print(f"Integer: {num_int}")

# 2. English function name with English keyword argument ('decimals')
num_dec = generate_number(1, 10, decimals=2)
print(f"Decimal (2 places): {num_dec}")

# 3. Italian function alias with Italian keyword argument ('decimali')
# for backward compatibility with version 1.0.0
num_ita = genera_numero(5, 50, decimali=4) 
print(f"Italian alias (4 places): {num_ita}")

Advanced Features: Unique Draws & History Management

import random_casual

# Activate the Advanced Anti-Repetition Shield
random_casual.non_repeatable = True

# Draw a pool of unique numbers
for _ in range(5):
    random_casual.generate_number(1, 10, decimals=0)

# Access the Public History Billboard to check extracted numbers
print("Drawn numbers database:", random_casual.list_drawn_numbers)

# Flush the ledger to clear the history for a brand new session
random_casual.clear_history()
print("Database after clear:", random_casual.list_drawn_numbers)  # Output: []