coord2region.ai_reports#

High-level helpers for generating structured AI reports and image specs.

This module centralises the logic that was previously spread across gallery examples, making it easier to build real applications around the AI features.

Attributes#

DEFAULT_SYSTEM_MESSAGE

DEFAULT_NEGATIVE_PROMPT

Classes#

ReasonedReportContext

Structured payload describing the coordinate, atlas, and studies.

ReasonedReport

Parsed result returned by run_reasoned_report().

Functions#

infer_hemisphere(→ str)

Infer the hemisphere from an MNI coordinate.

build_reasoned_report_messages(→ list[dict[str, str]])

Construct chat messages for the reasoned report prompt.

parse_reasoned_report_output(→ ReasonedReport)

Split the reasoned report narrative and JSON payload.

run_reasoned_report(→ tuple[ReasonedReport, dict[str, ...)

Generate and parse a reasoned report, returning metadata alongside.

build_region_image_request(→ dict[str, Any])

Return prompt components for AIModelInterface.generate_image().

Module Contents#

coord2region.ai_reports.DEFAULT_SYSTEM_MESSAGE = Multiline-String[source]#
Show Value
"""You are a careful neuroscience assistant. You convert MNI brain coordinates into clear, evidence-grounded explanations using ONLY the data provided in the prompt (atlas labels, neighbors, and the study list).
If something is missing or conflicting, explicitly report "insufficient_evidence" for that part--do not invent facts or citations."""
coord2region.ai_reports.DEFAULT_NEGATIVE_PROMPT = 'cartoon, abstract art, texture noise, extra brains, low resolution, blurry, distorted anatomy,...[source]#
class coord2region.ai_reports.ReasonedReportContext[source]#

Structured payload describing the coordinate, atlas, and studies.

coordinate_mni: Sequence[float][source]#
hemisphere: str | None = None[source]#
boundary_proximity_mm: float | None = None[source]#
atlas: dict[str, Any][source]#
atlas_notes: list[str] = [][source]#
studies: list[dict[str, Any]] = [][source]#
allowed_domains: Sequence[str] | None = None[source]#
format_instructions: list[str] = [][source]#
class coord2region.ai_reports.ReasonedReport[source]#

Parsed result returned by run_reasoned_report().

narrative: str[source]#
json_text: str | None = None[source]#
json_data: dict[str, Any] | None = None[source]#
json_error: str | None = None[source]#
coord2region.ai_reports.infer_hemisphere(coord: Sequence[float]) → str[source]#

Infer the hemisphere from an MNI coordinate.

Parameters:

coord (sequence of float) – MNI coordinate to evaluate.

Returns:

"left", "right", "midline", or "unknown" depending on the x coordinate.

Return type:

str

coord2region.ai_reports.build_reasoned_report_messages(context: ReasonedReportContext, *, system_message: str = DEFAULT_SYSTEM_MESSAGE, max_words: int = 180) → list[dict[str, str]][source]#

Construct chat messages for the reasoned report prompt.

Parameters:

  • context (ReasonedReportContext) – Context describing the coordinate, atlas, and studies.

  • system_message (str, optional) – System prompt guiding the AI assistant.

  • max_words (int, optional) – Maximum narrative word count requested from the assistant.

Returns:

Stream-ready chat messages for the AI request.

Return type:

list of dict

coord2region.ai_reports.parse_reasoned_report_output(output: str) → ReasonedReport[source]#

Split the reasoned report narrative and JSON payload.

Parameters:

output (str) – Raw text returned by the AI assistant.

Returns:

Parsed narrative along with optional JSON payload information.

Return type:

ReasonedReport

coord2region.ai_reports.run_reasoned_report(ai: AIModelInterface, model: str, context: ReasonedReportContext, *, max_tokens: int = 512, retries: int = 3, system_message: str = DEFAULT_SYSTEM_MESSAGE) → tuple[ReasonedReport, dict[str, Any]][source]#

Generate and parse a reasoned report, returning metadata alongside.

Parameters:

  • ai (AIModelInterface) – AI interface used to generate text.

  • model (str) – Model name to use for the completion.

  • context (ReasonedReportContext) – Structured context describing the coordinate, atlas, and studies.

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

  • retries (int, optional) – Number of retry attempts for the text generation call.

  • system_message (str, optional) – System message that guides the assistant’s tone and scope.

Returns:

Tuple containing the parsed ReasonedReport and metadata.

Return type:

tuple

coord2region.ai_reports.build_region_image_request(coord: Sequence[float], context: ReasonedReportContext, *, sphere_radius_mm: float = 6, negative_prompt: str = DEFAULT_NEGATIVE_PROMPT) → dict[str, Any][source]#

Return prompt components for AIModelInterface.generate_image().

Parameters:

  • coord (sequence of float) – Target MNI coordinate for the image.

  • context (ReasonedReportContext) – Context used to describe the coordinate and atlas.

  • sphere_radius_mm (float, optional) – Radius of the spherical highlight in millimetres.

  • negative_prompt (str, optional) – Negative prompt guiding the image generation.

Returns:

Dictionary containing both structured specification and text prompts.

Return type:

dict