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

abstractcore/__init__.py

@@ -49,6 +49,9 @@ _has_processing = True
 # Tools module (core functionality)
 from .tools import tool
 
+# Download module (core functionality)
+from .download import download_model, DownloadProgress, DownloadStatus
+
 # Compression module (optional import)
 try:
     from .compression import GlyphConfig, CompressionOrchestrator
@@ -67,7 +70,10 @@ __all__ = [
     'ModelNotFoundError',
     'ProviderAPIError',
     'AuthenticationError',
-    'tool'
+    'tool',
+    'download_model',
+    'DownloadProgress',
+    'DownloadStatus',
 ]
 
 if _has_embeddings:

abstractcore/architectures/detection.py

@@ -9,9 +9,9 @@ import json
 import os
 from typing import Dict, Any, Optional, List
 from pathlib import Path
-import logging
+from ..utils.structured_logging import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 # Cache for loaded JSON data
 _architecture_formats: Optional[Dict[str, Any]] = None

abstractcore/core/retry.py

@@ -8,13 +8,13 @@ and production LLM system requirements.
 
 import time
 import random
-import logging
 from typing import Type, Optional, Set, Dict, Any
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 from enum import Enum
+from ..utils.structured_logging import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class RetryableErrorType(Enum):

abstractcore/core/session.py

