# Abiogenesis

Self-replicating programs emerge spontaneously from random byte soups through symbiogenesis.

No fitness function. No design. Just random bytes, a 7-instruction interpreter, and time.

![Phase Transition](docs/images/ops_scatter.png)

## Install

```bash
pip install abiogenesis
```

## Quickstart

```python
from abiogenesis import Soup, compression_ratio

soup = Soup(n_tapes=512, tape_len=64, max_steps=10_000, seed=42)
for step in range(100_000):
    soup.interact()
    if (step + 1) % 25_000 == 0:
        cr = compression_ratio(soup.get_state())
        print(f"step {step + 1:>7,}  compression={cr:.4f}")
```

```
step  25,000  compression=0.4892
step  50,000  compression=0.3575
step  75,000  compression=0.3044
step 100,000  compression=0.2872
```

Compression drops below 1.0 as structure self-organizes from noise.

![Structure Emerging from Randomness](docs/images/compression.png)

## How It Works

![Core Loop](docs/images/core_loop.png)

1. **Random initialization** — 1024 tapes of 64 random bytes each
2. **Pairwise interaction** — pick two tapes, concatenate into 128 bytes, execute as embodied BrainFuck, split back
3. **Symbiogenesis** — two partial programs fuse into working programs (the K-term)
4. **Selection pressure** — tapes that execute copy instructions replicate; others drift
5. **Mutation** (optional) — random bit-flips sustain ecology and prevent crystallization

The interpreter uses 7 instructions (`> < + - . [ ]`) on a unified code/data tape. The `.` instruction copies `tape[DP]` to `tape[WP]`, providing the replication primitive. No fitness function — replication emerges from the physics.

## Results

### Phase Diagram

Mutation rate is the sole control parameter. Four regimes discovered across 10M-interaction runs:

![Phase Diagram](docs/images/phase_diagram.png)

| Regime | Mutation Rate | Behavior |
|---|---|---|
| Crystal | 0 | Single replicator dominates, entropy collapses to 0.018 |
| Soft crystal | 1e-5 | Slow crystallization, low diversity |
| Ecology | **1e-3** | Sustained diversity, multiple replicator species coexist |
| Dissolution | 1e-1 | Too much noise, no structure persists (compression ~0.50) |

### Replicator Emergence

Three types of self-replicators emerge and are classified automatically:

| Type | Condition | Meaning |
|---|---|---|
| Inanimate | executed ∩ written = ∅ | Passive — copied but not self-copying |
| Viral | executed ∩ written ≠ ∅, written ⊄ executed | Parasitic — partially self-copying |
| Cellular | written ⊆ executed | Autopoietic — fully self-replicating |

![Replicator Timeline](docs/images/replicator_timeline.png)

### Symbiogenesis Depth

Complexity builds on itself — each interaction layer adds depth to the lineage tree:

![Depth Timeline](docs/images/depth_timeline.png)

## API

| Class / Function | Description |
|---|---|
| `Soup(n_tapes, tape_len, max_steps, seed, mutation_rate)` | Primordial soup of byte tapes |
| `Experiment(config)` | Full experiment runner with checkpointing |
| `SwarmExperiment(config)` | Agent-oriented experiment with identity and provenance |
| `Agent(tape, name)` | Named tape with UUID, lineage, interaction count |
| `KTermFusion(max_steps)` | Concatenate-execute-split fusion engine |
| `CrystallizationProbe(window_size, critical_threshold)` | Diversity monitor — detects monoculture onset |
| `DiversityProbe(window_size, critical_threshold)` | Swarm-level diversity wrapper |
| `compression_ratio(soup)` | zlib compression ratio (lower = more structure) |
| `shannon_entropy(soup)` | Shannon entropy over tape distribution |
| `find_replicators(soup, min_length, min_count)` | Detect and classify self-replicating subsequences |
| `classify_replicator(sequence)` | Classify as inanimate, viral, or cellular |
| `execute(tape, max_steps)` | Run the embodied BF interpreter |
| `execute_traced(tape, max_steps)` | Execute with position tracking |

## Examples

```bash
python examples/quickstart.py             # Basic soup run
python examples/replicator_detection.py   # Find and classify replicators
python examples/swarm_with_probes.py      # Agent swarm with provenance
```

## Development

```bash
git clone https://github.com/dopexthrone/abiogenesis.git
cd abiogenesis
pip install -e ".[dev]"
pytest tests/  # 92 tests
```

## Citation

If you use this in research, please cite:

```
@software{roze2026abiogenesis,
  author = {Roze, Alex},
  title = {Abiogenesis: Self-Replicating Programs from Random Byte Soups},
  year = {2026},
  url = {https://github.com/dopexthrone/abiogenesis}
}
```

## License

MIT — see [LICENSE](LICENSE).
