lollms-client 0.17.2__tar.gz → 0.19.1__tar.gz

{lollms_client-0.17.2/lollms_client.egg-info → lollms_client-0.19.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.17.2
+Version: 0.19.1
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License
@@ -39,7 +39,7 @@ Dynamic: license-file
 [![GitHub stars](https://img.shields.io/github/stars/ParisNeo/lollms_client.svg?style=social&label=Star&maxAge=2592000)](https://github.com/ParisNeo/lollms_client/stargazers/)
 [![GitHub issues](https://img.shields.io/github/issues/ParisNeo/lollms_client.svg)](https://github.com/ParisNeo/lollms_client/issues)
 
-**`lollms_client`** is a powerful and flexible Python library designed to simplify interactions with the **LoLLMs (Lord of Large Language Models)** ecosystem and various other Large Language Model (LLM) backends. It provides a unified API for text generation, multimodal operations (text-to-image, text-to-speech, etc.), function calling, and advanced AI-driven tasks.
+**`lollms_client`** is a powerful and flexible Python library designed to simplify interactions with the **LoLLMs (Lord of Large Language Models)** ecosystem and various other Large Language Model (LLM) backends. It provides a unified API for text generation, multimodal operations (text-to-image, text-to-speech, etc.), and robust function calling through the Model Context Protocol (MCP).
 
 Whether you're connecting to a remote LoLLMs server, an Ollama instance, the OpenAI API, or running models locally using GGUF (via `llama-cpp-python` or a managed `llama.cpp` server), Hugging Face Transformers, or vLLM, `lollms-client` offers a consistent and developer-friendly experience.
 
@@ -47,12 +47,12 @@ Whether you're connecting to a remote LoLLMs server, an Ollama instance, the Ope
 
 *   🔌 **Versatile Binding System:** Seamlessly switch between different LLM backends (LoLLMs, Ollama, OpenAI, Llama.cpp, Transformers, vLLM, OpenLLM) without major code changes.
 *   🗣️ **Multimodal Support:** Interact with models capable of processing images and generate various outputs like speech (TTS) and images (TTI).
-*   🚀 **Streaming & Callbacks:** Efficiently handle real-time text generation with customizable callback functions.
-*   🛠️ **Task-Oriented Library:** High-level `TasksLibrary` for common operations like summarization, Q&A, code generation, and structured data extraction.
-*   📞 **Function Calling:** Enable LLMs to invoke your custom Python functions, bridging the gap between language models and external tools or data sources.
+*   🤖 **Function Calling with MCP:** Empowers LLMs to use external tools and functions through the Model Context Protocol (MCP), with built-in support for local Python tool execution via `local_mcp` binding and its default tools (file I/O, internet search, Python interpreter, image generation).
+*   🚀 **Streaming & Callbacks:** Efficiently handle real-time text generation with customizable callback functions, including during MCP interactions.
 *   💬 **Discussion Management:** Utilities to easily manage and format conversation histories for chat applications.
 *   ⚙️ **Configuration Management:** Flexible ways to configure bindings and generation parameters.
-*   🧩 **Extensible:** Designed to easily incorporate new LLM backends and modality services.
+*   🧩 **Extensible:** Designed to easily incorporate new LLM backends and modality services, including custom MCP toolsets.
+*   📝 **High-Level Operations:** Includes convenience methods for complex tasks like sequential summarization and deep text analysis directly within `LollmsClient`.
 
 ## Installation
 
@@ -119,12 +119,61 @@ except Exception as e:
 
 ```
 
+### Function Calling with MCP
+
+`lollms-client` supports robust function calling via the Model Context Protocol (MCP), allowing LLMs to interact with your custom Python tools or pre-defined utilities.
+
+```python
+from lollms_client import LollmsClient, MSG_TYPE
+from ascii_colors import ASCIIColors
+import json # For pretty printing results
+
+# Example callback for MCP streaming
+def mcp_stream_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, turn_history: list = None) -> bool:
+    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:  ASCIIColors.success(chunk, end="", flush=True) # LLM's final answer or thought process
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_START: ASCIIColors.info(f"\n>> MCP Step Start: {metadata.get('tool_name', chunk)}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END: ASCIIColors.success(f"\n<< MCP Step End: {metadata.get('tool_name', chunk)} -> Result: {json.dumps(metadata.get('result', ''))}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_INFO and metadata and metadata.get("type") == "tool_call_request": ASCIIColors.info(f"\nAI requests: {metadata.get('name')}({metadata.get('params')})", flush=True)
+    return True
+
+try:
+    # Initialize LollmsClient with an LLM binding and the local_mcp binding
+    lc = LollmsClient(
+        binding_name="ollama", model_name="mistral", # Example LLM
+        mcp_binding_name="local_mcp" # Enables default tools (file_writer, internet_search, etc.)
+                                     # or custom tools if mcp_binding_config.tools_folder_path is set.
+    )
+
+    user_query = "What were the main AI headlines last week and write a summary to 'ai_news.txt'?"
+    ASCIIColors.blue(f"User Query: {user_query}")
+    ASCIIColors.yellow("AI Processing with MCP (streaming):")
+
+    mcp_result = lc.generate_with_mcp(
+        prompt=user_query,
+        streaming_callback=mcp_stream_callback
+    )
+    print("\n--- End of MCP Interaction ---")
+
+    if mcp_result.get("error"):
+        ASCIIColors.error(f"MCP Error: {mcp_result['error']}")
+    else:
+        ASCIIColors.cyan(f"\nFinal Answer from AI: {mcp_result.get('final_answer', 'N/A')}")
+        ASCIIColors.magenta("\nTool Calls Made:")
+        for tc in mcp_result.get("tool_calls", []):
+            print(f"  - Tool: {tc.get('name')}, Params: {tc.get('params')}, Result (first 50 chars): {str(tc.get('result'))[:50]}...")
+
+except Exception as e:
+    ASCIIColors.error(f"An error occurred in MCP example: {e}")
+    trace_exception(e) # Assuming you have trace_exception utility
+```
+For a comprehensive guide on function calling and setting up tools, please refer to the [Usage Guide (DOC_USE.md)](DOC_USE.md).
+
 ## Documentation
 
 For more in-depth information, please refer to:
 
-*   **[Usage Guide (DOC_USE.md)](DOC_USE.md):** Learn how to use `LollmsClient`, different bindings, modality features, `TasksLibrary`, and `FunctionCalling_Library` with comprehensive examples.
-*   **[Developer Guide (DOC_DEV.md)](DOC_DEV.md):** Understand the architecture, how to create new bindings, and contribute to the library.
+*   **[Usage Guide (DOC_USE.md)](DOC_USE.md):** Learn how to use `LollmsClient`, different bindings, modality features, function calling with MCP, and high-level operations.
+*   **[Developer Guide (DOC_DEV.md)](DOC_DEV.md):** Understand the architecture, how to create new bindings (LLM, modality, MCP), and contribute to the library.
 
 ## Core Concepts
 
@@ -134,8 +183,9 @@ graph LR
 
     subgraph LollmsClient_Core
         LC -- Manages --> LLB[LLM Binding];
-        LC -- Provides Access To --> TL[TasksLibrary];
-        LC -- Provides Access To --> FCL[FunctionCalling_Library];
+        LC -- Manages --> MCPB[MCP Binding];
+        LC -- Orchestrates --> MCP_Interaction[generate_with_mcp];
+        LC -- Provides --> HighLevelOps[High-Level Ops<br>(summarize, deep_analyze etc.)];
         LC -- Provides Access To --> DM[DiscussionManager];
         LC -- Provides Access To --> ModalityBindings[TTS, TTI, STT etc.];
     end
@@ -148,14 +198,19 @@ graph LR
         LLB --> LocalHF[Local HuggingFace<br>(transformers / vLLM)];
     end
 
-    ModalityBindings --> ModalityServices[Modality Services<br>(e.g., LoLLMs Server TTS/TTI)];
+    MCP_Interaction --> MCPB;
+    MCPB --> LocalTools[Local Python Tools<br>(via local_mcp)];
+    MCPB --> RemoteTools[Remote MCP Tool Servers<br>(Future Potential)];
+
+
+    ModalityBindings --> ModalityServices[Modality Services<br>(e.g., LoLLMs Server TTS/TTI, local Bark/XTTS)];
 ```
 
-*   **`LollmsClient`**: The central class for all interactions. It holds the currently active LLM binding and provides access to modality bindings and helper libraries.
+*   **`LollmsClient`**: The central class for all interactions. It holds the currently active LLM binding, an optional MCP binding, and provides access to modality bindings and high-level operations.
 *   **LLM Bindings**: These are plugins that allow `LollmsClient` to communicate with different LLM backends. You choose a binding (e.g., `"ollama"`, `"lollms"`, `"pythonllamacpp"`) when you initialize `LollmsClient`.
+*   **🔧 MCP Bindings**: Enable tool use and function calling. `lollms-client` includes `local_mcp` for executing Python tools. It discovers tools from a specified folder (or uses its default set), each defined by a `.py` script and a `.mcp.json` metadata file.
 *   **Modality Bindings**: Similar to LLM bindings, but for services like Text-to-Speech (`tts`), Text-to-Image (`tti`), etc.
-*   **`TasksLibrary`**: Offers high-level functions for common AI tasks (summarization, Q&A) built on top of `LollmsClient`.
-*   **`FunctionCalling_Library`**: Enables you to define Python functions that the LLM can request to execute, allowing for tool usage.
+*   **High-Level Operations**: Methods directly on `LollmsClient` (e.g., `sequential_summarize`, `deep_analyze`, `generate_code`, `yes_no`) for performing complex, multi-step AI tasks.
 *   **`LollmsDiscussion`**: Helps manage and format conversation histories for chat applications.
 
 ## Examples
@@ -164,8 +219,8 @@ The `examples/` directory in this repository contains a rich set of scripts demo
 *   Basic text generation with different bindings.
 *   Streaming and non-streaming examples.
 *   Multimodal generation (text with images).
-*   Using `TasksLibrary` for summarization and Q&A.
-*   Implementing and using function calls.
+*   Using built-in methods for summarization and Q&A.
+*   Implementing and using function calls with **`generate_with_mcp`** and the `local_mcp` binding (see `examples/function_calling_with_local_custom_mcp.py` and `examples/local_mcp.py`).
 *   Text-to-Speech and Text-to-Image generation.
 
 Explore these examples to see `lollms-client` in action!

{lollms_client-0.17.2 → lollms_client-0.19.1}/README.md

@@ -9,7 +9,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/ParisNeo/lollms_client.svg?style=social&label=Star&maxAge=2592000)](https://github.com/ParisNeo/lollms_client/stargazers/)
 [![GitHub issues](https://img.shields.io/github/issues/ParisNeo/lollms_client.svg)](https://github.com/ParisNeo/lollms_client/issues)
 
-**`lollms_client`** is a powerful and flexible Python library designed to simplify interactions with the **LoLLMs (Lord of Large Language Models)** ecosystem and various other Large Language Model (LLM) backends. It provides a unified API for text generation, multimodal operations (text-to-image, text-to-speech, etc.), function calling, and advanced AI-driven tasks.
+**`lollms_client`** is a powerful and flexible Python library designed to simplify interactions with the **LoLLMs (Lord of Large Language Models)** ecosystem and various other Large Language Model (LLM) backends. It provides a unified API for text generation, multimodal operations (text-to-image, text-to-speech, etc.), and robust function calling through the Model Context Protocol (MCP).
 
 Whether you're connecting to a remote LoLLMs server, an Ollama instance, the OpenAI API, or running models locally using GGUF (via `llama-cpp-python` or a managed `llama.cpp` server), Hugging Face Transformers, or vLLM, `lollms-client` offers a consistent and developer-friendly experience.
 
@@ -17,12 +17,12 @@ Whether you're connecting to a remote LoLLMs server, an Ollama instance, the Ope
 
 *   🔌 **Versatile Binding System:** Seamlessly switch between different LLM backends (LoLLMs, Ollama, OpenAI, Llama.cpp, Transformers, vLLM, OpenLLM) without major code changes.
 *   🗣️ **Multimodal Support:** Interact with models capable of processing images and generate various outputs like speech (TTS) and images (TTI).
-*   🚀 **Streaming & Callbacks:** Efficiently handle real-time text generation with customizable callback functions.
-*   🛠️ **Task-Oriented Library:** High-level `TasksLibrary` for common operations like summarization, Q&A, code generation, and structured data extraction.
-*   📞 **Function Calling:** Enable LLMs to invoke your custom Python functions, bridging the gap between language models and external tools or data sources.
+*   🤖 **Function Calling with MCP:** Empowers LLMs to use external tools and functions through the Model Context Protocol (MCP), with built-in support for local Python tool execution via `local_mcp` binding and its default tools (file I/O, internet search, Python interpreter, image generation).
+*   🚀 **Streaming & Callbacks:** Efficiently handle real-time text generation with customizable callback functions, including during MCP interactions.
 *   💬 **Discussion Management:** Utilities to easily manage and format conversation histories for chat applications.
 *   ⚙️ **Configuration Management:** Flexible ways to configure bindings and generation parameters.
-*   🧩 **Extensible:** Designed to easily incorporate new LLM backends and modality services.
+*   🧩 **Extensible:** Designed to easily incorporate new LLM backends and modality services, including custom MCP toolsets.
+*   📝 **High-Level Operations:** Includes convenience methods for complex tasks like sequential summarization and deep text analysis directly within `LollmsClient`.
 
 ## Installation
 
@@ -89,12 +89,61 @@ except Exception as e:
 
 ```
 
+### Function Calling with MCP
+
+`lollms-client` supports robust function calling via the Model Context Protocol (MCP), allowing LLMs to interact with your custom Python tools or pre-defined utilities.
+
+```python
+from lollms_client import LollmsClient, MSG_TYPE
+from ascii_colors import ASCIIColors
+import json # For pretty printing results
+
+# Example callback for MCP streaming
+def mcp_stream_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, turn_history: list = None) -> bool:
+    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:  ASCIIColors.success(chunk, end="", flush=True) # LLM's final answer or thought process
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_START: ASCIIColors.info(f"\n>> MCP Step Start: {metadata.get('tool_name', chunk)}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END: ASCIIColors.success(f"\n<< MCP Step End: {metadata.get('tool_name', chunk)} -> Result: {json.dumps(metadata.get('result', ''))}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_INFO and metadata and metadata.get("type") == "tool_call_request": ASCIIColors.info(f"\nAI requests: {metadata.get('name')}({metadata.get('params')})", flush=True)
+    return True
+
+try:
+    # Initialize LollmsClient with an LLM binding and the local_mcp binding
+    lc = LollmsClient(
+        binding_name="ollama", model_name="mistral", # Example LLM
+        mcp_binding_name="local_mcp" # Enables default tools (file_writer, internet_search, etc.)
+                                     # or custom tools if mcp_binding_config.tools_folder_path is set.
+    )
+
+    user_query = "What were the main AI headlines last week and write a summary to 'ai_news.txt'?"
+    ASCIIColors.blue(f"User Query: {user_query}")
+    ASCIIColors.yellow("AI Processing with MCP (streaming):")
+
+    mcp_result = lc.generate_with_mcp(
+        prompt=user_query,
+        streaming_callback=mcp_stream_callback
+    )
+    print("\n--- End of MCP Interaction ---")
+
+    if mcp_result.get("error"):
+        ASCIIColors.error(f"MCP Error: {mcp_result['error']}")
+    else:
+        ASCIIColors.cyan(f"\nFinal Answer from AI: {mcp_result.get('final_answer', 'N/A')}")
+        ASCIIColors.magenta("\nTool Calls Made:")
+        for tc in mcp_result.get("tool_calls", []):
+            print(f"  - Tool: {tc.get('name')}, Params: {tc.get('params')}, Result (first 50 chars): {str(tc.get('result'))[:50]}...")
+
+except Exception as e:
+    ASCIIColors.error(f"An error occurred in MCP example: {e}")
+    trace_exception(e) # Assuming you have trace_exception utility
+```
+For a comprehensive guide on function calling and setting up tools, please refer to the [Usage Guide (DOC_USE.md)](DOC_USE.md).
+
 ## Documentation
 
 For more in-depth information, please refer to:
 
-*   **[Usage Guide (DOC_USE.md)](DOC_USE.md):** Learn how to use `LollmsClient`, different bindings, modality features, `TasksLibrary`, and `FunctionCalling_Library` with comprehensive examples.
-*   **[Developer Guide (DOC_DEV.md)](DOC_DEV.md):** Understand the architecture, how to create new bindings, and contribute to the library.
+*   **[Usage Guide (DOC_USE.md)](DOC_USE.md):** Learn how to use `LollmsClient`, different bindings, modality features, function calling with MCP, and high-level operations.
+*   **[Developer Guide (DOC_DEV.md)](DOC_DEV.md):** Understand the architecture, how to create new bindings (LLM, modality, MCP), and contribute to the library.
 
 ## Core Concepts
 
@@ -104,8 +153,9 @@ graph LR
 
     subgraph LollmsClient_Core
         LC -- Manages --> LLB[LLM Binding];
-        LC -- Provides Access To --> TL[TasksLibrary];
-        LC -- Provides Access To --> FCL[FunctionCalling_Library];
+        LC -- Manages --> MCPB[MCP Binding];
+        LC -- Orchestrates --> MCP_Interaction[generate_with_mcp];
+        LC -- Provides --> HighLevelOps[High-Level Ops<br>(summarize, deep_analyze etc.)];
         LC -- Provides Access To --> DM[DiscussionManager];
         LC -- Provides Access To --> ModalityBindings[TTS, TTI, STT etc.];
     end
@@ -118,14 +168,19 @@ graph LR
         LLB --> LocalHF[Local HuggingFace<br>(transformers / vLLM)];
     end
 
-    ModalityBindings --> ModalityServices[Modality Services<br>(e.g., LoLLMs Server TTS/TTI)];
+    MCP_Interaction --> MCPB;
+    MCPB --> LocalTools[Local Python Tools<br>(via local_mcp)];
+    MCPB --> RemoteTools[Remote MCP Tool Servers<br>(Future Potential)];
+
+
+    ModalityBindings --> ModalityServices[Modality Services<br>(e.g., LoLLMs Server TTS/TTI, local Bark/XTTS)];
 ```
 
-*   **`LollmsClient`**: The central class for all interactions. It holds the currently active LLM binding and provides access to modality bindings and helper libraries.
+*   **`LollmsClient`**: The central class for all interactions. It holds the currently active LLM binding, an optional MCP binding, and provides access to modality bindings and high-level operations.
 *   **LLM Bindings**: These are plugins that allow `LollmsClient` to communicate with different LLM backends. You choose a binding (e.g., `"ollama"`, `"lollms"`, `"pythonllamacpp"`) when you initialize `LollmsClient`.
+*   **🔧 MCP Bindings**: Enable tool use and function calling. `lollms-client` includes `local_mcp` for executing Python tools. It discovers tools from a specified folder (or uses its default set), each defined by a `.py` script and a `.mcp.json` metadata file.
 *   **Modality Bindings**: Similar to LLM bindings, but for services like Text-to-Speech (`tts`), Text-to-Image (`tti`), etc.
-*   **`TasksLibrary`**: Offers high-level functions for common AI tasks (summarization, Q&A) built on top of `LollmsClient`.
-*   **`FunctionCalling_Library`**: Enables you to define Python functions that the LLM can request to execute, allowing for tool usage.
+*   **High-Level Operations**: Methods directly on `LollmsClient` (e.g., `sequential_summarize`, `deep_analyze`, `generate_code`, `yes_no`) for performing complex, multi-step AI tasks.
 *   **`LollmsDiscussion`**: Helps manage and format conversation histories for chat applications.
 
 ## Examples
@@ -134,8 +189,8 @@ The `examples/` directory in this repository contains a rich set of scripts demo
 *   Basic text generation with different bindings.
 *   Streaming and non-streaming examples.
 *   Multimodal generation (text with images).
-*   Using `TasksLibrary` for summarization and Q&A.
-*   Implementing and using function calls.
+*   Using built-in methods for summarization and Q&A.
+*   Implementing and using function calls with **`generate_with_mcp`** and the `local_mcp` binding (see `examples/function_calling_with_local_custom_mcp.py` and `examples/local_mcp.py`).
 *   Text-to-Speech and Text-to-Image generation.
 
 Explore these examples to see `lollms-client` in action!

lollms_client-0.19.1/examples/function_calling_with_local_custom_mcp.py

@@ -0,0 +1,250 @@
+from lollms_client import LollmsClient, MSG_TYPE
+from ascii_colors import ASCIIColors, trace_exception
+from pathlib import Path
+import json # For pretty printing results
+
+# --- Configuration ---
+# LLM Configuration
+LLM_BINDING_NAME = "ollama"
+OLLAMA_HOST_ADDRESS = "http://localhost:11434" # Default Ollama host
+# Ensure you have a model capable of following instructions and generating JSON.
+# Mistral, Llama 3, or Phi-3 variants often work well.
+OLLAMA_MODEL_NAME = "mistral-nemo:latest" # Or "llama3:latest", "phi3:latest" - ensure it's pulled
+
+# Local MCP Binding Configuration
+# This path should point to the directory containing your tool subdirectories
+# (e.g., 'get_weather/', 'sum_numbers/')
+# For this example, we assume 'temp_mcp_tools_for_test' is in the parent directory
+# of this examples folder.
+TOOLS_FOLDER = Path(__file__).parent.parent / "temp_mcp_tools_for_test"
+
+# Function Calling Parameters
+MAX_LLM_ITERATIONS_FOR_TOOL_CALLS = 3 # How many times LLM can decide to call a tool in a sequence
+MAX_TOOL_CALLS_PER_TURN = 2 # Max distinct tools executed per user prompt
+
+# --- Helper to Create Dummy Tools (if they don't exist) ---
+def ensure_dummy_tools_exist(base_tools_dir: Path):
+    if not base_tools_dir.exists():
+        ASCIIColors.info(f"Creating dummy tools directory: {base_tools_dir}")
+        base_tools_dir.mkdir(parents=True, exist_ok=True)
+
+    tool_defs = {
+        "get_weather": {
+            "mcp": {
+                "name": "get_weather",
+                "description": "Fetches the current weather for a given city.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "city": {"type": "string", "description": "The city name."},
+                        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"}
+                    },
+                    "required": ["city"]
+                },
+                "output_schema": {
+                    "type": "object",
+                    "properties": {
+                        "temperature": {"type": "number"}, "condition": {"type": "string"}, "unit": {"type": "string"}
+                    }
+                }
+            },
+            "py": """
+import random
+def execute(params: dict) -> dict:
+    city = params.get("city")
+    unit = params.get("unit", "celsius")
+    if not city: return {"error": "City not provided"}
+    conditions = ["sunny", "cloudy", "rainy", "snowy", "windy"]
+    temp = random.randint(-5 if unit == "celsius" else 23, 30 if unit == "celsius" else 86)
+    return {"temperature": temp, "condition": random.choice(conditions), "unit": unit}
+"""
+        },
+        "sum_numbers": {
+            "mcp": {
+                "name": "sum_numbers",
+                "description": "Calculates the sum of a list of numbers.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {"numbers": {"type": "array", "items": {"type": "number"}}},
+                    "required": ["numbers"]
+                },
+                "output_schema": {"type": "object", "properties": {"sum": {"type": "number"}}}
+            },
+            "py": """
+def execute(params: dict) -> dict:
+    numbers = params.get("numbers", [])
+    if not isinstance(numbers, list) or not all(isinstance(n, (int, float)) for n in numbers):
+        return {"error": "Invalid input: 'numbers' must be a list of numbers."}
+    return {"sum": sum(numbers)}
+"""
+        }
+    }
+
+    for tool_name, files_content in tool_defs.items():
+        tool_dir = base_tools_dir / tool_name
+        tool_dir.mkdir(exist_ok=True)
+        
+        mcp_file = tool_dir / f"{tool_name}.mcp.json"
+        py_file = tool_dir / f"{tool_name}.py"
+
+        if not mcp_file.exists():
+            with open(mcp_file, "w") as f:
+                json.dump(files_content["mcp"], f, indent=2)
+            ASCIIColors.info(f"Created MCP definition for {tool_name}")
+        
+        if not py_file.exists():
+            with open(py_file, "w") as f:
+                f.write(files_content["py"])
+            ASCIIColors.info(f"Created Python code for {tool_name}")
+
+# --- Callback for streaming ---
+def function_calling_stream_callback(chunk: str, msg_type: MSG_TYPE, metadata: dict = None, turn_history: list = None) -> bool:
+    """
+    Callback to handle streamed output during function calling.
+    """
+    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:  # LLM generating text
+        ASCIIColors.success(chunk, end="", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_START:
+        step_type = metadata.get("type", "step") if metadata else "step"
+        step_info = metadata.get("tool_name", "") if metadata and "tool_name" in metadata else chunk
+        ASCIIColors.info(f">> Starting {step_type}: {step_info}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END:
+        step_type = metadata.get("type", "step") if metadata else "step"
+        step_info = metadata.get("tool_name", "") if metadata and "tool_name" in metadata else chunk
+        if metadata and "result" in metadata:
+            ASCIIColors.success(f"<< Finished {step_type}: {step_info} -> Result: {json.dumps(metadata['result'])}", flush=True)
+        else:
+            ASCIIColors.success(f"<< Finished {step_type}: {step_info}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_INFO:
+        if metadata and metadata.get("type") == "tool_call_request":
+            ASCIIColors.info(f"AI requests to call tool: {metadata.get('name')} with params: {metadata.get('params')}", flush=True)
+        else:
+            ASCIIColors.info(f"INFO: {chunk}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_EXCEPTION:
+        ASCIIColors.error(f"ERROR in stream: {chunk}", flush=True)
+
+    # Optional debug info:
+    # ASCIIColors.info(f"DEBUG Turn History (so far): {turn_history}")
+    return True
+
+
+
+def run_function_calling_example():
+    ASCIIColors.red("--- LoLLMs Client with Local MCP Function Calling Example ---")
+    
+    ensure_dummy_tools_exist(TOOLS_FOLDER) # Make sure our example tools are present
+
+    try:
+        ASCIIColors.magenta("\n1. Initializing LollmsClient...")
+        # MCP binding config is passed directly to the binding constructor
+        mcp_binding_configuration = {"tools_folder_path": str(TOOLS_FOLDER)}
+        
+        lc = LollmsClient(
+            binding_name=LLM_BINDING_NAME,
+            host_address=OLLAMA_HOST_ADDRESS,
+            model_name=OLLAMA_MODEL_NAME,
+            mcp_binding_name="local_mcp", # Activate the LocalMCP binding
+            mcp_binding_config=mcp_binding_configuration, # Pass its specific config
+            # Optional: Configure default LLM generation params if needed
+            temperature=0.2, # Lower temp for more focused tool decisions / final answer
+            n_predict=1024
+        )
+        ASCIIColors.green("LollmsClient initialized successfully.")
+        if lc.mcp:
+            ASCIIColors.info(f"MCP Binding '{lc.mcp.binding_name}' loaded.")
+            discovered_tools_on_init = lc.mcp.discover_tools()
+            ASCIIColors.info(f"Tools discovered by MCP binding on init: {[t['name'] for t in discovered_tools_on_init]}")
+        else:
+            ASCIIColors.error("MCP binding was not loaded correctly. Aborting.")
+            return
+
+        # --- Example Interaction 1: Weather Request ---
+        ASCIIColors.magenta("\n2. Example 1: Asking for weather")
+        user_prompt_weather = "What's the weather like in Paris today, and can you tell me in Fahrenheit?"
+        ASCIIColors.blue(f"User: {user_prompt_weather}")
+        ASCIIColors.yellow(f"AI thinking and interacting with tools (streaming output):")
+
+        weather_result = lc.generate_with_mcp(
+            prompt=user_prompt_weather,
+            # tools=None, # Let it discover from the binding
+            max_tool_calls=MAX_TOOL_CALLS_PER_TURN,
+            max_llm_iterations=MAX_LLM_ITERATIONS_FOR_TOOL_CALLS,
+            streaming_callback=function_calling_stream_callback,
+            # interactive_tool_execution=True # Uncomment to confirm tool calls
+        )
+        print("\n--- End of AI Response for Weather ---")
+        if weather_result["error"]:
+            ASCIIColors.error(f"Error in weather example: {weather_result['error']}")
+        else:
+            ASCIIColors.cyan(f"\nFinal Answer (Weather): {weather_result['final_answer']}")
+        ASCIIColors.info("\nTool Calls Made (Weather Example):")
+        for tc in weather_result["tool_calls"]:
+            print(f"  - Tool: {tc['name']}, Params: {tc['params']}, Result: {json.dumps(tc['result'])}")
+
+
+        # --- Example Interaction 2: Summation Request ---
+        ASCIIColors.magenta("\n3. Example 2: Asking to sum numbers")
+        user_prompt_sum = "Hey, can you please calculate the sum of 15.5, 25, and -5.5 for me?"
+        ASCIIColors.blue(f"User: {user_prompt_sum}")
+        ASCIIColors.yellow(f"AI thinking and interacting with tools (streaming output):")
+
+        sum_result_data = lc.generate_with_mcp(
+            prompt=user_prompt_sum,
+            max_tool_calls=MAX_TOOL_CALLS_PER_TURN,
+            max_llm_iterations=MAX_LLM_ITERATIONS_FOR_TOOL_CALLS,
+            streaming_callback=function_calling_stream_callback
+        )
+        print("\n--- End of AI Response for Sum ---")
+        if sum_result_data["error"]:
+            ASCIIColors.error(f"Error in sum example: {sum_result_data['error']}")
+        else:
+            ASCIIColors.cyan(f"\nFinal Answer (Sum): {sum_result_data['final_answer']}")
+        ASCIIColors.info("\nTool Calls Made (Sum Example):")
+        for tc in sum_result_data["tool_calls"]:
+            print(f"  - Tool: {tc['name']}, Params: {tc['params']}, Result: {json.dumps(tc['result'])}")
+
+
+        # --- Example Interaction 3: Multi-step (hypothetical, weather then sum) ---
+        ASCIIColors.magenta("\n4. Example 3: Multi-step (Weather, then maybe sum if AI decides)")
+        user_prompt_multi = "What's the weather in Berlin? And also, what's 100 + 200 + 300?"
+        ASCIIColors.blue(f"User: {user_prompt_sum}")
+        ASCIIColors.yellow(f"AI thinking and interacting with tools (streaming output):")
+
+        multi_result_data = lc.generate_with_mcp(
+            prompt=user_prompt_multi,
+            max_tool_calls=MAX_TOOL_CALLS_PER_TURN, # Allow up to 2 different tools
+            max_llm_iterations=MAX_LLM_ITERATIONS_FOR_TOOL_CALLS +1, # Allow a bit more LLM thinking
+            streaming_callback=function_calling_stream_callback
+        )
+        print("\n--- End of AI Response for Multi-step ---")
+        if multi_result_data["error"]:
+            ASCIIColors.error(f"Error in multi-step example: {multi_result_data['error']}")
+        else:
+            ASCIIColors.cyan(f"\nFinal Answer (Multi-step): {multi_result_data['final_answer']}")
+        ASCIIColors.info("\nTool Calls Made (Multi-step Example):")
+        for tc in multi_result_data["tool_calls"]:
+            print(f"  - Tool: {tc['name']}, Params: {tc['params']}, Result: {json.dumps(tc['result'])}")
+
+
+    except ValueError as ve: # Catch init errors
+        ASCIIColors.error(f"Initialization Error: {ve}")
+        trace_exception(ve)
+    except ConnectionRefusedError:
+        ASCIIColors.error(f"Connection refused. Is the Ollama server running at {OLLAMA_HOST_ADDRESS}?")
+    except Exception as e:
+        ASCIIColors.error(f"An unexpected error occurred: {e}")
+        trace_exception(e)
+    finally:
+        ASCIIColors.info(f"If dummy tools were created, they are in: {TOOLS_FOLDER.resolve()}")
+        # Consider cleaning up TOOLS_FOLDER if it was created purely for this test run
+        # For this example, we'll leave them.
+        # import shutil
+        # if "ensure_dummy_tools_exist" in globals() and TOOLS_FOLDER.exists() and "temp_mcp_tools_for_test" in str(TOOLS_FOLDER):
+        #     if input(f"Clean up dummy tools at {TOOLS_FOLDER}? (y/n): ").lower() == 'y':
+        #         shutil.rmtree(TOOLS_FOLDER)
+        #         ASCIIColors.info("Cleaned up dummy tools folder.")
+
+    ASCIIColors.red("\n--- Example Finished ---")
+
+if __name__ == "__main__":
+    run_function_calling_example()