trulens.apps.gepa.fitness

trulens.apps.gepa.fitness

GEPA fitness function adapter for TruLens feedback functions.

GEPA (Genetic/Evolutionary Prompt Adaptation) optimizes prompts using evolutionary algorithms. A fitness function is any callable that scores a candidate prompt as a float in [0, 1].

This module provides:

• :class:TruGEPA — wraps any TruLens feedback callable into the GEPA fitness-function interface and optionally logs each evaluation as a TruVirtual record for dashboard visibility when both app_name and app_version are supplied.
• :func:run_evolution — a simple (μ+λ) evolutionary loop that uses a fitness function to iteratively improve a base prompt.

Classes

TruGEPA

Adapts a TruLens feedback callable as a GEPA-compatible fitness function.

A GEPA fitness function is any callable (prompt: str, **kwargs) -> float. TruGEPA forwards each call to a TruLens feedback function implementation and, when both app_name and app_version are supplied, logs every evaluation as a TruVirtual record so the full optimization trajectory is visible in the TruLens dashboard.

Logging behaviour:

• Both app_name and app_version supplied → a TruVirtual recorder is created eagerly and every evaluation is logged. A TruSession must be active at construction time.
• Neither supplied → logging is disabled; evaluations run silently.
• Only one supplied → raises ValueError immediately.

PARAMETER	DESCRIPTION
feedback_fn	A TruLens feedback function implementation — any callable that accepts text keyword arguments and returns a float or a (float, dict) tuple (the standard TruLens return format). TYPE: Callable
optimize_key	The keyword argument name in feedback_fn that receives the evolving candidate prompt string. Defaults to "prompt". TYPE: str DEFAULT: 'prompt'
feedback_args	All other keyword arguments forwarded unchanged to feedback_fn on every call (e.g. {"context": "..."} for context_relevance, or {"source": "..."} for groundedness). TYPE: Optional[dict] DEFAULT: None
app_name	Name of the virtual app used for TruLens logging. Must be supplied together with app_version; omit both to disable logging. TYPE: Optional[str] DEFAULT: None
app_version	Version string of the virtual app. Must be supplied together with app_name; omit both to disable logging. TYPE: Optional[str] DEFAULT: None

Functions

__call__

__call__(prompt: str, **kwargs: Any) -> float

Evaluate prompt and return a fitness score.

PARAMETER	DESCRIPTION
prompt	The prompt string to evaluate. TYPE: str
**kwargs	Additional keyword arguments forwarded to the underlying feedback function. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
float	Float fitness score, typically in [0, 1].

Functions

run_evolution

run_evolution(
    base_prompt: str,
    fitness_fn: Callable[[str], float],
    mutate_fn: Callable[[str], str],
    *,
    n_generations: int = 10,
    population_size: int = 5,
    top_k: int = 2,
    seed: Optional[int] = None
) -> Tuple[str, float, List[Tuple[str, float]]]

Run a (μ+λ) evolutionary loop to optimize a prompt.

At each generation:

1. Score all candidates with fitness_fn.
2. Keep the top-top_k candidates (elitist selection).
3. Fill the next population by mutating survivors at random.

When fitness_fn is a :class:TruGEPA, every prompt evaluation is logged as a TruLens virtual record, giving a generation-by-generation audit trail in the dashboard.

PARAMETER	DESCRIPTION
base_prompt	The starting prompt for the evolutionary search. TYPE: str
fitness_fn	Any callable (prompt: str) -> float that scores a prompt. Use :class:TruGEPA to wrap a TruLens feedback function. TYPE: Callable[[str], float]
mutate_fn	Callable that takes a prompt string and returns a mutated variant (e.g. rephrasing, adding instructions, changing tone). TYPE: Callable[[str], str]
n_generations	Number of evolutionary generations to run. TYPE: int DEFAULT: 10
population_size	Number of candidate prompts evaluated per generation. TYPE: int DEFAULT: 5
top_k	Number of top-scoring candidates carried over to the next generation (elitist survivors). TYPE: int DEFAULT: 2
seed	Optional random seed for reproducibility. TYPE: Optional[int] DEFAULT: None

RETURNS	DESCRIPTION
str	A three-tuple (best_prompt, best_score, history) where history
float	is a list of (best_prompt_in_generation, best_score_in_generation)
List[Tuple[str, float]]	pairs, one entry per generation.