lollms-client 0.19.1__py3-none-any.whl → 0.19.6__py3-none-any.whl

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 ---")

examples/internet_search_with_rag.py

@@ -0,0 +1,228 @@
+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
+
+# --- Internet Search RAG Implementation ---
+_duckduckgo_search_installed = False
+_search_installation_error_message = ""
+try:
+    import pipmaster as pm
+    # ensure_packages should be called by the binding init ideally,
+    # but we call it here for the example's standalone execution.
+    pm.ensure_packages(["duckduckgo_search"]) 
+    from duckduckgo_search import DDGS
+    _duckduckgo_search_installed = True
+except Exception as e:
+    _search_installation_error_message = str(e)
+    DDGS = None
+    ASCIIColors.error(f"Failed to import duckduckgo_search: {_search_installation_error_message}")
+    ASCIIColors.info("Please install it: pip install duckduckgo-search")
+
+
+def perform_internet_search_rag(
+    query_text: str,
+    vectorizer_name: Optional[str] = None, # Not used for search
+    top_k: int = 5,
+    min_similarity_percent: float = 0.0 # Not used directly for search filter, but can influence result quality/rank
+) -> List[Dict[str, Any]]:
+    """
+    Performs an internet search using DuckDuckGo and formats results for RAG.
+    Similarity is simulated based on rank.
+    """
+    if not _duckduckgo_search_installed or DDGS is None:
+         ASCIIColors.error("duckduckgo_search is not available. Cannot perform internet search.")
+         return []
+
+    ASCIIColors.magenta(f"  [INTERNET SEARCH] Querying DuckDuckGo for: '{query_text}', max_results={top_k}")
+    search_results_raw = []
+    try:
+        # DDGS().text returns a generator, max_results limits it.
+        # Note: The DDGS library might sometimes return fewer results than max_results.
+        with DDGS() as ddgs:
+            search_results_raw = list(ddgs.text(keywords=query_text, max_results=top_k))
+            
+    except Exception as e:
+        ASCIIColors.error(f"  [INTERNET SEARCH] Search failed: {e}")
+        trace_exception(e)
+        return []
+
+    formatted_results: List[Dict[str, Any]] = []
+    if search_results_raw:
+        for i, r in enumerate(search_results_raw):
+            # Simulate similarity based on rank (rank 1 is highest sim)
+            # Max similarity is 100% for rank 1, decreases linearly or non-linearly.
+            # Simple linear decrease: 100 - (rank * (100 / top_k+1))
+            # Let's use rank-based score: 100% for rank 1, 90% for rank 2, ... 50% for rank 5 etc.
+            # Ensure similarity is above min_similarity_percent if that param was intended as a filter here
+            
+            simulated_similarity = max(0.0, 100.0 - i * (100.0 / (top_k + 1))) # Higher rank = lower sim
+            simulated_similarity = round(simulated_similarity, 2)
+
+            if simulated_similarity >= min_similarity_percent:
+                formatted_results.append({
+                    "file_path": r.get("href", "# Unknown URL"), # Use URL as document identifier
+                    "chunk_text": f"Title: {r.get('title', 'N/A')}\nSnippet: {r.get('body', 'N/A')}", # Combine title and snippet
+                    "similarity_percent": simulated_similarity,
+                })
+            else:
+                 ASCIIColors.debug(f"  [INTERNET SEARCH] Skipping result {i+1} due to low simulated similarity ({simulated_similarity}%)")
+
+    ASCIIColors.magenta(f"  [INTERNET SEARCH] Formatted {len(formatted_results)} results for RAG.")
+    if not formatted_results: ASCIIColors.yellow(f"  [INTERNET SEARCH] No results found for query: '{query_text}' or none met min_similarity_percent.")
+    return formatted_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
+) -> bool:
+    metadata = metadata or {}
+    hop = metadata.get("hop", "")
+    type_info = metadata.get("type", "N/A")
+
+    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:
+        info = metadata.get("query", chunk) if type_info in ["rag_query_generation", "rag_retrieval"] else chunk
+        ASCIIColors.yellow(f"\n>> RAG Hop {hop} | START | {type_info.upper()} | Info: {str(info)[:100]}...", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_STEP_END:
+        num_chunks = metadata.get("num_chunks")
+        query = metadata.get("query")
+        decision = metadata.get("decision")
+        
+        end_info = []
+        if query: end_info.append(f"Query: '{str(query)[:50]}...'")
+        if num_chunks is not None: end_info.append(f"Results: {num_chunks}")
+        if decision: end_info.append(f"LLM Decision: NeedMore={decision.get('need_more_data')}, Summary: '{str(decision.get('new_information_summary'))[:50]}...'")
+        
+        ASCIIColors.green(f"\n<< RAG Hop {hop} | END   | {type_info.upper()} | {' | '.join(end_info) if end_info else chunk}", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_EXCEPTION:
+        ASCIIColors.error(f"\nError in RAG stream: {chunk}", flush=True)
+    
+    return True
+
+# --- Main Example ---
+if __name__ == "__main__":
+    ASCIIColors.red("--- Multi-Hop Internet Search 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 = "mistral:latest" # or llama3, phi3 etc.
+
+    # You could also enable the internet_search tool via MCP,
+    # but this example specifically uses it directly via generate_text_with_rag.
+    # For MCP example, see examples/local_mcp.py
+
+    try:
+        lc = LollmsClient(
+            binding_name=LLM_BINDING_NAME,
+            model_name=LLM_MODEL_NAME,
+            temperature=0.1,
+            ctx_size=4096 
+        )
+        ASCIIColors.green(f"LollmsClient initialized with LLM: {LLM_BINDING_NAME}/{LLM_MODEL_NAME}")
+
+        if not _duckduckgo_search_installed or DDGS is None:
+             ASCIIColors.error("duckduckgo_search is not installed. Cannot run search examples.")
+             exit()
+
+
+        # --- Test Case 1: Classic Search RAG (max_rag_hops = 0) ---
+        ASCIIColors.cyan("\n\n--- Test Case 1: Classic Internet Search RAG (max_rag_hops = 0) ---")
+        classic_search_prompt = "What is the current population of Japan?"
+        ASCIIColors.blue(f"User Prompt: {classic_search_prompt}")
+
+        classic_rag_result = lc.generate_text_with_rag(
+            prompt=classic_search_prompt,
+            rag_query_function=perform_internet_search_rag, # Use the search function
+            max_rag_hops=0,
+            rag_top_k=3, # Get 3 search results
+            rag_min_similarity_percent=50.0, # Only use results with simulated sim >= 50%
+            streaming_callback=rag_streaming_callback,
+            n_predict=250
+        )
+        print("\n--- End of Classic Search RAG ---")
+        ASCIIColors.magenta("\nClassic Search RAG Final Output Structure:")
+        print(f"  Final Answer (first 100 chars): {classic_rag_result.get('final_answer', '')[:100]}...")
+        print(f"  Error: {classic_rag_result.get('error')}")
+        print(f"  Number of Hops: {len(classic_rag_result.get('rag_hops_history', []))}")
+        print(f"  Total Unique Sources Retrieved: {len(classic_rag_result.get('all_retrieved_sources', []))}")
+        if classic_rag_result.get('all_retrieved_sources'):
+            print("  Example Retrieved Source:")
+            source_ex = classic_rag_result['all_retrieved_sources'][0]
+            print(f"    Document (URL): {source_ex.get('document')}")
+            print(f"    Similarity: {source_ex.get('similarity')}%")
+            print(f"    Content (Snippet, first 50 chars): {source_ex.get('content', '')[:50]}...")
+
+
+        # --- Test Case 2: Multi-Hop Search RAG (max_rag_hops = 1) ---
+        ASCIIColors.cyan("\n\n--- Test Case 2: Multi-Hop Internet Search RAG (max_rag_hops = 1) ---")
+        multihop_search_prompt_1 = "Tell me about the latest developments in fusion energy, including any recent news."
+        ASCIIColors.blue(f"User Prompt: {multihop_search_prompt_1}")
+
+        multihop_rag_result_1 = lc.generate_text_with_rag(
+            prompt=multihop_search_prompt_1,
+            rag_query_function=perform_internet_search_rag,
+            rag_query_text=None, # LLM will generate first query
+            max_rag_hops=1, # Allow one refinement hop
+            rag_top_k=2, # Get 2 search results per query
+            rag_min_similarity_percent=50.0,
+            streaming_callback=rag_streaming_callback,
+            n_predict=400,
+            rag_hop_query_generation_temperature=0.1, 
+            rag_hop_summary_temperature=0.2 
+        )
+        print("\n--- End of Multi-Hop Search RAG (1 hop max) ---")
+        ASCIIColors.magenta("\nMulti-Hop Search RAG (1 hop max) Final Output Structure:")
+        print(f"  Final Answer (first 100 chars): {multihop_rag_result_1.get('final_answer', '')[:100]}...")
+        print(f"  Error: {multihop_rag_result_1.get('error')}")
+        print(f"  Number of Hops Made: {len(multihop_rag_result_1.get('rag_hops_history', []))}")
+        for i, hop_info in enumerate(multihop_rag_result_1.get('rag_hops_history', [])):
+            print(f"    Hop {i+1} Query: '{hop_info.get('query')}'")
+            print(f"    Hop {i+1} Results Count: {len(hop_info.get('retrieved_chunks_details',[]))}")
+            print(f"    Hop {i+1} Summary (first 50): '{str(hop_info.get('new_information_summary'))[:50]}...'")
+            print(f"    Hop {i+1} LLM Decision: NeedMoreData={hop_info.get('llm_decision_json',{}).get('need_more_data')}")
+        print(f"  Total Unique Sources Retrieved: {len(multihop_rag_result_1.get('all_retrieved_sources', []))}")
+
+
+        # --- Test Case 3: More complex multi-hop (max_rag_hops = 2) ---
+        ASCIIColors.cyan("\n\n--- Test Case 3: More Complex Multi-Hop Internet Search RAG (max_rag_hops = 2) ---")
+        multihop_search_prompt_2 = "What are the requirements and steps to install the lollms_client python library, and what are some of its key features?"
+        ASCIIColors.blue(f"User Prompt: {multihop_search_prompt_2}")
+
+        multihop_rag_result_2 = lc.generate_text_with_rag(
+            prompt=multihop_search_prompt_2,
+            rag_query_function=perform_internet_search_rag,
+            max_rag_hops=2, # Allow up to two refinement hops
+            rag_top_k=2, # Get 2 results per query
+            rag_min_similarity_percent=40.0, # Lower similarity to maybe get broader initial results
+            streaming_callback=rag_streaming_callback,
+            n_predict=500 # Allow more for the installation steps and features
+        )
+        print("\n--- End of More Complex Multi-Hop Search RAG (up to 2 hops) ---")
+        ASCIIColors.magenta("\nMore Complex Multi-Hop Search RAG (up to 2 hops) Final Output Structure:")
+        print(f"  Final Answer (first 100 chars): {multihop_rag_result_2.get('final_answer', '')[:100]}...")
+        print(f"  Error: {multihop_rag_result_2.get('error')}")
+        print(f"  Number of Hops Made: {len(multihop_rag_result_2.get('rag_hops_history', []))}")
+        for i, hop_info in enumerate(multihop_rag_result_2.get('rag_hops_history', [])):
+            print(f"    Hop {i+1} Query: '{hop_info.get('query')}'")
+            print(f"    Hop {i+1} Results Count: {len(hop_info.get('retrieved_chunks_details',[]))}")
+            print(f"    Hop {i+1} Summary (first 50): '{str(hop_info.get('new_information_summary'))[:50]}...'")
+        print(f"  Total Unique Sources Retrieved: {len(multihop_rag_result_2.get('all_retrieved_sources', []))}")
+
+
+    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 Internet Search Example Finished ---")

lollms_client/__init__.py

@@ -7,7 +7,7 @@ from lollms_client.lollms_utilities import PromptReshaper # Keep general utiliti
 from lollms_client.lollms_mcp_binding import LollmsMCPBinding, LollmsMCPBindingManager
 
 
-__version__ = "0.19.1" # Updated version
+__version__ = "0.19.6" # Updated version
 
 # Optionally, you could define __all__ if you want to be explicit about exports
 __all__ = [

lollms_client/lollms_core.py

@@ -12,7 +12,7 @@ from lollms_client.lollms_ttv_binding import LollmsTTVBinding, LollmsTTVBindingM
 from lollms_client.lollms_ttm_binding import LollmsTTMBinding, LollmsTTMBindingManager
 from lollms_client.lollms_mcp_binding import LollmsMCPBinding, LollmsMCPBindingManager
 
-import json
+import json, re
 from enum import Enum
 import base64
 import requests
@@ -853,6 +853,243 @@ Respond with a JSON object containing ONE of the following structures:
         turn_history.append({"type":"final_answer_generated", "content":final_answer_text})
         return {"final_answer": final_answer_text, "tool_calls": tool_calls_made_this_turn, "error": None}
 
+    # --- RAG ---
+    
+    def generate_text_with_rag(
+        self,
+        prompt: str,
+        rag_query_function: Callable[[str, Optional[str], int, float], List[Dict[str, Any]]],
+        rag_query_text: Optional[str] = None,
+        rag_vectorizer_name: Optional[str] = None,
+        rag_top_k: int = 5,
+        rag_min_similarity_percent: float = 70.0,
+        max_rag_hops: int = 0,
+        images: Optional[List[str]] = None,
+        system_prompt: str = "",
+        n_predict: Optional[int] = None,
+        stream: Optional[bool] = None,
+        temperature: Optional[float] = None,
+        top_k: Optional[int] = None,
+        top_p: Optional[float] = None,
+        repeat_penalty: Optional[float] = None,
+        repeat_last_n: Optional[int] = None,
+        seed: Optional[int] = None,
+        n_threads: Optional[int] = None,
+        ctx_size: int | None = None,
+        streaming_callback: Optional[Callable[[str, MSG_TYPE, Optional[Dict], Optional[List]], bool]] = None,
+        rag_hop_query_generation_temperature: float = 0.2,
+        rag_hop_summary_temperature: float = 0.3,
+        **llm_generation_kwargs
+    ) -> Dict[str, Any]:
+        if not self.binding:
+            return {"final_answer": "", "rag_hops_history": [], "all_retrieved_sources": [], "error": "LLM binding not initialized."}
+
+        turn_rag_history_for_callback: List[Dict[str, Any]] = []
+        accumulated_rag_context_str = ""
+        rag_hops_details_list: List[Dict[str, Any]] = []
+        all_unique_retrieved_chunks_map: Dict[str, Dict[str, Any]] = {} # To store unique chunks by content hash or path+text
+        current_query_for_rag = rag_query_text
+        original_user_prompt = prompt
+
+        for hop_count in range(max_rag_hops + 1):
+            if streaming_callback:
+                streaming_callback(f"Starting RAG Hop {hop_count + 1}", MSG_TYPE.MSG_TYPE_STEP, {"type": "rag_hop_start", "hop": hop_count + 1}, turn_rag_history_for_callback)
+
+            # 1. Determine/Generate RAG Query Text
+            if hop_count > 0 or (current_query_for_rag is None and max_rag_hops > 0):
+                if streaming_callback:
+                    streaming_callback("LLM generating refined RAG query...", MSG_TYPE.MSG_TYPE_STEP_START, {"type": "rag_query_generation", "hop": hop_count + 1}, turn_rag_history_for_callback)
+                
+                query_gen_prompt_parts = [
+                    f"{self.system_full_header}You are an expert research assistant. Your task is to formulate the best possible search query to find information relevant to the user's original request, considering the information already gathered.",
+                    f"{self.user_full_header}Original user request: '{original_user_prompt}'"
+                ]
+                if accumulated_rag_context_str:
+                    query_gen_prompt_parts.append(f"Information gathered so far (summaries):\n{accumulated_rag_context_str}")
+                if rag_hops_details_list:
+                    query_gen_prompt_parts.append("Previous search attempts and their summarized findings:")
+                    for prev_hop in rag_hops_details_list:
+                        query_gen_prompt_parts.append(f"  - Queried for: '{prev_hop['query']}', Summary: '{prev_hop.get('new_information_summary', 'N/A')}'")
+                
+                query_gen_prompt_parts.append("Based on this, what is the most effective and specific search query to perform next to get closer to answering the user's request? Output only the search query text, nothing else.")
+                query_gen_prompt_parts.append(self.ai_full_header)
+
+                new_query_text_raw = self.remove_thinking_blocks(self.generate_text(prompt="".join(query_gen_prompt_parts), temperature=rag_hop_query_generation_temperature, n_predict=100, stream=False))
+                if isinstance(new_query_text_raw, dict) and "error" in new_query_text_raw:
+                    return {"final_answer": "", "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": f"Failed to generate RAG query: {new_query_text_raw['error']}"}
+                
+                current_query_for_rag = new_query_text_raw.strip().replace("Search query:", "").replace("Query:", "").strip("\"'")
+                
+                if streaming_callback:
+                    streaming_callback(f"Generated RAG query: {current_query_for_rag}", MSG_TYPE.MSG_TYPE_STEP_END, {"type": "rag_query_generation", "hop": hop_count + 1, "query": current_query_for_rag}, turn_rag_history_for_callback)
+            
+            elif current_query_for_rag is None and max_rag_hops == 0:
+                current_query_for_rag = original_user_prompt
+
+            if not current_query_for_rag:
+                if max_rag_hops > 0 and hop_count < max_rag_hops:
+                    ASCIIColors.warning(f"RAG Hop {hop_count + 1}: Generated query was empty. Skipping hop.")
+                    rag_hops_details_list.append({"query": "EMPTY_QUERY_SKIPPED", "retrieved_chunks_details": [], "new_information_summary": "Skipped due to empty query.", "llm_decision_json": {"need_more_data": True if hop_count < max_rag_hops -1 else False}})
+                    turn_rag_history_for_callback.append({"type":"rag_hop_info", "hop": hop_count + 1, "query": "EMPTY_QUERY_SKIPPED", "summary":"Skipped."})
+                    continue
+                else:
+                    ASCIIColors.warning("RAG query is empty. Proceeding without RAG context.")
+                    break
+
+            # 2. Perform RAG Query
+            if streaming_callback:
+                streaming_callback(f"Querying knowledge base for: '{current_query_for_rag}'...", MSG_TYPE.MSG_TYPE_STEP_START, {"type": "rag_retrieval", "hop": hop_count + 1, "query": current_query_for_rag}, turn_rag_history_for_callback)
+            
+            try:
+                retrieved_chunks_raw = rag_query_function(current_query_for_rag, rag_vectorizer_name, rag_top_k, rag_min_similarity_percent)
+            except Exception as e_rag_query:
+                trace_exception(e_rag_query)
+                return {"final_answer": "", "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": f"RAG query function failed: {e_rag_query}"}
+
+            if streaming_callback:
+                streaming_callback(f"Retrieved {len(retrieved_chunks_raw)} chunks.", MSG_TYPE.MSG_TYPE_STEP_END, {"type": "rag_retrieval", "hop": hop_count + 1, "num_chunks": len(retrieved_chunks_raw)}, turn_rag_history_for_callback)
+
+            current_hop_details = {"query": current_query_for_rag, "retrieved_chunks_details": []}
+            
+            formatted_new_chunks_for_llm_summary = ""
+            if retrieved_chunks_raw:
+                for i, chunk in enumerate(retrieved_chunks_raw):
+                    doc_path = chunk.get('file_path', 'Unknown Document')
+                    similarity = chunk.get('similarity_percent', 'N/A')
+                    content = chunk.get('chunk_text', '')
+                    
+                    chunk_detail_for_history = {"document": doc_path, "similarity": similarity, "content": content}
+                    current_hop_details["retrieved_chunks_details"].append(chunk_detail_for_history)
+                    
+                    # Add to unique list for final output
+                    # Use a combination of path and content to uniquely identify a chunk to avoid duplicates if same content appears from different queries.
+                    # A more robust unique key might involve hashing content if it's very large.
+                    unique_key = f"{doc_path}::{content[:100]}" # Simple key
+                    if unique_key not in all_unique_retrieved_chunks_map:
+                         all_unique_retrieved_chunks_map[unique_key] = chunk_detail_for_history
+
+                    # Format for LLM processing (summary or direct use)
+                    formatted_new_chunks_for_llm_summary += f"Document: {doc_path} (Similarity: {similarity}%)\nContent:\n{content}\n---\n"
+            
+            if not retrieved_chunks_raw:
+                current_hop_details["new_information_summary"] = "No relevant information found for this query."
+                current_hop_details["llm_decision_json"] = {"need_more_data": True if max_rag_hops > 0 and hop_count < max_rag_hops -1 else False, "reasoning_for_decision":"No new information retrieved."}
+                rag_hops_details_list.append(current_hop_details)
+                turn_rag_history_for_callback.append({"type":"rag_hop_info", **current_hop_details})
+                if max_rag_hops == 0 or hop_count >= max_rag_hops -1 :
+                    break
+                else:
+                    accumulated_rag_context_str += f"\n\n---\nAttempted query: '{current_query_for_rag}' - No new information found.\n---"
+                    continue
+
+            if max_rag_hops == 0: # Classic RAG
+                accumulated_rag_context_str += formatted_new_chunks_for_llm_summary
+                current_hop_details["new_information_summary"] = "Directly used in context (classic RAG)."
+                current_hop_details["llm_decision_json"] = {"need_more_data": False}
+                rag_hops_details_list.append(current_hop_details)
+                turn_rag_history_for_callback.append({"type":"rag_hop_info", **current_hop_details})
+                break
+            
+            # Multi-hop: LLM summarizes and decides
+            if streaming_callback:
+                streaming_callback("LLM processing retrieved data and deciding next step...", MSG_TYPE.MSG_TYPE_STEP_START, {"type": "rag_llm_decision", "hop": hop_count + 1}, turn_rag_history_for_callback)
+
+            decision_prompt_llm_parts = [
+                f"{self.system_full_header}You are an AI research assistant. Analyze newly retrieved information against the user's request and prior knowledge, then decide if more searching is needed.",
+                f"{self.user_full_header}Original user request: '{original_user_prompt}'",
+            ]
+            if accumulated_rag_context_str:
+                decision_prompt_llm_parts.append(f"Current accumulated knowledge summary:\n{accumulated_rag_context_str}")
+            decision_prompt_llm_parts.append(f"You just searched for: '{current_query_for_rag}'")
+            decision_prompt_llm_parts.append(f"And found this new information:\n--- New Information Start ---\n{formatted_new_chunks_for_llm_summary}--- New Information End ---")
+            decision_prompt_llm_parts.append(
+                "Task: Provide a concise summary of ONLY the new information relevant to the original request. "
+                "Then, assess if you now have sufficient information to comprehensively answer the user's original request or if another, more targeted search is necessary. "
+                "Respond STRICTLY in the following JSON format, with no other text before or after the JSON block:"
+            )
+            json_template_for_decision = """
+{
+  "new_information_summary": "<Your concise summary of ONLY the new_information relevant to the original_user_request. Focus on what's new and useful. If nothing new is relevant, state that.>",
+  "need_more_data": <true_or_false>,
+  "reasoning_for_decision": "<Briefly explain why you need more data or why you have enough. If needing more, suggest what kind of information is still missing.>"
+}
+"""
+            decision_prompt_llm_parts.append(f"```json\n{json_template_for_decision}\n```")
+            decision_prompt_llm_parts.append(self.ai_full_header)
+
+            llm_decision_json_str = self.generate_code(prompt="".join(decision_prompt_llm_parts), language="json", template=json_template_for_decision, temperature=rag_hop_summary_temperature, max_size=1024)
+
+            if isinstance(llm_decision_json_str, dict) and "error" in llm_decision_json_str:
+                return {"final_answer": "", "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": f"LLM failed to make RAG decision: {llm_decision_json_str['error']}"}
+            if not llm_decision_json_str:
+                 return {"final_answer": "", "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": "LLM provided empty decision for RAG hop."}
+
+            try:
+                llm_decision = json.loads(llm_decision_json_str)
+            except json.JSONDecodeError:
+                try:
+                    match = re.search(r"```json\s*(\{.*?\})\s*```", llm_decision_json_str, re.DOTALL)
+                    if match: llm_decision = json.loads(match.group(1))
+                    else: llm_decision = json.loads(self.extract_code_blocks(llm_decision_json_str, format="markdown")[0]["content"])
+                except Exception as e_json_parse:
+                    trace_exception(e_json_parse)
+                    return {"final_answer": "", "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": f"Failed to parse LLM RAG decision JSON: {llm_decision_json_str}. Error: {e_json_parse}"}
+
+            new_summary = llm_decision.get("new_information_summary", "Summary not provided by LLM.")
+            need_more_data = llm_decision.get("need_more_data", True)
+
+            current_hop_details["new_information_summary"] = new_summary
+            current_hop_details["llm_decision_json"] = llm_decision
+            rag_hops_details_list.append(current_hop_details)
+            turn_rag_history_for_callback.append({"type":"rag_hop_info", **current_hop_details})
+
+            if streaming_callback:
+                streaming_callback(f"LLM decision: Summary='{new_summary[:100]}...', NeedMoreData={need_more_data}", MSG_TYPE.MSG_TYPE_STEP_END, {"type": "rag_llm_decision", "hop": hop_count + 1, "decision": llm_decision}, turn_rag_history_for_callback)
+
+            accumulated_rag_context_str += f"\n\n--- Summary of findings from query '{current_query_for_rag}' (Hop {hop_count + 1}) ---\n{new_summary}\n---"
+            
+            if not need_more_data or hop_count >= max_rag_hops -1 : # Subtract 1 because current hop is finishing
+                break
+
+        # 4. Final Answer Generation
+        if streaming_callback:
+            streaming_callback("LLM generating final answer using all gathered information...", MSG_TYPE.MSG_TYPE_STEP_START, {"type": "final_answer_generation"}, turn_rag_history_for_callback)
+
+        final_answer_prompt_parts = []
+        if system_prompt:
+            final_answer_prompt_parts.append(f"{self.system_full_header}{system_prompt}")
+        
+        final_answer_prompt_parts.append(f"{self.user_full_header}Original request: {original_user_prompt}")
+        if accumulated_rag_context_str:
+            final_answer_prompt_parts.append(f"\nBased on the information I have gathered:\n--- Gathered Context Start ---\n{accumulated_rag_context_str.strip()}\n--- Gathered Context End ---")
+        else:
+            final_answer_prompt_parts.append("\n(No specific information was retrieved from the knowledge base for this request.)")
+        
+        final_answer_prompt_parts.append("\nPlease provide a comprehensive answer to the original request using ONLY the provided gathered context. If the context is insufficient, clearly state that.")
+        final_answer_prompt_parts.append(self.ai_full_header)
+
+        final_answer_llm_prompt = "\n".join(final_answer_prompt_parts)
+        
+        final_answer_streaming_callback = None
+        if streaming_callback:
+            def final_answer_cb_adapter(chunk, msg_type):
+                return streaming_callback(chunk, msg_type, {"type": "final_answer_chunk"}, turn_rag_history_for_callback)
+            final_answer_streaming_callback = final_answer_cb_adapter
+
+        final_answer_text = self.remove_thinking_blocks(self.generate_text(
+            prompt=final_answer_llm_prompt, images=images,
+            n_predict=n_predict, stream=stream, temperature=temperature, top_k=top_k, top_p=top_p,
+            repeat_penalty=repeat_penalty, repeat_last_n=repeat_last_n, seed=seed, n_threads=n_threads,
+            ctx_size=ctx_size, streaming_callback=final_answer_streaming_callback, **llm_generation_kwargs
+        ))
+
+        if streaming_callback:
+            streaming_callback("Final answer generation complete.", MSG_TYPE.MSG_TYPE_STEP_END, {"type": "final_answer_generation"}, turn_rag_history_for_callback)
+
+        if isinstance(final_answer_text, dict) and "error" in final_answer_text:
+            return {"final_answer": "", "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": f"Final answer generation failed: {final_answer_text['error']}"}
+
+        return {"final_answer": final_answer_text, "rag_hops_history": rag_hops_details_list, "all_retrieved_sources": list(all_unique_retrieved_chunks_map.values()), "error": None}
 
     def generate_code(
                         self,

{lollms_client-0.19.1.dist-info → lollms_client-0.19.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.19.1
+Version: 0.19.6
 Summary: A client library for LoLLMs generate endpoint
 Author-email: ParisNeo <parisneoai@gmail.com>
 License: Apache Software License

{lollms_client-0.19.1.dist-info → lollms_client-0.19.6.dist-info}/RECORD

@@ -1,4 +1,6 @@
 examples/function_calling_with_local_custom_mcp.py,sha256=g6wOFRB8-p9Cv7hKmQaGzPvtMX3H77gas01QVNEOduM,12407
+examples/generate_text_with_multihop_rag_example.py,sha256=Z6TbVqThOCHNK6kzIqRnEi76JDxIFlg1-IIMWehZars,11582
+examples/internet_search_with_rag.py,sha256=WBoYFBEjGIFKyKTzezm7lI0bGPNuHFMyoq_8iY32qLY,12434
 examples/local_mcp.py,sha256=w40dgayvHYe01yvekEE0LjcbkpwKjWwJ-9v4_wGYsUk,9113
 examples/simple_text_gen_test.py,sha256=RoX9ZKJjGMujeep60wh5WT_GoBn0O9YKJY6WOy-ZmOc,8710
 examples/simple_text_gen_with_image_test.py,sha256=rR1O5Prcb52UHtJ3c6bv7VuTd1cvbkr5aNZU-v-Rs3Y,9263
@@ -17,9 +19,9 @@ examples/personality_test/chat_test.py,sha256=o2jlpoddFc-T592iqAiA29xk3x27KsdK5D
 examples/personality_test/chat_with_aristotle.py,sha256=4X_fwubMpd0Eq2rCReS2bgVlUoAqJprjkLXk2Jz6pXU,1774
 examples/personality_test/tesks_test.py,sha256=7LIiwrEbva9WWZOLi34fsmCBN__RZbPpxoUOKA_AtYk,1924
 examples/test_local_models/local_chat.py,sha256=slakja2zaHOEAUsn2tn_VmI4kLx6luLBrPqAeaNsix8,456
-lollms_client/__init__.py,sha256=rbZUoiSGIFLwCBjEUsAC68azS9mIfZ9EXmyasnBDbkY,910
+lollms_client/__init__.py,sha256=6_HMLYZ2YejnZPhg5Tomyq6wYfndu9otuy-o7YAinWQ,910
 lollms_client/lollms_config.py,sha256=goEseDwDxYJf3WkYJ4IrLXwg3Tfw73CXV2Avg45M_hE,21876
-lollms_client/lollms_core.py,sha256=psVTrEtHYhjy9h014rHLotBC4Aj72PvG2OV0UAjLcvw,102496
+lollms_client/lollms_core.py,sha256=56wntZAimRfx0qBR_96_1h9_ZKuvY1Uq_kMVs9xg-dE,119768
 lollms_client/lollms_discussion.py,sha256=9b83m0D894jwpgssWYTQHbVxp1gJoI-J947Ui_dRXII,2073
 lollms_client/lollms_js_analyzer.py,sha256=01zUvuO2F_lnUe_0NLxe1MF5aHE1hO8RZi48mNPv-aw,8361
 lollms_client/lollms_llm_binding.py,sha256=bdElz_IBx0zZ-85YTT1fyY_mSoHo46tKIMiHYJlKCkM,9809
@@ -67,8 +69,8 @@ lollms_client/tts_bindings/piper_tts/__init__.py,sha256=0IEWG4zH3_sOkSb9WbZzkeV5
 lollms_client/tts_bindings/xtts/__init__.py,sha256=FgcdUH06X6ZR806WQe5ixaYx0QoxtAcOgYo87a2qxYc,18266
 lollms_client/ttv_bindings/__init__.py,sha256=UZ8o2izQOJLQgtZ1D1cXoNST7rzqW22rL2Vufc7ddRc,3141
 lollms_client/ttv_bindings/lollms/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-lollms_client-0.19.1.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-lollms_client-0.19.1.dist-info/METADATA,sha256=MKuTL8GsNdArHgSQ_xxhqViSdpEVs0cAK4akk5tNGVM,13374
-lollms_client-0.19.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lollms_client-0.19.1.dist-info/top_level.txt,sha256=NI_W8S4OYZvJjb0QWMZMSIpOrYzpqwPGYaklhyWKH2w,23
-lollms_client-0.19.1.dist-info/RECORD,,
+lollms_client-0.19.6.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+lollms_client-0.19.6.dist-info/METADATA,sha256=kI_H4LhMJWMmt1rTJUMP7CdZVlzA-N7RhnyDSHEYJvA,13374
+lollms_client-0.19.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lollms_client-0.19.6.dist-info/top_level.txt,sha256=NI_W8S4OYZvJjb0QWMZMSIpOrYzpqwPGYaklhyWKH2w,23
+lollms_client-0.19.6.dist-info/RECORD,,