feat: Introduce argument direction handling and enhance conviction mechanics for juror interactions

agents/smolagent_juror.py

@@ -16,7 +16,7 @@ from typing import TYPE_CHECKING
 from smolagents import CodeAgent, LiteLLMModel
 
 from core.models import JurorConfig, JurorMemory, ArgumentMemory
-from core.game_state import GameState, DeliberationTurn
+from core.game_state import GameState, DeliberationTurn, ArgumentDirection
 from core.conviction import conviction_to_text
 from agents.tools import EvidenceLookupTool, CaseQueryTool
 
@@ -56,6 +56,61 @@ class SmolagentJuror:
     DEFAULT_MODEL_ID = "gemini/gemini-2.5-flash"
     MAX_STEPS = 3  # Limit reasoning steps for performance
 
+    # Extremely explicit direction prompts to prevent LLM from contradicting assigned direction
+    DIRECTION_PROMPTS = {
+        ArgumentDirection.PROSECUTION: """
+## YOUR TASK: ARGUE FOR GUILTY
+
+You are arguing that the defendant IS GUILTY.
+
+REQUIREMENTS:
+- Every sentence must support conviction
+- Point to evidence that proves guilt
+- Dismiss defense arguments as weak or irrelevant
+- End with a clear statement: "The defendant is guilty"
+
+DO NOT:
+- Express any doubt about guilt
+- Mention reasons for innocence
+- Say "but" or "however" to introduce defense points
+- Play devil's advocate
+""",
+
+        ArgumentDirection.DEFENSE: """
+## YOUR TASK: ARGUE FOR NOT GUILTY
+
+You are arguing that the defendant is NOT GUILTY.
+
+REQUIREMENTS:
+- Every sentence must support acquittal
+- Point to reasonable doubt in the evidence
+- Highlight weaknesses in the prosecution's case
+- End with a clear statement: "The defendant is not guilty" or "There is reasonable doubt"
+
+DO NOT:
+- Express any belief in guilt
+- Mention reasons the defendant might be guilty
+- Say "but" or "however" to introduce prosecution points
+- Concede prosecution's strong points
+""",
+
+        ArgumentDirection.NEUTRAL: """
+## YOUR TASK: ASK A PROBING QUESTION
+
+You are undecided and want to explore the case further.
+
+REQUIREMENTS:
+- Ask one specific question about the evidence or testimony
+- Do not take a side
+- Frame it as genuine uncertainty
+
+DO NOT:
+- Make any argument for guilty or not guilty
+- Answer your own question
+- Express a leaning toward either side
+"""
+    }
+
     def __init__(
         self,
         config: JurorConfig,
@@ -121,7 +176,8 @@ class SmolagentJuror:
         self,
         case: "CriminalCase",
         game_state: GameState,
-        task: str = "speak"
+        task: str = "speak",
+        direction: ArgumentDirection | None = None
     ) -> str:
         """Build the prompt for the agent."""
         guilty, not_guilty = game_state.get_vote_tally()
@@ -161,7 +217,22 @@ You are {self.config.name}, Juror #{self.config.seat_number}.
 Guilty: {guilty} | Not Guilty: {not_guilty}
 """
 
-        if task == "speak":
+        if task == "speak" and direction:
+            # Use extremely explicit direction prompts
+            direction_prompt = self.DIRECTION_PROMPTS.get(direction, "")
+            task_prompt = f"""
+{direction_prompt}
+
+Stay in character as {self.config.name} ({self.config.archetype}).
+- Be authentic to your personality and background
+- Keep your argument focused (2-4 sentences)
+- You may address other jurors or speak to the room
+- Use tools to look up evidence if needed
+
+Provide your argument as a single statement that your character would say out loud
+in the jury room. Do not include internal thoughts - just what you would say.
+"""
+        elif task == "speak":
             task_prompt = f"""
 # YOUR TASK
 Make an argument in the deliberation. You have access to tools to look up evidence
@@ -196,7 +267,11 @@ Return a brief internal reaction (not spoken aloud).
         Returns:
             Tuple of (DeliberationTurn, list of ReasoningSteps for UI)
         """
-        prompt = self._build_prompt(case, game_state, task="speak")
+        # Determine direction BEFORE generating content
+        direction = self._determine_argument_direction()
+
+        # Build prompt with direction guidance
+        prompt = self._build_prompt(case, game_state, task="speak", direction=direction)
 
         try:
             # Run the agent
@@ -216,12 +291,13 @@ Return a brief internal reaction (not spoken aloud).
             argument_types = self._get_preferred_argument_types()
             selected_type = random.choice(argument_types)
 
-            # Create the turn
+            # Create the turn with direction
             turn = DeliberationTurn(
                 round_number=game_state.round_number,
                 speaker_id=self.config.juror_id,
                 speaker_name=self.config.name,
                 argument_type=selected_type,
+                direction=direction,
                 content=content,
             )
 
@@ -232,12 +308,13 @@ Return a brief internal reaction (not spoken aloud).
 
         except Exception as e:
             print(f"Error in SmolagentJuror.generate_argument for {self.config.name}: {e}")
-            # Fallback response
+            # Fallback response - use neutral direction
             turn = DeliberationTurn(
                 round_number=game_state.round_number,
                 speaker_id=self.config.juror_id,
                 speaker_name=self.config.name,
                 argument_type="observation",
+                direction=ArgumentDirection.NEUTRAL,
                 content=f"*{self.config.name} pauses thoughtfully* I'm still considering the evidence...",
             )
             return turn, []
@@ -313,6 +390,20 @@ Return a brief internal reaction (not spoken aloud).
         }
         return archetype_preferences.get(self.config.archetype, ["observation", "logical"])
 
+    def _determine_argument_direction(self) -> ArgumentDirection:
+        """Determine argument direction based on current conviction."""
+        conviction = self.memory.current_conviction
+
+        if conviction > 0.6:
+            return ArgumentDirection.PROSECUTION
+        elif conviction < 0.4:
+            return ArgumentDirection.DEFENSE
+        else:
+            # Undecided - 30% chance to ask neutral questions
+            if random.random() < 0.3:
+                return ArgumentDirection.NEUTRAL
+            return ArgumentDirection.PROSECUTION if conviction > 0.5 else ArgumentDirection.DEFENSE
+
     def receive_argument(self, argument: DeliberationTurn, impact: float = 0.0) -> None:
         """Process an argument from another juror."""
         arg_memory = ArgumentMemory(

app.py

@@ -23,6 +23,8 @@ from case_db import CaseLoader, CriminalCase, CaseIndexFactory
 from agents import load_juror_configs, SmolagentJuror
 from ui.components import render_jury_box, render_vote_tally
 from services.mcp import MCPService, init_mcp_service, register_mcp_tools
+from services.tts import get_tts_service
+from services.narration import JudgeNarration
 
 
 # CSS file path for scalable styling
@@ -46,11 +48,11 @@ class JuryDeliberation:
         """Get game state from orchestrator."""
         return self.orchestrator.game_state if self.orchestrator else None
 
-    def initialize_game(self, case_id: str | None = None) -> tuple[str, str, str, list]:
+    async def initialize_game(self, case_id: str | None = None) -> tuple[str, str, str, list, str, bytes | None, str]:
         """Initialize a new game.
 
         Returns:
