vectara-agentic 0.4.7__py3-none-any.whl → 0.4.9__py3-none-any.whl

vectara_agentic/agent_core/streaming.py

@@ -42,6 +42,35 @@ def get_event_id(event) -> str:
 
     return str(uuid.uuid4())
 
+
+def is_tool_related_event(event) -> bool:
+    """
+    Determine if an event is actually tool-related and should be tracked.
+
+    This should only return True for events that represent actual tool calls or tool outputs,
+    not for streaming text deltas or other LLM response events.
+
+    Args:
+        event: The stream event to check
+
+    Returns:
+        bool: True if this event should be tracked for tool purposes
+    """
+    # Track explicit tool events from LlamaIndex workflow
+    if isinstance(event, (ToolCall, ToolCallResult)):
+        return True
+
+    has_tool_id = getattr(event, "tool_id", None)
+    has_tool_name = getattr(event, "tool_name", None)
+    has_delta = getattr(event, "delta", None)
+
+    # Some providers don't emit ToolCall/ToolCallResult; avoid treating deltas as tool events
+    if (has_tool_id or has_tool_name) and not has_delta:
+        return True
+
+    return False
+
+
 class StreamingResponseAdapter:
     """
     Adapter class that provides a LlamaIndex-compatible streaming response interface.
@@ -90,25 +119,6 @@ class StreamingResponseAdapter:
         """
         return AgentResponse(response=self.response, metadata=self.metadata)
 
-    def wait_for_completion(self) -> None:
-        """
-        Wait for post-processing to complete and update metadata.
-        This should be called after streaming finishes but before accessing metadata.
-        """
-        if self.post_process_task and not self.post_process_task.done():
-            return
-        if self.post_process_task and self.post_process_task.done():
-            try:
-                final_response = self.post_process_task.result()
-                if hasattr(final_response, "metadata") and final_response.metadata:
-                    # Update our metadata from the completed task
-                    self.metadata.update(final_response.metadata)
-            except Exception as e:
-                logging.error(
-                    f"Error during post-processing: {e}. "
-                    "Ensure the post-processing task is correctly implemented."
-                )
-
 
 def extract_response_text_from_chat_message(response_text: Any) -> str:
     """
@@ -123,15 +133,15 @@ def extract_response_text_from_chat_message(response_text: Any) -> str:
         str: Extracted text content
     """
     # Handle case where response is a ChatMessage object
-    if hasattr(response_text, "content"):
-        return response_text.content
-    elif hasattr(response_text, "blocks"):
+    if hasattr(response_text, "blocks"):
         # Extract text from ChatMessage blocks
         text_parts = []
         for block in response_text.blocks:
             if hasattr(block, "text"):
                 text_parts.append(block.text)
         return "".join(text_parts)
+    elif hasattr(response_text, "content"):
+        return response_text.content
     elif not isinstance(response_text, str):
         return str(response_text)
 
@@ -234,9 +244,8 @@ def create_stream_post_processing_task(
     async def _safe_post_process():
         try:
             return await _post_process()
-        except Exception:
-            traceback.print_exc()
-            # Return empty response on error
+        except Exception as e:
+            logging.error(f"Error {e} occurred during post-processing: {traceback.format_exc()}")
             return AgentResponse(response="", metadata={})
 
     return asyncio.create_task(_safe_post_process())
@@ -244,205 +253,203 @@ def create_stream_post_processing_task(
 
 class FunctionCallingStreamHandler:
     """
-    Handles streaming for function calling agents with proper event processing.
+    Streaming handler for function-calling agents with strict "no leaks" gating.
+
+    Core ideas:
+    - Buffer tokens PER LLM STEP.
+    - Commit the buffer ONLY if that step ends with AgentOutput.tool_calls == [].
+    - Drop the buffer if the step triggers tool calls (planning/tool-selection).
+    - Track pending tool results; handle multi-round (tool -> read -> tool -> ...) loops.
+    - Support return_direct tools (tool output is the final answer, no synthesis step).
+    - Two streaming modes:
+      - final_only: Buffer all tokens and commit only after step completes with no tool calls
+      - optimistic_live: Stream tokens live after all tool calls are complete
     """
 
-    def __init__(self, agent_instance, handler, prompt: str):
+    def __init__(
+        self,
+        agent_instance,
+        handler,
+        prompt: str,
+        *,
+        stream_policy: str = "optimistic_live",            # "final_only" | "optimistic_live"
+    ):
         self.agent_instance = agent_instance
-        self.handler = handler
+        self.handler = handler  # awaitable; also has .stream_events()
         self.prompt = prompt
+
+        self.stream_policy = stream_policy
+
+        # Plumbing for your existing adapter/post-processing
         self.final_response_container = {"resp": None}
         self.stream_complete_event = asyncio.Event()
 
     async def process_stream_events(self) -> AsyncIterator[str]:
         """
-        Process streaming events and yield text tokens.
+        Process streaming events and yield only valid, final tokens.
 
-        Yields:
-            str: Text tokens from the streaming response
+        Contract:
+        - Never surface "planning" tokens (tool arguments, scratchpads, etc).
+        - Only surface tokens produced in the last, post-tool LLM step,
+          or a return_direct tool's output.
         """
-        had_tool_calls = False
-        transitioned_to_prose = False
+        # Step-scoped state
+        step_buffer: list[str] = []
+        step_has_tool_calls = False
+
+        # Run-scoped state
+        pending_tools = 0
+        committed_any_text = False
+
+        def _reset_step():
+            nonlocal step_has_tool_calls
+            step_buffer.clear()
+            step_has_tool_calls = False
 
         async for ev in self.handler.stream_events():
-            # Store tool outputs for VHC regardless of progress callback
+            # ---- 1) Capture tool outputs for downstream logging/telemetry ----
             if isinstance(ev, ToolCallResult):
                 if hasattr(self.agent_instance, "_add_tool_output"):
                     # pylint: disable=W0212
-                    self.agent_instance._add_tool_output(
-                        ev.tool_name, str(ev.tool_output)
-                    )
+                    self.agent_instance._add_tool_output(ev.tool_name, str(ev.tool_output))
+
+                pending_tools = max(0, pending_tools - 1)
+
+                # Return-direct short-circuit: surface tool output as the final answer
+                if getattr(ev, "return_direct", False):
+                    yield str(ev.tool_output)
+                    committed_any_text = True
+                    # Do not early-break; keep draining events safely.
 
-            # Handle progress callbacks if available
+            # ---- 2) Progress callback plumbing (safe and optional) ----
             if self.agent_instance.agent_progress_callback:
-                # Only track events that are actual tool-related events
-                if self._is_tool_related_event(ev):
+                if is_tool_related_event(ev):
                     try:
                         event_id = get_event_id(ev)
                         await self._handle_progress_callback(ev, event_id)
-                    except ValueError as e:
-                        logging.warning(f"Skipping event due to missing ID: {e}")
-                        continue
+                    except Exception as e:
+                        logging.warning(f"[progress-callback] skipping event: {e}")
+
+            # ---- 3) Step boundaries & gating logic ----
+            # New step starts: clear per-step state
+            if isinstance(ev, AgentInput):
+                _reset_step()
+                continue
 
-            # Process streaming text events
+            # Streaming deltas (provisional)
             if hasattr(ev, "__class__") and "AgentStream" in str(ev.__class__):
-                if hasattr(ev, "tool_calls") and ev.tool_calls:
-                    had_tool_calls = True
-                elif (
-                    hasattr(ev, "tool_calls")
-                    and not ev.tool_calls
-                    and had_tool_calls
-                    and not transitioned_to_prose
-                ):
-                    yield "\n\n"
-                    transitioned_to_prose = True
-                    if hasattr(ev, "delta"):
-                        yield ev.delta
-                elif (
-                    hasattr(ev, "tool_calls")
-                    and not ev.tool_calls
-                    and hasattr(ev, "delta")
-                    and transitioned_to_prose
-                ):
-                    yield ev.delta
+                # If the model is constructing a function call, LlamaIndex will attach tool_calls here
+                if getattr(ev, "tool_calls", None):
+                    step_has_tool_calls = True
 
-        # When stream is done, await the handler to get the final response
+                delta = getattr(ev, "delta", None)
+                if not delta:
+                    continue
+
+                # Always buffer first
+                step_buffer.append(delta)
+
+                # Stream live only after all tools are complete
+                if self.stream_policy == "optimistic_live" and pending_tools == 0:
+                    yield delta
+
+                continue
+
+            # Step end: decide to commit or drop
+            if isinstance(ev, AgentOutput):
+                n_calls = len(getattr(ev, "tool_calls", []) or [])
+
+                if n_calls == 0:
+                    # Final text step -> commit
+                    if self.stream_policy == "final_only":
+                        # We held everything; now stream it out in order.
+                        for chunk in step_buffer:
+                            yield chunk
+                    # In optimistic mode, tokens were streamed live after tools completed.
+
+                    committed_any_text = committed_any_text or bool(step_buffer)
+                    _reset_step()
+
+                else:
+                    # Planning/tool step -> drop buffer
+                    _reset_step()
+                    pending_tools += n_calls
+
+                continue
+
+        # ---- 4) Finish: await the underlying handler for the final result ----
         try:
             self.final_response_container["resp"] = await self.handler
         except Exception as e:
             error_str = str(e).lower()
             if "rate limit" in error_str or "429" in error_str:
-                logging.error(f"[RATE_LIMIT_ERROR] Rate limit exceeded: {e}")
+                logging.error(f"[RATE_LIMIT_ERROR] {e}")
                 self.final_response_container["resp"] = AgentResponse(
                     response="Rate limit exceeded. Please try again later.",
                     source_nodes=[],
                     metadata={"error_type": "rate_limit", "original_error": str(e)},
                 )
             else:
-                logging.error(f"[STREAM_ERROR] Error processing stream events: {e}")
-                logging.error(
-                    f"[STREAM_ERROR] Full traceback: {traceback.format_exc()}"
-                )
+                logging.error(f"[STREAM_ERROR] {e}")
                 self.final_response_container["resp"] = AgentResponse(
                     response="Response completion Error",
                     source_nodes=[],
                     metadata={"error_type": "general", "original_error": str(e)},
                 )
         finally:
-            # Signal that stream processing is complete
+            # If nothing was ever committed and we ended right after a tool,
+            # assume that tool's output is the "final answer" (common with return_direct).
             self.stream_complete_event.set()
 
-    def _is_tool_related_event(self, event) -> bool:
+    async def _handle_progress_callback(self, event, event_id: str):
         """
-        Determine if an event is actually tool-related and should be tracked.
-
-        This should only return True for events that represent actual tool calls or tool outputs,
-        not for streaming text deltas or other LLM response events.
-
-        Args:
-            event: The stream event to check
-
-        Returns:
-            bool: True if this event should be tracked for tool purposes
+        Fan out progress events to the user's callback (sync or async). Mirrors your existing logic.
         """
-        # Track explicit tool events from LlamaIndex workflow
-        if isinstance(event, (ToolCall, ToolCallResult)):
-            return True
-
-        has_tool_id = hasattr(event, "tool_id") and event.tool_id
-        has_delta = hasattr(event, "delta") and event.delta
-        has_tool_name = hasattr(event, "tool_name") and event.tool_name
+        cb = self.agent_instance.agent_progress_callback
+        is_async = asyncio.iscoroutinefunction(cb)
 
-        # We're not seeing ToolCall/ToolCallResult events in the stream, so let's be more liberal
-        # but still avoid streaming deltas
-        if (has_tool_id or has_tool_name) and not has_delta:
-            return True
-
-        # Everything else (streaming deltas, agent outputs, workflow events, etc.)
-        # should NOT be tracked as tool events
-        return False
-
-    async def _handle_progress_callback(self, event, event_id: str):
-        """Handle progress callback events for different event types with proper context propagation."""
         try:
             if isinstance(event, ToolCall):
-                # Check if callback is async or sync
-                if asyncio.iscoroutinefunction(
-                    self.agent_instance.agent_progress_callback
-                ):
-                    await self.agent_instance.agent_progress_callback(
-                        status_type=AgentStatusType.TOOL_CALL,
-                        msg={
-                            "tool_name": event.tool_name,
-                            "arguments": json.dumps(event.tool_kwargs),
-                        },
-                        event_id=event_id,
-                    )
+                payload = {
+                    "tool_name": event.tool_name,
+                    "arguments": json.dumps(getattr(event, "tool_kwargs", {})),
+                }
+                if is_async:
+                    await cb(status_type=AgentStatusType.TOOL_CALL, msg=payload, event_id=event_id)
                 else:
-                    # For sync callbacks, ensure we call them properly
-                    self.agent_instance.agent_progress_callback(
-                        status_type=AgentStatusType.TOOL_CALL,
-                        msg={
-                            "tool_name": event.tool_name,
-                            "arguments": json.dumps(event.tool_kwargs),
-                        },
-                        event_id=event_id,
-                    )
+                    cb(status_type=AgentStatusType.TOOL_CALL, msg=payload, event_id=event_id)
 
             elif isinstance(event, ToolCallResult):
-                # Check if callback is async or sync
-                if asyncio.iscoroutinefunction(
-                    self.agent_instance.agent_progress_callback
-                ):
-                    await self.agent_instance.agent_progress_callback(
-                        status_type=AgentStatusType.TOOL_OUTPUT,
-                        msg={
-                            "tool_name": event.tool_name,
-                            "content": str(event.tool_output),
-                        },
-                        event_id=event_id,
-                    )
+                payload = {
+                    "tool_name": event.tool_name,
+                    "content": str(event.tool_output),
+                }
+                if is_async:
+                    await cb(status_type=AgentStatusType.TOOL_OUTPUT, msg=payload, event_id=event_id)
                 else:
-                    self.agent_instance.agent_progress_callback(
-                        status_type=AgentStatusType.TOOL_OUTPUT,
-                        msg={
-                            "tool_name": event.tool_name,
-                            "content": str(event.tool_output),
-                        },
-                        event_id=event_id,
-                    )
+                    cb(status_type=AgentStatusType.TOOL_OUTPUT, msg=payload, event_id=event_id)
 
             elif isinstance(event, AgentInput):
-                self.agent_instance.agent_progress_callback(
-                    status_type=AgentStatusType.AGENT_UPDATE,
-                    msg={"content": f"Agent input: {event.input}"},
-                    event_id=event_id,
-                )
+                payload = {"content": f"Agent input: {getattr(event, 'input', '')}"}
+                if is_async:
+                    await cb(status_type=AgentStatusType.AGENT_UPDATE, msg=payload, event_id=event_id)
+                else:
+                    cb(status_type=AgentStatusType.AGENT_UPDATE, msg=payload, event_id=event_id)
 
             elif isinstance(event, AgentOutput):
-                self.agent_instance.agent_progress_callback(
-                    status_type=AgentStatusType.AGENT_UPDATE,
-                    msg={"content": f"Agent output: {event.response}"},
-                    event_id=event_id,
-                )
+                payload = {"content": f"Agent output: {getattr(event, 'response', '')}"}
+                if is_async:
+                    await cb(status_type=AgentStatusType.AGENT_UPDATE, msg=payload, event_id=event_id)
+                else:
+                    cb(status_type=AgentStatusType.AGENT_UPDATE, msg=payload, event_id=event_id)
 
         except Exception as e:
+            logging.error(f"[progress-callback] Exception: {e}")
+            logging.error(traceback.format_exc())
 
-            logging.error(f"Exception in progress callback: {e}")
-            logging.error(f"Traceback: {traceback.format_exc()}")
-            # Continue execution despite callback errors
-
-    def create_streaming_response(
-        self, user_metadata: Dict[str, Any]
-    ) -> "StreamingResponseAdapter":
+    def create_streaming_response(self, user_metadata: Dict[str, Any]) -> "StreamingResponseAdapter":
         """
-        Create a StreamingResponseAdapter with proper post-processing.
-
-        Args:
-            user_metadata: User metadata dictionary to update
-
-        Returns:
-            StreamingResponseAdapter: Configured streaming adapter
+        Build the adapter with post-processing wired in.
         """
         post_process_task = create_stream_post_processing_task(
             self.stream_complete_event,
@@ -454,8 +461,8 @@ class FunctionCallingStreamHandler:
 
         return StreamingResponseAdapter(
             async_response_gen=self.process_stream_events,
-            response="",  # will be filled post-stream
-            metadata={},
+            response="",      # will be set by post-processing
+            metadata={},      # will be set by post-processing
             post_process_task=post_process_task,
         )
 
@@ -493,7 +500,7 @@ class ReActStreamHandler:
             # Handle progress callbacks if available - this is the key missing piece!
             if self.agent_instance.agent_progress_callback:
                 # Only track events that are actual tool-related events
-                if self._is_tool_related_event(event):
+                if is_tool_related_event(event):
                     try:
                         # Get event ID from LlamaIndex event
                         event_id = get_event_id(event)
@@ -603,36 +610,6 @@ class ReActStreamHandler:
             # Signal that stream processing is complete
             self.stream_complete_event.set()
 
-    def _is_tool_related_event(self, event) -> bool:
-        """
-        Determine if an event is actually tool-related and should be tracked.
-
-        This should only return True for events that represent actual tool calls or tool outputs,
-        not for streaming text deltas or other LLM response events.
-
-        Args:
-            event: The stream event to check
-
-        Returns:
-            bool: True if this event should be tracked for tool purposes
-        """
-        # Track explicit tool events from LlamaIndex workflow
-        if isinstance(event, (ToolCall, ToolCallResult)):
-            return True
-
-        has_tool_id = hasattr(event, "tool_id") and event.tool_id
-        has_delta = hasattr(event, "delta") and event.delta
-        has_tool_name = hasattr(event, "tool_name") and event.tool_name
-
-        # We're not seeing ToolCall/ToolCallResult events in the stream, so let's be more liberal
-        # but still avoid streaming deltas
-        if (has_tool_id or has_tool_name) and not has_delta:
-            return True
-
-        # Everything else (streaming deltas, agent outputs, workflow events, etc.)
-        # should NOT be tracked as tool events
-        return False
-
     def create_streaming_response(
         self, user_metadata: Dict[str, Any]
     ) -> "StreamingResponseAdapter":

vectara_agentic/agent_core/utils/hallucination.py

@@ -1,12 +1,41 @@
 """Vectara Hallucination Detection and Correction client."""
 
 import logging
+import re
 from typing import List, Optional, Tuple
 import requests
 
 from llama_index.core.llms import MessageRole
 
 
+# Compiled regex patterns for better performance
+_MARKDOWN_LINK_PATTERN = re.compile(r'\[([^\]]*)\]\([^)]*\)')
+_WHITESPACE_CLEANUP_PATTERN = re.compile(r'\s+')
+
+
+def clean_urls_from_text(text: str) -> str:
+    """
+    Remove markdown URLs [text](URL) from text, preserving the link text.
+    This prevents interference with hallucination detection while keeping useful text content.
+
+    Args:
+        text (str): The input text potentially containing markdown URLs
+
+    Returns:
+        str: Text with markdown URLs replaced by their text content
+    """
+    if not text:
+        return text
+
+    # Replace markdown links [text](url) with just the text part
+    cleaned_text = _MARKDOWN_LINK_PATTERN.sub(r'\1', text)
+
+    # Clean up any extra whitespace that might result from the replacement
+    cleaned_text = _WHITESPACE_CLEANUP_PATTERN.sub(' ', cleaned_text).strip()
+
+    return cleaned_text
+
+
 class Hallucination:
     """Vectara Hallucination Correction."""
 
@@ -143,9 +172,12 @@ def analyze_hallucinations(
         return None, []
 
     try:
+        # Clean URLs from agent response to prevent interference with hallucination detection
+        cleaned_agent_response = clean_urls_from_text(agent_response)
+
         h = Hallucination(vectara_api_key)
         corrected_text, corrections = h.compute(
-            query=query, context=context, hypothesis=agent_response
+            query=query, context=context, hypothesis=cleaned_agent_response
         )
         return corrected_text, corrections
 

vectara_agentic/db_tools.py

@@ -305,3 +305,7 @@ def patch_sync(func_async: AsyncCallable) -> Callable:
         return loop.run_until_complete(func_async(*args, **kwargs))
 
     return patched_sync
+
+
+# Tool name suffixes for pattern matching (with underscore prefix)
+DB_TOOL_SUFFIXES = {f"_{func}" for func in DatabaseTools.spec_functions}

vectara_agentic/llm_utils.py

@@ -18,7 +18,7 @@ from .agent_config import AgentConfig
 
 provider_to_default_model_name = {
     ModelProvider.OPENAI: "gpt-4.1-mini",
-    ModelProvider.ANTHROPIC: "claude-sonnet-4-0",
+    ModelProvider.ANTHROPIC: "claude-sonnet-4-5",
     ModelProvider.TOGETHER: "deepseek-ai/DeepSeek-V3",
     ModelProvider.GROQ: "openai/gpt-oss-20b",
     ModelProvider.BEDROCK: "us.anthropic.claude-sonnet-4-20250514-v1:0",
@@ -34,6 +34,7 @@ models_to_max_tokens = {
     "gpt-4.1-mini": 32768,
     "claude-sonnet-4-20250514": 64000,
     "claude-sonnet-4-0": 64000,
+    "claude-sonnet-4-5": 64000,
     "deepseek-ai/deepseek-v3": 8192,
     "models/gemini-2.5-flash": 65536,
     "models/gemini-2.5-flash-lite": 65536,
@@ -117,6 +118,57 @@ def _get_llm_params_for_role(
     return model_provider, model_name
 
 
+def _cleanup_gemini_clients() -> None:
+    """Helper function to cleanup Gemini client sessions."""
+    for llm in _llm_cache.values():
+        try:
+            # Check if this is a GoogleGenAI instance with internal client structure
+            if not hasattr(llm, '_client'):
+                continue
+
+            client = getattr(llm, '_client', None)
+            if not client:
+                continue
+
+            api_client = getattr(client, '_api_client', None)
+            if not api_client:
+                continue
+
+            async_session = getattr(api_client, '_async_session', None)
+            if not async_session:
+                continue
+
+            # Close the aiohttp session if it exists
+            try:
+                import asyncio
+                loop = asyncio.get_event_loop()
+                if not loop.is_closed():
+                    loop.run_until_complete(async_session.close())
+            except Exception:
+                pass
+        except Exception:
+            pass
+
+
+def clear_llm_cache(provider: Optional[ModelProvider] = None) -> None:
+    """
+    Clear the LLM cache, optionally for a specific provider only.
+
+    Args:
+        provider: If specified, only clear cache entries for this provider.
+                 If None, clear the entire cache.
+    """
+    # Before clearing, try to cleanup any Gemini clients
+    _cleanup_gemini_clients()
+
+    if provider is None:
+        # Clear entire cache
+        _llm_cache.clear()
+    else:
+        # For simplicity, just clear all when provider is specified
+        _llm_cache.clear()
+
+
 def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
     """
     Get the LLM for the specified role, using the provided config
@@ -159,6 +211,7 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
                 "google_genai not available. Install with: pip install llama-index-llms-google-genai"
             ) from e
         import google.genai.types as google_types
+
         generation_config = google_types.GenerateContentConfig(
             temperature=0.0,
             seed=123,
@@ -182,7 +235,7 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
             ) from e
         additional_kwargs = {"seed": 42}
         if model_name in [
-            "deepseek-ai/DeepSeek-V3.1", "openai/gpt-oss-120b",
+            "deepseek-ai/DeepSeek-V3.1",
             "deepseek-ai/DeepSeek-R1", "Qwen/Qwen3-235B-A22B-Thinking-2507"
             "openai/gpt-oss-120b", "openai/gpt-oss-20b",
         ]: