lollms-client 1.1.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

lollms_client/lollms_core.py

@@ -1458,75 +1458,36 @@ Provide your response as a single JSON object inside a JSON markdown tag. Use th
         streaming_callback: Optional[Callable[[str, 'MSG_TYPE', Optional[Dict], Optional[List]], bool]] = None,
         rag_top_k: int = 5,
         rag_min_similarity_percent: float = 50.0,
-        output_summarization_threshold: int = 500, # In tokens
+        output_summarization_threshold: int = 500,
         force_mcp_use: bool = False,
         debug: bool = False,
         **llm_generation_kwargs
     ) -> Dict[str, Any]:
-        """
-        Orchestrates a sophisticated and robust agentic process to generate a response.
-
-        This method employs a dynamic "observe-think-act" loop with several advanced architectural
-        patterns for improved robustness and efficiency, particularly when handling code.
-
-        Key Features:
-        - **Context-Aware Asset Ingestion**: The agent automatically detects if the `context`
-          parameter (representing the previous turn) contains code. If so, it registers that
-          code as an asset with a UUID, preventing the LLM from trying to paste large code
-          blocks into its prompts and avoiding JSON errors.
-        - **Tool Perception Filtering**: Identifies tools that directly consume code and HIDES
-          them from the LLM's view, forcing it to use the safer `generate_and_call` workflow.
-        - **Forced Safe Workflow**: The `generate_and_call` meta-tool is the ONLY way the agent
-          can execute code, ensuring a robust, error-free, and efficient process.
-        - **Verbose Internal Logging**: The `generate_and_call` tool is now fully instrumented
-          with detailed logging and robust error handling to ensure every failure is visible
-          and diagnosable, preventing silent loops.
-        
-        Args:
-            prompt: The user's initial prompt or question for the current turn.
-            context: An optional string containing the content of the previous turn.
-            use_mcps: Controls MCP tool usage.
-            use_data_store: Controls RAG usage.
-            system_prompt: Main system prompt for the final answer.
-            reasoning_system_prompt: System prompt for the decision-making process.
-            images: A list of base64-encoded images provided by the user for the current turn.
-            max_reasoning_steps: Maximum number of reasoning cycles.
-            decision_temperature: Temperature for LLM's decision-making.
-            final_answer_temperature: Temperature for final answer synthesis.
-            streaming_callback: Function for real-time output of tokens and steps.
-            rag_top_k: Number of top documents to retrieve during RAG.
-            rag_min_similarity_percent: Minimum similarity for RAG results.
-            output_summarization_threshold: Token count that triggers summarization.
-            force_mcp_use: If True, bypasses the "fast answer" check.
-            debug: If True, prints detailed prompting and response information.
-            **llm_generation_kwargs: Additional keyword arguments for LLM calls.
-
-        Returns:
-            A dictionary containing the agent's full run.
-        """
         if not self.llm:
             return {"final_answer": "", "tool_calls": [], "sources": [], "error": "LLM binding not initialized."}
         if max_reasoning_steps is None:
             max_reasoning_steps = 10
-        # --- Helper Functions ---
+
         def log_event(desc, event_type=MSG_TYPE.MSG_TYPE_CHUNK, meta=None, event_id=None) -> Optional[str]:
-            if not streaming_callback: return None
+            if not streaming_callback:
+                return None
             is_start = event_type == MSG_TYPE.MSG_TYPE_STEP_START
             event_id = str(uuid.uuid4()) if is_start and not event_id else event_id
             params = {"type": event_type, "description": desc, **(meta or {})}
-            if event_id: params["id"] = event_id
+            if event_id:
+                params["id"] = event_id
             streaming_callback(desc, event_type, params)
             return event_id
 
         def log_prompt(title: str, prompt_text: str):