-            Tuple of (case_summary, evidence_html, jury_box_html, chat_history)
+            Tuple of (case_summary, evidence_html, jury_box_html, chat_history, vote_html, audio_bytes, transcript)
         """
         # Load case
         if case_id:
@@ -63,7 +65,10 @@ class JuryDeliberation:
                 "No cases available. Please add case files to case_db/cases/",
                 "",
                 render_jury_box(self.juror_configs),
-                []
+                [],
+                "",
+                None,
+                ""
             )
 
         # Create LlamaIndex for this case
@@ -125,11 +130,20 @@ class JuryDeliberation:
 
         jury_html = render_jury_box(self.juror_configs, self.game_state)
 
+        # Generate judge narration
+        transcript = JudgeNarration.case_introduction(self.current_case)
+        audio_bytes = None
+        tts = get_tts_service()
+        if tts.is_available:
+            audio_bytes = await tts.asynthesize(transcript, style="formal", use_cache=True)
+
         chat_history = [
-            {"role": "assistant", "content": f"**Judge:** Members of the jury, you are here today to determine the fate of the defendant in the case of {self.current_case.title}. Please review the evidence carefully and deliberate with your fellow jurors. The burden of proof lies with the prosecution."}
+            {"role": "assistant", "content": f"**Judge:** {transcript}"}
         ]
 
-        return case_summary, evidence_html, jury_html, chat_history
+        vote_html = render_vote_tally(self.game_state)
+
+        return case_summary, evidence_html, jury_html, chat_history, vote_html, audio_bytes, transcript
 
     def select_player_side(self, side: str) -> tuple[str, str, list]:
         """Player selects prosecution or defense side."""
@@ -146,10 +160,17 @@ class JuryDeliberation:
 
         return vote_html, jury_html, chat_update
 
-    async def run_deliberation_round(self) -> tuple[str, str, list[dict]]:
-        """Run a single round of AI juror deliberation using fair speaker queue."""
+    async def run_deliberation_round(self, prev_tally: tuple | None = None) -> tuple[str, str, list[dict], bytes | None, str, tuple]:
+        """Run a single round of AI juror deliberation using fair speaker queue.
+
+        Args:
+            prev_tally: Previous vote tally (guilty, not_guilty) for shift detection.
+
+        Returns:
+            Tuple of (vote_html, jury_html, new_messages, audio_bytes, transcript, new_tally)
+        """
         if not self.orchestrator or not self.current_case:
-            return "", "", []
+            return "", "", [], None, "", (0, 0)
 
         new_messages = []
 
@@ -193,7 +214,25 @@ class JuryDeliberation:
         vote_html = render_vote_tally(self.game_state)
         jury_html = render_jury_box(self.juror_configs, self.game_state)
 
-        return vote_html, jury_html, new_messages
+        # Check for significant vote shift and generate narration
+        new_guilty, new_not_guilty = self.game_state.get_vote_tally()
+        new_tally = (new_guilty, new_not_guilty)
+        audio_bytes = None
+        transcript = ""
+
+        if prev_tally:
+            old_g, old_ng = prev_tally
+            shift = abs(new_guilty - old_g)
+            if shift >= 2:
+                direction = "conviction" if new_guilty > old_g else "acquittal"
+                transcript = JudgeNarration.vote_shift(shift, direction, new_guilty, new_not_guilty)
+                if transcript:
+                    tts = get_tts_service()
+                    if tts.is_available:
+                        audio_bytes = await tts.asynthesize(transcript, style="dramatic", use_cache=False)
+                    new_messages.append({"role": "assistant", "content": f"**Judge:** {transcript}"})
+
+        return vote_html, jury_html, new_messages, audio_bytes, transcript, new_tally
 
     def make_player_argument(
         self,
@@ -265,6 +304,23 @@ def create_ui():
                 )
                 vote_tally = gr.HTML("", elem_id="vote-tally-container")
 
+                # Judge narration section
+                gr.Markdown("### Judge")
+                with gr.Group(elem_id="judge-narration"):
+                    judge_audio = gr.Audio(
+                        label="",
+                        autoplay=True,
+                        elem_id="judge-audio",
+                        visible=True
+                    )
+                    judge_transcript = gr.Textbox(
+                        label="",
+                        lines=2,
+                        interactive=False,
+                        elem_id="judge-transcript",
+                        show_label=False
+                    )
+
                 gr.Markdown("### Your Side")
                 with gr.Row(elem_id="side-selection-row"):
                     defend_btn = gr.Button(
@@ -344,15 +400,19 @@ def create_ui():
             elem_classes=["primary-btn"]
         )
 
+        # State for tracking vote tally for shift detection
+        vote_tally_state = gr.State(None)
+
         # Event handlers
-        def start_game():
-            case_md, evidence_md, jury_html, chat = game.initialize_game()
-            return case_md, evidence_md, jury_html, chat, render_vote_tally(game.game_state)
+        async def start_game():
+            case_md, evidence_md, jury_html, chat, vote_html, audio_bytes, transcript = await game.initialize_game()
+            initial_tally = game.game_state.get_vote_tally() if game.game_state else (0, 0)
+            return case_md, evidence_md, jury_html, chat, vote_html, audio_bytes, transcript, initial_tally
 
         start_btn.click(
             fn=start_game,
             inputs=[],
-            outputs=[case_summary, evidence_display, jury_box, deliberation_chat, vote_tally]
+            outputs=[case_summary, evidence_display, jury_box, deliberation_chat, vote_tally, judge_audio, judge_transcript, vote_tally_state]
         )
 
         def select_defend(chat):
@@ -375,14 +435,14 @@ def create_ui():
             outputs=[vote_tally, jury_box, deliberation_chat]
         )
 
-        async def run_ai_round(chat):
-            vote_html, jury_html, new_msgs = await game.run_deliberation_round()
-            return vote_html, jury_html, chat + new_msgs
+        async def run_ai_round(chat, prev_tally):
+            vote_html, jury_html, new_msgs, audio_bytes, transcript, new_tally = await game.run_deliberation_round(prev_tally)
+            return vote_html, jury_html, chat + new_msgs, audio_bytes, transcript, new_tally
 
         next_round_btn.click(
             fn=run_ai_round,
-            inputs=[deliberation_chat],
-            outputs=[vote_tally, jury_box, deliberation_chat]
+            inputs=[deliberation_chat, vote_tally_state],
+            outputs=[vote_tally, jury_box, deliberation_chat, judge_audio, judge_transcript, vote_tally_state]
         )
 
         def player_speak(strategy, custom, chat):

case_db/index.py

@@ -36,7 +36,9 @@ class CaseIndex:
 
         # Build the index
         self.index = self._build_index()
-        self.query_engine = self.index.as_query_engine()
+        # Use retriever instead of query_engine to avoid redundant LLM calls
+        # The CodeAgent will reason about raw retrieved docs directly
+        self.retriever = self.index.as_retriever(similarity_top_k=3)
 
     def _build_index(self) -> VectorStoreIndex:
         """Build vector index from case documents."""
@@ -152,10 +154,13 @@ class CaseIndex:
             question: Natural language question about the case
 
         Returns:
-            Synthesized answer from relevant case documents
+            Relevant case documents (raw text, no LLM synthesis)
         """
