goldenseed

# 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

```bash
pip install golden-seed
```

### Basic Usage

```python
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

```python
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

```python
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...

# GoldenSeed for ClawHub

**Deterministic entropy streams for reproducible testing and procedural generation**

## Why Agents Need This

As an agent, you've probably hit these problems:

1. **Flaky tests** - "It passed locally but failed in CI" because random values changed
2. **Debugging randomness** - Can't reproduce the exact bug because random state is gone  
3. **Procedural generation** - Generated content but can't prove it came from your seed
4. **Statistical testing** - Need fair randomness but stdlib random isn't provably balanced

GoldenSeed solves all of these with **deterministic, verifiable, statistically perfect entropy**.

## Key Features for Agents

✅ **Perfect 50/50 coin flip** - Not just reproducible, but provably fair  
✅ **Hash verification** - Prove output came from declared seed  
✅ **Zero dependencies** - Pure Python, works anywhere  
✅ **Infinite streams** - Generate unlimited data from tiny seeds  
✅ **Cross-platform** - Same seed = same output on all platforms  

⚠️ **Not cryptographically secure** - Use for testing/generation, not passwords/keys

## Quick Examples

### Debug Flaky Tests

```python
from gq import UniversalQKD

# Before: random values make bugs irreproducible
import random
test_value = random.randint(1, 100)  # Different every time!

# After: same seed = same test conditions
gen = UniversalQKD()
test_value = next(gen)[0] % 100 + 1  # Reproducible!
```

### Verify Procedural Output

```python
from gq import UniversalQKD
import hashlib

# Generate world with proof
gen = UniversalQKD()
world_data = b''.join([next(gen) for _ in range(1000)])
proof = hashlib.sha256(world_data).hexdigest()

print(f"Generated 16KB world with hash: {proof}")
# Anyone can verify by running same seed
```

### Perfect Statistical Distribution

```python
from gq import UniversalQKD

# Prove 50/50 fairness
gen = UniversalQKD()
heads = sum(1 for _ in range(1_000_000) if next(gen)[0] & 1)
print(f"Heads ratio: {heads/1_000_000:.6f}")
# Output: 0.500xxx...