InstructionProposalSignature

gepa.strategies.instruction_proposal.InstructionProposalSignature() dataclass

Bases: Signature

Attributes

default_prompt_template = "I provided an assistant with the following instructions to perform a task for me:\n```\n<curr_instructions>\n```\n\nThe following are examples of different task inputs provided to the assistant along with the assistant's response for each of them, and some feedback on how the assistant's response could be better:\n```\n<inputs_outputs_feedback>\n```\n\nYour task is to write a new instruction for the assistant.\n\nRead the inputs carefully and identify the input format and infer detailed task description about the task I wish to solve with the assistant.\n\nRead all the assistant responses and the corresponding feedback. Identify all niche and domain specific factual information about the task and include it in the instruction, as a lot of it may not be available to the assistant in the future. The assistant may have utilized a generalizable strategy to solve the task, if so, include that in the instruction as well.\n\nProvide the new instructions within ``` blocks." class-attribute instance-attribute

input_keys: list[str] = ['current_instruction_doc', 'dataset_with_feedback', 'prompt_template'] class-attribute

output_keys: list[str] = ['new_instruction'] class-attribute

prompt_template: str class-attribute

Functions

validate_prompt_template(prompt_template: str | None) -> None classmethod

Source code in gepa/strategies/instruction_proposal.py

@classmethod
def validate_prompt_template(cls, prompt_template: str | None) -> None:
    if prompt_template is None:
        return
    missing_placeholders = [
        placeholder
        for placeholder in ("<curr_instructions>", "<inputs_outputs_feedback>")
        if placeholder not in prompt_template
    ]
    if missing_placeholders:
        raise ValueError(f"Missing placeholder(s) in prompt template: {', '.join(missing_placeholders)}")

prompt_renderer(input_dict: Mapping[str, Any]) -> str classmethod

Source code in gepa/strategies/instruction_proposal.py

@classmethod
def prompt_renderer(cls, input_dict: Mapping[str, Any]) -> str:
    current_instruction = input_dict.get("current_instruction_doc")
    if not isinstance(current_instruction, str):
        raise TypeError("current_instruction_doc must be a string")

    dataset = input_dict.get("dataset_with_feedback")
    if not isinstance(dataset, Sequence) or isinstance(dataset, (str, bytes)):
        raise TypeError("dataset_with_feedback must be a sequence of records")

    def format_samples(samples):
        def render_value(value, level=3):
            # level controls markdown header depth (###, ####, etc.)
            if isinstance(value, dict):
                s = ""
                for k, v in value.items():
                    s += f"{'#' * level} {k}\n"
                    s += render_value(v, min(level + 1, 6))
                if not value:
                    s += "\n"
                return s
            elif isinstance(value, list | tuple):
                s = ""
                for i, item in enumerate(value):
                    s += f"{'#' * level} Item {i + 1}\n"
                    s += render_value(item, min(level + 1, 6))
                if not value:
                    s += "\n"
                return s
            else:
                return f"{str(value).strip()}\n\n"

        def convert_sample_to_markdown(sample, examplenum):
            s = f"# Example {examplenum}\n"
            for key, val in sample.items():
                s += f"## {key}\n"
                s += render_value(val, level=3)
            return s

        return "\n\n".join(convert_sample_to_markdown(sample, i + 1) for i, sample in enumerate(samples))

    prompt_template = input_dict.get("prompt_template")
    if prompt_template is None:
        prompt_template = cls.default_prompt_template

    cls.validate_prompt_template(prompt_template)

    prompt = prompt_template.replace("<curr_instructions>", current_instruction)
    prompt = prompt.replace("<inputs_outputs_feedback>", format_samples(dataset))

    return prompt

output_extractor(lm_out: str) -> dict[str, str] classmethod

Source code in gepa/strategies/instruction_proposal.py

@classmethod
def output_extractor(cls, lm_out: str) -> dict[str, str]:
    def extract_instruction_text() -> str:
        # Find the first and last backtick positions (if any)
        start = lm_out.find("```") + 3
        end = lm_out.rfind("```")

        # Handle if the first and last backticks are the same or overlap
        if start >= end:
            # Handle incomplete blocks
            stripped = lm_out.strip()
            if stripped.startswith("```"):
                # Remove opening ``` and optional language specifier
                match = re.match(r"^```\S*\n?", lm_out)
                if match:
                    return lm_out[match.end() :].strip()
            elif stripped.endswith("```"):
                # Remove closing ```
                return stripped[:-3].strip()
            return stripped

        # Skip optional language specifier
        content = lm_out[start:end]
        match = re.match(r"^\S*\n", content)
        if match:
            content = content[match.end() :]

        return content.strip()

    return {"new_instruction": extract_instruction_text()}

run(lm: LanguageModel, input_dict: Mapping[str, Any]) -> dict[str, str] classmethod

Source code in gepa/proposer/reflective_mutation/base.py

@classmethod
def run(cls, lm: LanguageModel, input_dict: Mapping[str, Any]) -> dict[str, str]:
    full_prompt = cls.prompt_renderer(input_dict)
    lm_out = lm(full_prompt).strip()
    return cls.output_extractor(lm_out)