vectara-agentic 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

vectara_agentic/agent_core/utils/hallucination.py

@@ -0,0 +1,202 @@
+"""Vectara Hallucination Detection and Correction client."""
+
+import logging
+from typing import List, Dict, Optional, Tuple
+import requests
+
+from llama_index.core.llms import MessageRole
+
+class Hallucination:
+    """Vectara Hallucination Correction."""
+
+    def __init__(self, vectara_api_key: str):
+        self._vectara_api_key = vectara_api_key
+
+    def compute(
+        self, query: str, context: list[str], hypothesis: str
+    ) -> Tuple[str, list[str]]:
+        """
+        Calls the Vectara VHC (Vectara Hallucination Correction)
+
+        Returns:
+            str: The corrected hypothesis text.
+            list[str]: the list of corrections from VHC
+        """
+
+        payload = {
+            "generated_text": hypothesis,
+            "query": query,
+            "documents": [{"text": c} for c in context],
+            "model_name": "vhc-large-1.0",
+        }
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "x-api-key": self._vectara_api_key,
+        }
+
+        response = requests.post(
+            "https://api.vectara.io/v2/hallucination_correctors/correct_hallucinations",
+            json=payload,
+            headers=headers,
+            timeout=30,
+        )
+        response.raise_for_status()
+        data = response.json()
+        corrected_text = data.get("corrected_text", "")
+        corrections = data.get("corrections", [])
+
+        logging.debug(
+            f"VHC: query={query}\n"
+        )
+        logging.debug(
+            f"VHC: response={hypothesis}\n"
+        )
+        logging.debug("VHC: Context:")
+        for i, ctx in enumerate(context):
+            logging.info(f"VHC: context {i}: {ctx}\n\n")
+
+        logging.debug(
+            f"VHC: outputs: {len(corrections)} corrections"
+        )
+        logging.debug(
+            f"VHC: corrected_text: {corrected_text}\n"
+        )
+        for correction in corrections:
+            logging.debug(f"VHC: correction: {correction}\n")
+
+        return corrected_text, corrections
+
+def extract_tool_call_mapping(chat_history) -> Dict[str, str]:
+    """Extract tool_call_id to tool_name mapping from chat history."""
+    tool_call_id_to_name = {}
+    for msg in chat_history:
+        if (
+            msg.role == MessageRole.ASSISTANT
+            and hasattr(msg, "additional_kwargs")
+            and msg.additional_kwargs
+        ):
+            tool_calls = msg.additional_kwargs.get("tool_calls", [])
+            for tool_call in tool_calls:
+                if (
+                    isinstance(tool_call, dict)
+                    and "id" in tool_call
+                    and "function" in tool_call
+                ):
+                    tool_call_id = tool_call["id"]
+                    tool_name = tool_call["function"].get("name")
+                    if tool_call_id and tool_name:
+                        tool_call_id_to_name[tool_call_id] = tool_name
+
+    return tool_call_id_to_name
+
+
+def identify_tool_name(msg, tool_call_id_to_name: Dict[str, str]) -> Optional[str]:
+    """Identify tool name from message using multiple strategies."""
+    tool_name = None
+
+    # First try: standard tool_name attribute (for backwards compatibility)
+    tool_name = getattr(msg, "tool_name", None)
+
+    # Second try: additional_kwargs (LlamaIndex standard location)
+    if (
+        tool_name is None
+        and hasattr(msg, "additional_kwargs")
+        and msg.additional_kwargs
+    ):
+        tool_name = msg.additional_kwargs.get("name") or msg.additional_kwargs.get(
+            "tool_name"
+        )
+
+        # If no direct tool name, try to map from tool_call_id
+        if tool_name is None:
+            tool_call_id = msg.additional_kwargs.get("tool_call_id")
+            if tool_call_id and tool_call_id in tool_call_id_to_name:
+                tool_name = tool_call_id_to_name[tool_call_id]
+
+    # Third try: extract from content if it's a ToolOutput object
+    if tool_name is None and hasattr(msg.content, "tool_name"):
+        tool_name = msg.content.tool_name
+
+    return tool_name
+
+
+def check_tool_eligibility(tool_name: Optional[str], tools: List) -> bool:
+    """Check if a tool output is eligible to be included in VHC, by looking up in tools list."""
+    if not tool_name or not tools:
+        return False
+
+    # Try to find the tool and check its VHC eligibility
+    for tool in tools:
+        if (
+            hasattr(tool, "metadata")
+            and hasattr(tool.metadata, "name")
+            and tool.metadata.name == tool_name
+        ):
+            if hasattr(tool.metadata, "vhc_eligible"):
+                is_vhc_eligible = tool.metadata.vhc_eligible
+                return is_vhc_eligible
+            break
+
+    return True
+
+def analyze_hallucinations(
+    query: str, chat_history: List,
+    agent_response: str, tools: List, vectara_api_key: str
+) -> Tuple[Optional[str], List[str]]:
+    """Use VHC to compute corrected_text and corrections."""
+    if not vectara_api_key:
+        logging.debug("No Vectara API key - returning None")
+        return None, []
+
+    # Build a mapping from tool_call_id to tool_name for better tool identification
+    tool_call_id_to_name = extract_tool_call_mapping(chat_history)
+
+    context = []
+    last_assistant_index = -1
+    for i, msg in enumerate(chat_history):
+        if msg.role == MessageRole.ASSISTANT and msg.content:
+            last_assistant_index = i
+
+    for i, msg in enumerate(chat_history):
+        if msg.role == MessageRole.TOOL:
+            tool_name = identify_tool_name(msg, tool_call_id_to_name)
+            is_vhc_eligible = check_tool_eligibility(tool_name, tools)
+
+            # Only count tool calls from VHC-eligible tools
+            if is_vhc_eligible:
+                content = msg.content
+
+                # Since tools with human-readable output now convert to formatted strings immediately
+                # in VectaraTool._format_tool_output(), we just use the content directly
+                content = str(content) if content is not None else ""
+
+                # Only add non-empty content to context
+                if content and content.strip():
+                    context.append(content)
+
+        elif msg.role == MessageRole.USER and msg.content:
+            context.append(msg.content)
+
+        elif msg.role == MessageRole.ASSISTANT and msg.content:
+            if i == last_assistant_index:  # do not include the last assistant message
+                continue
+            context.append(msg.content)
+
+    # If no context or no tool calls, we cannot compute VHC
+    if len(context) == 0:
+        return None, []
+
+    try:
+        h = Hallucination(vectara_api_key)
+        corrected_text, corrections = h.compute(
+            query=query, context=context, hypothesis=agent_response
+        )
+        return corrected_text, corrections
+
+    except Exception as e:
+        logging.error(
+            f"VHC call failed: {e}. "
+            "Ensure you have a valid Vectara API key and the Hallucination Correction service is available."
+        )
+        return None, []

