{"skill":{"slug":"goldenseed","displayName":"GoldenSeed","summary":"Deterministic entropy streams for reproducible testing and procedural generation. Perfect 50/50 statistical distribution with hash verification. Not cryptographically secure - use for testing, worldgen, and scenarios where reproducibility matters more than unpredictability.","description":"---\nname: goldenseed\ndescription: Deterministic entropy streams for reproducible testing and procedural generation. Perfect 50/50 statistical distribution with hash verification. Not cryptographically secure - use for testing, worldgen, and scenarios where reproducibility matters more than unpredictability.\ntags: [testing, procedural-generation, deterministic, reproducibility, golden-ratio]\nversion: 1.0.0\nauthor: beanapologist\nlicense: GPL-3.0+\n---\n\n# GoldenSeed - Deterministic Entropy for Agents\n\n**Reproducible randomness when you need identical results every time.**\n\n## What This Does\n\nGoldenSeed generates infinite deterministic byte streams from tiny fixed seeds. Same seed → same output, always. Perfect for:\n\n- ✅ **Testing reproducibility**: Debug flaky tests by replaying exact random sequences\n- ✅ **Procedural generation**: Create verifiable game worlds, art, music from seeds\n- ✅ **Scientific simulations**: Reproducible Monte Carlo, physics engines\n- ✅ **Statistical testing**: Perfect 50/50 coin flip distribution (provably fair)\n- ✅ **Hash verification**: Prove output came from declared seed\n\n## What This Doesn't Do\n\n⚠️ **NOT cryptographically secure** - Don't use for passwords, keys, or security tokens. Use `os.urandom()` or `secrets` module for crypto.\n\n## Quick Start\n\n### Installation\n\n```bash\npip install golden-seed\n```\n\n### Basic Usage\n\n```python\nfrom gq import UniversalQKD\n\n# Create generator with default seed\ngen = UniversalQKD()\n\n# Generate 16-byte chunks\nchunk1 = next(gen)\nchunk2 = next(gen)\n\n# Same seed = same sequence (reproducibility!)\ngen1 = UniversalQKD()\ngen2 = UniversalQKD()\nassert next(gen1) == next(gen2)  # Always identical\n```\n\n### Statistical Quality - Perfect 50/50 Coin Flip\n\n```python\nfrom gq import UniversalQKD\n\ndef coin_flip_test(n=1_000_000):\n    \"\"\"Demonstrate perfect 50/50 distribution\"\"\"\n    gen = UniversalQKD()\n    heads = 0\n    \n    for _ in range(n):\n        byte = next(gen)[0]  # Get first byte\n        if byte & 1:  # Check LSB\n            heads += 1\n    \n    ratio = heads / n\n    print(f\"Heads: {ratio:.6f} (expected: 0.500000)\")\n    return abs(ratio - 0.5) < 0.001  # Within 0.1%\n\nassert coin_flip_test()  # ✓ Passes every time\n```\n\n### Reproducible Testing\n\n```python\nfrom gq import UniversalQKD\n\nclass TestDataGenerator:\n    def __init__(self, seed=0):\n        self.gen = UniversalQKD()\n        # Skip to seed position\n        for _ in range(seed):\n            next(self.gen)\n    \n    def random_user(self):\n        data = next(self.gen)\n        return {\n            'id': int.from_bytes(data[0:4], 'big'),\n            'age': 18 + (data[4] % 50),\n            'premium': bool(data[5] & 1)\n        }\n\n# Same seed = same test data every time\ndef test_user_pipeline():\n    users = TestDataGenerator(seed=42)\n    user1 = users.random_user()\n    \n    # Run again - identical results!\n    users2 = TestDataGenerator(seed=42)\n    user1_again = users2.random_user()\n    \n    assert user1 == user1_again  # ✓ Reproducible!\n```\n\n### Procedural World Generation\n\n```python\nfrom gq import UniversalQKD\n\nclass WorldGenerator:\n    def __init__(self, world_seed=0):\n        self.gen = UniversalQKD()\n        for _ in range(world_seed):\n            next(self.gen)\n    \n    def chunk(self, x, z):\n        \"\"\"Generate deterministic chunk at coordinates\"\"\"\n        data = next(self.gen)\n        return {\n            'biome': data[0] % 10,\n            'elevation': int.from_bytes(data[1:3], 'big') % 256,\n            'vegetation': data[3] % 100,\n            'seed_hash': data.hex()[:16]  # For verification\n        }\n\n# Generate infinite world from single seed\nworld = WorldGenerator(world_seed=12345)\nchunk = world.chunk(0, 0)\nprint(f\"Biome: {chunk['biome']}, Elevation: {chunk['elevation']}\")\nprint(f\"Verifiable hash: {chunk['seed_hash']}\")\n```\n\n### Hash Verification\n\n```python\nfrom gq import UniversalQKD\nimport hashlib\n\ndef generate_with_proof(seed=0, n_chunks=1000):\n    \"\"\"Generate data with hash proof\"\"\"\n    gen = UniversalQKD()\n    for _ in range(seed):\n        next(gen)\n    \n    chunks = [next(gen) for _ in range(n_chunks)]\n    data = b''.join(chunks)\n    proof = hashlib.sha256(data).hexdigest()\n    \n    return data, proof\n\n# Anyone with same seed can verify\ndata1, proof1 = generate_with_proof(seed=42, n_chunks=100)\ndata2, proof2 = generate_with_proof(seed=42, n_chunks=100)\n\nassert data1 == data2      # ✓ Same output\nassert proof1 == proof2    # ✓ Same hash\n```\n\n## Agent Use Cases\n\n### Debugging Flaky Tests\n\nWhen your tests pass sometimes and fail sometimes, replace random values with GoldenSeed to reproduce exact scenarios:\n\n```python\n# Instead of:\nimport random\nvalue = random.randint(1, 100)  # Different every time\n\n# Use:\nfrom gq import UniversalQKD\ngen = UniversalQKD()\nvalue = next(gen)[0] % 100 + 1  # Same value for same seed\n```\n\n### Procedural Art Generation\n\nGenerate art, music, or NFTs with verifiable seeds:\n\n```python\ndef generate_art(seed):\n    gen = UniversalQKD()\n    for _ in range(seed):\n        next(gen)\n    \n    # Generate deterministic art parameters\n    palette = [next(gen)[i % 16] for i in range(10)]\n    composition = next(gen)\n    \n    return create_artwork(palette, composition)\n\n# Seed 42 always produces the same artwork\nart = generate_art(seed=42)\n```\n\n### Competitive Game Fairness\n\nProve game outcomes were fair by sharing the seed:\n\n```python\nclass FairDice:\n    def __init__(self, game_seed):\n        self.gen = UniversalQKD()\n        for _ in range(game_seed):\n            next(self.gen)\n    \n    def roll(self):\n        return (next(self.gen)[0] % 6) + 1\n\n# Players can verify rolls by running same seed\ndice = FairDice(game_seed=99999)\nrolls = [dice.roll() for _ in range(100)]\n# Share seed 99999 - anyone can verify identical sequence\n```\n\n## References\n\n- **GitHub**: https://github.com/COINjecture-Network/seed\n- **PyPI**: https://pypi.org/project/golden-seed/\n- **Examples**: See `examples/` directory in repository\n- **Statistical Tests**: See `docs/ENTROPY_ANALYSIS.md`\n\n## Multi-Language Support\n\nIdentical output across platforms:\n- Python (this skill)\n- JavaScript (`examples/binary_fusion_tap.js`)\n- C, C++, Go, Rust, Java (see repository)\n\n## License\n\nGPL-3.0+ with restrictions on military applications.\n\nSee LICENSE in repository for details.\n\n---\n\n**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.\n","tags":{"latest":"1.1.0"},"stats":{"comments":0,"downloads":1570,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1770561395083,"updatedAt":1778486086401},"latestVersion":{"version":"1.1.0","createdAt":1770561423325,"changelog":"Updated docs: Emphasize testing reproducibility, perfect 50/50 coin flip, hash verification. Clear warnings about non-cryptographic use. Agent-focused examples for debugging flaky tests.","license":null},"metadata":null,"owner":{"handle":"beanapologist","userId":"s17av1nf6b23hqgwpkjq76c74s884h46","displayName":"beanapologist","image":"https://avatars.githubusercontent.com/u/188747204?v=4"},"moderation":null}