CodonTrace Genesis

Replayable digital evolution, causal mechanism auditing, and evidence-gated ALife research software.

CodonTrace Genesis is a Python library for running small digital-evolution experiments that you can replay later. You start a tiny world, let simple agents eat, survive, and reproduce, and the library writes down what happened as checkable records. Use it when you want to test an evolutionary idea with evidence instead of a screenshot. It is research software. It does not claim that the agents are intelligent.

That life-loop is still the product. Domain modules sit beside the engine; they do not replace it. The biomedical module is the first extra port: a ClaimGate DomainProfile that audits a declared evidence table. Hardware today is one arm, SimEsp32Bridge. Further domain modules and hardware arms attach the same way, without a second engine.

The installable package is codontrace. Product naming for contributors lives in CONTRIBUTING.md and STYLE.md.

What it is

• a Python research library for controlled digital-evolution and ALife experiments
• a replay / audit-first evidence layer (specs, runtime digests, manifests)
• a mechanism instrumentation toolkit (ablations, treatment/control, delayed outcomes)
• a claim-gated workflow: software capability and runtime observations are allowed; strong scientific conclusions are not auto-promoted
• one biomedical port and one hardware arm on that same auditor; more domain modules and hardware arms attach later without forking the engine

What it is not

CodonTrace Genesis is not currently presented as:

• proof of artificial general intelligence, consciousness, or collective intelligence
• proof of open-ended intelligence, or a Tokyo Type 1 pass (Channon 2024)
• a biological evolution simulator or wet-lab chemistry engine
• a replacement for Avida, MABE, DEAP, QDax, pyribs, or similar tools
• a physical-robot research platform (ESP32 Moj-ه is an engineering stub / SimEsp32Bridge only)
• a medical device, SaMD, IVD, FDA/CE clearance, or ASME V&V 40 certification (biomedical is a ClaimGate DomainProfile port)
• an Avida/MABE literature-compatible campaign runner (ClaimGate adapters are skeletons until audited published .dat/CSV exist)

The project is ambitious. Claims must pass evidence gates. See CLAIMS.md and docs/WHY_NOT_INTELLIGENCE_YET.md.

Status

Phases A–L

Phases A–G remain the earlier 0.3.0b3 substrate. Phases H–L + HE01 SCHEMA v7 + discovery ClaimGate pipeline ship in public 0.3.0b4.

Allowed when the evidence objects actually exist: runtime_observation, oee_measurement_only, tokyo_type1_measurement_only, and collective_intelligence_candidate (full honest flags only, including replay).

Still blocked: bare collective_intelligence, intelligence, AGI, tokyo_type1_passed, Avida replacement, and related aliases. Smoke never auto-sets ClaimGate flags. Digests are never faked.

North star: eventually produce honest collective-work / intelligence-pathway outputs. That is not the same as unlocking those claims.

Installation

The published wheel is codontrace==0.3.0b9 (tag v0.3.0b9). main is 0.3.0b10 and is not a recut of that wheel. Older public cuts 0.3.0b4, 0.3.0b5, 0.3.0b6, 0.3.0b7, and 0.3.0b8 remain immutable and must not be recut. Phases A–G remain the 0.3.0b3 substrate; H–L + HE01 SCHEMA v7 shipped in 0.3.0b4.

Python 3.11–3.14. CI smokes ubuntu-latest, windows-latest, and macos-latest on that range.

From PyPI (0.3.0b9)

pip install codontrace==0.3.0b9

Optional research extras:

pip install "codontrace[research]==0.3.0b9"
pip install "codontrace[causal]==0.3.0b9"
pip install "codontrace[qd]==0.3.0b9"

From source (main, may be ahead of PyPI)

git clone https://github.com/Parvaz-Jamei/codontrace-genesis.git
cd codontrace-genesis
python -m pip install -e ".[dev,research,causal,qd]"

python -c "import codontrace; print(codontrace.__version__)"

A PyPI install of the published tip prints 0.3.0b9. An editable install from main prints [project].version from pyproject.toml (currently 0.3.0b10). Do not treat the version tuple as a phase fence.

