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

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/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

vectara_agentic/db_tools.py

@@ -6,6 +6,7 @@ It makes the following adjustments:
 * Makes sure the load_data method returns a list of text values from the database (and not Document[] objects).
 * Limits the returned rows to self.max_rows.
 """
+
 from typing import Any, Optional, List, Awaitable, Callable
 import asyncio
 from inspect import signature
@@ -24,15 +25,20 @@ from llama_index.core.tools.utils import create_schema_from_function
 
 AsyncCallable = Callable[..., Awaitable[Any]]
 
+
 class DatabaseTools:
     """Database tools for vectara-agentic
     This class provides a set of tools to interact with a database.
     It allows you to load data, list tables, describe tables, and load unique values.
     It also provides a method to load sample data from a specified table.
     """
+
     spec_functions = [
-        "load_data", "load_sample_data", "list_tables",
-        "describe_tables", "load_unique_values",
+        "load_data",
+        "load_sample_data",
+        "list_tables",
+        "describe_tables",
+        "load_unique_values",
     ]
 
     def __init__(
@@ -61,7 +67,7 @@ class DatabaseTools:
         elif uri:
             self.uri = uri
             self.sql_database = SQLDatabase.from_uri(uri, *args, **kwargs)
-        elif (scheme and host and port and user and password and dbname):
+        elif scheme and host and port and user and password and dbname:
             uri = f"{scheme}://{user}:{password}@{host}:{port}/{dbname}"
             self.uri = uri
             self.sql_database = SQLDatabase.from_uri(uri, *args, **kwargs)
@@ -76,7 +82,8 @@ class DatabaseTools:
         self._metadata.reflect(bind=self.sql_database.engine)
 
     def _get_metadata_from_fn_name(
-        self, fn_name: Callable,
+        self,
+        fn_name: str,
     ) -> Optional[ToolMetadata]:
         """Return map from function name.
 
@@ -87,7 +94,9 @@ class DatabaseTools:
             func = getattr(self, fn_name)
         except AttributeError:
             return None
-        name = self.tool_name_prefix + "_" + fn_name if self.tool_name_prefix else fn_name
+        name = (
+            self.tool_name_prefix + "_" + fn_name if self.tool_name_prefix else fn_name
+        )
         docstring = func.__doc__ or ""
         description = f"{name}{signature(func)}\n{docstring}"
         fn_schema = create_schema_from_function(fn_name, getattr(self, fn_name))
@@ -118,7 +127,9 @@ class DatabaseTools:
         try:
             count_rows = self._load_data(count_query)
         except Exception as e:
