abstractvoice 0.3.1__tar.gz → 0.4.1__tar.gz

{abstractvoice-0.3.1 → abstractvoice-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractvoice
-Version: 0.3.1
+Version: 0.4.1
 Summary: A modular Python library for voice interactions with AI systems
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 License-Expression: MIT
@@ -164,34 +164,58 @@ AbstractVoice automatically detects espeak-ng and upgrades to premium quality vo
 
 ## Quick Start
 
-### Basic Usage (Minimal Installation)
+### ⚡ Instant TTS (v0.4.0+)
 
 ```python
-# First install with minimal dependencies
-# pip install abstractvoice
-
 from abstractvoice import VoiceManager
 
-# This will show a helpful error message with installation instructions
-try:
-    vm = VoiceManager()
-except ImportError as e:
-    print(e)  # Shows: "TTS functionality requires optional dependencies..."
-    # Follow the instructions to install: pip install abstractvoice[all]
+# Initialize voice manager - automatically downloads essential model if needed
+vm = VoiceManager()
+
+# Text-to-speech works immediately!
+vm.speak("Hello! TTS works out of the box!")
 ```
 
-### Full Usage Example
+**That's it!** AbstractVoice v0.4.0+ automatically:
+- ✅ Downloads essential English model (107MB) on first use
+- ✅ Caches models permanently for offline use
+- ✅ Works immediately after first setup
+- ✅ No complex configuration needed
 
-```python
-# After installing with: pip install abstractvoice[all]
+### 🌍 Multi-Language Support
 
-from abstractvoice import VoiceManager
+```python
+# Download and use French voice
+vm.download_model('fr.css10_vits')  # Downloads automatically
+vm.set_language('fr')
+vm.speak("Bonjour! Je parle français maintenant.")
+
+# Download and use German voice
+vm.download_model('de.thorsten_vits')
+vm.set_language('de')
+vm.speak("Hallo! Ich spreche jetzt Deutsch.")
+```
 
-# Initialize voice manager
-vm = VoiceManager(language='en', debug_mode=True)
+### 🔧 Check System Status
 
-# Text-to-speech
-vm.speak("Hello! I can speak text and listen for responses.")
+```python
+from abstractvoice import is_ready, get_status, list_models
+import json
+
+# Quick readiness check
+ready = is_ready()
+print(f"TTS ready: {ready}")
+
+# Get detailed status
+status = json.loads(get_status())
+print(f"Models cached: {status['total_cached']}")
+print(f"Offline ready: {status['ready_for_offline']}")
+
+# List all available models
+models = json.loads(list_models())
+for lang, voices in models.items():
+    print(f"{lang}: {len(voices)} voices available")
+```
 
 # Speech-to-text with callbacks
 def on_transcription(text):
@@ -1289,6 +1313,80 @@ voice_manager.listen(
 )
 ```
 
+## 💻 CLI Commands (v0.4.0+)
+
+AbstractVoice provides powerful CLI commands for model management and voice interactions.
+
+### Model Management
+
+```bash
+# Download essential model for offline use (recommended first step)
+abstractvoice download-models
+
+# Download models for specific languages
+abstractvoice download-models --language fr    # French
+abstractvoice download-models --language de    # German
+abstractvoice download-models --language it    # Italian
+abstractvoice download-models --language es    # Spanish
+
+# Download specific model by name
+abstractvoice download-models --model tts_models/fr/css10/vits
+
+# Download all available models (large download!)
+abstractvoice download-models --all
+
+# Check current cache status
+abstractvoice download-models --status
+
+# Clear model cache
+abstractvoice download-models --clear
+```
+
+### Voice Interface
+
+```bash
+# Start voice interface (default)
+abstractvoice
+
+# Start CLI REPL with specific language
+abstractvoice cli --language fr
+
+# Start with specific model
+abstractvoice --model granite3.3:2b --language de
+
+# Run simple example
+abstractvoice simple
+
+# Check dependencies
+abstractvoice check-deps
+```
+
+### CLI Voice Commands
+
+In the CLI REPL, use these commands:
+
+```bash
+# List all available voices with download status
+/setvoice
+
+# Download and set specific voice
+/setvoice fr.css10_vits      # French CSS10 VITS
+/setvoice de.thorsten_vits   # German Thorsten
+/setvoice it.mai_male_vits   # Italian Male
+
+# Change language
+/language fr
+/language de
+
+# Voice controls
+/pause                       # Pause current speech
+/resume                      # Resume speech
+/stop                        # Stop speech
+
+# Exit
+/exit
+```
+
 ## Perspectives
 
 This is a test project that I designed with examples to work with Ollama, but I will adapt the examples and abstractvoice to work with any LLM provider (anthropic, openai, etc).

{abstractvoice-0.3.1 → abstractvoice-0.4.1}/README.md

@@ -82,34 +82,58 @@ AbstractVoice automatically detects espeak-ng and upgrades to premium quality vo
 
 ## Quick Start
 
-### Basic Usage (Minimal Installation)
+### ⚡ Instant TTS (v0.4.0+)
 
 ```python
-# First install with minimal dependencies
-# pip install abstractvoice
-
 from abstractvoice import VoiceManager
 
-# This will show a helpful error message with installation instructions
-try:
-    vm = VoiceManager()
-except ImportError as e:
-    print(e)  # Shows: "TTS functionality requires optional dependencies..."
-    # Follow the instructions to install: pip install abstractvoice[all]
+# Initialize voice manager - automatically downloads essential model if needed
+vm = VoiceManager()
+
+# Text-to-speech works immediately!
+vm.speak("Hello! TTS works out of the box!")
 ```
 
-### Full Usage Example
+**That's it!** AbstractVoice v0.4.0+ automatically:
+- ✅ Downloads essential English model (107MB) on first use
+- ✅ Caches models permanently for offline use
+- ✅ Works immediately after first setup
+- ✅ No complex configuration needed
 
-```python
-# After installing with: pip install abstractvoice[all]
+### 🌍 Multi-Language Support
 
-from abstractvoice import VoiceManager
+```python
+# Download and use French voice
+vm.download_model('fr.css10_vits')  # Downloads automatically
+vm.set_language('fr')
+vm.speak("Bonjour! Je parle français maintenant.")
+
+# Download and use German voice
+vm.download_model('de.thorsten_vits')
+vm.set_language('de')
+vm.speak("Hallo! Ich spreche jetzt Deutsch.")
+```
 
-# Initialize voice manager
-vm = VoiceManager(language='en', debug_mode=True)
+### 🔧 Check System Status
 
-# Text-to-speech
-vm.speak("Hello! I can speak text and listen for responses.")
+```python
+from abstractvoice import is_ready, get_status, list_models
+import json
+
+# Quick readiness check
+ready = is_ready()
+print(f"TTS ready: {ready}")
+
+# Get detailed status
+status = json.loads(get_status())
+print(f"Models cached: {status['total_cached']}")
+print(f"Offline ready: {status['ready_for_offline']}")
+
+# List all available models
+models = json.loads(list_models())
+for lang, voices in models.items():
+    print(f"{lang}: {len(voices)} voices available")
+```
 
 # Speech-to-text with callbacks
 def on_transcription(text):
@@ -1207,6 +1231,80 @@ voice_manager.listen(
 )
 ```
 
+## 💻 CLI Commands (v0.4.0+)
+
+AbstractVoice provides powerful CLI commands for model management and voice interactions.
+
+### Model Management
+
+```bash
+# Download essential model for offline use (recommended first step)
+abstractvoice download-models
+
+# Download models for specific languages
+abstractvoice download-models --language fr    # French
+abstractvoice download-models --language de    # German
+abstractvoice download-models --language it    # Italian
+abstractvoice download-models --language es    # Spanish
+
+# Download specific model by name
+abstractvoice download-models --model tts_models/fr/css10/vits
+
+# Download all available models (large download!)
+abstractvoice download-models --all
+
+# Check current cache status
+abstractvoice download-models --status
+
+# Clear model cache
+abstractvoice download-models --clear
+```
+
+### Voice Interface
+
+```bash
+# Start voice interface (default)
+abstractvoice
+
+# Start CLI REPL with specific language
+abstractvoice cli --language fr
+
+# Start with specific model
+abstractvoice --model granite3.3:2b --language de
+
+# Run simple example
+abstractvoice simple
+
+# Check dependencies
+abstractvoice check-deps
+```
+
+### CLI Voice Commands
+
+In the CLI REPL, use these commands:
+
+```bash
+# List all available voices with download status
+/setvoice
+
+# Download and set specific voice
+/setvoice fr.css10_vits      # French CSS10 VITS
+/setvoice de.thorsten_vits   # German Thorsten
+/setvoice it.mai_male_vits   # Italian Male
+
+# Change language
+/language fr
+/language de
+
+# Voice controls
+/pause                       # Pause current speech
+/resume                      # Resume speech
+/stop                        # Stop speech
+
+# Exit
+/exit
+```
+
 ## Perspectives
 
 This is a test project that I designed with examples to work with Ollama, but I will adapt the examples and abstractvoice to work with any LLM provider (anthropic, openai, etc).

{abstractvoice-0.3.1 → abstractvoice-0.4.1}/abstractvoice/__init__.py

@@ -29,5 +29,8 @@ warnings.filterwarnings(
 # Import the main class for public API
 from .voice_manager import VoiceManager
 
-__version__ = "0.3.1"
-__all__ = ['VoiceManager'] 
+# Import simple APIs for third-party applications
+from .simple_model_manager import list_models, download_model, get_status, is_ready
+
+__version__ = "0.4.1"
+__all__ = ['VoiceManager', 'list_models', 'download_model', 'get_status', 'is_ready'] 

{abstractvoice-0.3.1 → abstractvoice-0.4.1}/abstractvoice/examples/cli_repl.py

@@ -38,7 +38,7 @@ class VoiceREPL(cmd.Cmd):
     use_rawinput = True
     
     def __init__(self, api_url="http://localhost:11434/api/chat",
-                 model="granite3.3:2b", debug_mode=False, language="en", tts_model=None):
+                 model="granite3.3:2b", debug_mode=False, language="en", tts_model=None, disable_tts=False):
         super().__init__()
 
         # Debug mode
@@ -54,11 +54,15 @@ class VoiceREPL(cmd.Cmd):
         self.current_language = language
 
         # Initialize voice manager with language support
-        self.voice_manager = VoiceManager(
-            language=language,
-            tts_model=tts_model,
-            debug_mode=debug_mode
-        )
+        if disable_tts:
+            self.voice_manager = None
+            print("🔇 TTS disabled - text-only mode")
+        else:
+            self.voice_manager = VoiceManager(
+                language=language,
+                tts_model=tts_model,
+                debug_mode=debug_mode
+            )
         
         # Settings
         self.use_tts = True
@@ -90,8 +94,11 @@ class VoiceREPL(cmd.Cmd):
     def _get_intro(self):
         """Generate intro message with help."""
         intro = f"\n{Colors.BOLD}Welcome to AbstractVoice CLI REPL{Colors.END}\n"
-        lang_name = self.voice_manager.get_language_name()
-        intro += f"API: {self.api_url} | Model: {self.model} | Voice: {lang_name}\n"
+        if self.voice_manager:
+            lang_name = self.voice_manager.get_language_name()
+            intro += f"API: {self.api_url} | Model: {self.model} | Voice: {lang_name}\n"
+        else:
+            intro += f"API: {self.api_url} | Model: {self.model} | Voice: Disabled\n"
         intro += f"\n{Colors.CYAN}Quick Start:{Colors.END}\n"
         intro += "  • Type messages to chat with the LLM\n"
         intro += "  • Use /voice <mode> to enable voice input\n"
@@ -232,7 +239,7 @@ class VoiceREPL(cmd.Cmd):
             print(f"{Colors.CYAN}{response_text}{Colors.END}")
             
             # Speak the response if voice manager is available
-            if self.voice_manager:
+            if self.voice_manager and self.use_tts:
                 self.voice_manager.speak(response_text)
                 
         except requests.exceptions.ConnectionError as e:
@@ -376,18 +383,47 @@ class VoiceREPL(cmd.Cmd):
           /setvoice <voice_id>         # Set voice (format: language.voice_id)
 
         Examples:
-          /setvoice                    # List all voices
+          /setvoice                    # List all voices with JSON-like info
           /setvoice fr.css10_vits      # Set French CSS10 VITS voice
           /setvoice it.mai_male_vits   # Set Italian male VITS voice
         """
         if not args:
-            # Show all available voices organized by language
+            # Show all available voices with metadata
             print(f"\n{Colors.CYAN}Available Voice Models:{Colors.END}")
-            self.voice_manager.list_voices()
 
-            print(f"\n{Colors.YELLOW}Usage:{Colors.END}")
-            print("  /setvoice <language>.<voice_id>")
-            print("  Example: /setvoice fr.css10_vits")
+            try:
+                models = self.voice_manager.list_available_models()
+
+                for language, voices in models.items():
+                    # Get language name
+                    lang_names = {
+                        'en': 'English', 'fr': 'French', 'es': 'Spanish',
+                        'de': 'German', 'it': 'Italian'
+                    }
+                    lang_name = lang_names.get(language, language.upper())
+
+                    print(f"\n🌍 {lang_name} ({language}):")
+
+                    for voice_id, voice_info in voices.items():
+                        cached_icon = "✅" if voice_info.get('cached', False) else "📥"
+                        quality_icon = "✨" if voice_info['quality'] == 'excellent' else "🔧"
+                        size_text = f"{voice_info['size_mb']}MB"
+
+                        print(f"  {cached_icon} {quality_icon} {language}.{voice_id}")
+                        print(f"      {voice_info['name']} ({size_text})")
+                        print(f"      {voice_info['description']}")
+                        if voice_info.get('requires_espeak', False):
+                            print(f"      ⚠️ Requires espeak-ng")
+
+                print(f"\n{Colors.YELLOW}Usage:{Colors.END}")
+                print("  /setvoice <language>.<voice_id>")
+                print("  Example: /setvoice fr.css10_vits")
+                print("\n📥 = Download needed  ✅ = Ready  ✨ = High quality  🔧 = Good quality")
+
+            except Exception as e:
+                print(f"❌ Error listing models: {e}")
+                # Fallback to old method
+                self.voice_manager.list_voices()
             return
 
         voice_spec = args.strip()
@@ -412,45 +448,46 @@ class VoiceREPL(cmd.Cmd):
         else:
             was_active = False
 
-        # Set the specific voice
+        # Download and set the specific voice using programmatic API
         try:
-            success = self.voice_manager.set_voice(language, voice_id)
+            print(f"🔄 Setting voice {voice_spec}...")
+
+            # Use the programmatic download API
+            success = self.voice_manager.download_model(voice_spec)
+
             if success:
-                # Update current language to match the voice
-                self.current_language = language
+                # Now set the language to match
+                success = self.voice_manager.set_language(language)
 
-                # Get voice info for confirmation
-                voice_info = self.voice_manager.VOICE_CATALOG.get(language, {}).get(voice_id, {})
-                lang_name = self.voice_manager.get_language_name(language)
+                if success:
+                    # Update current language
+                    self.current_language = language
 
-                print(f"✅ Voice changed successfully!")
-                print(f"   Language: {lang_name} ({language})")
-                print(f"   Voice: {voice_id}")
-                if voice_info:
-                    quality_icon = "✨" if voice_info.get('quality') == 'premium' else "🔧"
-                    gender_icon = {"male": "👨", "female": "👩", "multiple": "👥"}.get(voice_info.get('gender'), "🗣️")
-                    print(f"   Details: {quality_icon} {gender_icon} {voice_info.get('accent', 'Unknown accent')}")
+                    print(f"✅ Voice set to {voice_spec}")
 
-                # Test the new voice
-                test_messages = {
-                    'en': "Voice changed to English.",
-                    'fr': "Voix changée en français.",
-                    'es': "Voz cambiada al español.",
-                    'de': "Stimme auf Deutsch geändert.",
-                    'it': "Voce cambiata in italiano."
-                }
-                test_msg = test_messages.get(language, "Voice changed successfully.")
-                self.voice_manager.speak(test_msg)
+                    # Test the voice
+                    test_messages = {
+                        'en': 'Voice changed to English.',
+                        'fr': 'Voix changée en français.',
+                        'es': 'Voz cambiada al español.',
+                        'de': 'Stimme auf Deutsch geändert.',
+                        'it': 'Voce cambiata in italiano.'
+                    }
+                    test_msg = test_messages.get(language, f'Voice changed to {language}.')
+                    self.voice_manager.speak(test_msg)
 
-                # Restart voice mode if it was active
-                if was_active:
-                    self.do_voice(self.voice_mode)
+                    # Restart voice mode if it was active
+                    if was_active:
+                        self.do_voice(self.voice_mode)
+                else:
+                    print(f"❌ Failed to set language: {language}")
             else:
-                print(f"❌ Failed to set voice: {voice_spec}")
-                print(f"   Run '/setvoice' to see available voices")
+                print(f"❌ Failed to download voice: {voice_spec}")
+                print("   Check your internet connection or try a different voice")
 
         except Exception as e:
             print(f"❌ Error setting voice: {e}")
+            print(f"   Run '/setvoice' to see available voices")
             if self.debug_mode:
                 import traceback
                 traceback.print_exc()

{abstractvoice-0.3.1 → abstractvoice-0.4.1}/abstractvoice/examples/voice_cli.py

@@ -11,18 +11,20 @@ from abstractvoice.examples.cli_repl import VoiceREPL
 
 def print_examples():
     """Print available examples."""
-    print("Available examples:")
-    print("  cli       - Command-line REPL example")
-    print("  web       - Web API example")
-    print("  simple    - Simple usage example")
-    print("  check-deps - Check dependency compatibility")
-    print("\nUsage: abstractvoice <example> [--language <lang>] [args...]")
+    print("Available commands:")
+    print("  cli            - Command-line REPL example")
+    print("  web            - Web API example")
+    print("  simple         - Simple usage example")
+    print("  check-deps     - Check dependency compatibility")
+    print("  download-models - Download TTS models for offline use")
+    print("\nUsage: abstractvoice <command> [--language <lang>] [args...]")
     print("\nSupported languages: en, fr, es, de, it, ru, multilingual")
     print("\nExamples:")
-    print("  abstractvoice cli --language fr    # French CLI")
-    print("  abstractvoice simple --language ru # Russian simple example")
-    print("  abstractvoice check-deps           # Check dependencies")
-    print("  abstractvoice                      # Direct voice mode (default)")
+    print("  abstractvoice cli --language fr     # French CLI")
+    print("  abstractvoice simple --language ru  # Russian simple example")
+    print("  abstractvoice check-deps            # Check dependencies")
+    print("  abstractvoice download-models       # Download models for offline use")
+    print("  abstractvoice                       # Direct voice mode (default)")
 
 def simple_example():
     """Run a simple example demonstrating basic usage."""
@@ -95,10 +97,22 @@ def simple_example():
 
 def parse_args():
     """Parse command line arguments."""
+    import sys
+
+    # Check if it's a download-models command and handle separately
+    if len(sys.argv) > 1 and sys.argv[1] == "download-models":
+        # Return early with just the command to handle in main()
+        class DownloadModelsArgs:
+            command = "download-models"
+            # Add dummy attributes to prevent AttributeError
+            model = "granite3.3:2b"
+            debug = False
+        return DownloadModelsArgs()
+
     parser = argparse.ArgumentParser(description="AbstractVoice - Voice interactions with AI")
 
     # Examples and special commands
-    parser.add_argument("command", nargs="?", help="Command to run: cli, web, simple, check-deps (default: voice mode)")
+    parser.add_argument("command", nargs="?", help="Command to run: cli, web, simple, check-deps, download-models (default: voice mode)")
 
     # Voice mode arguments
     parser.add_argument("--debug", action="store_true", help="Enable debug mode")
@@ -110,6 +124,8 @@ def parse_args():
                       help="Whisper model to use (tiny, base, small, medium, large)")
     parser.add_argument("--no-listening", action="store_true",
                       help="Disable speech-to-text (listening), TTS still works")
+    parser.add_argument("--no-tts", action="store_true",
+                      help="Disable text-to-speech (TTS), text-only mode")
     parser.add_argument("--system",
                       help="Custom system prompt")
     parser.add_argument("--temperature", type=float, default=0.4,
@@ -141,6 +157,17 @@ def main():
                     import traceback
                     traceback.print_exc()
             return
+        elif args.command == "download-models":
+            from abstractvoice.model_manager import download_models_cli
+            # Pass remaining arguments to download_models_cli
+            import sys
+            original_argv = sys.argv
+            sys.argv = ["download-models"] + sys.argv[2:]  # Remove script name and "download-models"
+            try:
+                download_models_cli()
+            finally:
+                sys.argv = original_argv
+            return
         elif args.command == "cli":
             # Import and run CLI REPL example
             repl = VoiceREPL(
@@ -188,7 +215,8 @@ def main():
             model=args.model,
             debug_mode=args.debug,
             language=args.language,
-            tts_model=args.tts_model
+            tts_model=args.tts_model,
+            disable_tts=args.no_tts
         )
         
         # Set custom system prompt if provided
@@ -224,22 +252,30 @@ def main():
         print("\nExiting AbstractVoice...")
     except Exception as e:
         error_msg = str(e).lower()
-        if "model file not found" in error_msg or "no such file" in error_msg:
-            print(f"❌ Model '{args.model}' not found")
-            print(f"   The model file is missing or not fully downloaded")
-            print(f"   Try: ollama pull {args.model}")
-            print(f"   Or check available models: ollama list")
-        elif "connection" in error_msg or "refused" in error_msg:
-            print(f"❌ Cannot connect to Ollama")
+
+        # Check if it's a TTS-related error (not Ollama model error)
+        if "model file not found in the output path" in error_msg:
+            print(f"❌ TTS model download failed")
+            print(f"   This is a TTS voice model issue, not your Ollama model")
+            print(f"   Your Ollama model '{args.model}' is fine")
+            print(f"   Try: rm -rf ~/.cache/tts && pip install --force-reinstall coqui-tts")
+            print(f"   Or check network connectivity for model downloads")
+        elif "ollama" in error_msg or "11434" in error_msg:
+            print(f"❌ Cannot connect to Ollama at {args.api}")
             print(f"   Make sure Ollama is running: ollama serve")
-            print(f"   API URL: {args.api}")
+            print(f"   Your model '{args.model}' exists but Ollama server isn't responding")
         elif "importerror" in error_msg or "no module" in error_msg:
             print(f"❌ Missing dependencies")
             print(f"   Try running: abstractvoice check-deps")
             print(f"   Or install dependencies: pip install abstractvoice[voice-full]")
+        elif "espeak" in error_msg or "phoneme" in error_msg:
+            print(f"❌ Voice synthesis setup issue")
+            print(f"   Install espeak-ng for better voice quality: brew install espeak-ng")
+            print(f"   Or this might be a TTS model download issue")
         else:
             print(f"❌ Application error: {e}")
             print(f"   Try running with --debug for more details")
+            print(f"   Note: Your Ollama model '{args.model}' appears to be available")
 
         if args.debug:
             import traceback