Quick start

Use the beginner API first. It keeps setup small and returns the agent, world, trace, and optional explanation without manually creating low-level runtime objects.

from codontrace import WhiteBoxAgent, World2D

world = World2D.from_ascii("""
....
.A*.
....
""")

agent = WhiteBoxAgent.from_world(world, genome="101111000", initial_atp=5.0)
result = agent.run_trial(world, steps=3, explain=True)

print(result.agent.position)
print(result.explanation.summary if result.explanation else "no explanation")

Core API

For Genesis-level research runs, use the explicit experiment spec and engine APIs.

from codontrace.genesis import GenesisEngine, GenesisExperimentSpec

spec = GenesisExperimentSpec(seed=42, tick_count=32, population_max=8)
result = GenesisEngine.from_spec(spec).run_ticks()

print(result.digest()[:24])
print(len(result.engine_frames))

Short eat → survive → reproduce experiments should use GenesisRuntimeProfile.life_loop_world() instead of empty research defaults (ResourceConfig.density=0, ReproductionConfig SAME_CELL). The preset is a Darwinian life-loop substrate. It is not an Avida replacement.

from codontrace.genesis import GenesisEngine, GenesisRuntimeProfile

spec = GenesisRuntimeProfile.life_loop_world(seed=7, tick_count=12, population=6)
result = GenesisEngine.from_spec(spec).run_ticks()
print(result.digest()[:24])

Opt-in presets and measurement packs (sexual recombination, fluctuating environments, multi-generation / Tokyo Type 1 measurement, Phase E substrate, materials, RAG, and H–L CI harnesses) are library APIs with the ceilings in the status table. Defaults stay off so A–E digest pins remain stable.

Print-only smokes live under examples/.

Benchmark smoke

The smoke runner is a functionality and artifact-generation check. It is not a proof of collective intelligence.

python -m pytest tests/examples/test_collective_joss_evidence_benchmark_smoke.py -q

PYTHONPATH=src python examples/collective_joss_evidence_benchmark.py   --out outputs/joss_evidence_smoke   --profile smoke   --seed-count 1   --ticks 3   --population 4   --workers 1   --max-runs 6   --per-run-timeout 90

Expected core artifacts: run_config.json, summary.json, run_records.csv, feature_matrix.csv, counterfactual_pairs.csv, claim_readiness.json, artifact_manifest.json, environment.txt, report.html.

Levels and interpretation: BENCHMARKS.md.

Claim policy

ScientificClaimGate can allow collective_intelligence_candidate only when the full honest flag set is present, including replay. It does not allow bare collective_intelligence, intelligence, AGI, tokyo_type1_passed, or Avida replacement.

Full policy: CLAIMS.md.

Next steps

Library-complete beta is not “done.” The next work is not more empty Phase letters.

1. Do not recut published wheels 0.3.0b4, 0.3.0b5, 0.3.0b6, 0.3.0b7, 0.3.0b8, or 0.3.0b9. A later public identity needs its own version, a green CI on that exact commit, and an explicit tag. 0.3.0b10 is that next identity; it does not replace the 0.3.0b9 wheel.
2. Do not tag or publish from a red or queued CI. The PyPI wheel stays v0.3.0b9 until a later upload.
3. HE03 research campaign — run only against the locked prereg; do not fabricate results_v1.
4. Lint/type inventory — lint-type remains non-blocking until the ruff/mypy backlog is reduced in its own PR.
5. Candidate claims — collective_intelligence_candidate only if the full honest flags, including replay, are actually earned.
6. OEE later — Tokyo Type 1 pass and open-ended intelligence remain blocked.

Architecture

The product is still the engine: a world, agents that eat, survive, and reproduce, then a digest you can replay. The engine does not know medicine or hardware.

GenesisEngine  →  ticks, digest, replay
       └→ native adapter  →  claimgate_bundle_v1  →  audit_bundle()  →  ladder 0–5

