CodonTrace

This repository is an early CodonTrace prototype. The active public research release is now maintained at: https://github.com/Parvaz-Jamei/codontrace-genesis

CodonTrace is an experimental Python library for research on executable semantic genomes, ATP-constrained white-box agents, structured traces, and causal replay in compact deterministic simulation worlds.

It is designed as a research tool, not as a production AI system. Its purpose is to make agent behavior inspectable, reproducible, editable, and experimentally testable.

Version 0.2.0a3 is a developer-experience alpha for the library-first research core. The core returns Python objects and intentionally avoids automatic reports, dashboards, hidden output directories, file writers, or heavy runtime dependencies.

Table of contents

• Scientific motivation
• What this library is
• What this library is not
• Install
• Quick start
• Core API
• Custom actions
• Research use cases
• Reproducibility
• Limitations and non-claims
• Scientific background / prior art
• Citation / references
• Development status

Scientific motivation

Modern AI has achieved remarkable progress through statistical learning, large-scale optimization, and pattern extraction from data. However, I believe there remains an important underexplored path: agents whose behavior is not only predicted, but also structurally inspectable, causally traceable, and logically replayable.

My working hypothesis is that purely statistical AI, by itself, may not be sufficient to support embodied agents whose behavior is more structured, explainable, adaptive, and human-compatible. Human-compatible behavior is not only about producing plausible outputs; it also involves situated action, memory, causal structure, energy constraints, adaptation, and explainable interaction with an environment.

This library is built to explore that direction.

I am interested in the parts of AI research that have received less attention in recent years: executable symbolic structures, genome-like behavioral encodings, energy-bounded decision systems, causal replay, and digital agents whose internal behavior can be audited step by step.

The goal is not to reject statistical AI. The goal is to reopen a complementary research path: logical, causal, white-box agent simulation.

What this library is

codontrace is a compact, extensible research simulation library for studying how simple executable genomes can generate agent behavior inside deterministic environments.

The library provides:

• executable semantic genomes;
• codon-to-action translation;
• ATP-constrained white-box agents;
• deterministic World2D environments;
• structured execution traces;
• causal replay of agent decisions;
• mutation operators for genome variation;
• extension points for custom actions and experimental worlds.

The current version is intentionally focused. It is designed to be readable, testable, and suitable for researchers who want to inspect agent behavior rather than treat it as a black box.

What this library is not

codontrace is not:

• an AGI system;
• a consciousness model;
• a biological simulator;
• a replacement for neural networks or LLMs;
• a robotics control stack;
• proof of artificial life;
• proof of open-ended evolution;
• proof that logical AI is sufficient by itself;
• an output, report, dashboard, or notebook generator.

It is a research simulator and Python library. If future experiments do not produce strong emergent behavior, the project still remains useful as a controlled tool for studying traceable agents, causal replay, executable genomes, and failure modes in simple environments.

Research position

This project is positioned between several research traditions:

• digital evolution;
• artificial life;
• symbolic and programmatic agents;
• explainable AI;
• causal reasoning;
• open-ended search;
• quality-diversity exploration;
• agent observability and trace-based debugging.

The library does not claim to invent these fields. Instead, it explores a specific synthesis:

executable semantic genomes + ATP-constrained white-box agents + deterministic worlds + structured traces + causal replay.

That combination is the core research direction.

Why CodonTrace is different

A purely input-output view of intelligence can hide the internal structure of decision-making. For many embodied or safety-critical systems, it is not enough to know what an agent did. A researcher may also need to know:

• which genome segment produced the action;
• which codon was decoded;
• whether the agent had enough energy to act;
• what the agent observed;
• what changed in the world;
• whether an alternative local condition would have changed the decision;
• how a mutation changes behavior over repeated trials.

codontrace is designed to make those questions easy to ask with ordinary Python objects.

Claim level policy

The documentation uses conservative claim levels:

• design fact: intentionally implemented mechanism;
• tested: covered by tests or reproducible examples;
• needs experiment: plausible but not validated;
• aspirational: future target that requires evidence;
• out of scope: not claimed by this project.

These labels are used below to keep the scientific position honest.

Innovation points

The novelty of this library is not any single component in isolation. Its value comes from combining several ideas into a compact, inspectable Python package.

Point	Claim level	Notes
Executable semantic genome	design fact / tested	A genome is decoded into actions through a codon table.
Codon-to-action translation	design fact / tested	The genotype-to-behavior path is explicit and inspectable.
ATP-constrained agents	design fact / tested	Agents act under an energy budget and record ATP effects.
White-box decision traces	design fact / tested	Actions can be recorded as structured trace events.
Causal replay	tested in local deterministic examples	Replay is local and deterministic; it is not a general causal inference engine.
Mutation as a research primitive	design fact / tested	Mutation supports controlled comparisons between baseline and variant behavior.
Extensible research API	design fact / tested	Researchers can add custom actions, custom world metadata, and plugin registrars.
Larger-scale simulation	aspirational	Future scale claims require benchmark scripts, fixed seeds, and repeatable evidence.
Open-ended discovery	out of scope for this release	No discovery or open-endedness proof is claimed in v0.2.0a3.
Human-compatible embodied behavior	research motivation / needs experiment	This is a motivation for controlled experiments, not a current capability claim.

