docs/llm_prompts_report.md

# LLM Prompts Report

All LLM prompts used by mindVisualizer, with exact templates, parameters, code locations, and triggers.

**To see prompts live at runtime**, pass `--debug` to any script:
```bash
python -m src.main --no-rag --debug
python examples/rdcim_propagation.py --debug
python examples/roi_flow_mode.py --debug
```

---

## 1. Initialize Region States from Global State

**File:** `src/brain_state.py` — method `BrainStateDB.initialize_from_global()`
**Trigger:** Press `S` key (both flow mode and rDCIM mode)
**Model params:** temperature=0.4, max_tokens=4000

**Template:**
```
You are a neuroscience expert. The brain is currently in this overall state:
"{global_state}"

For each brain region below, write a SHORT (1-2 sentences) specific description of
what this region is likely doing right now given the overall brain state.

IMPORTANT RULES:
- Be SPECIFIC about the actual cognitive content, not generic function descriptions
- Don't force every region to match the global state -- some regions may be doing
  their own thing (e.g., sensory processing, homeostasis) independent of the global state
- First consider what the region generally does, then derive what it's specifically
  doing in this context
- Focus on CURRENT ACTIVITY, not general capabilities

Regions:
{regions}

Reply as JSON object mapping region name to state description. Example:
{"Amygdala (AMY)": "Low-level monitoring for threats; no active fear processing", ...}
Only output valid JSON, nothing else.
```

**Parameters:**
- `{global_state}` — user-provided description (e.g., "someone feeling anxious") or default "a resting state with spontaneous mind-wandering"
- `{regions}` — newline-separated list of region names (batched in groups of ~30)

**Output:** JSON object mapping region name to state description string.

---

## 2. Validate Perturbation

**File:** `src/brain_state.py` — method `BrainStateDB.validate_perturbation()`
**Trigger:** Called internally before applying a perturbation
**Model params:** temperature=0.2, max_tokens=300

**Template:**
```
You are a neuroscience expert. Evaluate whether this perturbation makes sense
for the specified brain region.

Region: {region}
Current state: {current}
Requested perturbation: "{perturbation}"

Consider:
1. What does this brain region actually do? (its primary functions)
2. Is the requested perturbation something this region CAN process?
3. If not, what WOULD be an appropriate perturbation for this region?

Reply as JSON:
{
  "valid": true/false,
  "region_function": "brief description of what this region does",
  "warning": "warning if questionable (empty string if fine)",
  "suggestion": "suggested alternative perturbation if invalid (empty string if valid)"
}
Only output valid JSON.
```

**Parameters:**
- `{region}` — region name
- `{current}` — current state description
- `{perturbation}` — the requested perturbation text

**Output:** JSON object with `valid`, `region_function`, `warning`, `suggestion`.

---

## 3. Propose Perturbations

**File:** `src/brain_state.py` — method `BrainStateDB.propose_perturbations()`
**Trigger:** Press `P` key in rDCIM mode
**Model params:** temperature=0.5, max_completion_tokens=400
**Note:** Uses OpenAI SDK directly (not LangChain) for reliability in background threads.

**Template:**
```
You are a neuroscience expert. A user wants to perturb a brain region
in a resting-state simulation.

Region: {short_name}
Current state: "{current}"

Based on the region's known functions and its current state, propose
exactly 4 different plausible ways this region's state could change.
Each should be specific to this region's actual function, a realistic
state change, described in 1 short sentence, and diverse from each other.

Reply as a JSON array of exactly 4 strings:
["perturbation 1", "perturbation 2", "perturbation 3", "perturbation 4"]
Only output valid JSON.
```

**Parameters:**
- `{short_name}` — region name (abbreviated if >80 chars)
- `{current}` — current state description

**Output:** JSON array of 4 perturbation strings. Falls back to defaults if API fails.

---

## 4. Alter Region State

**File:** `src/brain_state.py` — method `BrainStateDB.alter_region_state()`
**Trigger:** After user selects a perturbation (keys 1-5 in rDCIM mode)
**Model params:** temperature=0.3, max_tokens=200

**Template:**
```
You are a neuroscience expert. A brain region's state needs to be modified.

Region: {region}
Current state: {current}
Modification requested: {modification}

Write a new SHORT (1-2 sentences) specific state description that incorporates
the requested modification while staying neuroscientifically plausible.
Only output the new state description, nothing else.
```