-            return [f"Error ({str(e)}) occurred while counting number of rows, check your query."]
+            return [
+                f"Error ({str(e)}) occurred while counting number of rows, check your query."
+            ]
         num_rows = int(count_rows[0].text)
         if num_rows > self.max_rows:
             return [
@@ -128,7 +139,9 @@ class DatabaseTools:
         try:
             res = self._load_data(sql_query)
         except Exception as e:
-            return [f"Error ({str(e)}) occurred while executing the query {sql_query}, check your query."]
+            return [
+                f"Error ({str(e)}) occurred while executing the query {sql_query}, check your query."
+            ]
         return [d.text for d in res]
 
     def load_sample_data(self, table_name: str, num_rows: int = 25) -> Any:
@@ -149,7 +162,9 @@ class DatabaseTools:
         try:
             res = self._load_data(f"SELECT * FROM {table_name} LIMIT {num_rows}")
         except Exception as e:
-            return [f"Error ({str(e)}) occurred while loading sample data for table {table_name}"]
+            return [
+                f"Error ({str(e)}) occurred while loading sample data for table {table_name}"
+            ]
         return [d.text for d in res]
 
     def list_tables(self) -> List[str]:
@@ -179,7 +194,11 @@ class DatabaseTools:
         table_schemas = []
         for table_name in table_names:
             table = next(
-                (table for table in self._metadata.sorted_tables if table.name == table_name),
+                (
+                    table
+                    for table in self._metadata.sorted_tables
+                    if table.name == table_name
+                ),
                 None,
             )
             if table is None:
@@ -188,7 +207,9 @@ class DatabaseTools:
             table_schemas.append(f"{schema}\n")
         return "\n".join(table_schemas)
 
-    def load_unique_values(self, table_name: str, columns: list[str], num_vals: int = 200) -> Any:
+    def load_unique_values(
+        self, table_name: str, columns: list[str], num_vals: int = 200
+    ) -> Any:
         """
         Fetches the first num_vals unique values from the specified columns of the database table.
 
@@ -209,10 +230,14 @@ class DatabaseTools:
         res = {}
         try:
             for column in columns:
-                unique_vals = self._load_data(f'SELECT DISTINCT "{column}" FROM {table_name} LIMIT {num_vals}')
+                unique_vals = self._load_data(
+                    f'SELECT DISTINCT "{column}" FROM {table_name} LIMIT {num_vals}'
+                )
                 res[column] = [d.text for d in unique_vals]
         except Exception as e:
-            return {f"Error ({str(e)}) occurred while loading unique values for table {table_name}"}
+            return {
+                f"Error ({str(e)}) occurred while loading unique values for table {table_name}"
+            }
         return res
 
     def to_tool_list(self) -> List[FunctionTool]:

vectara_agentic/llm_utils.py

@@ -2,10 +2,10 @@
 Utilities for the Vectara agentic.
 """
 
-from typing import Tuple, Callable, Optional
+from typing import Tuple, Optional
 import os
 from functools import lru_cache
-import tiktoken
+import hashlib
 
 from llama_index.core.llms import LLM
 from llama_index.llms.openai import OpenAI
@@ -13,15 +13,14 @@ from llama_index.llms.anthropic import Anthropic
 
 # LLM provider imports are now lazy-loaded in get_llm() function
 
-from .types import LLMRole, AgentType, ModelProvider
+from .types import LLMRole, ModelProvider
 from .agent_config import AgentConfig
 
 provider_to_default_model_name = {
     ModelProvider.OPENAI: "gpt-4.1",
     ModelProvider.ANTHROPIC: "claude-sonnet-4-20250514",
     ModelProvider.TOGETHER: "deepseek-ai/DeepSeek-V3",
-    ModelProvider.GROQ: "deepseek-r1-distill-llama-70b",
-    ModelProvider.FIREWORKS: "accounts/fireworks/models/firefunction-v2",
+    ModelProvider.GROQ: "openai/gpt-oss-20b",
     ModelProvider.BEDROCK: "us.anthropic.claude-sonnet-4-20250514-v1:0",
     ModelProvider.COHERE: "command-a-03-2025",
     ModelProvider.GEMINI: "models/gemini-2.5-flash",
@@ -29,6 +28,30 @@ provider_to_default_model_name = {
 
 DEFAULT_MODEL_PROVIDER = ModelProvider.OPENAI
 
+# Manual cache for LLM instances to handle mutable AgentConfig objects
+_llm_cache = {}
+
+
+def _create_llm_cache_key(role: LLMRole, config: Optional[AgentConfig] = None) -> str:
+    """Create a hash-based cache key for LLM instances."""
+    if config is None:
+        config = AgentConfig()
+
+    # Extract only the relevant config parameters for the cache key
+    cache_data = {
+        "role": role.value,
+        "main_llm_provider": config.main_llm_provider.value,
+        "main_llm_model_name": config.main_llm_model_name,
+        "tool_llm_provider": config.tool_llm_provider.value,
+        "tool_llm_model_name": config.tool_llm_model_name,
+        "private_llm_api_base": config.private_llm_api_base,
+        "private_llm_api_key": config.private_llm_api_key,
+    }
+
+    # Create a stable hash from the cache data
+    cache_str = str(sorted(cache_data.items()))
+    return hashlib.md5(cache_str.encode()).hexdigest()
+
 
 @lru_cache(maxsize=None)
 def _get_llm_params_for_role(
@@ -54,42 +77,20 @@ def _get_llm_params_for_role(
             model_provider
         )
 
-    # If the agent type is OpenAI, check that the main LLM provider is also OpenAI.
-    if role == LLMRole.MAIN and config.agent_type == AgentType.OPENAI:
-        if model_provider != ModelProvider.OPENAI:
-            raise ValueError(
-                "OpenAI agent requested but main model provider is not OpenAI."
-            )
-
     return model_provider, model_name
 
 
-@lru_cache(maxsize=None)
-def get_tokenizer_for_model(
-    role: LLMRole, config: Optional[AgentConfig] = None
-) -> Optional[Callable]:
-    """
-    Get the tokenizer for the specified model, as determined by the role & config.
-    """
-    model_name = "Unknown model"
-    try:
-        model_provider, model_name = _get_llm_params_for_role(role, config)
-        if model_provider == ModelProvider.OPENAI:
-            return tiktoken.encoding_for_model("gpt-4o").encode
-        if model_provider == ModelProvider.ANTHROPIC:
-            return Anthropic().tokenizer
-    except Exception:
-        print(f"Error getting tokenizer for model {model_name}, ignoring")
-        return None
-    return None
-
-
-@lru_cache(maxsize=None)
 def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
     """
     Get the LLM for the specified role, using the provided config
     or a default if none is provided.
+
+    Uses a cache based on configuration parameters to avoid repeated LLM instantiation.
     """
+    # Check cache first
+    cache_key = _create_llm_cache_key(role, config)
+    if cache_key in _llm_cache:
+        return _llm_cache[cache_key]
     model_provider, model_name = _get_llm_params_for_role(role, config)
     max_tokens = (
         16384
@@ -107,7 +108,7 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
             model=model_name,
             temperature=0,
             is_function_calling_model=True,
-            strict=True,
+            strict=False,
             max_tokens=max_tokens,
             pydantic_program_mode="openai",
         )
@@ -128,7 +129,6 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
             model=model_name,
             temperature=0,
             is_function_calling_model=True,
-            allow_parallel_tool_calls=True,
             max_tokens=max_tokens,
         )
     elif model_provider == ModelProvider.TOGETHER:
@@ -157,14 +157,6 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
             is_function_calling_model=True,
             max_tokens=max_tokens,
         )
-    elif model_provider == ModelProvider.FIREWORKS:
-        try:
-            from llama_index.llms.fireworks import Fireworks
-        except ImportError as e:
-            raise ImportError(
-                "fireworks not available. Install with: pip install llama-index-llms-fireworks"
-            ) from e
-        llm = Fireworks(model=model_name, temperature=0, max_tokens=max_tokens)
     elif model_provider == ModelProvider.BEDROCK:
         try:
             from llama_index.llms.bedrock_converse import BedrockConverse
@@ -197,6 +189,10 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
             raise ImportError(
                 "openai_like not available. Install with: pip install llama-index-llms-openai-like"
             ) from e
+        if not config or not config.private_llm_api_base or not config.private_llm_api_key:
+            raise ValueError(
+                "Private LLM requires both private_llm_api_base and private_llm_api_key to be set in AgentConfig."
+            )
         llm = OpenAILike(
             model=model_name,
             temperature=0,
@@ -209,4 +205,7 @@ def get_llm(role: LLMRole, config: Optional[AgentConfig] = None) -> LLM:
 
     else:
         raise ValueError(f"Unknown LLM provider: {model_provider}")
+
+    # Cache the created LLM instance
+    _llm_cache[cache_key] = llm
     return llm