Upload 9 files

modules/config_settings_public.py

@@ -0,0 +1,143 @@
+# FILE: modules/config_settings_public.py
+
+import os
+import sys
+import logging
+from huggingface_hub import hf_hub_download # ✅ IMPORT THE DOWNLOADER
+
+logger = logging.getLogger("ZOTHEOS_Config")
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+# --- ✅ WEB DEPLOYMENT & LOCAL PATH CONFIG ---
+
+# Standard way to detect if we are running in a Hugging Face Space
+IS_WEB_MODE = "HF_SPACE_ID" in os.environ 
+
+_is_frozen = getattr(sys, 'frozen', False) and hasattr(sys, '_MEIPASS')
+
+if _is_frozen:
+    APP_DIR = os.path.dirname(sys.executable)
+else:
+    try:
+        APP_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    except NameError:
+        APP_DIR = os.getcwd()
+        logger.warning(f"__file__ not defined, APP_DIR set to CWD: {APP_DIR}")
+
+# This directory structure is primarily for local/desktop use.
+# On Hugging Face, these paths will be created in the virtual environment.
+BASE_MODELS_DIR = os.path.join(APP_DIR, "models")
+BASE_DATA_SUBDIR = "zotheos_public_data"
+BASE_DATA_PATH = os.path.join(APP_DIR, BASE_DATA_SUBDIR)
+CORE_DIRS_TO_VERIFY = {
+    "data_base": BASE_DATA_PATH, "memory": os.path.join(BASE_DATA_PATH, "zotheos_memory"),
+    "cache": os.path.join(BASE_DATA_PATH, "cache"), "cache_transformers": os.path.join(BASE_DATA_PATH, "cache", "transformers"),
+    "cache_huggingface": os.path.join(BASE_DATA_PATH, "cache", "huggingface"), "cache_hf_hub": os.path.join(BASE_DATA_PATH, "cache", "huggingface", "hub"),
+    "logs": os.path.join(BASE_DATA_PATH, "logs"), "temp": os.path.join(BASE_DATA_PATH, "temp_files"),
+    "models_root": BASE_MODELS_DIR
+}
+
+for dir_key, dir_path in CORE_DIRS_TO_VERIFY.items():
+    try:
+        if dir_key == "models_root" and (_is_frozen or IS_WEB_MODE):
+            continue # Skip creating models folder for frozen app or web app
+        os.makedirs(dir_path, exist_ok=True)
+    except Exception as e:
+        logger.error(f"Error creating directory {dir_path}: {e}")
+
+# --- ✅ CONDITIONAL MODEL PATHS & GPU CONFIG ---
+
+if IS_WEB_MODE:
+    logger.info("✅✅✅ RUNNING IN WEB MODE (Hugging Face Space) ✅✅✅")
+    logger.info("Model paths will be resolved by hf_hub_download.")
+    
+    # Download models from the Hub instead of looking for local files
+    MODEL_PATHS = {
+        "mistral": hf_hub_download(repo_id="TheBloke/Mistral-7B-Instruct-v0.2-GGUF", filename="mistral-7b-instruct-v0.2.Q4_K_M.gguf"),
+        "gemma": hf_hub_download(repo_id="google/gemma-2b-it-gguf", filename="gemma-2b-it.Q4_K_M.gguf"),
+        "qwen": hf_hub_download(repo_id="Qwen/Qwen1.5-1.8B-Chat-GGUF", filename="qwen1.5-1.8b-chat.Q4_K_M.gguf")
+    }
+    # Free Hugging Face Spaces are CPU-only, so GPU layers MUST be 0
+    N_GPU_LAYERS_FALLBACK = 0
+    logger.info("N_GPU_LAYERS_FALLBACK forced to 0 for CPU-only web environment.")
+
+else:
+    logger.info("✅✅✅ RUNNING IN LOCAL MODE (Desktop/PC) ✅✅✅")
+    logger.info(f"Models will be loaded from local directory: {BASE_MODELS_DIR}")
+    
+    # Use local file paths
+    # Note: I've updated your paths to match the ones from the hf_hub_download for consistency.
+    # Please ensure your local folder structure matches these paths.
+    MODEL_PATHS = {
+        "mistral": os.path.join(BASE_MODELS_DIR, "mistral-7b-instruct-v0.2.Q4_K_M.gguf"),
+        "gemma": os.path.join(BASE_MODELS_DIR, "gemma-2b-it.Q4_K_M.gguf"),
+        "qwen": os.path.join(BASE_MODELS_DIR, "qwen1.5-1.8b-chat.Q4_K_M.gguf"),
+    }
+    # On local machine, use your GPU
+    N_GPU_LAYERS_FALLBACK = -1 # -1 means offload all to GPU
+    logger.info("N_GPU_LAYERS_FALLBACK set to -1 for local GPU acceleration.")
+
+
+# --- Shared Configurations ---
+
+MAX_RAM_MODELS_GB = 23.8
+MAX_CONCURRENT_MODELS = 3
+N_CTX_FALLBACK = 2048
+N_THREADS_FALLBACK = 8
+VERBOSE_LLAMA_CPP = True
+
+MODEL_SPECIFIC_PARAMS = {
+    "mistral": { "chat_format": "mistral-instruct", "n_ctx": N_CTX_FALLBACK },
+    "gemma": { "chat_format": "gemma", "n_ctx": N_CTX_FALLBACK },
+    "qwen": { "chat_format": "chatml", "n_ctx": N_CTX_FALLBACK },
+    "_default": {
+        "f16_kv": True, "use_mmap": True, "use_mlock": False,
+        "verbose": VERBOSE_LLAMA_CPP,
+        "n_gpu_layers": N_GPU_LAYERS_FALLBACK, # This now uses the correct value for web or local
+        "n_threads": N_THREADS_FALLBACK,
+        "n_ctx": N_CTX_FALLBACK
+    }
+}
+
+INFERENCE_PRESETS = {
+    "balanced": {"temperature": 0.7, "top_p": 0.9, "top_k": 40, "repeat_penalty": 1.1, "mirostat_mode": 0, "max_tokens": 1024},
+    "precise": {"temperature": 0.2, "top_p": 0.7, "top_k": 20, "repeat_penalty": 1.05, "mirostat_mode": 0, "max_tokens": 1536},
+    "creative": {"temperature": 0.9, "top_p": 0.95, "top_k": 60, "repeat_penalty": 1.15, "mirostat_mode": 2, "mirostat_tau": 4.0, "mirostat_eta": 0.1, "max_tokens": 1024},
+    "passthrough": {}
+}
+DEFAULT_INFERENCE_PRESET = "balanced"
+
+DEFAULT_SYSTEM_PROMPT = "You are ZOTHEOS, an ethical AI developed to help humanity. Provide clear, concise, and helpful responses. Be respectful and avoid harmful content."
+SYSTEM_PERSONAS = {
+    "default": DEFAULT_SYSTEM_PROMPT, "helpful_assistant": "You are a helpful AI assistant. Your goal is to provide accurate and informative answers.",
+    "philosopher": "You are an AI philosopher. Engage with complex questions thoughtfully and explore different perspectives.",
+    "coder": "You are an expert AI programmer. Provide code examples and explain them clearly. Assume a senior developer audience.",
+    "concise_summarizer": "You are an AI tasked with providing very concise summaries. Get straight to the point. Use bullet points where appropriate.",
+}
+
+MODEL_ROLES = { "mistral": "analyst", "gemma": "humanist", "qwen": "skeptic" }
+MODEL_ROLE_SYSTEM_PROMPTS = {
+    "analyst": "You are an impartial analyst. Focus on facts, clarity, and cause-effect logic. Provide structured, evidence-based reasoning.",
+    "humanist": "You are a human-centered assistant. Focus on emotion, empathy, ethical considerations, and the potential human impact or experience related to the query.",
+    "skeptic": "You are a critical evaluator and a respectful skeptic. Your role is to challenge assumptions, highlight potential risks, point out biases, and explore alternative or less obvious interpretations. Question the premises if necessary.",
+    "general": DEFAULT_SYSTEM_PROMPT
+}
+
+MODEL_WEIGHTS = { "mistral": 1.0, "gemma": 0.9, "qwen": 1.1 }
+LOG_LEVEL = "INFO"
+LOG_FORMAT = '%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s'
+
+ENV_VARS_TO_SET = {
+    "TRANSFORMERS_CACHE": CORE_DIRS_TO_VERIFY["cache_transformers"], "HF_HOME": CORE_DIRS_TO_VERIFY["cache_huggingface"],
+    "HF_HUB_CACHE": CORE_DIRS_TO_VERIFY["cache_hf_hub"], "TOKENIZERS_PARALLELISM": "false",
+}
+
+ZOTHEOS_VERSION = "Public Beta 1.4 (Web Enabled)"
+
+logger.info(f"Config settings loaded. Version: {ZOTHEOS_VERSION}")
+logger.info(f"APP_DIR: {APP_DIR} (Frozen: {_is_frozen}) | Web Mode: {IS_WEB_MODE}")

modules/knowledge_core_public.py

@@ -0,0 +1,102 @@
+import os
+import json
+import logging
+import asyncio
+import traceback
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+# ✅ Define Knowledge Storage Path
+KNOWLEDGE_FILE = os.path.expanduser("~/zotheos_public/zotheos_knowledge.json")
+
+class KnowledgeCore:
+    """🚀 Public Version of Knowledge Core (Simplified Storage and Retrieval)"""
+
+    def __init__(self):
+        """✅ Initialize Knowledge Storage."""
+        self.knowledge_store = {}
+        self.load_knowledge()
+
+    def load_knowledge(self):
+        """✅ Load Knowledge from JSON."""
+        try:
+            if os.path.exists(KNOWLEDGE_FILE):
+                with open(KNOWLEDGE_FILE, "r", encoding="utf-8") as file:
+                    self.knowledge_store = json.load(file)
+                    logger.info(f"✅ Knowledge loaded from {KNOWLEDGE_FILE}")
+            else:
+                self.knowledge_store = {}
+                logger.info(f"✅ Created new knowledge store at {KNOWLEDGE_FILE}")
+        except Exception as e:
+            logger.warning(f"⚠️ Error loading knowledge: {e}")
+            self.knowledge_store = {}
+
+    def save_knowledge(self):
+        """✅ Save Knowledge to JSON."""
+        try:
+            with open(KNOWLEDGE_FILE, "w", encoding="utf-8") as file:
+                json.dump(self.knowledge_store, file, indent=4)
+            logger.info(f"✅ Knowledge saved to {KNOWLEDGE_FILE}")
+        except Exception as e:
+            logger.warning(f"⚠️ Error saving knowledge: {e}")
+
+    async def update(self, new_knowledge: str, category: str = "general") -> bool:
+        """✅ Add New Knowledge to the Store."""
+        try:
+            knowledge_id = str(len(self.knowledge_store) + 1)
+            self.knowledge_store[knowledge_id] = {
+                'content': new_knowledge,
+                'category': category
+            }
+            self.save_knowledge()
+            logger.info(f"✅ Knowledge added with ID {knowledge_id}")
+            return True
+        except Exception as e:
+            logger.error(f"❌ Error updating knowledge: {traceback.format_exc()}")
+            return False
+
+    async def retrieve(self, query: str, n_results: int = 5) -> List[dict]:
+        """🔎 Retrieve Relevant Knowledge Based on Simple Keyword Match."""
+        try:
+            matches = []
+            for knowledge_id, data in self.knowledge_store.items():
+                if query.lower() in data['content'].lower():
+                    matches.append({
+                        'id': knowledge_id,
+                        'content': data['content'],
+                        'category': data['category']
+                    })
+                    if len(matches) >= n_results:
+                        break
+            logger.info(f"✅ Retrieved {len(matches)} matches for query '{query}'")
+            return matches
+        except Exception as e:
+            logger.error(f"❌ Error retrieving knowledge: {traceback.format_exc()}")
+            return []
+
+    async def reset(self) -> bool:
+        """🗑️ Reset Knowledge Store (Delete All Stored Data)."""
+        try:
+            self.knowledge_store = {}
+            self.save_knowledge()
+            logger.info("✅ Knowledge store reset successfully.")
+            return True
+        except Exception as e:
+            logger.error(f"❌ Error resetting knowledge store: {traceback.format_exc()}")
+            return False
+
+    async def delete_knowledge(self, knowledge_id: str) -> bool:
+        """🗑️ Delete Specific Knowledge Entry by ID."""
+        try:
+            if knowledge_id in self.knowledge_store:
+                del self.knowledge_store[knowledge_id]
+                self.save_knowledge()
+                logger.info(f"✅ Deleted knowledge ID: {knowledge_id}")
+                return True
+            else:
+                logger.warning(f"⚠️ Knowledge ID {knowledge_id} not found.")
+                return False
+        except Exception as e:
+            logger.error(f"❌ Error deleting knowledge ID {knowledge_id}: {traceback.format_exc()}")
+            return False