-            if not debug: return
+            if not debug:
+                return
             ASCIIColors.cyan(f"** DEBUG: {title} **")
             ASCIIColors.magenta(prompt_text[-15000:])
             prompt_size = self.count_tokens(prompt_text)
             ASCIIColors.red(f"Prompt size:{prompt_size}/{self.llm.default_ctx_size}")
             ASCIIColors.cyan(f"** DEBUG: DONE **")
 
-        # --- 1. Initialize State & Context-Aware Asset Ingestion ---
         original_user_prompt, tool_calls_this_turn, sources_this_turn = prompt, [], []
         asset_store: Dict[str, Dict] = {}
         initial_state_parts = ["### Initial State", "- My goal is to address the user's request comprehensively."]
@@ -1541,121 +1502,314 @@ Provide your response as a single JSON object inside a JSON markdown tag. Use th
                 last_code_block = code_blocks[-1]
                 code_uuid = str(uuid.uuid4())
                 asset_store[code_uuid] = {"type": "code", "content": last_code_block}
-                initial_state_parts.append(f"- The user's request likely refers to a code block from the previous turn's context. It has been registered as asset ID: {code_uuid}")
+                initial_state_parts.append(f"- A code block was found in the context. It has been registered as asset ID: {code_uuid}")
         current_scratchpad = "\n".join(initial_state_parts)
 
-        # --- 2. Tool Discovery and Filtering ---
-        discovery_step_id = log_event("Discovering and filtering tools...", MSG_TYPE.MSG_TYPE_STEP_START)
-        all_discovered_tools, visible_tools, code_consuming_tools = [], [], set()
+        discovery_step_id = log_event("Discovering tools...", MSG_TYPE.MSG_TYPE_STEP_START)
+        all_discovered_tools, visible_tools = [], []
+        rag_registry: Dict[str, Callable] = {}
+        rag_tool_specs: Dict[str, Dict] = {}
+
         if use_mcps and hasattr(self, 'mcp'):
             mcp_tools = self.mcp.discover_tools(force_refresh=True)
-            if isinstance(use_mcps, list): all_discovered_tools.extend([t for t in mcp_tools if t["name"] in use_mcps])
-            elif use_mcps is True: all_discovered_tools.extend(mcp_tools)
-        code_param_keywords = {'code', 'script', 'python_code', 'javascript', 'html', 'css'}
-        for tool in all_discovered_tools:
-            if any(p in code_param_keywords for p in tool.get("input_schema", {}).get("properties", {})): code_consuming_tools.add(tool['name'])
-            else: visible_tools.append(tool)
+            if isinstance(use_mcps, list):
+                all_discovered_tools.extend([t for t in mcp_tools if t["name"] in use_mcps])
+            elif use_mcps is True:
+                all_discovered_tools.extend(mcp_tools)
+
         if use_data_store:
-            for name, info in use_data_store.items(): visible_tools.append({"name": f"research::{name}", "description": info.get("description", f"Queries '{name}'."), "input_schema": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}})
-        log_event(f"Made {len(visible_tools)} tools visible (hid {len(code_consuming_tools)} code tools).", MSG_TYPE.MSG_TYPE_STEP_END, meta={"visible": len(visible_tools), "hidden": len(code_consuming_tools), "hidden_list": list(code_consuming_tools)}, event_id=discovery_step_id)
+            for name, info in use_data_store.items():
+                tool_name = f"research::{name}"
+                description = f"Queries '{name}'."
+                call_fn = None
+                if callable(info):
+                    call_fn = info
+                elif isinstance(info, dict):
+                    if "call" in info and callable(info["call"]):
+                        call_fn = info["call"]
+                    description = info.get("description", description)
+                if call_fn:
+                    visible_tools.append({
+                        "name": tool_name,
+                        "description": description,
+                        "input_schema": {
+                            "type": "object",
+                            "properties": {
+                                "query": {"type": "string"},
+                                "top_k": {"type": "integer"},
+                                "min_similarity_percent": {"type": "number"},
+                                "filters": {"type": "object"}
+                            },
+                            "required": ["query"]
+                        }
+                    })
+                    rag_registry[tool_name] = call_fn
+                    rag_tool_specs[tool_name] = {"default_top_k": rag_top_k, "default_min_sim": rag_min_similarity_percent}
+                else:
+                    log_event("RAG tool registration failed", MSG_TYPE.MSG_TYPE_WARNING, meta={"store_name": name})
+
+        visible_tools.extend(all_discovered_tools)
+
+        built_in_tools = [
+            {"name": "local_tools::final_answer", "description": "Provide the final answer directly to the user.", "input_schema": {}},
+            {"name": "local_tools::request_clarification", "description": "Ask the user for more information.", "input_schema": {"type": "object", "properties": {"question_to_user": {"type": "string"}}, "required": ["question_to_user"]}}
+        ]
+
+        if getattr(self, "tti", None):
+            built_in_tools.append({
+                "name": "local_tools::generate_image",
+                "description": "Generate an image from a text description. Returns a base64-encoded image.",
+                "input_schema": {"type": "object", "properties": {"prompt": {"type": "string"}}, "required": ["prompt"]}
+            })
 