Domain modules (same auditor, no second engine)
       biomedical   DomainProfile  — declared evidence table
       hardware     SimEsp32Bridge — one arm today; more arms later
       (later)      another DomainProfile or ingest adapter

A new module is a DomainProfile or an adapter. It is not a copy of engine.py.

ALIFE is the default profile for the life-loop. BIOMEDICAL and HARDWARE are the two extra profiles that ship now. Biomedical stores ASME V&V 40, FDA 2023, IEC 62304, and IMDRF wording as labels. The same port ranks a phenomena table (PIRT, from nuclear safety) and caps a coupled model at its weakest submodel (building-block VVUQ). A study file closes a phenomenon only when that arm was executed; a typed rank does not. Declared model risk has a separate bar (level 2/3/4 for risk 1/2/3, and an open high-importance phenomenon blocks from risk 2 up). The bar does not move the ladder. See docs/claimgate/risk_bar.json. It is not a device. Strings such as asme_vv40_passed, fda_cleared, and samd_certified raise ConfigurationError.

from codontrace.claimgate import audit_bundle
from codontrace.claimgate.adapters.codontrace import bundle_from_hard_experiment_01

report = audit_bundle(bundle_from_hard_experiment_01())
print(report.achieved_level, report.public_name, report.missing_for_next)

from codontrace.claimgate import audit_bundle
from codontrace.claimgate.adapters.biomedical import bundle_from_device_model_cou

bundle = bundle_from_device_model_cou(
    question_of_interest="Would this score table support the claim?",
    context_of_use="Declared table only; no implant.",
    model_influence=2,
    decision_consequence=3,
    treatment_scores=(0.12, 0.11, 0.13),
    control_scores=(0.20, 0.19, 0.21),
    device_software_kind="simd_declared",
    iec_62304_class="B",
    imdrf_n12_category="II",
    fda_2023_evidence=(1, 3, 8),
    physics_based=True,
)
print(audit_bundle(bundle).achieved_level, bundle.extra["domain"], bundle.extra["model_risk"])

The second call stays on the biomedical port. It does not start GenesisEngine. Map: docs/ARCHITECTURE_PORTS.md. Biomedical scope: docs/BIOMEDICAL_ENGINEERING.md.

Documentation

Phase literature checklists: PHASE_D_LITERATURE.md, PHASE_E_LITERATURE.md, PHASE_G_MATERIALS_LITERATURE.md. Studio / performance notes stay out of core: STUDIO_BOUNDARY.md.

Testing

python -m compileall -q src tests examples tools
python -m pytest tests/genesis_gates -q
python -m pytest tests/science_gates -q
python -m pytest tests/examples/test_collective_joss_evidence_benchmark_smoke.py -q
python -m pytest tests -q

Validation tiers: REPRODUCIBILITY.md.

Citation

If you use CodonTrace Genesis in research, prototypes, technical evaluation, benchmark work, reports, or derivative research artifacts, please cite the versioned software release.

@software{codontrace_genesis_2026,
  title = {CodonTrace Genesis},
  author = {Jamei, Parvaz},
  version = {0.3.0b10},
  doi = {10.5281/zenodo.20337435},
  url = {https://github.com/Parvaz-Jamei/codontrace-genesis},
  note = {0.3.0b10 is the git identity. The PyPI wheel remains 0.3.0b9. The DOI is the software archive, not a campaign archive.}
}

A CITATION.cff file is included for citation-aware tools.

Use of the software does not automatically imply co-authorship. Co-authorship may be appropriate when there is substantial collaboration in experimental design, analysis, interpretation, validation, or manuscript writing.

License

CodonTrace Genesis is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

This license is selected to keep modified, redistributed, and network-deployed versions open, attributable, and scientifically inspectable.

Commercial or proprietary use cases that cannot comply with AGPL-3.0-or-later may contact the author for a separate commercial license.

See LICENSE and NOTICE.

Author

Parvaz Jamei Embedded / Industrial IoT / Edge AI / Digital Evolution Research Software

GitHub: @Parvaz-Jamei

CodonTrace Genesis Replayable evidence for digital evolution, causal mechanisms, and ALife research.