@@ -3,11 +3,12 @@ BasicSession for conversation tracking.
 Target: <500 lines maximum.
 """
 
-from typing import List, Optional, Dict, Any, Union, Iterator, Callable
+from typing import List, Optional, Dict, Any, Union, Iterator, AsyncIterator, Callable
 from datetime import datetime
 from pathlib import Path
 import json
 import uuid
+import asyncio
 from collections.abc import Generator
 
 from .interface import AbstractCoreInterface
@@ -273,6 +274,136 @@ class BasicSession:
         if collected_content:
             self.add_message('assistant', collected_content)
 
+    async def agenerate(self,
+                       prompt: str,
+                       name: Optional[str] = None,
+                       location: Optional[str] = None,
+                       **kwargs) -> Union[GenerateResponse, AsyncIterator[GenerateResponse]]:
+        """
+        Async generation with conversation history.
+
+        Args:
+            prompt: User message
+            name: Optional speaker name
+            location: Optional location context
+            **kwargs: Generation parameters (stream, temperature, etc.)
+
+        Returns:
+            GenerateResponse or AsyncIterator for streaming
+
+        Example:
+            # Async chat interaction
+            response = await session.agenerate('What is Python?')
+
+            # Async streaming
+            async for chunk in await session.agenerate('Tell me a story', stream=True):
+                print(chunk.content, end='')
+        """
+        if not self.provider:
+            raise ValueError("No provider configured")
+
+        # Check for auto-compaction before generating
+        if self.auto_compact and self.should_compact(self.auto_compact_threshold):
+            print(f"🗜️  Auto-compacting session (tokens: {self.get_token_estimate()} > {self.auto_compact_threshold})")
+            compacted = self.compact(reason="auto_threshold")
+            # Replace current session with compacted version
+            self._replace_with_compacted(compacted)
+
+        # Pre-processing (fast, sync is fine)
+        self.add_message('user', prompt, name=name, location=location)
+
+        # Format messages for provider (exclude the current user message since provider will add it)
+        messages = self._format_messages_for_provider_excluding_current()
+
+        # Use session tools if not provided in kwargs
+        if 'tools' not in kwargs and self.tools:
+            kwargs['tools'] = self.tools
+
+        # Pass session tool_call_tags if available and not overridden in kwargs
+        if hasattr(self, 'tool_call_tags') and self.tool_call_tags is not None and 'tool_call_tags' not in kwargs:
+            kwargs['tool_call_tags'] = self.tool_call_tags
+
+        # Extract media parameter explicitly
+        media = kwargs.pop('media', None)
+
+        # Add session-level parameters if not overridden in kwargs
+        if 'temperature' not in kwargs and self.temperature is not None:
+            kwargs['temperature'] = self.temperature
+        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)
+            })
+
+        # Check if streaming
+        stream = kwargs.get('stream', False)
+
+        if stream:
+            # Return async streaming wrapper that adds assistant message after
+            return self._async_session_stream(prompt, messages, media, **kwargs)
+        else:
+            # Async generation
+            response = await self.provider.agenerate(
+                prompt=prompt,
+                messages=messages,
+                system_prompt=self.system_prompt,
+                media=media,
+                **kwargs
+            )
+
+            # Post-processing (fast, sync is fine)
+            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
+
+    async def _async_session_stream(self,
+                                    prompt: str,
+                                    messages: List[Dict[str, str]],
+                                    media: Optional[List],
+                                    **kwargs) -> AsyncIterator[GenerateResponse]:
+        """Async streaming with session history management."""
+        collected_content = ""
+
+        # Remove 'stream' from kwargs since we're explicitly setting it
+        kwargs_copy = {k: v for k, v in kwargs.items() if k != 'stream'}
+
+        # CRITICAL: Await first to get async generator, then iterate
+        stream_gen = await self.provider.agenerate(
+            prompt=prompt,
+            messages=messages,
+            system_prompt=self.system_prompt,
+            media=media,
+            stream=True,
+            **kwargs_copy
+        )
+
+        async for chunk in stream_gen:
+            # Yield the chunk for the caller
+            yield chunk
+
+            # Collect content for history
+            if hasattr(chunk, 'content') and chunk.content:
+                collected_content += chunk.content
+
+        # After streaming completes, add assistant message
+        if collected_content:
+            self.add_message('assistant', collected_content)
+
     def _format_messages_for_provider(self) -> List[Dict[str, str]]:
         """Format messages for provider API"""
         return [

abstractcore/download.py

@@ -0,0 +1,253 @@
+"""
+Model download API with async progress reporting.
+
+Provides a provider-agnostic interface for downloading models from Ollama,
+HuggingFace Hub, and MLX with streaming progress updates.
+"""
+
+import json
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+from typing import AsyncIterator, Optional
+
+import httpx
+
+
+class DownloadStatus(Enum):
+    """Download progress status."""
+
+    STARTING = "starting"
+    DOWNLOADING = "downloading"
+    VERIFYING = "verifying"
+    COMPLETE = "complete"
+    ERROR = "error"
+
+
+@dataclass
+class DownloadProgress:
+    """Progress information for model download."""
+
+    status: DownloadStatus
+    message: str
+    percent: Optional[float] = None  # 0-100
+    downloaded_bytes: Optional[int] = None
+    total_bytes: Optional[int] = None
+
+
+async def download_model(
+    provider: str,
+    model: str,
+    token: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> AsyncIterator[DownloadProgress]:
+    """
+    Download a model with async progress reporting.
+
+    This function provides a unified interface for downloading models across
+    different providers. Progress updates are yielded as DownloadProgress
+    dataclasses that include status, message, and optional progress percentage.
+
+    Args:
+        provider: Provider name ("ollama", "huggingface", "mlx")
+        model: Model identifier:
+            - Ollama: "llama3:8b", "gemma3:1b", etc.
+            - HuggingFace/MLX: "meta-llama/Llama-2-7b", "mlx-community/Qwen3-4B-4bit", etc.
+        token: Optional auth token (for HuggingFace gated models)
+        base_url: Optional custom base URL (for Ollama, default: http://localhost:11434)
+
+    Yields:
+        DownloadProgress: Progress updates with status, message, and optional metrics
+
+    Raises:
+        ValueError: If provider doesn't support downloads (OpenAI, Anthropic, LMStudio)
+        httpx.HTTPStatusError: If Ollama server returns error
+        Exception: Various exceptions from HuggingFace Hub (RepositoryNotFoundError, etc.)
+
+    Examples:
+        Download Ollama model:
+            >>> async for progress in download_model("ollama", "gemma3:1b"):
+            ...     print(f"{progress.status.value}: {progress.message}")
+            ...     if progress.percent:
+            ...         print(f"  Progress: {progress.percent:.1f}%")
+
+        Download HuggingFace model with token:
+            >>> async for progress in download_model(
+            ...     "huggingface",
+            ...     "meta-llama/Llama-2-7b",
+            ...     token="hf_..."
+            ... ):
+            ...     print(f"{progress.message}")
+    """
+    provider_lower = provider.lower()
+
+    if provider_lower == "ollama":
+        async for progress in _download_ollama(model, base_url):
+            yield progress
+    elif provider_lower in ("huggingface", "mlx"):
+        async for progress in _download_huggingface(model, token):
+            yield progress
+    else:
+        raise ValueError(
+            f"Provider '{provider}' does not support model downloads. "
+            f"Supported providers: ollama, huggingface, mlx. "
+            f"Note: OpenAI and Anthropic are cloud-only; LMStudio has no download API."
+        )
+
+
+async def _download_ollama(
+    model: str,
+    base_url: Optional[str] = None,
+) -> AsyncIterator[DownloadProgress]:
+    """
+    Download model from Ollama using /api/pull endpoint.
+
+    Args:
+        model: Ollama model name (e.g., "llama3:8b", "gemma3:1b")
+        base_url: Ollama server URL (default: http://localhost:11434)
+
+    Yields:
+        DownloadProgress with status updates from Ollama streaming response
+    """
+    url = (base_url or "http://localhost:11434").rstrip("/")
+
+    yield DownloadProgress(
+        status=DownloadStatus.STARTING, message=f"Pulling {model} from Ollama..."
+    )
+
+    try:
+        async with httpx.AsyncClient(timeout=None) as client:
+            async with client.stream(
+                "POST",
+                f"{url}/api/pull",
+                json={"name": model, "stream": True},
+            ) as response:
+                response.raise_for_status()
+
+                async for line in response.aiter_lines():
+                    if not line:
+                        continue
+
+                    try:
+                        data = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+
+                    status_msg = data.get("status", "")
+
+                    # Parse progress from Ollama response
+                    # Format: {"status": "downloading...", "total": 123, "completed": 45}
+                    if "total" in data and "completed" in data:
+                        total = data["total"]
+                        completed = data["completed"]
+                        percent = (completed / total * 100) if total > 0 else 0
+
+                        yield DownloadProgress(
+                            status=DownloadStatus.DOWNLOADING,
+                            message=status_msg,
+                            percent=percent,
+                            downloaded_bytes=completed,
+                            total_bytes=total,
+                        )
+                    elif status_msg == "success":
+                        yield DownloadProgress(
+                            status=DownloadStatus.COMPLETE,
+                            message=f"Successfully pulled {model}",
+                            percent=100.0,
+                        )
+                    elif "verifying" in status_msg.lower():
+                        yield DownloadProgress(
+                            status=DownloadStatus.VERIFYING,
+                            message=status_msg,
+                        )
+                    else:
+                        # Other status messages (pulling manifest, etc.)
+                        yield DownloadProgress(
+                            status=DownloadStatus.DOWNLOADING,
+                            message=status_msg,
+                        )
+
+    except httpx.HTTPStatusError as e:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=f"Ollama server error: {e.response.status_code} - {e.response.text}",
+        )
+    except httpx.ConnectError:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=f"Cannot connect to Ollama server at {url}. Is Ollama running?",
+        )
+    except Exception as e:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=f"Download failed: {str(e)}",
+        )
+
+
+async def _download_huggingface(
+    model: str,
+    token: Optional[str] = None,
+) -> AsyncIterator[DownloadProgress]:
+    """
+    Download model from HuggingFace Hub.
+
+    Args:
+        model: HuggingFace model identifier (e.g., "meta-llama/Llama-2-7b")
+        token: Optional HuggingFace token (required for gated models)
+
+    Yields:
+        DownloadProgress with status updates
+    """
+    yield DownloadProgress(
+        status=DownloadStatus.STARTING,
+        message=f"Downloading {model} from HuggingFace Hub...",
+    )
+
+    try:
+        # Import here to make huggingface_hub optional
+        from huggingface_hub import snapshot_download
+        from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError
+    except ImportError:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=(
+                "huggingface_hub is not installed. "
+                "Install with: pip install abstractcore[huggingface]"
+            ),
+        )
+        return
+
+    try:
+        # Run blocking download in thread
+        # Note: snapshot_download doesn't have built-in async progress callbacks
+        # We provide start and completion messages
+        await asyncio.to_thread(
+            snapshot_download,
+            repo_id=model,
+            token=token,
+        )
+
+        yield DownloadProgress(
+            status=DownloadStatus.COMPLETE,
+            message=f"Successfully downloaded {model}",
+            percent=100.0,
+        )
+
+    except RepositoryNotFoundError:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=f"Model '{model}' not found on HuggingFace Hub",
+        )
+    except GatedRepoError:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=(
+                f"Model '{model}' requires authentication. "
+                f"Provide a HuggingFace token via the 'token' parameter."
+            ),
+        )
+    except Exception as e:
+        yield DownloadProgress(
+            status=DownloadStatus.ERROR,
+            message=f"Download failed: {str(e)}",
+        )

abstractcore/embeddings/manager.py

@@ -7,7 +7,6 @@ Production-ready embedding generation with SOTA models and efficient serving.
 
 import hashlib
 import pickle
-import logging
 import atexit
 import sys
 import builtins
@@ -33,8 +32,9 @@ except ImportError:
     emit_global = None
 
 from .models import EmbeddingBackend, get_model_config, list_available_models, get_default_model
+from ..utils.structured_logging import get_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 @contextmanager

abstractcore/events/__init__.py

@@ -20,15 +20,17 @@ from enum import Enum
 from dataclasses import dataclass, field
 from datetime import datetime
 import uuid
+import asyncio
 
 
 class EventType(Enum):
     """Minimal event system - clean, simple, efficient"""
 
-    # Core events (4) - matches LangChain pattern
+    # Core events (5) - matches LangChain pattern + async progress
     GENERATION_STARTED = "generation_started"      # Unified for streaming and non-streaming
     GENERATION_COMPLETED = "generation_completed"  # Includes all metrics
     TOOL_STARTED = "tool_started"                  # Before tool execution
+    TOOL_PROGRESS = "tool_progress"                # Real-time progress during tool execution
     TOOL_COMPLETED = "tool_completed"              # After tool execution
 
     # Error handling (1)
@@ -60,6 +62,7 @@ class EventEmitter:
 
     def __init__(self):
         self._listeners: Dict[EventType, List[Callable]] = {}
+        self._async_listeners: Dict[EventType, List[Callable]] = {}
 
     def on(self, event_type: EventType, handler: Callable):
         """
@@ -141,6 +144,67 @@ class EventEmitter:
             }
         )
 
