Overview
The Merge module implements a three-way text merge algorithm based on diff_match_patch, used to reconcile changes between a base text and two divergent versions.
Description
This module provides a single merge function that performs a three-way merge of text strings. Given a base text, a source modification, and a target modification, it computes the diffs between the base and each modified version using the diff_match_patch library, then walks both diff sequences in parallel to produce a merged result. The algorithm handles additions, deletions, and preserved regions from both sides, resolving conflicts by favoring deletions over additions and using Levenshtein distance heuristics for ambiguous addition-vs-addition conflicts. The implementation is adapted from the three-merge library. Constants PRESERVED (0), DELETION (-1), and ADDITION (1) map to the diff operation types.
Usage
Use this module when you need to merge two independently modified versions of a text against their common base. This is used within Guardrails to reconcile prompt or output modifications from different processing stages, such as merging LLM-generated output with corrected or re-asked versions.
Code Reference
Source Location
Signature
DIFFER: diff_match_patch
PRESERVED: int # 0
DELETION: int # -1
ADDITION: int # 1
def merge(
source: Optional[str],
target: Optional[str],
base: Optional[str],
) -> Optional[str]
Import
from guardrails.merge import merge
I/O Contract
merge
| Parameter |
Type |
Description
|
source |
Optional[str] |
The first modified version of the text
|
target |
Optional[str] |
The second modified version of the text
|
base |
Optional[str] |
The original (common ancestor) text that both source and target were derived from
|
| Returns |
Type |
Description
|
| Merged text |
Optional[str] |
The merged result string, or None if any input is None
|
Conflict Resolution Strategy
| Conflict Type |
Resolution
|
| Deletion vs. Addition |
Favors deletion; the added text is discarded
|
| Addition vs. Addition (overlapping) |
If one addition starts with the other, the longer one is kept; otherwise, the addition with the greatest Levenshtein distance from the previous text is selected
|
| Deletion vs. Deletion (non-matching) |
Both deletions are applied; neither text is preserved
|
| Preserved regions of different lengths |
The shorter preserved region is consumed and the difference is carried forward to process target/source additions
|
Usage Examples
from guardrails.merge import merge
base = "The quick brown fox jumps over the lazy dog."
source = "The quick brown fox leaps over the lazy dog."
target = "The quick brown fox jumps over the sleepy dog."
result = merge(source, target, base)
# result: "The quick brown fox leaps over the sleepy dog."
# Returns None when any input is None
result = merge(None, target, base)
# result: None
Related Pages
Page Connections
Double-click a node to navigate. Hold to expand connections.
