Skip to content

Genome

Base genome class and behavior descriptors.

Genome

Bases: ABC, Generic[T]

Abstract base class for evolvable genomes.

Implementations must define: - random(): Create a random genome - mutate(): Create a mutated copy - crossover(): Combine with another genome - to_stimulus(): Convert to the Stimulus a Target executes - behavior(): Extract behavior descriptor for QD

Source code in src/rotalabs_redqueen/core/genome.py 
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class Genome(ABC, Generic[T]):
    """Abstract base class for evolvable genomes.

    Implementations must define:
    - random(): Create a random genome
    - mutate(): Create a mutated copy
    - crossover(): Combine with another genome
    - to_stimulus(): Convert to the Stimulus a Target executes
    - behavior(): Extract behavior descriptor for QD
    """

    @classmethod
    @abstractmethod
    def random(cls, rng: Rng | None = None) -> T:
        """Create a random genome instance.

        Args:
            rng: Random number generator for reproducibility

        Returns:
            New random genome
        """
        pass

    @abstractmethod
    def mutate(self, rng: Rng | None = None) -> T:
        """Create a mutated copy of this genome.

        Args:
            rng: Random number generator for reproducibility

        Returns:
            New mutated genome (original unchanged)
        """
        pass

    @abstractmethod
    def crossover(self, other: T, rng: Rng | None = None) -> T:
        """Create offspring by combining with another genome.

        Args:
            other: Another genome to combine with
            rng: Random number generator for reproducibility

        Returns:
            New offspring genome
        """
        pass

    @abstractmethod
    def to_stimulus(self) -> Stimulus:
        """Convert genome to the Stimulus a Target executes.

        May be a single prompt, a multi-turn conversation, or an agentic
        action plan (see :mod:`rotalabs_redqueen.core.stimulus`).

        Returns:
            The Stimulus phenotype for evaluation.
        """
        pass

    @abstractmethod
    def behavior(self) -> BehaviorDescriptor:
        """Extract behavior descriptor for quality-diversity.

        Returns:
            Behavior descriptor characterizing this genome
        """
        pass

    @abstractmethod
    def to_dict(self) -> dict:
        """Serialize the genome to a JSON-compatible dict.

        Must round-trip via :meth:`from_dict`. This is how archives persist
        genomes for cross-run continuity.
        """
        pass

    @classmethod
    @abstractmethod
    def from_dict(cls, data: dict) -> T:
        """Reconstruct a genome from :meth:`to_dict` output."""
        pass

    def distance(self, other: T) -> float:
        """Genetic distance to another genome.

        Default implementation uses behavior distance. Override for
        custom distance metrics.

        Args:
            other: Another genome

        Returns:
            Distance value (higher = more different)
        """
        return self.behavior().distance(other.behavior())

random(rng: Rng | None = None) -> T abstractmethod classmethod

Create a random genome instance.

Parameters:

Name Type Description Default
rng Rng | None

Random number generator for reproducibility

 None

Returns:

Type Description
T

New random genome
Source code in src/rotalabs_redqueen/core/genome.py 
55
56
57
58
59
60
61
62
63
64
65
66
@classmethod
@abstractmethod
def random(cls, rng: Rng | None = None) -> T:
    """Create a random genome instance.

    Args:
        rng: Random number generator for reproducibility

    Returns:
        New random genome
    """
    pass

mutate(rng: Rng | None = None) -> T abstractmethod

Create a mutated copy of this genome.

Parameters:

Name Type Description Default
rng Rng | None

Random number generator for reproducibility

 None

Returns:

Type Description
T

New mutated genome (original unchanged)
Source code in src/rotalabs_redqueen/core/genome.py 
68
69
70
71
72
73
74
75
76
77
78
@abstractmethod
def mutate(self, rng: Rng | None = None) -> T:
    """Create a mutated copy of this genome.

    Args:
        rng: Random number generator for reproducibility

    Returns:
        New mutated genome (original unchanged)
    """
    pass

crossover(other: T, rng: Rng | None = None) -> T abstractmethod

Create offspring by combining with another genome.

Parameters:

Name Type Description Default
other T

Another genome to combine with

 required
rng Rng | None

Random number generator for reproducibility

 None

Returns:

Type Description
T

