abstractcore 2.5.2__py3-none-any.whl → 2.6.0__py3-none-any.whl

abstractcore/providers/base.py

@@ -3,7 +3,10 @@ Base provider with integrated telemetry, events, and exception handling.
 """
 
 import time
-from typing import List, Dict, Any, Optional, Union, Iterator, Type
+import uuid
+import asyncio
+from collections import deque
+from typing import List, Dict, Any, Optional, Union, Iterator, AsyncIterator, Type
 from abc import ABC, abstractmethod
 
 try:
@@ -67,6 +70,13 @@ class BaseProvider(AbstractCoreInterface, ABC):
 
         # Create provider key for circuit breaker tracking
         self.provider_key = f"{self.__class__.__name__}:{self.model}"
+        
+        # Setup Glyph compression configuration
+        self.glyph_config = kwargs.get('glyph_config', None)
+
+        # Setup interaction tracing
+        self.enable_tracing = kwargs.get('enable_tracing', False)
+        self._traces = deque(maxlen=kwargs.get('max_traces', 100))  # Ring buffer for memory efficiency
 
         # Provider created successfully - no event emission needed
         # (The simplified event system focuses on generation and tool events only)
@@ -173,6 +183,97 @@ class BaseProvider(AbstractCoreInterface, ABC):
             result_info = f" (result length: {len(str(result))})" if result else ""
             self.logger.info(f"Tool call completed: {tool_name}{result_info}")
 
+    def _capture_trace(self, prompt: str, messages: Optional[List[Dict[str, str]]],
+                       system_prompt: Optional[str], tools: Optional[List[Dict[str, Any]]],
+                       response: GenerateResponse, kwargs: Dict[str, Any]) -> str:
+        """
+        Capture interaction trace for observability.
+
+        Args:
+            prompt: Input prompt
+            messages: Conversation history
+            system_prompt: System prompt
+            tools: Available tools
+            response: Generated response
+            kwargs: Additional generation parameters
+
+        Returns:
+            Trace ID (UUID string)
+        """
+        trace_id = str(uuid.uuid4())
+
+        # Extract generation parameters
+        temperature = kwargs.get('temperature', self.temperature)
+        max_tokens = kwargs.get('max_tokens', self.max_tokens)
+        max_output_tokens = kwargs.get('max_output_tokens', self.max_output_tokens)
+        seed = kwargs.get('seed', self.seed)
+        top_p = kwargs.get('top_p', getattr(self, 'top_p', None))
+        top_k = kwargs.get('top_k', getattr(self, 'top_k', None))
+
+        # Build parameters dict
+        parameters = {
+            'temperature': temperature,
+            'max_tokens': max_tokens,
+            'max_output_tokens': max_output_tokens,
+        }
+        if seed is not None:
+            parameters['seed'] = seed
+        if top_p is not None:
+            parameters['top_p'] = top_p
+        if top_k is not None:
+            parameters['top_k'] = top_k
+
+        # Create trace record
+        trace = {
+            'trace_id': trace_id,
+            'timestamp': datetime.now().isoformat(),
+            'provider': self.__class__.__name__,
+            'model': self.model,
+            'system_prompt': system_prompt,
+            'prompt': prompt,
+            'messages': messages,
+            'tools': tools,
+            'parameters': parameters,
+            'response': {
+                'content': response.content,
+                'raw_response': None,  # Omit raw_response to save memory and avoid logging sensitive data
+                'tool_calls': response.tool_calls,
+                'finish_reason': response.finish_reason,
+                'usage': response.usage,
+                'generation_time_ms': response.gen_time,
+            },
+            'metadata': kwargs.get('trace_metadata', {})
+        }
+
+        # Store trace in ring buffer
+        self._traces.append(trace)
+
+        return trace_id
+
+    def get_traces(self, trace_id: Optional[str] = None, last_n: Optional[int] = None) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        """
+        Retrieve interaction traces.
+
+        Args:
+            trace_id: Optional specific trace ID to retrieve
+            last_n: Optional number of most recent traces to retrieve
+
+        Returns:
+            Single trace dict if trace_id provided, list of traces otherwise
+        """
+        if trace_id:
+            # Find specific trace by ID
+            for trace in self._traces:
+                if trace['trace_id'] == trace_id:
+                    return trace
+            return None
+
+        if last_n:
+            # Return last N traces
+            return list(self._traces)[-last_n:] if len(self._traces) >= last_n else list(self._traces)
+
+        # Return all traces
+        return list(self._traces)
 
     def _handle_api_error(self, error: Exception) -> Exception:
         """
