abstractcore 2.5.0__py3-none-any.whl → 2.5.3__py3-none-any.whl

abstractcore/core/session.py

@@ -34,9 +34,10 @@ class BasicSession:
                  auto_compact: bool = False,
                  auto_compact_threshold: int = 6000,
                  temperature: Optional[float] = None,
-                 seed: Optional[int] = None):
+                 seed: Optional[int] = None,
+                 enable_tracing: bool = False):
         """Initialize basic session
-        
+
         Args:
             provider: LLM provider instance
             system_prompt: System prompt for the session
@@ -48,6 +49,7 @@ class BasicSession:
             auto_compact_threshold: Token threshold for auto-compaction
             temperature: Default temperature for generation (0.0-1.0)
             seed: Default seed for deterministic generation
+            enable_tracing: Enable interaction tracing for observability
         """
 
         self.provider = provider
@@ -59,11 +61,15 @@ class BasicSession:
         self.auto_compact = auto_compact
         self.auto_compact_threshold = auto_compact_threshold
         self._original_session = None  # Track if this is a compacted session
-        
+
         # Store session-level generation parameters
         self.temperature = temperature
         self.seed = seed
-        
+
+        # Setup interaction tracing
+        self.enable_tracing = enable_tracing
+        self.interaction_traces: List[Dict[str, Any]] = []  # Session-specific traces
+
         # Optional analytics fields
         self.summary = None
         self.assessment = None
@@ -214,6 +220,16 @@ class BasicSession:
         if 'seed' not in kwargs and self.seed is not None:
             kwargs['seed'] = self.seed
 
+        # Add trace metadata if tracing is enabled
+        if self.enable_tracing:
+            if 'trace_metadata' not in kwargs:
+                kwargs['trace_metadata'] = {}
+            kwargs['trace_metadata'].update({
+                'session_id': self.id,
+                'step_type': kwargs.get('step_type', 'chat'),
+                'attempt_number': kwargs.get('attempt_number', 1)
+            })
+
         # Call provider
         response = self.provider.generate(
             prompt=prompt,
@@ -231,6 +247,14 @@ class BasicSession:
             # Non-streaming response
             if hasattr(response, 'content') and response.content:
                 self.add_message('assistant', response.content)
+
+            # Capture trace if enabled and available
+            if self.enable_tracing and hasattr(self.provider, 'get_traces'):
+                if hasattr(response, 'metadata') and response.metadata and 'trace_id' in response.metadata:
+                    trace = self.provider.get_traces(response.metadata['trace_id'])
+                    if trace:
+                        self.interaction_traces.append(trace)
+
             return response
 
     def _handle_streaming_response(self, response_iterator: Iterator[GenerateResponse]) -> Iterator[GenerateResponse]:
@@ -893,4 +917,80 @@ class BasicSession:
             "statistics": extraction_result.get("statistics", {})
         }
         
-        return self.facts
+        return self.facts
+
+    def analyze_intents(self, 
+                       focus_participant: Optional[str] = None,
+                       depth: str = "underlying",
+                       context_type: str = "conversational") -> Dict[str, Any]:
+        """
+        Analyze intents in the conversation using BasicIntentAnalyzer.
+        
+        Args:
+            focus_participant: Optional role to focus analysis on (e.g., "user", "assistant")
+            depth: Depth of intent analysis ("surface", "underlying", "comprehensive")
+            context_type: Context type for analysis ("conversational" is default for sessions)
+            
+        Returns:
+            Dict containing intent analysis results for each participant
+        """
+        if not self.messages:
+            return {}
+            
+        if not self.provider:
+            raise ValueError("No provider available for intent analysis")
+        
+        try:
+            from ..processing import BasicIntentAnalyzer, IntentDepth, IntentContext
+        except ImportError:
+            raise ImportError("BasicIntentAnalyzer not available")
+        
+        # Create intent analyzer
+        analyzer = BasicIntentAnalyzer(self.provider)
+        
+        # Convert depth and context strings to enums
+        depth_enum = IntentDepth(depth)
+        context_enum = IntentContext(context_type)
+        
+        # Convert session messages to the format expected by analyze_conversation_intents
+        message_dicts = [{"role": msg.role, "content": msg.content} for msg in self.messages]
+        
+        # Analyze conversation intents
+        results = analyzer.analyze_conversation_intents(
+            messages=message_dicts,
+            focus_participant=focus_participant,
+            depth=depth_enum
+        )
+
+        return results
+
+    def get_interaction_history(self) -> List[Dict[str, Any]]:
+        """
+        Get all interaction traces for this session.
+
+        Returns a list of all LLM interaction traces captured during the session.
+        Each trace contains complete information about the prompt, parameters,
+        and response for observability and debugging.
+
+        Returns:
+            List of trace dictionaries containing:
+                - trace_id: Unique identifier for the interaction
+                - timestamp: ISO format timestamp
+                - provider: Provider name
+                - model: Model name
+                - prompt: User prompt
+                - system_prompt: System prompt (if any)
+                - messages: Conversation history
+                - parameters: Generation parameters (temperature, tokens, etc.)
+                - response: Full response with content, usage, timing
+                - metadata: Custom metadata (session_id, step_type, etc.)
+
+        Example:
+            >>> session = BasicSession(provider=llm, enable_tracing=True)
+            >>> response = session.generate("What is Python?")
+            >>> traces = session.get_interaction_history()
+            >>> print(f"Captured {len(traces)} interactions")
+            >>> print(f"First trace: {traces[0]['trace_id']}")
+            >>> print(f"Tokens used: {traces[0]['response']['usage']}")
+        """
+        return self.interaction_traces.copy()

abstractcore/events/__init__.py

@@ -216,7 +216,7 @@ def emit_global(event_type: EventType, data: Dict[str, Any], source: Optional[st
 def create_generation_event(model_name: str, provider_name: str,
                           tokens_input: int = None, tokens_output: int = None,
                           duration_ms: float = None, cost_usd: float = None,
-                          **data) -> Dict[str, Any]:
+                          **data) -> tuple[Dict[str, Any], Dict[str, Any]]:
     """Create standardized generation event data"""
     event_data = {
         "model_name": model_name,

abstractcore/media/auto_handler.py

@@ -13,6 +13,25 @@ from typing import Dict, Any, Optional, List
 from .base import BaseMediaHandler
 from .types import MediaContent, MediaType, ContentFormat, detect_media_type
 from .processors import ImageProcessor, TextProcessor, PDFProcessor, OfficeProcessor
+from ..exceptions import UnsupportedFeatureError
+
+# Import Glyph compression support
+try:
+    from ..compression.orchestrator import CompressionOrchestrator
+    from ..compression.config import GlyphConfig
+    GLYPH_AVAILABLE = True
+except ImportError:
+    CompressionOrchestrator = None
+    GlyphConfig = None
+    GLYPH_AVAILABLE = False
+
+# Import vision detection
+try:
+    from ..architectures.detection import supports_vision
+    VISION_DETECTION_AVAILABLE = True
+except ImportError:
+    supports_vision = None
+    VISION_DETECTION_AVAILABLE = False
 
 
 class AutoMediaHandler(BaseMediaHandler):
@@ -41,6 +60,11 @@ class AutoMediaHandler(BaseMediaHandler):
         self._text_processor = None
         self._pdf_processor = None
         self._office_processor = None
+        
+        # Initialize Glyph compression support
+        self._compression_orchestrator = None
+        self.glyph_config = kwargs.get('glyph_config')
+        self.enable_compression = kwargs.get('enable_glyph_compression', GLYPH_AVAILABLE)
 
         # Track which processors are available
         self._available_processors = self._check_processor_availability()
@@ -74,6 +98,20 @@ class AutoMediaHandler(BaseMediaHandler):
             availability['office'] = True
         except ImportError:
             availability['office'] = False
+        
+        # GlyphProcessor (requires reportlab and pdf2image)
+        glyph_deps_available = True
+        if GLYPH_AVAILABLE and self.enable_compression:
+            # Check actual dependencies
+            try:
+                import reportlab
+                import pdf2image
+            except ImportError:
+                glyph_deps_available = False
+        else:
+            glyph_deps_available = False
+            
+        availability['glyph'] = glyph_deps_available
 
         return availability
 
@@ -100,6 +138,13 @@ class AutoMediaHandler(BaseMediaHandler):
         if self._office_processor is None:
             self._office_processor = OfficeProcessor(**self.processor_config)
         return self._office_processor
+    
+    def _get_compression_orchestrator(self) -> 'CompressionOrchestrator':
+        """Get or create CompressionOrchestrator instance."""
+        if self._compression_orchestrator is None and GLYPH_AVAILABLE:
+            config = self.glyph_config or GlyphConfig.from_abstractcore_config()
+            self._compression_orchestrator = CompressionOrchestrator(config)
+        return self._compression_orchestrator
 
     def _select_processor(self, file_path: Path, media_type: MediaType) -> Optional[BaseMediaHandler]:
         """
@@ -167,6 +212,20 @@ class AutoMediaHandler(BaseMediaHandler):
         Returns:
             MediaContent object with processed content
         """
+        # Check if Glyph compression should be applied
+        provider = kwargs.get('provider')
+        model = kwargs.get('model')
+        glyph_compression = kwargs.get('glyph_compression', 'auto')
+        
+        if self._should_apply_compression(file_path, media_type, provider, model, glyph_compression):
+            try:
+                # Remove provider and model from kwargs to avoid duplicate arguments
+                compression_kwargs = {k: v for k, v in kwargs.items() if k not in ['provider', 'model']}
+                return self._apply_compression(file_path, provider, model, **compression_kwargs)
+            except Exception as e:
+                self.logger.warning(f"Glyph compression failed, falling back to standard processing: {e}")
+                # Continue with standard processing
+        
         # Select the appropriate processor
         processor = self._select_processor(file_path, media_type)
 
@@ -218,6 +277,221 @@ class AutoMediaHandler(BaseMediaHandler):
             fallback_processing=True,
             available_processors=list(self._available_processors.keys())
         )
+    
+    def _should_apply_compression(self, file_path: Path, media_type: MediaType,
+                                provider: str, model: str, glyph_compression: str) -> bool:
+        """
+        Check if Glyph compression should be applied.
+
+        ⚠️ EXPERIMENTAL FEATURE: Glyph compression requires vision-capable models.
+
+        Raises:
+            UnsupportedFeatureError: When glyph_compression="always" but model lacks vision support
+        """
+        # Check if Glyph is available
+        if not self._available_processors.get('glyph', False):
+            if glyph_compression == "always":
+                # User explicitly requested compression but it's not available
+                self._log_compression_unavailable_warning()
+            return False
+
+        if glyph_compression == "never":
+            return False
+
+        # Check vision support for compression
+        model_supports_vision = self._check_vision_support(model)
+
+        if glyph_compression == "always":
+            # Explicit compression request - enforce vision requirement
+            if not model_supports_vision:
+                raise UnsupportedFeatureError(
+                    f"Glyph compression requires a vision-capable model. "
+                    f"Model '{model}' does not support vision. "
+                    f"Vision-capable models include: gpt-4o, gpt-4o-mini, claude-3-5-sonnet, "
+                    f"llama3.2-vision, qwen2-vl, gemini-1.5-pro, gemini-1.5-flash, etc."
+                )
+            return True
+
+        # Auto-decision logic
+        if not provider or not model:
+            return False
+
+        # Only compress text-based content
+        if media_type not in [MediaType.TEXT, MediaType.DOCUMENT]:
+            return False
+
+        # Auto mode: check vision support and warn if not supported
+        if not model_supports_vision:
+            self.logger.warning(
+                f"Glyph compression skipped: model '{model}' does not support vision. "
+                f"Use a vision-capable model to enable compression."
+            )
+            return False
+
+        try:
+            orchestrator = self._get_compression_orchestrator()
+            if orchestrator:
+                return orchestrator.should_compress(file_path, provider, model, glyph_compression)
+        except Exception as e:
+            self.logger.debug(f"Compression decision failed: {e}")
+
+        return False
+
+    def _check_vision_support(self, model: str) -> bool:
+        """
+        Check if the model supports vision capabilities.
+
+        Args:
+            model: Model name to check
+
+        Returns:
+            True if model supports vision, False otherwise
+        """
+        if not model or not VISION_DETECTION_AVAILABLE:
+            # Conservative approach: assume no vision if detection unavailable
+            return False
+
+        try:
+            return supports_vision(model)
+        except Exception as e:
+            self.logger.debug(f"Failed to check vision support for model '{model}': {e}")
+            return False
+
+    def _log_compression_unavailable_warning(self):
+        """Log detailed warning about why Glyph compression is unavailable."""
+        self.logger.warning("Glyph compression requested but not available")
+        
+        # Check specific reasons
+        if not GLYPH_AVAILABLE:
+            self.logger.warning("Glyph compression modules could not be imported")
+            
+        # Check dependencies
+        missing_deps = []
+        try:
+            import reportlab
+        except ImportError:
+            missing_deps.append("reportlab")
+            
+        try:
+            import pdf2image
+        except ImportError:
+            missing_deps.append("pdf2image")
+            
+        if missing_deps:
+            deps_str = ", ".join(missing_deps)
+            self.logger.warning(f"Missing Glyph dependencies: {deps_str}")
+            self.logger.warning(f"Install with: pip install {' '.join(missing_deps)}")
+        
+        if not self.enable_compression:
+            self.logger.warning("Glyph compression is disabled in AutoMediaHandler configuration")
+    
+    def _apply_compression(self, file_path: Path, provider: str, model: str, **kwargs) -> MediaContent:
+        """Apply Glyph compression to the file."""
+        media_type = detect_media_type(file_path)
+        
+        # For PDF files, use direct PDF-to-image conversion (no text extraction!)
+        if media_type == MediaType.DOCUMENT and file_path.suffix.lower() == '.pdf':
+            try:
+                from .processors.direct_pdf_processor import DirectPDFProcessor
+                
+                # Configure for optimal compression (2 pages per image)
+                direct_processor = DirectPDFProcessor(
+                    pages_per_image=2,  # 16 pages → 8 images
+                    dpi=150,  # Good quality for VLM processing
+                    layout='horizontal',  # Side-by-side like open book
+                    gap=20,  # Small gap between pages
+                    **kwargs
+                )
+                
+                # Get all combined images
+                combined_images = direct_processor.get_combined_image_paths(file_path)
+                
+                # Get session info for metadata from DirectPDFProcessor
+                from ..config import get_config_manager
+                import hashlib
+                config_manager = get_config_manager()
+                glyph_cache_base = Path(config_manager.config.cache.glyph_cache_dir).expanduser()
+                pdf_hash = hashlib.md5(str(file_path).encode()).hexdigest()[:8]
+                session_id = f"pdf_{pdf_hash}_{len(combined_images)}pages"
+                
+                # Create MediaContent objects for each combined image
+                media_contents = []
+                for i, img_path in enumerate(combined_images):
+                    with open(img_path, 'rb') as f:
+                        image_data = f.read()
+                    
+                    import base64
+                    encoded_data = base64.b64encode(image_data).decode('utf-8')
+                    
+                    media_content = MediaContent(
+                        media_type=MediaType.IMAGE,
+                        content=encoded_data,
+                        content_format=ContentFormat.BASE64,
+                        mime_type="image/png",
+                        metadata={
+                            'compression_used': True,
+                            'compression_method': 'direct_pdf_conversion',
+                            'pages_per_image': 2,
+                            'image_index': i,
+                            'total_images': len(combined_images),
+                            'original_file': str(file_path),
+                            'glyph_session_id': session_id,
+                            'glyph_cache_dir': str(glyph_cache_base / session_id),
+                            'processing_method': 'direct_pdf_conversion'  # For compatibility with test script
+                        }
+                    )
+                    media_contents.append(media_content)
+                
+                self.logger.info(f"Direct PDF conversion: {len(combined_images)} combined images created")
+                
+                # Return first image (in full implementation, would handle multiple)
+                if media_contents:
+                    return media_contents[0]
+                else:
+                    raise Exception("No combined images created")
+                    
+            except Exception as e:
+                self.logger.warning(f"DirectPDFProcessor failed: {e}, falling back to text extraction")
+                # Fall back to text extraction method
+                pass
+        
+        # Fallback: text extraction method (for non-PDF or if direct method fails)
+        orchestrator = self._get_compression_orchestrator()
+        if not orchestrator:
+            raise Exception("Compression orchestrator not available")
+        
+        if media_type == MediaType.DOCUMENT and file_path.suffix.lower() == '.pdf':
+            processor = self._get_pdf_processor()
+        elif media_type == MediaType.DOCUMENT:
+            processor = self._get_office_processor()
+        else:
+            processor = self._get_text_processor()
+        
+        # Extract text content
+        extracted_content = processor._process_internal(file_path, media_type, **kwargs)
+        text_content = extracted_content.content
+        
+        # Compress the extracted text content
+        glyph_compression = kwargs.get('glyph_compression', 'auto')
+        compressed_content = orchestrator.compress_content(text_content, provider, model, glyph_compression)
+        
+        if compressed_content and len(compressed_content) > 0:
+            # Return first compressed image as primary content
+            # Additional images can be accessed through metadata
+            primary_content = compressed_content[0]
+            
+            # Add information about additional images
+            if len(compressed_content) > 1:
+                primary_content.metadata['additional_images'] = len(compressed_content) - 1
+                primary_content.metadata['total_compressed_images'] = len(compressed_content)
+            
+            # Add compression metadata
+            primary_content.metadata['compression_used'] = True
+            primary_content.metadata['original_file'] = str(file_path)
+            
+            return primary_content
+        else:
+            raise Exception("No compressed content generated")
 
     def supports_media_type(self, media_type: MediaType) -> bool:
         """
@@ -259,9 +533,9 @@ class AutoMediaHandler(BaseMediaHandler):
             return format_ext.lower() in image_formats
 
         elif media_type == MediaType.TEXT:
-            # Text formats (always available)
-            text_formats = {'txt', 'md', 'csv', 'tsv', 'json', 'yaml', 'yml'}
-            return format_ext.lower() in text_formats
+            # TextProcessor can handle ANY text file through its plain text fallback
+            # This is always available and supports all text-based files
+            return True
 
         elif media_type == MediaType.DOCUMENT:
             # PDF support
@@ -272,9 +546,9 @@ class AutoMediaHandler(BaseMediaHandler):
             if format_ext.lower() in {'docx', 'xlsx', 'pptx'}:
                 return self._available_processors.get('office', False) or True  # Fallback to text
 
-            # Text document support (always available)
-            text_formats = {'txt', 'md', 'csv', 'tsv', 'json', 'yaml', 'yml'}
-            return format_ext.lower() in text_formats
+            # Any other document type can be handled by text processor as fallback
+            # This allows processing of unknown document formats
+            return True
 
         return False
 
@@ -282,27 +556,47 @@ class AutoMediaHandler(BaseMediaHandler):
         """
         Get supported formats organized by media type.
 
+        Returns comprehensive list of all supported file extensions.
+        Note: TEXT type supports ANY text-based file through content detection
+        and fallback processing, not just the listed extensions.
+
         Returns:
             Dictionary mapping media type to list of supported extensions
+
+        Example:
+            >>> handler = AutoMediaHandler()
+            >>> formats = handler.get_supported_formats()
+            >>> len(formats['text'])  # 70+ text extensions
+            70+
+            >>> 'r' in formats['text']  # R scripts supported
+            True
         """
-        formats = {}
+        from .types import get_all_supported_extensions
 
-        # Image formats
-        if self._available_processors.get('image', False):
-            formats['image'] = ['jpg', 'jpeg', 'png', 'gif', 'bmp', 'tiff', 'webp']
+        # Get comprehensive list from FILE_TYPE_MAPPINGS
+        all_formats = get_all_supported_extensions()
 
-        # Document formats
-        doc_formats = ['txt', 'md', 'csv', 'tsv', 'json', 'yaml', 'yml']
+        # Filter based on available processors
+        result = {}
 
-        if self._available_processors.get('pdf', False):
-            doc_formats.append('pdf')
+        # Image formats (requires PIL)
+        if self._available_processors.get('image', False):
+            result['image'] = all_formats.get('image', [])
 
-        if self._available_processors.get('office', False):
-            doc_formats.extend(['docx', 'xlsx', 'pptx'])
+        # Text formats (always available - TextProcessor has built-in fallback)
+        # Note: This includes 70+ extensions + unknown text files via content detection
+        result['text'] = all_formats.get('text', [])
+
+        # Document formats (includes PDFs, Office docs, and text fallbacks)
+        result['document'] = all_formats.get('document', [])
 
-        formats['document'] = doc_formats
+        # Audio/Video (not yet implemented but listed for completeness)
+        if 'audio' in all_formats:
+            result['audio'] = all_formats['audio']
+        if 'video' in all_formats:
+            result['video'] = all_formats['video']
 
-        return formats
+        return result
 
     def get_processor_info(self) -> Dict[str, Any]:
         """

abstractcore/media/handlers/local_handler.py

@@ -412,12 +412,24 @@ class LocalMediaHandler(BaseProviderMediaHandler):
             if media_content.media_type == MediaType.IMAGE and self.can_handle_media(media_content):
                 if media_content.content_format == ContentFormat.BASE64:
                     data_url = f"data:{media_content.mime_type};base64,{media_content.content}"
-                    content.append({
+                    image_obj = {
                         "type": "image_url",
                         "image_url": {
                             "url": data_url
                         }
-                    })
+                    }
+                    
+                    # Add detail level if specified in metadata (for Qwen models)
+                    detail_level = media_content.metadata.get('detail_level', 'auto')
+                    self.logger.debug(f"MediaContent metadata: {media_content.metadata}")
+                    self.logger.debug(f"Found detail_level: {detail_level}")
+                    if detail_level in ['low', 'high', 'auto']:
+                        image_obj["image_url"]["detail"] = detail_level
+                        self.logger.info(f"Setting detail level to '{detail_level}' for LMStudio image")
+                    else:
+                        self.logger.warning(f"Invalid detail level '{detail_level}', skipping")
+                    
+                    content.append(image_obj)
                 else:
                     self.logger.warning(f"LMStudio requires base64 image format, got {media_content.content_format}")