abstractcore 2.4.5__tar.gz → 2.4.7__tar.gz

{abstractcore-2.4.5 → abstractcore-2.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.4.5
+Version: 2.4.7
 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>
@@ -29,6 +29,7 @@ License-File: LICENSE
 Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: httpx<1.0.0,>=0.24.0
 Requires-Dist: tiktoken<1.0.0,>=0.5.0
+Requires-Dist: requests<3.0.0,>=2.25.0
 Provides-Extra: openai
 Requires-Dist: openai<2.0.0,>=1.0.0; extra == "openai"
 Provides-Extra: anthropic
@@ -46,6 +47,11 @@ Provides-Extra: embeddings
 Requires-Dist: sentence-transformers<4.0.0,>=2.7.0; extra == "embeddings"
 Requires-Dist: numpy<2.0.0,>=1.20.0; extra == "embeddings"
 Provides-Extra: processing
+Provides-Extra: tools
+Requires-Dist: beautifulsoup4<5.0.0,>=4.12.0; extra == "tools"
+Requires-Dist: lxml<6.0.0,>=4.9.0; extra == "tools"
+Requires-Dist: duckduckgo-search<4.0.0,>=3.8.0; extra == "tools"
+Requires-Dist: psutil<6.0.0,>=5.9.0; extra == "tools"
 Provides-Extra: media
 Requires-Dist: Pillow<12.0.0,>=10.0.0; extra == "media"
 Requires-Dist: pymupdf4llm<1.0.0,>=0.0.20; extra == "media"
@@ -60,9 +66,9 @@ 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
-Requires-Dist: abstractcore[anthropic,dev,docs,embeddings,huggingface,lmstudio,media,mlx,ollama,openai,processing,server,test]; extra == "all"
+Requires-Dist: abstractcore[anthropic,dev,docs,embeddings,huggingface,lmstudio,media,mlx,ollama,openai,processing,server,test,tools]; extra == "all"
 Provides-Extra: lightweight
-Requires-Dist: abstractcore[anthropic,embeddings,lmstudio,media,ollama,openai,processing,server]; extra == "lightweight"
+Requires-Dist: abstractcore[anthropic,embeddings,lmstudio,media,ollama,openai,processing,server,tools]; extra == "lightweight"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
@@ -89,7 +95,7 @@ Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.22.0; extra == "docs"
 Requires-Dist: mkdocs-autorefs>=0.4.0; extra == "docs"
 Provides-Extra: full-dev
-Requires-Dist: abstractcore[all-providers,dev,docs,test]; extra == "full-dev"
+Requires-Dist: abstractcore[all-providers,dev,docs,test,tools]; extra == "full-dev"
 Dynamic: license-file
 
 # AbstractCore
@@ -122,6 +128,21 @@ response = llm.generate("What is the capital of France?")
 print(response.content)
 ```
 
+### Deterministic Generation
+
+```python
+from abstractcore import create_llm
+
+# Deterministic outputs with seed + temperature=0
+llm = create_llm("openai", model="gpt-3.5-turbo", seed=42, temperature=0.0)
+
+# These will produce identical outputs
+response1 = llm.generate("Write exactly 3 words about coding")
+response2 = llm.generate("Write exactly 3 words about coding")
+print(f"Response 1: {response1.content}")  # "Innovative, challenging, rewarding."
+print(f"Response 2: {response2.content}")  # "Innovative, challenging, rewarding."
+```
+
 ### Tool Calling
 
 ```python
@@ -140,6 +161,78 @@ response = llm.generate(
 print(response.content)
 ```
 
+### Response Object (GenerateResponse)
+
+Every LLM generation returns a **GenerateResponse** object with consistent structure across all providers:
+
+```python
+from abstractcore import create_llm
+
+llm = create_llm("openai", model="gpt-4o-mini")
+response = llm.generate("Explain quantum computing in simple terms")
+
+# Core response data
+print(f"Content: {response.content}")               # Generated text
+print(f"Model: {response.model}")                   # Model used
+print(f"Finish reason: {response.finish_reason}")   # Why generation stopped
+
+# Consistent token access across ALL providers (NEW in v2.4.7)
+print(f"Input tokens: {response.input_tokens}")     # Always available
+print(f"Output tokens: {response.output_tokens}")   # Always available  
+print(f"Total tokens: {response.total_tokens}")     # Always available
+
+# Generation time tracking (NEW in v2.4.7)
+print(f"Generation time: {response.gen_time}ms")    # Always available (rounded to 1 decimal)
+
+# Advanced access
+print(f"Tool calls: {response.tool_calls}")         # Tools executed (if any)
+print(f"Raw usage: {response.usage}")               # Provider-specific token data
+print(f"Metadata: {response.metadata}")             # Additional context
+
+# Comprehensive summary
+print(f"Summary: {response.get_summary()}")         # "Model: gpt-4o-mini | Tokens: 117 | Time: 1234.5ms"
+```
+
+**Token Count Sources:**
+- **Provider APIs**: OpenAI, Anthropic, LMStudio (native API token counts)
+- **AbstractCore Calculation**: MLX, HuggingFace, Mock (using `token_utils.py`)
+- **Mixed Sources**: Ollama (combination of provider and calculated tokens)
+
+**Backward Compatibility**: Legacy `prompt_tokens` and `completion_tokens` keys remain available in `response.usage` dictionary.
+
+### Built-in Tools
+
+AbstractCore includes a comprehensive set of ready-to-use tools for common tasks:
+
+```python
+from abstractcore.tools.common_tools import fetch_url, search_files, read_file
+
+# Intelligent web content fetching with automatic parsing
+result = fetch_url("https://api.github.com/repos/python/cpython")
+# Automatically detects JSON, HTML, images, PDFs, etc. and provides structured analysis
+
+# File system operations
+files = search_files("def.*fetch", ".", file_pattern="*.py")  # Find function definitions
+content = read_file("config.json")  # Read file contents
+
+# Use with any LLM
+llm = create_llm("anthropic", model="claude-3-5-haiku-latest")
+response = llm.generate(
+    "Analyze this API response and summarize the key information",
+    tools=[fetch_url]
+)
+```
+
+**Available Tools:**
+- `fetch_url` - Intelligent web content fetching with automatic content type detection and parsing
+- `search_files` - Search for text patterns inside files using regex
+- `list_files` - Find and list files by names/paths using glob patterns  
+- `read_file` - Read file contents with optional line range selection
+- `write_file` - Write content to files with directory creation
+- `edit_file` - Edit files using pattern matching and replacement
+- `web_search` - Search the web using DuckDuckGo
+- `execute_command` - Execute shell commands safely with security controls
+
 ### Session Management
 
 ```python
@@ -223,19 +316,22 @@ response = llm.generate(
 - **Session Management**: Persistent conversations with metadata, analytics, and complete serialization
 - **Structured Responses**: Clean, predictable output formats with Pydantic
 - **Streaming Support**: Real-time token generation for interactive experiences
+- **Consistent Token Terminology**: Unified `input_tokens`, `output_tokens`, `total_tokens` across all providers
 - **Embeddings**: Built-in support for semantic search and RAG applications
 - **Universal Server**: Optional OpenAI-compatible API server with `/v1/responses` endpoint
 
 ## Supported Providers
 
-| Provider | Status | Setup |
-|----------|--------|-------|
-| **OpenAI** | Full | [Get API key](docs/prerequisites.md#openai-setup) |
-| **Anthropic** | Full | [Get API key](docs/prerequisites.md#anthropic-setup) |
-| **Ollama** | Full | [Install guide](docs/prerequisites.md#ollama-setup) |
-| **LMStudio** | Full | [Install guide](docs/prerequisites.md#lmstudio-setup) |
-| **MLX** | Full | [Setup guide](docs/prerequisites.md#mlx-setup) |
-| **HuggingFace** | Full | [Setup guide](docs/prerequisites.md#huggingface-setup) |
+| Provider | Status | SEED Support | Setup |
+|----------|--------|-------------|-------|
+| **OpenAI** | Full | ✅ Native | [Get API key](docs/prerequisites.md#openai-setup) |
+| **Anthropic** | Full | ⚠️ Warning* | [Get API key](docs/prerequisites.md#anthropic-setup) |
+| **Ollama** | Full | ✅ Native | [Install guide](docs/prerequisites.md#ollama-setup) |
+| **LMStudio** | Full | ✅ Native | [Install guide](docs/prerequisites.md#lmstudio-setup) |
+| **MLX** | Full | ✅ Native | [Setup guide](docs/prerequisites.md#mlx-setup) |
+| **HuggingFace** | Full | ✅ Native | [Setup guide](docs/prerequisites.md#huggingface-setup) |
+
+*Anthropic doesn't support seed parameters but issues a warning when provided. Use `temperature=0.0` for more consistent outputs.
 
 ## Server Mode (Optional HTTP REST API)
 

{abstractcore-2.4.5 → abstractcore-2.4.7}/README.md

@@ -28,6 +28,21 @@ response = llm.generate("What is the capital of France?")
 print(response.content)
 ```
 
+### Deterministic Generation
+
+```python
+from abstractcore import create_llm
+
+# Deterministic outputs with seed + temperature=0
+llm = create_llm("openai", model="gpt-3.5-turbo", seed=42, temperature=0.0)
+
+# These will produce identical outputs
+response1 = llm.generate("Write exactly 3 words about coding")
+response2 = llm.generate("Write exactly 3 words about coding")
+print(f"Response 1: {response1.content}")  # "Innovative, challenging, rewarding."
+print(f"Response 2: {response2.content}")  # "Innovative, challenging, rewarding."
+```
+
 ### Tool Calling
 
 ```python
@@ -46,6 +61,78 @@ response = llm.generate(
 print(response.content)
 ```
 
+### Response Object (GenerateResponse)
+
+Every LLM generation returns a **GenerateResponse** object with consistent structure across all providers:
+
+```python
+from abstractcore import create_llm
+
+llm = create_llm("openai", model="gpt-4o-mini")
+response = llm.generate("Explain quantum computing in simple terms")
+
+# Core response data
+print(f"Content: {response.content}")               # Generated text
+print(f"Model: {response.model}")                   # Model used
+print(f"Finish reason: {response.finish_reason}")   # Why generation stopped
+
+# Consistent token access across ALL providers (NEW in v2.4.7)
+print(f"Input tokens: {response.input_tokens}")     # Always available
+print(f"Output tokens: {response.output_tokens}")   # Always available  
+print(f"Total tokens: {response.total_tokens}")     # Always available
+
+# Generation time tracking (NEW in v2.4.7)
+print(f"Generation time: {response.gen_time}ms")    # Always available (rounded to 1 decimal)
+
+# Advanced access
+print(f"Tool calls: {response.tool_calls}")         # Tools executed (if any)
+print(f"Raw usage: {response.usage}")               # Provider-specific token data
+print(f"Metadata: {response.metadata}")             # Additional context
+
+# Comprehensive summary
+print(f"Summary: {response.get_summary()}")         # "Model: gpt-4o-mini | Tokens: 117 | Time: 1234.5ms"
+```
+
+**Token Count Sources:**
+- **Provider APIs**: OpenAI, Anthropic, LMStudio (native API token counts)
+- **AbstractCore Calculation**: MLX, HuggingFace, Mock (using `token_utils.py`)
+- **Mixed Sources**: Ollama (combination of provider and calculated tokens)
+
+**Backward Compatibility**: Legacy `prompt_tokens` and `completion_tokens` keys remain available in `response.usage` dictionary.
+
+### Built-in Tools
+
+AbstractCore includes a comprehensive set of ready-to-use tools for common tasks:
+
+```python
+from abstractcore.tools.common_tools import fetch_url, search_files, read_file
+
+# Intelligent web content fetching with automatic parsing
+result = fetch_url("https://api.github.com/repos/python/cpython")
+# Automatically detects JSON, HTML, images, PDFs, etc. and provides structured analysis
+
+# File system operations
+files = search_files("def.*fetch", ".", file_pattern="*.py")  # Find function definitions
+content = read_file("config.json")  # Read file contents
+
+# Use with any LLM
+llm = create_llm("anthropic", model="claude-3-5-haiku-latest")
+response = llm.generate(
+    "Analyze this API response and summarize the key information",
+    tools=[fetch_url]
+)
+```
+
+**Available Tools:**
+- `fetch_url` - Intelligent web content fetching with automatic content type detection and parsing
+- `search_files` - Search for text patterns inside files using regex
+- `list_files` - Find and list files by names/paths using glob patterns  
+- `read_file` - Read file contents with optional line range selection
+- `write_file` - Write content to files with directory creation
+- `edit_file` - Edit files using pattern matching and replacement
+- `web_search` - Search the web using DuckDuckGo
+- `execute_command` - Execute shell commands safely with security controls
+
 ### Session Management
 
 ```python
@@ -129,19 +216,22 @@ response = llm.generate(
 - **Session Management**: Persistent conversations with metadata, analytics, and complete serialization
 - **Structured Responses**: Clean, predictable output formats with Pydantic
 - **Streaming Support**: Real-time token generation for interactive experiences
+- **Consistent Token Terminology**: Unified `input_tokens`, `output_tokens`, `total_tokens` across all providers
 - **Embeddings**: Built-in support for semantic search and RAG applications
 - **Universal Server**: Optional OpenAI-compatible API server with `/v1/responses` endpoint
 
 ## Supported Providers
 
-| Provider | Status | Setup |
-|----------|--------|-------|
-| **OpenAI** | Full | [Get API key](docs/prerequisites.md#openai-setup) |
-| **Anthropic** | Full | [Get API key](docs/prerequisites.md#anthropic-setup) |
-| **Ollama** | Full | [Install guide](docs/prerequisites.md#ollama-setup) |
-| **LMStudio** | Full | [Install guide](docs/prerequisites.md#lmstudio-setup) |
-| **MLX** | Full | [Setup guide](docs/prerequisites.md#mlx-setup) |
-| **HuggingFace** | Full | [Setup guide](docs/prerequisites.md#huggingface-setup) |
+| Provider | Status | SEED Support | Setup |
+|----------|--------|-------------|-------|
+| **OpenAI** | Full | ✅ Native | [Get API key](docs/prerequisites.md#openai-setup) |
+| **Anthropic** | Full | ⚠️ Warning* | [Get API key](docs/prerequisites.md#anthropic-setup) |
+| **Ollama** | Full | ✅ Native | [Install guide](docs/prerequisites.md#ollama-setup) |
+| **LMStudio** | Full | ✅ Native | [Install guide](docs/prerequisites.md#lmstudio-setup) |
+| **MLX** | Full | ✅ Native | [Setup guide](docs/prerequisites.md#mlx-setup) |
+| **HuggingFace** | Full | ✅ Native | [Setup guide](docs/prerequisites.md#huggingface-setup) |
+
+*Anthropic doesn't support seed parameters but issues a warning when provided. Use `temperature=0.0` for more consistent outputs.
 
 ## Server Mode (Optional HTTP REST API)
 

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/__init__.py

@@ -44,6 +44,9 @@ except ImportError:
 from .processing import BasicSummarizer, SummaryStyle, SummaryLength, BasicExtractor
 _has_processing = True
 
+# Tools module (core functionality)
+from .tools import tool
+
 __all__ = [
     'create_llm',
     'BasicSession',
@@ -54,7 +57,8 @@ __all__ = [
     'MessageRole',
     'ModelNotFoundError',
     'ProviderAPIError',
-    'AuthenticationError'
+    'AuthenticationError',
+    'tool'
 ]
 
 if _has_embeddings:

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/assets/session_schema.json

@@ -109,7 +109,7 @@
                 "tokens_before": { "type": "integer" },
                 "tokens_after": { "type": "integer" },
                 "compression_ratio": { "type": "number" },
-                "generation_time_ms": { "type": "number" }
+                "gen_time": { "type": "number" }
               }
             }
           },

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/core/interface.py

@@ -70,6 +70,8 @@ class AbstractCoreInterface(ABC):
                  max_tokens: Optional[int] = None,
                  max_input_tokens: Optional[int] = None,
                  max_output_tokens: int = 2048,
+                 temperature: float = 0.7,
+                 seed: Optional[int] = None,
                  debug: bool = False,
                  **kwargs):
         self.model = model
@@ -79,6 +81,11 @@ class AbstractCoreInterface(ABC):
         self.max_tokens = max_tokens
         self.max_input_tokens = max_input_tokens
         self.max_output_tokens = max_output_tokens
+        
+        # Unified generation parameters
+        self.temperature = temperature
+        self.seed = seed
+        
         self.debug = debug
 
         # Validate token parameters

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/core/session.py

@@ -32,8 +32,23 @@ class BasicSession:
                  tool_timeout: Optional[float] = None,
                  recovery_timeout: Optional[float] = None,
                  auto_compact: bool = False,
-                 auto_compact_threshold: int = 6000):
-        """Initialize basic session"""
+                 auto_compact_threshold: int = 6000,
+                 temperature: Optional[float] = None,
+                 seed: Optional[int] = None):
+        """Initialize basic session
+        
+        Args:
+            provider: LLM provider instance
+            system_prompt: System prompt for the session
+            tools: List of available tools
+            timeout: HTTP request timeout
+            tool_timeout: Tool execution timeout
+            recovery_timeout: Circuit breaker recovery timeout
+            auto_compact: Enable automatic conversation compaction
+            auto_compact_threshold: Token threshold for auto-compaction
+            temperature: Default temperature for generation (0.0-1.0)
+            seed: Default seed for deterministic generation
+        """
 
         self.provider = provider
         self.id = str(uuid.uuid4())
@@ -45,6 +60,10 @@ class BasicSession:
         self.auto_compact_threshold = auto_compact_threshold
         self._original_session = None  # Track if this is a compacted session
         
+        # Store session-level generation parameters
+        self.temperature = temperature
+        self.seed = seed
+        
         # Optional analytics fields
         self.summary = None
         self.assessment = None
@@ -189,6 +208,12 @@ class BasicSession:
         # Extract media parameter explicitly (fix for media parameter passing)
         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
+
         # Call provider
         response = self.provider.generate(
             prompt=prompt,
@@ -735,7 +760,7 @@ class BasicSession:
                 "tokens_before": original_tokens,
                 "tokens_after": self._estimate_tokens_for_summary(summary_result.summary),
                 "compression_ratio": self._calculate_compression_ratio(original_tokens, summary_result.summary),
-                "generation_time_ms": duration_ms
+                "gen_time": duration_ms
             }
         }
         

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/core/types.py

@@ -91,6 +91,7 @@ class GenerateResponse:
     usage: Optional[Dict[str, int]] = None
     tool_calls: Optional[List[Dict[str, Any]]] = None
     metadata: Optional[Dict[str, Any]] = None
+    gen_time: Optional[float] = None  # Generation time in milliseconds
 
     def has_tool_calls(self) -> bool:
         """Check if response contains tool calls"""
@@ -109,6 +110,29 @@ class GenerateResponse:
             parts.append(f"Model: {self.model}")
         if self.usage:
             parts.append(f"Tokens: {self.usage.get('total_tokens', 'unknown')}")
+        if self.gen_time:
+            parts.append(f"Time: {self.gen_time:.1f}ms")
         if self.tool_calls:
             parts.append(f"Tools: {len(self.tool_calls)} executed")
-        return " | ".join(parts)
+        return " | ".join(parts)
+    
+    @property
+    def input_tokens(self) -> Optional[int]:
+        """Get input tokens with consistent terminology (prompt_tokens or input_tokens)."""
+        if not self.usage:
+            return None
+        return self.usage.get('input_tokens') or self.usage.get('prompt_tokens')
+    
+    @property
+    def output_tokens(self) -> Optional[int]:
+        """Get output tokens with consistent terminology (completion_tokens or output_tokens)."""
+        if not self.usage:
+            return None
+        return self.usage.get('output_tokens') or self.usage.get('completion_tokens')
+    
+    @property
+    def total_tokens(self) -> Optional[int]:
+        """Get total tokens."""
+        if not self.usage:
+            return None
+        return self.usage.get('total_tokens')

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/providers/anthropic_provider.py

@@ -47,8 +47,7 @@ class AnthropicProvider(BaseProvider):
         # Initialize tool handler
         self.tool_handler = UniversalToolHandler(model)
 
-        # Store configuration (remove duplicate max_tokens)
-        self.temperature = kwargs.get("temperature", 0.7)
+        # Store provider-specific configuration
         self.top_p = kwargs.get("top_p", 1.0)
         self.top_k = kwargs.get("top_k", None)
 
@@ -132,6 +131,19 @@ class AnthropicProvider(BaseProvider):
         if kwargs.get("top_k") or self.top_k:
             call_params["top_k"] = kwargs.get("top_k", self.top_k)
 
+        # Handle seed parameter (Anthropic doesn't support seed natively)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            import warnings
+            warnings.warn(
+                f"Seed parameter ({seed_value}) is not supported by Anthropic Claude API. "
+                f"For deterministic outputs, use temperature=0.0 which may provide more consistent results, "
+                f"though true determinism is not guaranteed.",
+                UserWarning,
+                stacklevel=3
+            )
+            self.logger.warning(f"Seed {seed_value} requested but not supported by Anthropic API")
+
         # Handle structured output using the "tool trick"
         structured_tool_name = None
         if response_model and PYDANTIC_AVAILABLE:
@@ -174,8 +186,14 @@ class AnthropicProvider(BaseProvider):
             if stream:
                 return self._stream_response(call_params, tools)
             else:
+                # Track generation time
+                start_time = time.time()
                 response = self.client.messages.create(**call_params)
+                gen_time = round((time.time() - start_time) * 1000, 1)
+                
                 formatted = self._format_response(response)
+                # Add generation time to response
+                formatted.gen_time = gen_time
 
                 # Handle tool execution for Anthropic responses
                 if tools and (formatted.has_tool_calls() or

{abstractcore-2.4.5 → abstractcore-2.4.7}/abstractcore/providers/base.py

@@ -570,8 +570,32 @@ class BaseProvider(AbstractCoreInterface, ABC):
         result_kwargs = kwargs.copy()
         result_kwargs["max_output_tokens"] = effective_max_output
 
+        # Add unified generation parameters with fallback hierarchy: kwargs → instance → defaults
+        result_kwargs["temperature"] = result_kwargs.get("temperature", self.temperature)
+        if self.seed is not None:
+            result_kwargs["seed"] = result_kwargs.get("seed", self.seed)
+
         return result_kwargs
 
+    def _extract_generation_params(self, **kwargs) -> Dict[str, Any]:
+        """
+        Extract generation parameters with consistent fallback hierarchy.
+        
+        Returns:
+            Dict containing temperature, seed, and other generation parameters
+        """
+        params = {}
+        
+        # Temperature (always present)
+        params["temperature"] = kwargs.get("temperature", self.temperature)
+        
+        # Seed (only if not None)
+        seed_value = kwargs.get("seed", self.seed)
+        if seed_value is not None:
+            params["seed"] = seed_value
+            
+        return params
+
     def _get_provider_max_tokens_param(self, kwargs: Dict[str, Any]) -> int:
         """
         Extract the appropriate max tokens parameter for this provider.