-        # --- 3. Fast Answer Path (Not shown for brevity, but retained) ---
-        
-        # --- 4. Format Tools for Main Loop ---
-        CODE_PLACEHOLDER = "{GENERATED_CODE}"
-        built_in_tools = [{"name": "local_tools::generate_and_call", "description": f"CRITICAL: To run or modify code, you MUST use this tool. It generates code (e.g., to fix code from an asset) and then calls a tool with it. Refer to existing code using its asset ID. Use '{CODE_PLACEHOLDER}' in `next_tool_params` for the NEWLY generated code.", "input_schema": { "type": "object", "properties": { "code_generation_prompt": {"type": "string"}, "language": {"type": "string"}, "next_tool_name": {"type": "string"}, "next_tool_params": {"type": "object"}}, "required": ["code_generation_prompt", "next_tool_name", "next_tool_params"]}}, {"name": "local_tools::refactor_scratchpad", "description": "Rewrites the scratchpad.", "input_schema": {}}, {"name": "local_tools::request_clarification", "description": "Asks the user for more information.", "input_schema": {"type": "object", "properties": {"question_to_user": {"type": "string"}}, "required": ["question_to_user"]}}, {"name": "local_tools::final_answer", "description": "Provides the final answer.", "input_schema": {}}]
         all_visible_tools = visible_tools + built_in_tools
         formatted_tools_list = "\n".join([f"**{t['name']}**:\n- Description: {t['description']}" for t in all_visible_tools])
+        log_event(
+            f"Made {len(all_visible_tools)} tools visible.",
+            MSG_TYPE.MSG_TYPE_STEP_END,
+            meta={"visible": len(all_visible_tools), "rag_tools": list(rag_registry.keys())},
+            event_id=discovery_step_id
+        )
 
-        # --- 5. Dynamic Reasoning Loop ---
         for i in range(max_reasoning_steps):
             reasoning_step_id = log_event(f"Reasoning Step {i+1}/{max_reasoning_steps}", MSG_TYPE.MSG_TYPE_STEP_START)
             try:
-                reasoning_prompt = f"""--- AVAILABLE ACTIONS ---\n{formatted_tools_list}\n\n--- YOUR INTERNAL SCRATCHPAD ---\n{current_scratchpad}\n--- END SCRATCHPAD ---\n\n**INSTRUCTIONS:**\n1. **OBSERVE:** Review your scratchpad, especially available asset IDs.\n2. **THINK:** Based on '{original_user_prompt}', what is the single next logical action using ONLY the available actions?\n3. **ACT:** Formulate your decision as a JSON object. Do NOT paste large code blocks into parameters; use their asset IDs instead."""
-                action_schema = {"thought": "My reasoning.", "action": {"tool_name": "string", "tool_params": "object"}}
-                action_data = self.generate_structured_content(prompt=reasoning_prompt, schema=action_schema, system_prompt=reasoning_system_prompt, temperature=decision_temperature, **llm_generation_kwargs)
-                
-                if not action_data or not isinstance(action_data.get("action"), dict):
-                    log_event("Failed to generate a valid JSON action. Will retry.", MSG_TYPE.MSG_TYPE_WARNING, event_id=reasoning_step_id)
-                    current_scratchpad += "\n\n### Step Failure\n- **Error:** Failed to produce a valid JSON action."
+                reasoning_prompt = f"""--- AVAILABLE ACTIONS ---
+{formatted_tools_list}
+
+--- YOUR INTERNAL SCRATCHPAD ---
+{current_scratchpad}
+--- END SCRATCHPAD ---
+
+INSTRUCTIONS:
+1) OBSERVE the scratchpad and available assets.
+2) THINK what is the single best next action to progress toward the user's goal: "{original_user_prompt}".
+3) ACT: Produce only this JSON:
+
+{{
+  "thought": "short, concrete reasoning",
+  "action": {{
+    "tool_name": "string",
+    "requires_code_input": true/false,
+    "requires_image_input": true/false
+  }}
+}}
+
+You may choose "local_tools::final_answer" to answer directly without tools.
+"""
+                log_prompt("Decision Prompt", reasoning_prompt)
+                decision_schema = {
+                    "thought": "My reasoning.",
+                    "action": {"tool_name": "string", "requires_code_input": "boolean", "requires_image_input": "boolean"}
+                }
+                decision_data = self.generate_structured_content(
+                    prompt=reasoning_prompt,
+                    schema=decision_schema,
+                    system_prompt=reasoning_system_prompt,
+                    temperature=decision_temperature,
+                    **llm_generation_kwargs
+                )
+                if not decision_data or not isinstance(decision_data.get("action"), dict):
+                    log_event("Invalid decision JSON", MSG_TYPE.MSG_TYPE_WARNING, meta={"decision_raw": str(decision_data)}, event_id=reasoning_step_id)
+                    current_scratchpad += "\n\n### Step Failure\n- Error: Invalid decision JSON."
                     continue
 
-                thought, action = action_data.get("thought", ""), action_data.get("action", {})
-                tool_name, tool_params = action.get("tool_name"), action.get("tool_params", {})
+                thought, action = decision_data.get("thought", ""), decision_data.get("action", {})
+                tool_name = action.get("tool_name")
+                requires_code = action.get("requires_code_input", False)
+                requires_image = action.get("requires_image_input", False)
                 current_scratchpad += f"\n\n### Step {i+1}: Thought\n{thought}"
-                log_event(thought, MSG_TYPE.MSG_TYPE_THOUGHT_CONTENT)
+                log_event("Decision taken", MSG_TYPE.MSG_TYPE_STEP, meta={"tool_name": tool_name, "requires_code": requires_code, "requires_image": requires_image})
 
-                if tool_name == "local_tools::final_answer": break
+                if tool_name == "local_tools::final_answer":
+                    break
                 if tool_name == "local_tools::request_clarification":
-                    return {"final_answer": tool_params.get("question_to_user", "?"), "final_scratchpad": current_scratchpad, "tool_calls": tool_calls_this_turn, "sources": sources_this_turn, "clarification_required": True, "error": None}
+                    return {
+                        "final_answer": decision_data.get("question_to_user", "?"),
+                        "final_scratchpad": current_scratchpad,
+                        "tool_calls": tool_calls_this_turn,
+                        "sources": sources_this_turn,
+                        "clarification_required": True,
+                        "error": None
+                    }
 
