# Random Search (`random`)

> The plain keep-all evolve loop, but the parent and its context are chosen uniformly at random instead of by fitness.

## Overview

Random Search is a deliberately small community scaffold: the standard Galapagos evolve loop with **uniform-random selection** in place of greedy elitism. Every iteration draws a parent uniformly from the complete candidate history and samples distinct inspirations from the remaining candidates, so fitness never steers which program is expanded next.

Every component lives in this package — the scaffold is self-contained and does not borrow another scaffold's classes. All of them are the standard Galapagos building blocks except selection: a keep-all `RandomPopulation`, the default multi-section `RandomPromptBuilder`, the SEARCH/REPLACE `RandomProposer`, the task-supplied evaluator, and null `RandomMemory`. Only `RandomSelectionPolicy` carries real behavior. Holding everything but selection fixed makes random-vs-elitist selection the single independent variable, which is what makes this a clean exploration-oriented reference point for adaptive search.

The policy uses Galapagos's seeded selection RNG, so the same `seed` and population history reproduce the same choices, and a resumed run continues the same draw stream. When the population contains only the initial seed, that seed is used as its own inspiration so the context is never empty.

## Algorithm

```
seed -> evaluate -> population.add(seed)

repeat until max_iterations:
    members     = population.all()                   # the full keep-all history
    parent      = uniform_choice(members)            # fitness plays no role
    inspiration = uniform_sample(members - parent, K) or [parent]

    prompt = build(parent, inspiration, memory)      # task -> metrics -> feedback -> inspirations -> current
    child  = propose(parent, prompt)                 # one LLM call -> SEARCH/REPLACE diff
    score  = evaluate(child)                          # task-supplied evaluator (retried up to inner_retry_times)
    population.add(child)                              # keep-all; drawn from next iteration
```

## Components

A Galapagos scaffold composes six components. Random Search keeps the standard defaults everywhere except selection.

| Slot | Implementation | Role |
|---|---|---|
| Population | `RandomPopulation` (InMemoryPopulation, keep-all) | Uncapped store over the full history; errored children dropped. |
| SelectionPolicy | `RandomSelectionPolicy` (uniform_random) | Uniform-random parent + distinct random inspirations; seeded, resume-safe. |
| PromptBuilder | `RandomPromptBuilder` (DefaultPromptBuilder) | Canonical task → metrics → feedback → inspirations → current template. |
| Proposer | `RandomProposer` (LLMProposer) | One LLM call → SEARCH/REPLACE diff, with no-op detection. |
| Evaluator | task-supplied | Scores each child; provides the combined score. |
| Memory | `RandomMemory` (NullMemory, none) | None — Random Search keeps no cross-candidate knowledge. |

## Configuration

- `general.max_iterations` (100) — number of select → propose → evaluate → admit steps.
- `population.capacity` (null) — uncapped keep-all by default; set an int to bound the archive.
- `selection_policy.num_inspirations` (4) — K, the number of random context programs shown alongside the parent.
- `seed` (0) — RNG seed for the selection policy; fixes the (otherwise random) draw stream for reproducibility.
- `general.inner_retry_times` (3) — attempts per iteration when a proposal fails to parse or evaluate.

## When to use

Reach for Random Search as the exploration-side counterpart to `topk`: same pipeline, but selection ignores fitness entirely. It is the natural control when you want to measure whether a method's *selection* strategy is actually doing work — if an adaptive scaffold cannot beat uniform-random selection on a task, the gain is coming from somewhere other than selection. It has no mechanism to concentrate effort on promising candidates, so it is a baseline, not a strategy for hard optimization.

## Source

A minimal community variant of the Galapagos `topk` baseline. Random Search reuses the same evolve pipeline but replaces greedy rank-1 selection with uniform-random parent/context sampling; it is implemented from the shared `galapagos.components` building blocks rather than by importing another scaffold's classes.