lollms-client 0.15.2__tar.gz → 0.17.0__tar.gz

lollms_client-0.17.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: lollms_client
+Version: 0.17.0
+Summary: A client library for LoLLMs generate endpoint
+Author-email: ParisNeo <parisneoai@gmail.com>
+License: Apache Software License
+Project-URL: Homepage, https://github.com/ParisNeo/lollms_client
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: ascii-colors
+Requires-Dist: pipmaster
+Requires-Dist: pyyaml
+Requires-Dist: tiktoken
+Requires-Dist: pydantic
+Requires-Dist: numpy
+Requires-Dist: pillow
+Dynamic: license-file
+
+# LoLLMs Client Library
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI version](https://badge.fury.io/py/lollms_client.svg)](https://badge.fury.io/py/lollms_client)
+[![Python Versions](https://img.shields.io/pypi/pyversions/lollms_client.svg)](https://pypi.org/project/lollms_client/)
+[![Downloads](https://static.pepy.tech/personalized-badge/lollms-client?period=total&units=international_system&left_color=grey&right_color=green&left_text=Downloads)](https://pepy.tech/project/lollms-client)
+[![Documentation - Usage](https://img.shields.io/badge/docs-Usage%20Guide-brightgreen)](DOC_USE.md)
+[![Documentation - Developer](https://img.shields.io/badge/docs-Developer%20Guide-blue)](DOC_DEV.md)
+[![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.
+
+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.
+
+## Key Features
+
+*   🔌 **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.
+*   💬 **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.
+
+## Installation
+
+You can install `lollms_client` directly from PyPI:
+
+```bash
+pip install lollms-client
+```
+
+This will install the core library. Some bindings may require additional dependencies (e.g., `llama-cpp-python`, `torch`, `transformers`, `ollama`, `vllm`). The library attempts to manage these using `pipmaster`, but for complex dependencies (especially those requiring compilation like `llama-cpp-python` with GPU support), manual installation might be preferred.
+
+## Quick Start
+
+Here's a very basic example of how to use `LollmsClient` to generate text with a LoLLMs server (ensure one is running at `http://localhost:9600`):
+
+```python
+from lollms_client import LollmsClient, MSG_TYPE
+from ascii_colors import ASCIIColors
+
+# Callback for streaming output
+def simple_streaming_callback(chunk: str, msg_type: MSG_TYPE, params=None, metadata=None) -> bool:
+    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:
+        print(chunk, end="", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_EXCEPTION:
+        ASCIIColors.error(f"\nStreaming Error: {chunk}")
+    return True # True to continue streaming
+
+try:
+    # Initialize client to connect to a LoLLMs server
+    # For other backends, change 'binding_name' and provide necessary parameters.
+    # See DOC_USE.md for detailed initialization examples.
+    lc = LollmsClient(
+        binding_name="lollms",
+        host_address="http://localhost:9600"
+    )
+
+    prompt = "Tell me a fun fact about space."
+    ASCIIColors.yellow(f"Prompt: {prompt}")
+
+    # Generate text with streaming
+    ASCIIColors.green("Streaming Response:")
+    response_text = lc.generate_text(
+        prompt,
+        n_predict=100,
+        stream=True,
+        streaming_callback=simple_streaming_callback
+    )
+    print("\n--- End of Stream ---")
+
+    # The 'response_text' variable will contain the full concatenated text
+    # if streaming_callback returns True throughout.
+    if isinstance(response_text, str):
+        ASCIIColors.cyan(f"\nFull streamed text collected: {response_text[:100]}...")
+    elif isinstance(response_text, dict) and "error" in response_text:
+        ASCIIColors.error(f"Error during generation: {response_text['error']}")
+
+except ValueError as ve:
+    ASCIIColors.error(f"Initialization Error: {ve}")
+    ASCIIColors.info("Ensure a LoLLMs server is running or configure another binding.")
+except ConnectionRefusedError:
+    ASCIIColors.error("Connection refused. Is the LoLLMs server running at http://localhost:9600?")
+except Exception as e:
+    ASCIIColors.error(f"An unexpected error occurred: {e}")
+
+```
+
+## 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.
+
+## Core Concepts
+
+```mermaid
+graph LR
+    A[Your Application] --> LC[LollmsClient];
+
+    subgraph LollmsClient_Core
+        LC -- Manages --> LLB[LLM Binding];
+        LC -- Provides Access To --> TL[TasksLibrary];
+        LC -- Provides Access To --> FCL[FunctionCalling_Library];
+        LC -- Provides Access To --> DM[DiscussionManager];
+        LC -- Provides Access To --> ModalityBindings[TTS, TTI, STT etc.];
+    end
+
+    subgraph LLM_Backends
+        LLB --> LollmsServer[LoLLMs Server];
+        LLB --> OllamaServer[Ollama];
+        LLB --> OpenAPIServer[OpenAI API];
+        LLB --> LocalGGUF[Local GGUF<br>(pythonllamacpp / llamacpp server)];
+        LLB --> LocalHF[Local HuggingFace<br>(transformers / vLLM)];
+    end
+
+    ModalityBindings --> ModalityServices[Modality Services<br>(e.g., LoLLMs Server TTS/TTI)];
+```
+
+*   **`LollmsClient`**: The central class for all interactions. It holds the currently active LLM binding and provides access to modality bindings and helper libraries.
+*   **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`.
+*   **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.
+*   **`LollmsDiscussion`**: Helps manage and format conversation histories for chat applications.
+
+## Examples
+
+The `examples/` directory in this repository contains a rich set of scripts demonstrating various features:
+*   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.
+*   Text-to-Speech and Text-to-Image generation.
+
+Explore these examples to see `lollms-client` in action!
+
+## Contributing
+
+Contributions are welcome! Whether it's bug reports, feature suggestions, documentation improvements, or new bindings, please feel free to open an issue or submit a pull request on our [GitHub repository](https://github.com/ParisNeo/lollms_client).
+
+## License
+
+This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details (assuming you have a LICENSE file, if not, state "Apache 2.0 License").
+
+## Changelog
+
+For a list of changes and updates, please refer to the [CHANGELOG.md](CHANGELOG.md) file.

lollms_client-0.17.0/README.md

@@ -0,0 +1,153 @@
+# LoLLMs Client Library
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![PyPI version](https://badge.fury.io/py/lollms_client.svg)](https://badge.fury.io/py/lollms_client)
+[![Python Versions](https://img.shields.io/pypi/pyversions/lollms_client.svg)](https://pypi.org/project/lollms_client/)
+[![Downloads](https://static.pepy.tech/personalized-badge/lollms-client?period=total&units=international_system&left_color=grey&right_color=green&left_text=Downloads)](https://pepy.tech/project/lollms-client)
+[![Documentation - Usage](https://img.shields.io/badge/docs-Usage%20Guide-brightgreen)](DOC_USE.md)
+[![Documentation - Developer](https://img.shields.io/badge/docs-Developer%20Guide-blue)](DOC_DEV.md)
+[![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.
+
+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.
+
+## Key Features
+
+*   🔌 **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.
+*   💬 **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.
+
+## Installation
+
+You can install `lollms_client` directly from PyPI:
+
+```bash
+pip install lollms-client
+```
+
+This will install the core library. Some bindings may require additional dependencies (e.g., `llama-cpp-python`, `torch`, `transformers`, `ollama`, `vllm`). The library attempts to manage these using `pipmaster`, but for complex dependencies (especially those requiring compilation like `llama-cpp-python` with GPU support), manual installation might be preferred.
+
+## Quick Start
+
+Here's a very basic example of how to use `LollmsClient` to generate text with a LoLLMs server (ensure one is running at `http://localhost:9600`):
+
+```python
+from lollms_client import LollmsClient, MSG_TYPE
+from ascii_colors import ASCIIColors
+
+# Callback for streaming output
+def simple_streaming_callback(chunk: str, msg_type: MSG_TYPE, params=None, metadata=None) -> bool:
+    if msg_type == MSG_TYPE.MSG_TYPE_CHUNK:
+        print(chunk, end="", flush=True)
+    elif msg_type == MSG_TYPE.MSG_TYPE_EXCEPTION:
+        ASCIIColors.error(f"\nStreaming Error: {chunk}")
+    return True # True to continue streaming
+
+try:
+    # Initialize client to connect to a LoLLMs server
+    # For other backends, change 'binding_name' and provide necessary parameters.
+    # See DOC_USE.md for detailed initialization examples.
+    lc = LollmsClient(
+        binding_name="lollms",
+        host_address="http://localhost:9600"
+    )
+
+    prompt = "Tell me a fun fact about space."
+    ASCIIColors.yellow(f"Prompt: {prompt}")
+
+    # Generate text with streaming
+    ASCIIColors.green("Streaming Response:")
+    response_text = lc.generate_text(
+        prompt,
+        n_predict=100,
+        stream=True,
+        streaming_callback=simple_streaming_callback
+    )
+    print("\n--- End of Stream ---")
+
+    # The 'response_text' variable will contain the full concatenated text
+    # if streaming_callback returns True throughout.
+    if isinstance(response_text, str):
+        ASCIIColors.cyan(f"\nFull streamed text collected: {response_text[:100]}...")
+    elif isinstance(response_text, dict) and "error" in response_text:
+        ASCIIColors.error(f"Error during generation: {response_text['error']}")
+
+except ValueError as ve:
+    ASCIIColors.error(f"Initialization Error: {ve}")
+    ASCIIColors.info("Ensure a LoLLMs server is running or configure another binding.")
+except ConnectionRefusedError:
+    ASCIIColors.error("Connection refused. Is the LoLLMs server running at http://localhost:9600?")
+except Exception as e:
+    ASCIIColors.error(f"An unexpected error occurred: {e}")
+
+```
+
+## 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.
+
+## Core Concepts
+
+```mermaid
+graph LR
+    A[Your Application] --> LC[LollmsClient];
+
+    subgraph LollmsClient_Core
+        LC -- Manages --> LLB[LLM Binding];
+        LC -- Provides Access To --> TL[TasksLibrary];
+        LC -- Provides Access To --> FCL[FunctionCalling_Library];
+        LC -- Provides Access To --> DM[DiscussionManager];
+        LC -- Provides Access To --> ModalityBindings[TTS, TTI, STT etc.];
+    end
+
+    subgraph LLM_Backends
+        LLB --> LollmsServer[LoLLMs Server];
+        LLB --> OllamaServer[Ollama];
+        LLB --> OpenAPIServer[OpenAI API];
+        LLB --> LocalGGUF[Local GGUF<br>(pythonllamacpp / llamacpp server)];
+        LLB --> LocalHF[Local HuggingFace<br>(transformers / vLLM)];
+    end
+
+    ModalityBindings --> ModalityServices[Modality Services<br>(e.g., LoLLMs Server TTS/TTI)];
+```
+
+*   **`LollmsClient`**: The central class for all interactions. It holds the currently active LLM binding and provides access to modality bindings and helper libraries.
+*   **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`.
+*   **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.
+*   **`LollmsDiscussion`**: Helps manage and format conversation histories for chat applications.
+
+## Examples
+
+The `examples/` directory in this repository contains a rich set of scripts demonstrating various features:
+*   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.
+*   Text-to-Speech and Text-to-Image generation.
+
+Explore these examples to see `lollms-client` in action!
+
+## Contributing
+
+Contributions are welcome! Whether it's bug reports, feature suggestions, documentation improvements, or new bindings, please feel free to open an issue or submit a pull request on our [GitHub repository](https://github.com/ParisNeo/lollms_client).
+
+## License
+
+This project is licensed under the **Apache 2.0 License**. See the [LICENSE](LICENSE) file for details (assuming you have a LICENSE file, if not, state "Apache 2.0 License").
+
+## Changelog
+
+For a list of changes and updates, please refer to the [CHANGELOG.md](CHANGELOG.md) file.

lollms_client-0.17.0/examples/generate_and_speak/generate_and_speak.py

@@ -0,0 +1,251 @@
+# lollms_client/examples/text_and_speech_demo/generate_and_speak.py
+from pathlib import Path
+import time
+import argparse
+
+# 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, MSG_TYPE
+from ascii_colors import ASCIIColors, trace_exception
+
+# --- Configuration ---
+SPEECH_OUTPUT_DIR = Path(__file__).parent / "speech_output"
+SPEECH_OUTPUT_DIR.mkdir(exist_ok=True)
+
+# Default path for Piper voices relative to this example script for convenience
+DEFAULT_PIPER_VOICES_SUBDIR = Path(__file__).parent / "piper_voices_for_demo"
+DEFAULT_PIPER_VOICE_FILENAME = "en_US-lessac-medium.onnx" # A common, good quality English voice
+
+def text_stream_callback(chunk: str, message_type: MSG_TYPE, params: dict = None, metadata: list = None) -> bool:
+    if message_type == MSG_TYPE.MSG_TYPE_CHUNK:
+        print(chunk, end="", flush=True)
+    elif message_type == MSG_TYPE.MSG_TYPE_STEP_START:
+        ASCIIColors.yellow(f"\n>> Starting step: {chunk}")
+    elif message_type == MSG_TYPE.MSG_TYPE_STEP_END:
+        ASCIIColors.green(f"\n<< Finished step: {chunk}")
+    return True
+
+def ensure_default_piper_voice_for_demo(voices_dir: Path, voice_filename: str):
+    """Helper to download a default Piper voice if not present for the demo."""
+    voices_dir.mkdir(exist_ok=True)
+    onnx_path = voices_dir / voice_filename
+    json_path = voices_dir / f"{voice_filename}.json"
+
+    if not onnx_path.exists() or not json_path.exists():
+        ASCIIColors.info(f"Default Piper test voice '{voice_filename}' not found in {voices_dir}. Attempting to download...")
+        try:
+            import requests
+            # Construct URLs (assuming en_US/lessac/medium structure)
+            voice_parts = voice_filename.split('-') # e.g., ['en_US', 'lessac', 'medium.onnx']
+            lang_code = voice_parts[0].split('_')[0] # en
+            voice_name_path = "/".join(voice_parts[0:2]) # en_US/lessac
+            quality_path = voice_parts[2].split('.')[0] # medium
+
+            # Base URL for Piper voices on Hugging Face
+            PIPER_VOICES_HF_BASE_URL = "https://huggingface.co/rhasspy/piper-voices/resolve/main/"
+
+            onnx_url = f"{PIPER_VOICES_HF_BASE_URL}{lang_code}/{voice_name_path}/{quality_path}/{voice_filename}"
+            json_url = f"{PIPER_VOICES_HF_BASE_URL}{lang_code}/{voice_name_path}/{quality_path}/{voice_filename}.json"
+
+
+            if not onnx_path.exists():
+                ASCIIColors.info(f"Downloading {onnx_url} to {onnx_path}")
+                r_onnx = requests.get(onnx_url, stream=True)
+                r_onnx.raise_for_status()
+                with open(onnx_path, 'wb') as f:
+                    for chunk in r_onnx.iter_content(chunk_size=8192): f.write(chunk)
+            
+            if not json_path.exists():
+                ASCIIColors.info(f"Downloading {json_url} to {json_path}")
+                r_json = requests.get(json_url)
+                r_json.raise_for_status()
+                with open(json_path, 'w', encoding='utf-8') as f: f.write(r_json.text)
+            ASCIIColors.green(f"Default Piper test voice '{voice_filename}' downloaded successfully to {voices_dir}.")
+            return True
+        except Exception as e_download:
+            ASCIIColors.error(f"Failed to download default Piper test voice '{voice_filename}': {e_download}")
+            ASCIIColors.warning(f"Please manually download '{voice_filename}' and '{voice_filename}.json' "
+                                f"from rhasspy.github.io/piper-voices/ or Hugging Face "
+                                f"and place them in {voices_dir.resolve()}")
+            return False
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Generate text with an LLM and synthesize it to speech using LOLLMS.")
+    # LLM Arguments
+    parser.add_argument(
+        "--llm_binding", type=str, default="ollama", choices=["ollama", "openai", "lollms", "llamacpp", "pythonllamacpp", "transformers", "vllm"],
+        help="The LLM binding to use for text generation."
+    )
+    parser.add_argument(
+        "--llm_model", type=str, default="mistral",
+        help="Model name or path for the LLM binding."
+    )
+    parser.add_argument("--llm_host", type=str, default=None, help="Host address for server-based LLM bindings.")
+    parser.add_argument("--models_path", type=str, default=None, help="Path to models directory for local LLM bindings.")
+    parser.add_argument("--openai_key", type=str, default=None, help="OpenAI API key.")
+
+    # TTS Arguments
+    parser.add_argument(
+        "--tts_binding", type=str, default="bark", choices=["bark", "lollms", "xtts", "piper"],
+        help="The TTS binding to use for speech synthesis."
+    )
+    # Bark specific
+    parser.add_argument("--bark_model", type=str, default="suno/bark-small", help="Bark model ID for TTS.")
+    parser.add_argument("--bark_voice_preset", type=str, default="v2/en_speaker_6", help="Bark voice preset.")
+    # XTTS specific
+    parser.add_argument("--xtts_model", type=str, default="tts_models/multilingual/multi-dataset/xtts_v2", help="XTTS model identifier for Coqui TTS.")
+    parser.add_argument("--xtts_speaker_wav", type=str, default=None, help="Path to speaker WAV for XTTS voice cloning.")
+    parser.add_argument("--xtts_language", type=str, default="en", help="Language for XTTS.")
+    # Piper specific
+    parser.add_argument("--piper_default_voice_model_path", type=str, default=None, help="Path to the default .onnx Piper voice model.")
+    parser.add_argument("--piper_voices_dir", type=str, default=str(DEFAULT_PIPER_VOICES_SUBDIR), help="Directory containing Piper voice models.")
+    parser.add_argument("--piper_voice_file", type=str, default=DEFAULT_PIPER_VOICE_FILENAME, help="Filename of the Piper voice to use from piper_voices_dir (e.g., en_US-ryan-medium.onnx).")
+
+    # Common TTS/LLM args
+    parser.add_argument("--tts_host", type=str, default=None, help="Host address for server-based TTS bindings (e.g., lollms TTS).")
+    parser.add_argument("--device", type=str, default=None, choices=["cpu", "cuda", "mps", None], help="Device for local TTS/LLM models.")
+    args = parser.parse_args()
+
+    ASCIIColors.red("--- LOLLMS Text Generation and Speech Synthesis Demo ---")
+    ASCIIColors.info(f"Using LLM Binding: {args.llm_binding} (Model: {args.llm_model})")
+    ASCIIColors.info(f"Using TTS Binding: {args.tts_binding}")
+    if args.tts_binding == "bark":
+        ASCIIColors.info(f"  Bark Model: {args.bark_model}, Voice Preset: {args.bark_voice_preset}")
+    elif args.tts_binding == "xtts":
+        ASCIIColors.info(f"  XTTS Model: {args.xtts_model}, Speaker WAV: {args.xtts_speaker_wav or 'Default in binding'}, Lang: {args.xtts_language}")
+    elif args.tts_binding == "piper":
+        ASCIIColors.info(f"  Piper Voices Dir: {args.piper_voices_dir}, Voice File: {args.piper_voice_file}")
+        # Ensure default Piper voice for demo if Piper is selected and no specific default path is given
+        if not args.piper_default_voice_model_path:
+            ensure_default_piper_voice_for_demo(Path(args.piper_voices_dir), args.piper_voice_file)
+            args.piper_default_voice_model_path = str(Path(args.piper_voices_dir) / args.piper_voice_file)
+
+
+    llm_binding_config = {}
+    if args.llm_binding == "openai" and args.openai_key: llm_binding_config["service_key"] = args.openai_key
+    elif args.llm_binding in ["llamacpp", "pythonllamacpp", "transformers", "vllm"]:
+        if args.device: llm_binding_config["device"] = args.device
+        if args.llm_binding == "pythonllamacpp": llm_binding_config["n_gpu_layers"] = -1 if args.device == "cuda" else 0
+
+    tts_binding_config = {"device": args.device}
+    if args.tts_binding == "bark":
+        tts_binding_config["model_name"] = args.bark_model
+        tts_binding_config["default_voice"] = args.bark_voice_preset
+    elif args.tts_binding == "xtts":
+        tts_binding_config["model_name"] = args.xtts_model
+        tts_binding_config["default_speaker_wav"] = args.xtts_speaker_wav
+        tts_binding_config["default_language"] = args.xtts_language
+    elif args.tts_binding == "piper":
+        tts_binding_config["default_voice_model_path"] = args.piper_default_voice_model_path
+        tts_binding_config["piper_voices_dir"] = args.piper_voices_dir
+    elif args.tts_binding == "lollms":
+        tts_binding_config["model_name"] = "default_lollms_voice" # Placeholder, server handles actual voice
+
+    lollms_client = None
+    try:
+        ASCIIColors.magenta("Initializing LollmsClient...")
+        lollms_client = LollmsClient(
+            binding_name=args.llm_binding, model_name=args.llm_model,
+            host_address=args.llm_host, models_path=args.models_path,
+            llm_binding_config=llm_binding_config,
+            tts_binding_name=args.tts_binding, tts_host_address=args.tts_host,
+            tts_binding_config=tts_binding_config,
+            verify_ssl_certificate=False
+        )
+        ASCIIColors.green("LollmsClient initialized.")
+    except Exception as e:
+        ASCIIColors.error(f"Failed to initialize LollmsClient: {e}"); trace_exception(e)
+        return
+
+    generated_text = ""
+    text_prompt = "Craft a very short, cheerful message about the joy of discovery."
+    ASCIIColors.cyan(f"\n--- Generating Text (Prompt: '{text_prompt[:50]}...') ---")
+    if not lollms_client.binding:
+        ASCIIColors.error("LLM binding not available."); return
+    try:
+        print(f"{ASCIIColors.YELLOW}AI is thinking: {ASCIIColors.RESET}", end="")
+        generated_text = lollms_client.generate_text(
+            prompt=text_prompt, n_predict=100, stream=True,
+            streaming_callback=text_stream_callback, temperature=0.7
+        )
+        print("\n"); ASCIIColors.green("Text generation complete.")
+        ASCIIColors.magenta("Generated Text:\n"); ASCIIColors.yellow(generated_text)
+    except Exception as e:
+        ASCIIColors.error(f"Text generation failed: {e}"); trace_exception(e); return
+    if not generated_text:
+        ASCIIColors.warning("LLM did not generate any text."); return
+
+    speech_file_path = None
+    ASCIIColors.cyan(f"\n--- Synthesizing Speech (using {args.tts_binding}) ---")
+    if not lollms_client.tts:
+        ASCIIColors.error("TTS binding not available."); return
+    try:
+        tts_call_kwargs = {}
+        if args.tts_binding == "bark":
+            # For Bark, 'voice' in generate_audio is the voice_preset.
+            # If not using the default from init, pass it here.
+            # tts_call_kwargs['voice'] = args.bark_voice_preset 
+            pass # Uses default_voice from init if args.bark_voice_preset not specified to override
+        elif args.tts_binding == "xtts":
+            tts_call_kwargs['language'] = args.xtts_language
+            # 'voice' for XTTS is the speaker_wav path. If not using default from init, pass here.
+            # tts_call_kwargs['voice'] = args.xtts_speaker_wav 
+        elif args.tts_binding == "piper":
+            # 'voice' for Piper is the .onnx filename.
+            tts_call_kwargs['voice'] = args.piper_voice_file
+            # Example Piper specific param:
+            # tts_call_kwargs['length_scale'] = 1.0 
+
+        audio_bytes = lollms_client.tts.generate_audio(text=generated_text, **tts_call_kwargs)
+
+        if audio_bytes:
+            filename_stem = f"speech_output_{args.llm_binding}_{args.tts_binding}"
+            speech_file_path = SPEECH_OUTPUT_DIR / f"{filename_stem.replace('/', '_')}.wav"
+            with open(speech_file_path, "wb") as f: f.write(audio_bytes)
+            ASCIIColors.green(f"Speech synthesized and saved to: {speech_file_path}")
+        elif args.tts_binding == "lollms":
+            ASCIIColors.warning("LOLLMS TTS binding returned empty bytes. Server might have saved file if 'fn' was used.")
+            speech_file_path = None
+        else:
+            ASCIIColors.warning("Speech synthesis returned empty bytes."); speech_file_path = None
+    except Exception as e:
+        ASCIIColors.error(f"Speech synthesis failed: {e}"); trace_exception(e); return
+
+    if speech_file_path and PYGAME_AVAILABLE:
+        ASCIIColors.magenta("\n--- Playing Synthesized Speech ---")
+        try:
+            pygame.mixer.init()
+            speech_sound = pygame.mixer.Sound(str(speech_file_path))
+            ASCIIColors.cyan("Playing audio... Press Ctrl+C in console to stop playback early.")
+            speech_sound.play()
+            while pygame.mixer.get_busy():
+                pygame.time.Clock().tick(10)
+                for event in pygame.event.get():
+                    if event.type == pygame.QUIT: pygame.mixer.stop(); break
+            ASCIIColors.green("Playback finished.")
+        except pygame.error as e: ASCIIColors.warning(f"Could not play audio with pygame: {e}")
+        except KeyboardInterrupt: pygame.mixer.stop(); ASCIIColors.yellow("\nPlayback interrupted.")
+        finally: pygame.quit()
+    elif not PYGAME_AVAILABLE:
+        ASCIIColors.warning("Pygame is not available for playback.")
+        if speech_file_path: ASCIIColors.info(f"Generated speech: {speech_file_path.resolve()}")
+    elif not speech_file_path:
+         ASCIIColors.warning("No speech file generated/path unknown. Skipping playback.")
+
+    ASCIIColors.red("\n--- Demo Finished ---")
+
+if __name__ == "__main__":
+    main()