Prompts

Utilities for loading and rendering Jinja prompt templates with strict undefined-variable behaviour: a reference to a missing context variable raises TemplateError rather than rendering a silently incomplete prompt. AnalysisMode selects the template subdirectory (agentic or single_turn). See Architecture for how processors assemble prompts.

prompts

Prompt loading utilities for GAZE.

Provides Jinja2 template loading and rendering for system and task prompts. Dataset-specific implementations should provide their own prompts directory.

Templates use strict undefined variable behavior: any reference to a variable not present in the context dict will raise TemplateError immediately, preventing silent generation of incomplete prompts.

AnalysisMode

Bases: str, Enum

Analysis modes for prompt generation.

Inherits from str for easy comparison with string values.

Source code in src/gaze/prompts/__init__.py

class AnalysisMode(str, Enum):
    """Analysis modes for prompt generation.

    Inherits from str for easy comparison with string values.
    """

    AGENTIC = "agentic"
    SINGLE_TURN = "single_turn"

load_template

load_template(
    template_path: Path, context: dict[str, Any]
) -> str

Load and render a Jinja template with the given context.

Uses strict undefined variable behavior: any variable referenced in the template but missing from context will raise TemplateError.

Parameters:

Name	Type	Description	Default
template_path	Path	Path to the Jinja template file	required
context	dict[str, Any]	Dictionary of variables for template rendering	required

Returns:

Type	Description
str	Rendered template string

Raises:

Type	Description
TemplateError	If template file doesn't exist, a required variable is missing, or rendering fails for any other reason.

Example

from pathlib import Path from gaze.prompts import load_template

prompt = load_template( Path("prompts/system.jinja"), {"task": "diagnosis", "modality": "MRI"} )

Source code in src/gaze/prompts/__init__.py

@beartype
def load_template(
    template_path: Path,
    context: dict[str, Any],
) -> str:
    """Load and render a Jinja template with the given context.

    Uses strict undefined variable behavior: any variable referenced in the
    template but missing from *context* will raise ``TemplateError``.

    Args:
        template_path: Path to the Jinja template file
        context: Dictionary of variables for template rendering

    Returns:
        Rendered template string

    Raises:
        TemplateError: If template file doesn't exist, a required variable
            is missing, or rendering fails for any other reason.

    Example:
        from pathlib import Path
        from gaze.prompts import load_template

        prompt = load_template(
            Path("prompts/system.jinja"),
            {"task": "diagnosis", "modality": "MRI"}
        )
    """
    try:
        with open(template_path, encoding="utf-8") as f:
            template_content = f.read()
    except FileNotFoundError as e:
        raise TemplateError(
            f"Template file not found: {template_path}",
            template_path=template_path,
        ) from e
    except OSError as e:
        raise TemplateError(
            f"Failed to read template file: {e}",
            template_path=template_path,
        ) from e

    try:
        return _env.render_str(template_content, **context)
    except (ValueError, TypeError, RuntimeError, MinijinjaTemplateError) as e:
        raise TemplateError(
            f"Failed to render template: {e}",
            template_path=template_path,
        ) from e

load_prompt

load_prompt(
    prompts_dir: Path,
    template_name: str,
    mode: str,
    context: dict[str, Any],
) -> str

Load and render a prompt template from a prompts directory.

Parameters:

Name	Type	Description	Default
prompts_dir	Path	Base directory containing mode subdirectories	required
template_name	str	Name of the template file (e.g., 'task.jinja')	required
mode	str	Analysis mode ('agentic' or 'single_turn')	required
context	dict[str, Any]	Dictionary of variables for template rendering	required

Returns:

Type	Description
str	Rendered prompt string

Raises:

Type	Description
ValueError	If mode directory doesn't exist
TemplateError	If template file doesn't exist or rendering fails

Source code in src/gaze/prompts/__init__.py

@beartype
def load_prompt(
    prompts_dir: Path,
    template_name: str,
    mode: str,
    context: dict[str, Any],
) -> str:
    """Load and render a prompt template from a prompts directory.

    Args:
        prompts_dir: Base directory containing mode subdirectories
        template_name: Name of the template file (e.g., 'task.jinja')
        mode: Analysis mode ('agentic' or 'single_turn')
        context: Dictionary of variables for template rendering

    Returns:
        Rendered prompt string

    Raises:
        ValueError: If mode directory doesn't exist
        TemplateError: If template file doesn't exist or rendering fails
    """
    valid_modes = [m.value for m in AnalysisMode]
    if mode not in valid_modes:
        raise ValueError(f"Unknown mode: {mode!r}. Valid modes: {valid_modes}")

    mode_dir = prompts_dir / mode
    if not mode_dir.exists():
        raise ValueError(f"Mode directory not found: {mode_dir}")

    template_path = mode_dir / template_name
    return load_template(template_path, context)

