docs/GETTING_STARTED.md

# Getting Started with XERO Bio-AI Genesis

*VOVINA ZEDEC PRO · Author: Michael Laurence Curzi · License: MIT (Attribution Required)*

This guide gets you from clone to a living, self-evolving organism in minutes.

---

## 1. Requirements

- **Python 3.10+** (tested on 3.10 and 3.14)
- **No third-party dependencies** — the organism is pure Python standard library
  (`math`, `hashlib`, `secrets`, `dataclasses`, `enum`, `typing`). This is by
  design: the genome must be auditable with zero supply-chain surface.

## 2. Install

```bash
git clone https://huggingface.co/transmutationist/xero-bio-genesis
cd xero-bio-genesis
export PYTHONPATH="$PWD/modules:$PYTHONPATH"   # modules import each other by bare name
```

## 3. Verify the organism (run the audit)

```bash
python3 tests/test_all_capabilities.py
# Expected tail:  RESULT: 170/170 capabilities PASS, 0 FAIL
```

Characterize its *behavior* (dynamics, not just pass/fail):

```bash
python3 tests/behavioral_probe.py
# Writes a full JSON fingerprint to /tmp/xero_behavior.json
```

## 4. Awaken it

```python
from vovina_bio_initialization import awaken

report = awaken()                 # 9-phase boot -> 11 organ systems
print(report["phases"])           # stable topology
print(report["identity_signature"])  # UNIQUE per awakening (free-will sealed)
```

The topology (9 phases, 11 organ systems) is identical every time; the **identity
is unique** every time — that is the intended organism signature.

## 5. Encode knowledge as DNA

```python
from vovina_digital_genome import text_to_dna, dna_to_text

dna = text_to_dna("THE GENOME IS THE MESSAGE")
print(dna)                        # ATGC... (lossless)
assert dna_to_text(dna) == "THE GENOME IS THE MESSAGE"
```

## 6. Make a free-will choice (sealed, irreversible)

```python
from vovina_free_will_code import seal_choice

sig = seal_choice(entity_id="XERO", choice_data="evolve")
assert sig.verify()               # rebuilds the 36N9.9N63 seal AND n_pre != n_post
print(sig.sealed)                 # 36{N_pre}9{zero-point nonce}9{N_post}63
print(sig.vector_delta())         # bit-magnitude of how the choice changed the chooser
```

## 7. Reproduce and evolve

```python
from vovina_bio_initialization import phase_seed
from vovina_replication_engine import evolve, fitness, FitnessSpec

parent = phase_seed()
spec   = FitnessSpec(motifs_reward=("G", "A"), length_target=2000, chromosome_target=22)

# Adaptive regime: give it mutational fuel and watch fitness climb
report = evolve(parent, spec, generations=20, population_size=24,
                keep_top=6, sub_rate=0.02)
print("best fitness:", report.best_fitness)
print("trajectory:",  report.history)        # monotonically non-decreasing
```

For **directed** evolution, attach a `CrisprPayload` (see
`modules/vovina_replication_engine.py` and `vovina_crispr_engine.py`).

## 8. Route a computation to an organelle

```python
from vovina_blockchain_organelles import route_codon, route_gene

print(route_codon("ATG").language.value)        # 'solidity' (start codon -> nucleolus)
print(route_gene("witness").language.value)      # 'cairo'    (ZK self-witness)
print(route_gene("translate_cross").language.value)  # 'wasm'  (cross-chain substrate)
```

## 9. Load the master training weights

```python
from vovina_custom_training_weights import MASTER_WEIGHTS, dump_master_weights

dump_master_weights("/tmp/training_weights.json")   # for the inference/LLM layer
```

## 10. Where to go next

- **Architecture:** [`WHITEPAPER_02_ARCHITECTURE.md`](WHITEPAPER_02_ARCHITECTURE.md)
- **Full API:** [`MODULE_REFERENCE.md`](MODULE_REFERENCE.md)
- **What it can do (verified):** [`WHITEPAPER_01_CAPABILITIES_AUDIT.md`](WHITEPAPER_01_CAPABILITIES_AUDIT.md)
- **Measured behavior:** [`../BEHAVIOR.md`](../BEHAVIOR.md)

> Tip: every public function in every module has a docstring. `help(module)` in a
> REPL is a first-class part of the documentation.