-        response = self.query_engine.query(question)
-        return str(response)
+        nodes = self.retriever.retrieve(question)
+        if not nodes:
+            return "No relevant information found."
+        # Return raw document text for CodeAgent to reason about
+        return "\n\n".join([node.text for node in nodes])
 
     def query_evidence(self, query: str) -> str:
         """Query specifically for evidence-related information.

core/__init__.py

@@ -4,13 +4,19 @@ from .game_state import (
     GameState,
     DeliberationTurn,
     GamePhase,
+    ArgumentDirection,
 )
 from .models import (
     JurorConfig,
     JurorMemory,
     ArgumentMemory,
 )
-from .conviction import calculate_conviction_change, check_vote_flip
+from .conviction import (
+    calculate_conviction_change,
+    check_vote_flip,
+    calculate_direction_impact,
+    apply_conviction_update,
+)
 from .orchestrator import (
     OrchestratorAgent,
     TurnManager,
@@ -22,11 +28,14 @@ __all__ = [
     "GameState",
     "DeliberationTurn",
     "GamePhase",
+    "ArgumentDirection",
     "JurorConfig",
     "JurorMemory",
     "ArgumentMemory",
     "calculate_conviction_change",
     "check_vote_flip",
+    "calculate_direction_impact",
+    "apply_conviction_update",
     "OrchestratorAgent",
     "TurnManager",
     "TurnResult",

core/conviction.py

@@ -1,8 +1,9 @@
 """Conviction score mechanics for juror persuasion."""
 
 import random
+from typing import Literal
 from .models import JurorConfig, JurorMemory
-from .game_state import DeliberationTurn
+from .game_state import DeliberationTurn, ArgumentDirection
 
 
 # Archetype modifiers for different argument types
@@ -104,11 +105,32 @@ def get_archetype_modifier(archetype: str, argument_type: str) -> float:
     return archetype_mods.get(argument_type, 1.0)
 
 
+def calculate_direction_impact(
+    direction: ArgumentDirection,
+    base_strength: float = 0.1
+) -> float:
+    """
+    Convert argument direction to signed impact.
+
+    Args:
+        direction: Which side the argument supports
+        base_strength: Base argument strength (0.0 to 1.0)
+
+    Returns:
+        Signed impact: positive pushes toward guilty, negative toward not guilty
+    """
+    if direction == ArgumentDirection.PROSECUTION:
+        return base_strength  # Positive: push toward guilty
+    elif direction == ArgumentDirection.DEFENSE:
+        return -base_strength  # Negative: push toward not guilty
+    return 0.0  # Neutral: no directional push
+
+
 def calculate_conviction_change(
     juror: JurorConfig,
     juror_memory: JurorMemory,
     argument: DeliberationTurn,
-    base_impact: float = 0.0,
+    base_strength: float = 0.1,
 ) -> float:
     """
     Calculate how much an argument shifts a juror's conviction.