New offspring genome
Source code in src/rotalabs_redqueen/core/genome.py 
80
81
82
83
84
85
86
87
88
89
90
91
@abstractmethod
def crossover(self, other: T, rng: Rng | None = None) -> T:
    """Create offspring by combining with another genome.

    Args:
        other: Another genome to combine with
        rng: Random number generator for reproducibility

    Returns:
        New offspring genome
    """
    pass

to_stimulus() -> Stimulus abstractmethod

Convert genome to the Stimulus a Target executes.

May be a single prompt, a multi-turn conversation, or an agentic action plan (see :mod:rotalabs_redqueen.core.stimulus).

Returns:

Type Description
Stimulus

The Stimulus phenotype for evaluation.
Source code in src/rotalabs_redqueen/core/genome.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
@abstractmethod
def to_stimulus(self) -> Stimulus:
    """Convert genome to the Stimulus a Target executes.

    May be a single prompt, a multi-turn conversation, or an agentic
    action plan (see :mod:`rotalabs_redqueen.core.stimulus`).

    Returns:
        The Stimulus phenotype for evaluation.
    """
    pass

behavior() -> BehaviorDescriptor abstractmethod

Extract behavior descriptor for quality-diversity.

Returns:

Type Description
BehaviorDescriptor

Behavior descriptor characterizing this genome
Source code in src/rotalabs_redqueen/core/genome.py 
105
106
107
108
109
110
111
112
@abstractmethod
def behavior(self) -> BehaviorDescriptor:
    """Extract behavior descriptor for quality-diversity.

    Returns:
        Behavior descriptor characterizing this genome
    """
    pass

to_dict() -> dict abstractmethod

Serialize the genome to a JSON-compatible dict.

Must round-trip via :meth:from_dict. This is how archives persist genomes for cross-run continuity.

Source code in src/rotalabs_redqueen/core/genome.py 
114
115
116
117
118
119
120
121
@abstractmethod
def to_dict(self) -> dict:
    """Serialize the genome to a JSON-compatible dict.

    Must round-trip via :meth:`from_dict`. This is how archives persist
    genomes for cross-run continuity.
    """
    pass

from_dict(data: dict) -> T abstractmethod classmethod

Reconstruct a genome from :meth:to_dict output.

Source code in src/rotalabs_redqueen/core/genome.py 
123
124
125
126
127
@classmethod
@abstractmethod
def from_dict(cls, data: dict) -> T:
    """Reconstruct a genome from :meth:`to_dict` output."""
    pass

distance(other: T) -> float

Genetic distance to another genome.

Default implementation uses behavior distance. Override for custom distance metrics.

Parameters:

Name Type Description Default
other T

Another genome

 required

Returns:

Type Description
float

Distance value (higher = more different)
Source code in src/rotalabs_redqueen/core/genome.py 
129
130
131
132
133
134
135
136
137
138
139
140
141
def distance(self, other: T) -> float:
    """Genetic distance to another genome.

    Default implementation uses behavior distance. Override for
    custom distance metrics.

    Args:
        other: Another genome

    Returns:
        Distance value (higher = more different)
    """
    return self.behavior().distance(other.behavior())

BehaviorDescriptor

Characterizes behavior for quality-diversity algorithms.

The behavior descriptor places an individual in a multi-dimensional behavior space, enabling MAP-Elites and novelty search.

Source code in src/rotalabs_redqueen/core/genome.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@dataclass(frozen=True)
class BehaviorDescriptor:
    """Characterizes behavior for quality-diversity algorithms.

    The behavior descriptor places an individual in a multi-dimensional
    behavior space, enabling MAP-Elites and novelty search.
    """

    values: tuple[float, ...]

    def distance(self, other: BehaviorDescriptor) -> float:
        """Euclidean distance between behavior descriptors."""
        if len(self.values) != len(other.values):
            raise ValueError("Behavior descriptors must have same dimensions")
        return float(np.sqrt(sum((a - b) ** 2 for a, b in zip(self.values, other.values))))

    def __len__(self) -> int:
        return len(self.values)

    def __getitem__(self, idx: int) -> float:
        return self.values[idx]

distance(other: BehaviorDescriptor) -> float

Euclidean distance between behavior descriptors.

Source code in src/rotalabs_redqueen/core/genome.py 
31
32
33
34
35
def distance(self, other: BehaviorDescriptor) -> float:
    """Euclidean distance between behavior descriptors."""
    if len(self.values) != len(other.values):
        raise ValueError("Behavior descriptors must have same dimensions")
    return float(np.sqrt(sum((a - b) ** 2 for a, b in zip(self.values, other.values))))