lollms-client 0.19.9__py3-none-any.whl → 0.20.1__py3-none-any.whl

examples/external_mcp.py

@@ -0,0 +1,267 @@
+# File: run_lollms_client_with_mcp_example.py
+
+import sys
+import os
+import shutil
+from pathlib import Path
+import json
+import subprocess
+from dotenv import load_dotenv # Import the function
+
+# --- Load environment variables from .env file ---
+# Load from .env in the current script's directory, or from project root if specified
+# You can specify a path: load_dotenv(dotenv_path=Path('.') / '.env')
+# By default, it looks for .env in the current working directory or parent directories.
+# For simplicity, let's assume .env is next to this script or in a discoverable location.
+load_dotenv()
+
+# --- Python Path Adjustment (same as before) ---
+current_script_dir = Path(__file__).resolve().parent
+project_root_for_lollms_client = current_script_dir.parent
+if str(project_root_for_lollms_client) not in sys.path:
+    sys.path.insert(0, str(project_root_for_lollms_client))
+    print(f"Added to sys.path: {project_root_for_lollms_client}")
+
+# --- Pipmaster and LollmsClient Core Imports (same as before) ---
+try:
+    import pipmaster as pm
+except ImportError:
+    print("ERROR: pipmaster is not installed or not in PYTHONPATH.")
+    sys.exit(1)
+
+try:
+    from lollms_client import LollmsClient
+    from lollms_client.lollms_llm_binding import LollmsLLMBinding
+    from ascii_colors import ASCIIColors, trace_exception
+    from lollms_client.lollms_types import MSG_TYPE
+except ImportError as e:
+    print(f"ERROR: Could not import LollmsClient components: {e}")
+    trace_exception(e)
+    sys.exit(1)
+
+
+# --- Dummy Server Scripts (Time and Calculator - same as before) ---
+TIME_SERVER_PY = """
+import asyncio
+from datetime import datetime
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("TimeMCP", description="A server that provides the current time.")
+
+@mcp_server.tool(description="Returns the current server time and echoes received parameters.")
+def get_current_time(user_id: str = "unknown_user") -> dict:
+    return {"time": datetime.now().isoformat(), "params_received": {"user_id": user_id}, "server_name": "TimeServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+CALCULATOR_SERVER_PY = """
+import asyncio
+from typing import List, Union
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("CalculatorMCP", description="A server that performs addition.")
+
+@mcp_server.tool(description="Adds a list of numbers provided in the 'numbers' parameter.")
+def add_numbers(numbers: List[Union[int, float]]) -> dict:
+    if not isinstance(numbers, list) or not all(isinstance(x, (int, float)) for x in numbers):
+        return {"error": "'numbers' must be a list of numbers."}
+    return {"sum": sum(numbers), "server_name": "CalculatorServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+# --- Main Function ---
+def main():
+    ASCIIColors.red("--- Example: Using LollmsClient with StandardMCPBinding (including external ElevenLabs MCP) ---")
+
+    # --- 1. Setup Temporary Directory for Dummy MCP Servers ---
+    example_base_dir = Path(__file__).parent / "temp_mcp_example_servers"
+    if example_base_dir.exists():
+        shutil.rmtree(example_base_dir)
+    example_base_dir.mkdir(exist_ok=True)
+
+    time_server_script_path = example_base_dir / "time_server.py"
+    with open(time_server_script_path, "w") as f: f.write(TIME_SERVER_PY)
+
+    calculator_server_script_path = example_base_dir / "calculator_server.py"
+    with open(calculator_server_script_path, "w") as f: f.write(CALCULATOR_SERVER_PY)
+
+    # --- 2. MCP Configuration ---
+    initial_mcp_servers = {
+        "time_machine": {
+            "command": [sys.executable, str(time_server_script_path.resolve())],
+        },
+        "calc_unit": {
+            "command": [sys.executable, str(calculator_server_script_path.resolve())]
+        }
+    }
+
+    # --- Configuration for ElevenLabs MCP Server (Optional) ---
+    # Variables are now loaded from .env by load_dotenv() at the start of the script
+    elevenlabs_api_key = os.getenv("ELEVENLABS_API_KEY")
+    elevenlabs_voice_id_from_env = os.getenv("ELEVENLABS_VOICE_ID", "Rachel") # Default if not in .env
+    elevenlabs_model_id_from_env = os.getenv("ELEVENLABS_MODEL_ID", "eleven_multilingual_v2") # Default
+
+    uvx_available = False
+    try:
+        subprocess.run(["uvx", "--version"], capture_output=True, check=True, text=True, timeout=5)
+        uvx_available = True
+        ASCIIColors.green("uvx command is available.")
+    except (FileNotFoundError, subprocess.CalledProcessError, subprocess.TimeoutExpired):
+        ASCIIColors.yellow("uvx command not found, not working, or timed out. ElevenLabs MCP server (via uvx) will not be configured.")
+
+    if elevenlabs_api_key and uvx_available:
+        ASCIIColors.green("ELEVENLABS_API_KEY found (from .env) and uvx available. Configuring ElevenLabs MCP server.")
+        initial_mcp_servers["elevenlabs"] = {
+            "command": ["uvx"],
+            "args": ["elevenlabs-mcp-server"],
+            "env": {
+                "ELEVENLABS_API_KEY": elevenlabs_api_key,
+                "ELEVENLABS_VOICE_ID": elevenlabs_voice_id_from_env,
+                "ELEVENLABS_MODEL_ID": elevenlabs_model_id_from_env,
+                "ELEVENLABS_OUTPUT_DIR": str(example_base_dir / "elevenlabs_output")
+                # Add other ELEVENLABS_ env vars from os.getenv() if needed
+            }
+        }
+        (example_base_dir / "elevenlabs_output").mkdir(exist_ok=True)
+    elif not elevenlabs_api_key:
+        ASCIIColors.yellow("ELEVENLABS_API_KEY not found in .env file or environment variables. Skipping ElevenLabs MCP server configuration.")
+    
+    mcp_config = {"initial_servers": initial_mcp_servers}
+
+    # --- 3. Initialize LollmsClient ---
+    ASCIIColors.magenta("\n1. Initializing LollmsClient...")
+    try:
+        client = LollmsClient(
+            binding_name="ollama",
+            model_name="mistral-nemo:latest",
+            mcp_binding_name="standard_mcp",
+            mcp_binding_config=mcp_config,
+        )
+    except Exception as e:
+        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}")
+        trace_exception(e)
+        shutil.rmtree(example_base_dir, ignore_errors=True)
+        sys.exit(1)
+
+    if not client.binding:
+        ASCIIColors.error("LollmsClient's LLM binding (ollama) failed to load.")
+        shutil.rmtree(example_base_dir, ignore_errors=True)
+        sys.exit(1)
+    if not client.mcp:
+        ASCIIColors.error("LollmsClient's MCP binding (standard_mcp) failed to load.")
+        if hasattr(client, 'close'): client.close()
+        shutil.rmtree(example_base_dir, ignore_errors=True)
+        sys.exit(1)
+    ASCIIColors.green("LollmsClient initialized successfully.")
+
+
+    # --- 4. Define Streaming Callback (same as before) ---
+    def mcp_streaming_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, history: list = None) -> bool:
+        if metadata:
+            type_info = metadata.get('type', 'unknown_type')
+            if msg_type == MSG_TYPE.MSG_TYPE_STEP_START: ASCIIColors.cyan(f"MCP Step Start ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END: ASCIIColors.cyan(f"MCP Step End ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_INFO: ASCIIColors.yellow(f"MCP Info ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_CHUNK: ASCIIColors.green(chunk, end="")
+            else: ASCIIColors.green(f"MCP Output ({str(msg_type)}, {type_info}): {chunk}")
+        else:
+             if msg_type == MSG_TYPE.MSG_TYPE_CHUNK: ASCIIColors.green(chunk, end="")
+             else: ASCIIColors.green(f"MCP Output ({str(msg_type)}): {chunk}")
+        sys.stdout.flush()
+        return True
+
+    # --- 5. Use generate_with_mcp with local dummy servers ---
+    ASCIIColors.magenta("\n2. Calling generate_with_mcp to get current time (local dummy server)...")
+    time_prompt = "Hey assistant, what time is it right now?"
+    time_response = client.generate_with_mcp(
+        prompt=time_prompt,
+        streaming_callback=mcp_streaming_callback
+    )
+    print() 
+    ASCIIColors.blue(f"Final response for time prompt: {json.dumps(time_response, indent=2)}")
+    assert time_response.get("error") is None, f"Time prompt error: {time_response.get('error')}"
+    assert time_response.get("final_answer"), "Time prompt no final answer."
+    assert len(time_response.get("tool_calls", [])) > 0, "Time prompt should call tool."
+    if time_response.get("tool_calls"):
+        assert time_response["tool_calls"][0]["name"] == "time_machine::get_current_time", "Incorrect tool for time."
+        assert "time" in time_response["tool_calls"][0].get("result", {}).get("output", {}), "Time tool result missing time."
+
+    ASCIIColors.magenta("\n3. Calling generate_with_mcp for calculation (local dummy server)...")
+    calc_prompt = "Can you sum 50, 25, and 7.5 for me?"
+    calc_response = client.generate_with_mcp(
+        prompt=calc_prompt,
+        streaming_callback=mcp_streaming_callback
+    )
+    print()
+    ASCIIColors.blue(f"Final response for calc prompt: {json.dumps(calc_response, indent=2)}")
+    assert calc_response.get("error") is None, f"Calc prompt error: {calc_response.get('error')}"
+    assert calc_response.get("final_answer"), "Calc prompt no final answer."
+    assert len(calc_response.get("tool_calls", [])) > 0, "Calc prompt should call tool."
+    if calc_response.get("tool_calls"):
+        assert calc_response["tool_calls"][0]["name"] == "calc_unit::add_numbers", "Incorrect tool for calc."
+        assert "sum" in calc_response["tool_calls"][0].get("result", {}).get("output", {}), "Calculator tool result missing sum."
+
+
+    # --- 6. Interact with ElevenLabs MCP Server (if configured) ---
+    if "elevenlabs" in client.mcp.get_binding_config().get("initial_servers", {}):
+        ASCIIColors.magenta("\n4. Interacting with ElevenLabs MCP server...")
+
+        ASCIIColors.info("Discovering all available tools (including ElevenLabs)...")
+        all_mcp_tools = client.mcp.discover_tools(force_refresh=True, timeout_per_server=45) # Longer timeout for external server
+        ASCIIColors.green(f"Discovered {len(all_mcp_tools)} tools in total:")
+        for tool in all_mcp_tools:
+            # Try to get properties keys from input_schema for a more informative print
+            props_keys = "N/A"
+            if isinstance(tool.get('input_schema'), dict) and isinstance(tool['input_schema'].get('properties'), dict):
+                props_keys = list(tool['input_schema']['properties'].keys())
+            print(f"  - Name: {tool.get('name')}, Desc: {tool.get('description')}, Schema Props: {props_keys}")
+
+
+        elevenlabs_list_voices_tool_name = "elevenlabs::list_voices"
+        if any(t['name'] == elevenlabs_list_voices_tool_name for t in all_mcp_tools):
+            ASCIIColors.magenta(f"\n4a. Calling '{elevenlabs_list_voices_tool_name}' via LLM prompt...")
+            
+            list_voices_prompt = "Please list all the available voices from the elevenlabs tool."
+            voices_response = client.generate_with_mcp(
+                prompt=list_voices_prompt,
+                streaming_callback=mcp_streaming_callback,
+                max_tool_calls=1 
+            )
+            print()
+            ASCIIColors.blue(f"Final response for ElevenLabs list_voices prompt: {json.dumps(voices_response, indent=2)}")
+
+            assert voices_response.get("error") is None, f"ElevenLabs list_voices error: {voices_response.get('error')}"
+            assert voices_response.get("final_answer"), "ElevenLabs list_voices no final answer."
+            tool_calls = voices_response.get("tool_calls", [])
+            assert len(tool_calls) > 0, "ElevenLabs list_voices should call tool."
+            if tool_calls:
+                assert tool_calls[0]["name"] == elevenlabs_list_voices_tool_name, "Incorrect tool for ElevenLabs list_voices."
+                tool_output = tool_calls[0].get("result", {}).get("output")
+                assert isinstance(tool_output, list), f"ElevenLabs list_voices output not a list, got: {type(tool_output)}"
+                if tool_output:
+                     ASCIIColors.green(f"First voice from ElevenLabs: {tool_output[0].get('name')} (ID: {tool_output[0].get('voice_id')})")
+        else:
+            ASCIIColors.yellow(f"Tool '{elevenlabs_list_voices_tool_name}' not found. Skipping ElevenLabs tool execution test.")
+    else:
+        ASCIIColors.yellow("ElevenLabs MCP server not configured in this run (check .env for API key and uvx availability). Skipping ElevenLabs tests.")
+
+    # --- 7. Cleanup ---
+    ASCIIColors.magenta("\n5. Closing LollmsClient and cleaning up...")
+    if client and hasattr(client, 'close'):
+        try:
+            client.close()
+        except Exception as e:
+            ASCIIColors.error(f"Error closing LollmsClient: {e}")
+            trace_exception(e)
+
+    ASCIIColors.info("Cleaning up temporary server scripts directory...")
+    shutil.rmtree(example_base_dir, ignore_errors=True)
+
+    ASCIIColors.red("\n--- LollmsClient with MCP Example (including external) Finished ---")
+
+if __name__ == "__main__":
+    main()

examples/openai_mcp.py

@@ -0,0 +1,203 @@
+# File: run_openai_mcp_example.py
+# (Keep imports, path adjustments, helper functions, and initial setup as before)
+
+import sys
+import os
+import shutil
+from pathlib import Path
+import json
+import base64
+from dotenv import load_dotenv
+
+load_dotenv() # For this script's own potential .env
+
+try:
+    from lollms_client import LollmsClient
+    from ascii_colors import ASCIIColors, trace_exception
+    from lollms_client.lollms_types import MSG_TYPE
+except ImportError as e:
+    print(f"ERROR: Could not import LollmsClient components: {e}")
+    trace_exception(e)
+    sys.exit(1)
+
+PATH_TO_OPENAI_MCP_SERVER_PROJECT = Path(__file__).resolve().parent # Standard if script is in PArisNeoMCPServers root
+if not PATH_TO_OPENAI_MCP_SERVER_PROJECT.is_dir():
+    print(f"ERROR: openai-mcp-server project not found at {PATH_TO_OPENAI_MCP_SERVER_PROJECT}")
+    sys.exit(1)
+
+OUTPUT_DIRECTORY = Path(__file__).resolve().parent / "mcp_example_outputs"
+OUTPUT_DIRECTORY.mkdir(parents=True, exist_ok=True)
+
+def save_base64_audio(base64_str: str, filename_stem: str, audio_format: str) -> Path:
+    audio_bytes = base64.b64decode(base64_str)
+    file_path = OUTPUT_DIRECTORY / f"{filename_stem}.{audio_format}"
+    with open(file_path, "wb") as f: f.write(audio_bytes)
+    ASCIIColors.green(f"Audio saved to: {file_path}")
+    return file_path
+
+def save_base64_image(base64_str: str, filename_stem: str) -> Path:
+    image_bytes = base64.b64decode(base64_str)
+    file_path = OUTPUT_DIRECTORY / f"{filename_stem}.png"
+    with open(file_path, "wb") as f: f.write(image_bytes)
+    ASCIIColors.green(f"Image saved to: {file_path}")
+    return file_path
+
+def main():
+    ASCIIColors.red(f"--- Example: Using LollmsClient with OpenAI MCP Server (TTS & DALL-E) ---")
+    ASCIIColors.red(f"--- Make sure OPENAI_API_KEY is set in: {PATH_TO_OPENAI_MCP_SERVER_PROJECT / '.env'} ---")
+    ASCIIColors.red(f"--- And that 'uv pip install -e .' has been run in: {PATH_TO_OPENAI_MCP_SERVER_PROJECT} ---")
+
+    # Determine the Python executable within the server's .venv IF IT EXISTS
+    # This is the most robust way to ensure the server runs with its own isolated dependencies.
+    path_to_openai_server_venv_python = PATH_TO_OPENAI_MCP_SERVER_PROJECT / ".venv" / ("Scripts" if os.name == "nt" else "bin") / "python"
+    
+    python_exe_to_use = None
+    if path_to_openai_server_venv_python.exists():
+        python_exe_to_use = str(path_to_openai_server_venv_python.resolve())
+        ASCIIColors.cyan(f"Attempting to use Python from server's .venv: {python_exe_to_use}")
+    else:
+        python_exe_to_use = sys.executable # Fallback to current script's Python
+        ASCIIColors.yellow(f"Server's .venv Python not found at {path_to_openai_server_venv_python}. Using current environment's Python: {python_exe_to_use}")
+        ASCIIColors.yellow("Ensure openai-mcp-server dependencies are met in the current environment if its .venv is not used.")
+
+    mcp_config = {
+        "initial_servers": {
+            "my_openai_server": {
+                "command": [
+                    "uv",       # Use uv to manage the environment for the python execution
+                    "run",
+                    "--quiet",  # Optional: reduce uv's own output unless there's an error
+                    "--",       # Separator: arguments after this are for the command being run by `uv run`
+                    python_exe_to_use, # Explicitly specify the Python interpreter
+                    str((PATH_TO_OPENAI_MCP_SERVER_PROJECT / "openai_mcp_server" / "server.py").resolve()) # Full path to your server script
+                ],
+                "args": [], # No *additional* arguments for server.py itself here
+                "cwd": str(PATH_TO_OPENAI_MCP_SERVER_PROJECT.resolve()), # CRUCIAL
+            }
+        }
+    }
+
+
+    ASCIIColors.magenta("\n1. Initializing LollmsClient...")
+    try:
+        client = LollmsClient(
+            binding_name="ollama",
+            model_name="mistral-nemo:latest",
+            mcp_binding_name="standard_mcp",
+            mcp_binding_config=mcp_config,
+        )
+    except Exception as e:
+        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}")
+        trace_exception(e)
+        sys.exit(1)
+
+    if not client.binding or not client.mcp:
+        ASCIIColors.error("LollmsClient LLM or MCP binding failed to load.")
+        if hasattr(client, 'close'): client.close()
+        sys.exit(1)
+    ASCIIColors.green("LollmsClient initialized successfully.")
+
+    def mcp_streaming_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, history: list = None) -> bool:
+        prefix = ""
+        color_func = ASCIIColors.green
+        if metadata:
+            type_info = metadata.get('type', 'unknown_type')
+            tool_name_info = metadata.get('tool_name', '')
+            prefix = f"MCP ({type_info}{f' - {tool_name_info}' if tool_name_info else ''})"
+            if msg_type == MSG_TYPE.MSG_TYPE_STEP_START: color_func = ASCIIColors.cyan; prefix += " Step Start"
+            elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END: color_func = ASCIIColors.cyan; prefix += " Step End"
+            elif msg_type == MSG_TYPE.MSG_TYPE_INFO: color_func = ASCIIColors.yellow; prefix += " Info"
+            elif msg_type == MSG_TYPE.MSG_TYPE_EXCEPTION: color_func = ASCIIColors.red; prefix += " Exception"
+        else:
+            prefix = f"MCP (Type: {str(msg_type).split('.')[-1]})"
+        if msg_type == MSG_TYPE.MSG_TYPE_CHUNK: ASCIIColors.green(chunk, end="")
+        else: color_func(f"{prefix}: {chunk}")
+        sys.stdout.flush()
+        return True
+
+    # --- Test 1: General Text Query (handled by Ollama, no MCP tool expected) ---
+    ASCIIColors.magenta("\n2. Test: General Text Query (should be handled by Ollama)")
+    general_query = "What is the capital of France?"
+    general_response = client.generate_with_mcp( # generate_with_mcp will discover no suitable text tool
+        prompt=general_query,
+        streaming_callback=mcp_streaming_callback,
+        # tools=[] # Optionally explicitly pass an empty list of tools if you want to be sure
+                  # generate_with_mcp will discover tools from the binding if not passed
+    )
+    print()
+    ASCIIColors.blue(f"Final response for general query: {json.dumps(general_response, indent=2)}")
+    assert general_response.get("error") is None, f"General query error: {general_response.get('error')}"
+    assert general_response.get("final_answer"), "General query: no final answer."
+    tool_calls_general = general_response.get("tool_calls", [])
+    assert len(tool_calls_general) == 0, "General query should NOT have called an MCP tool from my_openai_server."
+    ASCIIColors.green(f"General query handled by LLM directly, as expected. Answer: {general_response.get('final_answer')[:100]}...")
+
+
+    # --- Test 2: Text-to-Speech (TTS) ---
+    ASCIIColors.magenta("\n3. Test: OpenAI TTS via MCP")
+    tts_text = "This audio was generated by the OpenAI MCP server through Lollms Client."
+    tts_prompt_for_llm = f"Please use the OpenAI tool to say the following using tts: '{tts_text}'."
+    
+    tts_response = client.generate_with_mcp(
+        prompt=tts_prompt_for_llm,
+        streaming_callback=mcp_streaming_callback,
+        max_tool_calls=1
+    )
+    print()
+    ASCIIColors.blue(f"Final response for TTS prompt: {json.dumps(tts_response, indent=2)}")
+
+    assert tts_response.get("error") is None, f"TTS error: {tts_response.get('error')}"
+    assert tts_response.get("final_answer"), "TTS: no final answer (LLM should confirm action)."
+    tool_calls_tts = tts_response.get("tool_calls", [])
+    assert len(tool_calls_tts) > 0, "TTS should have called a tool."
+    if tool_calls_tts:
+        assert tool_calls_tts[0]["name"] == "my_openai_server::generate_tts", "Incorrect tool for TTS."
+        tts_result_output = tool_calls_tts[0].get("result", {}).get("output", {})
+        assert "audio_base64" in tts_result_output, "TTS tool result missing 'audio_base64'."
+        assert "format" in tts_result_output, "TTS tool result missing 'format'."
+        if tts_result_output.get("audio_base64"):
+            save_base64_audio(tts_result_output["audio_base64"], "openai_tts_example_output", tts_result_output["format"])
+
+    # --- Test 3: DALL-E Image Generation ---
+    ASCIIColors.magenta("\n4. Test: OpenAI DALL-E Image Generation via MCP")
+    dalle_image_prompt = "A vibrant illustration of a friendly AI robot helping a human plant a tree on a futuristic Earth."
+    dalle_prompt_for_llm = f"I need an image for a presentation. Can you use DALL-E to create this: {dalle_image_prompt}. Please use URL format for the image."
+
+    dalle_response = client.generate_with_mcp(
+        prompt=dalle_prompt_for_llm,
+        streaming_callback=mcp_streaming_callback,
+        max_tool_calls=1,
+        # You could also try to force params for the tool if LLM struggles:
+        # Example: if LLM isn't picking response_format="url"
+        # This requires knowing the exact tool name and schema, usually let LLM handle it.
+    )
+    print()
+    ASCIIColors.blue(f"Final response for DALL-E prompt: {json.dumps(dalle_response, indent=2)}")
+    
+    assert dalle_response.get("error") is None, f"DALL-E error: {dalle_response.get('error')}"
+    assert dalle_response.get("final_answer"), "DALL-E: no final answer (LLM should confirm action)."
+    tool_calls_dalle = dalle_response.get("tool_calls", [])
+    assert len(tool_calls_dalle) > 0, "DALL-E should have called a tool."
+    if tool_calls_dalle:
+        assert tool_calls_dalle[0]["name"] == "my_openai_server::generate_image_dalle", "Incorrect tool for DALL-E."
+        dalle_result_output = tool_calls_dalle[0].get("result", {}).get("output", {})
+        assert "images" in dalle_result_output and isinstance(dalle_result_output["images"], list), "DALL-E result missing 'images' list."
+        if dalle_result_output.get("images"):
+            image_data = dalle_result_output["images"][0]
+            if image_data.get("url"):
+                ASCIIColors.green(f"DALL-E image URL: {image_data['url']}")
+                ASCIIColors.info(f"Revised prompt by DALL-E: {image_data.get('revised_prompt')}")
+            elif image_data.get("b64_json"):
+                save_base64_image(image_data["b64_json"], "openai_dalle_example_output")
+                ASCIIColors.info(f"Revised prompt by DALL-E: {image_data.get('revised_prompt')}")
+
+    ASCIIColors.magenta("\n5. Closing LollmsClient...")
+    if client and hasattr(client, 'close'):
+        try: client.close()
+        except Exception as e: ASCIIColors.error(f"Error closing LollmsClient: {e}"); trace_exception(e)
+
+    ASCIIColors.info(f"Example finished. Check {OUTPUT_DIRECTORY} for any generated files.")
+    ASCIIColors.red("\n--- LollmsClient with OpenAI MCP Server (TTS & DALL-E) Example Finished ---")
+
+if __name__ == "__main__":
+    main()

