lollms-client 0.32.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

examples/generate_game_sfx/generate_game_fx.py

@@ -1,240 +0,0 @@
-# lollms_client/examples/game_sfx_generation/generate_game_sfx.py
-from pathlib import Path
-import time
-import argparse # For command-line arguments
-
-# Ensure pygame is installed for this example
-try:
-    import pipmaster as pm
-    pm.ensure_packages(["pygame"])
-    import pygame
-    PYGAME_AVAILABLE = True
-except ImportError:
-    print("Pygame not found or pipmaster failed. Please install it manually: pip install pygame")
-    PYGAME_AVAILABLE = False
-except Exception as e:
-    print(f"Could not ensure pygame: {e}")
-    PYGAME_AVAILABLE = False
-
-
-from lollms_client import LollmsClient # Removed LollmsDiscussion, LollmsMessage as not used
-from ascii_colors import ASCIIColors, trace_exception
-
-# --- Configuration ---
-# Output directory for generated sound effects
-SFX_OUTPUT_DIR = Path(__file__).parent / "sfx_output"
-SFX_OUTPUT_DIR.mkdir(exist_ok=True)
-
-# Sound effect descriptions. Note: 'duration' is more relevant for audiocraft.
-# Bark's duration is more implicit based on prompt content.
-SOUND_EFFECTS_TO_GENERATE = [
-    {
-        "filename": "sfx_crunch",
-        "prompt": "Sound effect of a single, sharp, dry crunch, like stepping on a crisp autumn leaf or a piece of dry wood breaking.",
-        "duration": 1, # audiocraft specific
-        "bark_params": {"fine_temperature": 0.4, "coarse_temperature": 0.6} # Example bark specific
-    },
-    {
-        "filename": "sfx_death_electronic",
-        "prompt": "Short, impactful electronic death sound effect for a video game character, like a quick digital zap or a brief power-down sound.",
-        "duration": 1.5,
-        "bark_params": {"voice_preset": None} # Try without preset for more raw SFX
-    },
-    {
-        "filename": "sfx_powerup_positive",
-        "prompt": "Bright, positive, short power-up collection sound effect, like a magical chime, a sparkling shimmer, or an uplifting notification. [SFX]",
-        "duration": 1.5
-    },
-    {
-        "filename": "sfx_laser_shot",
-        "prompt": "Sound effect of a futuristic laser gun firing a single shot, a quick 'pew' sound. [SFX: laser pew]",
-        "duration": 0.5
-    },
-    {
-        "filename": "sfx_coin_collect",
-        "prompt": "Classic video game coin collection sound effect, a short, metallic, cheerful 'ding' or 'jingle'. [SFX: coin]",
-        "duration": 0.7
-    }
-]
-
-def generate_sfx(lollms_client: LollmsClient, sfx_info: dict) -> Path | None:
-    """Generates a single sound effect using the LollmsClient's TTM binding."""
-    filename_stem = sfx_info["filename"]
-    prompt = sfx_info["prompt"]
-
-    # Default output format
-    output_format = "wav" # WAV is generally best for SFX in pygame
-    output_path = SFX_OUTPUT_DIR / f"{filename_stem}_{lollms_client.ttm.binding_name}.{output_format}" # Add binding name to filename
-
-    ASCIIColors.cyan(f"\nGenerating SFX using '{lollms_client.ttm.binding_name}': '{filename_stem}'")
-    ASCIIColors.info(f"Prompt: '{prompt[:60]}...'")
-
-
-    if not lollms_client.ttm:
-        ASCIIColors.error("TTM (Text-to-Music/Sound) binding is not available in LollmsClient.")
-        return None
-
-    ttm_params = {"progress": True} # Common param for both
-
-    if lollms_client.ttm.binding_name == "audiocraft":
-        ttm_params["duration"] = sfx_info.get("duration", 1.0)
-        ttm_params["temperature"] = sfx_info.get("audiocraft_temperature", 1.0)
-        ttm_params["cfg_coef"] = sfx_info.get("audiocraft_cfg_coef", 3.0)
-        ASCIIColors.info(f"AudioCraft Params: duration={ttm_params['duration']}, temp={ttm_params['temperature']}, cfg={ttm_params['cfg_coef']}")
-    elif lollms_client.ttm.binding_name == "bark":
-        # Bark duration is implicit. Parameters are different.
-        bark_specific_params = sfx_info.get("bark_params", {})
-        ttm_params["voice_preset"] = bark_specific_params.get("voice_preset", None) # None might be good for SFX
-        ttm_params["fine_temperature"] = bark_specific_params.get("fine_temperature", 0.5)
-        ttm_params["coarse_temperature"] = bark_specific_params.get("coarse_temperature", 0.7)
-        ASCIIColors.info(f"Bark Params: preset={ttm_params['voice_preset']}, fine_temp={ttm_params['fine_temperature']}, coarse_temp={ttm_params['coarse_temperature']}")
-    else:
-        ASCIIColors.warning(f"Unknown TTM binding '{lollms_client.ttm.binding_name}'. Using generic parameters.")
-
-
-    try:
-        music_bytes = lollms_client.ttm.generate_music(prompt=prompt, **ttm_params)
-
-        if music_bytes:
-            with open(output_path, "wb") as f:
-                f.write(music_bytes)
-            ASCIIColors.green(f"SFX '{filename_stem}' ({lollms_client.ttm.binding_name}) saved to: {output_path}")
-            return output_path
-        else:
-            ASCIIColors.warning(f"SFX generation for '{filename_stem}' ({lollms_client.ttm.binding_name}) returned empty bytes.")
-            return None
-    except Exception as e:
-        ASCIIColors.error(f"Error generating SFX '{filename_stem}' ({lollms_client.ttm.binding_name}): {e}")
-        trace_exception(e)
-        return None
-
-def main():
-    parser = argparse.ArgumentParser(description="Generate game sound effects using LOLLMS TTM bindings.")
-    parser.add_argument(
-        "--ttm_binding",
-        type=str,
-        choices=["audiocraft", "bark"],
-        default="bark", # Default to audiocraft
-        help="The TTM binding to use for generation."
-    )
-    parser.add_argument(
-        "--audiocraft_model",
-        type=str,
-        default="facebook/musicgen-small",
-        help="Hugging Face model ID for AudioCraft (e.g., facebook/musicgen-small, facebook/musicgen-melody)."
-    )
-    parser.add_argument(
-        "--bark_model",
-        type=str,
-        default="suno/bark-small",
-        help="Hugging Face model ID for Bark (e.g., suno/bark-small, suno/bark)."
-    )
-    parser.add_argument(
-        "--device",
-        type=str,
-        default=None, # Auto-detect
-        choices=["cpu", "cuda", "mps", None],
-        help="Device to run the TTM model on (cpu, cuda, mps, or auto-detect)."
-    )
-    args = parser.parse_args()
-
-    ASCIIColors.red(f"--- LOLLMS Game SFX Generation Example (Using: {args.ttm_binding}) ---")
-
-    ttm_binding_config = {"device": args.device} # Common device config
-    if args.ttm_binding == "audiocraft":
-        ttm_binding_config["model_name"] = args.audiocraft_model
-        ttm_binding_config["output_format"] = "wav" # Audiocraft binding defaults to wav for bytes
-    elif args.ttm_binding == "bark":
-        ttm_binding_config["model_name"] = args.bark_model
-        # Bark binding currently outputs WAV by default for bytes
-    else:
-        ASCIIColors.error(f"Unsupported TTM binding: {args.ttm_binding}")
-        return
-
-    try:
-        ASCIIColors.magenta(f"Initializing LollmsClient with {args.ttm_binding} for TTM...")
-        lollms_client = LollmsClient(
-            binding_name="lollms", # Can be a dummy if only using TTM
-            ttm_binding_name=args.ttm_binding,
-            ttm_binding_config=ttm_binding_config
-        )
-        ASCIIColors.green("LollmsClient initialized.")
-    except Exception as e:
-        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}")
-        trace_exception(e)
-        return
-
-    if not lollms_client.ttm:
-        ASCIIColors.error(f"{args.ttm_binding.capitalize()} TTM binding could not be loaded. Exiting.")
-        return
-
-    generated_sfx_paths = {}
-    for sfx_info_item in SOUND_EFFECTS_TO_GENERATE:
-        sfx_path = generate_sfx(lollms_client, sfx_info_item)
-        if sfx_path:
-            generated_sfx_paths[sfx_info_item["filename"]] = {
-                "path": sfx_path,
-                "binding": args.ttm_binding # Store which binding generated it
-            }
-        time.sleep(0.5) # Small delay
-
-    ASCIIColors.red("\n--- SFX Generation Complete ---")
-    if not generated_sfx_paths:
-        ASCIIColors.warning("No sound effects were successfully generated.")
-        return
-
-    if not PYGAME_AVAILABLE:
-        ASCIIColors.warning("Pygame is not available. Skipping sound playback demo.")
-        ASCIIColors.info(f"Generated SFX can be found in: {SFX_OUTPUT_DIR.resolve()}")
-        return
-
-    ASCIIColors.magenta("\n--- Pygame SFX Playback Demo ---")
-    pygame.mixer.init()
-    game_sounds = {}
-    sfx_playback_order = [] # To map number keys to sounds
-
-    for filename_stem, sfx_data in generated_sfx_paths.items():
-        path = sfx_data["path"]
-        binding_used = sfx_data["binding"]
-        playback_name = f"{filename_stem} ({binding_used})"
-        try:
-            sound = pygame.mixer.Sound(str(path))
-            game_sounds[playback_name] = sound
-            sfx_playback_order.append(playback_name)
-            ASCIIColors.green(f"Loaded '{path.name}' into pygame as '{playback_name}'.")
-        except pygame.error as e:
-            ASCIIColors.warning(f"Could not load sound '{path.name}' into pygame: {e}")
-
-    if not game_sounds:
-        ASCIIColors.warning("No sounds loaded into pygame. Exiting demo.")
-        return
-
-    print("\nInstructions:")
-    for i, sfx_name_to_play in enumerate(sfx_playback_order):
-        print(f"  Press key '{i+1}' to play: {sfx_name_to_play}")
-    print("  Press 'Q' to quit the demo.")
-
-    pygame.display.set_mode((400, 200))
-    pygame.display.set_caption(f"SFX Player ({args.ttm_binding.capitalize()})")
-
-    running = True
-    while running:
-        for event in pygame.event.get():
-            if event.type == pygame.QUIT: running = False
-            if event.type == pygame.KEYDOWN:
-                if event.key == pygame.K_q: running = False
-                for i in range(len(sfx_playback_order)):
-                    if event.key == getattr(pygame, f"K_{i+1}", None): # Check if K_i+1 exists
-                        sfx_name_to_play = sfx_playback_order[i]
-                        if sfx_name_to_play in game_sounds:
-                            ASCIIColors.cyan(f"Playing: {sfx_name_to_play}")
-                            game_sounds[sfx_name_to_play].play()
-                        break
-        pygame.time.Clock().tick(30)
-
-    pygame.quit()
-    ASCIIColors.red("--- Demo Finished ---")
-    ASCIIColors.info(f"Generated SFX are in: {SFX_OUTPUT_DIR.resolve()}")
-
-if __name__ == "__main__":
-    main()

examples/generate_text_with_multihop_rag_example.py

@@ -1,210 +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
-
-# --- 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
-        )
-        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 ---")