modules/main_fusion_public.py

@@ -0,0 +1,379 @@
+# FILE: modules/main_fusion_public.py (Finalized with Tier Logic, Async, Fusion Summary)
+
+import asyncio
+import logging
+import os
+import sys
+import time
+import json
+from typing import Dict, Any, Optional, List, Union
+
+try:
+    # Correctly determine project_root assuming this file is in 'modules'
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(script_dir)
+    if project_root not in sys.path:
+        sys.path.insert(0, project_root)
+except Exception as e_path:
+    # Basic logging if path setup fails, though critical
+    logging.basicConfig(level=logging.ERROR)
+    logging.error(f"Error setting up sys.path in main_fusion_public.py: {e_path}")
+
+try:
+    from modules.config_settings_public import (
+        MODEL_PATHS, MAX_CONCURRENT_MODELS, MAX_RAM_MODELS_GB, # Used by ModelManager init
+        DEFAULT_SYSTEM_PROMPT, SYSTEM_PERSONAS, INFERENCE_PRESETS, DEFAULT_INFERENCE_PRESET,
+        MODEL_ROLES, MODEL_ROLE_SYSTEM_PROMPTS
+    )
+    from modules.model_manager_public import ModelManager
+    from modules.memory_bank_public import MemoryBank
+    from modules.user_auth import get_user_tier
+except ImportError as e:
+    logging.basicConfig(level=logging.CRITICAL, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    logging.critical(f"CRITICAL IMPORT ERROR in main_fusion_public.py: {e}. ZOTHEOS may not function.", exc_info=True)
+    # Provide fallbacks for critical components if possible, or allow failure
+    # For now, if these fail, the __init__ will likely raise an error or log critical status.
+    # Making the application fail loudly is often better than silent dysfunction.
+    # Consider exiting if critical imports fail: sys.exit(f"Fatal Import Error in main_fusion_public.py: {e}")
+
+# --- Start of FIX: Define LLAMA_CPP_AVAILABLE ---
+try:
+    # Attempt to import the core Llama class from llama_cpp
+    from llama_cpp import Llama # You might also need LlamaCppError if you use it
+    LLAMA_CPP_AVAILABLE = True
+    # print("DEBUG: llama_cpp imported successfully, LLAMA_CPP_AVAILABLE=True") # Optional debug print
+except ImportError:
+    LLAMA_CPP_AVAILABLE = False
+    # print("DEBUG: llama_cpp import failed, LLAMA_CPP_AVAILABLE=False") # Optional debug print
+except Exception as e_llama_import: # Catch other potential errors during import
+    LLAMA_CPP_AVAILABLE = False
+    # print(f"DEBUG: An unexpected error occurred during llama_cpp import: {e_llama_import}, LLAMA_CPP_AVAILABLE=False") # Optional debug print
+# --- End of FIX ---
+
+logger = logging.getLogger("ZOTHEOS_MainFusion")
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+
+class MainFusionPublic:
+    def __init__(self, device_preference: Optional[str] = "cuda"):
+        logger.info("🚀 ZOTHEOS MainFusion Initializing (Tier Logic, Async Fusion Summary Enabled)...")
+
+        self.config = {
+            "MODEL_ROLES": MODEL_ROLES,
+            "MODEL_ROLE_SYSTEM_PROMPTS": MODEL_ROLE_SYSTEM_PROMPTS,
+            "DEFAULT_SYSTEM_PROMPT": DEFAULT_SYSTEM_PROMPT,
+            "TIER_CONFIG": {
+                "free": {"model_limit": 2, "memory_enabled": False, "display_name": "Free Tier"},
+                "starter": {"model_limit": 3, "memory_enabled": True, "display_name": "Starter Tier"},
+                # Pro uses max models from MODEL_PATHS, ensuring it uses all available configured models
+                "pro": {"model_limit": len(MODEL_PATHS.keys()) if MODEL_PATHS else 3, "memory_enabled": True, "display_name": "Pro Tier"}
+            }
+        }
+        self.models_last_queried_for_perspectives: List[str] = []
+
+        try:
+            # Pass global config values for ModelManager initialization
+            logger.info(f"Initializing ModelManager with device_preference='{device_preference}', max_count={MAX_CONCURRENT_MODELS}, max_ram_gb={MAX_RAM_MODELS_GB}...")
+            self.model_manager = ModelManager(
+                device_preference=device_preference,
+                max_model_count=MAX_CONCURRENT_MODELS,
+                max_ram_models_gb=MAX_RAM_MODELS_GB
+            )
+            # active_model_names_in_order is the master list of all models ZOTHEOS *could* use
+            self.active_model_names_in_order: List[str] = list(MODEL_PATHS.keys()) if MODEL_PATHS else []
+            logger.info(f"✅ MainFusion initialized. Max available models for fusion: {self.active_model_names_in_order}")
+        except Exception as e_mm_init:
+            logger.critical(f"❌ CRITICAL: ModelManager failed to initialize in MainFusion: {e_mm_init}", exc_info=True)
+            self.model_manager = None
+            self.active_model_names_in_order = []
+
+        try:
+            self.memory_bank = MemoryBank()
+            logger.info("✅ MemoryBank initialized.")
+        except Exception as e_mb_init:
+            logger.error(f"❌ MemoryBank failed to initialize: {e_mb_init}. Interactions may not be stored.", exc_info=True)
+            self.memory_bank = None
+
+        if not self.model_manager or not LLAMA_CPP_AVAILABLE: # Check if ModelManager itself or Llama backend failed
+             logger.critical("MainFusion started in a DEGRADED state: ModelManager or Llama.cpp backend is UNAVAILABLE.")
+
+
+    async def _get_single_model_response_direct(self, model_name: str, user_query: str, system_prompt_for_call: str, preset_name_for_call: str) -> Dict[str, Any]:
+        response_text = f"[Error: Model '{model_name}' generation did not complete or model unavailable]"
+        start_time_model = time.perf_counter()
+        status = "Model Error or Unavailable"
+
+        if not self.model_manager:
+            logger.error(f"[{model_name}] ModelManager not available for generation.")
+            return {"model": model_name, "text": "[Error: ModelManager is offline]", "time_ms": 0, "status": "ModelManager Offline"}
+
+        try:
+            logger.info(f"⚙️ [{model_name}] Calling ModelManager.generate_with_model. System Prompt: '{system_prompt_for_call[:50]}...'. User Query: '{user_query[:50].replace(chr(10),' ')}...'")
+            # generate_with_model handles actual call to Llama instance via async_generation_wrapper
+            response_text = await self.model_manager.generate_with_model(
+                model_name=model_name,
+                prompt=user_query,
+                preset_name=preset_name_for_call,
+                system_prompt=system_prompt_for_call
+            )
+            preview = response_text[:100].replace("\n", " ")
+            if response_text.startswith(("[Error:", "[No text generated", "[Malformed response")) or not response_text.strip():
+                logger.warning(f"⚠️ [{model_name}] Model returned an error string or empty content: {preview}...")
+                status = "Model Error or Empty Response"
+            else:
+                logger.info(f"✅ [{model_name}] Response received ({len(response_text)} chars): {preview}...")
+                status = "Success"
+        except Exception as e:
+            logger.error(f"❌ [{model_name}] Exception in _get_single_model_response_direct: {e}", exc_info=True)
+            response_text = f"[Error: MainFusion encountered an exception during {model_name} generation: {type(e).__name__}]"
+            status = "MainFusion Exception"
+        inference_time_ms = (time.perf_counter() - start_time_model) * 1000
+        return {"model": model_name, "text": response_text.strip(), "time_ms": round(inference_time_ms, 2), "status": status}
+
+    async def _generate_true_fusion_summary(self, raw_responses_dict: Dict[str, str], original_query: str, models_actually_used: List[str]) -> str:
+        logger.info(f"Attempting to generate a true fusion summary from {len(models_actually_used)} perspective(s).")
+        summarizer_model_key = "gemma" # Default summarizer, ensure it's in MODEL_PATHS and loadable
+
+        valid_responses_for_summary = {
+            model: text for model, text in raw_responses_dict.items()
+            if model in models_actually_used and text and not text.startswith("[Error:")
+        }
+
+        if not valid_responses_for_summary: # No valid responses at all
+            logger.warning("No valid responses available to generate a fusion summary.")
+            return "A summary could not be generated as no valid perspectives were successfully gathered."
+
+        if len(valid_responses_for_summary) == 1:
+            single_model_name = list(valid_responses_for_summary.keys())[0]
+            logger.info(f"Only one valid perspective from {single_model_name}. Using it as the summary.")
+            return f"Based on the single available perspective from **{single_model_name.capitalize()}**:\n\n{list(valid_responses_for_summary.values())[0]}"
+
+        fusion_prompt = f"Original User Question: \"{original_query}\"\n\n"
+        fusion_prompt += "You are the Fusion Summary engine for ZOTHEOS. Your task is to read the multiple perspectives provided below and write a concise, balanced, and synthesized summary. Capture the most important points, common themes, and notable differences from all viewpoints. Your tone should be thoughtful, neutral, and respectful. Structure the summary clearly.\n\n"
+
+        for model_name, text in valid_responses_for_summary.items():
+            role = self.config["MODEL_ROLES"].get(model_name, "General")
+            fusion_prompt += f"--- PERSPECTIVE FROM {model_name.upper()} ({role.capitalize()}) ---\n{text}\n\n"
+
+        fusion_prompt += "--- SYNTHESIZED SUMMARY (Combine the perspectives above into a unified insight) ---\n"
+
+        logger.info(f"Calling summarizer model '{summarizer_model_key}' (from available: {self.active_model_names_in_order}) for fusion summary.")
+
+        if not self.model_manager:
+            logger.error("ModelManager not available for generating fusion summary.")
+            return "[Error: Summarizer service unavailable - ModelManager offline]"
+
+        try:
+            # The system prompt for the summarizer itself
+            summarizer_system_prompt = "You are an expert synthesis AI. Your role is to create a coherent and insightful summary from the provided texts."
+
+            summary_text = await self.model_manager.generate_with_model(
+                model_name=summarizer_model_key,
+                prompt=fusion_prompt, # The full context with all perspectives
+                preset_name="precise", # Use a precise preset for summarization
+                system_prompt=summarizer_system_prompt
+            )
+            if summary_text and not summary_text.startswith("[Error:"):
+                logger.info("✅ True fusion summary generated successfully.")
+                return summary_text.strip()
+            else:
+                logger.warning(f"Summarizer model '{summarizer_model_key}' returned an error or empty response: {summary_text}")
+                return "[Warning: Summary generation was partial or failed. Displaying raw perspectives.]"
+        except Exception as e:
+            logger.error(f"❌ Exception while generating true fusion summary with '{summarizer_model_key}': {e}", exc_info=True)
+            return f"[Error: The summary generation process failed. Exception: {type(e).__name__}]"
+
+    def _analyze_responses_basic(self, responses_dict: Dict[str, str], model_roles: Dict[str, str]) -> Dict[str, Any]:
+        valid_responses = {model: text for model, text in responses_dict.items() if text and not text.startswith("[Error:")}
+        consensus_points = []
+        if len(valid_responses) > 1: consensus_points.append("Multiple perspectives were gathered and synthesized.")
+        elif len(valid_responses) == 1: consensus_points.append("A single primary perspective was available for synthesis.")
+        else: consensus_points.append("No valid primary perspectives were available for synthesis.")
+        return {"consensus_points": consensus_points, "contradictions": [], "unique_insights": valid_responses}
+
+    def _synthesize_fusion_response(self, analysis_result: dict, model_roles: dict, raw_responses_dict: dict, final_summary_text: str, models_used_for_perspectives: List[str]) -> str:
+        response_parts = []
+
+        response_parts.append("## ✨ ZOTHEOS Final Synthesized Insight ✨")
+        response_parts.append(final_summary_text if final_summary_text and not final_summary_text.startswith(("[Error:", "[Warning:")) else "*Synthesis process encountered an issue or no summary was generated. Please see detailed perspectives below.*")
+        response_parts.append("\n---\n")
+
+        response_parts.append("### 💬 Detailed Individual Perspectives")
+        has_any_valid_perspectives = False
+        for model_name in models_used_for_perspectives:
+            text = raw_responses_dict.get(model_name)
+            role = model_roles.get(model_name, "General") # Default role
+            response_parts.append(f"**Perspective from {model_name.capitalize()} ({role.capitalize()}):**")
+            if text and not text.startswith("[Error:"):
+                response_parts.append(text.strip())
+                has_any_valid_perspectives = True
+            else:
+                response_parts.append(f"*{text if text else '[No response or error from this model.]'}*") # Display error or placeholder
+            response_parts.append("")
+        if not has_any_valid_perspectives and not (final_summary_text and not final_summary_text.startswith(("[Error:", "[Warning:"))):
+             # If summary also failed/empty and no valid individual perspectives.
+             response_parts = ["## ⚠️ ZOTHEOS Alert\n\nUnfortunately, ZOTHEOS encountered issues processing your query with all available AI cores for your tier. No insights could be gathered at this time. Please try rephrasing your query or try again later."]
+        elif not has_any_valid_perspectives : # Summary might be there, but no individual details.
+            response_parts.append("*No valid individual perspectives were successfully retrieved to display in detail.*")
+
+
+        return "\n".join(response_parts).strip()
+
+    async def process_query_with_fusion(
+        self,
+        query: str,
+        user_token: Optional[str] = None,
+        persona_key: Optional[str] = None,
+        fusion_mode_override: str = "balanced",
+        **kwargs
+    ) -> str:
+        process_start_time = time.time()
+        current_tier_name = get_user_tier(user_token if user_token else "")
+        tier_settings = self.config["TIER_CONFIG"].get(current_tier_name, self.config["TIER_CONFIG"]["free"])
+        tier_model_limit = tier_settings["model_limit"]
+        tier_memory_enabled = tier_settings["memory_enabled"]
+        logger.info(f"User Tier: '{current_tier_name}' ({tier_settings['display_name']}). Model Limit: {tier_model_limit}, Memory: {'Enabled' if tier_memory_enabled else 'Disabled'}.")
+
+        if not self.model_manager or not LLAMA_CPP_AVAILABLE: return "[Error: ZOTHEOS Core Model Manager not ready or Llama.cpp backend unavailable.]"
+        if not self.active_model_names_in_order: return "[Error: ZOTHEOS Core not ready. No models configured in MODEL_PATHS.]"
+        if not query or not query.strip(): return "[Error: Query is empty. Please provide a question or topic.]"
+
+        current_query_text = query
+        current_preset_name = fusion_mode_override if fusion_mode_override in INFERENCE_PRESETS else DEFAULT_INFERENCE_PRESET
+        base_persona_prompt = SYSTEM_PERSONAS.get(persona_key or "default", self.config["DEFAULT_SYSTEM_PROMPT"])
+
+        # Determine actual models to use based on tier limit and availability
+        models_to_use_for_perspectives = [m for m in self.active_model_names_in_order if m in MODEL_PATHS][:tier_model_limit]
+        self.models_last_queried_for_perspectives = models_to_use_for_perspectives # For status report
+
+        if not models_to_use_for_perspectives:
+            logger.error(f"No models available for tier '{current_tier_name}' after applying limit of {tier_model_limit}.")
+            return f"[Error: No models available for your current tier ('{current_tier_name}').]"
+
+        logger.info(f"🔎 Processing query. Models for perspectives (Tier: {current_tier_name}): {models_to_use_for_perspectives}. Preset: '{current_preset_name}'. Query: '{current_query_text[:60].replace(chr(10),' ')}...'")
+
+        raw_responses_dict: Dict[str, str] = {}
+        individual_results_for_memory: List[Dict[str, Any]] = []
+        successful_responses = 0
+
+        for model_name in models_to_use_for_perspectives:
+            model_role = self.config["MODEL_ROLES"].get(model_name, "general")
+            system_prompt_for_model = self.config["MODEL_ROLE_SYSTEM_PROMPTS"].get(model_role, base_persona_prompt)
+            query_for_this_model = current_query_text
+            if model_name.lower() == "gemma" and system_prompt_for_model:
+                query_for_this_model = f"<start_of_turn>user\n{system_prompt_for_model.strip()}\n{current_query_text}<end_of_turn>\n<start_of_turn>model\n"
+                system_prompt_for_model = ""
+            model_output_data = await self._get_single_model_response_direct(model_name, query_for_this_model, system_prompt_for_model, current_preset_name)
+            individual_results_for_memory.append(model_output_data)
+            raw_responses_dict[model_name] = model_output_data.get("text", "[Error: No text field in response data]")
+            if model_output_data.get("status") == "Success":
+                successful_responses += 1
+
+        synthesized_summary_text = await self._generate_true_fusion_summary(raw_responses_dict, current_query_text, models_to_use_for_perspectives)
+        analysis_result = self._analyze_responses_basic(raw_responses_dict, self.config["MODEL_ROLES"]) # Basic analysis for now
+        final_fused_output_content = self._synthesize_fusion_response(analysis_result, self.config["MODEL_ROLES"], raw_responses_dict, synthesized_summary_text, models_to_use_for_perspectives)
+
+        persona_display = (persona_key or "default").capitalize()
+        mode_display = current_preset_name.capitalize()
+        tier_display_name = tier_settings.get("display_name", current_tier_name.capitalize())
+        final_header = f"## 🧠 ZOTHEOS Fused Perspectives 🧠\n*(Fusion Mode: {mode_display} | Persona: {persona_display} | Tier: {tier_display_name})*\n\n"
+        final_fused_output = final_header + final_fused_output_content
+
+        if successful_responses == 0 and not "[Error:" in final_fused_output_content and not "[Warning:" in final_fused_output_content:
+             logger.error(f"All models ({len(models_to_use_for_perspectives)}) failed for tier '{current_tier_name}'.")
+             final_fused_output = final_header + "[Critical Error: ZOTHEOS was unable to obtain any valid responses from its AI cores for this query.]\n\n" + final_fused_output_content.split("\n\n",1)[-1]
+
+        if tier_memory_enabled:
+            if self.memory_bank:
+                try:
+                    memory_metadata = {
+                        "user_token_used_prefix": user_token[:3] + "***" if user_token and len(user_token) > 3 else "N/A (No Token)" if not user_token else user_token,
+                        "tier_at_interaction": current_tier_name,
+                        "persona_key": persona_key or "default", "fusion_mode_used": current_preset_name,
+                        # timestamp_iso is now added within store_memory_async
+                        "duration_seconds": round(time.time() - process_start_time, 3),
+                        "active_models_queried": models_to_use_for_perspectives, # Models actually used for perspectives
+                        "individual_model_outputs": individual_results_for_memory, # Detailed dicts
+                        "synthesized_summary_text": synthesized_summary_text, # The AI-generated summary
+                        "fused_response_length_chars": len(final_fused_output),
+                        "successful_model_responses": successful_responses,
+                        "total_models_queried": len(models_to_use_for_perspectives)
+                    }
+                    await self.memory_bank.store_memory_async(query=current_query_text, response=final_fused_output, metadata=memory_metadata)
+                except Exception as e_mem: logger.error(f"Failed to store fusion interaction in MemoryBank (Tier: '{current_tier_name}'): {e_mem}", exc_info=True)
+            else: logger.warning(f"MemoryBank not initialized. Skipping storage (Tier: '{current_tier_name}').")
+        else: logger.info(f"Memory storage disabled for tier '{current_tier_name}'. Skipping storage.")
+
+        total_processing_time = round(time.time() - process_start_time, 2)
+        logger.info(f"🧠 Fusion complete in {total_processing_time}s. Output len: {len(final_fused_output)}. Models used: {len(models_to_use_for_perspectives)} (Tier: {current_tier_name}).")
+        return final_fused_output
+
+    async def get_status_report(self) -> Dict[str, Any]:
+        report: Dict[str, Any] = {
+            "status": "Full Multi-Model Fusion Mode Active",
+            "fusion_engine_status": "Online" if self.model_manager and self.active_model_names_in_order and LLAMA_CPP_AVAILABLE else "Degraded/Offline",
+            "all_available_models": self.active_model_names_in_order,
+            "models_last_queried_for_perspectives": getattr(self, 'models_last_queried_for_perspectives', []),
+            "model_manager_status": "Online" if self.model_manager else "Offline/Init Failed",
+            "llama_cpp_backend_available": LLAMA_CPP_AVAILABLE,
+            "memory_bank_status": "Online" if self.memory_bank else "Offline/Init Failed"
+        }
+        if self.model_manager and hasattr(self.model_manager, 'get_loaded_model_stats'):
+            try: report["model_manager_runtime_stats"] = self.model_manager.get_loaded_model_stats()
+            except Exception as e: report["model_manager_runtime_stats"] = f"Error getting MM stats: {e}"
+        else: report["model_manager_runtime_stats"] = "ModelManager N/A for stats."
+
+        if self.memory_bank and hasattr(self.memory_bank, 'get_memory_stats'):
+            try: report["memory_bank_stats"] = await self.memory_bank.get_memory_stats()
+            except Exception as e: report["memory_bank_stats"] = f"Error getting MB stats: {e}"
+        else: report["memory_bank_stats"] = "MemoryBank N/A for stats."
+        return report
+
+if __name__ == "__main__":
+    if os.getenv("ZOTHEOS_DEBUG_DEPS", "false").lower() != "true":
+        for lib_logger_name in ["torch", "huggingface_hub", "psutil", "llama_cpp", "httpx", "PIL"]: logging.getLogger(lib_logger_name).setLevel(logging.WARNING)
+    logger.setLevel(logging.DEBUG)
+    logger.info("--- MainFusionPublic (Tier Logic & Async Summary) CLI Test ---")
+    async def run_main_fusion_cli_test_with_token(test_token=None, token_desc="Default (Free Tier)"):
+        main_fusion_instance: Optional[MainFusionPublic] = None
+        logger.info(f"\n--- Testing with token: '{token_desc}' ---")
+        try:
+            main_fusion_instance = MainFusionPublic(device_preference="cuda")
+            if not main_fusion_instance.model_manager or not main_fusion_instance.active_model_names_in_order or not LLAMA_CPP_AVAILABLE:
+                logger.critical("CLI Test Aborted: MainFusion init failed (MM or LlamaCPP unavailable)."); return
+            test_query = "What are the core principles of Stoicism and how can they be applied in modern life?"
+            logger.info(f"CLI Test: Querying (Token: {test_token[:3] + '...' if test_token and len(test_token)>3 else test_token}): '{test_query}'")
+            response = await main_fusion_instance.process_query_with_fusion(query=test_query, user_token=test_token, persona_key="philosopher", fusion_mode_override="balanced")
+            print("\n" + "="*25 + f" CLI Test Response ({token_desc}) " + "="*25); print(response); print("="* (50 + len(f" CLI Test Response ({token_desc}) ") + 2))
+            status = await main_fusion_instance.get_status_report()
+            print("\nSystem Status Report After Query:"); print(json.dumps(status, indent=2, default=str))
+        except Exception as e: logger.critical(f"Error during CLI test ({token_desc}): {e}", exc_info=True); print(f"🚨 CLI Test Error ({token_desc}): {e}")
+        finally:
+            if main_fusion_instance and main_fusion_instance.model_manager and hasattr(main_fusion_instance.model_manager, 'shutdown'):
+                logger.info(f"CLI Test ({token_desc}): Shutting down ModelManager...")
+                main_fusion_instance.model_manager.shutdown() # This is synchronous
+            logger.info(f"🛑 MainFusion CLI test ({token_desc}) shutdown.")
+    async def run_all_cli_tests():
+        # Ensure stripe_users.json is in project root for this test to work with tokens
+        tokens_to_test = {
+            None: "No Token (Defaults to Free)",
+            "TOKEN_FOR_FREE_TEST": "Free Tier Token", # Add this to your stripe_users.json
+            "TOKEN_FOR_STARTER_TEST": "Starter Tier Token", # Add this
+            "TOKEN_FOR_PRO_TEST": "Pro Tier Token" # Add this
+        }
+        # Create dummy stripe_users.json if not exists for test
+        if not os.path.exists(os.path.join(project_root, "stripe_users.json")):
+            logger.warning("Creating dummy stripe_users.json for CLI test.")
+            dummy_users = {t: t.split('_')[1].lower() for t in tokens_to_test if t} # type: ignore
+            with open(os.path.join(project_root, "stripe_users.json"), "w") as f:
+                json.dump(dummy_users, f, indent=2)
+
+        for token, desc in tokens_to_test.items():
+            await run_main_fusion_cli_test_with_token(token, desc)
+
+    asyncio.run(run_all_cli_tests())

modules/memory_bank_public.py

@@ -0,0 +1,354 @@
+# FILE: modules/memory_bank_public.py (Finalized for Beta Checklist & Async Correctness)
+
+import os
+import json
+import time 
+import asyncio
+import logging
+import traceback # For more detailed error logging if needed
+from typing import List, Dict, Optional, Any
+from json import JSONDecodeError
+from datetime import datetime, timezone # For ISO timestamps
+from pathlib import Path # For home directory in export
+import sys # For logger setup if run standalone
+
+logger = logging.getLogger("ZOTHEOS_MemoryBank")
+if not logger.handlers:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+# --- Define memory file paths and limits ---
+try:
+    # Path logic for when memory_bank_public.py is in 'modules' folder
+    # and data directory is in project root ('../zotheos_public_data')
+    current_file_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root_dir = os.path.dirname(current_file_dir) # This is ZOTHEOS_Release_Package
+    
+    # Check if running from PyInstaller bundle
+    if getattr(sys, 'frozen', False) and hasattr(sys, '_MEIPASS'):
+        # If bundled, data directory is relative to sys._MEIPASS (the temp extraction folder)
+        DATA_BASE_DIR = os.path.join(sys._MEIPASS, "zotheos_public_data")
+    else:
+        # If running as script, data directory is relative to project root
+        DATA_BASE_DIR = os.path.join(project_root_dir, "zotheos_public_data")
+
+    if not os.path.exists(DATA_BASE_DIR):
+        os.makedirs(DATA_BASE_DIR, exist_ok=True)
+        logger.info(f"Created data base directory: {DATA_BASE_DIR}")
+        
+    MEMORY_DIR = os.path.join(DATA_BASE_DIR, "zotheos_memory")
+    if not os.path.exists(MEMORY_DIR):
+        os.makedirs(MEMORY_DIR, exist_ok=True)
+        logger.info(f"Created memory directory: {MEMORY_DIR}")
+        
+except Exception as e:
+     logger.critical(f"❌ Failed to setup base/memory directory for MemoryBank: {e}. Using fallback in user home.")
+     MEMORY_DIR = os.path.join(os.path.expanduser("~"), ".zotheos", "zotheos_memory")
+     os.makedirs(MEMORY_DIR, exist_ok=True)
+
+
+MEMORY_FILE_PATH = os.path.join(MEMORY_DIR, "zotheos_memory.json")
+MEMORY_FILE_TMP = os.path.join(MEMORY_DIR, "zotheos_memory_tmp.json")
+MEMORY_SIZE_LIMIT = 1000 
+MEMORY_SCHEMA_VERSION = 1.2 # Bumped for metadata structure in entry
+
+class MemoryBank:
+    def __init__(self):
+        self.memory_list: List[Dict[str, Any]] = []
+        self.memory_dict: Dict[str, Dict[str, Any]] = {} # For ID-based lookups, ID should be string
+        self.next_id = 0
+        logger.info(f"🧠 Initializing Memory Bank. Memory file: {MEMORY_FILE_PATH}")
+        self._load_memory() # Load initial state
+        
+        if self.memory_list:
+            try:
+                # Ensure IDs are treated as integers for max() if they are numeric strings
+                numeric_ids = [int(m.get('id', -1)) for m in self.memory_list if str(m.get('id', '')).isdigit()]
+                if numeric_ids:
+                    max_id = max(numeric_ids)
+                    self.next_id = max(max_id + 1, len(self.memory_list))
+                else: # No numeric IDs found
+                    self.next_id = len(self.memory_list)
+            except ValueError: # Fallback if conversion to int fails for some reason
+                self.next_id = len(self.memory_list) 
+            logger.info(f"Loaded {len(self.memory_list)} memories. Next ID set to {self.next_id}.")
+        else:
+            logger.info("Initialized with empty memory.")
+
+    def _reset_memory_state(self):
+        self.memory_list = []
+        self.memory_dict = {}
+        self.next_id = 0
+        logger.info("Memory state has been reset.")
+
+    def _load_memory(self):
+        logger.info(f"Attempting to load memory from {MEMORY_FILE_PATH}...")
+        try:
+            if os.path.exists(MEMORY_FILE_PATH):
+                with open(MEMORY_FILE_PATH, "r", encoding="utf-8") as file:
+                    data = json.load(file)
+                if isinstance(data, dict) and "entries" in data and isinstance(data["entries"], list):
+                    self.memory_list = data["entries"]
+                    # Rebuild dictionary, ensuring IDs are strings for keys
+                    self.memory_dict = {str(m['id']): m for m in self.memory_list if m.get('id') is not None}
+                    logger.info(f"✅ Successfully loaded {len(self.memory_list)} memory entries (schema version: {data.get('schema_version', 'Unknown')}).")
+                elif isinstance(data, list): 
+                    logger.warning(f"Old memory format (list) detected. Converting and saving in new format.")
+                    self.memory_list = data
+                    self.memory_dict = {str(m.get('id','')): m for m in self.memory_list if m.get('id') is not None}
+                    self._save_memory() # Save immediately in new format
+                else:
+                    logger.warning(f"⚠️ Memory file {MEMORY_FILE_PATH} has an unexpected main structure. Resetting memory.")
+                    self._reset_memory_state()
+            else:
+                logger.info(f"✅ No existing memory file found at {MEMORY_FILE_PATH}. Starting fresh.")
+                self._reset_memory_state()
+        except JSONDecodeError as e:
+            logger.error(f"❌ Error decoding JSON from memory file {MEMORY_FILE_PATH}: {e}. File might be corrupted. Resetting memory.", exc_info=False)
+            self._handle_corrupted_memory_file()
+        except FileNotFoundError: 
+            logger.info(f"✅ Memory file {MEMORY_FILE_PATH} not found. Starting fresh (FileNotFound).")
+            self._reset_memory_state()
+        except Exception as e:
+            logger.error(f"❌ Unexpected error loading memory: {e}. Resetting memory.", exc_info=True)
+            self._reset_memory_state()
+
+    def _handle_corrupted_memory_file(self):
+        self._reset_memory_state()
+        if os.path.exists(MEMORY_FILE_PATH):
+            try:
+                corrupt_backup_path = f"{MEMORY_FILE_PATH}.corrupt_{datetime.now().strftime('%Y%m%d%H%M%S')}"
+                os.rename(MEMORY_FILE_PATH, corrupt_backup_path)
+                logger.info(f"Backed up corrupted memory file to {corrupt_backup_path}")
+            except OSError as backup_err:
+                logger.error(f"Failed to backup corrupted memory file: {backup_err}")
+
+    def _save_memory(self): # This is synchronous
+        logger.debug(f"Attempting atomic save to {MEMORY_FILE_PATH}...")
+        try:
+            data_to_save = {"schema_version": MEMORY_SCHEMA_VERSION, "entries": self.memory_list}
+            with open(MEMORY_FILE_TMP, "w", encoding="utf-8") as file:
+                json.dump(data_to_save, file, indent=2) 
+            os.replace(MEMORY_FILE_TMP, MEMORY_FILE_PATH)
+            logger.info(f"✅ Memory saved successfully ({len(self.memory_list)} entries).")
+        except Exception as e:
+            logger.error(f"❌ Error saving memory: {e}", exc_info=True)
+            if os.path.exists(MEMORY_FILE_TMP):
+                try: os.remove(MEMORY_FILE_TMP)
+                except OSError: pass
+        finally:
+            if os.path.exists(MEMORY_FILE_TMP):
+                try: os.remove(MEMORY_FILE_TMP)
+                except OSError as e_rem: logger.warning(f"Could not remove temp memory file {MEMORY_FILE_TMP}: {e_rem}")
+
+    async def save_memory_async(self):
+         logger.debug("Scheduling asynchronous memory save...")
+         await asyncio.to_thread(self._save_memory)
+
+    async def store_memory_async(self, query: str, response: str, metadata: Optional[Dict[str, Any]] = None):
+        if not query or not response:
+             logger.warning("⚠️ Attempted to store empty query or response. Skipping.")
+             return
+        try:
+            current_id_num = self.next_id
+            current_metadata = metadata.copy() if metadata is not None else {} # Work with a copy
+
+            # Ensure a proper ISO-formatted timestamp is in metadata
+            current_metadata['timestamp_iso'] = datetime.now(timezone.utc).isoformat()
+
+            memory_entry = {
+                'id': str(current_id_num), 
+                'query': query,
+                'response': response, # This is the full_fused_output from main_fusion
+                'created_at_unix': time.time(), # Retain for fallback sorting
+                'schema_version': MEMORY_SCHEMA_VERSION,
+                'metadata': current_metadata # This now contains timestamp_iso and other details
+            }
+            self.next_id += 1
+            self.memory_list.append(memory_entry)
+            self.memory_dict[str(current_id_num)] = memory_entry
+            logger.info(f"Stored memory entry ID {current_id_num}.")
+            
+            removed_count = 0
+            while len(self.memory_list) > MEMORY_SIZE_LIMIT:
+                oldest_memory = self.memory_list.pop(0)
+                oldest_id = str(oldest_memory.get('id', ''))
+                if oldest_id and oldest_id in self.memory_dict: del self.memory_dict[oldest_id]
+                removed_count += 1
+            if removed_count > 0: logger.info(f"Removed {removed_count} oldest entries for size limit.")
+            await self.save_memory_async()
+        except Exception as e: logger.error(f"❌ Error storing memory entry: {e}", exc_info=True)
+
+    async def retrieve_recent_memories_async(self, limit: int = 5) -> List[Dict[str, Any]]:
+        logger.debug(f"Retrieving up to {limit} recent memories, sorted.")
+        if not self.memory_list: return []
+        try:
+            def get_sort_key(entry):
+                ts_iso = entry.get('metadata', {}).get('timestamp_iso')
+                # Fallback to created_at_unix if timestamp_iso is missing or unparsable
+                if ts_iso:
+                    try: return datetime.fromisoformat(ts_iso.replace('Z', '+00:00'))
+                    except ValueError: 
+                        logger.warning(f"Could not parse timestamp_iso '{ts_iso}' for entry ID {entry.get('id')}. Falling back to created_at_unix.")
+                        pass # Fall through to use created_at_unix
+                return datetime.fromtimestamp(entry.get('created_at_unix', 0), timezone.utc)
+
+            # Make a copy for sorting to avoid modifying self.memory_list if other operations occur
+            sorted_entries = sorted(list(self.memory_list), key=get_sort_key, reverse=True)
+            
+            actual_limit = max(0, min(limit, len(sorted_entries)))
+            recent_sorted_memories = sorted_entries[:actual_limit]
+            logger.info(f"Retrieved {len(recent_sorted_memories)} recent memories (sorted).")
+            return recent_sorted_memories
+        except Exception as e:
+            logger.error(f"❌ Error retrieving and sorting recent memories: {e}", exc_info=True)
+            # Fallback to unsorted last N if sorting fails
+            return self.memory_list[-limit:][::-1] if limit > 0 and self.memory_list else []
+            
+    def load_all_memory_entries_structured(self) -> List[Dict[str, Any]]:
+        logger.info(f"Loading all {len(self.memory_list)} memory entries (structured).")
+        return list(self.memory_list)
+
+    async def load_all_memory_entries_structured_async(self) -> List[Dict[str, Any]]:
+        logger.info(f"Asynchronously loading all {len(self.memory_list)} memory entries (structured).")
+        return list(self.memory_list) # For now, direct copy is fine as it's in-memory
+
+    async def retrieve_memory_by_id(self, memory_id: str) -> Optional[Dict[str, Any]]:
+        memory_id_str = str(memory_id)
+        try:
+            memory = self.memory_dict.get(memory_id_str)
+            if memory: logger.info(f"Retrieved memory entry ID {memory_id_str}.")
+            else: logger.warning(f"Memory ID {memory_id_str} not found in dictionary.")
+            return memory 
+        except Exception as e: logger.error(f"❌ Error retrieving memory ID {memory_id_str}: {e}", exc_info=True); return None
+
+    async def retrieve_last_response(self) -> Optional[str]:
+        if not self.memory_list: logger.info("Retrieve last response: Memory list is empty."); return None
+        try:
+            last_entry = self.memory_list[-1]; response = last_entry.get('response')
+            if isinstance(response, str) and response.strip(): logger.info("Retrieve last response: Found valid response."); return response
+            else: logger.warning(f"Retrieve last response: Last entry (ID {last_entry.get('id', 'N/A')}) has empty response."); return None
+        except Exception as e: logger.error(f"❌ Error retrieving last response: {e}", exc_info=True); return None
+
+    async def clear_all_memory(self):
+        logger.warning("Initiating complete memory wipe...")
+        try: self._reset_memory_state(); await self.save_memory_async(); logger.info("✅ All memory cleared successfully."); return True
+        except Exception as e: logger.error(f"❌ Error clearing memory: {e}", exc_info=True); return False
+
+    async def delete_memory_by_id(self, memory_id: str):
+        logger.warning(f"Attempting to delete memory ID {memory_id}...")
+        memory_id_str = str(memory_id)
+        try:
+            if memory_id_str in self.memory_dict:
+                del self.memory_dict[memory_id_str]
+                self.memory_list = [m for m in self.memory_list if str(m.get('id', '')) != memory_id_str]
+                await self.save_memory_async()
+                logger.info(f"✅ Memory with ID {memory_id_str} deleted successfully.")
+                return True
+            else:
+                logger.warning(f"⚠️ Memory ID {memory_id_str} not found for deletion.")
+                return False
+        except Exception as e:
+            logger.error(f"❌ Error deleting memory ID {memory_id_str}: {e}", exc_info=True)
+            return False
+
+    async def get_memory_stats(self) -> Dict[str, Any]: # This is now async
+        logger.info("Calculating memory statistics...")
+        stats: Dict[str, Any] = {'total_entries': len(self.memory_list), 'disk_usage_mb': 0.0, 'memory_limit': MEMORY_SIZE_LIMIT, 'next_id': self.next_id, 'schema_version': MEMORY_SCHEMA_VERSION }
+        try:
+            if os.path.exists(MEMORY_FILE_PATH):
+                file_size_bytes = await asyncio.to_thread(os.path.getsize, MEMORY_FILE_PATH)
+                stats['disk_usage_mb'] = round(file_size_bytes / (1024 * 1024), 3)
+            logger.info(f"Memory Stats: {stats}")
+        except Exception as e: logger.error(f"❌ Error calculating memory file size: {e}", exc_info=True)
+        return stats
+
+    def export_memory_to_file_sync(self) -> Optional[str]:
+        """Synchronously exports memory file. Returns exported file path or None."""
+        # NOTE (Future Personalization): Consider allowing user to choose export location via UI dialog.
+        if not os.path.exists(MEMORY_FILE_PATH):
+            logger.warning("No memory file to export because it doesn't exist.")
+            return None
+        if not self.memory_list: # Also check if there are any entries to export
+            logger.warning("No memory entries to export, memory file might be empty or just schema.")
+            # Decide if you want to export an empty "entries" file or return None
+            # For now, let's allow exporting an empty structure.
+            # return None 
+            
+        try:
+            export_dir = Path.home() / "Desktop"
+            if not (export_dir.exists() and export_dir.is_dir()):
+                export_dir = Path.home() / "Downloads"
+            if not (export_dir.exists() and export_dir.is_dir()):
+                export_dir = Path(MEMORY_DIR) # Fallback
+                logger.warning(f"Desktop/Downloads not found/accessible, exporting to memory directory: {export_dir}")
+            os.makedirs(export_dir, exist_ok=True) # Ensure export_dir exists
+
+            timestamp_str = datetime.now().strftime('%Y%m%d_%H%M%S')
+            export_filename = f"zotheos_memory_export_{timestamp_str}.json"
+            export_full_path = export_dir / export_filename
+
+            import shutil 
+            shutil.copy2(MEMORY_FILE_PATH, export_full_path)
+            
+            logger.info(f"✅ Memory successfully exported to: {export_full_path}")
+            return str(export_full_path)
+        except Exception as e:
+            logger.error(f"❌ Failed to export memory: {e}", exc_info=True)
+            return None
+
+    async def export_memory_to_file_async(self) -> Optional[str]:
+        """Asynchronously exports the memory file."""
+        logger.info("Scheduling asynchronous memory export...")
+        return await asyncio.to_thread(self.export_memory_to_file_sync)
+
+
+async def main_test():
+     logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+     logger.info("--- MemoryBank Test ---")
+     mb = MemoryBank()
+     
+     logger.info(f"Initial memory file path: {MEMORY_FILE_PATH}")
+     if os.path.exists(MEMORY_FILE_PATH):
+         logger.info("Memory file exists. Clearing for fresh test.")
+         await mb.clear_all_memory()
+     else:
+         logger.info("No pre-existing memory file found for test.")
+
+     stats1 = await mb.get_memory_stats()
+     logger.info(f"Stats after potential clear: {stats1}")
+
+     # Test Store
+     await mb.store_memory_async("Query 1", "Response 1", metadata={"custom_field": "value1", "tier_at_interaction": "free"})
+     await asyncio.sleep(0.01) 
+     await mb.store_memory_async("Query 2", "Response 2", metadata={"user_token_used_prefix": "tes***", "synthesized_summary_text": "Summary for Q2"})
+     await asyncio.sleep(0.01)
+     await mb.store_memory_async("Query 3", "Response 3", metadata={"tier_at_interaction": "pro", "synthesized_summary_text": "Summary for Q3"})
+     await asyncio.sleep(0.01)
+     await mb.store_memory_async("Query 4", "Response 4", metadata={}) # No extra metadata
+     await asyncio.sleep(0.01)
+     await mb.store_memory_async("Query 5", "Response 5", metadata={"synthesized_summary_text": "This is summary 5."})
+     await asyncio.sleep(0.01)
+     await mb.store_memory_async("Query 6", "Response 6", metadata={"synthesized_summary_text": "This is summary 6, a bit longer than the preview."})
+
+     recent_for_display = await mb.retrieve_recent_memories_async(limit=5)
+     logger.info(f"Recent 5 (for display, should be newest first - Q6, Q5, Q4, Q3, Q2):")
+     for i, item in enumerate(recent_for_display):
+         ts = item.get('metadata',{}).get('timestamp_iso', item.get('created_at_unix'))
+         logger.info(f"  {i+1}. ID: {item.get('id')}, Timestamp: {ts}, Query: {item.get('query')[:20]}..., Summary in meta: {'synthesized_summary_text' in item.get('metadata', {})}")
+
+     stats2 = await mb.get_memory_stats()
+     logger.info(f"Memory Stats after storing: {stats2}")
+
+     exported_file = await mb.export_memory_to_file_async()
+     if exported_file: logger.info(f"Test export successful: {exported_file}")
+     else: logger.error("Test export failed.")
+     
+     logger.info("--- MemoryBank Test Complete ---")
+
+if __name__ == "__main__":
+     asyncio.run(main_test())

modules/model_manager_public.py

@@ -0,0 +1,401 @@
+# FILE: modules/model_manager_public.py
+
+import asyncio
+import logging
+import os
+import sys
+import time
+import threading
+from concurrent.futures import ThreadPoolExecutor, TimeoutError as FuturesTimeoutError
+from typing import Dict, Any, Optional, List, Callable, Coroutine
+
+# --- Llama.cpp Python Backend Import & Debug ---
+logger_import_debug = logging.getLogger("ModelManager_ImportDebug")
+if not logger_import_debug.handlers: # Minimal setup for this specific logger
+    _h = logging.StreamHandler(sys.stdout)
+    _f = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    _h.setFormatter(_f)
+    logger_import_debug.addHandler(_h)
+    logger_import_debug.setLevel(logging.INFO)
+
+# --- Start of FIX: Define LlamaMock unconditionally and manage Llama variable ---
+class LlamaMock:
+    def __init__(self, model_path: str = "mock_model_path", *args, **kwargs):
+        # Use logger_import_debug as it's defined at this point
+        logger_import_debug.error(f"LlamaMock initialized for model_path='{model_path}' with args: {args}, kwargs: {kwargs}. llama_cpp is not installed or importable.")
+        self.model_path = model_path
+        self.n_ctx_train = kwargs.get('n_ctx', 0) # Mock common attributes
+        self.metadata = {}
+
+    def create_chat_completion(self, messages: List[Dict[str,str]], *args, **kwargs) -> Dict[str, Any]:
+        logger_import_debug.error(f"LlamaMock: create_chat_completion called for '{self.model_path}', but llama_cpp is unavailable.")
+        return {
+            "id": "chatcmpl-mock", "object": "chat.completion", "created": int(time.time()),
+            "model": self.model_path,
+            "choices": [{"index": 0, "message": {"role": "assistant", "content": f"[Error: Llama.cpp backend not available for {self.model_path}]"}, "finish_reason": "stop"}],
+            "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+        }
+
+    def __call__(self, prompt: str, *args, **kwargs) -> Dict[str, Any]: # For older direct call style
+        logger_import_debug.error(f"LlamaMock: __call__ used for '{self.model_path}', but llama_cpp is unavailable.")
+        return {
+            "id": "cmpl-mock", "object": "text_completion", "created": int(time.time()),
+            "model": self.model_path,
+            "choices": [{"text": f"[Error: Llama.cpp backend not available for {self.model_path}]", "index": 0, "logprobs": None, "finish_reason": "stop"}],
+            "usage": {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+        }
+    
+    def get_metadata(self) -> Dict[str, Any]:
+        return self.metadata
+
+    def tokenizer(self) -> Any:
+        class MockTokenizer:
+            def encode(self, text: str) -> List[int]: return [0] * len(text)
+            def decode(self, tokens: List[int]) -> str: return "".join([chr(t) for t in tokens if t < 256]) # Simplistic
+        return MockTokenizer()
+
+# Initialize variables that will hold the class to be used
+Llama_imported_class: Any = LlamaMock  # Default to mock
+LlamaCppError_imported_class: Any = Exception  # Default to base Exception
+LLAMA_CPP_AVAILABLE: bool = False
+
+try:
+    from llama_cpp import Llama as RealLlama, LlamaCppError as RealLlamaCppSpecificError
+    Llama_imported_class = RealLlama
+    LlamaCppError_imported_class = RealLlamaCppSpecificError
+    LLAMA_CPP_AVAILABLE = True
+    logger_import_debug.info("🎉 Final llama-cpp-python status: AVAILABLE. Using REAL Llama class. Error catching for Llama.cpp specifics will use 'LlamaCppSpecificError'.")
+except ImportError:
+    logger_import_debug.warning("Could not import 'Llama' and 'LlamaCppSpecificError' from 'llama_cpp' directly. Trying simpler import...")
+    try:
+        from llama_cpp import Llama as RealLlamaOnly # Try again without specific error import (older versions)
+        Llama_imported_class = RealLlamaOnly
+        # LlamaCppError_imported_class remains Exception
+        LLAMA_CPP_AVAILABLE = True
+        logger_import_debug.warning("Note: 'LlamaCppError' not found at llama_cpp top-level. Using base 'Exception' for LlamaCpp errors.")
+        logger_import_debug.info("🎉 Final llama-cpp-python status: AVAILABLE (LlamaCppError not found). Using REAL Llama class.")
+    except ImportError:
+        # Llama_imported_class remains LlamaMock, LLAMA_CPP_AVAILABLE remains False
+        logger_import_debug.critical("CRITICAL FAILURE: Cannot import 'Llama' from 'llama_cpp': No module named 'llama_cpp'. Using LlamaMock. Model loading will fail for real models.")
+except Exception as e_import_general:
+    # Llama_imported_class remains LlamaMock, LLAMA_CPP_AVAILABLE remains False
+    logger_import_debug.critical(f"CRITICAL FAILURE: Unexpected error during 'llama_cpp' import: {e_import_general}. Using LlamaMock.", exc_info=True)
+
+# Assign to the names used throughout the rest of this module
+Llama = Llama_imported_class
+LlamaCppError = LlamaCppError_imported_class
+# --- End of FIX ---
+# --- End Llama.cpp Python Backend Import & Debug ---
+
+
+try:
+    # Assume config_settings_public.py is in the same 'modules' directory or project root is in sys.path
+    from modules.config_settings_public import (
+        MODEL_PATHS, MODEL_SPECIFIC_PARAMS, INFERENCE_PRESETS, N_CTX_FALLBACK, VERBOSE_LLAMA_CPP
+    )
+except ImportError as e_conf:
+    logging.critical(f"CRITICAL IMPORT ERROR in ModelManager: Cannot import from config_settings_public: {e_conf}")
+    # Provide minimal fallbacks if config cannot be loaded, though this is a critical failure
+    MODEL_PATHS = {}
+    MODEL_SPECIFIC_PARAMS = {"_default": {"n_ctx": 2048, "n_gpu_layers": -1, "verbose": False}}
+    INFERENCE_PRESETS = {"default": {"temperature": 0.7}}
+    N_CTX_FALLBACK = 2048
+    VERBOSE_LLAMA_CPP = False
+
+
+logger = logging.getLogger("ZOTHEOS_ModelManager")
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+# Timeout for model generation tasks when run in a thread
+GENERATION_THREAD_TIMEOUT_SECONDS = 300 # 5 minutes
+
+class ModelManager:
+    def __init__(self, device_preference: Optional[str] = "cuda", max_model_count: int = 1, max_ram_models_gb: float = 8.0):
+        self.device_preference = device_preference
+        self.loaded_models: Dict[str, Any] = {} # Stores Llama instances
+        self.model_load_status: Dict[str, str] = {} # "unloaded", "loading", "loaded", "error"
+        self.model_ram_estimate_gb: Dict[str, float] = {}
+        self.total_estimated_ram_gb: float = 0.0
+        self.max_model_count = max_model_count
+        self.max_ram_models_gb = max_ram_models_gb
+        self.model_load_order: List[str] = [] # Tracks order for LRU
+        self.model_locks: Dict[str, asyncio.Lock] = {} # Per-model lock for loading
+        self.executor = ThreadPoolExecutor(max_workers=max_model_count + 1, thread_name_prefix="LLM_Gen") # +1 for summarizer
+
+        dev_log = "CPU (default)"
+        if self.device_preference == "cuda":
+            # Check NVIDIA drivers and CUDA toolkit availability (conceptual)
+            try:
+                import torch
+                if torch.cuda.is_available():
+                    dev_log = f"CUDA (preference): {torch.cuda.get_device_name(0)}"
+                else:
+                    dev_log = "CUDA (preference, but torch.cuda.is_available()=False)"
+            except ImportError:
+                dev_log = "CUDA (preference, but PyTorch not found for detailed check)"
+            except Exception as e_cuda_check:
+                dev_log = f"CUDA (preference, error during torch check: {e_cuda_check})"
+        # Actual CUDA usage is determined by n_gpu_layers > 0 during Llama init
+
+        logger.info(f"🔥 MMgr init. Dev Preference: {dev_log}. MaxRAM Models: {self.max_ram_models_gb}GB. Max Count: {self.max_model_count}.")
+        if not LLAMA_CPP_AVAILABLE:
+            logger.critical("❌ Llama.cpp backend CRITICAL FAILURE: The 'Llama' class could not be imported from 'llama_cpp'. ModelManager cannot load GGUF models. Please check installation and logs from 'ModelManager_ImportDebug'.")
+        logger.info(f"✅ MMGR Config: Max Models: {self.max_model_count}, Max RAM: {self.max_ram_models_gb} GB.")
+
+    async def _ensure_model_loaded(self, model_name: str) -> bool:
+        if model_name not in self.model_locks:
+            self.model_locks[model_name] = asyncio.Lock()
+
+        async with self.model_locks[model_name]:
+            if self.model_load_status.get(model_name) == "loaded" and model_name in self.loaded_models:
+                if model_name in self.model_load_order: self.model_load_order.remove(model_name)
+                self.model_load_order.append(model_name) # Move to end of LRU
+                return True
+
+            if self.model_load_status.get(model_name) == "loading":
+                logger.info(f"Model '{model_name}' is already being loaded by another task. Waiting...")
+                while self.model_load_status.get(model_name) == "loading": await asyncio.sleep(0.5)
+                return self.model_load_status.get(model_name) == "loaded"
+
+            self.model_load_status[model_name] = "loading"
+            logger.info(f"Attempting to load model '{model_name}'...")
+
+            await self._evict_models_if_needed(new_model_name_to_load=model_name)
+
+            model_instance, ram_gb = await asyncio.to_thread(self._load_model_from_disk, model_name)
+            if model_instance:
+                self.loaded_models[model_name] = model_instance
+                self.model_ram_estimate_gb[model_name] = ram_gb
+                self.total_estimated_ram_gb += ram_gb
+                self.model_load_status[model_name] = "loaded"
+                if model_name in self.model_load_order: self.model_load_order.remove(model_name)
+                self.model_load_order.append(model_name)
+                logger.info(f"✅ Model '{model_name}' loaded successfully. RAM used by this model: {ram_gb:.2f}GB. Total est. RAM: {self.total_estimated_ram_gb:.2f}GB.")
+                return True
+            else:
+                self.model_load_status[model_name] = "error"
+                logger.error(f"❌ Failed to load model '{model_name}'.")
+                # Clean up RAM if an estimate was added prematurely or if partial load occurred
+                if model_name in self.model_ram_estimate_gb:
+                    self.total_estimated_ram_gb -= self.model_ram_estimate_gb.pop(model_name)
+                return False
+
+    def _load_model_from_disk(self, model_name: str) -> tuple[Optional[Any], float]:
+        # The check Llama == LlamaMock now works because LlamaMock is always defined
+        if not LLAMA_CPP_AVAILABLE or Llama == LlamaMock: # Llama is the variable pointing to the class
+            logger.error(f"Cannot load model '{model_name}': Llama.cpp backend not available (LLAMA_CPP_AVAILABLE={LLAMA_CPP_AVAILABLE}, Llama is LlamaMock: {Llama == LlamaMock}).")
+            return None, 0.0
+
+        model_path = MODEL_PATHS.get(model_name)
+        if not model_path or not os.path.exists(model_path):
+            logger.error(f"Model path for '{model_name}' not found or invalid: {model_path}")
+            return None, 0.0
+
+        specific_params = MODEL_SPECIFIC_PARAMS.get(model_name, {})
+        default_params = MODEL_SPECIFIC_PARAMS.get("_default", {})
+
+        load_params = default_params.copy()
+        load_params.update(specific_params)
+        load_params['model_path'] = model_path
+        load_params.setdefault('verbose', VERBOSE_LLAMA_CPP) # Use global verbose if not set per model
+
+        if 'n_ctx' not in load_params or load_params['n_ctx'] == 0: # Ensure n_ctx is valid
+            load_params['n_ctx'] = N_CTX_FALLBACK
+            logger.warning(f"n_ctx for model {model_name} was invalid or not found, using fallback: {N_CTX_FALLBACK}")
+
+        logger.info(f"🔄 Loading '{model_name}' from: {model_path}")
+        logger.debug(f"--- FINAL LOAD PARAMS FOR {model_name.upper()}: {load_params} ---")
+
+        start_time = time.perf_counter()
+        try:
+            model_instance = Llama(**load_params) # Llama here is the variable assigned above
+            load_time = time.perf_counter() - start_time
+            logger.info(f"✅ Model '{model_name}' (Llama instance) initialized by Llama(...). Load time: {load_time:.2f}s.")
+
+            ram_gb = os.path.getsize(model_path) / (1024**3)
+            ram_gb_with_buffer = ram_gb * 1.5 + 1 # Heuristic: file size + 50% + 1GB for KV cache, etc.
+            logger.info(f"Model '{model_name}' path: '{model_path}'. Est. RAM for this model (with buffer): {ram_gb_with_buffer:.2f}GB.")
+            return model_instance, ram_gb_with_buffer
+        except LlamaCppError as e_llama: # Catch specific LlamaCpp errors
+            logger.error(f"❌ LlamaCppError loading model '{model_name}': {e_llama}", exc_info=True)
+        except Exception as e:
+            logger.error(f"❌ Generic error loading model '{model_name}': {e}", exc_info=True)
+        return None, 0.0
+
+    async def _evict_models_if_needed(self, new_model_name_to_load: Optional[str] = None):
+        new_model_ram_gb_estimate = 0.0
+        if new_model_name_to_load:
+             model_path = MODEL_PATHS.get(new_model_name_to_load)
+             if model_path and os.path.exists(model_path):
+                 new_model_ram_gb_estimate = (os.path.getsize(model_path) / (1024**3)) * 1.5 + 1 # Same heuristic
+
+        # Check if eviction is needed:
+        # 1. If we are at max model count AND the new model isn't already loaded.
+        # 2. OR if adding the new model would exceed total RAM limit AND we have models loaded.
+        while (len(self.loaded_models) >= self.max_model_count and (new_model_name_to_load not in self.loaded_models)) or \
+              (self.total_estimated_ram_gb + new_model_ram_gb_estimate > self.max_ram_models_gb and self.model_load_order):
+            if not self.model_load_order:
+                logger.warning("Eviction needed but model_load_order is empty. This should not happen if loaded_models is populated.")
+                break
+
+            model_to_evict = self.model_load_order.pop(0) # Evict LRU
+            if model_to_evict in self.loaded_models:
+                logger.warning(f"⚠️ Evicting model '{model_to_evict}' due to resource limits (Count: {len(self.loaded_models)}/{self.max_model_count}, RAM: {self.total_estimated_ram_gb:.2f}/{self.max_ram_models_gb:.2f}GB).")
+                del self.loaded_models[model_to_evict] # Release model instance
+                evicted_ram = self.model_ram_estimate_gb.pop(model_to_evict, 0)
+                self.total_estimated_ram_gb -= evicted_ram
+                self.model_load_status[model_to_evict] = "unloaded"
+                logger.info(f"Model '{model_to_evict}' unloaded. RAM reclaimed: {evicted_ram:.2f}GB. Total est. RAM: {self.total_estimated_ram_gb:.2f}GB.")
+            else:
+                logger.warning(f"Model '{model_to_evict}' was in load order but not in loaded_models dict. Inconsistency detected.")
+
+
+    def _generation_task_sync(self, model_instance: Any, prompt_messages: List[Dict[str,str]], gen_params: Dict[str, Any]) -> str:
+        model_log_name = model_instance.model_path.split(os.sep)[-1] if hasattr(model_instance, 'model_path') else 'UnknownModel'
+        logger.debug(f"--- [{model_log_name}] ENTERING _generation_task_sync ---")
+        output_text = "[Error: Generation failed in thread]"
+        try:
+            completion = model_instance.create_chat_completion(messages=prompt_messages, **gen_params)
+            if completion and "choices" in completion and completion["choices"]:
+                message_content = completion["choices"][0].get("message", {}).get("content")
+                output_text = message_content.strip() if message_content else "[No content in choice message]"
+            else:
+                output_text = "[No choices in completion or completion is empty]"
+                logger.warning(f"[{model_log_name}] Malformed completion object: {completion}")
+            logger.debug(f"✅ [{model_log_name}] Sync generation successful. Preview: {output_text[:100].replace(chr(10),' ')}...")
+        except Exception as e:
+            logger.error(f"❌ [{model_log_name}] Exception during model generation in thread: {e}", exc_info=True)
+            output_text = f"[Error: Exception during generation - {type(e).__name__}: {str(e)[:100]}]"
+        logger.debug(f"--- [{model_log_name}] EXITING _generation_task_sync ---")
+        return output_text
+
+    async def async_generation_wrapper(self, model_instance: Any, prompt_messages: List[Dict[str,str]], gen_params: Dict[str, Any], model_name_for_log: str) -> str:
+        logger.debug(f"--- [{model_name_for_log}] ENTERING async_generation_wrapper ---")
+        output_str = f"[Error: Model '{model_name_for_log}' instance not available for generation]"
+        if not model_instance:
+            logger.error(f"[{model_name_for_log}] Model instance is None in async_generation_wrapper.")
+            return output_str
+        try:
+            output_str = await asyncio.wait_for(
+                asyncio.to_thread(self._generation_task_sync, model_instance, prompt_messages, gen_params),
+                timeout=GENERATION_THREAD_TIMEOUT_SECONDS + 10
+            )
+        except asyncio.TimeoutError:
+            logger.error(f"❌ [{model_name_for_log}] Generation task TIMED OUT in asyncio.wait_for (>{GENERATION_THREAD_TIMEOUT_SECONDS + 10}s).")
+            output_str = f"[Error: Generation timed out for model {model_name_for_log}]"
+        except Exception as e:
+            logger.error(f"❌ [{model_name_for_log}] Exception in async_generation_wrapper: {e}", exc_info=True)
+            output_str = f"[Error: Async wrapper exception for model {model_name_for_log} - {type(e).__name__}]"
+        logger.debug(f"--- [{model_name_for_log}] EXITING async_generation_wrapper ---")
+        return output_str
+
+
+    async def generate_with_model(self, model_name: str, prompt: str, preset_name: str = "default", system_prompt: Optional[str] = None) -> str:
+        logger.info(f"--- [{model_name}] Received generation request. System prompt: {'Yes' if system_prompt else 'No'}. Preset: {preset_name} ---")
+        # Check if Llama class is LlamaMock (meaning llama.cpp is not available)
+        if not LLAMA_CPP_AVAILABLE or Llama == LlamaMock:
+            logger.error(f"Cannot generate with model '{model_name}': Llama.cpp backend not available (LLAMA_CPP_AVAILABLE={LLAMA_CPP_AVAILABLE}, Llama is LlamaMock: {Llama == LlamaMock}).")
+            return "[Error: Llama.cpp backend core ('Llama' class) not available or is mocked]"
+
+        if not await self._ensure_model_loaded(model_name):
+            return f"[Error: Model '{model_name}' could not be loaded or is not available.]"
+
+        model_instance = self.loaded_models.get(model_name)
+        if not model_instance:
+            logger.error(f"Model '{model_name}' instance not found in loaded_models after successful _ensure_model_loaded. This is unexpected.")
+            return f"[Error: Model '{model_name}' instance unexpectedly not found after load attempt.]"
+
+        gen_params = INFERENCE_PRESETS.get(preset_name, INFERENCE_PRESETS.get("balanced", {"temperature": 0.7})).copy() # Fallback to "balanced" then hardcoded default
+
+        prompt_messages = []
+        if system_prompt and system_prompt.strip():
+            prompt_messages.append({"role": "system", "content": system_prompt})
+        prompt_messages.append({"role": "user", "content": prompt})
+
+        logger.debug(f"[{model_name}] Calling async_generation_wrapper with messages: {prompt_messages}, params: {gen_params}")
+        response_text = await self.async_generation_wrapper(model_instance, prompt_messages, gen_params, model_name)
+        logger.info(f"--- [{model_name}] Generation complete. Response length: {len(response_text)} ---")
+        return response_text
+
+    def get_loaded_model_stats(self) -> Dict[str, Any]:
+        return {
+            "loaded_model_count": len(self.loaded_models),
+            "total_ram_estimate_gb": round(self.total_estimated_ram_gb, 2),
+            "max_ram_models_gb": self.max_ram_models_gb,
+            "max_model_count": self.max_model_count,
+            "models_in_memory": list(self.loaded_models.keys()),
+            "load_order_lru": self.model_load_order, # LRU (oldest) to MRU (newest)
+            "model_ram_details_gb": {name: round(ram, 2) for name, ram in self.model_ram_estimate_gb.items()},
+            "model_load_status": self.model_load_status,
+            "llama_cpp_available": LLAMA_CPP_AVAILABLE,
+            "llama_class_is_mock": Llama == LlamaMock
+        }
+
+    def shutdown(self):
+        logger.info("🔌 Shutting down ModelManager...")
+        self.executor.shutdown(wait=True, cancel_futures=True) # Cancel pending futures on shutdown
+        self.loaded_models.clear()
+        self.model_ram_estimate_gb.clear()
+        self.model_load_order.clear()
+        self.model_load_status.clear()
+        self.total_estimated_ram_gb = 0
+        logger.info("✅ ModelManager shutdown complete.")
+
+# Example usage for direct testing
+async def main_model_manager_test():
+    # Configure logging for the test
+    logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+    # Set specific loggers to higher levels if too verbose
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    
+    logger.info("--- ModelManager Test ---")
+
+    if not MODEL_PATHS:
+        logger.error("MODEL_PATHS is empty. Cannot run test. Check config_settings_public.py")
+        return
+    if Llama == LlamaMock: # Check if we are using the mock
+        logger.warning("Llama.cpp is not available. Running test with LlamaMock. Responses will be mocked.")
+
+    # Example: max 2 models, 10GB RAM limit
+    mm = ModelManager(max_model_count=2, max_ram_models_gb=10.0)
+    
+    test_models_available = list(MODEL_PATHS.keys())
+    if not test_models_available:
+        logger.error("No models defined in MODEL_PATHS for testing.")
+        mm.shutdown()
+        return
+
+    # Select up to 3 models for testing, or fewer if not available
+    model1_name = test_models_available[0]
+    model2_name = test_models_available[1] if len(test_models_available) > 1 else model1_name
+    model3_name = test_models_available[2] if len(test_models_available) > 2 else model1_name
+    
+    test_queries = [
+        (model1_name, "What is the capital of France?", "precise", "You are a helpful geography expert."),
+        (model2_name, "Explain black holes simply.", "creative", None),
+        (model1_name, "What is 1+1?", "precise", None), # Query model1 again
+    ]
+    if len(test_models_available) > 2 and model3_name not in [model1_name, model2_name]: # Only add model3 if it's distinct and available
+        test_queries.append((model3_name, "Tell me a short joke.", "default", None))
+
+    for i, (model_name, query, preset, sys_prompt) in enumerate(test_queries):
+        logger.info(f"\n--- Test Query {i+1}: Model '{model_name}', Preset '{preset}' ---")
+        response = await mm.generate_with_model(model_name, query, preset_name=preset, system_prompt=sys_prompt)
+        print(f"Response from '{model_name}': {response[:150]}...") # Print more of the response
+        print(f"Stats after '{model_name}': {mm.get_loaded_model_stats()}")
+        await asyncio.sleep(1) # Small delay between queries
+
+    mm.shutdown()
+    logger.info("--- ModelManager Test Complete ---")
+
+if __name__ == "__main__":
+    # This allows testing ModelManager directly if needed
+    # Ensure your MODEL_PATHS in config_settings_public.py point to valid GGUF files
+    # To run: python -m modules.model_manager_public
+    asyncio.run(main_model_manager_test())

modules/plugin_manager_public.py

@@ -0,0 +1,80 @@
+import logging
+import asyncio
+from typing import Dict, Any, Type
+
+logger = logging.getLogger(__name__)
+
+# ✅ Define Pre-Approved Plugins (Only Trusted Plugins for Public Use)
+ALLOWED_PLUGINS = {
+    "basic_math": "BasicMathPlugin",  # Example of a basic utility plugin
+    "date_time": "DateTimePlugin"     # Example of a simple utility plugin
+}
+
+class PluginManager:
+    """🚀 Public Plugin Manager (Pre-Approved Plugins Only)"""
+
+    def __init__(self):
+        self.plugins: Dict[str, Any] = {}
+
+    async def load_plugin(self, plugin_name: str):
+        """✅ Load Pre-Approved Plugin."""
+        if plugin_name not in ALLOWED_PLUGINS:
+            logger.warning(f"⚠️ Plugin '{plugin_name}' is not available in the public version.")
+            return f"⚠️ Plugin '{plugin_name}' not allowed in public version."
+
+        if plugin_name in self.plugins:
+            logger.info(f"✅ Plugin '{plugin_name}' already loaded.")
+            return f"✅ Plugin '{plugin_name}' already loaded."
+
+        try:
+            # ✅ Use pre-defined plugin mappings for security
+            plugin_class = globals().get(ALLOWED_PLUGINS[plugin_name])
+            if plugin_class:
+                plugin_instance = plugin_class()
+                self.plugins[plugin_name] = plugin_instance
+                logger.info(f"✅ Plugin '{plugin_name}' loaded successfully.")
+                return f"✅ Plugin '{plugin_name}' loaded successfully."
+            else:
+                logger.error(f"❌ Plugin class '{plugin_name}' not found.")
+                return f"❌ Plugin class '{plugin_name}' not found."
+        except Exception as e:
+            logger.exception(f"❌ Error loading plugin '{plugin_name}': {e}")
+            return f"❌ Error loading plugin '{plugin_name}'."
+
+    async def execute_plugin_command(self, plugin_name: str, command: str, args: Dict[str, Any] = {}):
+        """✅ Execute Plugin Command (Predefined Only)."""
+        if plugin_name not in self.plugins:
+            logger.warning(f"⚠️ Attempt to execute command from unloaded plugin '{plugin_name}'.")
+            return f"⚠️ Plugin '{plugin_name}' not loaded."
+
+        plugin = self.plugins[plugin_name]
+        if hasattr(plugin, command):
+            method = getattr(plugin, command)
+            try:
+                if asyncio.iscoroutinefunction(method):
+                    return await method(**args)
+                return method(**args)
+            except Exception as e:
+                logger.error(f"❌ Error executing command '{command}' in plugin '{plugin_name}': {e}")
+                return f"❌ Error executing '{command}' in '{plugin_name}'."
+        else:
+            logger.warning(f"⚠️ Command '{command}' not found in plugin '{plugin_name}'.")
+            return f"⚠️ Command '{command}' not found in '{plugin_name}'."
+
+# ✅ Example Predefined Plugin Classes
+class BasicMathPlugin:
+    """Basic Math Plugin (Example)"""
+    
+    def add(self, x, y):
+        return x + y
+    
+    def subtract(self, x, y):
+        return x - y
+
+class DateTimePlugin:
+    """Date/Time Plugin (Example)"""
+    
+    async def current_time(self):
+        from datetime import datetime
+        return datetime.utcnow().isoformat()
+

modules/query_processor_public.py

@@ -0,0 +1,135 @@
+import asyncio
+import logging
+import torch
+from difflib import SequenceMatcher
+from time import time
+from typing import Dict, List, Tuple
+
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+from config_settings_public import MODEL_PATHS, MODEL_CONFIG, MODEL_WEIGHTS
+from model_manager_public import ModelManager
+from response_optimizer_public import ResponseOptimizer
+
+logger = logging.getLogger(__name__)
+
+
+class QueryProcessor:
+    def __init__(self, model_manager: ModelManager, response_optimizer: ResponseOptimizer):
+        self.model_manager = model_manager
+        self.response_optimizer = response_optimizer
+        self.model_paths = MODEL_PATHS
+        self.model_config = MODEL_CONFIG
+        self.memory_bank = []
+
+        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+        if torch.cuda.is_available():
+            torch.cuda.set_device(0)
+            torch.backends.cudnn.benchmark = True
+            torch.backends.cudnn.enabled = True
+            torch.set_float32_matmul_precision('high')
+            logger.info(f"✅ QueryProcessor initialized on {self.device}")
+        else:
+            logger.warning("⚠️ Running on CPU")
+
+        self.model_tiers = {
+            "balanced": ["gemma", "mistral", "llama"]
+        }
+
+    def select_models(self, query: str) -> List[str]:
+        return [m for m in self.model_tiers["balanced"] if m in self.model_paths]
+
+    async def process_query_with_fusion(self, query: str) -> str:
+        selected_models = self.select_models(query)
+        logger.info(f"🧠 Selected models: {selected_models}")
+
+        tasks = [asyncio.create_task(self.invoke_model(m, query)) for m in selected_models]
+        responses = await asyncio.gather(*tasks, return_exceptions=True)
+
+        valid_responses = {
+            m: r for m, r in zip(selected_models, responses)
+            if isinstance(r, str) and r.strip()
+        }
+
+        if not valid_responses:
+            logger.error("❌ All models failed or returned empty responses.")
+            return "⚠️ No valid responses received from models."
+
+        logger.info(f"✅ {len(valid_responses)} valid responses received.")
+        fused = await self.advanced_fusion(valid_responses, query)
+        self.memory_bank.append({"query": query, "response": fused, "timestamp": time()})
+        return fused
+
+    async def invoke_model(self, model_name: str, query: str) -> str:
+        try:
+            model = self.model_manager.loaded_models.get(model_name)
+            if not model:
+                model = self.model_manager.load_model_from_disk(model_name)
+                if not model:
+                    raise RuntimeError(f"Model '{model_name}' failed to load.")
+
+            config = self.model_config.get(model_name, {})
+            max_tokens = config.get("max_tokens", 800)
+            temperature = config.get("temperature", 0.7)
+
+            logger.info(f"🔧 Invoking '{model_name}' with temp={temperature}, max_tokens={max_tokens}")
+
+            with torch.no_grad():
+                completion = await asyncio.to_thread(
+                    model.create_completion,
+                    prompt=query,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    stop=["</s>", "User:", "Assistant:"]
+                )
+
+            response_text = completion.get("choices", [{}])[0].get("text", "").strip()
+            return response_text
+
+        except Exception as e:
+            logger.error(f"❌ Error in model '{model_name}': {e}")
+            return ""
+
+    def clean_response(self, raw) -> str:
+        if isinstance(raw, str):
+            return raw.strip()
+
+        if isinstance(raw, dict):
+            return raw.get("generated_text", "").strip() or raw.get("text", "").strip()
+
+        if isinstance(raw, list):
+            if isinstance(raw[0], dict) and "generated_text" in raw[0]:
+                return raw[0]["generated_text"].strip()
+            return " ".join(str(x).strip() for x in raw if isinstance(x, str))
+
+        return str(raw).strip()
+
+    async def advanced_fusion(self, responses: Dict[str, str], query: str) -> str:
+        cleaned = {m: self.clean_response(r) for m, r in responses.items()}
+        seen = set()
+        unique: List[Tuple[str, float, str]] = []
+
+        for model, text in cleaned.items():
+            if not text or any(self.is_similar(text, prev) for prev in seen):
+                continue
+            seen.add(text)
+            score = self.score_response(text, query)
+            unique.append((text, score, model))
+
+        if not unique:
+            return "⚠️ No high-quality content to merge."
+
+        unique.sort(key=lambda x: x[1], reverse=True)
+        best_responses = [await self.response_optimizer.optimize_response(t, query) for t, _, _ in unique[:3]]
+        return "\n---\n".join(best_responses).strip()
+
+    def is_similar(self, a: str, b: str, threshold: float = 0.9) -> bool:
+        return SequenceMatcher(None, a.strip().lower(), b.strip().lower()).ratio() > threshold
+
+    def score_response(self, response: str, query: str) -> float:
+        try:
+            tfidf = TfidfVectorizer().fit_transform([response, query])
+            return cosine_similarity(tfidf[0:1], tfidf[1:2])[0][0]
+        except:
+            return 0.5

modules/response_optimizer_public.py

@@ -0,0 +1,53 @@
+import logging
+from collections import defaultdict
+from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+class ResponseOptimizer:
+    """🚀 Public Response Optimizer (Basic Filtering + Length Control)"""
+
+    def __init__(self):
+        self.response_cache = {}  # Stores past responses to reduce redundant processing
+        self.optim_rules = defaultdict(list)  # Holds rule-based response refinements
+        self.cache_limit = 100  # ✅ Limit cache size to avoid overflow
+
+    async def optimize_response(self, response: str, context: Dict) -> str:
+        """✅ Optimizes AI-generated responses (Fast + Secure)."""
+
+        # ✅ Return cached response if available
+        if response in self.response_cache:
+            logger.info("✅ Returning cached optimized response.")
+            return self.response_cache[response]
+
+        # ✅ Apply context-based optimization (length, profanity)
+        optimized_response = self.apply_optimizations(response, context)
+
+        # ✅ Store in cache (Respect size limit)
+        if len(self.response_cache) >= self.cache_limit:
+            oldest_response = next(iter(self.response_cache))
+            del self.response_cache[oldest_response]
+
+        self.response_cache[response] = optimized_response
+        return optimized_response
+
+    def apply_optimizations(self, response: str, context: Dict) -> str:
+        """✅ Applies context-specific response optimization."""
+        if "filter_profanity" in context and context["filter_profanity"]:
+            response = self.remove_profanity(response)
+
+        if "trim_length" in context:
+            response = response[:context["trim_length"]].strip() + "..."  # Trims to desired length
+
+        return response
+
+    def remove_profanity(self, response: str) -> str:
+        """🚫 Removes flagged words from AI-generated responses."""
+        banned_words = [
+            "badword1", "badword2", "badword3", "shit", "fuck", "damn", "bitch", "asshole"
+        ]  # ✅ Add or remove based on testing
+
+        for word in banned_words:
+            response = response.replace(word, "***")  # ✅ Replace with censorship symbol
+
+        return response

modules/user_auth.py

@@ -0,0 +1,136 @@
+# FILE: modules/user_auth.py
+
+import json
+import os
+import sys 
+import logging
+
+logger = logging.getLogger("ZOTHEOS_UserAuth")
+if not logger.handlers:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - [%(funcName)s] - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+
+USERS_FILE_PATH = "stripe_users.json" # Default name, path will be determined below
+
+try:
+    if getattr(sys, 'frozen', False) and hasattr(sys, '_MEIPASS'):
+        # Running in a PyInstaller bundle
+        # _MEIPASS is the path to the temporary directory where PyInstaller unpacks files
+        application_path = sys._MEIPASS
+        logger.debug(f"UserAuth running in PyInstaller bundle. MEIPASS: {application_path}")
+        # stripe_users.json should be in the root of _MEIPASS, alongside the .exe's main script
+        candidate_path = os.path.join(application_path, "stripe_users.json")
+        # Check if it exists there directly
+        if os.path.exists(candidate_path):
+             USERS_FILE_PATH = candidate_path
+        else:
+            # Fallback: if user_auth.py is in a 'modules' subdir within _MEIPASS, try one level up for stripe_users.json
+            # This handles if --add-data "modules;modules" was used and user_auth.py is at _MEIPASS/modules/user_auth.py
+            # and stripe_users.json was added to _MEIPASS/.
+            # This might happen if the main script is also at the root of _MEIPASS.
+            current_module_dir = os.path.dirname(os.path.abspath(__file__)) # This would be _MEIPASS/modules
+            project_root_guess = os.path.dirname(current_module_dir) # This would be _MEIPASS
+            alt_candidate_path = os.path.join(project_root_guess, "stripe_users.json")
+            if os.path.exists(alt_candidate_path):
+                USERS_FILE_PATH = alt_candidate_path
+            else:
+                # If still not found, log a warning. The get_user_tier will handle the FileNotFoundError.
+                 logger.warning(f"stripe_users.json not found at primary bundle path '{candidate_path}' or alternate '{alt_candidate_path}'. It must be bundled at the root relative to the main script.")
+                 # Keep USERS_FILE_PATH as "stripe_users.json" to allow relative loading if script is at root of _MEIPASS
+                 # This will likely fail if not at root, and get_user_tier will default to 'free'
+    else:
+        # Running as a normal script (user_auth.py is in modules folder)
+        script_dir = os.path.dirname(os.path.abspath(__file__)) 
+        project_root = os.path.dirname(script_dir) 
+        USERS_FILE_PATH = os.path.join(project_root, "stripe_users.json")
+    
+    logger.info(f"User authentication file path dynamically set to: {os.path.abspath(USERS_FILE_PATH) if os.path.isabs(USERS_FILE_PATH) else USERS_FILE_PATH}")
+
+except Exception as e_path:
+    logger.error(f"Critical error setting USERS_FILE_PATH in user_auth.py: {e_path}. Using default 'stripe_users.json'.")
+    USERS_FILE_PATH = "stripe_users.json"
+
+
+def get_user_tier(user_token: str) -> str:
+    """
+    Retrieves the user's tier based on their token from stripe_users.json.
+    Defaults to 'free' if token not found or an error occurs.
+    """
+    default_tier = "free"
+    if not user_token or not isinstance(user_token, str) or not user_token.strip():
+        # This log is fine, but can be noisy if called frequently with no token (e.g. UI init)
+        # logger.debug("No user token provided or invalid token, defaulting to 'free' tier.")
+        return default_tier
+
+    try:
+        # Log the path being attempted for diagnosis
+        logger.debug(f"Attempting to load users file from: {os.path.abspath(USERS_FILE_PATH)}")
+        if not os.path.exists(USERS_FILE_PATH):
+            logger.warning(f"Users file '{USERS_FILE_PATH}' not found. Defaulting all users to '{default_tier}' tier. Please ensure this file is correctly bundled at the application root.")
+            return default_tier
+
+        with open(USERS_FILE_PATH, "r", encoding="utf-8") as f:
+            users = json.load(f)
+        
+        tier = users.get(user_token, default_tier)
+        log_token_display = user_token[:3] + "***" if len(user_token) > 3 else user_token
+        logger.info(f"Token '{log_token_display}' resolved to tier: '{tier}'.")
+        return tier
+    except json.JSONDecodeError:
+        logger.error(f"Error decoding JSON from {USERS_FILE_PATH}. Defaulting to '{default_tier}' tier.", exc_info=True)
+        return default_tier
+    except Exception as e:
+        logger.error(f"An unexpected error occurred in get_user_tier: {e}. Defaulting to '{default_tier}' tier.", exc_info=True)
+        return default_tier
+
+if __name__ == '__main__':
+    logger.setLevel(logging.DEBUG) 
+    print(f"--- Testing user_auth.py ---")
+    print(f"USERS_FILE_PATH is configured as: {os.path.abspath(USERS_FILE_PATH)}")
+
+    # Create a dummy stripe_users.json in the expected location for testing if it doesn't exist
+    # For standalone testing, this means it looks for it relative to where this script would be if it were project root.
+    # If this script is in 'modules', project_root is one level up.
+    
+    # Determine the correct test path based on whether script is run directly or from project root
+    if os.path.basename(os.getcwd()) == "modules": # If CWD is modules folder
+        test_stripe_users_path = "../stripe_users.json"
+    else: # If CWD is project root (where zotheos_interface_public.py is)
+        test_stripe_users_path = "stripe_users.json"
+
+    if not os.path.exists(test_stripe_users_path):
+        print(f"'{test_stripe_users_path}' not found relative to CWD ({os.getcwd()}). Creating a dummy file for testing purposes at this location.")
+        dummy_users_for_test = {
+            "TOKEN_FREE_USER": "free",
+            "TOKEN_STARTER_USER": "starter",
+            "TOKEN_PRO_USER": "pro"
+        }
+        try:
+            with open(test_stripe_users_path, "w") as f:
+                json.dump(dummy_users_for_test, f, indent=2)
+            print(f"Dummy '{test_stripe_users_path}' created successfully with test tokens.")
+            # Update USERS_FILE_PATH for this test run if it was different
+            USERS_FILE_PATH = test_stripe_users_path 
+            print(f"For this test run, USERS_FILE_PATH is now: {os.path.abspath(USERS_FILE_PATH)}")
+        except Exception as e_create:
+            print(f"Could not create dummy users file at {test_stripe_users_path}: {e_create}")
+            print("Please ensure stripe_users.json exists in the project root for user_auth.py to function correctly.")
+    
+    print("\nTest Results:")
+    test_tokens = {
+        "Pro User Token": "TOKEN_PRO_USER",
+        "Starter User Token": "TOKEN_STARTER_USER",
+        "Free User Token": "TOKEN_FREE_USER",
+        "Non-existent Token": "invalid_dummy_token_123",
+        "Empty String Token": "",
+    }
+
+    for description, token_to_test in test_tokens.items():
+        actual_tier = get_user_tier(token_to_test)
+        print(f"- Test '{description}' (Input: '{token_to_test}'): Tier = '{actual_tier}'")
+
+    print(f"\n--- End of user_auth.py test ---")