coord2region.llm#

LLM utilities for prompt construction and summary generation.

The summary helpers keep an in-memory LRU cache keyed by (model, prompt). The cache currently uses a fixed size controlled by SUMMARY_CACHE_SIZE.

Attributes#

LLM_PROMPT_TEMPLATES

IMAGE_PROMPT_TEMPLATES

Functions#

generate_mni152_image(→ bytes)

Return a PNG image of a sphere drawn on the MNI152 template.

generate_llm_prompt(→ str)

Generate a detailed prompt for language models based on studies.

generate_region_image_prompt(→ str)

Generate a prompt for creating images of brain regions.

generate_region_image(→ bytes)

Generate an image for a brain region using an AI model.

generate_summary(→ str)

Generate a text summary for a coordinate based on studies.

generate_batch_summaries(→ list[str])

Generate summaries for multiple coordinates.

generate_summary_async(→ str)

Asynchronously generate a text summary for a coordinate.

stream_summary(→ collections.abc.Iterator[str])

Stream a text summary for a coordinate in chunks.

Module Contents#

coord2region.llm.generate_mni152_image(coord: Sequence[float], radius: int = 6, cmap: str = 'autumn') → bytes[source]#

Return a PNG image of a sphere drawn on the MNI152 template.

Parameters:

  • coord (sequence of float) – MNI coordinate (x, y, z) in millimetres.

  • radius (int, optional) – Radius of the sphere in millimetres. Defaults to 6.

  • cmap (str, optional) – Matplotlib colormap used for the overlay. Defaults to "autumn".

Returns:

PNG-encoded image bytes representing the sphere on the MNI152 template.

Return type:

bytes

coord2region.llm.LLM_PROMPT_TEMPLATES: dict[str, str][source]#
coord2region.llm.IMAGE_PROMPT_TEMPLATES: dict[str, str][source]#
coord2region.llm.generate_llm_prompt(studies: list[dict[str, Any]], coordinate: list[float] | tuple[float, float, float], prompt_type: str = 'summary', prompt_template: str | None = None) → str[source]#

Generate a detailed prompt for language models based on studies.

Parameters:

  • studies (list of dict) – Study metadata dictionaries that describe the activation evidence.

  • coordinate (sequence of float) – MNI coordinate used for formatting the prompt header.

  • prompt_type (str, optional) – Key that selects a built-in template from LLM_PROMPT_TEMPLATES.

  • prompt_template (str, optional) – Custom template string requiring coord and studies placeholders.

Returns:

Fully formatted prompt ready for submission to a language model.

Return type:

str

coord2region.llm.generate_region_image_prompt(coordinate: list[float] | tuple[float, float, float], region_info: dict[str, Any], image_type: str = 'anatomical', include_atlas_labels: bool = True, prompt_template: str | None = None) → str[source]#

Generate a prompt for creating images of brain regions.

Parameters:

  • coordinate (sequence of float) – Target MNI coordinate to highlight in the visualization.

  • region_info (dict) – Metadata describing the region, such as summary and atlas labels.

  • image_type (str, optional) – Template key selecting the style of the image prompt.

  • include_atlas_labels (bool, optional) – Whether atlas label descriptions should be inserted into the prompt.

  • prompt_template (str, optional) – Custom template string overriding the built-in prompt dictionary.

Returns:

Fully formatted prompt with atlas and study context injected.

Return type:

str

coord2region.llm.generate_region_image(ai: AIModelInterface, coordinate: list[float] | tuple[float, float, float], region_info: dict[str, Any], image_type: str = 'anatomical', model: str = 'stabilityai/stable-diffusion-2', include_atlas_labels: bool = True, prompt_template: str | None = None, retries: int = 3, watermark: bool = True, **kwargs: Any) → bytes[source]#

Generate an image for a brain region using an AI model.

Parameters:

  • ai (AIModelInterface) – Interface used to generate images.

  • coordinate (sequence of float) – MNI coordinate for the target region.

  • region_info (dict) – Dictionary containing region summary and atlas labels.

  • image_type (str, optional) – Type of image to generate. Defaults to "anatomical".

  • model (str, optional) – Name of the AI model to use. Defaults to "stabilityai/stable-diffusion-2".

  • include_atlas_labels (bool, optional) – Whether to include atlas label context in the prompt. Defaults to True.

  • prompt_template (str, optional) – Custom template overriding default prompts.

  • retries (int, optional) – Number of times to retry generation on failure. Defaults to 3.

  • watermark (bool, optional) – When True (default), a semi-transparent watermark is applied to the resulting image.

  • **kwargs (Any) – Additional keyword arguments passed to the underlying AI provider.