vectara_agentic/agent_core/utils/logging.py

@@ -0,0 +1,52 @@
+"""
+Logging configuration and utilities for agent functionality.
+
+This module provides logging filters, configuration, and setup utilities
+specifically tailored for agent operations and debugging.
+"""
+
+import logging
+from dotenv import load_dotenv
+
+
+class IgnoreUnpickleableAttributeFilter(logging.Filter):
+    """
+    Filter to ignore log messages that contain certain strings.
+
+    This filter is used to suppress common unpickleable attribute warnings
+    that occur during agent serialization/deserialization operations.
+    """
+
+    def filter(self, record):
+        """
+        Filter log records based on message content.
+
+        Args:
+            record: LogRecord to evaluate
+
+        Returns:
+            bool: True if record should be logged, False if it should be ignored
+        """
+        msgs_to_ignore = [
+            "Removing unpickleable private attribute _split_fns",
+            "Removing unpickleable private attribute _sub_sentence_split_fns",
+        ]
+        return all(msg not in record.getMessage() for msg in msgs_to_ignore)
+
+
+def setup_agent_logging():
+    """
+    Set up logging configuration for agent operations.
+
+    This configures logging filters and levels to reduce noise from
+    agent-related operations while maintaining useful debug information.
+    """
+    # Add filter to suppress unpickleable attribute warnings
+    logging.getLogger().addFilter(IgnoreUnpickleableAttributeFilter())
+
+    # Set critical level for OTLP trace exporter to reduce noise
+    logger = logging.getLogger("opentelemetry.exporter.otlp.proto.http.trace_exporter")
+    logger.setLevel(logging.CRITICAL)
+
+    # Load environment variables with override
+    load_dotenv(override=True)

vectara_agentic/agent_core/utils/prompt_formatting.py

@@ -0,0 +1,56 @@
+"""
+Prompt formatting and templating utilities.
+
+This module handles prompt template processing, placeholder replacement,
+and LLM-specific prompt formatting for different agent types.
+"""
+
+from datetime import date
+
+def format_prompt(
+    prompt_template: str,
+    general_instructions: str,
+    topic: str,
+    custom_instructions: str,
+) -> str:
+    """
+    Generate a prompt by replacing placeholders with topic and date.
+
+    Args:
+        prompt_template: The template for the prompt
+        general_instructions: General instructions to be included in the prompt
+        topic: The topic to be included in the prompt
+        custom_instructions: The custom instructions to be included in the prompt
+
+    Returns:
+        str: The formatted prompt
+    """
+    return (
+        prompt_template.replace("{chat_topic}", topic)
+        .replace("{today}", date.today().strftime("%A, %B %d, %Y"))
+        .replace("{custom_instructions}", custom_instructions)
+        .replace("{INSTRUCTIONS}", general_instructions)
+    )
+
+
+def format_llm_compiler_prompt(
+    prompt: str, general_instructions: str, topic: str, custom_instructions: str
+) -> str:
+    """
+    Add custom instructions to the prompt for LLM compiler agents.
+
+    Args:
+        prompt: The base prompt to which custom instructions should be added
+        general_instructions: General instructions for the agent
+        topic: Topic expertise for the agent
+        custom_instructions: Custom user instructions
+
+    Returns:
+        str: The prompt with custom instructions added
+    """
+    prompt += "\nAdditional Instructions:\n"
+    prompt += f"You have expertise in {topic}.\n"
+    prompt += general_instructions
+    prompt += custom_instructions
+    prompt += f"Today is {date.today().strftime('%A, %B %d, %Y')}"
+    return prompt

vectara_agentic/agent_core/utils/schemas.py