**Parameters:**
- `{region}` — region name
- `{current}` — current state
- `{modification}` — the selected perturbation

**Output:** Plain text — the new state description (1-2 sentences).

---

## 5. Propagate Through Graph (rDCIM Mode)

**File:** `src/brain_state.py` — method `BrainStateDB.propagate_through_graph()`
**Trigger:** Press `Shift+P` in rDCIM mode
**Model params:** temperature=0.3, max_tokens=300
**Called once per affected region (depth-by-depth).**

**Template:**
```
You are a computational neuroscientist analyzing intrinsic information flow in a resting-state brain network (rs-fMRI effective connectivity).

TARGET REGION: {target}
TARGET PREVIOUS STATE: {target_state}

INCOMING SIGNAL FROM: {source}
INCOMING SIGNAL STRENGTH: {strength} (connection weight: {weight:.4f})
CONNECTION TYPE: {sign}
SOURCE REGION'S CURRENT STATE: "{source_state}"
{context}
CRITICAL INSTRUCTIONS:
1. NO SEMANTIC ECHOING: Do not simply copy the semantic concept of the source region. You must TRANSLATE the incoming signal into the strict anatomical and functional domain of the TARGET REGION. If the source is about "visual beauty", the motor cortex should NOT start "appreciating beauty" -- it should show changes in motor readiness or postural tone.
2. RESTING-STATE CONTEXT: The connectivity data reflects intrinsic resting-state dynamics. Information flow here represents spontaneous internal cognition or modulation of the target region's resting equilibrium.
3. INHIBITORY vs EXCITATORY: If the connection is INHIBITORY, the incoming signal SUPPRESSES or DAMPENS the target region's activity. If EXCITATORY, it AMPLIFIES or FACILITATES the target's function. This fundamentally changes the nature of the state change.
4. INTRINSIC DYNAMICS: Focus on how the target region's OWN function shifts, not on relaying the source's content.
5. Output ONLY the precise description of the target region's new state (1-2 sentences). No conversational filler.
```

**Parameters:**
- `{target}` — target region name
- `{target_state}` — target's previous state
- `{source}` — source region name
- `{source_state}` — source region's current state
- `{strength}` — "STRONG (well above average)", "moderate", or "weak (below average)"
- `{sign}` — "EXCITATORY (positive connection weight)" or "INHIBITORY (negative connection weight)"
- `{weight}` — absolute connection weight (float)
- `{context}` — additional context showing 1-3 other strong un-perturbed connections

**Output:** Plain text — new state description (1-2 sentences).

---

## 6. Propagate Through Regions (Flow Mode)

**File:** `src/brain_state.py` — method `BrainStateDB.propagate_through_regions()`
**Trigger:** Press `Shift+S` in flow mode with active probe
**Model params:** temperature=0.3, max_tokens=300

**Template:**
```
You are a computational neuroscientist analyzing intrinsic information flow in a resting-state brain network.

TARGET REGION: {target}
TARGET PREVIOUS STATE: {target_state}

INCOMING SIGNAL FROM: {source}
INCOMING SIGNAL STRENGTH: {strength}
SOURCE REGION'S CURRENT STATE: "{source_state}"

CRITICAL INSTRUCTIONS:
1. NO SEMANTIC ECHOING: Do not simply copy the semantic concept of the source region. You must TRANSLATE the incoming signal into the strict anatomical and functional domain of the TARGET REGION ({target}). For example, if the source is a visual area processing "edge detection" and the target is a motor area, do NOT say the motor area is doing "edge detection" -- describe how the motor area's OWN function shifts in response.
2. RESTING-STATE CONTEXT: This is intrinsic resting-state dynamics, not task-driven activity. Describe subtle modulations, not dramatic activations.
3. INTRINSIC DYNAMICS: Focus on how {target}'s OWN function shifts given the incoming signal. The target region does what IT does, influenced by the source -- not what the source does.

Output ONLY the precise description of {target}'s new state (1-2 sentences). No labels, no prefixes.
```

**Parameters:**
- `{target}` — target region name
- `{target_state}` — target's previous state
- `{source}` — source region name
- `{source_state}` — source's current state
- `{strength}` — "STRONG", "moderate", or "weak"

