abstractcore 2.6.6__py3-none-any.whl → 2.6.8__py3-none-any.whl

abstractcore/assets/model_capabilities.json

@@ -638,17 +638,26 @@
       "max_tokens": 262144
     },
     "qwen3-coder-30b": {
-      "max_output_tokens": 8192,
+      "max_output_tokens": 65536,
       "tool_support": "native",
       "structured_output": "native",
       "parallel_tools": true,
       "vision_support": false,
       "audio_support": false,
-      "notes": "Code-focused model with native tool support via chatml-function-calling format",
-      "source": "Alibaba official docs",
+      "architecture": "mixture_of_experts",
+      "total_parameters": "30.5B",
+      "active_parameters": "3.3B",
+      "experts": 128,
+      "experts_activated": 8,
+      "notes": "Code-focused MoE model (30.5B total/3.3B active, 128 experts/8 activated). Native tool support via chatml-function-calling format. Supports up to 1M tokens with YaRN extension.",
+      "source": "Qwen HuggingFace model card 2025",
       "canonical_name": "qwen3-coder-30b",
-      "aliases": [],
-      "max_tokens": 32768
+      "aliases": [
+        "Qwen/Qwen3-Coder-30B-A3B-Instruct",
+        "qwen3-coder-30b-a3b",
+        "qwen3-coder-30b-a3b-instruct"
+      ],
+      "max_tokens": 262144
     },
     "qwen2-vl": {
       "max_output_tokens": 8192,

abstractcore/media/utils/image_scaler.py

@@ -3,20 +3,13 @@ Image scaling utility for AbstractCore media handling.
 
 Provides intelligent image scaling based on model-specific requirements
 and capabilities for vision models.
-
-Requires: PIL (Pillow) - install with `pip install Pillow`
 """
 
 from typing import Tuple, Optional, Union, Dict, Any
 from enum import Enum
 from pathlib import Path
 
-try:
-    from PIL import Image, ImageOps
-except ImportError as e:
-    raise ImportError(
-        "PIL (Pillow) is required for image scaling. Install with: pip install Pillow"
-    ) from e
+from PIL import Image, ImageOps
 
 from ..base import MediaProcessingError
 from ...utils.structured_logging import get_logger

abstractcore/processing/__init__.py

@@ -5,14 +5,14 @@ Basic text processing capabilities built on top of AbstractCore,
 demonstrating how to leverage the core infrastructure for real-world tasks.
 """
 
-from .basic_summarizer import BasicSummarizer, SummaryStyle, SummaryLength
+from .basic_summarizer import BasicSummarizer, SummaryStyle, SummaryLength, CompressionMode
 from .basic_extractor import BasicExtractor
 from .basic_judge import BasicJudge, JudgmentCriteria, Assessment, create_judge
 from .basic_deepsearch import BasicDeepSearch, ResearchReport, ResearchFinding, ResearchPlan, ResearchSubTask
 from .basic_intent import BasicIntentAnalyzer, IntentType, IntentDepth, IntentContext, IdentifiedIntent, IntentAnalysisOutput
 
 __all__ = [
-    'BasicSummarizer', 'SummaryStyle', 'SummaryLength',
+    'BasicSummarizer', 'SummaryStyle', 'SummaryLength', 'CompressionMode',
     'BasicExtractor',
     'BasicJudge', 'JudgmentCriteria', 'Assessment', 'create_judge',
     'BasicDeepSearch', 'ResearchReport', 'ResearchFinding', 'ResearchPlan', 'ResearchSubTask',

abstractcore/processing/basic_summarizer.py

@@ -35,6 +35,42 @@ class SummaryLength(Enum):
     COMPREHENSIVE = "comprehensive"  # Full analysis with context
 
 
+class CompressionMode(Enum):
+    """Compression aggressiveness for chat history summarization.
+
+    Controls how aggressively the summarizer compresses conversation history:
+    - LIGHT: Keep most information, only remove redundancy
+    - STANDARD: Balanced compression, main points and context
+    - HEAVY: Aggressive compression, only critical information
+    """
+    LIGHT = "light"
+    STANDARD = "standard"
+    HEAVY = "heavy"
+
+
+# Compression mode-specific instructions for summarization prompts
+COMPRESSION_INSTRUCTIONS = {
+    CompressionMode.LIGHT: (
+        "Preserve most details from this conversation while removing only redundancy. "
+        "Keep: all key decisions and outcomes, important context and background, "
+        "specific details/names/numbers/technical terms, all tool calls and results, "
+        "error messages and resolutions. Remove only: repetitive greetings, duplicate information."
+    ),
+    CompressionMode.STANDARD: (
+        "Summarize with balanced compression, keeping main points and essential context. "
+        "Keep: key decisions and rationale, important outcomes, critical context for ongoing work, "
+        "unresolved items and pending tasks. Remove: intermediate reasoning steps, "
+        "exploratory tangents, detailed tool outputs (keep only key findings)."
+    ),
+    CompressionMode.HEAVY: (
+        "Extract only the most critical information. Keep ONLY: final decisions made, "
+        "critical outcomes (success/failure), essential context to continue work, "
+        "blocking issues and hard dependencies. Remove: all exploratory discussion, "
+        "all intermediate steps, all detailed outputs, all background explanations."
+    ),
+}
+
+
 class LLMSummaryOutput(BaseModel):
     """LLM-generated summary output (without word counts)"""
     summary: str = Field(description="The main summary text")
@@ -493,7 +529,8 @@ Create a unified summary that represents the entire document effectively."""
         self,
         messages: List[dict],
         preserve_recent: int = 6,
-        focus: Optional[str] = None
+        focus: Optional[str] = None,
+        compression_mode: CompressionMode = CompressionMode.STANDARD
     ) -> SummaryOutput:
         """
         Specialized method for chat history summarization following SOTA 2025 practices
@@ -502,6 +539,7 @@ Create a unified summary that represents the entire document effectively."""
             messages: List of message dicts with 'role' and 'content' keys
             preserve_recent: Number of recent messages to keep intact (default 6)
             focus: Optional focus for summarization (e.g., "key decisions", "technical solutions")
+            compression_mode: How aggressively to compress (LIGHT, STANDARD, HEAVY)
 
         Returns:
             SummaryOutput: Structured summary optimized for chat history context
@@ -511,36 +549,67 @@ Create a unified summary that represents the entire document effectively."""
         - Focuses on decisions, solutions, and ongoing topics
         - Maintains user intent and assistant responses
         - Optimized for chat continuation rather than standalone summary
+
+        Compression Modes:
+        - LIGHT: Keep most information, only remove redundancy
+        - STANDARD: Balanced compression, main points and context
+        - HEAVY: Aggressive compression, only critical information
         """
+        # Build focus with compression instructions
+        compression_instruction = COMPRESSION_INSTRUCTIONS.get(
+            compression_mode,
+            COMPRESSION_INSTRUCTIONS[CompressionMode.STANDARD]
+        )
+
+        # Combine user focus with compression instruction
+        if focus:
+            effective_focus = f"{compression_instruction} Focus especially on: {focus}"
+        else:
+            effective_focus = compression_instruction
+
+        # Map compression mode to summary length for appropriate output size
+        length_map = {
+            CompressionMode.LIGHT: SummaryLength.DETAILED,
+            CompressionMode.STANDARD: SummaryLength.STANDARD,
+            CompressionMode.HEAVY: SummaryLength.BRIEF,
+        }
+        target_length = length_map.get(compression_mode, SummaryLength.STANDARD)
+
+        logger.debug("Chat history summarization with compression mode",
+                    message_count=len(messages),
+                    preserve_recent=preserve_recent,
+                    compression_mode=compression_mode.value,
+                    target_length=target_length.value)
+
         if len(messages) <= preserve_recent:
             # If short enough, just summarize normally
-            logger.debug("Chat history is short, using standard summarization", 
-                        message_count=len(messages), 
+            logger.debug("Chat history is short, using standard summarization",
+                        message_count=len(messages),
                         preserve_recent=preserve_recent)
             chat_text = self._format_chat_messages_to_text(messages)
             return self.summarize(
                 chat_text,
-                focus=focus or "conversational context and key information",
+                focus=effective_focus,
                 style=SummaryStyle.CONVERSATIONAL,
-                length=SummaryLength.STANDARD
+                length=target_length
             )
 
         # Split into older messages (to summarize) and recent messages (to preserve)
         older_messages = messages[:-preserve_recent]
         recent_messages = messages[-preserve_recent:]
-        
-        logger.debug("Splitting chat history for summarization", 
+
+        logger.debug("Splitting chat history for summarization",
                     total_messages=len(messages),
                     older_messages=len(older_messages),
                     recent_messages=len(recent_messages))
 
-        # Summarize older messages with conversational focus
+        # Summarize older messages with conversational focus and compression mode
         older_text = self._format_chat_messages_to_text(older_messages)
         older_summary = self.summarize(
             older_text,
-            focus=focus or "key decisions, solutions, and ongoing context",
+            focus=effective_focus,
             style=SummaryStyle.CONVERSATIONAL,
-            length=SummaryLength.DETAILED
+            length=target_length
         )
 
         # The summary should ONLY contain the older messages summary

abstractcore/providers/base.py

@@ -5,6 +5,7 @@ Base provider with integrated telemetry, events, and exception handling.
 import time
 import uuid
 import asyncio
+import warnings
 from collections import deque
 from typing import List, Dict, Any, Optional, Union, Iterator, AsyncIterator, Type
 from abc import ABC, abstractmethod
@@ -60,6 +61,13 @@ class BaseProvider(AbstractCoreInterface, ABC):
         # execute_tools: True = AbstractCore executes tools (legacy mode)
         #                False = Pass-through mode (default - for API server / agentic CLI)
         self.execute_tools = kwargs.get('execute_tools', False)
+        if self.execute_tools:
+            warnings.warn(
+                "execute_tools=True is deprecated. Prefer passing tools explicitly to generate() "
+                "and executing tool calls in the host/runtime via a ToolExecutor.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
         # Setup retry manager with optional configuration
         retry_config = kwargs.get('retry_config', None)
@@ -202,6 +210,12 @@ class BaseProvider(AbstractCoreInterface, ABC):
         """
         trace_id = str(uuid.uuid4())
 
+        # If trace retention is disabled, still return a trace_id for correlation
+        # without constructing/storing a full trace payload.
+        maxlen = getattr(getattr(self, "_traces", None), "maxlen", None)
+        if maxlen == 0:
+            return trace_id
+
         # Extract generation parameters
         temperature = kwargs.get('temperature', self.temperature)
         max_tokens = kwargs.get('max_tokens', self.max_tokens)
@@ -408,6 +422,13 @@ class BaseProvider(AbstractCoreInterface, ABC):
         
         # Handle tool execution control
         should_execute_tools = execute_tools if execute_tools is not None else self.execute_tools
+        if should_execute_tools and converted_tools:
+            warnings.warn(
+                "execute_tools=True is deprecated. Prefer passing tools explicitly to generate() "
+                "and executing tool calls in the host/runtime via a ToolExecutor.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if not should_execute_tools and converted_tools:
             # If tools are provided but execution is disabled,
             # we still pass them to the provider for generation but won't execute them
@@ -1556,4 +1577,4 @@ Please provide a structured response."""
         # Yield chunks asynchronously
         for chunk in sync_gen:
             yield chunk
-            await asyncio.sleep(0)  # Yield control to event loop
+            await asyncio.sleep(0)  # Yield control to event loop

abstractcore/server/app.py

@@ -1956,6 +1956,39 @@ async def provider_chat_completions(
     _, model = parse_model_string(request.model)
     return await process_chat_completion(provider, model, request, http_request)
 
+
+def _extract_trace_metadata(http_request: Request) -> Dict[str, Any]:
+    """Extract trace metadata from request headers (schema-safe)."""
+    meta: Dict[str, Any] = {}
+
+    raw = (
+        http_request.headers.get("x-abstractcore-trace-metadata")
+        or http_request.headers.get("x-abstract-trace-metadata")
+    )
+    if raw:
+        try:
+            parsed = json.loads(raw)
+            if isinstance(parsed, dict):
+                meta.update(parsed)
+        except Exception:
+            # Ignore invalid metadata payloads; tracing is best-effort.
+            pass
+
+    header_map = {
+        "actor_id": "x-abstractcore-actor-id",
+        "session_id": "x-abstractcore-session-id",
+        "run_id": "x-abstractcore-run-id",
+        "parent_run_id": "x-abstractcore-parent-run-id",
+    }
+    for key, header in header_map.items():
+        val = http_request.headers.get(header)
+        if val is not None and key not in meta:
+            meta[key] = val
+
+    # Never log or return these directly; they are for internal correlation only.
+    return meta
+
+
 async def process_chat_completion(
     provider: str,
     model: str,
@@ -2019,6 +2052,11 @@ async def process_chat_completion(
         # Create LLM instance
         # Prepare provider-specific kwargs
         provider_kwargs = {}
+        trace_metadata = _extract_trace_metadata(http_request)
+        if trace_metadata:
+            # Enable trace capture (trace_id) without retaining full trace buffers by default.
+            provider_kwargs["enable_tracing"] = True
+            provider_kwargs.setdefault("max_traces", 0)
         if request.base_url:
             provider_kwargs["base_url"] = request.base_url
             logger.info(
@@ -2047,6 +2085,8 @@ async def process_chat_completion(
             "tool_choice": request.tool_choice if request.tools else None,
             "execute_tools": False,  # Server mode - don't execute tools
         }
+        if trace_metadata:
+            gen_kwargs["trace_metadata"] = trace_metadata
 
         # Add optional parameters
         if request.stop:
@@ -2081,9 +2121,18 @@ async def process_chat_completion(
                 )
             else:
                 response = llm.generate(**gen_kwargs)
-                return convert_to_openai_response(
+                openai_response = convert_to_openai_response(
                     response, provider, model, syntax_rewriter, request_id
                 )
+                trace_id = None
+                if hasattr(response, "metadata") and isinstance(getattr(response, "metadata"), dict):
+                    trace_id = response.metadata.get("trace_id")
+                if trace_id:
+                    return JSONResponse(
+                        content=openai_response,
+                        headers={"X-AbstractCore-Trace-Id": str(trace_id)},
+                    )
+                return openai_response
         finally:
             # Cleanup temporary files (base64 and downloaded images) with delay to avoid race conditions
             import threading
@@ -2408,4 +2457,4 @@ Debug Mode:
 # ============================================================================
 
 if __name__ == "__main__":
-    run_server_with_args()
+    run_server_with_args()

abstractcore/tools/__init__.py

@@ -4,42 +4,63 @@ Universal tool support for AbstractCore.
 This package provides a unified tool system that works across all models
 and providers, whether they have native tool APIs or require prompting.
 
-Key components:
+Tool Execution Modes
+--------------------
+
+AbstractCore supports two tool execution modes:
+
+**Passthrough Mode (Default)** - execute_tools=False
+    The LLM returns raw tool call tags that downstream runtimes
+    (AbstractRuntime, Codex, Claude Code) parse and execute.
+    Use case: Agent loops, custom orchestration, multi-step workflows.
+
+**Direct Execution Mode** - execute_tools=True
+    AbstractCore parses and executes tools internally using the
+    global registry. Requires register_tool() for each tool.
+    Use case: Simple scripts, single-turn tool use.
+
+Key Components
+--------------
 - Core types (ToolDefinition, ToolCall, ToolResult)
 - Universal handler for all models
 - Architecture-based parsing and formatting
 - Tool registry for managing available tools
 
-Example usage:
+Example: Passthrough Mode (Default)
+-----------------------------------
 ```python
-from abstractcore.tools import ToolDefinition, UniversalToolHandler, register_tool
+from abstractcore import create_llm
+from abstractcore.tools import tool
 
-# Define a tool
-def list_files(directory: str = ".", pattern: str = "*") -> str:
-    '''List files in a directory.'''
-    import os, fnmatch
-    files = [f for f in os.listdir(directory) if fnmatch.fnmatch(f, pattern)]
-    return "\n".join(files)
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny"
 
-# Register the tool
-tool_def = ToolDefinition.from_function(list_files)
+llm = create_llm("ollama", model="qwen3:4b")
+response = llm.generate("Weather in Paris?", tools=[get_weather])
+# response.content has tool call tags - parse with your runtime
+```
 
-# Create handler for a model
-handler = UniversalToolHandler("qwen3-coder:30b")
+Example: Direct Execution Mode
+------------------------------
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool, register_tool
 
-# Get tool prompt for prompted models
-if handler.supports_prompted:
-    tool_prompt = handler.format_tools_prompt([tool_def])
-    print("Add this to your system prompt:")
-    print(tool_prompt)
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny"
 
-# Parse response for tool calls
-response = "I'll list the files. <|tool_call|>{'name': 'list_files', 'arguments': {'directory': '.'}}"
-tool_calls = handler.parse_response(response, mode="prompted")
+register_tool(get_weather)  # Required for direct execution
 
-if tool_calls.has_tool_calls():
-    print("Tool calls found:", tool_calls.tool_calls)
+llm = create_llm("ollama", model="qwen3:4b", execute_tools=True)
+response = llm.generate("Weather in Paris?", tools=[get_weather])
+# response.content has executed tool results
 ```
+
+Note: The @tool decorator creates metadata but does NOT auto-register.
+Tools are passed explicitly to generate(). Use register_tool() only
+when using direct execution mode.
 """
 
 # Core types

abstractcore/tools/common_tools.py

@@ -240,7 +240,7 @@ def list_files(directory_path: str = ".", pattern: str = "*", recursive: bool =
 
 
 @tool(
-    description="Search for text patterns INSIDE files using regex (returns file paths with line numbers by default)",
+    description="Search for text patterns INSIDE files and codes using regex (returns file paths with line numbers by default)",
     tags=["search", "content", "regex", "grep", "text"],
     when_to_use="When you need to find specific text, code patterns, or content INSIDE files (NOT for finding files by names)",
     examples=[
@@ -1742,9 +1742,9 @@ def _parse_binary_content(binary_bytes: bytes, content_type: str, include_previe
 
 
 @tool(
-    description="Edit files using pattern matching and replacement - simple, powerful, and intuitive",
-    tags=["file", "edit", "modify", "pattern", "replace", "regex"],
-    when_to_use="When you need to edit files by finding patterns (text, functions, code blocks) and replacing them",
+    description="Edit files by replacing text patterns using simple matching or regex",
+    tags=["file", "edit", "replace", "pattern", "substitute", "regex"],
+    when_to_use="When you need to edit files by replacing text. Supports simple text or regex patterns, line ranges, preview mode, and controlling replacement count.",
     examples=[
         {
             "description": "Replace simple text",
@@ -1764,7 +1764,7 @@ def _parse_binary_content(binary_bytes: bytes, content_type: str, include_previe
             }
         },
         {
-            "description": "Replace with occurrence limit",
+            "description": "Replace only first occurrence",
             "arguments": {
                 "file_path": "document.txt",
                 "pattern": "TODO",
@@ -1780,9 +1780,147 @@ def _parse_binary_content(binary_bytes: bytes, content_type: str, include_previe
                 "replacement": "class NewClass",
                 "preview_only": True
             }
+        },
+        {
+            "description": "Match pattern ignoring whitespace differences (enabled by default)",
+            "arguments": {
+                "file_path": "script.py",
+                "pattern": "if condition:\n    do_something()",
+                "replacement": "if condition:\n    do_something_else()",
+                "flexible_whitespace": True
+            }
         }
     ]
 )
+
+
+def _normalize_escape_sequences(text: str) -> str:
+    """Convert literal escape sequences to actual control characters.
+
+    Handles cases where LLMs send '\\n' (literal) instead of actual newlines.
+    This is a common issue when LLM output is over-escaped in JSON.
+
+    Args:
+        text: Input string potentially containing literal escape sequences
+
+    Returns:
+        String with \\n, \\t, \\r converted to actual control characters
+    """
+    # Only convert if there are literal escape sequences
+    if '\\n' in text or '\\t' in text or '\\r' in text:
+        text = text.replace('\\n', '\n')
+        text = text.replace('\\t', '\t')
+        text = text.replace('\\r', '\r')
+    return text
+
+
+def _flexible_whitespace_match(
+    pattern: str,
+    replacement: str,
+    content: str,
+    max_replacements: int
+) -> Optional[tuple]:
+    """
+    Match pattern with flexible leading whitespace handling.
+
+    Converts a multi-line pattern into a regex that:
+    1. Normalizes line endings (\r\n -> \n)
+    2. Matches any amount of leading whitespace on each line
+    3. Preserves the non-whitespace content exactly
+
+    Returns (updated_content, count) if matches found, None otherwise.
+    """
+    # Normalize line endings in both pattern and content
+    pattern_normalized = pattern.replace('\r\n', '\n')
+    content_normalized = content.replace('\r\n', '\n')
+
+    # Split pattern into lines
+    pattern_lines = pattern_normalized.split('\n')
+
+    # Build regex parts for each line
+    regex_parts = []
+    for i, line in enumerate(pattern_lines):
+        # Get leading whitespace and content
+        stripped = line.lstrip()
+        if stripped:
+            # Escape special regex characters in the content
+            escaped_content = re.escape(stripped)
+            # Match any leading whitespace (spaces or tabs)
+            regex_parts.append(r'[ \t]*' + escaped_content)
+        else:
+            # Empty line or whitespace-only - match any whitespace
+            regex_parts.append(r'[ \t]*')
+
+    # Join with flexible newline matching (handles \n or \r\n)
+    flexible_pattern = r'\r?\n'.join(regex_parts)
+
+    try:
+        regex = re.compile(flexible_pattern, re.MULTILINE)
+    except re.error:
+        return None
+
+    matches = list(regex.finditer(content_normalized))
+    if not matches:
+        return None
+
+    # Apply replacements
+    # For the replacement, we need to adjust indentation to match
+    # the actual indentation found in the match
+
+    def replacement_fn(match):
+        """Adjust replacement to use the indentation from the matched text."""
+        matched_text = match.group(0)
+        matched_lines = matched_text.split('\n')
+
+        # Normalize the replacement's line endings
+        repl_normalized = replacement.replace('\r\n', '\n')
+        repl_lines = repl_normalized.split('\n')
+
+        if not repl_lines:
+            return replacement
+
+        # For each line in the replacement, use the corresponding matched line's
+        # actual indentation. This preserves the file's indentation style exactly.
+        adjusted_lines = []
+        for j, repl_line in enumerate(repl_lines):
+            repl_stripped = repl_line.lstrip()
+
+            if j < len(matched_lines):
+                # We have a corresponding matched line - use its actual indentation
+                matched_line = matched_lines[j]
+                actual_indent_str = matched_line[:len(matched_line) - len(matched_line.lstrip())]
+                adjusted_lines.append(actual_indent_str + repl_stripped)
+            else:
+                # Extra lines in replacement - no matched counterpart
+                # Use the indentation from the last matched line as reference
+                if matched_lines:
+                    last_matched = matched_lines[-1]
+                    base_indent_str = last_matched[:len(last_matched) - len(last_matched.lstrip())]
+                    # Add relative indentation from replacement
+                    repl_indent_len = len(repl_line) - len(repl_stripped)
+                    pattern_last_indent = len(pattern_lines[-1]) - len(pattern_lines[-1].lstrip()) if pattern_lines else 0
+                    extra_spaces = max(0, repl_indent_len - pattern_last_indent)
+                    adjusted_lines.append(base_indent_str + ' ' * extra_spaces + repl_stripped)
+                else:
+                    adjusted_lines.append(repl_line)
+
+        return '\n'.join(adjusted_lines)
+
+    # Apply the replacement
+    if max_replacements == -1:
+        updated = regex.sub(replacement_fn, content_normalized)
+        count = len(matches)
+    else:
+        updated = regex.sub(replacement_fn, content_normalized, count=max_replacements)
+        count = min(len(matches), max_replacements)
+
+    # Restore original line endings if needed
+    if '\r\n' in content and '\r\n' not in updated:
+        updated = updated.replace('\n', '\r\n')
+
+    return (updated, count)
+
+
 def edit_file(
     file_path: str,
     pattern: str,
@@ -1792,12 +1930,14 @@ def edit_file(
     start_line: Optional[int] = None,
     end_line: Optional[int] = None,
     preview_only: bool = False,
-    encoding: str = "utf-8"
+    encoding: str = "utf-8",
+    flexible_whitespace: bool = True
 ) -> str:
     """
-    Edit files using pattern matching and replacement.
+    Replace text patterns in files using pattern matching.
 
     Finds patterns (text or regex) in files and replaces them with new content.
+    For complex multi-line edits, consider using edit_file with unified diff instead.
 
     Args:
         file_path: Path to the file to edit
@@ -1809,6 +1949,10 @@ def edit_file(
         end_line: Ending line number to limit search scope (1-indexed, optional)
         preview_only: Show what would be changed without applying (default: False)
         encoding: File encoding (default: "utf-8")
+        flexible_whitespace: Enable whitespace-flexible matching (default: True).
+            When enabled, matches patterns even if indentation differs between
+            the pattern and file content. Handles tabs vs spaces, different
+            indentation levels, and line ending differences (\n vs \r\n).
 
     Returns:
         Success message with replacement details or error message
@@ -1839,6 +1983,10 @@ def edit_file(
 
         original_content = content
 
+        # Normalize escape sequences - handles LLMs sending \\n instead of actual newlines
+        pattern = _normalize_escape_sequences(pattern)
+        replacement = _normalize_escape_sequences(replacement)
+
         # Handle line range targeting if specified
         search_content = content
         line_offset = 0
@@ -1889,16 +2037,31 @@ def edit_file(
         else:
             # Simple text replacement on search content
             count = search_content.count(pattern)
-            if count == 0:
+
+            # If exact match fails and flexible_whitespace is enabled, try flexible matching
+            if count == 0 and flexible_whitespace and '\n' in pattern:
+                # Convert pattern to regex with flexible leading whitespace per line
+                # Strategy: Replace each newline + whitespace with a regex that matches
+                # any amount of leading whitespace
+                flexible_result = _flexible_whitespace_match(
+                    pattern, replacement, search_content, max_replacements
+                )
+                if flexible_result is not None:
+                    updated_search_content, replacements_made = flexible_result
+                else:
+                    range_info = f" (lines {start_line}-{end_line})" if start_line is not None or end_line is not None else ""
+                    return f"No occurrences of '{pattern}' found in '{file_path}'{range_info}"
+            elif count == 0:
                 range_info = f" (lines {start_line}-{end_line})" if start_line is not None or end_line is not None else ""
                 return f"No occurrences of '{pattern}' found in '{file_path}'{range_info}"
-
-            if max_replacements == -1:
-                updated_search_content = search_content.replace(pattern, replacement)
-                replacements_made = count
             else:
-                updated_search_content = search_content.replace(pattern, replacement, max_replacements)
-                replacements_made = min(count, max_replacements)
+                # Exact match found
+                if max_replacements == -1:
+                    updated_search_content = search_content.replace(pattern, replacement)
+                    replacements_made = count
+                else:
+                    updated_search_content = search_content.replace(pattern, replacement, max_replacements)
+                    replacements_made = min(count, max_replacements)
 
         # Reconstruct the full file content if line ranges were used
         if start_line is not None or end_line is not None:
@@ -1988,7 +2151,6 @@ def edit_file(
         return f"❌ Error editing file: {str(e)}"
 
 
-
 @tool(
     description="Execute shell commands safely with security controls and platform detection",
     tags=["command", "shell", "execution", "system"],

abstractcore/tools/parser.py

@@ -148,10 +148,64 @@ def format_tool_prompt(tools: List[ToolDefinition], model_name: Optional[str] =
 
 # Internal helpers
 
+def _sanitize_tool_call_tags(response: str) -> str:
+    """
+    Sanitize malformed tool call tags before parsing.
+
+    Handles common LLM output malformations:
+    - Doubled opening tags: <|tool_call|><|tool_call|> → <|tool_call|>
+    - Doubled closing tags: </|tool_call|></|tool_call|> → </|tool_call|>
+    - Malformed closing with }: </|tool_call|} → </|tool_call|>
+
+    Args:
+        response: Raw model response text
+
+    Returns:
+        Sanitized response with normalized tool call syntax
+    """
+    if not response:
+        return response
+
+    original = response
+
+    # Fix doubled/multiple opening tags (collapse to single)
+    # Handles: <|tool_call|><|tool_call|> or <|tool_call|>\n<|tool_call|>
+    response = re.sub(
+        r'(<\|tool_call\|>\s*)+',
+        r'<|tool_call|>',
+        response,
+        flags=re.IGNORECASE
+    )
+
+    # Fix malformed closing tags with } instead of |>
+    # Handles: </|tool_call|} → </|tool_call|>
+    response = re.sub(
+        r'</\|tool_call\|\}',
+        r'</|tool_call|>',
+        response,
+        flags=re.IGNORECASE
+    )
+
+    # Fix doubled/multiple closing tags (collapse to single)
+    response = re.sub(
+        r'(</\|tool_call\|>\s*)+',
+        r'</|tool_call|>',
+        response,
+        flags=re.IGNORECASE
+    )
+
+    if response != original:
+        logger.debug(f"Sanitized malformed tool call tags")
+
+    return response
+
+
 def _get_tool_format(model_name: Optional[str]) -> ToolFormat:
     """Get tool format for a model."""
     if not model_name:
-        return ToolFormat.RAW_JSON
+        # When no model specified, use NATIVE which triggers _parse_any_format
+        # This ensures all formats are tried including <|tool_call|> special tokens
+        return ToolFormat.NATIVE
 
     architecture = detect_architecture(model_name)
     arch_format = get_architecture_format(architecture)
@@ -175,7 +229,10 @@ def _get_tool_format(model_name: Optional[str]) -> ToolFormat:
 def _parse_special_token(response: str) -> List[ToolCall]:
     """Parse Qwen-style <|tool_call|> format with robust fallback."""
     tool_calls = []
-    
+
+    # SANITIZE FIRST: Fix malformed tags (doubled tags, broken closing tags)
+    response = _sanitize_tool_call_tags(response)
+
     # Pre-process: Remove markdown code fences that might wrap tool calls
     # This handles cases like ```json\n<|tool_call|>...\n```
     cleaned_response = re.sub(r'```(?:json|python|tool_code|tool_call)?\s*\n', '', response, flags=re.IGNORECASE)
@@ -250,8 +307,40 @@ def _parse_special_token(response: str) -> List[ToolCall]:
             try:
                 tool_data = json.loads(json_str)
             except json.JSONDecodeError:
-                # Fallback: fix common LLM JSON issues (unescaped newlines)
-                fixed_json = json_str.replace('\n', '\\n').replace('\r', '\\r').replace('\t', '\\t')
+                # Fallback: Escape newlines/tabs only inside JSON string values
+                # This prevents escaping structural newlines which would break parsing
+                # Algorithm: Track when inside/outside strings, only escape within strings
+                in_string = False
+                escaped = False
+                fixed = []
+
+                for char in json_str:
+                    if escaped:
+                        # Previous char was backslash, this is part of escape sequence
+                        fixed.append(char)
+                        escaped = False
+                    elif char == '\\':
+                        # Start of escape sequence
+                        fixed.append(char)
+                        escaped = True
+                    elif char == '"':
+                        # Toggle string context
+                        in_string = not in_string
+                        fixed.append(char)
+                    elif in_string and char == '\n':
+                        # Newline inside string - escape it
+                        fixed.append('\\n')
+                    elif in_string and char == '\r':
+                        # CR inside string - escape it
+                        fixed.append('\\r')
+                    elif in_string and char == '\t':
+                        # Tab inside string - escape it
+                        fixed.append('\\t')
+                    else:
+                        # Normal character or structural whitespace
+                        fixed.append(char)
+
+                fixed_json = ''.join(fixed)
                 tool_data = json.loads(fixed_json)
 
             if isinstance(tool_data, dict):
@@ -424,6 +513,9 @@ def _parse_raw_json(response: str) -> List[ToolCall]:
 
 def _parse_any_format(response: str) -> List[ToolCall]:
     """Try all parsing formats with comprehensive fallbacks."""
+    # SANITIZE FIRST: Fix malformed tags before trying any parser
+    response = _sanitize_tool_call_tags(response)
+
     tool_calls = []
 
     # Try each parser and accumulate results

abstractcore/tools/registry.py

@@ -6,6 +6,7 @@ and executing them safely.
 """
 
 import time
+import warnings
 from typing import Dict, List, Any, Callable, Optional, Union
 from functools import wraps
 
@@ -270,6 +271,12 @@ def register_tool(tool: Union[ToolDefinition, Callable]) -> ToolDefinition:
     Returns:
         The registered ToolDefinition
     """
+    warnings.warn(
+        "Global tool registration is deprecated. Prefer passing tools explicitly to generate() "
+        "and executing tool calls via a host-configured ToolExecutor.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
     return _global_registry.register(tool)
 
 
@@ -308,19 +315,11 @@ def clear_registry():
     return _global_registry.clear()
 
 
-def tool(func: Callable) -> Callable:
-    """
-    Decorator to register a function as a tool.
-
-    Args:
-        func: Function to register as a tool
-
-    Returns:
-        The original function (unchanged)
-    """
-    register_tool(func)
-    return func
-
-
-# Convenience decorator alias
-register = tool
+__all__ = [
+    "ToolRegistry",
+    "get_registry",
+    "register_tool",
+    "execute_tool",
+    "execute_tools",
+    "clear_registry",
+]

abstractcore/utils/version.py

@@ -11,4 +11,4 @@ including when the package is installed from PyPI where pyproject.toml is not av
 
 # Package version - update this when releasing new versions
 # This must be manually synchronized with the version in pyproject.toml
-__version__ = "2.6.6"
+__version__ = "2.6.8"

abstractcore/utils/vlm_token_calculator.py

@@ -24,12 +24,7 @@ from typing import Tuple, Dict, Any, Optional, List
 from pathlib import Path
 import logging
 
-try:
-    from PIL import Image
-except ImportError as e:
-    raise ImportError(
-        "PIL (Pillow) is required for VLM token calculation. Install with: pip install Pillow"
-    ) from e
+from PIL import Image
 
 from ..utils.structured_logging import get_logger
 from ..architectures.detection import get_model_capabilities, detect_architecture

{abstractcore-2.6.6.dist-info → abstractcore-2.6.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.6.6
+Version: 2.6.8
 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>
@@ -30,6 +30,7 @@ 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
+Requires-Dist: Pillow<12.0.0,>=10.0.0
 Provides-Extra: openai
 Requires-Dist: openai<2.0.0,>=1.0.0; extra == "openai"
 Provides-Extra: anthropic
@@ -194,6 +195,50 @@ response = llm.generate(
 print(response.content)
 ```
 
+### Tool Execution Modes
+
+AbstractCore supports two tool execution modes:
+
+**Mode 1: Passthrough (Default)** - Returns raw tool call tags for downstream processing
+
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool
+
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny, 22°C"
+
+llm = create_llm("ollama", model="qwen3:4b")  # execute_tools=False by default
+response = llm.generate("What's the weather in Paris?", tools=[get_weather])
+# response.content contains raw tool call tags: <|tool_call|>...
+# Downstream runtime (AbstractRuntime, Codex, Claude Code) parses and executes
+```
+
+**Use case**: Agent loops, AbstractRuntime, Codex, Claude Code, custom orchestration
+
+**Mode 2: Direct Execution** - AbstractCore executes tools and returns results
+
+```python
+from abstractcore import create_llm
+from abstractcore.tools import tool
+from abstractcore.tools.registry import register_tool
+
+@tool(name="get_weather", description="Get weather for a city")
+def get_weather(city: str) -> str:
+    return f"Weather in {city}: Sunny, 22°C"
+
+register_tool(get_weather)  # Required for direct execution
+
+llm = create_llm("ollama", model="qwen3:4b", execute_tools=True)
+response = llm.generate("What's the weather in Paris?", tools=[get_weather])
+# response.content contains executed tool results
+```
+
+**Use case**: Simple scripts, single-turn tool use
+
+> **Note**: The `@tool` decorator creates metadata but does NOT register globally. Tools are passed explicitly to `generate()`. Use `register_tool()` only when using direct execution mode.
+
 ### Response Object (GenerateResponse)
 
 Every LLM generation returns a **GenerateResponse** object with consistent structure across all providers:

{abstractcore-2.6.6.dist-info → abstractcore-2.6.8.dist-info}/RECORD

@@ -12,7 +12,7 @@ abstractcore/architectures/__init__.py,sha256=-4JucAM7JkMWShWKkePoclxrUHRKgaG36U
 abstractcore/architectures/detection.py,sha256=jmpD04xcKotWCW7--jadBzCtD2a5dYJi1zljpxB9JmU,19813
 abstractcore/architectures/enums.py,sha256=9vIv2vDBEKhxwzwH9iaSAyf-iVj3p8y9loMeN_mYTJ8,3821
 abstractcore/assets/architecture_formats.json,sha256=Yf-W1UuadrL8qid0pfU_pEBOkjwH4lvx7Nzu83GACp8,16622
-abstractcore/assets/model_capabilities.json,sha256=tmfQNNPTNJAauF51nPYkMqcjc17F2geeYngh0HjEUZ0,68836
+abstractcore/assets/model_capabilities.json,sha256=d3rC-nqXJ5LDeG0MWEcODcyEqzF4A8FWe27fNcCBBPY,69235
 abstractcore/assets/session_schema.json,sha256=hMCVrq3KSyVExrMGzuykf7bU-z6WyIVuEGU8du9_zUY,10570
 abstractcore/compression/__init__.py,sha256=svwaHCHoLkKp1IJKdlSC72k6b8vOUOqVF-Yek8ZHwj8,915
 abstractcore/compression/analytics.py,sha256=3orxJkjjMQE_6mID8_8C0sRQ4Gr2Pw7kQ-Iy0p7pIgM,16042
@@ -60,16 +60,16 @@ abstractcore/media/processors/office_processor.py,sha256=_aTrrDtREiy6MivbANFc1FK
 abstractcore/media/processors/pdf_processor.py,sha256=qniYt7cTYYPVRi_cS1IsXztOldeY0bqdn7sdbELBU9k,17157
 abstractcore/media/processors/text_processor.py,sha256=D84QWxxIou4MeNhERmCTxi_p27CgicVFhMXJiujZgIE,21905
 abstractcore/media/utils/__init__.py,sha256=30-CTif91iRKOXJ4njGiduWAt-xp31U7NafMBNvgdO0,460
-abstractcore/media/utils/image_scaler.py,sha256=RWE2kPeURLEtJDK-Qs4KvZKtu-GkMLziFL9Vc9-aWjc,11388
-abstractcore/processing/__init__.py,sha256=QcACEnhnHKYCkFL1LNOW_uqBrwkTAmz5A61N4K2dyu0,988
+abstractcore/media/utils/image_scaler.py,sha256=uUVF91_mLTt-PR0LZiDawTolE2qIrTG1rzV9oYVbxhg,11171
+abstractcore/processing/__init__.py,sha256=T9DPd6iLo06opJ2DrUIjmqGhYcvvYNTfuOp0DNEoU5Q,1024
 abstractcore/processing/basic_deepsearch.py,sha256=dzJQtH4k44XY9tvG0Z4JIlYt_s7HpbLdSPScha-t7vk,101036
 abstractcore/processing/basic_extractor.py,sha256=3x-3BdIHgLvqLnLF6K1-P4qVaLIpAnNIIutaJi7lDQM,49832
 abstractcore/processing/basic_intent.py,sha256=wD99Z7fE2RiYk6oyTZXojUbv-bz8HhKFIuIHYLLTw54,32455
 abstractcore/processing/basic_judge.py,sha256=L1fc9H0-_88B1TULL-mlaNL7OydMgp-ru_zzzoGdr38,37220
-abstractcore/processing/basic_summarizer.py,sha256=XHNxMQ_8aLStTeUo6_2JaThlct12Htpz7ORmm0iuJsg,25495
+abstractcore/processing/basic_summarizer.py,sha256=XYAKpsOiqVGt1Rl9K6Uaa3YyANc-zSvqD4qH0KAnffM,28603
 abstractcore/providers/__init__.py,sha256=dNz-KrUwpBZhEv6DkAe3t_V8w40_HjeME5j9VL0lDyo,1886
 abstractcore/providers/anthropic_provider.py,sha256=0-qZb0Es6-VLuVVl2j7IUjOuyRlgjQdJFulWfpi4qb4,31740
-abstractcore/providers/base.py,sha256=nWF1pxeUlT4ozlUqKG0rWOmLkfo-zQgfU7fv3AUSI08,68452
+abstractcore/providers/base.py,sha256=yP75mfBW_SM7IEcMO_Sl-zeNq-IjzJWzYq-ouMOyRQs,69402
 abstractcore/providers/huggingface_provider.py,sha256=v4UUmODrnWKtTygzPh-lm4jSCAPms5VYJE5v7PWB4Lo,79458
 abstractcore/providers/lmstudio_provider.py,sha256=92_vx7AVVt_oufJdHo3R0D_V2qyTKO2DKzi9-l4KzWs,34114
 abstractcore/providers/mlx_provider.py,sha256=afLCEwuw7r8OK4fD3OriyKMcWpxVIob_37ItmgAclfc,23123
@@ -81,16 +81,16 @@ abstractcore/providers/registry.py,sha256=gz2fu3m7EVYHWy9Lggbmjh46abrdnxC3_73ccI
 abstractcore/providers/streaming.py,sha256=HaGkoItPWXqgml3C-KiPc0hBNpztLzjl_ooECw11BHI,31370
 abstractcore/providers/vllm_provider.py,sha256=zl1utRG-G__Qh5UpgIEU-Dbb6w5LeZfiboBUC5aPeL0,33969
 abstractcore/server/__init__.py,sha256=1DSAz_YhQtnKv7sNi5TMQV8GFujctDOabgvAdilQE0o,249
-abstractcore/server/app.py,sha256=AYupb0rlmf4-L9xDb7qHVLdUi8lGC-jYgg1Pe_AvZ3o,97507
+abstractcore/server/app.py,sha256=XQueggO5TtkhhxLaVQQ7pxpIPbh4QqB6NcwQ9GJwzAQ,99418
 abstractcore/structured/__init__.py,sha256=VXRQHGcm-iaYnLOBPin2kyhvhhQA0kaGt_pcNDGsE_8,339
 abstractcore/structured/handler.py,sha256=hcUe_fZcwx0O3msLqFiOsj6-jbq3S-ZQa9c1nRIZvuo,24622
 abstractcore/structured/retry.py,sha256=BN_PvrWybyU1clMy2cult1-TVxFSMaVqiCPmmXvA5aI,3805
-abstractcore/tools/__init__.py,sha256=oh6vG0RdM1lqUtOp95mLrTsWLh9VmhJf5_FVjGIP5_M,2259
-abstractcore/tools/common_tools.py,sha256=hn4Y-HmpYAH3nLnKqJayWr-mpou3T5Ixu-LRdeO1_c4,95161
+abstractcore/tools/__init__.py,sha256=JPPLRLMnwJorbudHL3sWZrJVKA_IHuZLnOGrpHYliGY,3034
+abstractcore/tools/common_tools.py,sha256=zSE5H8PkOQ3SHYi9-srmfnTlkl9jWoKc0TEq9G53ibc,102148
 abstractcore/tools/core.py,sha256=lUUGihyceiRYlKUFvEMig9jWFF563d574mSDbYYD3fM,4777
 abstractcore/tools/handler.py,sha256=nBbbBNq029s8pV6NbTU-VmQ6xoSTdt7Af1-XbcMdgU4,12050
-abstractcore/tools/parser.py,sha256=AYM0-baSGGGdwd_w2My3B3sOiw2flE2x59mLmdpwJ0A,27768
-abstractcore/tools/registry.py,sha256=eI0qKrauT1PzLIfaporXCjBMojmWYzgfd96xdN_Db1g,9087
+abstractcore/tools/parser.py,sha256=Otn1rL2JVTN87CYQuLdXlSM1wTW_Juf2PMsDCJpYzuw,30979
+abstractcore/tools/registry.py,sha256=2C8zNJqVQwBnmnkWogvnNwCktJIBvdo4lA9W5HxJtm8,9184
 abstractcore/tools/syntax_rewriter.py,sha256=_lBvIJ_gFleR5JZI0UuukQ47pe5CXp3IM9Oee0ypx60,17346
 abstractcore/tools/tag_rewriter.py,sha256=2hjLoIjVs4277mPBSrNsnxLOVvmXm83xtF0WCOU3uno,20350
 abstractcore/utils/__init__.py,sha256=8uvIU1WpUfetvWA90PPvXtxnFNjMQF0umb8_FuK2cTA,779
@@ -100,11 +100,11 @@ abstractcore/utils/self_fixes.py,sha256=1VYxPq-q7_DtNl39NbrzUmyHpkhb9Q2SdnXUj4c0
 abstractcore/utils/structured_logging.py,sha256=Vm-HviSa42G9DJCWmaEv4a0QG3NMsADD3ictLOs4En0,19952
 abstractcore/utils/token_utils.py,sha256=eLwFmJ68p9WMFD_MHLMmeJRW6Oqx_4hKELB8FNQ2Mnk,21097
 abstractcore/utils/trace_export.py,sha256=MD1DHDWltpewy62cYzz_OSPAA6edZbZq7_pZbvxz_H8,9279
-abstractcore/utils/version.py,sha256=Z8uyHNTgXcYjIz0T3S0B0d_LcOXgKpyd_2WS8Rg3MtU,605
-abstractcore/utils/vlm_token_calculator.py,sha256=pIDc_iwJ4IrM_e8AxY2HDU8UdTYitBOXVhu0F-EaMTY,28144
-abstractcore-2.6.6.dist-info/licenses/LICENSE,sha256=PI2v_4HMvd6050uDD_4AY_8PzBnu2asa3RKbdDjowTA,1078
-abstractcore-2.6.6.dist-info/METADATA,sha256=Z4_SfHiSDLDXMDGLWdsd7cZASoZg2DtXgCQfnjrB6HA,45799
-abstractcore-2.6.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-abstractcore-2.6.6.dist-info/entry_points.txt,sha256=jXNdzeltVs23A2JM2e2HOiAHldHrsnud3EvPI5VffOs,658
-abstractcore-2.6.6.dist-info/top_level.txt,sha256=DiNHBI35SIawW3N9Z-z0y6cQYNbXd32pvBkW0RLfScs,13
-abstractcore-2.6.6.dist-info/RECORD,,
+abstractcore/utils/version.py,sha256=BjFWFsKdU0RCZy3o-rumfIgdOnuCfs0EPAMpSfaof5Y,605
+abstractcore/utils/vlm_token_calculator.py,sha256=KMhV97gYpiWHYNnPR5yFLw6eA1CPKQ1c-ihPdns72Wg,27979
+abstractcore-2.6.8.dist-info/licenses/LICENSE,sha256=PI2v_4HMvd6050uDD_4AY_8PzBnu2asa3RKbdDjowTA,1078
+abstractcore-2.6.8.dist-info/METADATA,sha256=oSh7ayXP7hwFd83EqAWpmBnkB9PI8of1TWmaudzVYY0,47485
+abstractcore-2.6.8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+abstractcore-2.6.8.dist-info/entry_points.txt,sha256=jXNdzeltVs23A2JM2e2HOiAHldHrsnud3EvPI5VffOs,658
+abstractcore-2.6.8.dist-info/top_level.txt,sha256=DiNHBI35SIawW3N9Z-z0y6cQYNbXd32pvBkW0RLfScs,13
+abstractcore-2.6.8.dist-info/RECORD,,