@@ -0,0 +1,87 @@
+"""
+Schema and type conversion utilities for agent functionality.
+
+This module handles JSON schema to Python type conversion,
+Pydantic model reconstruction, and type mapping operations.
+"""
+
+from typing import Any, Union, List
+
+
+# Type mapping constants
+JSON_TYPE_TO_PYTHON = {
+    "string": str,
+    "integer": int,
+    "boolean": bool,
+    "array": list,
+    "object": dict,
+    "number": float,
+    "null": type(None),
+}
+
+PY_TYPES = {
+    "str": str,
+    "int": int,
+    "float": float,
+    "bool": bool,
+    "dict": dict,
+    "list": list,
+}
+
+
+def get_field_type(field_schema: dict) -> Any:
+    """
+    Convert a JSON schema field definition to a Python type.
+    Handles 'type' and 'anyOf' cases.
+
+    Args:
+        field_schema: JSON schema field definition
+
+    Returns:
+        Any: Corresponding Python type
+    """
+    if not field_schema:  # Handles empty schema {}
+        return Any
+
+    if "anyOf" in field_schema:
+        types = []
+        for option_schema in field_schema["anyOf"]:
+            types.append(get_field_type(option_schema))  # Recursive call
+        if not types:
+            return Any
+        return Union[tuple(types)]
+
+    if "type" in field_schema and isinstance(field_schema["type"], list):
+        types = []
+        for type_name in field_schema["type"]:
+            if type_name == "array":
+                item_schema = field_schema.get("items", {})
+                types.append(List[get_field_type(item_schema)])
+            elif type_name in JSON_TYPE_TO_PYTHON:
+                types.append(JSON_TYPE_TO_PYTHON[type_name])
+            else:
+                types.append(Any)  # Fallback for unknown types in the list
+        if not types:
+            return Any
+        return Union[tuple(types)]  # type: ignore
+
+    if "type" in field_schema:
+        schema_type_name = field_schema["type"]
+        if schema_type_name == "array":
+            item_schema = field_schema.get(
+                "items", {}
+            )  # Default to Any if "items" is missing
+            return List[get_field_type(item_schema)]
+
+        return JSON_TYPE_TO_PYTHON.get(schema_type_name, Any)
+
+    # If only "items" is present (implies array by some conventions, but less standard)
+    # Or if it's a schema with other keywords like 'properties' (implying object)
+    # For simplicity, if no "type" or "anyOf" at this point, default to Any or add more specific handling.
+    # If 'properties' in field_schema or 'additionalProperties' in field_schema, it's likely an object.
+    if "properties" in field_schema or "additionalProperties" in field_schema:
+        # This path might need to reconstruct a nested Pydantic model if you encounter such schemas.
+        # For now, treating as 'dict' or 'Any' might be a simpler placeholder.
+        return dict  # Or Any, or more sophisticated object reconstruction.
+
+    return Any

vectara_agentic/agent_core/utils/tools.py

