Database API

Tracks candidate programs, archive state, island membership, and auxiliary metadata used for sampling and visualization.

---

DatabaseConfig

Controls island topology, archive size, migration, and parent-selection behavior.

DatabaseConfig dataclass

DatabaseConfig(
    db_path: Optional[str] = None,
    num_islands: int = 2,
    archive_size: int = 40,
    elite_selection_ratio: float = 0.3,
    num_archive_inspirations: int = 1,
    num_top_k_inspirations: int = 1,
    migration_interval: int = 10,
    migration_rate: float = 0.0,
    island_elitism: bool = True,
    enforce_island_separation: bool = True,
    island_selection_strategy: str = "uniform",
    enable_dynamic_islands: bool = False,
    stagnation_threshold: int = 100,
    island_spawn_strategy: str = "initial",
    island_spawn_subtree_size: int = 1,
    parent_selection_strategy: str = "weighted",
    exploitation_alpha: float = 1.0,
    exploitation_ratio: float = 0.2,
    parent_selection_lambda: float = 10.0,
    num_beams: int = 5,
    archive_selection_strategy: str = "fitness",
    archive_criteria: Dict[str, float] = default_archive_criteria(),
)

---

Program

Persisted candidate program with lineage, metrics, embeddings, and metadata.

Program dataclass

Program(
    id: str,
    code: str,
    language: str = "python",
    parent_id: Optional[str] = None,
    archive_inspiration_ids: List[str] = list(),
    top_k_inspiration_ids: List[str] = list(),
    island_idx: Optional[int] = None,
    generation: int = 0,
    timestamp: float = time.time(),
    code_diff: Optional[str] = None,
    combined_score: float = 0.0,
    public_metrics: Dict[str, Any] = dict(),
    private_metrics: Dict[str, Any] = dict(),
    text_feedback: Union[str, List[str]] = "",
    correct: bool = False,
    children_count: int = 0,
    complexity: float = 0.0,
    embedding: List[float] = list(),
    embedding_pca_2d: List[float] = list(),
    embedding_pca_3d: List[float] = list(),
    embedding_cluster_id: Optional[int] = None,
    migration_history: List[Dict[str, Any]] = list(),
    metadata: Dict[str, Any] = dict(),
    in_archive: bool = False,
    system_prompt_id: Optional[str] = None,
)

Represents a program in the database

to_dict

to_dict() -> Dict[str, Any]

Convert to dict representation, cleaning NaN values for JSON.

from_dict classmethod

from_dict(data: Dict[str, Any]) -> Program

Create from dictionary representation, ensuring correct types for nested dicts.

---

ProgramDatabase

Main synchronous database interface.

ProgramDatabase

ProgramDatabase(
    config: DatabaseConfig,
    embedding_model: str = "text-embedding-3-small",
    read_only: bool = False,
)

SQLite-backed database for storing and managing programs during an evolutionary process. Supports MAP-Elites style feature-based organization, island populations, and an archive of elites.

get_best_program

get_best_program(metric: Optional[str] = None) -> Optional[Program]

---

Prompt Database Types

Prompt co-evolution uses a dedicated prompt database layer.

SystemPromptConfig dataclass

SystemPromptConfig(
    db_path: Optional[str] = None,
    archive_size: int = 10,
    ucb_exploration_constant: float = 1.0,
    min_programs_for_fitness: int = 3,
    epsilon: float = 0.1,
    use_optimistic_prior: bool = True,
)

Configuration for SystemPromptDatabase.

---

SystemPromptDatabase

SystemPromptDatabase(config: SystemPromptConfig, read_only: bool = False)

SQLite-backed database for storing and managing system prompts during meta-prompt evolution.