Scalability position

codontrace is designed with scalability in mind, but it does not claim large-scale performance without evidence.

The current library focuses on correctness, reproducibility, clean API design, and experiment structure. Larger-scale simulations should be treated as future benchmark targets, not as current claims.

The architecture is intentionally modular so that future versions can explore:

• larger worlds;
• more agents;
• richer action registries;
• batch experiments;
• structured experiment logs;
• reproducibility artifacts;
• performance-oriented backends.

Any future scale claim should be backed by benchmark results, fixed seeds, repeatable configurations, and published measurement scripts.

Install

For local development:

python -m pip install -e ".[dev]"

For a built wheel:

python -m pip install dist/codontrace-0.2.0a3-py3-none-any.whl

Quick start

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)
assert result.explanation is not None

print(result.trace.last().action)
print(result.explanation.summary)

In ASCII worlds:

• . means empty space.
• A marks the initial agent position.
• * marks a resource.
• # marks a wall.

run_trial() returns a RunResult containing the agent, world, trace, and optional explanation. It does not create files, reports, charts, or dashboards.

Core API

Manual agent creation

from codontrace import AgentFactory, AgentSpec, SemanticGenome, World2D

world = World2D(4, 4)
agents = AgentFactory.from_specs(
    [
        AgentSpec(
            agent_id="explorer-1",
            genome=SemanticGenome.from_codons(["101", "111", "000"]),
            initial_atp=4.0,
            position=(1, 1),
            profile="explorer",
        )
    ],
    world=world,
)

Automatic and profiled agent creation

from codontrace import AgentFactory, AgentProfile, InitializationConfig, World2D

world = World2D(width=12, height=8)
agents = AgentFactory.create_many(
    world=world,
    config=InitializationConfig(
        count=50,
        seed=42,
        genome_strategy="profiled_random",
        placement_strategy="poisson_disk",
        profiles=(
            AgentProfile(name="explorer", count=20, genome_length=8, initial_atp=4.0),
            AgentProfile(name="collector", count=20, genome_length=6, initial_atp=6.0),
            AgentProfile(name="conserver", count=10, genome_length=4, initial_atp=8.0),
        ),
    ),
)

Available genome strategies are uniform_random, profiled_random, lineage_seeded, and latin_hypercube_lite. The latin_hypercube_lite strategy is a pure-Python LHS-inspired coverage strategy, not full QMC. latin_hypercube is kept as a backward-compatible alias. Placement strategies are uniform_random, poisson_disk, and grid.

Multi-agent simulation API

from codontrace import AgentFactory, InitializationConfig, Simulation, SimulationConfig, World2D

world = World2D(8, 8)
agents = AgentFactory.create_many(
    world=world,
    config=InitializationConfig(count=10, seed=7, placement_strategy="grid"),
)
result = Simulation.run(
    world=world,
    agents=agents,
    config=SimulationConfig(steps=20, scheduler="random_order", seed=7),
)

print(result.trace_digest)

Simulation.run() returns a SimulationResult object. It does not print, write files, or create hidden output directories.

Custom actions

from codontrace import ATPAccount, Codon, CodonTable, SemanticGenome, Trace, WhiteBoxAgent, World2D
from codontrace.actions import ActionContext, ActionResult, default_action_registry


def rest_handler(ctx: ActionContext) -> ActionResult:
    return ActionResult.executed(
        reason="rested",
        position_after=ctx.position,
        world_delta={"rest": True},
    )

table = CodonTable.default_minimal().replace(
    Codon("001", "REST", 0.0, "Recover without moving.")
)
registry = default_action_registry().extend("REST", rest_handler)
agent = WhiteBoxAgent(
    id="a1",
    genome=SemanticGenome.from_codons(["001"]),
    codon_table=table,
    atp_account=ATPAccount(5.0),
    position=(1, 1),
    action_registry=registry,
)
trace = Trace()
event = agent.step(World2D(3, 3), trace)
assert event.action == "REST"

Custom ATP effects

Handlers must not mutate ATPAccount directly. They can request ATP effects declaratively:

from codontrace.actions import ActionContext, ActionResult, EnergyEffect


def charge(ctx: ActionContext) -> ActionResult:
    return ActionResult.executed(
        reason="charged",
        position_after=ctx.position,
        world_delta={"charged": True},
        energy=EnergyEffect(credit=1.0, reason="charge_action"),
    )

The agent core applies credits/debits through ATPAccount, records ledger entries, and attaches all ledger IDs to TraceEvent.ledger_entry_ids.

World object metadata layer

from codontrace import World2D, WorldObject

world = World2D(5, 5)
world.add_object((2, 2), WorldObject(kind="FOOD", amount=3.0, metadata={"source": "user"}))
objects = world.objects_at((2, 2))