@@ -211,6 +312,7 @@ class BaseProvider(AbstractCoreInterface, ABC):
                                retry_strategy=None,  # Custom retry strategy for structured output
                                tool_call_tags: Optional[str] = None,  # Tool call tag rewriting
                                execute_tools: Optional[bool] = None,  # Tool execution control
+                               glyph_compression: Optional[str] = None,  # Glyph compression preference
                                **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse], BaseModel]:
         """
         Generate with integrated telemetry and error handling.
@@ -227,6 +329,7 @@ class BaseProvider(AbstractCoreInterface, ABC):
             retry_strategy: Optional retry strategy for structured output validation
             tool_call_tags: Optional tool call tag format for rewriting
             execute_tools: Whether to execute tools automatically (True) or let agent handle execution (False)
+            glyph_compression: Glyph compression preference ("auto", "always", "never")
         """
         # Handle structured output request
         if response_model is not None:
@@ -269,8 +372,17 @@ class BaseProvider(AbstractCoreInterface, ABC):
 
         # Process media content if provided
         processed_media = None
+        media_metadata = None
         if media:
-            processed_media = self._process_media_content(media)
+            compression_pref = glyph_compression or kwargs.get('glyph_compression', 'auto')
+            processed_media = self._process_media_content(media, compression_pref)
+            
+            # Extract metadata from processed media for response
+            if processed_media:
+                media_metadata = []
+                for media_content in processed_media:
+                    if hasattr(media_content, 'metadata') and media_content.metadata:
+                        media_metadata.append(media_content.metadata)
 
         # Convert tools to ToolDefinition objects first (outside retry loop)
         converted_tools = None
@@ -327,6 +439,7 @@ class BaseProvider(AbstractCoreInterface, ABC):
                     stream=stream,
                     execute_tools=should_execute_tools,
                     tool_call_tags=tool_call_tags,
+                    media_metadata=media_metadata,
                     **kwargs
                 )
 
@@ -380,6 +493,26 @@ class BaseProvider(AbstractCoreInterface, ABC):
                     # Apply default qwen3 rewriting for non-streaming responses
                     response = self._apply_non_streaming_tag_rewriting(response, tool_call_tags)
 
+                # Add visual token calculation if media metadata is available
+                if media_metadata and response:
+                    self.logger.debug(f"Enhancing response with visual tokens from {len(media_metadata)} media items")
+                    response = self._enhance_response_with_visual_tokens(response, media_metadata)
+
+                # Capture interaction trace if enabled
+                if self.enable_tracing and response:
+                    trace_id = self._capture_trace(
+                        prompt=prompt,
+                        messages=messages,
+                        system_prompt=system_prompt,
+                        tools=converted_tools,
+                        response=response,
+                        kwargs=kwargs
+                    )
+                    # Attach trace_id to response metadata
+                    if not response.metadata:
+                        response.metadata = {}
+                    response.metadata['trace_id'] = trace_id
+
                 self._track_generation(prompt, response, start_time, success=True, stream=False)
                 return response
 
@@ -411,6 +544,7 @@ class BaseProvider(AbstractCoreInterface, ABC):
                           stream: bool = False,
                           response_model: Optional[Type[BaseModel]] = None,
                           execute_tools: Optional[bool] = None,
+                          media_metadata: Optional[List[Dict[str, Any]]] = None,
                           **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse]]:
         """
         Internal generation method to be implemented by subclasses.
@@ -429,6 +563,102 @@ class BaseProvider(AbstractCoreInterface, ABC):
         """
         raise NotImplementedError("Subclasses must implement _generate_internal")
 
