abstractcore 2.5.3__py3-none-any.whl → 2.6.2__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/config/__init__.py

@@ -7,4 +7,27 @@ Provides configuration management and command-line interface for AbstractCore.
 from .vision_config import handle_vision_commands, add_vision_arguments
 from .manager import get_config_manager
 
-__all__ = ['handle_vision_commands', 'add_vision_arguments', 'get_config_manager']
+
+def configure_provider(provider: str, **kwargs) -> None:
+    """Configure runtime settings for a provider."""
+    get_config_manager().configure_provider(provider, **kwargs)
+
+
+def get_provider_config(provider: str) -> dict:
+    """Get runtime configuration for a provider."""
+    return get_config_manager().get_provider_config(provider)
+
+
+def clear_provider_config(provider: str = None) -> None:
+    """Clear runtime provider configuration."""
+    get_config_manager().clear_provider_config(provider)
+
+
+__all__ = [
+    'handle_vision_commands',
+    'add_vision_arguments',
+    'get_config_manager',
+    'configure_provider',
+    'get_provider_config',
+    'clear_provider_config'
+]

abstractcore/config/manager.py

@@ -136,6 +136,7 @@ class ConfigurationManager:
         self.config_dir = Path.home() / ".abstractcore" / "config"
         self.config_file = self.config_dir / "abstractcore.json"
         self.config = self._load_config()
+        self._provider_config: Dict[str, Dict[str, Any]] = {}  # Runtime config (not persisted)
 
     def _load_config(self) -> AbstractCoreConfig:
         """Load configuration from file or create default."""
@@ -437,6 +438,52 @@ class ConfigurationManager:
         """Check if local_files_only should be forced for transformers."""
         return self.config.offline.force_local_files_only
 
+    def configure_provider(self, provider: str, **kwargs) -> None:
+        """
+        Configure runtime settings for a provider.
+
+        Args:
+            provider: Provider name ('ollama', 'lmstudio', 'openai', 'anthropic')
+            **kwargs: Configuration options (base_url, timeout, etc.)
+
+        Example:
+            configure_provider('ollama', base_url='http://192.168.1.100:11434')
+        """
+        provider = provider.lower()
+        if provider not in self._provider_config:
+            self._provider_config[provider] = {}
+
+        for key, value in kwargs.items():
+            if value is None:
+                # Remove config (revert to env var / default)
+                self._provider_config[provider].pop(key, None)
+            else:
+                self._provider_config[provider][key] = value
+
+    def get_provider_config(self, provider: str) -> Dict[str, Any]:
+        """
+        Get runtime configuration for a provider.
+
+        Args:
+            provider: Provider name
+
+        Returns:
+            Dict with configured settings, or empty dict if no config
+        """
+        return self._provider_config.get(provider.lower(), {}).copy()
+
+    def clear_provider_config(self, provider: Optional[str] = None) -> None:
+        """
+        Clear runtime provider configuration.
+
+        Args:
+            provider: Provider name, or None to clear all
+        """
+        if provider is None:
+            self._provider_config.clear()
+        else:
+            self._provider_config.pop(provider.lower(), None)
+
 
 # Global instance
 _config_manager = 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