WorldObject is metadata only. It does not implement physics, rewards, AI behavior, or automatic effects.

Plugin discovery

Third-party packages can expose action registrars with Python entry points:

[project.entry-points."codontrace.actions"]
my_actions = "my_package.actions:register_actions"

from codontrace import ActionRegistry


def register_actions(registry: ActionRegistry) -> ActionRegistry:
    return registry.extend("REST", rest_handler)

Then use:

from codontrace import discover_action_plugins

registry = discover_action_plugins()

No external plugin framework is required in core.

Research use cases

codontrace can be used to explore:

• how executable genomes produce behavior;
• how energy constraints shape agent decisions;
• how mutation affects behavior;
• how local world state influences action selection;
• how causal replay can support explainable agent simulation;
• how compact deterministic environments can be used as testbeds for interpretable agency;
• how symbolic and causal mechanisms can complement statistical AI.

Using inside a research app

codontrace returns objects:

result.trace
result.final_world
result.agent_states
result.trace_digest

A research app decides how to export, visualize, store, or analyze them.

Reproducibility

Use AgentFactory.create_specs() to create an inspectable initialization plan before constructing agents:

specs = AgentFactory.create_specs(world=world, config=config)
payload = [spec.to_dict() for spec in specs]
restored = tuple(AgentSpec.from_dict(item) for item in payload)

Object serialization is dictionary/string based and optional:

jsonl_text = result.trace.to_jsonl_string()
restored_trace = Trace.from_jsonl_string(jsonl_text)

payload = result.to_dict()
restored_result = SimulationResult.from_dict(payload)

The core does not call save(path), load(path), or write files for you.

Limitations and non-claims

This library is experimental.

The current version uses compact deterministic worlds and minimal behavioral primitives. It does not prove artificial life, human-like intelligence, AGI, consciousness, or open-ended evolution.

The project should be evaluated as a research tool. Its value is in providing a clean experimental substrate for controlled questions, not in claiming that those questions are already solved.

If an experiment fails to produce emergent or useful behavior, that failure should be treated as data. Negative results are still useful because they clarify which mechanisms are insufficient, which assumptions were wrong, and which parts of the design need to be revised.

Scientific background / prior art

This project is influenced by several research traditions:

• Digital evolution: self-replicating and evolving computer programs, including Tierra and Avida.
• Open-ended and novelty-driven search: novelty search, quality-diversity, MAP-Elites, and POET-style environment-agent coevolution.
• Symbolic and programmatic agents: explicit behavioral programs and inspectable decision structures.
• Explainable AI and causal explanation: motivation for traceable decisions, local counterfactuals, and replay-based explanations.
• Trace-based observability: motivation for structured execution logs, replayable behavior, and reproducible debugging.

The library should be understood as a compact research substrate inspired by those directions, not as a replacement for them.

Citation / references

Citation metadata for this package is available in CITATION.cff.

Recommended background references include:

• Ray, T. S. (1991). An approach to the synthesis of life. In C. G. Langton, C. Taylor, J. D. Farmer, & S. Rasmussen (Eds.), Artificial Life II. Addison-Wesley. Context: Tierra and digital organisms.
• Ofria, C., & Wilke, C. O. (2004). Avida: A software platform for research in computational evolutionary biology. Artificial Life, 10(2), 191-229. https://doi.org/10.1162/106454604773563612 Context: digital evolution experiments with self-replicating and evolving programs.
• Lehman, J., & Stanley, K. O. (2011). Abandoning objectives: Evolution through the search for novelty alone. Evolutionary Computation, 19(2), 189-223. https://doi.org/10.1162/EVCO_a_00025 Context: novelty search and stepping-stone behavior.
• Mouret, J.-B., & Clune, J. (2015). Illuminating search spaces by mapping elites. arXiv:1504.04909. Context: MAP-Elites and quality-diversity search.
• Wang, R., Lehman, J., Clune, J., & Stanley, K. O. (2019). Paired Open-Ended Trailblazer (POET): Endlessly generating increasingly complex and diverse learning environments and their solutions. arXiv:1901.01753. Context: environment-agent coevolution and open-ended search.

Additional formal references for explainable AI, causal explanation, or trace observability should be added only when the exact paper details are verified.

Development status

codontrace is currently an alpha-stage research library.

The current priority is:

1. stable public API;
2. reproducible examples;
3. readable source code;
4. complete tests;
5. honest documentation;
6. controlled scientific claims;
7. extensibility for future research.

Roadmap

• 0.2.0a3: developer-experience API layer on top of the library-first research core.
• 0.2.0a3-docs: README scientific positioning and documentation hardening.
• 0.2.0a3-testpypi: packaging and TestPyPI candidate after documentation gates pass.
• 0.2.0b1: optional adapters after core gates pass.
• 0.3.0a1: population runtime exploration, still without discovery claims unless D0, ablation, and multi-seed gates exist.

License

MIT.