@@ -116,12 +138,22 @@ def calculate_conviction_change(
     Args:
         juror: The juror configuration
         juror_memory: The juror's current memory state
-        argument: The argument being made
-        base_impact: Base impact from argument strength (-1.0 to 1.0)
+        argument: The argument being made (includes direction)
+        base_strength: Base argument strength (0.0 to 1.0)
 
     Returns:
         delta to add to conviction score (-0.3 to +0.3 typically)
     """
+    # Calculate directional base impact from argument direction
+    base_impact = calculate_direction_impact(
+        argument.direction,
+        base_strength
+    )
+
+    # If no meaningful impact (neutral direction), skip noise and return 0
+    if abs(base_impact) < 0.001:
+        return 0.0
+
     # Personality modifiers
     archetype_modifier = get_archetype_modifier(
         juror.archetype,
@@ -131,10 +163,6 @@ def calculate_conviction_change(
     # Stubbornness reduces all changes
     stubbornness_modifier = 1.0 - (juror.stubbornness * 0.7)
 
-    # Volatility adds randomness - but stubbornness dampens volatility effect
-    effective_volatility = juror.volatility * (1.0 - juror.stubbornness * 0.5)
-    volatility_noise = random.gauss(0, effective_volatility * 0.1)
-
     # Relationship modifier - trust the speaker?
     trust = juror_memory.opinions_of_others.get(argument.speaker_id, 0.0)
     trust_modifier = 1.0 + (trust * 0.3)  # -30% to +30%
@@ -144,16 +172,21 @@ def calculate_conviction_change(
     distance = abs(current - 0.5)  # 0 at center, 0.5 at extremes
     extreme_resistance = 1.0 - (distance ** 2) * 1.5  # Quadratic: 1.0 center, 0.625 extremes
 
-    # Calculate final delta
+    # Calculate base delta without noise
     delta = (
         base_impact
         * archetype_modifier
         * stubbornness_modifier
         * trust_modifier
         * extreme_resistance
-        + volatility_noise
     )
 
+    # Only add volatility noise when there's meaningful impact
+    if abs(delta) > 0.01:
+        effective_volatility = juror.volatility * (1.0 - juror.stubbornness * 0.5)
+        volatility_noise = random.gauss(0, effective_volatility * 0.1)
+        delta += volatility_noise
+
     # Clamp to reasonable range
     return max(-0.3, min(0.3, delta))
 
@@ -181,6 +214,33 @@ def check_vote_flip(juror_memory: JurorMemory) -> bool:
     return False
 
 
+def apply_conviction_update(
+    juror_memory: JurorMemory,
+    delta: float
+) -> tuple[bool, Literal["guilty", "not_guilty"] | None]:
+    """
+    Apply conviction update and check for vote flip using hysteresis.
+
+    Args:
+        juror_memory: Juror's memory state
+        delta: Conviction change to apply
+
+    Returns:
+        Tuple of (vote_flipped, new_vote or None)
+    """
+    old_vote = juror_memory.get_current_vote()
+
+    # Apply the delta
+    juror_memory.update_conviction(delta)
+
+    # Check for vote flip using hysteresis
+    if check_vote_flip(juror_memory):
+        new_vote = juror_memory.get_current_vote()
+        return True, new_vote
+
+    return False, None
+
+
 def conviction_to_text(conviction: float) -> str:
     """Convert conviction score to human-readable text."""
     if conviction < 0.2:

core/game_state.py

@@ -18,6 +18,13 @@ class GamePhase(str, Enum):
     VERDICT = "verdict"
 
 
+class ArgumentDirection(str, Enum):
+    """Direction of an argument's stance."""
+    PROSECUTION = "prosecution"  # Argues for guilty verdict
+    DEFENSE = "defense"          # Argues for not guilty verdict
+    NEUTRAL = "neutral"          # Procedural, questions, undecided
+
+
 @dataclass
 class DeliberationTurn:
     """A single turn in deliberation."""
@@ -26,6 +33,7 @@ class DeliberationTurn:
     speaker_id: str
     speaker_name: str
     argument_type: str  # "evidence", "emotional", "logical", "question", etc.
+    direction: ArgumentDirection  # prosecution, defense, or neutral
     content: str
     target_id: str | None = None  # Who they're addressing
     impact: dict[str, float] = field(default_factory=dict)  # conviction changes
@@ -38,6 +46,7 @@ class DeliberationTurn:
             "speaker_id": self.speaker_id,
             "speaker_name": self.speaker_name,
             "argument_type": self.argument_type,
+            "direction": self.direction.value,
             "content": self.content,
             "target_id": self.target_id,
             "impact": self.impact,

core/models.py

@@ -83,8 +83,22 @@ class JurorMemory:
     doubts: list[str] = field(default_factory=list)
 
     def get_current_vote(self) -> Literal["guilty", "not_guilty"]:
-        """Get vote based on current conviction."""
-        return "guilty" if self.current_conviction > 0.5 else "not_guilty"
+        """Get vote based on current conviction with hysteresis."""
+        # If no history, use simple threshold
+        if len(self.conviction_history) < 2:
+            return "guilty" if self.current_conviction > 0.5 else "not_guilty"
+
+        # Determine previous vote from previous conviction
+        prev_conviction = self.conviction_history[-2]
+        prev_vote_guilty = prev_conviction > 0.5
+
+        # Apply hysteresis thresholds to prevent flip-flopping
+        if prev_vote_guilty:
+            # Currently guilty - need to drop below 0.4 to flip
+            return "not_guilty" if self.current_conviction < 0.4 else "guilty"
+        else:
+            # Currently not guilty - need to rise above 0.6 to flip
+            return "guilty" if self.current_conviction > 0.6 else "not_guilty"
 
     def add_argument(self, argument: ArgumentMemory) -> None:
         """Add a heard argument to memory."""

core/orchestrator.py

@@ -7,9 +7,9 @@ import random
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
-from core.game_state import GameState, DeliberationTurn, GamePhase
+from core.game_state import GameState, DeliberationTurn, GamePhase, ArgumentDirection
 from core.models import JurorConfig, JurorMemory
-from core.conviction import calculate_conviction_change
+from core.conviction import calculate_conviction_change, apply_conviction_update
 
 if TYPE_CHECKING:
     from agents.smolagent_juror import SmolagentJuror
@@ -276,24 +276,28 @@ class OrchestratorAgent:
                     continue
 
                 old_vote = self.state.votes.get(other_id)
-                base_impact = random.uniform(-0.15, 0.15)
 
+                # Calculate base strength based on speaker influence
+                base_strength = 0.08 + (agent.config.influence * 0.07)
                 if other_id in active_listeners:
-                    base_impact *= 1.2
+                    base_strength *= 1.2
 
+                # Use direction-aware conviction calculation
                 delta = calculate_conviction_change(
                     other_agent.config,
                     other_agent.memory,
-                    turn,
-                    base_impact=base_impact
+                    turn,  # turn now includes direction
+                    base_strength=base_strength
                 )
 
-                other_agent.receive_argument(turn, delta)
+                # Store argument in memory (don't apply delta here - do it via apply_conviction_update)
+                other_agent.receive_argument(turn, 0.0)
                 conviction_changes[other_id] = delta
                 turn.impact[other_id] = delta
 
-                new_vote = other_agent.get_vote()
-                if old_vote != new_vote:
+                # Apply conviction update with hysteresis
+                vote_flipped, new_vote = apply_conviction_update(other_agent.memory, delta)
+                if vote_flipped and new_vote:
                     self.state.votes[other_id] = new_vote
                     vote_changes.append((other_id, old_vote, new_vote))
 
@@ -351,11 +355,19 @@ class OrchestratorAgent:
         target_id: str | None = None
     ) -> TurnResult:
         """Process an argument from the human player."""