examples/run_standard_mcp_example.py

@@ -0,0 +1,204 @@
+# File: run_lollms_client_with_mcp_example.py
+
+import sys
+import os
+import shutil
+from pathlib import Path
+import json
+from lollms_client import LollmsClient
+# --- Dynamically adjust Python path to find lollms_client ---
+# This assumes the example script is in a directory, and 'lollms_client' is
+# in a sibling directory or a known relative path. Adjust as needed.
+# For example, if script is in 'lollms_client/examples/' and lollms_client code is in 'lollms_client/'
+# then the parent of the script's parent is the project root.
+
+# Get the directory of the current script
+current_script_dir = Path(__file__).resolve().parent
+
+# Option 1: If lollms_client is in the parent directory of this script's directory
+# (e.g. script is in 'project_root/examples' and lollms_client is in 'project_root/lollms_client')
+# project_root = current_script_dir.parent
+# lollms_client_path = project_root / "lollms_client" # Assuming this is where lollms_client.py and bindings are
+
+# Option 2: If lollms_client package is directly one level up
+# (e.g. script is in 'lollms_client/examples' and lollms_client package is 'lollms_client')
+project_root_for_lollms_client = current_script_dir.parent
+if str(project_root_for_lollms_client) not in sys.path:
+    sys.path.insert(0, str(project_root_for_lollms_client))
+    print(f"Added to sys.path: {project_root_for_lollms_client}")
+
+
+# --- Ensure pipmaster is available (core LoLLMs dependency) ---
+try:
+    import pipmaster as pm
+except ImportError:
+    print("ERROR: pipmaster is not installed or not in PYTHONPATH.")
+    sys.exit(1)
+
+# --- Import LollmsClient and supporting components ---
+try:
+
+    from lollms_client.lollms_llm_binding import LollmsLLMBinding # Base for LLM
+    from ascii_colors import ASCIIColors, trace_exception
+    from lollms_client.lollms_types import MSG_TYPE # Assuming MSG_TYPE is here
+except ImportError as e:
+    print(f"ERROR: Could not import LollmsClient components: {e}")
+    print("Ensure 'lollms_client' package structure is correct and accessible via PYTHONPATH.")
+    print(f"Current sys.path: {sys.path}")
+    trace_exception(e)
+    sys.exit(1)
+
+
+# --- Dummy Server Scripts using FastMCP (as per previous successful iteration) ---
+TIME_SERVER_PY = """
+import asyncio
+from datetime import datetime
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("TimeMCP", description="A server that provides the current time.")
+
+@mcp_server.tool(description="Returns the current server time and echoes received parameters.")
+def get_current_time(user_id: str = "unknown_user") -> dict:
+    return {"time": datetime.now().isoformat(), "params_received": {"user_id": user_id}, "server_name": "TimeServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+CALCULATOR_SERVER_PY = """
+import asyncio
+from typing import List, Union
+from mcp.server.fastmcp import FastMCP
+
+mcp_server = FastMCP("CalculatorMCP", description="A server that performs addition.")
+
+@mcp_server.tool(description="Adds a list of numbers provided in the 'numbers' parameter.")
+def add_numbers(numbers: List[Union[int, float]]) -> dict:
+    if not isinstance(numbers, list) or not all(isinstance(x, (int, float)) for x in numbers):
+        return {"error": "'numbers' must be a list of numbers."}
+    return {"sum": sum(numbers), "server_name": "CalculatorServer"}
+
+if __name__ == "__main__":
+    mcp_server.run(transport="stdio")
+"""
+
+
+def main():
+    ASCIIColors.red("--- Example: Using LollmsClient with StandardMCPBinding ---")
+
+    # --- 1. Setup Temporary Directory for Dummy MCP Servers ---
+    example_base_dir = Path(__file__).parent / "temp_mcp_example_servers"
+    if example_base_dir.exists():
+        shutil.rmtree(example_base_dir)
+    example_base_dir.mkdir(exist_ok=True)
+
+    time_server_script_path = example_base_dir / "time_server.py"
+    with open(time_server_script_path, "w") as f: f.write(TIME_SERVER_PY)
+
+    calculator_server_script_path = example_base_dir / "calculator_server.py"
+    with open(calculator_server_script_path, "w") as f: f.write(CALCULATOR_SERVER_PY)
+
+    # MCP Binding Configuration (for StandardMCPBinding)
+    mcp_config = {
+        "initial_servers": {
+            "time_machine": {
+                "command": [sys.executable, str(time_server_script_path.resolve())],
+            },
+            "calc_unit": {
+                "command": [sys.executable, str(calculator_server_script_path.resolve())]
+            }
+        }
+    }
+    ASCIIColors.magenta("\n1. Initializing LollmsClient...")
+    try:
+        client = LollmsClient(
+            binding_name="ollama", # Use the dummy LLM binding
+            model_name="mistral-nemo:latest",
+            mcp_binding_name="standard_mcp",
+            mcp_binding_config=mcp_config,
+        )
+    except Exception as e:
+        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}")
+        trace_exception(e)
+        shutil.rmtree(example_base_dir)
+        sys.exit(1)
+
+    if not client.binding:
+        ASCIIColors.error("LollmsClient's LLM binding (dummy_llm) failed to load.")
+        shutil.rmtree(example_base_dir)
+        sys.exit(1)
+    if not client.mcp:
+        ASCIIColors.error("LollmsClient's MCP binding (standard_mcp) failed to load.")
+        client.close() # Close LLM binding if it loaded
+        shutil.rmtree(example_base_dir)
+        sys.exit(1)
+
+    ASCIIColors.green("LollmsClient initialized successfully with DummyLLM and StandardMCP bindings.")
+
+    # --- 3. Define a streaming callback for generate_with_mcp ---
+    def mcp_streaming_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, history: list = None) -> bool:
+        if metadata:
+            type_info = metadata.get('type', 'unknown_type')
+            if msg_type == MSG_TYPE.MSG_TYPE_STEP_START:
+                ASCIIColors.cyan(f"MCP Step Start ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END:
+                ASCIIColors.cyan(f"MCP Step End ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_INFO:
+                ASCIIColors.yellow(f"MCP Info ({type_info}): {chunk}")
+            elif msg_type == MSG_TYPE.MSG_TYPE_CHUNK: # Part of final answer typically
+                ASCIIColors.green(chunk, end="") # type: ignore
+            else: # FULL, default, etc.
+                ASCIIColors.green(f"MCP Output ({str(msg_type)}, {type_info}): {chunk}")
+        else:
+             if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:
+                ASCIIColors.green(chunk, end="") # type: ignore
+             else:
+                ASCIIColors.green(f"MCP Output ({str(msg_type)}): {chunk}")
+        sys.stdout.flush()
+        return True # Continue streaming
+
+    # --- 4. Use generate_with_mcp ---
+    ASCIIColors.magenta("\n2. Calling generate_with_mcp to get current time...")
+    time_prompt = "Hey assistant, what time is it right now?"
+    time_response = client.generate_with_mcp(
+        prompt=time_prompt,
+        streaming_callback=mcp_streaming_callback,
+        interactive_tool_execution=False # Set to True to test interactive mode
+    )
+    print() # Newline after streaming
+    ASCIIColors.blue(f"Final response for time prompt: {json.dumps(time_response, indent=2)}")
+
+    assert time_response.get("error") is None, f"Time prompt resulted in an error: {time_response.get('error')}"
+    assert time_response.get("final_answer"), "Time prompt did not produce a final answer."
+    assert len(time_response.get("tool_calls", [])) > 0, "Time prompt should have called a tool."
+    assert time_response["tool_calls"][0]["name"] == "time_machine::get_current_time", "Incorrect tool called for time."
+    assert "time" in time_response["tool_calls"][0].get("result", {}).get("output", {}), "Time tool result missing time."
+
+
+    ASCIIColors.magenta("\n3. Calling generate_with_mcp for calculation...")
+    calc_prompt = "Can you please calculate the sum of 50, 25, and 7.5 for me?"
+    calc_response = client.generate_with_mcp(
+        prompt=calc_prompt,
+        streaming_callback=mcp_streaming_callback
+    )
+    print() # Newline
+    ASCIIColors.blue(f"Final response for calc prompt: {json.dumps(calc_response, indent=2)}")
+
+    assert calc_response.get("error") is None, f"Calc prompt resulted in an error: {calc_response.get('error')}"
+    assert calc_response.get("final_answer"), "Calc prompt did not produce a final answer."
+    assert len(calc_response.get("tool_calls", [])) > 0, "Calc prompt should have called a tool."
+    assert calc_response["tool_calls"][0]["name"] == "calc_unit::add_numbers", "Incorrect tool called for calculation."
+    # The dummy LLM uses hardcoded params [1,2,3] for calc, so result will be 6.
+    # A real LLM would extract 50, 25, 7.5.
+    # For this dummy test, we check against the dummy's behavior.
+    assert calc_response["tool_calls"][0].get("result", {}).get("output", {}).get("sum") == 82.5, "Calculator tool result mismatch for dummy params."
+
+
+    # --- 5. Cleanup ---
+    ASCIIColors.info("Cleaning up temporary server scripts and dummy binding directory...")
+    shutil.rmtree(example_base_dir, ignore_errors=True)
+
+    ASCIIColors.red("\n--- LollmsClient with StandardMCPBinding Example Finished Successfully! ---")
+
+if __name__ == "__main__":
+    main()