**Output:** Plain text — new state description (1-2 sentences).

---

## 7. Summarize Changes (Network-Level Overview)

**File:** `src/brain_state.py` — method `BrainStateDB.summarize_changes()`
**Trigger:** Called automatically after propagation completes
**Model params:** temperature=0.3, max_tokens=800

**Template:**
```
You are a network neuroscientist analyzing a macroscopic shift in resting-state brain activity based on effective connectivity changes.

INITIAL BRAIN STATE MAP:
{comparisons_before}

POST-PROPAGATION BRAIN STATE MAP:
{comparisons_after}

CRITICAL INSTRUCTIONS:
1. DO NOT list the regions or compare them one by one.
2. This is a resting-state brain network -- interpret changes as shifts in intrinsic functional organization, not external stimulus-response narratives.
3. FOCUS ON INTRINSIC STATES: Synthesize this data into ONE coherent paragraph explaining the overall shift in the subject's internal cognitive, emotional, or physiological baseline.
4. NETWORK LEVEL INTEGRATION: Identify the broad functional domains driving the new equilibrium and describe the holistic network-level transition based purely on the provided state changes.

Provide your coherent resting-state network insight below:
```

**Parameters:**
- `{comparisons_before}` — newline-separated before states: `- Region: "state"`
- `{comparisons_after}` — newline-separated after states: `- Region: "state"`

**Output:** One coherent paragraph describing the network-level shift.

---

## 8. Generate Information Flow Story

**File:** `src/brain_state.py` — method `BrainStateDB.generate_flow_story()`
**Trigger:** Called automatically after propagation completes
**Model params:** temperature=0.4, max_tokens=800

**Template:**
```
You are a science writer narrating how a signal traveled through a resting-state brain network.

SIGNAL FLOW PATH (in order of propagation):
{flow_path}

Write a SHORT narrative story (2-3 paragraphs) of how the information traveled through the brain:
- Start with where the signal originated and what it carried
- Describe how each region it reached processed and TRANSFORMED the signal according to its own function
- Highlight how the signal's meaning changed as it moved through different functional domains
- End with the overall effect on the brain's resting state

RULES:
- Do NOT list regions mechanically -- weave them into a flowing narrative
- Use concrete, vivid language about what each region actually does
- Show how the signal was transformed at each hop, not just passed along
- Keep it grounded in neuroscience but accessible to a general audience
```

**Parameters:**
- `{flow_path}` — formatted flow steps, e.g.:
  ```
  ORIGIN -- Region: "before" -> "after"
  DEPTH 1 (excitatory) -- Region: "before" -> "after"
  DEPTH 2 (inhibitory) -- Region: "before" -> "after"
  ```

**Output:** 2-3 paragraph narrative story.

---

## 9. Probe Flow Analysis (RAG Chain)

**File:** `src/region_analyzer.py` — function `create_rag_chain()`
**Trigger:** Press `Shift+G` in flow mode (when RAG is enabled)
**Model params:** temperature=0.3, max_tokens=1500

**System prompt template:**
```
You are a neuroscience expert interpreting information flow in a resting-state brain.

Reference knowledge about relevant brain regions:
{context}

{question}

CRITICAL INSTRUCTIONS -- read carefully before answering:
1. Do NOT list which regions the probe passed through -- the user already knows that.
2. Do NOT give a generic answer like "this flow is associated with the default mode network" -- that is too shallow.
3. DO explain what SPECIFIC INFORMATION is likely flowing along this exact path.
4. DO describe the functional MEANING of this particular flow trajectory.
5. DO explain how each region transforms the signal before passing it on.
6. DO consider laterality.
7. This is a RESTING-STATE brain -- describe what spontaneous cognitive process would produce this exact flow.
```

**Parameters:**
- `{context}` — retrieved RAG documents (top-10 semantic matches from knowledge base)
- `{question}` — the full analysis question (see Prompt 11 below)

---

## 10. Probe Flow Analysis (Direct / No-RAG)

**File:** `src/region_analyzer.py` — function `_call_direct_responses_api()`
**Trigger:** Press `Shift+G` in flow mode (with `--no-rag` flag)
**API:** OpenAI Responses API (not LangChain)
**Model params:** reasoning.effort="low", max_output_tokens=2500