+    def _enhance_response_with_visual_tokens(self, response: GenerateResponse, media_metadata: List[Dict[str, Any]]) -> GenerateResponse:
+        """
+        Enhance the response with visual token calculations for Glyph compression.
+        This method is called automatically by BaseProvider for all providers.
+        """
+        try:
+            # Calculate visual tokens using VLM token calculator
+            provider_name = self.provider or self.__class__.__name__.lower().replace('provider', '')
+            self.logger.debug(f"Calculating visual tokens for provider={provider_name}, model={self.model}")
+            
+            visual_tokens = self._calculate_visual_tokens(media_metadata, provider_name, self.model)
+            self.logger.debug(f"Calculated visual tokens: {visual_tokens}")
+            
+            if visual_tokens > 0:
+                # Ensure response has metadata
+                if not response.metadata:
+                    response.metadata = {}
+                
+                # Add visual token information to metadata
+                response.metadata['visual_tokens'] = visual_tokens
+                
+                # Ensure response has usage dict
+                if not response.usage:
+                    response.usage = {}
+                
+                # Add visual tokens to usage
+                response.usage['visual_tokens'] = visual_tokens
+                
+                # Update total tokens to include visual tokens
+                original_total = response.usage.get('total_tokens', 0)
+                response.usage['total_tokens'] = original_total + visual_tokens
+                
+                self.logger.info(f"Enhanced response with {visual_tokens} visual tokens (new total: {response.usage['total_tokens']})")
+            else:
+                self.logger.debug("No visual tokens calculated - skipping enhancement")
+                
+        except Exception as e:
+            self.logger.warning(f"Failed to enhance response with visual tokens: {e}")
+        
+        return response
+
+    def _calculate_visual_tokens(self, media_metadata: List[Dict[str, Any]], provider: str, model: str) -> int:
+        """Calculate visual tokens from media metadata using VLM token calculator."""
+        try:
+            from ..utils.vlm_token_calculator import VLMTokenCalculator
+            from pathlib import Path
+            
+            calculator = VLMTokenCalculator()
+            total_visual_tokens = 0
+            
+            self.logger.debug(f"Processing {len(media_metadata)} media metadata items")
+            
+            for i, metadata in enumerate(media_metadata):
+                self.logger.debug(f"Metadata {i}: processing_method={metadata.get('processing_method')}")
+                
+                # Check if this is Glyph compression
+                if metadata.get('processing_method') == 'direct_pdf_conversion':
+                    glyph_cache_dir = metadata.get('glyph_cache_dir')
+                    total_images = metadata.get('total_images', 0)
+                    
+                    self.logger.debug(f"Glyph metadata found: cache_dir={glyph_cache_dir}, total_images={total_images}")
+                    
+                    if glyph_cache_dir and Path(glyph_cache_dir).exists():
+                        # Get actual image paths
+                        cache_dir = Path(glyph_cache_dir)
+                        image_paths = list(cache_dir.glob("image_*.png"))
+                        
+                        self.logger.debug(f"Found {len(image_paths)} images in cache directory")
+                        
+                        if image_paths:
+                            # Calculate tokens for all images
+                            token_analysis = calculator.calculate_tokens_for_images(
+                                image_paths=image_paths,
+                                provider=provider,
+                                model=model
+                            )
+                            total_visual_tokens += token_analysis['total_tokens']
+                            
+                            self.logger.debug(f"Calculated {token_analysis['total_tokens']} visual tokens for {len(image_paths)} Glyph images")
+                        else:
+                            # Fallback: estimate based on total_images
+                            base_tokens = calculator.PROVIDER_CONFIGS.get(provider, {}).get('base_tokens', 512)
+                            estimated_tokens = total_images * base_tokens
+                            total_visual_tokens += estimated_tokens
+                            
+                            self.logger.debug(f"Estimated {estimated_tokens} visual tokens for {total_images} Glyph images (fallback)")
+                    else:
+                        self.logger.debug(f"Cache directory not found or doesn't exist: {glyph_cache_dir}")
+            
+            self.logger.debug(f"Total visual tokens calculated: {total_visual_tokens}")
+            return total_visual_tokens
+            
+        except Exception as e:
+            self.logger.warning(f"Failed to calculate visual tokens: {e}")
+            return 0
+
     def _initialize_token_limits(self):
         """Initialize default token limits based on model capabilities"""
         # Set default max_tokens if not provided