-                tool_result = {"status": "failure", "error": f"Tool '{tool_name}' was called but did not execute properly."} # Default error
-                if tool_name == "local_tools::generate_and_call":
-                    chain_id = log_event(f"Starting chained tool call...", MSG_TYPE.MSG_TYPE_STEP_START)
-                    try:
-                        code_gen_prompt, lang = tool_params.get("code_generation_prompt", ""), tool_params.get("language", "python")
-                        next_tool_name, next_tool_params = tool_params.get("next_tool_name"), tool_params.get("next_tool_params", {})
-                        log_event("Received parameters for chain", MSG_TYPE.MSG_TYPE_STEP, meta={"parent_id": chain_id, "params": tool_params})
-
-                        if not (use_mcps and hasattr(self, 'mcp')):
-                            tool_result = {"status": "failure", "error": "MCPs are not enabled, cannot execute tools."}
-                        elif next_tool_name not in code_consuming_tools:
-                            tool_result = {"status": "failure", "error": f"Tool '{next_tool_name}' is not a valid code-consuming tool. Valid options are: {list(code_consuming_tools)}"}
-                        else:
-                            def _hydrate(text: str, store: Dict) -> str:
-                                for k, v in store.items(): text = text.replace(k, v.get('content',''))
-                                return text
-                            hydrated_prompt = _hydrate(code_gen_prompt, asset_store)
-                            log_event(f"Generating {lang} code for {next_tool_name}", MSG_TYPE.MSG_TYPE_STEP, meta={"parent_id": chain_id, "hydrated_prompt": hydrated_prompt})
-                            generated_code = self.generate_code(prompt=hydrated_prompt, system_prompt=f"Generate ONLY raw {lang} code.", **llm_generation_kwargs)
-                            
-                            def _substitute(data: Any) -> Any:
-                                if isinstance(data, dict): return {k: _substitute(v) for k, v in data.items()}
-                                if isinstance(data, list): return [_substitute(item) for item in data]
-                                if isinstance(data, str) and data == CODE_PLACEHOLDER: return generated_code
-                                return data
-                            hydrated_params = _substitute(next_tool_params)
-                            
-                            log_event(f"Calling tool: {next_tool_name}", MSG_TYPE.MSG_TYPE_TOOL_CALL, meta={"parent_id": chain_id, "name": next_tool_name, "parameters": hydrated_params})
-                            tool_result = self.mcp.execute_tool(next_tool_name, hydrated_params, lollms_client_instance=self)
-                    except Exception as e:
-                        tool_result = {"status": "failure", "error": f"Exception in chained tool logic: {str(e)}"}
-                    log_event(f"Finished chained tool call.", MSG_TYPE.MSG_TYPE_STEP_END, event_id=chain_id)
-                # ... other non-code tool handlers ...
-
-                # --- Process and Sanitize ALL Tool Outputs for the Scratchpad ---
-                sanitized_result = {}
-                if isinstance(tool_result, dict):
-                    sanitized_result = tool_result.copy()
-                    for key, value in tool_result.items():
-                        if isinstance(value, str) and value.startswith("data:image"):
-                            img_uuid = str(uuid.uuid4())
-                            asset_store[img_uuid] = {"type": "image", "content": value}
-                            sanitized_result[key] = f"[Image asset generated: {img_uuid}]"
+                prepared_assets = {}
+                if requires_code:
+                    code_prompt = f"""--- ORIGINAL USER REQUEST ---
+"{original_user_prompt}"
+
+--- YOUR INTERNAL SCRATCHPAD ---
+{current_scratchpad}
+--- END SCRATCHPAD ---
+
+INSTRUCTIONS:
+Generate raw code only, with no explanations. The code must be self-contained and directly address the current next action."""
+                    log_prompt("Code Generation Prompt", code_prompt)
+                    generated_code = self.generate_code(prompt=code_prompt, system_prompt="Generate ONLY raw code.", **llm_generation_kwargs)
+                    code_uuid = str(uuid.uuid4())
+                    asset_store[code_uuid] = {"type": "code", "content": generated_code}
+                    prepared_assets["code_asset_id"] = code_uuid
+                    log_event("Code asset created", MSG_TYPE.MSG_TYPE_STEP, meta={"code_asset_id": code_uuid, "code_len": len(generated_code) if isinstance(generated_code, str) else None})
+
+                if requires_image:
+                    for img_b64 in images or []:
+                        img_uuid = str(uuid.uuid4())
+                        asset_store[img_uuid] = {"type": "image", "content": img_b64}
+                        prepared_assets.setdefault("image_asset_ids", []).append(img_uuid)
+                    log_event("Image assets prepared", MSG_TYPE.MSG_TYPE_STEP, meta={"image_asset_ids": prepared_assets.get("image_asset_ids", [])})
+
+                param_prompt = f"""--- SELECTED TOOL ---
+{tool_name}
+
+--- AVAILABLE ASSETS ---
+code_asset_id: {prepared_assets.get("code_asset_id","<none>")}
+image_asset_ids: {prepared_assets.get("image_asset_ids","<none>")}
+
+--- ORIGINAL USER REQUEST ---
+"{original_user_prompt}"
+
+--- YOUR INTERNAL SCRATCHPAD ---
+{current_scratchpad}
+--- END SCRATCHPAD ---
+
+INSTRUCTIONS:
+Fill the parameters for the selected tool. If code is required, do not paste code; use the code asset ID string exactly. If images are required, use the provided image asset IDs. Output only:
+
+{{
+  "tool_params": {{...}}
+}}
+"""
+                log_prompt("Parameter Generation Prompt", param_prompt)
+                param_schema = {"tool_params": "object"}
+                param_data = self.generate_structured_content(
+                    prompt=param_prompt,
+                    schema=param_schema,
+                    system_prompt=reasoning_system_prompt,
+                    temperature=decision_temperature,
+                    **llm_generation_kwargs
+                )
+                tool_params = {}
+                if param_data and isinstance(param_data.get("tool_params"), dict):
+                    tool_params = param_data["tool_params"]
                 else:
-                    sanitized_result = {"raw_output": str(tool_result)}
-                
+                    log_event("Parameter generation returned empty", MSG_TYPE.MSG_TYPE_WARNING, meta={"param_raw": str(param_data)})
+
+                def _hydrate(data: Any, store: Dict) -> Any:
+                    if isinstance(data, dict):
+                        return {k: _hydrate(v, store) for k, v in data.items()}
+                    if isinstance(data, list):
+                        return [_hydrate(item, store) for item in data]
+                    if isinstance(data, str) and data in store:
+                        return store[data].get("content", data)
+                    return data
+
+                hydrated_params = _hydrate(tool_params, asset_store)
+                log_event("Hydrated parameters", MSG_TYPE.MSG_TYPE_STEP, meta={"tool_name": tool_name})
+
+                tool_result = {"status": "failure", "error": f"Tool '{tool_name}' failed."}
+                try:
+                    if tool_name == "local_tools::generate_image":
+                        prompt_for_img = hydrated_params.get("prompt", "")
+                        log_event("TTI call start", MSG_TYPE.MSG_TYPE_STEP, meta={"tool_name": tool_name})
+                        image_bytes = self.tti.generate_image(prompt=prompt_for_img)
+                        if not image_bytes:
+                            raise Exception("TTI binding returned empty image data.")
+                        b64_image = base64.b64encode(image_bytes).decode("utf-8")
+                        img_uuid = str(uuid.uuid4())
+                        asset_store[img_uuid] = {"type": "image", "content": f"data:image/png;base64,{b64_image}"}
+                        tool_result = {"status": "success", "image_asset": img_uuid, "html_tag": f"<img src='data:image/png;base64,{b64_image}' alt='Generated Image'/>"}
+                        log_event("TTI call success", MSG_TYPE.MSG_TYPE_STEP, meta={"image_asset": img_uuid})
+                    elif tool_name in rag_registry:
+                        query = hydrated_params.get("query", "")
+                        top_k = int(hydrated_params.get("top_k", rag_tool_specs[tool_name]["default_top_k"]))
+                        min_sim = float(hydrated_params.get("min_similarity_percent", rag_tool_specs[tool_name]["default_min_sim"]))
+                        filters = hydrated_params.get("filters", None)
+                        log_event("RAG call start", MSG_TYPE.MSG_TYPE_STEP, meta={"tool_name": tool_name, "query": query, "top_k": top_k, "min_similarity_percent": min_sim, "has_filters": bool(filters)})
+                        rag_fn = rag_registry[tool_name]
+                        try:
+                            raw_results = rag_fn(query=query, top_k=top_k, filters=filters)
+                        except TypeError:
+                            raw_results = rag_fn(query)
+                        docs = []
+                        if isinstance(raw_results, dict) and "results" in raw_results:
+                            raw_iter = raw_results["results"]
+                        else:
+                            raw_iter = raw_results
+                        for d in raw_iter or []:
+                            text = d.get("text") if isinstance(d, dict) else str(d)
+                            score = d.get("score", 0.0) if isinstance(d, dict) else 0.0
+                            meta = d.get("metadata", {}) if isinstance(d, dict) else {}
+                            pct = score * 100.0 if score <= 1.0 else score
+                            docs.append({"text": text, "score": pct, "metadata": meta})
+                        docs.sort(key=lambda x: x.get("score", 0.0), reverse=True)
+                        kept = [x for x in docs if x.get("score", 0.0) >= min_sim][:top_k]
+                        dropped = len(docs) - len(kept)
+                        tool_result = {"status": "success", "results": kept, "dropped": dropped, "min_similarity_percent": min_sim, "top_k": top_k}
+                        sources_this_turn.extend([{"source": tool_name, "metadata": x.get("metadata", {}), "score": x.get("score", 0.0)} for x in kept])
+                        snippet_preview = [{"score": x["score"], "text": (x["text"][:200] + "…") if isinstance(x["text"], str) and len(x["text"]) > 200 else x["text"]} for x in kept]
+                        log_event("RAG call end", MSG_TYPE.MSG_TYPE_STEP_END, meta={"tool_name": tool_name, "kept": len(kept), "dropped": dropped, "preview": snippet_preview})
+                        rag_notes = "\n".join([f"- [{idx+1}] score={x['score']:.1f}% | {x['text'][:500]}" for idx, x in enumerate(kept)])
+                        current_scratchpad += f"\n\n### RAG Notes ({tool_name})\n{rag_notes if rag_notes else '- No results above threshold.'}"
+                    elif hasattr(self, "mcp"):
+                        log_event("MCP tool call start", MSG_TYPE.MSG_TYPE_STEP, meta={"tool_name": tool_name})
+                        tool_result = self.mcp.execute_tool(tool_name, hydrated_params, lollms_client_instance=self)
+                        log_event("MCP tool call end", MSG_TYPE.MSG_TYPE_STEP_END, meta={"tool_name": tool_name})
+                    else:
+                        tool_result = {"status": "failure", "error": "No MCP instance available and tool is not RAG/TTI."}
+                except Exception as e:
+                    tool_result = {"status": "failure", "error": str(e)}
+                    log_event("Tool call exception", MSG_TYPE.MSG_TYPE_EXCEPTION, meta={"tool_name": tool_name, "error": str(e)})
+
+                sanitized_result = tool_result.copy() if isinstance(tool_result, dict) else {"raw_output": str(tool_result)}
                 observation_text = f"```json\n{json.dumps(sanitized_result, indent=2)}\n```"