combine_prompts

combine_prompts(
    system_prompt: str, task_prompt: str, mode: str
) -> str

Combine system prompt with task-specific prompt.

Parameters:

Name	Type	Description	Default
system_prompt	str	The base system prompt	required
task_prompt	str	The task-specific prompt	required
mode	str	Analysis mode string (must be valid AnalysisMode value)	required

Returns:

Type	Description
str	Combined prompt string

Raises:

Type	Description
ValueError	If mode is not a valid AnalysisMode

Source code in src/gaze/prompts/__init__.py

@beartype
def combine_prompts(
    system_prompt: str,
    task_prompt: str,
    mode: str,
) -> str:
    """Combine system prompt with task-specific prompt.

    Args:
        system_prompt: The base system prompt
        task_prompt: The task-specific prompt
        mode: Analysis mode string (must be valid AnalysisMode value)

    Returns:
        Combined prompt string

    Raises:
        ValueError: If mode is not a valid AnalysisMode
    """
    try:
        mode_enum = AnalysisMode(mode)
    except ValueError:
        valid_modes = [m.value for m in AnalysisMode]
        raise ValueError(f"Unknown mode: {mode}. Valid modes: {valid_modes}") from None

    if mode_enum == AnalysisMode.SINGLE_TURN:
        return (
            f"{system_prompt}\n\n<analysis_instructions>\n{task_prompt}\n</analysis_instructions>"
        )
    if mode_enum == AnalysisMode.AGENTIC:
        return (
            f"{system_prompt}\n\n"
            f"<agentic_analysis_instructions>\n{task_prompt}\n"
            f"</agentic_analysis_instructions>"
        )

    assert_never(mode_enum)

create_prompt

create_prompt(
    prompts_dir: Path,
    mode: str,
    context: dict[str, Any],
    template_name: str = "task.jinja",
) -> str

Create a complete prompt by combining system and task prompts.

Parameters:

Name	Type	Description	Default
prompts_dir	Path	Base directory containing mode subdirectories	required
mode	str	Analysis mode ('agentic' or 'single_turn')	required
context	dict[str, Any]	Dictionary of variables for template rendering. Standard context variables for generic GAZE templates: - domain_expertise: Domain-specific expertise description - analysis_workflow: Domain-specific analysis workflow steps - task_instructions: The specific task to perform - image_info: Information about the image (dimensions, etc.) - context: Additional context (e.g., clinical history) - output_format: Description of expected output format Note: Tool documentation is injected automatically by _run_analysis() from the ToolRegistry — do NOT pass it as a template context variable.	required
template_name	str	Name of the task template (default: 'task.jinja')	'task.jinja'

Returns:

Type	Description
str	Complete combined prompt string

Example

from gaze.prompts import create_prompt

prompt = create_prompt( prompts_dir=Path("my_prompts"), mode="agentic", context={ "domain_expertise": "You are an expert radiologist...", "task_instructions": "Analyze this brain MRI...", }, )

Source code in src/gaze/prompts/__init__.py

@beartype
def create_prompt(
    prompts_dir: Path,
    mode: str,
    context: dict[str, Any],
    template_name: str = "task.jinja",
) -> str:
    """Create a complete prompt by combining system and task prompts.

    Args:
        prompts_dir: Base directory containing mode subdirectories
        mode: Analysis mode ('agentic' or 'single_turn')
        context: Dictionary of variables for template rendering.
            Standard context variables for generic GAZE templates:
            - domain_expertise: Domain-specific expertise description
            - analysis_workflow: Domain-specific analysis workflow steps
            - task_instructions: The specific task to perform
            - image_info: Information about the image (dimensions, etc.)
            - context: Additional context (e.g., clinical history)
            - output_format: Description of expected output format

            Note: Tool documentation is injected automatically by
            ``_run_analysis()`` from the ``ToolRegistry`` — do NOT pass
            it as a template context variable.
        template_name: Name of the task template (default: 'task.jinja')

    Returns:
        Complete combined prompt string

    Example:
        from gaze.prompts import create_prompt

        prompt = create_prompt(
            prompts_dir=Path("my_prompts"),
            mode="agentic",
            context={
                "domain_expertise": "You are an expert radiologist...",
                "task_instructions": "Analyze this brain MRI...",
            },
        )
    """
    system_prompt = load_prompt(prompts_dir, "system.jinja", mode, context)
    task_prompt = load_prompt(prompts_dir, template_name, mode, context)
    return combine_prompts(system_prompt, task_prompt, mode)