lollms-client 0.19.0__tar.gz → 0.19.5__tar.gz

{lollms_client-0.19.0 → lollms_client-0.19.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.19.0
+Version: 0.19.5
 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.19.0 → lollms_client-0.19.5}/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.5/examples/generate_text_with_multihop_rag_example.py

@@ -0,0 +1,211 @@
+from lollms_client import LollmsClient, MSG_TYPE
+from ascii_colors import ASCIIColors, trace_exception
+from typing import List, Dict, Any, Optional, Callable
+import json
+from pathlib import Path
+
+# --- Mock RAG Implementation ---
+# In a real application, this would interact with your vector database (Pinecone, ChromaDB, FAISS, etc.)
+# and use a real sentence transformer for vectorization.
+
+MOCK_KNOWLEDGE_BASE = {
+    "python_basics.md": [
+        {"chunk_id": 1, "text": "Python is a high-level, interpreted programming language known for its readability and versatility. It was created by Guido van Rossum and first released in 1991."},
+        {"chunk_id": 2, "text": "Key features of Python include dynamic typing, automatic memory management (garbage collection), and a large standard library. It supports multiple programming paradigms, such as procedural, object-oriented, and functional programming."},
+        {"chunk_id": 3, "text": "Common applications of Python include web development (e.g., Django, Flask), data science (e.g., Pandas, NumPy, Scikit-learn), machine learning, artificial intelligence, automation, and scripting."},
+    ],
+    "javascript_info.js": [
+        {"chunk_id": 1, "text": "JavaScript is a scripting language primarily used for front-end web development to create interactive effects within web browsers. It is also used in back-end development (Node.js), mobile app development, and game development."},
+        {"chunk_id": 2, "text": "JavaScript is dynamically typed, prototype-based, and multi-paradigm. Along with HTML and CSS, it is one of the core technologies of the World Wide Web."},
+        {"chunk_id": 3, "text": "Popular JavaScript frameworks and libraries include React, Angular, Vue.js for front-end, and Express.js for Node.js back-end applications."},
+    ],
+    "ai_concepts.txt": [
+        {"chunk_id": 1, "text": "Artificial Intelligence (AI) refers to the simulation of human intelligence in machines that are programmed to think like humans and mimic their actions. The term may also be applied to any machine that exhibits traits associated with a human mind such as learning and problem-solving."},
+        {"chunk_id": 2, "text": "Machine Learning (ML) is a subset of AI that provides systems the ability to automatically learn and improve from experience without being explicitly programmed. Deep Learning (DL) is a further subset of ML based on artificial neural networks with representation learning."},
+        {"chunk_id": 3, "text": "Retrieval Augmented Generation (RAG) is an AI framework for improving the quality of LLM-generated responses by grounding the model on external sources of knowledge to supplement the LLM’s internal representation of information."},
+    ]
+}
+
+def mock_rag_query_function(
+    query_text: str,
+    vectorizer_name: Optional[str] = None, # Ignored in mock
+    top_k: int = 3,
+    min_similarity_percent: float = 0.0 # Ignored in mock, simple keyword match
+) -> List[Dict[str, Any]]:
+    """
+    A mock RAG query function.
+    Performs a simple keyword search in the MOCK_KNOWLEDGE_BASE.
+    """
+    ASCIIColors.magenta(f"  [MOCK RAG] Querying with: '{query_text}', top_k={top_k}")
+    results = []
+    query_lower = query_text.lower()
+    
+    all_chunks = []
+    for file_path, chunks_in_file in MOCK_KNOWLEDGE_BASE.items():
+        for chunk_data in chunks_in_file:
+            all_chunks.append({"file_path": file_path, **chunk_data})
+
+    # Simple keyword matching and scoring (very basic)
+    scored_chunks = []
+    for chunk_info in all_chunks:
+        score = 0
+        for keyword in query_lower.split():
+            if keyword in chunk_info["text"].lower() and len(keyword)>2: # Basic relevance
+                score += 1
+        if "python" in query_lower and "python" in chunk_info["file_path"].lower(): score+=5
+        if "javascript" in query_lower and "javascript" in chunk_info["file_path"].lower(): score+=5
+        if "ai" in query_lower and "ai" in chunk_info["file_path"].lower(): score+=3
+
+
+        if score > 0 : # Only include if some keywords match
+            # Simulate similarity percentage (higher score = higher similarity)
+            similarity = min(100.0, score * 20.0 + 40.0) # Arbitrary scaling
+            if similarity >= min_similarity_percent:
+                scored_chunks.append({
+                    "file_path": chunk_info["file_path"],
+                    "chunk_text": chunk_info["text"],
+                    "similarity_percent": similarity,
+                    "_score_for_ranking": score # Internal score for sorting
+                })
+    
+    # Sort by internal score (descending) and take top_k
+    scored_chunks.sort(key=lambda x: x["_score_for_ranking"], reverse=True)
+    results = [
+        {"file_path": c["file_path"], "chunk_text": c["chunk_text"], "similarity_percent": c["similarity_percent"]}
+        for c in scored_chunks[:top_k]
+    ]
+    ASCIIColors.magenta(f"  [MOCK RAG] Found {len(results)} relevant chunks.")
+    return results
+
+# --- Streaming Callback for RAG and LLM ---
+def rag_streaming_callback(
+    chunk: str, 
+    msg_type: MSG_TYPE, 
+    metadata: Optional[Dict] = None, 
+    turn_history: Optional[List] = None # history of this specific RAG turn
+) -> bool:
+    """
+    Handles various stages of RAG and final LLM generation.
+    """
+    metadata = metadata or {}
+    turn_history = turn_history or [] # Should be populated by LollmsClient
+
+    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK: # Final answer chunks
+        ASCIIColors.success(chunk, end="", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_START:
+        step_type = metadata.get("type", "step")
+        hop = metadata.get("hop", "")
+        info = metadata.get("query", chunk) if step_type == "rag_query_generation" or step_type == "rag_retrieval" else chunk
+        ASCIIColors.yellow(f"\n>> RAG Step Start (Hop {hop}): {step_type} - Info: {str(info)[:100]}...", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END:
+        step_type = metadata.get("type", "step")
+        hop = metadata.get("hop", "")
+        num_chunks = metadata.get("num_chunks", "")
+        query = metadata.get("query", "")
+        decision = metadata.get("decision", "")
+        
+        info_str = ""
+        if step_type == "rag_query_generation" and query: info_str = f"Generated Query: {query}"
+        elif step_type == "rag_retrieval": info_str = f"Retrieved {num_chunks} chunks"
+        elif step_type == "rag_llm_decision": info_str = f"LLM Decision: {json.dumps(decision)}"
+        elif step_type == "final_answer_generation": info_str = "Final answer generation complete."
+        else: info_str = chunk
+
+        ASCIIColors.green(f"\n<< RAG Step End (Hop {hop}): {step_type} - {info_str}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_EXCEPTION:
+        ASCIIColors.error(f"\nError in RAG stream: {chunk}", flush=True)
+    
+    # You can inspect turn_history here if needed:
+    # ASCIIColors.debug(f"Current RAG Turn History: {turn_history}")
+    return True
+
+# --- Main Example ---
+if __name__ == "__main__":
+    ASCIIColors.red("--- Multi-Hop RAG Example with LollmsClient ---")
+
+    # LLM Configuration (use a model good at instruction following and JSON)
+    # Ensure your Ollama server is running and has this model pulled.
+    LLM_BINDING_NAME = "ollama"
+    LLM_MODEL_NAME = "qwen3:4b" # or llama3, phi3 etc.
+    # LLM_MODEL_NAME = "qwen2:1.5b" # Smaller model for quicker tests, but might struggle with complex JSON
+
+    try:
+        lc = LollmsClient(
+            binding_name=LLM_BINDING_NAME,
+            model_name=LLM_MODEL_NAME,
+            temperature=0.1, # Default temp for final answer if not overridden
+            # Other LollmsClient params as needed
+        )
+        ASCIIColors.green(f"LollmsClient initialized with LLM: {LLM_BINDING_NAME}/{LLM_MODEL_NAME}")
+
+        # --- Test Case 1: Classic RAG (max_rag_hops = 0) ---
+        ASCIIColors.cyan("\n\n--- Test Case 1: Classic RAG (max_rag_hops = 0) ---")
+        classic_rag_prompt = "What are the key features of Python?"
+        ASCIIColors.blue(f"User Prompt: {classic_rag_prompt}")
+
+        classic_rag_result = lc.generate_text_with_rag(
+            prompt=classic_rag_prompt,
+            rag_query_function=mock_rag_query_function,
+            # rag_query_text=None, # Will use `prompt` for query
+            max_rag_hops=0,
+            rag_top_k=2, # Get 2 best chunks
+            rag_min_similarity_percent=50.0,
+            streaming_callback=rag_streaming_callback,
+            n_predict=1024 # Max tokens for final answer
+        )
+        print("\n--- End of Classic RAG ---")
+        ASCIIColors.magenta("\nClassic RAG Final Output:")
+        print(json.dumps(classic_rag_result, indent=2))
+
+
+        # --- Test Case 2: Multi-Hop RAG (max_rag_hops = 1) ---
+        ASCIIColors.cyan("\n\n--- Test Case 2: Multi-Hop RAG (max_rag_hops = 1) ---")
+        multihop_prompt_1 = "Compare Python and JavaScript for web development based on their common applications and core technologies."
+        ASCIIColors.blue(f"User Prompt: {multihop_prompt_1}")
+
+        multihop_rag_result_1 = lc.generate_text_with_rag(
+            prompt=multihop_prompt_1,
+            rag_query_function=mock_rag_query_function,
+            # rag_query_text="Python web development applications", # Optional: provide an initial query
+            max_rag_hops=1, # Allow one hop for LLM to refine search or decide
+            rag_top_k=2,
+            rag_min_similarity_percent=60.0,
+            streaming_callback=rag_streaming_callback,
+            n_predict=1024,
+            rag_hop_query_generation_temperature=0.1, # Focused query gen
+            rag_hop_summary_temperature=0.2 # Focused summary
+        )
+        print("\n--- End of Multi-Hop RAG (1 hop) ---")
+        ASCIIColors.magenta("\nMulti-Hop RAG (1 hop) Final Output:")
+        print(json.dumps(multihop_rag_result_1, indent=2))
+        
+
+        # --- Test Case 3: Multi-Hop RAG (max_rag_hops = 2) - LLM might decide it has enough earlier ---
+        ASCIIColors.cyan("\n\n--- Test Case 3: Multi-Hop RAG (max_rag_hops = 2) ---")
+        multihop_prompt_2 = "Explain Retrieval Augmented Generation (RAG) and its relation to Machine Learning."
+        ASCIIColors.blue(f"User Prompt: {multihop_prompt_2}")
+
+        multihop_rag_result_2 = lc.generate_text_with_rag(
+            prompt=multihop_prompt_2,
+            rag_query_function=mock_rag_query_function,
+            max_rag_hops=2, # Allow up to two refinement hops
+            rag_top_k=1, # Get only the best chunk per hop to force more specific queries
+            rag_min_similarity_percent=50.0,
+            streaming_callback=rag_streaming_callback,
+            n_predict=300
+        )
+        print("\n--- End of Multi-Hop RAG (up to 2 hops) ---")
+        ASCIIColors.magenta("\nMulti-Hop RAG (up to 2 hops) Final Output:")
+        print(json.dumps(multihop_rag_result_2, indent=2))
+
+
+    except ValueError as ve:
+        ASCIIColors.error(f"Initialization or RAG parameter error: {ve}")
+        trace_exception(ve)
+    except ConnectionRefusedError:
+        ASCIIColors.error(f"Connection refused. Is the Ollama server ({LLM_BINDING_NAME}) running?")
+    except Exception as e:
+        ASCIIColors.error(f"An unexpected error occurred: {e}")
+        trace_exception(e)
+
+    ASCIIColors.red("\n--- Multi-Hop RAG Example Finished ---")