-                log_event(f"Received output from: {tool_name}", MSG_TYPE.MSG_TYPE_TOOL_OUTPUT, meta={"name": tool_name, "result": sanitized_result})
                 tool_calls_this_turn.append({"name": tool_name, "params": tool_params, "result": tool_result})
-                current_scratchpad += f"\n\n### Step {i+1}: Observation\n- **Action:** Called `{tool_name}`\n- **Result:**\n{observation_text}"
-                log_event(f"Finished reasoning step {i+1}", MSG_TYPE.MSG_TYPE_STEP_END, event_id=reasoning_step_id)
+                current_scratchpad += f"\n\n### Step {i+1}: Observation\n- Action: `{tool_name}`\n- Result:\n{observation_text}"
+                log_event("Observation recorded", MSG_TYPE.MSG_TYPE_TOOL_OUTPUT, meta={"tool_name": tool_name})
 
+                log_event(f"Finished reasoning step {i+1}", MSG_TYPE.MSG_TYPE_STEP_END, event_id=reasoning_step_id)
             except Exception as ex:
                 trace_exception(ex)
-                log_event(f"Error in reasoning loop: {str(ex)}", MSG_TYPE.MSG_TYPE_EXCEPTION, event_id=reasoning_step_id)
-        
-        # --- 6. Final Answer Synthesis ---
+                log_event("Error in reasoning loop", MSG_TYPE.MSG_TYPE_EXCEPTION, meta={"error": str(ex)}, event_id=reasoning_step_id)
+
         synthesis_id = log_event("Synthesizing final answer...", MSG_TYPE.MSG_TYPE_STEP_START)