+        # Determine direction from player's chosen side
+        direction = (
+            ArgumentDirection.PROSECUTION
+            if self.state.player_side == "prosecute"
+            else ArgumentDirection.DEFENSE
+        )
+
         turn = DeliberationTurn(
             round_number=self.state.round_number,
             speaker_id="juror_7",
             speaker_name="You",
             argument_type=argument_type,
+            direction=direction,
             content=content,
             target_id=target_id
         )
@@ -365,24 +377,27 @@ class OrchestratorAgent:
 
         for juror_id, agent in self.juror_agents.items():
             old_vote = self.state.votes.get(juror_id)
-            base_impact = random.uniform(-0.1, 0.1) * 1.2
 
+            # Calculate base strength (player has moderate influence)
+            base_strength = 0.10
             if target_id == juror_id:
-                base_impact *= 1.5
+                base_strength *= 1.5
 
             delta = calculate_conviction_change(
                 agent.config,
                 agent.memory,
                 turn,
-                base_impact=base_impact
+                base_strength=base_strength
             )
 
-            agent.receive_argument(turn, delta)
+            # Store argument in memory (don't apply delta here)
+            agent.receive_argument(turn, 0.0)
             conviction_changes[juror_id] = delta
             turn.impact[juror_id] = delta
 
-            new_vote = agent.get_vote()
-            if old_vote != new_vote:
+            # Apply conviction update with hysteresis
+            vote_flipped, new_vote = apply_conviction_update(agent.memory, delta)
+            if vote_flipped and new_vote:
                 self.state.votes[juror_id] = new_vote
                 vote_changes.append((juror_id, old_vote, new_vote))
 
@@ -401,7 +416,8 @@ class OrchestratorAgent:
         speaker_id: str,
         speaker_name: str,
         content: str,