@@ -805,12 +1035,14 @@ class BaseProvider(AbstractCoreInterface, ABC):
         """Rough estimation of token count for given text"""
         return super().estimate_tokens(text)
 
-    def _process_media_content(self, media: List[Union[str, Dict[str, Any], 'MediaContent']]) -> List['MediaContent']:
+    def _process_media_content(self, media: List[Union[str, Dict[str, Any], 'MediaContent']], 
+                              glyph_compression: str = "auto") -> List['MediaContent']:
         """
         Process media content from various input formats into standardized MediaContent objects.
 
         Args:
             media: List of media inputs (file paths, MediaContent objects, or dicts)
+            glyph_compression: Glyph compression preference (auto, always, never)
 
         Returns:
             List of processed MediaContent objects
@@ -838,8 +1070,16 @@ class BaseProvider(AbstractCoreInterface, ABC):
             try:
                 if isinstance(media_item, str):
                     # File path - process with auto media handler
-                    handler = AutoMediaHandler()
-                    result = handler.process_file(media_item)
+                    handler = AutoMediaHandler(
+                        enable_glyph_compression=True,
+                        glyph_config=getattr(self, 'glyph_config', None)
+                    )
+                    result = handler.process_file(
+                        media_item,
+                        provider=self.provider,
+                        model=self.model,
+                        glyph_compression=glyph_compression
+                    )
                     if result.success:
                         processed_media.append(result.media_content)
                     else:
@@ -881,14 +1121,47 @@ class BaseProvider(AbstractCoreInterface, ABC):
         The server will use this method to aggregate models across all providers.
 
         Args:
-            **kwargs: Provider-specific parameters (e.g., api_key, base_url)
+            **kwargs: Provider-specific parameters including:
+                - api_key: API key for authentication (if required)
+                - base_url: Base URL for API endpoint (if applicable)
+                - input_capabilities: Optional list of ModelInputCapability enums to filter by input capability
+                    (e.g., [ModelInputCapability.IMAGE] for vision models)
+                - output_capabilities: Optional list of ModelOutputCapability enums to filter by output capability
+                    (e.g., [ModelOutputCapability.EMBEDDINGS] for embedding models)
 
         Returns:
-            List of model names available for this provider
+            List of model names available for this provider, optionally filtered by capabilities
+
+        Examples:
+            >>> from abstractcore.providers import OpenAIProvider
+            >>> from abstractcore.providers.model_capabilities import ModelInputCapability, ModelOutputCapability
+            >>>
+            >>> # Get all models
+            >>> all_models = OpenAIProvider.list_available_models(api_key="...")
+            >>>
+            >>> # Get models that can analyze images
+            >>> vision_models = OpenAIProvider.list_available_models(
+            ...     api_key="...",
+            ...     input_capabilities=[ModelInputCapability.IMAGE]
+            ... )
+            >>>
+            >>> # Get embedding models
+            >>> embedding_models = OpenAIProvider.list_available_models(
+            ...     api_key="...",
+            ...     output_capabilities=[ModelOutputCapability.EMBEDDINGS]
+            ... )
+            >>>
+            >>> # Get vision models that generate text (most common case)
+            >>> vision_text_models = OpenAIProvider.list_available_models(
+            ...     api_key="...",
+            ...     input_capabilities=[ModelInputCapability.TEXT, ModelInputCapability.IMAGE],
+            ...     output_capabilities=[ModelOutputCapability.TEXT]
+            ... )
 
         Note:
             This is an abstract method that MUST be implemented by all provider subclasses.
             Each provider should implement its own discovery logic (API calls, local scanning, etc.).
+            Providers should apply the capability filters if provided in kwargs.
         """
         pass
 
