abstractcore 2.6.9__py3-none-any.whl → 2.9.1__py3-none-any.whl

abstractcore/providers/vllm_provider.py

@@ -59,7 +59,16 @@ class VLLMProvider(BaseProvider):
             self.client = httpx.Client(timeout=timeout_value)
         except Exception as e:
             try:
-                self.client = httpx.Client(timeout=300.0)
+                fallback_timeout = None
+                try:
+                    from ..config.manager import get_config_manager
+
+                    fallback_timeout = float(get_config_manager().get_default_timeout())
+                except Exception:
+                    fallback_timeout = 7200.0
+                if isinstance(fallback_timeout, (int, float)) and float(fallback_timeout) <= 0:
+                    fallback_timeout = None
+                self.client = httpx.Client(timeout=fallback_timeout)
             except Exception:
                 raise RuntimeError(f"Failed to create HTTP client for vLLM: {e}")
 
@@ -154,19 +163,24 @@ class VLLMProvider(BaseProvider):
         chat_messages = []
 
         # Add tools to system prompt if provided
-        enhanced_system_prompt = system_prompt
-        if tools and self.tool_handler.supports_prompted:
-            tool_prompt = self.tool_handler.format_tools_prompt(tools)
-            if enhanced_system_prompt:
-                enhanced_system_prompt += f"\n\n{tool_prompt}"
+        final_system_prompt = system_prompt
+        # Prefer native tools when the model supports them. Only inject a prompted tool list
+        # when native tool calling is not available.
+        if tools and self.tool_handler.supports_prompted and not self.tool_handler.supports_native:
+            include_tool_list = True
+            if final_system_prompt and "## Tools (session)" in final_system_prompt:
+                include_tool_list = False
+            tool_prompt = self.tool_handler.format_tools_prompt(tools, include_tool_list=include_tool_list)
+            if final_system_prompt:
+                final_system_prompt += f"\n\n{tool_prompt}"
             else:
-                enhanced_system_prompt = tool_prompt
+                final_system_prompt = tool_prompt
 
         # Add system message if provided
-        if enhanced_system_prompt:
+        if final_system_prompt:
             chat_messages.append({
                 "role": "system",
-                "content": enhanced_system_prompt
+                "content": final_system_prompt
             })
 
         # Add conversation history
@@ -222,6 +236,11 @@ class VLLMProvider(BaseProvider):
             "top_p": kwargs.get("top_p", 0.9),
         }
 
+        # Native tools (OpenAI-compatible): send structured tools/tool_choice when supported.
+        if tools and self.tool_handler.supports_native:
+            payload["tools"] = self.tool_handler.prepare_tools_for_native(tools)
+            payload["tool_choice"] = kwargs.get("tool_choice", "auto")
+
         # Add additional generation parameters if provided
         if "frequency_penalty" in kwargs:
             payload["frequency_penalty"] = kwargs["frequency_penalty"]
@@ -283,8 +302,9 @@ class VLLMProvider(BaseProvider):
                 raise ProviderAPIError("HTTP client not initialized")
 
             start_time = time.time()
+            request_url = f"{self.base_url}/chat/completions"
             response = self.client.post(
-                f"{self.base_url}/chat/completions",
+                request_url,
                 json=payload,
                 headers=self._get_headers()
             )
@@ -296,10 +316,18 @@ class VLLMProvider(BaseProvider):
             # Extract response from OpenAI format
             if "choices" in result and len(result["choices"]) > 0:
                 choice = result["choices"][0]
-                content = choice.get("message", {}).get("content", "")
+                message = choice.get("message") or {}
+                if not isinstance(message, dict):
+                    message = {}
+
+                content = message.get("content", "")
+                tool_calls = message.get("tool_calls")
+                if tool_calls is None:
+                    tool_calls = choice.get("tool_calls")
                 finish_reason = choice.get("finish_reason", "stop")
             else:
                 content = "No response generated"
+                tool_calls = None
                 finish_reason = "error"
 
             # Extract usage info
@@ -310,6 +338,13 @@ class VLLMProvider(BaseProvider):
                 model=self.model,
                 finish_reason=finish_reason,
                 raw_response=result,
+                tool_calls=tool_calls if isinstance(tool_calls, list) else None,
+                metadata={
+                    "_provider_request": {
+                        "url": request_url,
+                        "payload": payload,
+                    }
+                },
                 usage={
                     "input_tokens": usage.get("prompt_tokens", 0),
                     "output_tokens": usage.get("completion_tokens", 0),
@@ -335,7 +370,7 @@ class VLLMProvider(BaseProvider):
                 except Exception:
                     raise ModelNotFoundError(f"Model '{self.model}' not found in vLLM and could not fetch available models")
             else:
-                raise ProviderAPIError(f"vLLM API error: {str(e)}")
+                raise
 
     def _stream_generate(self, payload: Dict[str, Any]) -> Iterator[GenerateResponse]:
         """Generate streaming response."""
@@ -366,13 +401,17 @@ class VLLMProvider(BaseProvider):
                                 if "choices" in chunk and len(chunk["choices"]) > 0:
                                     choice = chunk["choices"][0]
                                     delta = choice.get("delta", {})
+                                    if not isinstance(delta, dict):
+                                        delta = {}
                                     content = delta.get("content", "")
+                                    tool_calls = delta.get("tool_calls") or choice.get("tool_calls")
                                     finish_reason = choice.get("finish_reason")
 
                                     yield GenerateResponse(
                                         content=content,
                                         model=self.model,
                                         finish_reason=finish_reason,
+                                        tool_calls=tool_calls if isinstance(tool_calls, list) else None,
                                         raw_response=chunk
                                     )
 
@@ -408,16 +447,20 @@ class VLLMProvider(BaseProvider):
         # Build messages (same logic as sync)
         chat_messages = []
 
-        enhanced_system_prompt = system_prompt
-        if tools and self.tool_handler.supports_prompted:
-            tool_prompt = self.tool_handler.format_tools_prompt(tools)
-            if enhanced_system_prompt:
-                enhanced_system_prompt += f"\n\n{tool_prompt}"
+        final_system_prompt = system_prompt
+        # Prefer native tools when available; only inject prompted tool syntax as fallback.
+        if tools and self.tool_handler.supports_prompted and not self.tool_handler.supports_native:
+            include_tool_list = True
+            if final_system_prompt and "## Tools (session)" in final_system_prompt:
+                include_tool_list = False
+            tool_prompt = self.tool_handler.format_tools_prompt(tools, include_tool_list=include_tool_list)
+            if final_system_prompt:
+                final_system_prompt += f"\n\n{tool_prompt}"
             else:
-                enhanced_system_prompt = tool_prompt
+                final_system_prompt = tool_prompt
 
-        if enhanced_system_prompt:
-            chat_messages.append({"role": "system", "content": enhanced_system_prompt})
+        if final_system_prompt:
+            chat_messages.append({"role": "system", "content": final_system_prompt})
 
         if messages:
             chat_messages.extend(messages)
@@ -469,6 +512,11 @@ class VLLMProvider(BaseProvider):
             "top_p": kwargs.get("top_p", 0.9),
         }
 
+        # Native tools (OpenAI-compatible): send structured tools/tool_choice when supported.
+        if tools and self.tool_handler.supports_native:
+            payload["tools"] = self.tool_handler.prepare_tools_for_native(tools)
+            payload["tool_choice"] = kwargs.get("tool_choice", "auto")
+
         if "frequency_penalty" in kwargs:
             payload["frequency_penalty"] = kwargs["frequency_penalty"]
         if "presence_penalty" in kwargs:
@@ -700,7 +748,16 @@ class VLLMProvider(BaseProvider):
                 if hasattr(self, 'logger'):
                     self.logger.warning(f"Failed to update HTTP client timeout: {e}")
                 try:
-                    self.client = httpx.Client(timeout=300.0)
+                    fallback_timeout = None
+                    try:
+                        from ..config.manager import get_config_manager
+
+                        fallback_timeout = float(get_config_manager().get_default_timeout())
+                    except Exception:
+                        fallback_timeout = 7200.0
+                    if isinstance(fallback_timeout, (int, float)) and float(fallback_timeout) <= 0:
+                        fallback_timeout = None
+                    self.client = httpx.Client(timeout=fallback_timeout)
                 except Exception:
                     pass
 

abstractcore/server/app.py

@@ -517,6 +517,16 @@ class ChatCompletionRequest(BaseModel):
         example="http://localhost:1234/v1"
     )
 
+    # Runtime/orchestrator policy (AbstractCore-specific feature)
+    timeout_s: Optional[float] = Field(
+        default=None,
+        description="Per-request provider HTTP timeout in seconds (AbstractCore-specific feature). "
+                    "Intended for orchestrators (e.g. AbstractRuntime) to enforce execution policy. "
+                    "If omitted, the server uses its own defaults. "
+                    "Values <= 0 are treated as unlimited.",
+        example=7200.0,
+    )
+
     class Config:
         schema_extra = {
             "examples": {
@@ -1956,6 +1966,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 +2062,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(
@@ -2026,6 +2074,10 @@ async def process_chat_completion(
                 request_id=request_id,
                 base_url=request.base_url
             )
+        if request.timeout_s is not None:
+            # Orchestrator policy: allow the caller to specify the provider timeout.
+            # Note: BaseProvider treats non-positive values as "unlimited".
+            provider_kwargs["timeout"] = request.timeout_s
 
         llm = create_llm(provider, model=model, **provider_kwargs)
 
@@ -2047,6 +2099,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 +2135,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
@@ -2165,31 +2228,49 @@ def generate_streaming_response(
                     }
                     yield f"data: {json.dumps(openai_chunk)}\n\n"
 
-            # Tool calls - always convert to OpenAI format for streaming
+            # Tool calls
             if hasattr(chunk, 'tool_calls') and chunk.tool_calls:
                 has_tool_calls = True
-                openai_tool_calls = syntax_rewriter.convert_to_openai_format(chunk.tool_calls)
-
-                for i, openai_tool_call in enumerate(openai_tool_calls):
-                    tool_chunk = {
-                        "id": chat_id,
-                        "object": "chat.completion.chunk",
-                        "created": created_time,
-                        "model": f"{provider}/{model}",
-                        "choices": [{
-                            "index": 0,
-                            "delta": {
-                                "tool_calls": [{
-                                    "index": i,  # Proper indexing for multiple tools
-                                    "id": openai_tool_call["id"],
-                                    "type": "function",
-                                    "function": openai_tool_call["function"]
-                                }]
-                            },
-                            "finish_reason": "tool_calls"  # Critical for Codex
-                        }]
-                    }
-                    yield f"data: {json.dumps(tool_chunk)}\n\n"
+                # OpenAI/Codex clients expect structured tool_calls deltas.
+                if syntax_rewriter.target_format in [SyntaxFormat.OPENAI, SyntaxFormat.CODEX]:
+                    openai_tool_calls = syntax_rewriter.convert_to_openai_format(chunk.tool_calls)
+
+                    for i, openai_tool_call in enumerate(openai_tool_calls):
+                        tool_chunk = {
+                            "id": chat_id,
+                            "object": "chat.completion.chunk",
+                            "created": created_time,
+                            "model": f"{provider}/{model}",
+                            "choices": [{
+                                "index": 0,
+                                "delta": {
+                                    "tool_calls": [{
+                                        "index": i,  # Proper indexing for multiple tools
+                                        "id": openai_tool_call["id"],
+                                        "type": "function",
+                                        "function": openai_tool_call["function"]
+                                    }]
+                                },
+                                "finish_reason": "tool_calls"  # Critical for Codex
+                            }]
+                        }
+                        yield f"data: {json.dumps(tool_chunk)}\n\n"
+                # Tag-based clients parse tool calls from assistant content.
+                elif syntax_rewriter.target_format != SyntaxFormat.PASSTHROUGH:
+                    tool_text = syntax_rewriter.rewrite_content("", detected_tool_calls=chunk.tool_calls)
+                    if tool_text and tool_text.strip():
+                        openai_chunk = {
+                            "id": chat_id,
+                            "object": "chat.completion.chunk",
+                            "created": created_time,
+                            "model": f"{provider}/{model}",
+                            "choices": [{
+                                "index": 0,
+                                "delta": {"content": tool_text},
+                                "finish_reason": None
+                            }]
+                        }
+                        yield f"data: {json.dumps(openai_chunk)}\n\n"
 
         # Final chunk
         final_chunk = {
@@ -2270,6 +2351,7 @@ def convert_to_openai_response(
 
     # Apply syntax rewriting to content
     content = response.content if hasattr(response, 'content') else str(response)
+    tool_calls = getattr(response, "tool_calls", None) if hasattr(response, "tool_calls") else None
 
     # For OpenAI/Codex format: only clean if content contains tool calls
     # For other formats: apply syntax rewriting
@@ -2279,8 +2361,12 @@ def convert_to_openai_response(
         if any(pattern in content for pattern in ['<function_call>', '<tool_call>', '<|tool_call|>', '```tool_code']):
             content = syntax_rewriter.remove_tool_call_patterns(content)
     elif syntax_rewriter.target_format != SyntaxFormat.PASSTHROUGH:
-        # Apply format-specific rewriting for non-OpenAI formats
-        content = syntax_rewriter.rewrite_content(content)
+        # Apply format-specific rewriting for non-OpenAI formats.
+        # Prefer structured tool_calls when present (content may be cleaned upstream).
+        if tool_calls:
+            content = syntax_rewriter.rewrite_content(content, detected_tool_calls=tool_calls)
+        else:
+            content = syntax_rewriter.rewrite_content(content)
 
     response_dict = {
         "id": f"chatcmpl-{uuid.uuid4().hex[:8]}",
@@ -2300,15 +2386,15 @@ def convert_to_openai_response(
     }
 
     # Add tool calls if present
-    if hasattr(response, 'tool_calls') and response.tool_calls:
-        openai_tool_calls = syntax_rewriter.convert_to_openai_format(response.tool_calls)
+    if tool_calls:
+        openai_tool_calls = syntax_rewriter.convert_to_openai_format(tool_calls)
         response_dict["choices"][0]["message"]["tool_calls"] = openai_tool_calls
         response_dict["choices"][0]["finish_reason"] = "tool_calls"
 
         logger.info(
             "🔧 Tool calls converted",
             request_id=request_id,
-            tool_count=len(response.tool_calls),
+            tool_count=len(tool_calls),
             target_format=syntax_rewriter.target_format.value
         )
 
@@ -2408,4 +2494,4 @@ Debug Mode:
 # ============================================================================
 
 if __name__ == "__main__":
-    run_server_with_args()
+    run_server_with_args()

abstractcore/structured/retry.py

@@ -62,17 +62,20 @@ class FeedbackRetry(Retry):
 
     def should_retry(self, attempt: int, error: Exception) -> bool:
         """
-        Retry only for Pydantic ValidationErrors and within attempt limit.
+        Retry for structured-output errors that the model can often self-correct:
+        - Pydantic ValidationError (schema mismatch)
+        - JSONDecodeError (not valid JSON at all)
         """
-        return isinstance(error, ValidationError) and attempt < self.max_attempts
+        return isinstance(error, (ValidationError, json.JSONDecodeError)) and attempt < self.max_attempts
 
-    def prepare_retry_prompt(self, original_prompt: str, error: ValidationError, attempt: int) -> str:
+    def prepare_retry_prompt(self, original_prompt: str, error: Exception, attempt: int) -> str:
         """
         Create a retry prompt with validation error feedback.
         """
-        error_feedback = self._format_validation_errors(error)
+        if isinstance(error, ValidationError):
+            error_feedback = self._format_validation_errors(error)
 
-        retry_prompt = f"""{original_prompt}
+            retry_prompt = f"""{original_prompt}
 
 IMPORTANT: Your previous response (attempt {attempt}) had validation errors:
 
@@ -80,7 +83,17 @@ IMPORTANT: Your previous response (attempt {attempt}) had validation errors:
 
 Please correct these errors and provide a valid JSON response that matches the required schema exactly."""
 
-        return retry_prompt
+            return retry_prompt
+
+        # JSONDecodeError (or other JSON parsing issues): retry with a simpler instruction.
+        return f"""{original_prompt}
+
+IMPORTANT: Your previous response (attempt {attempt}) was not valid JSON:
+
+{error}
+
+Please respond again with a single valid JSON object that matches the required schema exactly.
+Return ONLY the JSON object, with no additional text or formatting."""
 
     def _format_validation_errors(self, error: ValidationError) -> str:
         """
@@ -113,4 +126,4 @@ Please correct these errors and provide a valid JSON response that matches the r
             else:
                 error_lines.append(f"• Field '{field_path}': {error_msg}")
 
-        return "\n".join(error_lines)
+        return "\n".join(error_lines)

abstractcore/tools/__init__.py

@@ -4,42 +4,64 @@ 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
+    AbstractCore detects/parses tool calls (native API fields or prompted tags)
+    and returns structured `GenerateResponse.tool_calls` plus cleaned `content`.
+    Downstream runtimes (AbstractRuntime, Codex, Claude Code) execute tools.
+    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.tool_calls contains structured tool calls; response.content is cleaned
+```
 
-# 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
@@ -98,4 +120,4 @@ __all__ = [
     "execute_tool",
     "execute_tools",
     "clear_registry",
-]
+]