abstractcore 2.4.2__py3-none-any.whl → 2.4.4__py3-none-any.whl

abstractcore/tools/common_tools.py

@@ -121,7 +121,8 @@ def list_files(directory_path: str = ".", pattern: str = "*", recursive: bool =
             except ValueError:
                 head_limit = 50  # fallback to default
         
-        directory = Path(directory_path)
+        # Expand home directory shortcuts like ~
+        directory = Path(directory_path).expanduser()
 
         if not directory.exists():
             return f"Error: Directory '{directory_path}' does not exist"
@@ -302,7 +303,8 @@ def search_files(
             except ValueError:
                 head_limit = 20  # fallback to default
         
-        search_path = Path(path)
+        # Expand home directory shortcuts like ~
+        search_path = Path(path).expanduser()
 
         # Compile regex pattern
         flags = 0 if case_sensitive else re.IGNORECASE
@@ -651,7 +653,8 @@ def read_file(file_path: str, should_read_entire_file: bool = True, start_line_o
         File contents or error message
     """
     try:
-        path = Path(file_path)
+        # Expand home directory shortcuts like ~
+        path = Path(file_path).expanduser()
 
         if not path.exists():
             return f"Error: File '{file_path}' does not exist"
@@ -765,8 +768,8 @@ def write_file(file_path: str, content: str = "", mode: str = "w", create_dirs:
         OSError: If there are filesystem issues
     """
     try:
-        # Convert to Path object for better handling
-        path = Path(file_path)
+        # Convert to Path object for better handling and expand home directory shortcuts like ~
+        path = Path(file_path).expanduser()
 
         # Create parent directories if requested and they don't exist
         if create_dirs and path.parent != path:
@@ -1073,8 +1076,8 @@ def edit_file(
         edit_file("test.py", "class OldClass", "class NewClass", preview_only=True)
     """
     try:
-        # Validate file exists
-        path = Path(file_path)
+        # Validate file exists and expand home directory shortcuts like ~
+        path = Path(file_path).expanduser()
         if not path.exists():
             return f"❌ File not found: {file_path}"
 
@@ -1344,7 +1347,8 @@ def execute_command(
 
         # Working directory validation
         if working_directory:
-            working_dir = Path(working_directory).resolve()
+            # Expand home directory shortcuts like ~ before resolving
+            working_dir = Path(working_directory).expanduser().resolve()
             if not working_dir.exists():
                 return f"❌ Error: Working directory does not exist: {working_directory}"
             if not working_dir.is_dir():

abstractcore/utils/__init__.py

@@ -5,13 +5,14 @@ Utility functions for AbstractCore.
 from .structured_logging import configure_logging, get_logger, capture_session
 from .version import __version__
 from .token_utils import (
-    TokenUtils, 
-    count_tokens, 
-    estimate_tokens, 
+    TokenUtils,
+    count_tokens,
+    estimate_tokens,
     count_tokens_precise,
     TokenCountMethod,
     ContentType
 )
+from .message_preprocessor import MessagePreprocessor, parse_files, has_files
 
 __all__ = [
     'configure_logging',
@@ -20,8 +21,11 @@ __all__ = [
     '__version__',
     'TokenUtils',
     'count_tokens',
-    'estimate_tokens', 
+    'estimate_tokens',
     'count_tokens_precise',
     'TokenCountMethod',
-    'ContentType'
+    'ContentType',
+    'MessagePreprocessor',
+    'parse_files',
+    'has_files'
 ]

abstractcore/utils/cli.py

@@ -25,6 +25,18 @@ import sys
 import time
 from typing import Optional
 
+# Enable command history and arrow key navigation
+try:
+    import readline
+    # Configure readline for better history behavior
+    readline.set_startup_hook(lambda: readline.insert_text(''))
+    readline.parse_and_bind("tab: complete")
+    # Set a reasonable history length
+    readline.set_history_length(1000)
+except ImportError:
+    # readline not available (typically on Windows)
+    readline = None
+
 from .. import create_llm, BasicSession
 from ..tools.common_tools import list_files, read_file, write_file, execute_command, search_files
 from ..processing import BasicExtractor, BasicJudge
@@ -57,11 +69,14 @@ class SimpleCLI:
 
         self.max_tokens = max_tokens
 
+        # Initialize command history with persistent storage
+        self._setup_command_history()
+
         # Initialize provider and session with tools
         self.provider = create_llm(provider, model=model, max_tokens=max_tokens, **kwargs)
         self.session = BasicSession(
             self.provider,
-            system_prompt="You are a helpful AI assistant.",
+            system_prompt="You are a helpful AI assistant with vision capabilities. When users provide images or media files, analyze and describe them directly. You also have access to file operation tools.",
             tools=[list_files, read_file, write_file, execute_command, search_files]
         )
 
@@ -81,6 +96,47 @@ class SimpleCLI:
             print("💡 Ask questions naturally or use tools: 'What files are here?'")
             print("=" * 70)
 
+    def _setup_command_history(self):
+        """Setup command history with persistent storage."""
+        if readline is None:
+            return  # No readline support available
+
+        # Store history in user's home directory
+        import os
+        import pathlib
+
+        # Create .abstractcore directory if it doesn't exist
+        history_dir = pathlib.Path.home() / '.abstractcore'
+        history_dir.mkdir(exist_ok=True)
+
+        # Define history file path
+        self.history_file = history_dir / 'cli_history.txt'
+
+        try:
+            # Load existing history if file exists
+            if self.history_file.exists():
+                readline.read_history_file(str(self.history_file))
+                if self.debug_mode:
+                    history_size = readline.get_current_history_length()
+                    print(f"🔍 Loaded {history_size} command(s) from history")
+        except (FileNotFoundError, PermissionError) as e:
+            if self.debug_mode:
+                print(f"⚠️ Could not load command history: {e}")
+
+    def _save_command_history(self):
+        """Save current command history to disk."""
+        if readline is None or not hasattr(self, 'history_file'):
+            return
+
+        try:
+            # Ensure the directory exists
+            self.history_file.parent.mkdir(exist_ok=True)
+            # Save history to file
+            readline.write_history_file(str(self.history_file))
+        except (PermissionError, OSError) as e:
+            if self.debug_mode:
+                print(f"⚠️ Could not save command history: {e}")
+
     def handle_command(self, user_input: str) -> bool:
         """Handle commands. Returns True if command processed, False otherwise."""
         if not user_input.startswith('/'):
@@ -89,6 +145,7 @@ class SimpleCLI:
         cmd = user_input[1:].strip()
 
         if cmd in ['quit', 'exit', 'q']:
+            self._save_command_history()
             print("👋 Goodbye!")
             sys.exit(0)
 
@@ -101,7 +158,8 @@ class SimpleCLI:
             print("─" * 50)
             print("  /help                    Show this comprehensive help")
             print("  /quit                    Exit the CLI")
-            print("  /clear                   Clear conversation history")
+            print("  /clear                   Clear the screen (like unix terminal)")
+            print("  /reset                   Reset conversation history")
             print("  /status                  Show system status and capabilities")
             
             print("\n💬 CONVERSATION MANAGEMENT")
@@ -153,11 +211,22 @@ class SimpleCLI:
             print("  • write_file             Create or modify files")
             print("  • execute_command        Run shell commands")
             
+            print("\n📎 FILE ATTACHMENTS")
+            print("─" * 50)
+            print("  Use @filename syntax to attach files to your message:")
+            print("  • Images: 'Analyze this screenshot @screenshot.png'")
+            print("  • Documents: 'Summarize @report.pdf and @data.csv'")
+            print("  • Multiple files: 'Compare @image1.jpg @image2.jpg @notes.txt'")
+            print("  • Vision analysis: Works with vision models (GPT-4o, Claude, qwen2.5vl)")
+            print("  • Auto-fallback: Text-only models use vision captioning for images")
+            print("  • Supported formats: Images (jpg, png, gif), PDFs, Office docs, text files")
+
             print("\n💡 TIPS & EXAMPLES")
             print("─" * 50)
             print("  • Ask questions naturally: 'What files are in this directory?'")
             print("  • Search inside files: 'Find all TODO comments in Python files'")
             print("  • Request file operations: 'Read the README.md file'")
+            print("  • Attach files: 'What's in this image? @photo.jpg'")
             print("  • Save important conversations: '/save project_discussion --summary'")
             print("  • Switch models for different tasks: '/model ollama:qwen3-coder:30b'")
             print("  • Use /status to check token usage and model capabilities")
@@ -167,8 +236,13 @@ class SimpleCLI:
             print("=" * 70 + "\n")
 
         elif cmd == 'clear':
+            # Clear the screen like in unix terminal
+            import os
+            os.system('cls' if os.name == 'nt' else 'clear')
+
+        elif cmd == 'reset':
             self.session.clear_history(keep_system=True)
-            print("🧹 History cleared")
+            print("🧹 Chat history reset")
 
         elif cmd == 'stream':
             self.stream_mode = not self.stream_mode
@@ -208,7 +282,7 @@ class SimpleCLI:
                                          max_tokens=self.max_tokens, **self.kwargs)
                 self.session = BasicSession(
                     self.provider,
-                    system_prompt="You are a helpful AI assistant.",
+                    system_prompt="You are a helpful AI assistant with vision capabilities. When users provide images or media files, analyze and describe them directly. You also have access to file operation tools.",
                     tools=[list_files, read_file, write_file, execute_command, search_files]
                 )
                 print("✅ Model switched")
@@ -898,18 +972,62 @@ class SimpleCLI:
 
         print("=" * 60)
 
+    def _parse_file_attachments(self, user_input: str):
+        """Parse @filename references using AbstractCore's message preprocessor."""
+        from ..utils.message_preprocessor import MessagePreprocessor
+        import os
+
+        # Use AbstractCore's centralized file parsing logic
+        clean_input, media_files = MessagePreprocessor.parse_file_attachments(
+            user_input,
+            validate_existence=True,
+            verbose=self.debug_mode
+        )
+
+        # Show user-friendly status messages for CLI (only in interactive mode)
+        if media_files and not self.single_prompt_mode:
+            print(f"📎 Attaching {len(media_files)} file(s): {', '.join(media_files)}")
+
+            # Check for vision capabilities if images are attached
+            image_extensions = {'.jpg', '.jpeg', '.png', '.gif', '.bmp', '.tiff', '.webp'}
+            image_files = [f for f in media_files if os.path.splitext(f.lower())[1] in image_extensions]
+
+            if image_files:
+                try:
+                    from ..media.capabilities import is_vision_model
+                    if is_vision_model(self.model_name):
+                        print(f"👁️  Vision model detected - will analyze {len(image_files)} image(s)")
+                    else:
+                        print(f"📷 Text model - will use vision fallback for {len(image_files)} image(s)")
+                except:
+                    print(f"📷 Processing {len(image_files)} image(s)")
+
+        return clean_input, media_files
+
     def generate_response(self, user_input: str):
-        """Generate and display response with tool execution."""
+        """Generate and display response with tool execution and file attachment support."""
         import re
         start_time = time.time()
 
         try:
+            # Parse @filename attachments
+            clean_input, media_files = self._parse_file_attachments(user_input)
+
+            # If no text remains after removing file references, provide default prompt
+            if not clean_input and media_files:
+                clean_input = "Please analyze the attached file(s)."
+
             if self.debug_mode:
                 print(f"🔍 Sending to {self.provider_name}:{self.model_name}")
-
-            # Don't pass tool_call_tags to avoid format confusion
-            # Let the model use its native format, we'll parse it universally
-            response = self.session.generate(user_input, stream=self.stream_mode)
+                if media_files:
+                    print(f"🔍 Media files: {media_files}")
+
+            # Generate response with media support
+            response = self.session.generate(
+                clean_input,
+                stream=self.stream_mode,
+                media=media_files if media_files else None
+            )
 
             if self.stream_mode:
                 if not self.single_prompt_mode:
@@ -1180,10 +1298,12 @@ class SimpleCLI:
                     print("\n\n👋 Use /quit to exit.")
                     continue
                 except EOFError:
+                    self._save_command_history()
                     print("\n👋 Goodbye!")
                     break
 
         except Exception as e:
+            self._save_command_history()
             print(f"❌ Fatal error: {e}")
 
     def run_single_prompt(self, prompt: str):
@@ -1205,7 +1325,7 @@ Examples:
   python -m abstractcore.utils.cli --provider ollama --model qwen3-coder:30b
   python -m abstractcore.utils.cli --provider openai --model gpt-4o-mini --stream
   python -m abstractcore.utils.cli --provider anthropic --model claude-3-5-haiku-20241022
-  python -m abstractcore.utils.cli --provider ollama --model qwen3-coder:30b --prompt "What is Python?"
+  python -m abstractcore.utils.cli --prompt "What is Python?"  # Uses configured defaults
 
 Key Commands:
   /help                           Show comprehensive command guide
@@ -1221,17 +1341,26 @@ Key Commands:
 
 Tools: list_files, search_files, read_file, write_file, execute_command
 
+File Attachments:
+  Use @filename syntax to attach files: "Analyze @image.jpg and @doc.pdf"
+  Supports images, PDFs, Office docs, text files with automatic processing
+  Vision models analyze images directly; text models use vision fallback
+
+Configuration:
+  Set defaults with: abstractcore --set-app-default cli <provider> <model>
+  Check status with: abstractcore --status
+
 Note: This is a basic demonstrator with limited capabilities. For production
 use cases requiring advanced reasoning, ReAct patterns, or complex tool chains,
 build custom solutions using the AbstractCore framework directly.
         """
     )
 
-    # Required arguments
-    parser.add_argument('--provider', required=True,
+    # Optional arguments (no longer required - will use configured defaults)
+    parser.add_argument('--provider',
                        choices=['openai', 'anthropic', 'ollama', 'huggingface', 'mlx', 'lmstudio'],
-                       help='LLM provider to use')
-    parser.add_argument('--model', required=True, help='Model name to use')
+                       help='LLM provider to use (optional - uses configured default)')
+    parser.add_argument('--model', help='Model name to use (optional - uses configured default)')
 
     # Optional arguments
     parser.add_argument('--stream', action='store_true', help='Enable streaming mode')
@@ -1246,6 +1375,59 @@ build custom solutions using the AbstractCore framework directly.
 
     args = parser.parse_args()
 
+    # Load configuration manager for defaults
+    try:
+        from ..config import get_config_manager
+        config_manager = get_config_manager()
+    except Exception as e:
+        config_manager = None
+        if not args.provider or not args.model:
+            print(f"❌ Error loading configuration: {e}")
+            print("💡 Please specify --provider and --model explicitly")
+            sys.exit(1)
+
+    # Get provider and model from configuration if not specified
+    if not args.provider or not args.model:
+        if config_manager:
+            default_provider, default_model = config_manager.get_app_default('cli')
+
+            # Use configured defaults if available
+            provider = args.provider or default_provider
+            model = args.model or default_model
+
+            if not provider or not model:
+                print("❌ Error: No provider/model specified and no defaults configured")
+                print()
+                print("💡 Solutions:")
+                print("   1. Specify explicitly: --provider ollama --model gemma3:1b-it-qat")
+                print("   2. Configure defaults: abstractcore --set-app-default cli ollama gemma3:1b-it-qat")
+                print("   3. Check current config: abstractcore --status")
+                sys.exit(1)
+
+            # Show what we're using if defaults were applied
+            if not args.provider or not args.model:
+                if not args.prompt:  # Only show in interactive mode
+                    print(f"🔧 Using configured defaults: {provider}/{model}")
+                    print("   (Configure with: abstractcore --set-app-default cli <provider> <model>)")
+                    print()
+        else:
+            print("❌ Error: No provider/model specified and configuration unavailable")
+            sys.exit(1)
+    else:
+        # Use explicit arguments
+        provider = args.provider
+        model = args.model
+
+    # Get streaming default from configuration (only if --stream not explicitly provided)
+    if not args.stream and config_manager:
+        try:
+            default_streaming = config_manager.get_streaming_default('cli')
+            stream_mode = default_streaming
+        except Exception:
+            stream_mode = False  # Safe fallback
+    else:
+        stream_mode = args.stream
+
     # Build kwargs
     kwargs = {'temperature': args.temperature}
     if args.base_url:
@@ -1255,9 +1437,9 @@ build custom solutions using the AbstractCore framework directly.
 
     # Create CLI (suppress banner for single-prompt mode)
     cli = SimpleCLI(
-        provider=args.provider,
-        model=args.model,
-        stream=args.stream,
+        provider=provider,
+        model=model,
+        stream=stream_mode,
         max_tokens=args.max_tokens,
         debug=args.debug,
         show_banner=not args.prompt,  # Hide banner in single-prompt mode

abstractcore/utils/message_preprocessor.py

@@ -0,0 +1,182 @@
+"""
+Message preprocessing utilities for AbstractCore.
+
+This module provides utilities for parsing and preprocessing user messages,
+particularly for extracting file references using @filename syntax.
+Used across all AbstractCore applications for consistent behavior.
+"""
+
+import re
+import os
+from typing import Tuple, List, Optional
+
+
+class MessagePreprocessor:
+    """
+    Message preprocessing utilities for extracting file references and cleaning input.
+
+    Supports @filename syntax for attaching files to messages across all AbstractCore apps.
+    """
+
+    # Pattern to match @filename (supports various file extensions)
+    FILE_PATTERN = r'@([^\s@]+\.[\w]+)'
+
+    @staticmethod
+    def parse_file_attachments(user_input: str,
+                             validate_existence: bool = True,
+                             verbose: bool = False) -> Tuple[str, List[str]]:
+        """
+        Parse @filename references from user input and return cleaned text + file list.
+
+        Args:
+            user_input: The user's message that may contain @filename references
+            validate_existence: Whether to check if files actually exist (default: True)
+            verbose: Whether to log file processing details (default: False)
+
+        Returns:
+            Tuple of (clean_input_text, list_of_valid_file_paths)
+
+        Examples:
+            >>> clean_text, files = MessagePreprocessor.parse_file_attachments(
+            ...     "Analyze this image @screenshot.png and @data.csv"
+            ... )
+            >>> print(clean_text)
+            "Analyze this image  and"
+            >>> print(files)
+            ["screenshot.png", "data.csv"]
+        """
+        # Find all @filename references
+        matches = re.findall(MessagePreprocessor.FILE_PATTERN, user_input)
+
+        if not matches:
+            return user_input, []
+
+        valid_files = []
+        invalid_files = []
+
+        for filename in matches:
+            if not validate_existence or os.path.exists(filename):
+                valid_files.append(filename)
+                if verbose:
+                    size_kb = os.path.getsize(filename) / 1024 if validate_existence else 0
+                    print(f"📎 Found file: {filename} ({size_kb:.1f}KB)")
+            else:
+                invalid_files.append(filename)
+
+        # Show warnings for missing files if verbose mode
+        if verbose and invalid_files:
+            print(f"⚠️  Files not found: {', '.join(invalid_files)}")
+
+        # Remove @filename references from the input text
+        clean_input = re.sub(MessagePreprocessor.FILE_PATTERN, '', user_input)
+
+        # Clean up extra whitespace
+        clean_input = re.sub(r'\s+', ' ', clean_input).strip()
+
+        return clean_input, valid_files
+
+    @staticmethod
+    def has_file_attachments(user_input: str) -> bool:
+        """
+        Check if the user input contains any @filename references.
+
+        Args:
+            user_input: The message to check
+
+        Returns:
+            True if @filename patterns are found, False otherwise
+        """
+        return bool(re.search(MessagePreprocessor.FILE_PATTERN, user_input))
+
+    @staticmethod
+    def get_file_count(user_input: str) -> int:
+        """
+        Count the number of @filename references in the input.
+
+        Args:
+            user_input: The message to analyze
+
+        Returns:
+            Number of @filename patterns found
+        """
+        return len(re.findall(MessagePreprocessor.FILE_PATTERN, user_input))
+
+    @staticmethod
+    def extract_file_paths(user_input: str) -> List[str]:
+        """
+        Extract just the file paths from @filename references without validation.
+
+        Args:
+            user_input: The message containing @filename references
+
+        Returns:
+            List of file paths (may include non-existent files)
+        """
+        return re.findall(MessagePreprocessor.FILE_PATTERN, user_input)
+
+    @staticmethod
+    def process_message_with_media(user_input: str,
+                                 default_prompt: Optional[str] = None,
+                                 validate_files: bool = True,
+                                 verbose: bool = False) -> Tuple[str, List[str]]:
+        """
+        Process a message with @filename attachments, providing a default prompt if needed.
+
+        This is the main entry point for applications that want full message preprocessing.
+
+        Args:
+            user_input: The user's message
+            default_prompt: Default text to use if only files are specified (e.g., "Analyze the attached files")
+            validate_files: Whether to validate file existence
+            verbose: Whether to show processing details
+
+        Returns:
+            Tuple of (processed_prompt, media_file_list)
+        """
+        clean_input, media_files = MessagePreprocessor.parse_file_attachments(
+            user_input,
+            validate_existence=validate_files,
+            verbose=verbose
+        )
+
+        # If no text remains after removing file references, use default prompt
+        if not clean_input and media_files and default_prompt:
+            clean_input = default_prompt
+
+        return clean_input, media_files
+
+
+# Convenience functions for common use cases
+def parse_files(user_input: str, verbose: bool = False) -> Tuple[str, List[str]]:
+    """
+    Convenience function for basic file parsing.
+
+    Args:
+        user_input: Message with @filename references
+        verbose: Show processing details
+
+    Returns:
+        Tuple of (clean_text, file_list)
+    """
+    return MessagePreprocessor.parse_file_attachments(user_input, verbose=verbose)
+
+
+def has_files(user_input: str) -> bool:
+    """
+    Convenience function to check if message has file attachments.
+
+    Args:
+        user_input: Message to check
+
+    Returns:
+        True if @filename patterns found
+    """
+    return MessagePreprocessor.has_file_attachments(user_input)
+
+
+# Export main classes and functions
+__all__ = [
+    'MessagePreprocessor',
+    'parse_files',
+    'has_files'
+]