-        final_answer_prompt = f"""--- Original User Request ---\n"{original_user_prompt}"\n\n--- Your Internal Scratchpad ---\n{current_scratchpad}\n\n--- INSTRUCTIONS ---\nSynthesize a clear, comprehensive, and friendly answer for the user based ONLY on your scratchpad."""
+        final_answer_prompt = f"""--- ORIGINAL USER REQUEST ---
+"{original_user_prompt}"
+
+--- YOUR INTERNAL SCRATCHPAD ---
+{current_scratchpad}
+--- END SCRATCHPAD ---
+
+INSTRUCTIONS:
+Synthesize a clear, comprehensive, and friendly answer for the user based ONLY on your scratchpad. If relevant images were generated, refer to them naturally. Keep the answer concise but complete."""
         final_synthesis_images = [img for img in (images or [])] + [asset['content'] for asset in asset_store.values() if asset['type'] == 'image']
-        final_answer_text = self.generate_text(prompt=final_answer_prompt, system_prompt=system_prompt, images=final_synthesis_images, stream=streaming_callback is not None, streaming_callback=streaming_callback, temperature=final_answer_temperature, **llm_generation_kwargs)
+        log_prompt("Final Synthesis Prompt", final_answer_prompt)
+        final_answer_text = self.generate_text(
+            prompt=final_answer_prompt,
+            system_prompt=system_prompt,
+            images=final_synthesis_images,
+            stream=streaming_callback is not None,
+            streaming_callback=streaming_callback,
+            temperature=final_answer_temperature,
+            **llm_generation_kwargs
+        )
         if isinstance(final_answer_text, dict) and "error" in final_answer_text:
             return {"final_answer": "", "final_scratchpad": current_scratchpad, "tool_calls": tool_calls_this_turn, "sources": sources_this_turn, "clarification_required": False, "error": final_answer_text["error"]}
+
         final_answer = self.remove_thinking_blocks(final_answer_text)
+        for asset_id, asset in asset_store.items():
+            if asset["type"] == "image" and isinstance(asset.get("content"), str) and asset["content"].startswith("data:image"):
+                final_answer += f"\n\n<img src='{asset['content']}' alt='Generated Image'/>"
+
         log_event("Finished synthesizing answer.", MSG_TYPE.MSG_TYPE_STEP_END, event_id=synthesis_id)
 
-        return {"final_answer": final_answer, "final_scratchpad": current_scratchpad, "tool_calls": tool_calls_this_turn, "sources": sources_this_turn, "clarification_required": False, "error": None}
+        return {
+            "final_answer": final_answer,
+            "final_scratchpad": current_scratchpad,
+            "tool_calls": tool_calls_this_turn,
+            "sources": sources_this_turn,
+            "clarification_required": False,
+            "error": None
+        }
 
     def generate_code(
                         self,