abstractcore 2.5.3__tar.gz → 2.6.0__tar.gz

{abstractcore-2.5.3 → abstractcore-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.5.3
+Version: 2.6.0
 Summary: Unified interface to all LLM providers with essential infrastructure for tool calling, streaming, and model management
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 Maintainer-email: Laurent-Philippe Albou <contact@abstractcore.ai>
@@ -67,12 +67,18 @@ Provides-Extra: api-providers
 Requires-Dist: abstractcore[anthropic,openai]; extra == "api-providers"
 Provides-Extra: local-providers
 Requires-Dist: abstractcore[lmstudio,mlx,ollama]; extra == "local-providers"
+Provides-Extra: local-providers-non-mlx
+Requires-Dist: abstractcore[lmstudio,ollama]; extra == "local-providers-non-mlx"
 Provides-Extra: heavy-providers
 Requires-Dist: abstractcore[huggingface]; extra == "heavy-providers"
 Provides-Extra: all-providers
 Requires-Dist: abstractcore[anthropic,embeddings,huggingface,lmstudio,mlx,ollama,openai]; extra == "all-providers"
+Provides-Extra: all-providers-non-mlx
+Requires-Dist: abstractcore[anthropic,embeddings,huggingface,lmstudio,ollama,openai]; extra == "all-providers-non-mlx"
 Provides-Extra: all
 Requires-Dist: abstractcore[anthropic,compression,dev,docs,embeddings,huggingface,lmstudio,media,mlx,ollama,openai,processing,server,test,tools]; extra == "all"
+Provides-Extra: all-non-mlx
+Requires-Dist: abstractcore[anthropic,compression,dev,docs,embeddings,huggingface,lmstudio,media,ollama,openai,processing,server,test,tools]; extra == "all-non-mlx"
 Provides-Extra: lightweight
 Requires-Dist: abstractcore[anthropic,compression,embeddings,lmstudio,media,ollama,openai,processing,server,tools]; extra == "lightweight"
 Provides-Extra: dev
@@ -120,7 +126,11 @@ A unified Python library for interaction with multiple Large Language Model (LLM
 ### Installation
 
 ```bash
+# macOS/Apple Silicon (includes MLX)
 pip install abstractcore[all]
+
+# Linux/Windows (excludes MLX)
+pip install abstractcore[all-non-mlx]
 ```
 
 ### Basic Usage
@@ -311,6 +321,69 @@ export_traces(traces, format='markdown', file_path='workflow_trace.md')
 
 [Learn more about Interaction Tracing](docs/interaction-tracing.md)
 
+### Async/Await Support
+
+Execute concurrent LLM requests for batch operations, multi-provider comparisons, or non-blocking web applications. **Production-ready with validated 6-7.5x performance improvement** for concurrent requests.
+
+```python
+import asyncio
+from abstractcore import create_llm
+
+async def main():
+    llm = create_llm("openai", model="gpt-4o-mini")
+
+    # Execute 3 requests concurrently (6-7x faster!)
+    tasks = [
+        llm.agenerate(f"Summarize {topic}")
+        for topic in ["Python", "JavaScript", "Rust"]
+    ]
+    responses = await asyncio.gather(*tasks)
+
+    for response in responses:
+        print(response.content)
+
+asyncio.run(main())
+```
+
+**Performance (Validated with Real Testing):**
+- **Ollama**: 7.5x faster for concurrent requests
+- **LMStudio**: 6.5x faster for concurrent requests
+- **OpenAI**: 6.0x faster for concurrent requests
+- **Anthropic**: 7.4x faster for concurrent requests
+- **Average**: ~7x speedup across all providers
+
+**Native Async vs Fallback:**
+- **Native async** (httpx.AsyncClient): Ollama, LMStudio, OpenAI, Anthropic
+- **Fallback** (asyncio.to_thread): MLX, HuggingFace
+- All providers work seamlessly - fallback keeps event loop responsive
+
+**Use Cases:**
+- Batch operations with 6-7x speedup via parallel execution
+- Multi-provider comparisons (query OpenAI and Anthropic simultaneously)
+- FastAPI/async web frameworks integration
+- Session async for conversation management
+
+**Works with:**
+- All 6 providers (OpenAI, Anthropic, Ollama, LMStudio, MLX, HuggingFace)
+- Streaming via `async for chunk in llm.agenerate(..., stream=True)`
+- Sessions via `await session.agenerate(...)`
+- Zero breaking changes to sync API
+
+**Learn async patterns:**
+
+AbstractCore includes an educational [async CLI demo](examples/async_cli_demo.py) that demonstrates 8 core async/await patterns:
+- Event-driven progress with GlobalEventBus
+- Parallel tool execution with asyncio.gather()
+- Proper async streaming pattern (await first, then async for)
+- Non-blocking animations and user input
+
+```bash
+# Try the educational async demo
+python examples/async_cli_demo.py --provider ollama --model qwen3:4b --stream
+```
+
+[Learn more in CLI docs](docs/acore-cli.md#async-cli-demo-educational-reference)
+
 ### Media Handling
 
 AbstractCore provides unified media handling across all providers with automatic resolution optimization. Upload images, PDFs, and documents using the same simple API regardless of your provider.
@@ -408,7 +481,8 @@ if response.metadata and response.metadata.get('compression_used'):
 
 - **Offline-First Design**: Built primarily for open source LLMs with full offline capability. Download once, run forever without internet access
 - **Provider Agnostic**: Seamlessly switch between OpenAI, Anthropic, Ollama, LMStudio, MLX, HuggingFace
-- **Interaction Tracing**: Complete LLM observability with programmatic access to prompts, responses, tokens, and timing for debugging and compliance
+- **Async/Await Support** ⭐ NEW in v2.6.0: Native async support for concurrent requests with `asyncio.gather()` - works with all 6 providers
+- **Interaction Tracing**: Complete LLM observability with programmatic access to prompts, responses, tokens, timing, and trace correlation for debugging, trust, and compliance
 - **Glyph Visual-Text Compression**: Revolutionary compression system that renders text as optimized images for 3-4x token compression and faster inference
 - **Centralized Configuration**: Global defaults and app-specific preferences at `~/.abstractcore/config/abstractcore.json`
 - **Intelligent Media Handling**: Upload images, PDFs, and documents with automatic maximum resolution optimization
@@ -522,7 +596,7 @@ python -m abstractcore.utils.cli --provider anthropic --model claude-3-5-haiku-l
 
 ## Built-in Applications (Ready-to-Use CLI Tools)
 
-AbstractCore includes **four specialized command-line applications** for common LLM tasks. These are production-ready tools that can be used directly from the terminal without any Python programming.
+AbstractCore includes **five specialized command-line applications** for common LLM tasks. These are production-ready tools that can be used directly from the terminal without any Python programming.
 
 ### Available Applications
 
@@ -532,6 +606,7 @@ AbstractCore includes **four specialized command-line applications** for common
 | **Extractor** | Entity and relationship extraction | `extractor` |
 | **Judge** | Text evaluation and scoring | `judge` |
 | **Intent Analyzer** | Psychological intent analysis & deception detection | `intent` |
+| **DeepSearch** | Autonomous multi-stage research with web search | `deepsearch` |
 
 ### Quick Usage Examples
 
@@ -555,6 +630,11 @@ judge proposal.md --custom-criteria has_examples,covers_risks --output assessmen
 intent conversation.txt --focus-participant user --depth comprehensive
 intent email.txt --format plain --context document --verbose
 intent chat_log.json --conversation-mode --provider lmstudio --model qwen/qwen3-30b-a3b-2507
+
+# Autonomous research with web search and reflexive refinement
+deepsearch "What are the latest advances in quantum computing?" --depth comprehensive
+deepsearch "AI impact on healthcare" --focus "diagnosis,treatment,ethics" --reflexive
+deepsearch "sustainable energy 2025" --max-sources 25 --provider openai --model gpt-4o-mini
 ```
 
 ### Installation & Setup
@@ -567,9 +647,10 @@ pip install abstractcore[all]
 
 # Apps are immediately available
 summarizer --help
-extractor --help  
+extractor --help
 judge --help
 intent --help
+deepsearch --help
 ```
 
 ### Alternative Usage Methods
@@ -580,12 +661,14 @@ summarizer document.txt
 extractor report.pdf
 judge essay.md
 intent conversation.txt
+deepsearch "your research query"
 
 # Method 2: Via Python module
 python -m abstractcore.apps summarizer document.txt
 python -m abstractcore.apps extractor report.pdf
 python -m abstractcore.apps judge essay.md
 python -m abstractcore.apps intent conversation.txt
+python -m abstractcore.apps deepsearch "your research query"
 ```
 
 ### Key Parameters
@@ -633,6 +716,7 @@ Each application has documentation with examples and usage information:
 - **[Extractor Guide](docs/apps/basic-extractor.md)** - Entity and relationship extraction
 - **[Intent Analyzer Guide](docs/apps/basic-intent.md)** - Psychological intent analysis and deception detection
 - **[Judge Guide](docs/apps/basic-judge.md)** - Text evaluation and scoring systems
+- **[DeepSearch Guide](docs/apps/basic-deepsearch.md)** - Autonomous multi-stage research with web search
 
 **When to use the apps:**
 - Processing documents without writing code
@@ -878,6 +962,9 @@ pip install abstractcore[media]
 pip install abstractcore[openai]
 pip install abstractcore[anthropic]
 pip install abstractcore[ollama]
+pip install abstractcore[lmstudio]
+pip install abstractcore[huggingface]
+pip install abstractcore[mlx]  # macOS/Apple Silicon only
 
 # With server support
 pip install abstractcore[server]
@@ -887,6 +974,16 @@ pip install abstractcore[embeddings]
 
 # Everything (recommended)
 pip install abstractcore[all]
+
+# Cross-platform (all except MLX - for Linux/Windows)
+pip install abstractcore[all-non-mlx]
+
+# Provider groups
+pip install abstractcore[all-providers]          # All providers (includes MLX)
+pip install abstractcore[all-providers-non-mlx]  # All providers except MLX
+pip install abstractcore[local-providers]        # Ollama, LMStudio, MLX
+pip install abstractcore[local-providers-non-mlx]  # Ollama, LMStudio only
+pip install abstractcore[api-providers]          # OpenAI, Anthropic
 ```
 
 **Media processing extras:**
@@ -917,6 +1014,7 @@ All tests passing as of October 12th, 2025.
 ## Quick Links
 
 - **[📚 Documentation Index](docs/)** - Complete documentation navigation guide
+- **[🔍 Interaction Tracing](docs/interaction-tracing.md)** - LLM observability and debugging ⭐ NEW
 - **[Getting Started](docs/getting-started.md)** - 5-minute quick start
 - **[⚙️ Prerequisites](docs/prerequisites.md)** - Provider setup (OpenAI, Anthropic, Ollama, etc.)
 - **[📖 Python API](docs/api-reference.md)** - Complete Python API reference

{abstractcore-2.5.3 → abstractcore-2.6.0}/README.md

@@ -14,7 +14,11 @@ A unified Python library for interaction with multiple Large Language Model (LLM
 ### Installation
 
 ```bash
+# macOS/Apple Silicon (includes MLX)
 pip install abstractcore[all]
+
+# Linux/Windows (excludes MLX)
+pip install abstractcore[all-non-mlx]
 ```
 
 ### Basic Usage
@@ -205,6 +209,69 @@ export_traces(traces, format='markdown', file_path='workflow_trace.md')
 
 [Learn more about Interaction Tracing](docs/interaction-tracing.md)
 
+### Async/Await Support
+
+Execute concurrent LLM requests for batch operations, multi-provider comparisons, or non-blocking web applications. **Production-ready with validated 6-7.5x performance improvement** for concurrent requests.
+
+```python
+import asyncio
+from abstractcore import create_llm
+
+async def main():
+    llm = create_llm("openai", model="gpt-4o-mini")
+
+    # Execute 3 requests concurrently (6-7x faster!)
+    tasks = [
+        llm.agenerate(f"Summarize {topic}")
+        for topic in ["Python", "JavaScript", "Rust"]
+    ]
+    responses = await asyncio.gather(*tasks)
+
+    for response in responses:
+        print(response.content)
+
+asyncio.run(main())
+```
+
+**Performance (Validated with Real Testing):**
+- **Ollama**: 7.5x faster for concurrent requests
+- **LMStudio**: 6.5x faster for concurrent requests
+- **OpenAI**: 6.0x faster for concurrent requests
+- **Anthropic**: 7.4x faster for concurrent requests
+- **Average**: ~7x speedup across all providers
+
+**Native Async vs Fallback:**
+- **Native async** (httpx.AsyncClient): Ollama, LMStudio, OpenAI, Anthropic
+- **Fallback** (asyncio.to_thread): MLX, HuggingFace
+- All providers work seamlessly - fallback keeps event loop responsive
+
+**Use Cases:**
+- Batch operations with 6-7x speedup via parallel execution
+- Multi-provider comparisons (query OpenAI and Anthropic simultaneously)
+- FastAPI/async web frameworks integration
+- Session async for conversation management
+
+**Works with:**
+- All 6 providers (OpenAI, Anthropic, Ollama, LMStudio, MLX, HuggingFace)
+- Streaming via `async for chunk in llm.agenerate(..., stream=True)`
+- Sessions via `await session.agenerate(...)`
+- Zero breaking changes to sync API
+
+**Learn async patterns:**
+
+AbstractCore includes an educational [async CLI demo](examples/async_cli_demo.py) that demonstrates 8 core async/await patterns:
+- Event-driven progress with GlobalEventBus
+- Parallel tool execution with asyncio.gather()
+- Proper async streaming pattern (await first, then async for)
+- Non-blocking animations and user input
+
+```bash
+# Try the educational async demo
+python examples/async_cli_demo.py --provider ollama --model qwen3:4b --stream
+```
+
+[Learn more in CLI docs](docs/acore-cli.md#async-cli-demo-educational-reference)
+
 ### Media Handling
 
 AbstractCore provides unified media handling across all providers with automatic resolution optimization. Upload images, PDFs, and documents using the same simple API regardless of your provider.
@@ -302,7 +369,8 @@ if response.metadata and response.metadata.get('compression_used'):
 
 - **Offline-First Design**: Built primarily for open source LLMs with full offline capability. Download once, run forever without internet access
 - **Provider Agnostic**: Seamlessly switch between OpenAI, Anthropic, Ollama, LMStudio, MLX, HuggingFace
-- **Interaction Tracing**: Complete LLM observability with programmatic access to prompts, responses, tokens, and timing for debugging and compliance
+- **Async/Await Support** ⭐ NEW in v2.6.0: Native async support for concurrent requests with `asyncio.gather()` - works with all 6 providers
+- **Interaction Tracing**: Complete LLM observability with programmatic access to prompts, responses, tokens, timing, and trace correlation for debugging, trust, and compliance
 - **Glyph Visual-Text Compression**: Revolutionary compression system that renders text as optimized images for 3-4x token compression and faster inference
 - **Centralized Configuration**: Global defaults and app-specific preferences at `~/.abstractcore/config/abstractcore.json`
 - **Intelligent Media Handling**: Upload images, PDFs, and documents with automatic maximum resolution optimization
@@ -416,7 +484,7 @@ python -m abstractcore.utils.cli --provider anthropic --model claude-3-5-haiku-l
 
 ## Built-in Applications (Ready-to-Use CLI Tools)
 
-AbstractCore includes **four specialized command-line applications** for common LLM tasks. These are production-ready tools that can be used directly from the terminal without any Python programming.
+AbstractCore includes **five specialized command-line applications** for common LLM tasks. These are production-ready tools that can be used directly from the terminal without any Python programming.
 
 ### Available Applications
 
@@ -426,6 +494,7 @@ AbstractCore includes **four specialized command-line applications** for common
 | **Extractor** | Entity and relationship extraction | `extractor` |
 | **Judge** | Text evaluation and scoring | `judge` |
 | **Intent Analyzer** | Psychological intent analysis & deception detection | `intent` |
+| **DeepSearch** | Autonomous multi-stage research with web search | `deepsearch` |
 
 ### Quick Usage Examples
 
@@ -449,6 +518,11 @@ judge proposal.md --custom-criteria has_examples,covers_risks --output assessmen
 intent conversation.txt --focus-participant user --depth comprehensive
 intent email.txt --format plain --context document --verbose
 intent chat_log.json --conversation-mode --provider lmstudio --model qwen/qwen3-30b-a3b-2507
+
+# Autonomous research with web search and reflexive refinement
+deepsearch "What are the latest advances in quantum computing?" --depth comprehensive
+deepsearch "AI impact on healthcare" --focus "diagnosis,treatment,ethics" --reflexive
+deepsearch "sustainable energy 2025" --max-sources 25 --provider openai --model gpt-4o-mini
 ```
 
 ### Installation & Setup
@@ -461,9 +535,10 @@ pip install abstractcore[all]
 
 # Apps are immediately available
 summarizer --help
-extractor --help  
+extractor --help
 judge --help
 intent --help
+deepsearch --help
 ```
 
 ### Alternative Usage Methods
@@ -474,12 +549,14 @@ summarizer document.txt
 extractor report.pdf
 judge essay.md
 intent conversation.txt
+deepsearch "your research query"
 
 # Method 2: Via Python module
 python -m abstractcore.apps summarizer document.txt
 python -m abstractcore.apps extractor report.pdf
 python -m abstractcore.apps judge essay.md
 python -m abstractcore.apps intent conversation.txt
+python -m abstractcore.apps deepsearch "your research query"
 ```
 
 ### Key Parameters
@@ -527,6 +604,7 @@ Each application has documentation with examples and usage information:
 - **[Extractor Guide](docs/apps/basic-extractor.md)** - Entity and relationship extraction
 - **[Intent Analyzer Guide](docs/apps/basic-intent.md)** - Psychological intent analysis and deception detection
 - **[Judge Guide](docs/apps/basic-judge.md)** - Text evaluation and scoring systems
+- **[DeepSearch Guide](docs/apps/basic-deepsearch.md)** - Autonomous multi-stage research with web search
 
 **When to use the apps:**
 - Processing documents without writing code
@@ -772,6 +850,9 @@ pip install abstractcore[media]
 pip install abstractcore[openai]
 pip install abstractcore[anthropic]
 pip install abstractcore[ollama]
+pip install abstractcore[lmstudio]
+pip install abstractcore[huggingface]
+pip install abstractcore[mlx]  # macOS/Apple Silicon only
 
 # With server support
 pip install abstractcore[server]
@@ -781,6 +862,16 @@ pip install abstractcore[embeddings]
 
 # Everything (recommended)
 pip install abstractcore[all]
+
+# Cross-platform (all except MLX - for Linux/Windows)
+pip install abstractcore[all-non-mlx]
+
+# Provider groups
+pip install abstractcore[all-providers]          # All providers (includes MLX)
+pip install abstractcore[all-providers-non-mlx]  # All providers except MLX
+pip install abstractcore[local-providers]        # Ollama, LMStudio, MLX
+pip install abstractcore[local-providers-non-mlx]  # Ollama, LMStudio only
+pip install abstractcore[api-providers]          # OpenAI, Anthropic
 ```
 
 **Media processing extras:**
@@ -811,6 +902,7 @@ All tests passing as of October 12th, 2025.
 ## Quick Links
 
 - **[📚 Documentation Index](docs/)** - Complete documentation navigation guide
+- **[🔍 Interaction Tracing](docs/interaction-tracing.md)** - LLM observability and debugging ⭐ NEW
 - **[Getting Started](docs/getting-started.md)** - 5-minute quick start
 - **[⚙️ Prerequisites](docs/prerequisites.md)** - Provider setup (OpenAI, Anthropic, Ollama, etc.)
 - **[📖 Python API](docs/api-reference.md)** - Complete Python API reference

{abstractcore-2.5.3 → abstractcore-2.6.0}/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-2.5.3 → abstractcore-2.6.0}/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-2.5.3 → abstractcore-2.6.0}/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-2.5.3 → abstractcore-2.6.0}/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 [