+    def on_async(self, event_type: EventType, handler: Callable):
+        """
+        Register an async event handler.
+
+        Args:
+            event_type: Type of event to listen for
+            handler: Async function to call when event occurs
+        """
+        if event_type not in self._async_listeners:
+            self._async_listeners[event_type] = []
+        self._async_listeners[event_type].append(handler)
+
+    async def emit_async(self, event_type: EventType, data: Dict[str, Any], source: Optional[str] = None, **kwargs) -> Event:
+        """
+        Emit an event asynchronously to all registered handlers.
+
+        Runs async handlers concurrently with asyncio.gather().
+        Also triggers sync handlers for backward compatibility.
+
+        Args:
+            event_type: Type of event
+            data: Event data
+            source: Source of the event
+            **kwargs: Additional event attributes (model_name, tokens, etc.)
+
+        Returns:
+            The event object
+        """
+        # Filter kwargs to only include valid Event fields
+        try:
+            valid_fields = set(Event.__dataclass_fields__.keys())
+        except AttributeError:
+            # Fallback for older Python versions
+            valid_fields = {'trace_id', 'span_id', 'request_id', 'duration_ms', 'model_name',
+                          'provider_name', 'tokens_input', 'tokens_output', 'cost_usd', 'metadata'}
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_fields}
+
+        event = Event(
+            type=event_type,
+            timestamp=datetime.now(),
+            data=data,
+            source=source or self.__class__.__name__,
+            **filtered_kwargs
+        )
+
+        # Run async handlers concurrently
+        if event_type in self._async_listeners:
+            tasks = [handler(event) for handler in self._async_listeners[event_type]]
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Also run sync handlers (backward compatible)
+        if event_type in self._listeners:
+            for handler in self._listeners[event_type]:
+                try:
+                    handler(event)
+                except Exception as e:
+                    # Log error but don't stop event propagation
+                    print(f"Error in event handler: {e}")
+
+        return event
+
 
 class GlobalEventBus:
     """
@@ -149,6 +213,7 @@ class GlobalEventBus:
     """
     _instance = None
     _listeners: Dict[EventType, List[Callable]] = {}
