{"id":47724038,"url":"https://github.com/fardinsabid/aleam","last_synced_at":"2026-04-06T00:01:18.136Z","repository":{"id":348244558,"uuid":"1196522555","full_name":"fardinsabid/aleam","owner":"fardinsabid","description":"Aleam: True randomness for AI. Non-recursive, stateless, cryptographically secure random number generator.","archived":false,"fork":false,"pushed_at":"2026-04-02T21:08:41.000Z","size":1365,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T05:43:02.262Z","etag":null,"topics":["ai","aleam","cryptographic-random","cuda","cupy","deep-learning","distributions","entropy","gpu-acceleration","jax","machine-learning","opensource","probability","pypi","python","pytorch","random-number-generator","statistics","tensorflow","true-randomness"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fardinsabid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-30T19:29:05.000Z","updated_at":"2026-04-02T21:09:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fardinsabid/aleam","commit_stats":null,"previous_names":["fardinsabid/aleam"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/fardinsabid/aleam","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardinsabid%2Faleam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardinsabid%2Faleam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardinsabid%2Faleam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardinsabid%2Faleam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fardinsabid","download_url":"https://codeload.github.com/fardinsabid/aleam/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fardinsabid%2Faleam/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31379453,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T21:40:47.592Z","status":"ssl_error","status_checked_at":"2026-04-03T21:40:05.436Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","aleam","cryptographic-random","cuda","cupy","deep-learning","distributions","entropy","gpu-acceleration","jax","machine-learning","opensource","probability","pypi","python","pytorch","random-number-generator","statistics","tensorflow","true-randomness"],"created_at":"2026-04-02T20:01:52.612Z","updated_at":"2026-04-03T22:01:32.303Z","avatar_url":"https://github.com/fardinsabid.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003c!-- Animated Header Banner --\u003e\n\u003cimg src=\"https://capsule-render.vercel.app/api?type=waving\u0026color=gradient\u0026customColorList=12,15,20\u0026height=200\u0026section=header\u0026text=Aleam\u0026fontSize=70\u0026fontColor=fff\u0026animation=fadeIn\u0026fontAlignY=35\u0026desc=True%20Randomness%20for%20AI\u0026descAlignY=55\u0026descSize=20\" width=\"100%\"/\u003e\n\n\u003c!-- Typing Animation --\u003e\n[![Typing SVG](https://readme-typing-svg.demolab.com?font=Fira+Code\u0026weight=600\u0026size=24\u0026pause=1000\u0026color=00D9FF\u0026center=true\u0026vCenter=true\u0026width=700\u0026lines=No+recursion.+No+state.+Just+entropy.;Break+the+pseudo-random+cage.;True+randomness+for+AI+exploration.;From+Bangladesh+🌍+for+the+World)](https://git.io/typing-svg)\n\n\u003cbr/\u003e\n\n\u003c!-- Badges Row 1 --\u003e\n[![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://python.org)\n[![License](https://img.shields.io/badge/License-MIT-brightgreen?style=for-the-badge\u0026logo=open-source-initiative\u0026logoColor=white)](LICENSE)\n[![PyPI](https://img.shields.io/badge/PyPI-aleam-006dad?style=for-the-badge\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/aleam)\n[![Platform](https://img.shields.io/badge/Platform-Any%20OS-blueviolet?style=for-the-badge\u0026logo=linux\u0026logoColor=white)](.)\n\n\u003cbr/\u003e\n\n\u003c!-- Badges Row 2 --\u003e\n[![Stats](https://img.shields.io/badge/Statistical%20Quality-Perfect-00C853?style=for-the-badge\u0026logo=checkmarx\u0026logoColor=white)](.)\n[![Speed](https://img.shields.io/badge/GPU%20Speed-100M%20ops%2Fsec-FF6D00?style=for-the-badge\u0026logo=speedtest\u0026logoColor=white)](.)\n[![Entropy](https://img.shields.io/badge/Entropy-128%20bits%2Fcall-9C27B0?style=for-the-badge\u0026logo=chainlink\u0026logoColor=white)](.)\n[![Hash](https://img.shields.io/badge/Hash-BLAKE2s-FF1493?style=for-the-badge\u0026logo=hive\u0026logoColor=white)](.)\n\n\u003cbr/\u003e\n\n\u003c!-- Badges Row 3 - Framework Support --\u003e\n[![PyTorch](https://img.shields.io/badge/PyTorch-CUDA-EE4C2C?style=for-the-badge\u0026logo=pytorch\u0026logoColor=white)](.)\n[![TensorFlow](https://img.shields.io/badge/TensorFlow-GPU-FF6F00?style=for-the-badge\u0026logo=tensorflow\u0026logoColor=white)](.)\n[![JAX](https://img.shields.io/badge/JAX-GPU-9B59B6?style=for-the-badge\u0026logo=jax\u0026logoColor=white)](.)\n[![CuPy](https://img.shields.io/badge/CuPy-CUDA-00BCD4?style=for-the-badge\u0026logo=nvidia\u0026logoColor=white)](.)\n\n\u003cbr/\u003e\n\n\u003c!-- Badges Row 4 - Data Science --\u003e\n[![NumPy](https://img.shields.io/badge/NumPy-Integrate-013243?style=for-the-badge\u0026logo=numpy\u0026logoColor=white)](.)\n[![Pandas](https://img.shields.io/badge/Pandas-Integrate-150458?style=for-the-badge\u0026logo=pandas\u0026logoColor=white)](.)\n[![Polars](https://img.shields.io/badge/Polars-Integrate-CD792C?style=for-the-badge\u0026logo=polars\u0026logoColor=white)](.)\n[![Dask](https://img.shields.io/badge/Dask-Integrate-FCA121?style=for-the-badge\u0026logo=dask\u0026logoColor=white)](.)\n\n\u003cbr/\u003e\n\n\u003c!-- Badges Row 5 - Testing --\u003e\n[![Tests](https://img.shields.io/github/actions/workflow/status/fardinsabid/aleam/tests.yml?branch=main\u0026label=Tests\u0026style=for-the-badge\u0026logo=github)](https://github.com/fardinsabid/aleam/actions)\n[![Coverage](https://img.shields.io/codecov/c/github/fardinsabid/aleam?style=for-the-badge\u0026logo=codecov)](https://codecov.io/gh/fardinsabid/aleam)\n[![Downloads](https://img.shields.io/pypi/dm/aleam?style=for-the-badge\u0026logo=pypi)](https://pypi.org/project/aleam)\n\n\u003cbr/\u003e\n\n\u003c!-- Quote --\u003e\n\u003cimg src=\"https://quotes-github-readme.vercel.app/api?type=horizontal\u0026theme=radical\" width=\"100%\"/\u003e\n\n\u003c/div\u003e\n\n---\n\n## 📌 The Problem\n\nPseudo-random number generators (PRNGs) like Mersenne Twister and Python's `random` are **recursive**:\n\n```\nxₙ₊₁ = (a·xₙ + c) mod m\n```\n\nThis creates:\n\n- 🔁 **Hidden correlations** — each number depends on the one before\n- 📅 **Periodicity** — sequences eventually repeat\n- 🧱 **Exploration boundaries** — AI can't truly explore\n- 🎭 **False reproducibility** — same seed = same path\n\n**AI deserves better.**\n\n---\n\n## 🎯 The Solution: Aleam\n\n```python\nimport aleam as al\n\nrng = al.Aleam()\nx = rng.random()  # True randomness. No recursion. No state.\n```\n\nAleam implements the proven equation:\n\n```\nΨ(t) = BLAKE2s( (Φ × Ξ(t)) ⊕ τ(t) )\n```\n\n| Symbol | Meaning |\n|--------|---------|\n| **Φ** | Golden ratio prime (`0x9E3779B97F4A7C15`) |\n| **Ξ(t)** | 128-bit true entropy from system |\n| **τ(t)** | Nanosecond timestamp |\n| **⊕** | XOR mixing |\n| **BLAKE2s** | Cryptographic hash |\n\n**Properties:**\n\n| 🔄 Non-recursive | 🎲 Stateless | 🔒 Cryptographically Secure | 🧠 AI-Optimized |\n|---|---|---|---|\n| Each call independent | No seeds, no state | Powered by BLAKE2s | Gradient noise, latent sampling |\n\n---\n\n## 🔬 How It Works\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fardinsabid/aleam/main/assets/images/diagrams/algorithm.png\" alt=\"Aleam Core Algorithm\" width=\"85%\"/\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n### The Core Equation in Detail\n\n| Step | Operation | Description |\n|------|-----------|-------------|\n| **1** | `Ξ(t) = os.urandom(16)` | Pull 128-bit true entropy from system |\n| **2** | `Ω = Φ × Ξ(t)` | Golden ratio mixing (bijective, maximally equidistributed) |\n| **3** | `τ = time.time_ns()` | Nanosecond timestamp for uniqueness |\n| **4** | `Σ = Ω ⊕ τ` | XOR mixing over 64 bits |\n| **5** | `ψ = BLAKE2s(Σ)` | Cryptographic hash to 64-bit output |\n| **6** | `r = ψ / 2⁶⁴` | Map to floating point [0, 1) |\n\n---\n\n## ⚡ GPU Performance: Aleam vs Real Lava Lamps\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fardinsabid/aleam/main/assets/images/benchmarks/aleam_gpu_vs_lavarand_hd.png\" alt=\"Aleam GPU vs Lava Lamps\" width=\"90%\"/\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n| Metric | Aleam GPU | Cloudflare LavaRand |\n|--------|-----------|---------------------|\n| **Speed** | **93.4 MILLION ops/sec** | 11.47 ops/sec |\n| **Time for 1B numbers** | **11.7 seconds** | 1,009 days |\n| **Uniqueness** | **100%** | 13.3% |\n| **Speedup** | **8,140,555x FASTER** | — |\n\n*Tested on NVIDIA Tesla T4 (Google Colab) · CuPy 14.0.1 · Aleam 1.0.2*\n\n\u003e 💡 **Key Insight:** Lava lamps look cool on a wall, but for AI training, Aleam is 8 million times faster and delivers 100% unique random numbers.\n\n---\n\n## 🚀 CPU vs GPU Performance\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/fardinsabid/aleam/main/assets/images/benchmarks/cpu_vs_gpu.png\" alt=\"Aleam CPU vs GPU\" width=\"90%\"/\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n| Metric | CPU | GPU | Speedup |\n|--------|-----|-----|---------|\n| **Speed** | 435K ops/sec | 93.4M ops/sec | **215x** |\n| **Time for 1B numbers** | 38 minutes | 11.7 seconds | **195x** |\n\n---\n\n## 📊 Statistical Validation\n\nAfter **2.55 million samples**, Aleam passed all 10 rigorous tests:\n\n| Test | Result | Status |\n|------|--------|--------|\n| Mean | 0.499578 | ✓ |\n| Variance | 0.083154 | ✓ |\n| Chi-Square (Uniformity) | 21.40 (critical 30.14) | ✓ PASS |\n| Max Autocorrelation | 0.0094 | ✓ EXCELLENT |\n| π Estimation Error | 0.0105% | ✓ EXCELLENT |\n| Shannon Entropy | 0.9999 | ✓ NEAR-PERFECT |\n\n**\"True randomness is not a bug — it's a feature.\"**\n\n---\n\n## 🚀 Quick Start\n\n```bash\npip install aleam\n```\n\n```python\nimport aleam as al\n\nrng = al.Aleam()\n\n# Basic randomness\nx = rng.random()              # 0.90324326\ny = rng.randint(1, 100)       # 86\nz = rng.choice(['AI', 'ML'])  # 'ML'\n\n# AI/ML features\nnoise = rng.gauss(0, 0.1)               # Gradient noise\nbatch = rng.sample(range(10000), 64)    # Mini-batch sampling\n```\n\n---\n\n## ✨ Features\n\n### 🎲 Core Randomness\n| Method | Description |\n|--------|-------------|\n| `random()` | True random float in [0, 1) |\n| `randint(a, b)` | True random integer |\n| `choice(seq)` | Random element from sequence |\n| `shuffle(lst)` | Shuffle list in-place |\n| `sample(pop, k)` | Sample without replacement |\n\n### 📈 Distributions\n| Distribution | Method |\n|--------------|--------|\n| Normal | `gauss(mu, sigma)` |\n| Exponential | `exponential(rate)` |\n| Beta | `beta(alpha, beta)` |\n| Gamma | `gamma(shape, scale)` |\n| Poisson | `poisson(lam)` |\n| Laplace | `laplace(loc, scale)` |\n| Logistic | `logistic(loc, scale)` |\n| Log-Normal | `lognormal(mu, sigma)` |\n| Weibull | `weibull(shape, scale)` |\n| Pareto | `pareto(alpha, scale)` |\n| Chi-square | `chi_square(df)` |\n| Student's t | `student_t(df)` |\n| F-distribution | `f_distribution(df1, df2)` |\n| Dirichlet | `dirichlet(alpha)` |\n\n### 🧠 AI/ML Features\n| Class | Features |\n|-------|----------|\n| `AIRandom` | Gradient noise, latent vectors, dropout masks, augmentation params, mini-batch, exploration noise |\n| `GradientNoise` | Gradient noise injection with decay |\n| `LatentSampler` | Latent space sampling with interpolation |\n\n### 🔢 Array Operations\n| Function | Description |\n|----------|-------------|\n| `random_array(shape)` | NumPy-style random array |\n| `randn_array(shape, mu, sigma)` | Normal array |\n| `randint_array(shape, low, high)` | Integer array |\n| `choice_array(a, size, p)` | Weighted sampling |\n\n---\n\n## 🔌 Framework Integrations\n\n### PyTorch\n```python\nimport aleam as al\n\ngen = al.TorchGenerator(device='cuda')\ntensor = gen.randn(100, 100)  # True random on GPU\n```\n\n### TensorFlow\n```python\nimport aleam as al\n\ngen = al.TFGenerator()\ntensor = gen.normal((100, 100))  # True random on GPU\n```\n\n### JAX\n```python\nimport aleam as al\n\ngen = al.JAXGenerator()\nkey = gen.key()  # True random key\ntensor = jax.random.normal(key, (100, 100))\n```\n\n### CuPy\n```python\nimport aleam as al\n\ngen = al.CuPyGenerator()\narr = gen.randn((10000, 10000))  # 100M numbers in 1 second!\n```\n\n### Pandas\n```python\nimport aleam as al\n\ngen = al.PandasGenerator()\ndf = gen.dataframe(1000, columns=['a', 'b', 'c'])\n```\n\n---\n\n## ⚡ CUDA Acceleration\n\nAleam provides GPU acceleration through multiple backends:\n\n| Method | Speed (elements/sec) | Verified |\n|--------|---------------------|----------|\n| CPU (Python) | ~270,000 | ✅ |\n| CPU (NumPy) | ~5,000,000 | ✅ |\n| CuPy GPU | **~100,000,000** | ✅ **Verified** |\n| PyTorch CUDA | ~100,000,000 | ✅ |\n| TensorFlow GPU | ~80,000,000 | ✅ |\n| JAX GPU | ~90,000,000 | ✅ |\n\n```python\nimport aleam as al\n\n# Automatic GPU acceleration (auto-detects best backend)\ncuda_gen = al.CUDAGenerator()\n\n# Works with all frameworks\ncupy_arr = cuda_gen.cupy_random((10000, 10000))   # 100M numbers\ntorch_tensor = cuda_gen.torch_randn(10000, 10000, device='cuda')\ntf_tensor = cuda_gen.tf_random_normal((10000, 10000))\n```\n\n### Distribution Performance (CPU)\n\n| Distribution | Speed (ops/sec) |\n|--------------|-----------------|\n| `random()` | 270,000 |\n| `uniform()` | 253,000 |\n| `exponential()` | 248,000 |\n| `laplace()` | 236,000 |\n| `gauss()` | 129,000 |\n| `gamma()` | 79,000 |\n| `poisson()` | 46,000 |\n| `beta()` | 41,000 |\n\n---\n\n## 📦 Installation\n\n### Quick Install\n```bash\npip install aleam\n```\n\n### With Framework Support\n```bash\n# PyTorch\npip install aleam[torch]\n\n# TensorFlow\npip install aleam[tensorflow]\n\n# JAX\npip install aleam[jax]\n\n# CuPy (for maximum GPU speed)\npip install aleam[cupy]\n\n# All frameworks\npip install aleam[all]\n```\n\n### From Source\n```bash\ngit clone https://github.com/fardinsabid/aleam.git\ncd aleam\npip install -e .\n```\n\n---\n\n## 📁 Project Structure\n\n```\naleam/\n├── aleam/\n│   ├── __init__.py          # Package exports\n│   ├── core.py              # Aleam, AleamFast\n│   ├── ai.py                # AIRandom, GradientNoise, LatentSampler\n│   ├── sources.py           # SystemEntropy, HardwareEntropy\n│   ├── distributions.py     # All statistical distributions\n│   ├── arrays.py            # Array operations\n│   ├── utils.py             # Helper functions\n│   ├── torch_integration.py # PyTorch support\n│   ├── tensorflow_integration.py # TensorFlow support\n│   ├── jax_integration.py   # JAX support\n│   ├── cupy_integration.py  # CuPy support\n│   ├── pandas_integration.py # Pandas support\n│   ├── polars_integration.py # Polars support\n│   ├── xarray_integration.py # Xarray support\n│   ├── pymc_integration.py  # PyMC support\n│   ├── cuda_integration.py  # CUDA acceleration\n│   └── cuda_kernels.py      # CUDA kernels\n├── tests/                   # 70+ unit tests\n├── benchmarks/              # Performance benchmarks\n├── examples/                # Usage examples\n├── docs/                    # Documentation\n├── setup.py                 # PyPI packaging\n├── README.md                # You are here\n└── LICENSE                  # MIT License\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### Q: Why is Aleam slower than random.random?\n\n**A:** True randomness is ~37x slower than pseudo-random on CPU — that's expected. You're trading speed for genuine entropy. On GPU, Aleam can achieve 100M+ ops/sec, making it **faster than CPU pseudo-random!**\n\n### Q: Can I seed Aleam for reproducible results?\n\n**A:** No. Aleam is stateless by design. Use Python's `random` module if you need reproducibility.\n\n### Q: Is Aleam cryptographically secure?\n\n**A:** Yes. Each call consumes 128 bits of true entropy and passes through BLAKE2s, a cryptographic hash.\n\n### Q: Will Aleam work on my phone?\n\n**A:** Yes! Works on Android (Termux + Ubuntu) and iOS (iSH) with full functionality.\n\n### Q: Does Aleam support GPU?\n\n**A:** Yes! PyTorch, TensorFlow, JAX, and CuPy integrations all support GPU acceleration. Use `al.CUDAGenerator()` for automatic backend detection.\n\n---\n\n## 🔒 Responsible Use\n\n- ✅ Use for AI research, exploration, and creative projects\n- ✅ Use for scientific simulations requiring true randomness\n- ✅ Use for cryptographic applications\n- ❌ Do not use for security-critical systems without additional entropy sources\n- ❌ Do not use to generate deceptive or harmful content\n\n---\n\n## 📄 License\n\n| Component | License |\n|-----------|---------|\n| **Aleam Interface** | MIT |\n| **Core Algorithm** | MIT |\n| **BLAKE2s** | Public Domain / CC0 |\n\n---\n\n## 🌐 Links\n\n| | |\n|---|---|\n| 📦 PyPI | [pypi.org/project/aleam](https://pypi.org/project/aleam) |\n| 🐛 Issues | [GitHub Issues](https://github.com/fardinsabid/aleam/issues) |\n| 📖 Documentation | [GitHub Docs](https://github.com/fardinsabid/aleam/blob/main/docs/index.md) |\n| 📄 Research Paper | [ALEAM_RESEARCH_PAPER.md](https://github.com/fardinsabid/aleam/blob/main/docs/ALEAM_RESEARCH_PAPER.md) |\n\n---\n\n## 🙏 Acknowledgments\n\n- **BLAKE2** team for the cryptographic hash function\n- **Open-source community** for entropy source implementations\n- **Python** community for the amazing ecosystem\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ by Fardin Sabid**  \n**🇧🇩 From Bangladesh, for the World 🌍**\n\n\u003cbr\u003e\n\n```\nTrue randomness. No recursion. No state. Just entropy.\n```\n\nAfter 2 days of discovery, testing, and refinement — the equation is proven.\n\n\u003cbr\u003e\n\n[![GitHub stars](https://img.shields.io/github/stars/fardinsabid/aleam?style=for-the-badge\u0026logo=github)](https://github.com/fardinsabid/aleam)\n[![Follow](https://img.shields.io/github/followers/fardinsabid?style=for-the-badge\u0026logo=github)](https://github.com/fardinsabid)\n\n**If you find this project useful, please ⭐ star it on GitHub!**\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffardinsabid%2Faleam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffardinsabid%2Faleam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffardinsabid%2Faleam/lists"}