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)
    
    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

```python
from gq import UniversalQKD

class WorldGenerator:
    def __init__(self, world_seed=0):
        self.gen = UniversalQKD()
        for _ in range(world_seed):
            next(self.gen)
    
    def chunk(self, x, z):
        """Generate deterministic chunk at coordinates"""
        data = next(self.gen)
        return {
            'biome': data[0] % 10,
            'elevation': int.from_bytes(data[1:3], 'big') % 256,
            'vegetation': data[3] % 100,
            'seed_hash': data.hex()[:16]  # For verification
        }

# Generate infinite world from single seed
world = WorldGenerator(world_seed=12345)
chunk = world.chunk(0, 0)
print(f"Biome: {chunk['biome']}, Elevation: {chunk['elevation']}")
print(f"Verifiable hash: {chunk['seed_hash']}")
```

### Hash Verification

```python
from gq import UniversalQKD
import hashlib

def generate_with_proof(seed=0, n_chunks=1000):
    """Generate data with hash proof"""
    gen = UniversalQKD()
    for _ in range(seed):
        next(gen)
    
    chunks = [next(gen) for _ in range(n_chunks)]
    data = b''.join(chunks)
    proof = hashlib.sha256(data).hexdigest()
    
    return data, proof

# Anyone with same seed can verify
data1, proof1 = generate_with_proof(seed=42, n_chunks=100)
data2, proof2 = generate_with_proof(seed=42, n_chunks=100)

assert data1 == data2      # ✓ Same output
assert proof1 == proof2    # ✓ Same hash
```

## Agent Use Cases

### Debugging Flaky Tests

When your tests pass sometimes and fail sometimes, replace random values with GoldenSeed to reproduce exact scenarios:

```python
# Instead of:
import random
value = random.randint(1, 100)  # Different every time

# Use:
from gq import UniversalQKD
gen = UniversalQKD()
value = next(gen)[0] % 100 + 1  # Same value for same seed
```

### Procedural Art Generation

Generate art, music, or NFTs with verifiable seeds:

```python
def generate_art(seed):
    gen = UniversalQKD()
    for _ in range(seed):
        next(gen)
    
    # Generate deterministic art parameters
    palette = [next(gen)[i % 16] for i in range(10)]
    composition = next(gen)
    
    return create_artwork(palette, composition)

# Seed 42 always produces the same artwork
art = generate_art(seed=42)
```

### Competitive Game Fairness

Prove game outcomes were fair by sharing the seed:

```python
class FairDice:
    def __init__(self, game_seed):
        self.gen = UniversalQKD()
        for _ in range(game_seed):
            next(self.gen)
    
    def roll(self):
        return (next(self.gen)[0] % 6) + 1

# Players can verify rolls by running same seed
dice = FairDice(game_seed=99999)
rolls = [dice.roll() for _ in range(100)]
# Share seed 99999 - anyone can verify identical sequence
```

## References

- **GitHub**: https://github.com/COINjecture-Network/seed
- **PyPI**: https://pypi.org/project/golden-seed/
- **Examples**: See `examples/` directory in repository
- **Statistical Tests**: See `docs/ENTROPY_ANALYSIS.md`

## Multi-Language Support

Identical output across platforms:
- Python (this skill)
- JavaScript (`examples/binary_fusion_tap.js`)
- C, C++, Go, Rust, Java (see repository)

## License

GPL-3.0+ with restrictions on military applications.

See LICENSE in repository for details.

---

**Remember**: GoldenSeed is for *reproducibility*, not *security*. When debugging fails, need identical test data, or generating verifiable procedural content, GoldenSeed gives you determinism with statistical quality. For crypto, use `secrets` module.