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_param>\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<side_info>\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

adapter: SignatureAdapter | None = _INSTRUCTION_PROPOSAL_ADAPTER class-attribute

reasoning_tags: tuple[str, ...] = ('think',) class-attribute

prompt_template: str class-attribute

Methods:

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_param>", "<side_info>") 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 | list[dict[str, Any]] classmethod

Source code in gepa/strategies/instruction_proposal.py

@classmethod
def prompt_renderer(cls, input_dict: Mapping[str, Any]) -> str | list[dict[str, Any]]:
    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: Sequence[Mapping[str, Any]]) -> tuple[str, list[Image]]:
        """Render samples as markdown, extracting any Image objects.

        Returns:
            A tuple of (formatted_text, collected_images).  Image objects
            are replaced with ``[IMAGE-N]`` placeholders in the text.
        """
        collected_images: list[Image] = []

        def render_value(value: Any, level: int = 3) -> str:
            # level controls markdown header depth (###, ####, etc.)
            if isinstance(value, Image):
                collected_images.append(value)
                return f"[IMAGE-{len(collected_images)} — see visual content]\n\n"
            elif 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: Mapping[str, Any], examplenum: int) -> str:
            s = f"# Example {examplenum}\n"
            for key, val in sample.items():
                s += f"## {key}\n"
                s += render_value(val, level=3)
            return s

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

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

    cls.validate_prompt_template(prompt_template)

    formatted_text, images = format_samples(dataset)

    if images:
        formatted_text = (
            f"The evaluation data below includes visual content ({len(images)} image(s)). "
            "Analyze both the text and images when suggesting improvements.\n\n" + formatted_text
        )

    prompt = prompt_template.replace("<curr_param>", current_instruction)
    prompt = prompt.replace("<side_info>", formatted_text)

    # When images are present, return an OpenAI-compatible multimodal
    # messages list so the reflection LM receives the images inline.
    if images:
        content: list[dict[str, Any]] = [{"type": "text", "text": prompt}]
        for img in images:
            content.append(img.to_openai_content_part())
        return [{"role": "user", "content": content}]

    return prompt

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

Compatibility boundary for callers that require a proposal or error.

Source code in gepa/strategies/instruction_proposal.py

@classmethod
def output_extractor(cls, lm_out: str) -> dict[str, str]:
    """Compatibility boundary for callers that require a proposal or error."""
    return {"new_instruction": parse_proposal(cls, lm_out).require()}

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._render(input_dict)
    lm_res = lm(full_prompt)
    lm_out = lm_res.strip()
    return cls._parse(lm_out)

run_with_metadata(lm: LanguageModel, input_dict: Mapping[str, Any]) -> tuple[dict[str, str], str | list[dict[str, Any]], str] classmethod

Like run(), but also returns the rendered prompt and raw LM output.

Returns:

Type	Description
tuple[dict[str, str], str | list[dict[str, Any]], str]	A tuple of (extracted_output, rendered_prompt, raw_lm_output).

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

@classmethod
def run_with_metadata(
    cls, lm: LanguageModel, input_dict: Mapping[str, Any]
) -> tuple[dict[str, str], str | list[dict[str, Any]], str]:
    """Like ``run()``, but also returns the rendered prompt and raw LM output.

    Returns:
        A tuple of (extracted_output, rendered_prompt, raw_lm_output).
    """
    full_prompt = cls._render(input_dict)
    lm_res = lm(full_prompt)
    lm_out = lm_res.strip()
    return cls._parse(lm_out), full_prompt, lm_out