-        argument_type: str,
+        direction: ArgumentDirection,  # REQUIRED - no fallback
+        argument_type: str = "logical",
         target_id: str | None = None
     ) -> TurnResult:
         """Process an argument from an external MCP agent.
@@ -413,7 +429,8 @@ class OrchestratorAgent:
             speaker_id: Juror seat ID (e.g., "juror_3")
             speaker_name: Display name for the speaker
             content: Argument text
-            argument_type: Type of argument
+            direction: REQUIRED - "prosecution", "defense", or "neutral"
+            argument_type: Type of argument (default: "logical")
             target_id: Optional juror_id to address directly
 
         Returns:
@@ -424,6 +441,7 @@ class OrchestratorAgent:
             speaker_id=speaker_id,
             speaker_name=speaker_name,
             argument_type=argument_type,
+            direction=direction,
             content=content,
             target_id=target_id
         )
@@ -436,24 +454,27 @@ class OrchestratorAgent:
                 continue
 
             old_vote = self.state.votes.get(juror_id)
-            base_impact = random.uniform(-0.1, 0.1) * 1.2
 
+            # Calculate base strength (external agents have moderate influence)
+            base_strength = 0.10
             if target_id == juror_id:
-                base_impact *= 1.5
+                base_strength *= 1.5
 
             delta = calculate_conviction_change(
                 agent.config,
                 agent.memory,
                 turn,
-                base_impact=base_impact
+                base_strength=base_strength
             )
 
-            agent.receive_argument(turn, delta)
+            # Store argument in memory (don't apply delta here)
+            agent.receive_argument(turn, 0.0)
             conviction_changes[juror_id] = delta
             turn.impact[juror_id] = delta
 
-            new_vote = agent.get_vote()
-            if old_vote != new_vote:
+            # Apply conviction update with hysteresis
+            vote_flipped, new_vote = apply_conviction_update(agent.memory, delta)
+            if vote_flipped and new_vote:
                 self.state.votes[juror_id] = new_vote
                 vote_changes.append((juror_id, old_vote, new_vote))
 

services/__init__.py

@@ -1,6 +1,8 @@
 """Services for 12 Angry Agents."""
 
 from .embeddings import EmbeddingService, get_embedding_service
+from .tts import TTSService, get_tts_service, reset_tts_service
+from .narration import JudgeNarration
 from .mcp import (
     MCPService,
     MCPSessionManager,
@@ -16,6 +18,11 @@ __all__ = [
     # Embedding service
     "EmbeddingService",
     "get_embedding_service",
+    # TTS service
+    "TTSService",
+    "get_tts_service",
+    "reset_tts_service",
+    "JudgeNarration",
     # MCP service
     "MCPService",
     "MCPSessionManager",

services/mcp/service.py

@@ -7,6 +7,7 @@ from enum import Enum
 from typing import TYPE_CHECKING, Optional
 
 from .session import MCPSessionManager, MCPSession
+from core.game_state import ArgumentDirection
 
 if TYPE_CHECKING:
     from core.orchestrator import OrchestratorAgent, TurnResult
@@ -300,6 +301,7 @@ class MCPService:
         self,
         session_id: str,
         content: str,
+        direction: str,  # REQUIRED: "prosecution", "defense", "neutral"
         argument_type: str = "logical",
         target_juror: Optional[str] = None
     ) -> dict:
@@ -308,7 +310,8 @@ class MCPService:
         Args:
             session_id: Session token
             content: Argument text
-            argument_type: Type of argument
+            direction: REQUIRED - "prosecution", "defense", or "neutral"
+            argument_type: Type of argument (default: "logical")
             target_juror: Optional juror_id to address
 
         Returns:
@@ -330,6 +333,18 @@ class MCPService:
                 "error_code": "EMPTY_CONTENT"
             }
 
+        # Validate direction (REQUIRED - no fallback)
+        valid_directions = ["prosecution", "defense", "neutral"]
+        if not direction or direction not in valid_directions:
+            return {
+                "success": False,
+                "error": f"direction is required and must be one of: {', '.join(valid_directions)}",
+                "error_code": "MISSING_DIRECTION"
+            }
+
+        # Convert direction string to ArgumentDirection enum
+        arg_direction = ArgumentDirection(direction)
+
         # Validate argument type
         valid_types = ["logical", "emotional", "evidence", "moral", "narrative", "question"]
         if argument_type not in valid_types:
@@ -358,6 +373,7 @@ class MCPService:
                 speaker_id=session.seat_id,
                 speaker_name=speaker_name,
                 content=content,
+                direction=arg_direction,
                 argument_type=argument_type,
                 target_id=target_juror
             )
@@ -372,6 +388,7 @@ class MCPService:
                 "success": True,
                 "data": {
                     "message": "Argument submitted.",
+                    "direction": direction,
                     "vote_changes": [
                         {"juror": vc[0], "from": vc[1], "to": vc[2]}
                         for vc in result.vote_changes

services/narration.py

@@ -0,0 +1,163 @@
+"""Judge narration text templates for different game events."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from case_db.models import CriminalCase
+    from core.game_state import GameState
+
+
+class JudgeNarration:
+    """Generate judge narration text for game events.
+
+    Provides templated narration for:
+    - Case introduction
+    - Round transitions
+    - Vote shifts
+    - Final verdict
+    """
+
+    @staticmethod
+    def case_introduction(case: "CriminalCase") -> str:
+        """Generate case introduction narration.
+
+        Args:
+            case: The criminal case being tried.
+
+        Returns:
+            Narration text for the judge to speak.
+        """
+        charges = ", ".join(case.charges) if case.charges else "the charges presented"
+        defendant_name = case.defendant.name if case.defendant else "the defendant"
+
+        return (
+            f"Members of the jury. You are now empaneled to hear the case of "
+            f"{case.title}. The defendant, {defendant_name}, stands charged with "
+            f"{charges}. You will hear testimony from witnesses, examine the evidence, "
+            f"and determine whether the prosecution has proven its case beyond a "
+            f"reasonable doubt. Remember: the defendant is presumed innocent until "
+            f"proven guilty."
+        )
+
+    @staticmethod
+    def round_transition(round_number: int, guilty: int, not_guilty: int) -> str:
+        """Generate round transition narration.
+
+        Args:
+            round_number: Current deliberation round.
+            guilty: Current guilty votes.
+            not_guilty: Current not guilty votes.
+
+        Returns:
+            Narration text.
+        """
+        if round_number == 1:
+            return (
+                f"The initial vote has been taken. The count stands at "
+                f"{guilty} for guilty, {not_guilty} for not guilty. "
+                f"Let the deliberation begin."
+            )
+
+        return (
+            f"Round {round_number} of deliberations continues. "
+            f"The current vote stands at {guilty} for guilty, "
+            f"{not_guilty} for not guilty. Please proceed."
+        )
+
+    @staticmethod
+    def vote_shift(
+        shift_count: int,
+        direction: str,
+        guilty: int,
+        not_guilty: int,
+    ) -> str | None:
+        """Generate vote shift narration.
+
+        Args:
+            shift_count: Number of votes that shifted.
+            direction: Direction of shift ("conviction" or "acquittal").
+            guilty: New guilty vote count.
+            not_guilty: New not guilty vote count.
+
+        Returns:
+            Narration text, or None if shift not significant enough.
+        """
+        if shift_count < 2:
+            return None
+
+        return (
+            f"We have movement in the jury. {shift_count} jurors have shifted "
+            f"toward {direction}. The vote now stands at {guilty} guilty, "
+            f"{not_guilty} not guilty."
+        )
+
+    @staticmethod
+    def verdict(
+        verdict: str,
+        unanimous: bool,
+        guilty: int,
+        not_guilty: int,
+        rounds: int,
+    ) -> str:
+        """Generate verdict announcement narration.
+
+        Args:
+            verdict: Final verdict ("GUILTY", "NOT GUILTY", or "HUNG JURY").
+            unanimous: Whether verdict was unanimous.
+            guilty: Final guilty vote count.
+            not_guilty: Final not guilty vote count.
+            rounds: Number of deliberation rounds.
+
+        Returns:
+            Narration text.
+        """
+        if verdict == "HUNG JURY":
+            return (
+                f"After {rounds} rounds of deliberation, the jury remains "
+                f"hopelessly deadlocked at {guilty} to {not_guilty}. "
+                f"This court has no choice but to declare a mistrial. "
+                f"The defendant may be retried at the prosecution's discretion."
+            )
+
+        unanimity = "unanimously " if unanimous else ""
+        if verdict == "GUILTY":
+            return (
+                f"Members of the jury, have you reached a verdict? "
+                f"We have, your honor. "
+                f"After {rounds} rounds of deliberation, the jury has {unanimity}"
+                f"found the defendant... guilty. "
+                f"The defendant will be remanded for sentencing. "
+                f"This court thanks you for your service."
+            )
+        else:  # NOT GUILTY
+            return (
+                f"Members of the jury, have you reached a verdict? "
+                f"We have, your honor. "
+                f"After {rounds} rounds of deliberation, the jury has {unanimity}"
+                f"found the defendant... not guilty. "
+                f"The defendant is free to go. "
+                f"This court thanks you for your service."
+            )
+
+    @staticmethod
+    def side_selected(side: str) -> str:
+        """Generate narration when player selects their side.
+
+        Args:
+            side: The side chosen ("prosecution" or "defense").
+
+        Returns:
+            Narration text.
+        """
+        if side == "prosecution":
+            return (
+                "You have chosen to argue for conviction. "
+                "Remember, the burden of proof lies with the prosecution. "
+                "The deliberation will now begin."
+            )
+        return (
+            "You have chosen to argue for acquittal. "
+            "The defense need only establish reasonable doubt. "
+            "The deliberation will now begin."
+        )