@@ -1168,9 +1441,9 @@ Please provide a structured response."""
                 **kwargs) -> Union[GenerateResponse, Iterator[GenerateResponse], BaseModel]:
         """
         Generate response from the LLM.
-        
+
         This method implements the AbstractCoreInterface and delegates to generate_with_telemetry.
-        
+
         Args:
             prompt: The input prompt
             messages: Optional conversation history
@@ -1178,7 +1451,7 @@ Please provide a structured response."""
             tools: Optional list of available tools
             stream: Whether to stream the response
             **kwargs: Additional provider-specific parameters (including response_model)
-            
+
         Returns:
             GenerateResponse, iterator of GenerateResponse for streaming, or BaseModel for structured output
         """
@@ -1189,4 +1462,98 @@ Please provide a structured response."""
             tools=tools,
             stream=stream,
             **kwargs
-        )
+        )
+
+    async def agenerate(self,
+                       prompt: str = "",
+                       messages: Optional[List[Dict]] = None,
+                       system_prompt: Optional[str] = None,
+                       tools: Optional[List] = None,
+                       media: Optional[List] = None,
+                       stream: bool = False,
+                       **kwargs) -> Union[GenerateResponse, AsyncIterator[GenerateResponse], BaseModel]:
+        """
+        Async generation - works with all providers.
+
+        Calls _agenerate_internal() which can be overridden for native async.
+        Default implementation uses asyncio.to_thread() fallback.
+
+        Args:
+            prompt: Text prompt
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Available tools
+            media: Media attachments
+            stream: Enable streaming
+            **kwargs: Additional generation parameters (including response_model)
+
+        Returns:
+            GenerateResponse, AsyncIterator[GenerateResponse] for streaming, or BaseModel for structured output
+        """
+        return await self._agenerate_internal(
+            prompt, messages, system_prompt, tools, media, stream, **kwargs
+        )
+
+    async def _agenerate_internal(self,
+                                   prompt: str,
+                                   messages: Optional[List[Dict]],
+                                   system_prompt: Optional[str],
+                                   tools: Optional[List],
+                                   media: Optional[List],
+                                   stream: bool,
+                                   **kwargs) -> Union[GenerateResponse, AsyncIterator[GenerateResponse], BaseModel]:
+        """
+        Internal async generation method.
+
+        Default implementation: Uses asyncio.to_thread() to run sync generate().
+        Providers override this for native async (3-10x faster for batch operations).
+
+        Args:
+            prompt: Text prompt
+            messages: Conversation history
+            system_prompt: System instructions
+            tools: Available tools
+            media: Media attachments
+            stream: Enable streaming
+            **kwargs: Additional generation parameters
+
+        Returns:
+            GenerateResponse, AsyncIterator[GenerateResponse] for streaming, or BaseModel for structured output
+        """
+        if stream:
+            # Return async iterator for streaming
+            return self._async_stream_generate(
+                prompt, messages, system_prompt, tools, media, **kwargs
+            )
+        else:
+            # Run sync generate in thread pool (fallback)
+            return await asyncio.to_thread(
+                self.generate,
+                prompt, messages, system_prompt, tools, stream, **kwargs
+            )
+
+    async def _async_stream_generate(self,
+                                     prompt: str,
+                                     messages: Optional[List[Dict]],
+                                     system_prompt: Optional[str],
+                                     tools: Optional[List],
+                                     media: Optional[List],
+                                     **kwargs) -> AsyncIterator[GenerateResponse]:
+        """
+        Async streaming generator.
+
+        Wraps sync streaming in async iterator, yielding control to event loop.
+        """
+        # Get sync generator in thread pool
+        def get_sync_stream():
+            return self.generate(
+                prompt, messages, system_prompt, tools,
+                stream=True, **kwargs
+            )
+
+        sync_gen = await asyncio.to_thread(get_sync_stream)
+
+        # Yield chunks asynchronously
+        for chunk in sync_gen:
+            yield chunk
+            await asyncio.sleep(0)  # Yield control to event loop