+    _async_listeners: Dict[EventType, List[Callable]] = {}
 
     def __new__(cls):
         if cls._instance is None:
@@ -199,6 +264,52 @@ class GlobalEventBus:
     def clear(cls):
         """Clear all global event handlers"""
         cls._listeners.clear()
+        cls._async_listeners.clear()
+
+    @classmethod
+    def on_async(cls, event_type: EventType, handler: Callable):
+        """Register a global async event handler"""
+        if event_type not in cls._async_listeners:
+            cls._async_listeners[event_type] = []
+        cls._async_listeners[event_type].append(handler)
+
+    @classmethod
+    async def emit_async(cls, event_type: EventType, data: Dict[str, Any], source: Optional[str] = None, **kwargs):
+        """
+        Emit a global event asynchronously.
+
+        Runs async handlers concurrently with asyncio.gather().
+        Also triggers sync handlers for backward compatibility.
+        """
+        # Filter kwargs to only include valid Event fields
+        try:
+            valid_fields = set(Event.__dataclass_fields__.keys())
+        except AttributeError:
+            # Fallback for older Python versions
+            valid_fields = {'trace_id', 'span_id', 'request_id', 'duration_ms', 'model_name',
+                          'provider_name', 'tokens_input', 'tokens_output', 'cost_usd', 'metadata'}
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_fields}
+
+        event = Event(
+            type=event_type,
+            timestamp=datetime.now(),
+            data=data,
+            source=source or "GlobalEventBus",
+            **filtered_kwargs
+        )
+
+        # Run async handlers concurrently
+        if event_type in cls._async_listeners:
+            tasks = [handler(event) for handler in cls._async_listeners[event_type]]
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+        # Also run sync handlers (backward compatible)
+        if event_type in cls._listeners:
+            for handler in cls._listeners[event_type]:
+                try:
+                    handler(event)
+                except Exception as e:
+                    print(f"Error in global event handler: {e}")
 
 
 # Convenience functions