**Instructions (system-level):**
```
You are a neuroscience expert interpreting information flow in a resting-state brain.

Do NOT repeat the region list.
Do explain:
1. what specific information is likely flowing,
2. how the signal is transformed across regions,
3. what spontaneous resting-state process could produce this path,
4. the functional purpose of this exact trajectory.
Be concrete, not generic.
```

**Input:** The full question (see Prompt 11).

---

## 11. Probe Analysis Question Construction

**File:** `src/region_analyzer.py` — function `analyze_with_gpt()`
**Used by:** Both Prompt 9 (RAG) and Prompt 10 (no-RAG)

**Question template:**
```
A probe was placed in a resting-state brain and followed the intrinsic information
flow field through these regions:

{formatted_transitions}

Analyze this SPECIFIC flow pathway in depth:
1. What concrete information is likely being carried along this path?
2. How does the information CHANGE and get TRANSFORMED as it passes through each region?
3. What spontaneous resting-state cognitive process would produce this EXACT flow?
4. What is the functional PURPOSE of information flowing in this exact direction and order?
Do NOT repeat the region list or give a generic network label. Give deep, specific insight.
Keep your response SHORT and focused — 2-3 concise paragraphs maximum.
```

**Parameters:**
- `{formatted_transitions}` — output of `format_transitions_text()`, listing regions in order with enriched context including:
  - **Interaction type**: "passed through center", "traversed mid-region", "briefly touched surface", "passed through periphery", or "nearby (did not enter, ~X.Xmm away)"
  - **Penetration depth**: 0-100% normalized distance to region center
  - **Traversal direction**: anatomical direction (e.g., "moving upward and anteriorly")
  - **Entry/exit positions**: relative position within the region (e.g., "upper-left-anterior")
  - **Hemisphere**: left/right when applicable
  - **Flow strength, entropy, enclosing regions**: as before
  - **Subregion**: extra parcellation subregion name when available

---

## 12. ROI Flow Interpretation (ROI Flow Mode)

**File:** `src/roi_flow.py` — class `ROIFlowLLM.interpret_roi_flow()`
**Trigger:** Press `Shift+G` in ROI flow mode after recording a path
**API:** OpenAI Responses API
**Model params:** reasoning.effort="low", max_output_tokens=2500
**Note:** ROI flow mode uses its own manifold-space MDN flow field (downloaded from HuggingFace), not the brain-space field used by flow mode.

**Instructions:**
```
You are a neuroscientist interpreting brain state dynamics from a manifold flow
simulation. The user traced a path through a learned neural manifold (a
dimensionality-reduced representation of resting-state brain dynamics). You are
given how each ROI's contribution changed along this path.

IMPORTANT: The delta values do NOT mean regions became more or less 'active' in
a simple sense. They measure how each ROI's CONTRIBUTION to the overall brain
state shifted — some regions contribute more to the new state, some less.
A positive delta means the region became a stronger contributor; negative means
it became a weaker contributor. This is a transition in the brain's dynamic state.

Analyze what this particular state transition might mean. Do NOT list the
individual ROI changes — instead, synthesize them into ONE coherent picture of
what cognitive or neural process could underlie this specific shift in brain
dynamics. Consider the spatial pattern (which networks gained vs lost
contribution), the directionality, and what spontaneous resting-state process
would produce this exact transition.

Keep your response SHORT — 2-3 concise paragraphs maximum.
```

**Input:** Structured analysis text from `ROIFlowAnalyzer.build_llm_context()` containing:
- Top changed ROIs (positive and negative delta) with brain region names, hemisphere, and MNI coordinates
- Direction of bulk information flow (anterior/posterior, left/right)
- Flow pattern type (one-to-many, many-to-one, distributed, bilateral_split)
- Directional analysis (L/R, A/P, S/I shift in mm)

---

## How to Modify Prompts

All prompts are defined as inline string templates at the code locations listed above. To change a prompt:

1. Open the file listed above
2. Find the `ChatPromptTemplate.from_template(...)` or instructions string
3. Edit the template text directly
4. Parameters in `{curly_braces}` are filled at runtime -- keep the variable names unchanged
5. Use `--debug` to verify your changes at runtime

The prompts are intentionally kept as inline strings (not in separate files) so they are easy to find and modify alongside the logic that uses them.