Returns:

PNG image bytes, optionally watermarked.

Return type:

bytes

coord2region.llm.generate_summary(ai: AIModelInterface, studies: list[dict[str, Any]], coordinate: list[float] | tuple[float, float, float], prompt_type: str = 'summary', model: str = 'gemini-2.0-flash', atlas_labels: dict[str, str] | None = None, custom_prompt: str | None = None, max_tokens: int = 1000) → str[source]#

Generate a text summary for a coordinate based on studies.

Parameters:

  • ai (AIModelInterface) – AI backend used to create the summary.

  • studies (list of dict) – Studies reporting activation at the target coordinate.

  • coordinate (sequence of float) – MNI coordinate around which the summary should focus.

  • prompt_type (str, optional) – Key into LLM_PROMPT_TEMPLATES. Use "custom" with custom_prompt to provide a bespoke template.

  • model (str, optional) – Name of the text generation model. Defaults to "gemini-2.0-flash".

  • atlas_labels (dict, optional) – Atlas-derived labels to prepend to the prompt for extra context.

  • custom_prompt (str, optional) – Template string formatted with coord and studies placeholders.

  • max_tokens (int, optional) – Maximum number of tokens requested from the language model.

Returns:

Textual summary returned by the AI model.

Return type:

str

coord2region.llm.generate_batch_summaries(ai: AIModelInterface, coord_studies_pairs: list[tuple[list[float] | tuple[float, float, float], list[dict[str, Any]]]], prompt_type: str = 'summary', model: str = 'gemini-2.0-flash', custom_prompt: str | None = None, max_tokens: int = 1000) → list[str][source]#

Generate summaries for multiple coordinates.

Parameters:

  • ai (AIModelInterface) – AI backend used to create the summaries.

  • coord_studies_pairs (list of tuple) – Coordinate-study pairs to summarise.

  • prompt_type (str, optional) – Template key used for each summary prompt.

  • model (str, optional) – Model used for text generation. Defaults to "gemini-2.0-flash".

  • custom_prompt (str, optional) – Template string overriding the built-in prompt for every coordinate.

  • max_tokens (int, optional) – Maximum tokens requested from each AI call.

Returns:

Generated summaries for the provided coordinate pairs.

Return type:

list of str

async coord2region.llm.generate_summary_async(ai: AIModelInterface, studies: list[dict[str, Any]], coordinate: list[float] | tuple[float, float, float], prompt_type: str = 'summary', model: str = 'gemini-2.0-flash', atlas_labels: dict[str, str] | None = None, custom_prompt: str | None = None, max_tokens: int = 1000) → str[source]#

Asynchronously generate a text summary for a coordinate.

Parameters:

  • ai (AIModelInterface) – AI backend used to create the summary asynchronously.

  • studies (list of dict) – Studies reporting activation at the target coordinate.

  • coordinate (sequence of float) – MNI coordinate for the summary.

  • prompt_type (str, optional) – Prompt template key defaulting to "summary".

  • model (str, optional) – Model name, defaulting to "gemini-2.0-flash".

  • atlas_labels (dict, optional) – Atlas-derived labels to include in the prompt.

  • custom_prompt (str, optional) – User-supplied template applied via str.format.

  • max_tokens (int, optional) – Maximum number of tokens requested for the summary.

Returns:

Generated summary text.

Return type:

str

coord2region.llm.stream_summary(ai: AIModelInterface, studies: list[dict[str, Any]], coordinate: list[float] | tuple[float, float, float], prompt_type: str = 'summary', model: str = 'gemini-2.0-flash', atlas_labels: dict[str, str] | None = None, custom_prompt: str | None = None, max_tokens: int = 1000) → Iterator[str][source]#

Stream a text summary for a coordinate in chunks.

Parameters:

  • ai (AIModelInterface) – Streaming AI backend used to generate the summary.

  • studies (list of dict) – Studies reporting activation at the target coordinate.

  • coordinate (sequence of float) – MNI coordinate for the summary.

  • prompt_type (str, optional) – Prompt template key defaulting to "summary".

  • model (str, optional) – Model name, defaulting to "gemini-2.0-flash".

  • atlas_labels (dict, optional) – Atlas-derived labels to include in the prompt.

  • custom_prompt (str, optional) – User-supplied template applied via str.format.

  • max_tokens (int, optional) – Maximum number of tokens requested for the summary.

Returns:

Chunks of text yielded by the streaming AI backend.

Return type:

iterator of str