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

{lollms_client-0.19.5/lollms_client.egg-info → lollms_client-0.19.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lollms_client
-Version: 0.19.5
+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.6/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-0.19.5 → lollms_client-0.19.6}/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.5" # Updated version
+__version__ = "0.19.6" # Updated version
 
 # Optionally, you could define __all__ if you want to be explicit about exports
 __all__ = [

{lollms_client-0.19.5 → lollms_client-0.19.6/lollms_client.egg-info}/PKG-INFO

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

@@ -1,189 +0,0 @@
-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
-
-# --- Dependency Management for the Search Tool ---
-# Ensure the duckduckgo_search library is installed for our RAG query function.
-try:
-    import pipmaster as pm
-    pm.ensure_packages(["duckduckgo_search"])
-    from duckduckgo_search import DDGS
-    _ddgs_installed = True
-except Exception as e_dep:
-    _ddgs_installed = False
-    ASCIIColors.error(f"Could not ensure/import duckduckgo_search: {e_dep}")
-    ASCIIColors.warning("The RAG function in this example will not work.")
-    DDGS = None
-# --- End Dependency Management ---
-
-
-def internet_rag_query_function(
-    query_text: str,
-    vectorizer_name: Optional[str] = None, # Not used for this keyword-based search
-    top_k: int = 5,
-    min_similarity_percent: float = 0.0 # Not used for this keyword-based search
-) -> List[Dict[str, Any]]:
-    """
-    A RAG-compatible query function that performs a live internet search using DuckDuckGo.
-
-    Args:
-        query_text: The search query.
-        vectorizer_name: Ignored by this function.
-        top_k: The maximum number of search results to return.
-        min_similarity_percent: Ignored by this function.
-
-    Returns:
-        A list of dictionaries, each formatted for RAG with 'document', 'content', and 'similarity'.
-    """
-    if not _ddgs_installed:
-        ASCIIColors.error("duckduckgo_search library is not available. Cannot perform internet search.")
-        return []
-
-    ASCIIColors.magenta(f"  [INTERNET RAG] Searching web for: '{query_text}', max_results={top_k}")
-    formatted_results = []
-    try:
-        with DDGS() as ddgs:
-            # Fetch search results from DuckDuckGo
-            search_results = ddgs.text(keywords=query_text, max_results=top_k)
-            
-            if not search_results:
-                ASCIIColors.yellow("  [INTERNET RAG] DuckDuckGo returned no results for this query.")
-                return []
-
-            for i, result in enumerate(search_results):
-                # Format the search result into the structure expected by generate_text_with_rag
-                # 'document' will be the URL.
-                # 'content' will be a combination of title and snippet.
-                # 'similarity' is emulated based on rank, as DDG doesn't provide a score.
-                formatted_results.append({
-                    "document": result.get("href", "#"),
-                    "similarity": round(100.0 - (i * (10.0 / top_k)), 2), # Create a descending score
-                    "content": f"Title: {result.get('title', 'N/A')}\nSnippet: {result.get('body', 'N/A')}"
-                })
-        
-        ASCIIColors.magenta(f"  [INTERNET RAG] Found {len(formatted_results)} results.")
-        return formatted_results
-
-    except Exception as e:
-        trace_exception(e)
-        ASCIIColors.error(f"  [INTERNET RAG] An error occurred during search: {e}")
-        return []
-
-# --- Streaming Callback for RAG and LLM ---
-# (This is the same useful callback from the previous example)
-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:
-        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"Retrieved: {num_chunks} sources")
-        if decision: end_info.append(f"LLM Decision: NeedMore={decision.get('need_more_data')}, Summary: '{str(decision.get('new_information_summary'))[:40]}...'")
-        
-        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("--- Internet Search with Multi-Hop RAG Example ---")
-
-    LLM_BINDING_NAME = "ollama"
-    LLM_MODEL_NAME = "mistral-nemo:latest" # Nemo is good with JSON and reasoning
-
-    if not _ddgs_installed:
-        ASCIIColors.error("Cannot run this example because the 'duckduckgo-search' library is not installed.")
-        exit(1)
-
-    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}")
-
-        # --- Test Case 1: Classic RAG with Internet Search ---
-        ASCIIColors.cyan("\n\n--- Test Case 1: Classic RAG (max_rag_hops = 0) using Internet Search ---")
-        classic_rag_prompt = "What is the James Webb Space Telescope and what was its launch date?"
-        ASCIIColors.blue(f"User Prompt: {classic_rag_prompt}")
-
-        classic_rag_result = lc.generate_text_with_rag(
-            prompt=classic_rag_prompt,
-            rag_query_function=internet_rag_query_function,
-            max_rag_hops=0,
-            rag_top_k=3,
-            streaming_callback=rag_streaming_callback,
-            n_predict=300
-        )
-        print("\n--- End of Classic RAG ---")
-        ASCIIColors.magenta("\nClassic RAG Final Output Details:")
-        print(f"  Final Answer (first 150 chars): {classic_rag_result.get('final_answer', '')[:150]}...")
-        print(f"  Error: {classic_rag_result.get('error')}")
-        print(f"  Total Unique Sources Retrieved: {len(classic_rag_result.get('all_retrieved_sources', []))}")
-        if classic_rag_result.get('all_retrieved_sources'):
-            print("  Retrieved Sources (URLs):")
-            for source in classic_rag_result['all_retrieved_sources']:
-                print(f"    - {source.get('document')}")
-
-        # --- Test Case 2: Multi-Hop RAG with Internet Search ---
-        ASCIIColors.cyan("\n\n--- Test Case 2: Multi-Hop RAG (max_rag_hops = 2) using Internet Search ---")
-        multihop_prompt = "First, find out what the TRAPPIST-1 system is. Then, search for recent news about its planets from the James Webb Space Telescope."
-        ASCIIColors.blue(f"User Prompt: {multihop_prompt}")
-        
-        multihop_rag_result = lc.generate_text_with_rag(
-            prompt=multihop_prompt,
-            rag_query_function=internet_rag_query_function,
-            rag_query_text=None, # Let the LLM generate the first query
-            max_rag_hops=2, # Allow up to two separate search queries
-            rag_top_k=2,
-            streaming_callback=rag_streaming_callback,
-            n_predict=400,
-        )
-        print("\n--- End of Multi-Hop RAG ---")
-        ASCIIColors.magenta("\nMulti-Hop RAG Final Output Details:")
-        print(f"  Final Answer (first 150 chars): {multihop_rag_result.get('final_answer', '')[:150]}...")
-        print(f"  Error: {multihop_rag_result.get('error')}")
-        print(f"  Number of Hops Made: {len(multihop_rag_result.get('rag_hops_history', []))}")
-        for i, hop_info in enumerate(multihop_rag_result.get('rag_hops_history', [])):
-            print(f"    Hop {i+1} Query: '{hop_info.get('query')}'")
-            print(f"    Hop {i+1} Retrieved Count: {len(hop_info.get('retrieved_chunks_details',[]))}")
-            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.get('all_retrieved_sources', []))}")
-        if multihop_rag_result.get('all_retrieved_sources'):
-            print("  All Retrieved Sources (URLs):")
-            for source in multihop_rag_result['all_retrieved_sources']:
-                print(f"    - {source.get('document')}")
-
-
-    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--- Internet Search RAG Example Finished ---")