services/tts.py

@@ -0,0 +1,214 @@
+"""ElevenLabs TTS service for judge narration."""
+
+import os
+import asyncio
+import hashlib
+from pathlib import Path
+from concurrent.futures import ThreadPoolExecutor
+
+from elevenlabs.client import ElevenLabs
+from elevenlabs import VoiceSettings
+
+
+_tts_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="tts")
+
+
+class TTSService:
+    """Non-blocking ElevenLabs TTS service for judge narration.
+
+    Features:
+    - Low-latency Flash v2.5 model (~75ms inference)
+    - Sync and async synthesis methods
+    - File-based caching for repeated narrations
+    - Graceful degradation when API unavailable
+    """
+
+    DEFAULT_MODEL = "eleven_flash_v2_5"
+    DEFAULT_OUTPUT_FORMAT = "mp3_44100_128"
+    CACHE_DIR = Path(".cache/tts")
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        voice_id: str | None = None,
+        model_id: str = DEFAULT_MODEL,
+        cache_enabled: bool = True,
+    ):
+        """Initialize the TTS service.
+
+        Args:
+            api_key: ElevenLabs API key. Falls back to ELEVENLABS_API_KEY env var.
+            voice_id: Voice ID to use. Falls back to VALOR_VOICE_ID env var.
+            model_id: Model ID (default: eleven_flash_v2_5 for low latency).
+            cache_enabled: Whether to cache synthesized audio.
+        """
+        self.api_key = api_key or os.getenv("ELEVENLABS_API_KEY")
+        self.voice_id = voice_id or os.getenv("VALOR_VOICE_ID", "JBFqnCBsd6RMkjVDRZzb")
+        self.model_id = model_id
+        self.cache_enabled = cache_enabled
+
+        self._client: ElevenLabs | None = None
+        self._available = False
+
+        if self.api_key:
+            try:
+                self._client = ElevenLabs(api_key=self.api_key)
+                self._available = True
+            except Exception as e:
+                print(f"TTS init failed: {e}")
+
+        if cache_enabled:
+            self.CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def is_available(self) -> bool:
+        """Check if TTS service is available."""
+        return self._available
+
+    def _get_voice_settings(self, style: str = "formal") -> VoiceSettings:
+        """Get voice settings for different narration styles.
+
+        Args:
+            style: Narration style - "formal" for case intro,
+                   "dramatic" for vote shifts and verdict.
+        """
+        if style == "dramatic":
+            return VoiceSettings(
+                stability=0.6,
+                similarity_boost=0.8,
+                style=0.4,
+                use_speaker_boost=True,
+            )
+        # formal (default)
+        return VoiceSettings(
+            stability=0.75,
+            similarity_boost=0.75,
+            style=0.2,
+            use_speaker_boost=True,
+        )
+
+    def _get_cache_key(self, text: str, style: str) -> str:
+        """Generate cache key from text and style."""
+        content = f"{text}|{style}|{self.voice_id}|{self.model_id}"
+        return hashlib.sha256(content.encode()).hexdigest()[:16]
+
+    def _get_from_cache(self, text: str, style: str) -> bytes | None:
+        """Retrieve audio from cache if available."""
+        if not self.cache_enabled:
+            return None
+        cache_path = self.CACHE_DIR / f"{self._get_cache_key(text, style)}.mp3"
+        if cache_path.exists():
+            try:
+                return cache_path.read_bytes()
+            except Exception:
+                return None
+        return None
+
+    def _save_to_cache(self, text: str, style: str, audio: bytes) -> None:
+        """Save audio to cache."""
+        if not self.cache_enabled:
+            return
+        cache_path = self.CACHE_DIR / f"{self._get_cache_key(text, style)}.mp3"
+        try:
+            cache_path.write_bytes(audio)
+        except Exception as e:
+            print(f"Warning: Failed to cache TTS audio: {e}")
+
+    def synthesize(
+        self,
+        text: str,
+        style: str = "formal",
+        use_cache: bool = True,
+    ) -> bytes | None:
+        """Synthesize text to speech (synchronous).
+
+        Args:
+            text: Text to synthesize.
+            style: Narration style ("formal" or "dramatic").
+            use_cache: Whether to use/store cached audio.
+
+        Returns:
+            Audio bytes (MP3) or None if synthesis fails.
+        """
+        if not self.is_available or not text.strip():
+            return None
+
+        if use_cache:
+            cached = self._get_from_cache(text, style)
+            if cached:
+                return cached
+
+        try:
+            audio_gen = self._client.text_to_speech.convert(
+                text=text,
+                voice_id=self.voice_id,
+                model_id=self.model_id,
+                output_format=self.DEFAULT_OUTPUT_FORMAT,
+                voice_settings=self._get_voice_settings(style),
+            )
+            audio_bytes = b"".join(audio_gen)
+
+            if use_cache:
+                self._save_to_cache(text, style, audio_bytes)
+
+            return audio_bytes
+        except Exception as e:
+            print(f"TTS synthesis failed: {e}")
+            return None
+
+    async def asynthesize(
+        self,
+        text: str,
+        style: str = "formal",
+        use_cache: bool = True,
+    ) -> bytes | None:
+        """Synthesize text to speech (asynchronous, non-blocking).
+
+        Args:
+            text: Text to synthesize.
+            style: Narration style ("formal" or "dramatic").
+            use_cache: Whether to use/store cached audio.
+
+        Returns:
+            Audio bytes (MP3) or None if synthesis fails.
+        """
+        loop = asyncio.get_event_loop()
+        try:
+            return await asyncio.wait_for(
+                loop.run_in_executor(
+                    _tts_executor,
+                    lambda: self.synthesize(text, style, use_cache)
+                ),
+                timeout=10.0  # 10 second timeout
+            )
+        except asyncio.TimeoutError:
+            print("TTS synthesis timed out")
+            return None
+        except Exception as e:
+            print(f"Async TTS synthesis failed: {e}")
+            return None
+
+
+# Singleton instance
+_tts_service: TTSService | None = None
+
+
+def get_tts_service(force_new: bool = False) -> TTSService:
+    """Get or create the singleton TTS service.
+
+    Args:
+        force_new: Force creation of a new instance.
+
+    Returns:
+        TTSService instance.
+    """
+    global _tts_service
+    if _tts_service is None or force_new:
+        _tts_service = TTSService()
+    return _tts_service
+
+
+def reset_tts_service() -> None:
+    """Reset the singleton instance. Useful for testing."""
+    global _tts_service
+    _tts_service = None