@@ -0,0 +1,125 @@
+"""
+Tool processing and validation utilities for agent functionality.
+
+This module provides utilities for tool validation, processing, and
+compatibility adjustments for different LLM providers.
+"""
+
+import inspect
+from typing import Any, List
+from inspect import Signature, Parameter, ismethod
+from collections import Counter
+
+from pydantic import Field, create_model
+from llama_index.core.tools import FunctionTool
+from ...llm_utils import get_llm
+from ...types import LLMRole
+
+
+def sanitize_tools_for_gemini(tools: List[FunctionTool]) -> List[FunctionTool]:
+    """
+    Strip all default values from tools for Gemini LLM compatibility.
+
+    Gemini requires that tools only show required parameters without defaults.
+    This function modifies:
+    - tool.fn signature
+    - tool.async_fn signature
+    - tool.metadata.fn_schema
+
+    Args:
+        tools: List of FunctionTool objects to sanitize
+
+    Returns:
+        List[FunctionTool]: Sanitized tools with no default values
+    """
+    for tool in tools:
+        # 1) Strip defaults off the actual callables
+        for func in (tool.fn, tool.async_fn):
+            if not func:
+                continue
+            orig_sig = inspect.signature(func)
+            new_params = [
+                p.replace(default=Parameter.empty) for p in orig_sig.parameters.values()
+            ]
+            new_sig = Signature(
+                new_params, return_annotation=orig_sig.return_annotation
+            )
+            if ismethod(func):
+                func.__func__.__signature__ = new_sig
+            else:
+                func.__signature__ = new_sig
+
+        # 2) Rebuild the Pydantic schema so that *every* field is required
+        schema_cls = getattr(tool.metadata, "fn_schema", None)
+        if schema_cls and hasattr(schema_cls, "model_fields"):
+            # Collect (name → (type, Field(...))) for all fields
+            new_fields: dict[str, tuple[type, Any]] = {}
+            for name, mf in schema_cls.model_fields.items():
+                typ = mf.annotation
+                desc = getattr(mf, "description", "")
+                # Force required (no default) with Field(...)
+                new_fields[name] = (typ, Field(..., description=desc))
+
+            # Make a brand-new schema class where every field is required
+            no_default_schema = create_model(
+                f"{schema_cls.__name__}",  # new class name
+                **new_fields,  # type: ignore
+            )
+
+            # Give it a clean __signature__ so inspect.signature sees no defaults
+            params = [
+                Parameter(n, Parameter.POSITIONAL_OR_KEYWORD, annotation=typ)
+                for n, (typ, _) in new_fields.items()
+            ]
+            no_default_schema.__signature__ = Signature(params)
+
+            # Swap it back onto the tool
+            tool.metadata.fn_schema = no_default_schema
+
+    return tools
+
+
+def validate_tool_consistency(
+    tools: List[FunctionTool], custom_instructions: str, agent_config
+) -> None:
+    """
+    Validate that tools mentioned in instructions actually exist.
+
+    Args:
+        tools: List of available tools
+        custom_instructions: Custom instructions that may reference tools
+        agent_config: Agent configuration for LLM access
+
+    Raises:
+        ValueError: If invalid tools are referenced in instructions
+    """
+    tool_names = [tool.metadata.name for tool in tools]
+
+    # Check for duplicate tools
+    duplicates = [tool for tool, count in Counter(tool_names).items() if count > 1]
+    if duplicates:
+        raise ValueError(f"Duplicate tools detected: {', '.join(duplicates)}")
+
+    # Validate tools mentioned in instructions exist
+    if custom_instructions:
+        prompt = f"""
+        You are provided these tools:
+        <tools>{','.join(tool_names)}</tools>
+        And these instructions:
+        <instructions>
+        {custom_instructions}
+        </instructions>
+        Your task is to identify invalid tools.
+        A tool is invalid if it is mentioned in the instructions but not in the tools list.
+        A tool's name must have at least two characters.
+        Your response should be a comma-separated list of the invalid tools.
+        If no invalid tools exist, respond with "<OKAY>" (and nothing else).
+        """
+        llm = get_llm(LLMRole.MAIN, config=agent_config)
+        bad_tools_str = llm.complete(prompt).text.strip("\n")
+        if bad_tools_str and bad_tools_str != "<OKAY>":
+            bad_tools = [tool.strip() for tool in bad_tools_str.split(",")]
+            numbered = ", ".join(f"({i}) {tool}" for i, tool in enumerate(bad_tools, 1))
+            raise ValueError(
+                f"The Agent custom instructions mention these invalid tools: {numbered}"
+            )

vectara_agentic/agent_endpoint.py

@@ -16,12 +16,6 @@ from .agent import Agent
 from .agent_config import AgentConfig
 
 
-class ChatRequest(BaseModel):
-    """Request schema for the /chat endpoint."""
-
-    message: str
-
-
 class CompletionRequest(BaseModel):
     """Request schema for the /v1/completions endpoint."""
 
@@ -64,12 +58,14 @@ class CompletionResponse(BaseModel):
 
 class ChatMessage(BaseModel):
     """Schema for individual chat messages in ChatCompletionRequest."""
+
     role: Literal["system", "user", "assistant"]
     content: str
 
 
 class ChatCompletionRequest(BaseModel):
     """Request schema for the /v1/chat endpoint."""
+
     model: str
     messages: List[ChatMessage]
     temperature: Optional[float] = Field(1.0, ge=0.0, le=2.0)
@@ -79,6 +75,7 @@ class ChatCompletionRequest(BaseModel):
 
 class ChatCompletionChoice(BaseModel):
     """Choice schema returned in ChatCompletionResponse."""
+
     index: int
     message: ChatMessage
     finish_reason: Literal["stop", "length", "error", None]
@@ -86,6 +83,7 @@ class ChatCompletionChoice(BaseModel):
 
 class ChatCompletionResponse(BaseModel):
     """Response schema for the /v1/chat endpoint."""
+
     id: str
     object: Literal["chat.completion"]
     created: int