Implementation:Explodinggradients Ragas Version Experiment Function

Knowledge Sources	Domains	Last Updated
explodinggradients/ragas	Experiment Management, Reproducibility	2026-02-10

Overview

The Version Experiment Function creates Git-based snapshots of the codebase state for evaluation experiments, optionally creating named branches for easy navigation between experiment versions.

Description

The version_experiment() function (lines 21-100 of src/ragas/experiment.py) uses GitPython to version control experiment states. It detects repository changes, stages them according to the specified mode (tracked-only or all files), creates a commit with a descriptive message, and optionally creates a ragas/{experiment_name} branch pointing to that commit. If no changes are detected, it returns the current HEAD commit hash without creating an empty commit. The function requires the optional ragas[git] dependency (GitPython) and raises an ImportError with installation instructions if it is not available.

Usage

Use the Version Experiment Function when:

Snapshotting code before or after running an evaluation experiment
Creating named branches to bookmark experiment iterations
Building reproducibility records that link experiment results to code versions
Automating experiment versioning in CI/CD evaluation pipelines

Code Reference

Source Location: src/ragas/experiment.py, lines 21-100

Signature:

def version_experiment(
    experiment_name: str,
    commit_message: Optional[str] = None,
    repo_path: Union[str, Path, None] = None,
    create_branch: bool = True,
    stage_all: bool = False,
) -> str

Import:

from ragas.experiment import version_experiment

I/O Contract

Inputs:

Parameter	Type	Required	Description
`experiment_name`	`str`	Yes	Name for the experiment, used in the branch name (`ragas/{experiment_name}`) and default commit message
`commit_message`	`Optional[str]`	No	Custom commit message (defaults to `"Experiment: {experiment_name}"`)
`repo_path`	`Union[str, Path, None]`	No	Path to the Git repository (defaults to auto-detected git root via `find_git_root()`)
`create_branch`	`bool`	No	Whether to create a named branch for the experiment (default: `True`)
`stage_all`	`bool`	No	Whether to stage untracked files; when `False`, only tracked file changes are staged (default: `False`)

Outputs:

Output	Type	Description
Commit hash	`str`	The full SHA hash of the Git commit capturing the experiment state (or current HEAD if no changes)

Side Effects:

Effect	Condition
Git commit created	When there are staged changes in the repository
Git branch created	When `create_branch=True` (branch name: `ragas/{experiment_name}`)
Files staged	Modified tracked files (or all files if `stage_all=True`)
Console output	Progress messages printed to stdout

Raises:

Exception	Condition
`ImportError`	GitPython is not installed (provides installation instructions)

Usage Examples

Basic experiment versioning:

from ragas.experiment import version_experiment

# Version the current codebase state for an experiment
commit_hash = version_experiment("eval-v1")
print(f"Versioned at: {commit_hash[:8]}")
# Output:
# Staging changes to tracked files
# Changes committed with hash: a1b2c3d4
# Created branch: ragas/eval-v1
# Versioned at: a1b2c3d4

Custom commit message without branch:

from ragas.experiment import version_experiment

commit_hash = version_experiment(
    experiment_name="qa-eval-v2",
    commit_message="Experiment: Updated prompt template for QA evaluation",
    create_branch=False,
)

Staging all files including untracked:

from ragas.experiment import version_experiment

# Include new files that were added for this experiment
commit_hash = version_experiment(
    experiment_name="new-metrics-eval",
    stage_all=True,
)

Specifying a repository path:

from pathlib import Path
from ragas.experiment import version_experiment

commit_hash = version_experiment(
    experiment_name="remote-eval",
    repo_path=Path("/path/to/my/project"),
)

Integration with experiment workflow:

import asyncio
from ragas import Dataset, experiment
from ragas.experiment import version_experiment

# 1. Version the code before running
commit_hash = version_experiment("faithfulness-eval-v3")

# 2. Run the experiment
@experiment()
async def evaluate(row):
    # evaluation logic
    return {"score": 0.95}

dataset = Dataset.load("test_data", "local/csv", root_dir="./data")
results = asyncio.run(evaluate.arun(dataset))

# 3. The commit_hash links results to the exact code version
print(f"Results from code version: {commit_hash[:8]}")

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment