fix: prevent import scoping issues and improve error handling

Resolves UnboundLocalError when using Ollama backend by removing local
import statements that shadowed module-level imports. All non-lazy
imports are now at the top of files for better readability and to
prevent variable scoping issues.

Adds validation for Ollama models before invocation to fail fast with
actionable error messages when a model isn't installed, rather than
allowing confusing downstream errors or silent fallbacks.

Author: Farmerobot

scripts/batch_analyze_random_games.py

@@ -1,15 +1,21 @@
 import argparse
-import tempfile
-import os
 import json
+import os
+import random
 import statistics
-from pathlib import Path
-from typing import List, Optional, Dict, Any
+import tempfile
 from collections import defaultdict
 from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Dict, Any
+
+import tiktoken
 
 from among_them.game_config import GameConfig
 from among_them.game_engine import GameEngine
+from among_them.models.action_type import ActionType
+from among_them.models.player_role import PlayerRole
+from among_them.utils.llm_utils import parse_llm_response_to_action
 
 
 def generate_long_cot(action, current_player, history, players, target_tokens: int = 3000) -> str:
@@ -54,13 +60,6 @@ def run_random_game_in_memory(game_config: GameConfig, greedy: bool = False) ->
             # Initialize engine
             engine = GameEngine(game_config, temp_path)
 
-            # Import random game logic
-            import random
-            from among_them.models.action_type import ActionType
-            from among_them.models.player_role import PlayerRole
-            from among_them.utils.llm_utils import parse_llm_response_to_action
-            import tiktoken
-            
             # Run game loop
             while True:
                 turn_context_history, actions_player_can_take, conversation, pre_discussion_vote_prompts = engine.get_turn_context()
@@ -596,7 +595,6 @@ def main():
 
     # Save detailed results if requested
     if args.output:
-        import json
         output_data = {
             "game_config": {
                 "num_players": args.num_players,

scripts/calculate_action_probabilities_mlx.py

@@ -13,6 +13,7 @@
 import math
 from typing import List, Tuple
 
+import numpy as np
 import mlx.core as mx
 from mlx_lm import load as mlx_load
 from mlx_lm import stream_generate
@@ -154,8 +155,6 @@ def generate_reasoning_and_calculate_probabilities(
     print("\n🎯 TOP TOKEN PROBABILITIES after Action: prefix:")
     print("-" * 60)
     if base_logprobs is not None:
-        import numpy as np
-
         logp_np = np.asarray(base_logprobs.tolist(), dtype=np.float32)
         probs_np = np.exp(logp_np)
         top_k = 10

scripts/manual_llm_game.py

@@ -1,11 +1,15 @@
+import argparse
+import os
+import sys
+import traceback
+
 import tiktoken
+
 from among_them.config import STATE_FILE
 from among_them.game_engine import GameEngine
-from among_them.utils.llm_utils import parse_llm_response_to_action, invoke_llm
+from among_them.utils.llm_utils import parse_llm_response_to_action, invoke_llm, ConfigurationError
 from among_them.utils.ui_utils import prompt_manual_fallback_action
 from among_them.game_config import GameConfig
-import os
-import argparse
 
 def main(reset=False, remove_last_n=0, game_config: GameConfig = None, state_file_path: str = None):
     """Runs the game with manual LLM control."""
@@ -92,6 +96,12 @@ def main(reset=False, remove_last_n=0, game_config: GameConfig = None, state_fil
                                 break
                             continue  # retry with same prompt
 
+                    except ConfigurationError as config_error:
+                        # Configuration errors should not be retried
+                        print(f"\033[91mConfiguration Error: {config_error}\033[0m")
+                        print(f"\033[91mPlease fix your configuration and restart the game.\033[0m")
+                        sys.exit(1)
+                            
                     except KeyboardInterrupt:
                         action_idx, llm_response, cot, _ = prompt_manual_fallback_action(actions_pd)
                         action_taken = actions_pd[action_idx]
@@ -158,6 +168,12 @@ def main(reset=False, remove_last_n=0, game_config: GameConfig = None, state_fil
                         break
                     continue  # retry with same prompt
 
+            except ConfigurationError as config_error:
+                # Configuration errors should not be retried
+                print(f"\033[91mConfiguration Error: {config_error}\033[0m")
+                print(f"\033[91mPlease fix your configuration and restart the game.\033[0m")
+                sys.exit(1)
+                    
             except KeyboardInterrupt:
                 # First Ctrl+C: switch to manual fallback. If another Ctrl+C occurs during fallback, exit cleanly.
                 try:
@@ -170,7 +186,6 @@ def main(reset=False, remove_last_n=0, game_config: GameConfig = None, state_fil
                     return  # exit the main() function cleanly
             except Exception as e:
                 # Log the error but keep the loop running
-                import traceback
                 stacktrace = traceback.format_exc()
                 print(f"\033[91mError during LLM invocation: {e}\033[0m")
                 print(f"\033[91mStacktrace: {stacktrace}\033[0m")
@@ -216,5 +231,4 @@ def parse_args():
     except KeyboardInterrupt:
         # Any uncaught Ctrl+C lands here – exit without stack trace.
         print("\nGame interrupted by user. Goodbye!")
-        import sys
         sys.exit(0)

scripts/replay_games.py

@@ -8,16 +8,13 @@
 
 import json
 import os
+import shutil
+import traceback
 from pathlib import Path
 
-from among_them.config import STATE_FILE
 from among_them.game_engine import GameEngine
 from among_them.models.action import Action
 from among_them.models.action_type import ActionType
-from among_them.models.history import History
-from among_them.utils.end_utils import get_end_game_reason
-from among_them.utils.llm_utils import parse_llm_response_to_action
-from among_them.game_config import GameConfig
 
 
 def replay_game(json_file: Path, output_folder: Path):
@@ -29,7 +26,6 @@ def replay_game(json_file: Path, output_folder: Path):
 
     # Copy the JSON file to the state file location
     try:
-        import shutil
         shutil.copyfile(json_file, state_file)
     except Exception as e:
         print(f"Error copying game file to state file: {e}")
@@ -200,7 +196,6 @@ def replay_game(json_file: Path, output_folder: Path):
 
         except Exception as e:
             print(f"Error during step: {e}")
-            import traceback
             traceback.print_exc()
             break
 
@@ -236,7 +231,6 @@ def replay_all_games(data_folder: str, output_folder: str):
             # print(f"Completed replay of {json_file.name}")
         except Exception as e:
             print(f"Failed to replay {json_file.name}: {e}")
-            import traceback
             traceback.print_exc()
 
     print(f"\nSuccessfully replayed {successful_replays}/{len(json_files)} games")

src/among_them/game_engine.py

@@ -1,4 +1,5 @@
 import json
+import os
 import random
 from typing import List, Optional
 
@@ -20,6 +21,7 @@
                                            get_players_in_room)
 from among_them.utils.end_utils import get_end_game_reason
 from among_them.utils.history_utils import initialize_history, create_system_message
+from among_them.utils.prompt_utils import build_conversation_for_player, get_initial_turn_prompt, get_incremental_observations
 from among_them.game_config import GameConfig
 
 class GameEngine:
@@ -127,8 +129,6 @@ def get_turn_context(self, player_name: Optional[str] = None) -> Optional[tuple[
         )
 
         # Build conversation history from existing turns + new user message
-        from among_them.utils.prompt_utils import build_conversation_for_player, get_initial_turn_prompt, get_incremental_observations
-        
         # Get past conversation turns for this player
         conversation, last_turn_index = build_conversation_for_player(
             current_player, self.history, self.players, self.game_config
@@ -329,7 +329,6 @@ def save_state(self):
         """Saves the current game state (history, players, config) to a JSON file."""
         try:
             # Ensure the directory exists
-            import os
             os.makedirs(os.path.dirname(self.file_path), exist_ok=True)
 
             with open(self.file_path, 'w') as f:

src/among_them/utils/llm_utils.py

@@ -6,6 +6,11 @@
 from among_them.models.action import Action, ActionType
 
 
+class ConfigurationError(Exception):
+    """Exception for configuration errors that should not be retried."""
+    pass
+
+
 def invoke_llm(
     conversation: List[dict],
     model_name: str,
@@ -62,7 +67,6 @@ def invoke_llm(
         response_text = best_action.command_perspective
 
         # Extract chain of thought from generated text
-        import re
         cot_match = re.search(r"<think>.*?</think>", generated_text, re.DOTALL)
         if cot_match:
             cot = cot_match.group(0)
@@ -103,6 +107,21 @@ def invoke_llm(
             elif LLM_BACKEND == LLMBackend.OLLAMA:
                 import ollama
 
+                # Validate model exists before attempting to use it
+                try:
+                    models_response = ollama.list()
+                    available_models = [m.model for m in models_response.models]
+                    # Check both exact match and with :latest tag
+                    model_variants = [model_name, f"{model_name}:latest"]
+                    if not any(variant in available_models for variant in model_variants):
+                        raise ConfigurationError(
+                            f"Model '{model_name}' not found in Ollama.\n"
+                            f"Available models: {', '.join(available_models)}\n"
+                            f"Pull the model first with: ollama pull {model_name}"
+                        )
+                except ollama.ResponseError as e:
+                    raise ConfigurationError(f"Failed to list Ollama models: {e}")
+                
                 print(f"Using Ollama with model: {model_name}")
 
                 response = ollama.chat(