GoldenSeed - Deterministic Entropy for Agents

Reproducible randomness when you need identical results every time.

What This Does

GoldenSeed generates infinite deterministic byte streams from tiny fixed seeds. Same seed → same output, always. Perfect for:

• ✅ Testing reproducibility: Debug flaky tests by replaying exact random sequences
• ✅ Procedural generation: Create verifiable game worlds, art, music from seeds
• ✅ Scientific simulations: Reproducible Monte Carlo, physics engines
• ✅ Statistical testing: Perfect 50/50 coin flip distribution (provably fair)
• ✅ Hash verification: Prove output came from declared seed

What This Doesn't Do

⚠️ NOT cryptographically secure - Don't use for passwords, keys, or security tokens. Use os.urandom() or secrets module for crypto.

Quick Start

Installation

pip install golden-seed

Basic Usage

from gq import UniversalQKD

# Create generator with default seed
gen = UniversalQKD()

# Generate 16-byte chunks
chunk1 = next(gen)
chunk2 = next(gen)

# Same seed = same sequence (reproducibility!)
gen1 = UniversalQKD()
gen2 = UniversalQKD()
assert next(gen1) == next(gen2)  # Always identical

Statistical Quality - Perfect 50/50 Coin Flip

from gq import UniversalQKD

def coin_flip_test(n=1_000_000):
    """Demonstrate perfect 50/50 distribution"""
    gen = UniversalQKD()
    heads = 0
    
    for _ in range(n):
        byte = next(gen)[0]  # Get first byte
        if byte & 1:  # Check LSB
            heads += 1
    
    ratio = heads / n
    print(f"Heads: {ratio:.6f} (expected: 0.500000)")
    return abs(ratio - 0.5) < 0.001  # Within 0.1%

assert coin_flip_test()  # ✓ Passes every time

Reproducible Testing

from gq import UniversalQKD

class TestDataGenerator:
    def __init__(self, seed=0):
        self.gen = UniversalQKD()
        # Skip to seed position
        for _ in range(seed):
            next(self.gen)
    
    def random_user(self):
        data = next(self.gen)
        return {
            'id': int.from_bytes(data[0:4], 'big'),
            'age': 18 + (data[4] % 50),
            'premium': bool(data[5] & 1)
        }

# Same seed = same test data every time
def test_user_pipeline():
    users = TestDataGenerator(seed=42)
    user1 = users.random_user()
    
    # Run again - identical results!
    users2 = TestDataGenerator(seed=42)
    user1_again = users2.random_user()
    
    assert user1 == user1_again  # ✓ Reproducible!

Procedural World Generation

from gq import UniversalQKD