ui/static/styles.css

@@ -252,3 +252,58 @@ h1, h2, h3 {
 p, span {
     color: var(--text-light);
 }
+
+/* ============================================
+   Judge Narration Component
+   ============================================ */
+#judge-narration {
+    background: var(--secondary-dark);
+    border-radius: var(--border-radius-md);
+    padding: 12px;
+    margin-top: 15px;
+    border-left: 3px solid var(--accent-red);
+}
+
+#judge-narration .gr-group {
+    background: transparent !important;
+    border: none !important;
+}
+
+#judge-audio {
+    margin-bottom: 8px;
+}
+
+#judge-audio audio {
+    width: 100%;
+    height: 40px;
+    border-radius: var(--border-radius-sm);
+}
+
+#judge-transcript {
+    margin-top: 5px;
+}
+
+#judge-transcript textarea {
+    background: transparent !important;
+    border: none !important;
+    color: var(--text-muted) !important;
+    font-style: italic;
+    font-size: 12px;
+    padding: 5px 0 !important;
+    min-height: 40px !important;
+}
+
+#judge-transcript label {
+    display: none !important;
+}
+
+/* Pulsing animation when judge is speaking */
+#judge-narration.speaking {
+    animation: judge-pulse 1.5s infinite;
+}
+
+@keyframes judge-pulse {
+    0% { border-left-color: var(--accent-red); }
+    50% { border-left-color: var(--guilty-red); }
+    100% { border-left-color: var(--accent-red); }
+}