abstractcore/exceptions/__init__.py

@@ -106,10 +106,55 @@ def format_model_error(provider: str, invalid_model: str, available_models: list
     return message.rstrip()
 
 
+def format_auth_error(provider: str, reason: str = None) -> str:
+    """
+    Format actionable authentication error with setup instructions.
+
+    Args:
+        provider: Provider name (e.g., "openai", "anthropic")
+        reason: Optional reason for auth failure
+
+    Returns:
+        Formatted error message with fix instructions
+    """
+    urls = {
+        "openai": "https://platform.openai.com/api-keys",
+        "anthropic": "https://console.anthropic.com/settings/keys",
+    }
+    msg = f"{provider.upper()} authentication failed"
+    if reason:
+        msg += f": {reason}"
+    msg += f"\nFix: abstractcore --set-api-key {provider} YOUR_KEY"
+    if provider.lower() in urls:
+        msg += f"\nGet key: {urls[provider.lower()]}"
+    return msg
+
+
+def format_provider_error(provider: str, reason: str) -> str:
+    """
+    Format actionable provider unavailability error with setup instructions.
+
+    Args:
+        provider: Provider name (e.g., "ollama", "lmstudio")
+        reason: Reason for unavailability (e.g., "Connection refused")
+
+    Returns:
+        Formatted error message with setup instructions
+    """
+    instructions = {
+        "ollama": "Install: https://ollama.com/download\nStart: ollama serve",
+        "lmstudio": "Install: https://lmstudio.ai/\nEnable API in settings",
+    }
+    msg = f"Provider '{provider}' unavailable: {reason}"
+    if provider.lower() in instructions:
+        msg += f"\n{instructions[provider.lower()]}"
+    return msg
+
+
 # Export all exceptions for easy importing
 __all__ = [
     'AbstractCoreError',
-    'ProviderError', 
+    'ProviderError',
     'ProviderAPIError',
     'AuthenticationError',
     'Authentication',  # Backward compatibility alias
@@ -121,5 +166,7 @@ __all__ = [
     'SessionError',
     'ConfigurationError',
     'ModelNotFoundError',
-    'format_model_error'
+    'format_model_error',
+    'format_auth_error',
+    'format_provider_error'
 ]