vectara-agentic 0.3.2__tar.gz → 0.4.0__tar.gz

{vectara_agentic-0.3.2/vectara_agentic.egg-info → vectara_agentic-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectara_agentic
-Version: 0.3.2
+Version: 0.4.0
 Summary: A Python package for creating AI Assistants and AI Agents with Vectara
 Home-page: https://github.com/vectara/py-vectara-agentic
 Author: Ofer Mendelevitch
@@ -16,26 +16,26 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: llama-index==0.12.37
-Requires-Dist: llama-index-core==0.12.37
-Requires-Dist: llama-index-cli==0.4.1
+Requires-Dist: llama-index==0.12.49
+Requires-Dist: llama-index-core==0.12.49
+Requires-Dist: llama-index-workflow==1.0.1
+Requires-Dist: llama-index-cli==0.4.4
 Requires-Dist: llama-index-indices-managed-vectara==0.4.5
-Requires-Dist: llama-index-agent-llm-compiler==0.3.1
-Requires-Dist: llama-index-agent-lats==0.3.0
-Requires-Dist: llama-index-agent-openai==0.4.8
-Requires-Dist: llama-index-llms-openai==0.3.44
-Requires-Dist: llama-index-llms-openai-like==0.3.5
-Requires-Dist: llama-index-llms-anthropic==0.6.19
-Requires-Dist: llama-index-llms-together==0.3.1
-Requires-Dist: llama-index-llms-groq==0.3.1
-Requires-Dist: llama-index-llms-fireworks==0.3.2
+Requires-Dist: llama-index-agent-llm-compiler==0.3.2
+Requires-Dist: llama-index-agent-lats==0.3.2
+Requires-Dist: llama-index-agent-openai==0.4.12
+Requires-Dist: llama-index-llms-openai==0.4.7
+Requires-Dist: llama-index-llms-openai-like==0.4.0
+Requires-Dist: llama-index-llms-anthropic==0.7.6
+Requires-Dist: llama-index-llms-together==0.3.2
+Requires-Dist: llama-index-llms-groq==0.3.2
 Requires-Dist: llama-index-llms-cohere==0.5.0
-Requires-Dist: llama-index-llms-google-genai==0.2.1
-Requires-Dist: llama-index-llms-bedrock-converse==0.7.1
+Requires-Dist: llama-index-llms-google-genai==0.2.5
+Requires-Dist: llama-index-llms-bedrock-converse==0.7.6
 Requires-Dist: llama-index-tools-yahoo-finance==0.3.0
 Requires-Dist: llama-index-tools-arxiv==0.3.0
 Requires-Dist: llama-index-tools-database==0.3.0
-Requires-Dist: llama-index-tools-google==0.3.1
+Requires-Dist: llama-index-tools-google==0.5.0
 Requires-Dist: llama-index-tools-tavily_research==0.3.0
 Requires-Dist: llama_index.tools.brave_search==0.3.0
 Requires-Dist: llama-index-tools-neo4j==0.3.0
@@ -44,11 +44,11 @@ Requires-Dist: llama-index-graph-stores-kuzu==0.7.0
 Requires-Dist: llama-index-tools-salesforce==0.3.0
 Requires-Dist: llama-index-tools-slack==0.3.0
 Requires-Dist: llama-index-tools-exa==0.3.0
-Requires-Dist: llama-index-tools-wikipedia==0.3.0
+Requires-Dist: llama-index-tools-wikipedia==0.3.1
 Requires-Dist: llama-index-tools-bing-search==0.3.0
-Requires-Dist: openai>=1.82.1
-Requires-Dist: tavily-python==0.7.3
-Requires-Dist: exa-py==1.13.1
+Requires-Dist: openai>=1.96.1
+Requires-Dist: tavily-python>=0.7.9
+Requires-Dist: exa-py>=1.14.8
 Requires-Dist: openinference-instrumentation-llama-index==4.3.1
 Requires-Dist: opentelemetry-proto>=1.31.0
 Requires-Dist: arize-phoenix==10.9.1
@@ -56,9 +56,9 @@ Requires-Dist: arize-phoenix-otel==0.10.3
 Requires-Dist: protobuf==5.29.3
 Requires-Dist: tokenizers>=0.20
 Requires-Dist: pydantic==2.11.5
+Requires-Dist: pandas==2.2.3
 Requires-Dist: retrying==1.3.4
 Requires-Dist: python-dotenv==1.0.1
-Requires-Dist: tiktoken==0.9.0
 Requires-Dist: cloudpickle>=3.1.1
 Requires-Dist: httpx==0.28.1
 Requires-Dist: commonmark==0.9.1
@@ -108,6 +108,7 @@ Dynamic: summary
 - [Using Tools](#using-tools)
 - [Advanced Usage: Workflows](#advanced-usage-workflows)
 - [Configuration](#️-configuration)
+- [Migrating from v0.3.x](#-migrating-from-v03x)
 - [Contributing](#-contributing)
 - [License](#-license)
 
@@ -124,11 +125,11 @@ Dynamic: summary
 - **Rapid Tool Creation:**  
   Build Vectara RAG tools or search tools with a single line of code.
 - **Agent Flexibility:**  
-  Supports multiple agent types including `ReAct`, `OpenAIAgent`, `LATS`, and `LLMCompiler`.
+  Supports multiple agent types including `ReAct`, `Function Calling`, `LATS`, and `LLMCompiler`.
 - **Pre-Built Domain Tools:**  
   Tools tailored for finance, legal, and other verticals.
 - **Multi-LLM Integration:**  
-  Seamless integration with OpenAI, Anthropic, Gemini, GROQ, Together.AI, Cohere, Bedrock, and Fireworks.
+  Seamless integration with OpenAI, Anthropic, Gemini, GROQ, Together.AI, Cohere, and Bedrock.
 - **Observability:**  
   Built-in support with Arize Phoenix for monitoring and feedback.
 - **Workflow Support:**  
@@ -148,7 +149,7 @@ Check out our example AI assistants:
 - [Vectara account](https://console.vectara.com/signup/?utm_source=github&utm_medium=code&utm_term=DevRel&utm_content=vectara-agentic&utm_campaign=github-code-DevRel-vectara-agentic)
 - A Vectara corpus with an [API key](https://docs.vectara.com/docs/api-keys)
 - [Python 3.10 or higher](https://www.python.org/downloads/)
-- OpenAI API key (or API keys for Anthropic, TOGETHER.AI, Fireworks AI, Cohere, GEMINI or GROQ, if you choose to use them).
+- OpenAI API key (or API keys for Anthropic, TOGETHER.AI, Cohere, GEMINI or GROQ, if you choose to use them).
   To use AWS Bedrock, make sure that
   * The Bedrock models you need are enabled on your account
   * Your environment includes `AWS_PROFILE` with your AWS profile name.
@@ -200,7 +201,8 @@ ask_finance = vec_factory.create_rag_tool(
     tool_description="Query financial reports for a company and year",
     tool_args_schema=QueryFinancialReportsArgs,
     lambda_val=0.005,
-    summary_num_results=7, 
+    summary_num_results=7,
+    vhc_eligible=True,  # RAG tools participate in VHC by default
     # Additional Vectara query arguments...
 )
 ```
@@ -480,6 +482,30 @@ def mult_func(x, y):
 mult_tool = ToolsFactory().create_tool(mult_func)
 ```
 
+#### VHC Eligibility
+
+When creating tools, you can control whether they participate in Vectara Hallucination Correction, by using the `vhc_eligible` parameter:
+
+```python
+# Tool that provides factual data - should participate in VHC
+data_tool = ToolsFactory().create_tool(get_company_data, vhc_eligible=True)
+
+# Utility tool that doesn't provide context - should not participate in VHC  
+summary_tool = ToolsFactory().create_tool(summarize_text, vhc_eligible=False)
+```
+
+**VHC-eligible tools** (default: `True`) are those that provide factual context for responses, such as:
+- Data retrieval tools
+- Search tools  
+- API calls that return factual information
+
+**Non-VHC-eligible tools** (`vhc_eligible=False`) are utility tools that don't contribute factual context:
+- Text summarization tools
+- Text rephrasing tools
+- Formatting or processing tools
+
+Built-in utility tools like `summarize_text`, `rephrase_text`, and `get_bad_topics` are automatically marked as non-VHC-eligible.
+
 #### Human-Readable Tool Output
 
 Tools can provide both raw data and human-readable formatted output using the `create_human_readable_output` utility:
@@ -504,7 +530,7 @@ Built-in formatters include `format_as_table`, `format_as_json`, and `format_as_
 > and not as nested functions. Nested functions are not supported if you use serialization 
 > (dumps/loads or from_dict/to_dict).
 
-The human-readable format, if available, is used when computing the factual consistency score.
+The human-readable format, if available, is used when using Vectara Hallucination Correction.
 
 ### Tool Validation
 
@@ -719,12 +745,13 @@ agent = Agent(
 ```
 
 The `AgentConfig` object may include the following items:
-- `agent_type`: the agent type. Valid values are `REACT`, `LLMCOMPILER`, `LATS` or `OPENAI` (default: `OPENAI`).
-- `main_llm_provider` and `tool_llm_provider`: the LLM provider for main agent and for the tools. Valid values are `OPENAI`, `ANTHROPIC`, `TOGETHER`, `GROQ`, `COHERE`, `BEDROCK`, `GEMINI` or `FIREWORKS` (default: `OPENAI`).
-- `main_llm_model_name` and `tool_llm_model_name`: agent model name for agent and tools (default depends on provider).
+- `agent_type`: the agent type. Valid values are `REACT`, `LLMCOMPILER`, `LATS` or `FUNCTION_CALLING` (default: `FUNCTION_CALLING`).
+- `main_llm_provider` and `tool_llm_provider`: the LLM provider for main agent and for the tools. Valid values are `OPENAI`, `ANTHROPIC`, `TOGETHER`, `GROQ`, `COHERE`, `BEDROCK`, `GEMINI` (default: `OPENAI`).
+
+> **Note:** Fireworks AI support has been removed. If you were using Fireworks, please migrate to one of the supported providers listed above.
+- `main_llm_model_name` and `tool_llm_model_name`: agent model name for agent and tools (default depends on provider: OpenAI uses gpt-4.1, Gemini uses gemini-2.5-flash).
 - `observer`: the observer type; should be `ARIZE_PHOENIX` or if undefined no observation framework will be used.
 - `endpoint_api_key`: a secret key if using the API endpoint option (defaults to `dev-api-key`)
-- `max_reasoning_steps`: the maximum number of reasoning steps (iterations for React and function calls for OpenAI agent, respectively). Defaults to 50.
 
 If any of these are not provided, `AgentConfig` first tries to read the values from the OS environment.
 
@@ -759,3 +786,15 @@ agent = Agent(
 )
 ```
 
+## 🚀 Migrating from v0.3.x
+
+If you're upgrading from v0.3.x, please note the following breaking changes in v0.4.0:
+
+- **Fireworks LLM removed**: Migrate to OpenAI, Anthropic, Together.AI, GROQ, Cohere, Bedrock, or Gemini
+- **OPENAI AgentType removed**: Use the FUNCTION_CALLING AgentType instead, when using OpenAI for main_llm_provider
+- **StructuredPlanning deprecated**: Use standard Agent workflows or create custom workflows
+- **Token counting and compact_docstring removed**: Remove these from your configuration
+- **update_func removed**: This functionality is no longer available
+
+For detailed migration instructions, see [CHANGELOG.md](CHANGELOG.md).
+

{vectara_agentic-0.3.2 → vectara_agentic-0.4.0}/README.md

@@ -31,6 +31,7 @@
 - [Using Tools](#using-tools)
 - [Advanced Usage: Workflows](#advanced-usage-workflows)
 - [Configuration](#️-configuration)
+- [Migrating from v0.3.x](#-migrating-from-v03x)
 - [Contributing](#-contributing)
 - [License](#-license)
 
@@ -47,11 +48,11 @@
 - **Rapid Tool Creation:**  
   Build Vectara RAG tools or search tools with a single line of code.
 - **Agent Flexibility:**  
-  Supports multiple agent types including `ReAct`, `OpenAIAgent`, `LATS`, and `LLMCompiler`.
+  Supports multiple agent types including `ReAct`, `Function Calling`, `LATS`, and `LLMCompiler`.
 - **Pre-Built Domain Tools:**  
   Tools tailored for finance, legal, and other verticals.
 - **Multi-LLM Integration:**  
-  Seamless integration with OpenAI, Anthropic, Gemini, GROQ, Together.AI, Cohere, Bedrock, and Fireworks.
+  Seamless integration with OpenAI, Anthropic, Gemini, GROQ, Together.AI, Cohere, and Bedrock.
 - **Observability:**  
   Built-in support with Arize Phoenix for monitoring and feedback.
 - **Workflow Support:**  
@@ -71,7 +72,7 @@ Check out our example AI assistants:
 - [Vectara account](https://console.vectara.com/signup/?utm_source=github&utm_medium=code&utm_term=DevRel&utm_content=vectara-agentic&utm_campaign=github-code-DevRel-vectara-agentic)
 - A Vectara corpus with an [API key](https://docs.vectara.com/docs/api-keys)
 - [Python 3.10 or higher](https://www.python.org/downloads/)
-- OpenAI API key (or API keys for Anthropic, TOGETHER.AI, Fireworks AI, Cohere, GEMINI or GROQ, if you choose to use them).
+- OpenAI API key (or API keys for Anthropic, TOGETHER.AI, Cohere, GEMINI or GROQ, if you choose to use them).
   To use AWS Bedrock, make sure that
   * The Bedrock models you need are enabled on your account
   * Your environment includes `AWS_PROFILE` with your AWS profile name.
@@ -123,7 +124,8 @@ ask_finance = vec_factory.create_rag_tool(
     tool_description="Query financial reports for a company and year",
     tool_args_schema=QueryFinancialReportsArgs,
     lambda_val=0.005,
-    summary_num_results=7, 
+    summary_num_results=7,
+    vhc_eligible=True,  # RAG tools participate in VHC by default
     # Additional Vectara query arguments...
 )
 ```
@@ -403,6 +405,30 @@ def mult_func(x, y):
 mult_tool = ToolsFactory().create_tool(mult_func)
 ```
 
+#### VHC Eligibility
+
+When creating tools, you can control whether they participate in Vectara Hallucination Correction, by using the `vhc_eligible` parameter:
+
+```python
+# Tool that provides factual data - should participate in VHC
+data_tool = ToolsFactory().create_tool(get_company_data, vhc_eligible=True)
+
+# Utility tool that doesn't provide context - should not participate in VHC  
+summary_tool = ToolsFactory().create_tool(summarize_text, vhc_eligible=False)
+```
+
+**VHC-eligible tools** (default: `True`) are those that provide factual context for responses, such as:
+- Data retrieval tools
+- Search tools  
+- API calls that return factual information
+
+**Non-VHC-eligible tools** (`vhc_eligible=False`) are utility tools that don't contribute factual context:
+- Text summarization tools
+- Text rephrasing tools
+- Formatting or processing tools
+
+Built-in utility tools like `summarize_text`, `rephrase_text`, and `get_bad_topics` are automatically marked as non-VHC-eligible.
+
 #### Human-Readable Tool Output
 
 Tools can provide both raw data and human-readable formatted output using the `create_human_readable_output` utility:
@@ -427,7 +453,7 @@ Built-in formatters include `format_as_table`, `format_as_json`, and `format_as_
 > and not as nested functions. Nested functions are not supported if you use serialization 
 > (dumps/loads or from_dict/to_dict).
 
-The human-readable format, if available, is used when computing the factual consistency score.
+The human-readable format, if available, is used when using Vectara Hallucination Correction.
 
 ### Tool Validation
 
@@ -642,12 +668,13 @@ agent = Agent(
 ```
 
 The `AgentConfig` object may include the following items:
-- `agent_type`: the agent type. Valid values are `REACT`, `LLMCOMPILER`, `LATS` or `OPENAI` (default: `OPENAI`).
-- `main_llm_provider` and `tool_llm_provider`: the LLM provider for main agent and for the tools. Valid values are `OPENAI`, `ANTHROPIC`, `TOGETHER`, `GROQ`, `COHERE`, `BEDROCK`, `GEMINI` or `FIREWORKS` (default: `OPENAI`).
-- `main_llm_model_name` and `tool_llm_model_name`: agent model name for agent and tools (default depends on provider).
+- `agent_type`: the agent type. Valid values are `REACT`, `LLMCOMPILER`, `LATS` or `FUNCTION_CALLING` (default: `FUNCTION_CALLING`).
+- `main_llm_provider` and `tool_llm_provider`: the LLM provider for main agent and for the tools. Valid values are `OPENAI`, `ANTHROPIC`, `TOGETHER`, `GROQ`, `COHERE`, `BEDROCK`, `GEMINI` (default: `OPENAI`).
+
+> **Note:** Fireworks AI support has been removed. If you were using Fireworks, please migrate to one of the supported providers listed above.
+- `main_llm_model_name` and `tool_llm_model_name`: agent model name for agent and tools (default depends on provider: OpenAI uses gpt-4.1, Gemini uses gemini-2.5-flash).
 - `observer`: the observer type; should be `ARIZE_PHOENIX` or if undefined no observation framework will be used.
 - `endpoint_api_key`: a secret key if using the API endpoint option (defaults to `dev-api-key`)
-- `max_reasoning_steps`: the maximum number of reasoning steps (iterations for React and function calls for OpenAI agent, respectively). Defaults to 50.
 
 If any of these are not provided, `AgentConfig` first tries to read the values from the OS environment.
 
@@ -682,3 +709,15 @@ agent = Agent(
 )
 ```
 
+## 🚀 Migrating from v0.3.x
+
+If you're upgrading from v0.3.x, please note the following breaking changes in v0.4.0:
+
+- **Fireworks LLM removed**: Migrate to OpenAI, Anthropic, Together.AI, GROQ, Cohere, Bedrock, or Gemini
+- **OPENAI AgentType removed**: Use the FUNCTION_CALLING AgentType instead, when using OpenAI for main_llm_provider
+- **StructuredPlanning deprecated**: Use standard Agent workflows or create custom workflows
+- **Token counting and compact_docstring removed**: Remove these from your configuration
+- **update_func removed**: This functionality is no longer available
+
+For detailed migration instructions, see [CHANGELOG.md](CHANGELOG.md).
+

{vectara_agentic-0.3.2 → vectara_agentic-0.4.0}/requirements.txt

@@ -1,23 +1,23 @@
-llama-index==0.12.37
-llama-index-core==0.12.37
-llama-index-cli==0.4.1
+llama-index==0.12.49
+llama-index-core==0.12.49
+llama-index-workflow==1.0.1
+llama-index-cli==0.4.4
 llama-index-indices-managed-vectara==0.4.5
-llama-index-agent-llm-compiler==0.3.1
-llama-index-agent-lats==0.3.0
-llama-index-agent-openai==0.4.8
-llama-index-llms-openai==0.3.44
-llama-index-llms-openai-like==0.3.5
-llama-index-llms-anthropic==0.6.19
-llama-index-llms-together==0.3.1
-llama-index-llms-groq==0.3.1
-llama-index-llms-fireworks==0.3.2
+llama-index-agent-llm-compiler==0.3.2
+llama-index-agent-lats==0.3.2
+llama-index-agent-openai==0.4.12
+llama-index-llms-openai==0.4.7
+llama-index-llms-openai-like==0.4.0
+llama-index-llms-anthropic==0.7.6
+llama-index-llms-together==0.3.2
+llama-index-llms-groq==0.3.2
 llama-index-llms-cohere==0.5.0
-llama-index-llms-google-genai==0.2.1
-llama-index-llms-bedrock-converse==0.7.1
+llama-index-llms-google-genai==0.2.5
+llama-index-llms-bedrock-converse==0.7.6
 llama-index-tools-yahoo-finance==0.3.0
 llama-index-tools-arxiv==0.3.0
 llama-index-tools-database==0.3.0
-llama-index-tools-google==0.3.1
+llama-index-tools-google==0.5.0
 llama-index-tools-tavily_research==0.3.0
 llama_index.tools.brave_search==0.3.0
 llama-index-tools-neo4j==0.3.0
@@ -26,11 +26,11 @@ llama-index-graph-stores-kuzu==0.7.0
 llama-index-tools-salesforce==0.3.0
 llama-index-tools-slack==0.3.0
 llama-index-tools-exa==0.3.0
-llama-index-tools-wikipedia==0.3.0
+llama-index-tools-wikipedia==0.3.1
 llama-index-tools-bing-search==0.3.0
-openai>=1.82.1
-tavily-python==0.7.3
-exa-py==1.13.1
+openai>=1.96.1
+tavily-python>=0.7.9
+exa-py>=1.14.8
 openinference-instrumentation-llama-index==4.3.1
 opentelemetry-proto>=1.31.0
 arize-phoenix==10.9.1
@@ -38,9 +38,9 @@ arize-phoenix-otel==0.10.3
 protobuf==5.29.3
 tokenizers>=0.20
 pydantic==2.11.5
+pandas==2.2.3
 retrying==1.3.4
 python-dotenv==1.0.1
-tiktoken==0.9.0
 cloudpickle>=3.1.1
 httpx==0.28.1
 commonmark==0.9.1

vectara_agentic-0.4.0/tests/__init__.py

@@ -0,0 +1,7 @@
+"""
+Tests package for vectara_agentic.
+"""
+
+# Suppress external dependency warnings globally for all tests
+import warnings
+warnings.simplefilter("ignore", DeprecationWarning)

vectara_agentic-0.4.0/tests/conftest.py

@@ -0,0 +1,312 @@
+# Suppress external dependency warnings before any other imports
+import warnings
+
+warnings.simplefilter("ignore", DeprecationWarning)
+
+"""
+Common test utilities, configurations, and fixtures for the vectara-agentic test suite.
+"""
+
+import unittest
+from contextlib import contextmanager
+from typing import Any
+
+from vectara_agentic.agent_config import AgentConfig
+from vectara_agentic.types import AgentType, ModelProvider
+
+
+# ========================================
+# Common Test Functions
+# ========================================
+
+def mult(x: float, y: float) -> float:
+    """Multiply two numbers - common test function used across multiple test files."""
+    return x * y
+
+
+def add(x: float, y: float) -> float:
+    """Add two numbers - common test function used in workflow tests."""
+    return x + y
+
+
+# ========================================
+# Common Test Data
+# ========================================
+
+# Standard test topic used across most tests
+STANDARD_TEST_TOPIC = "AI topic"
+
+# Standard test instructions used across most tests
+STANDARD_TEST_INSTRUCTIONS = "Always do as your father tells you, if your mother agrees!"
+
+# Alternative instructions for specific tests
+WORKFLOW_TEST_INSTRUCTIONS = "You are a helpful AI assistant."
+MATH_AGENT_INSTRUCTIONS = "you are an agent specializing in math, assisting a user."
+
+
+# ========================================
+# Agent Configuration Objects
+# ========================================
+
+# Default configurations
+default_config = AgentConfig()
+
+# Function Calling configurations for all providers
+fc_config_anthropic = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.ANTHROPIC,
+    tool_llm_provider=ModelProvider.ANTHROPIC,
+)
+
+fc_config_gemini = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.GEMINI,
+    tool_llm_provider=ModelProvider.GEMINI,
+)
+
+fc_config_together = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.TOGETHER,
+    tool_llm_provider=ModelProvider.TOGETHER,
+)
+
+fc_config_openai = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.OPENAI,
+    tool_llm_provider=ModelProvider.OPENAI,
+)
+
+fc_config_groq = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.GROQ,
+    tool_llm_provider=ModelProvider.GROQ,
+)
+
+fc_config_bedrock = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.BEDROCK,
+    tool_llm_provider=ModelProvider.BEDROCK,
+)
+
+# ReAct configurations for all providers
+react_config_anthropic = AgentConfig(
+    agent_type=AgentType.REACT,
+    main_llm_provider=ModelProvider.ANTHROPIC,
+    tool_llm_provider=ModelProvider.ANTHROPIC,
+)
+
+react_config_gemini = AgentConfig(
+    agent_type=AgentType.REACT,
+    main_llm_provider=ModelProvider.GEMINI,
+    main_llm_model_name="models/gemini-2.5-flash",
+    tool_llm_provider=ModelProvider.GEMINI,
+    tool_llm_model_name="models/gemini-2.5-flash",
+)
+
+react_config_together = AgentConfig(
+    agent_type=AgentType.REACT,
+    main_llm_provider=ModelProvider.TOGETHER,
+    tool_llm_provider=ModelProvider.TOGETHER,
+)
+
+react_config_groq = AgentConfig(
+    agent_type=AgentType.REACT,
+    main_llm_provider=ModelProvider.GROQ,
+    tool_llm_provider=ModelProvider.GROQ,
+)
+
+# Private LLM configurations
+private_llm_react_config = AgentConfig(
+    agent_type=AgentType.REACT,
+    main_llm_provider=ModelProvider.PRIVATE,
+    main_llm_model_name="gpt-4o",
+    private_llm_api_base="http://localhost:8000/v1",
+    tool_llm_provider=ModelProvider.PRIVATE,
+    tool_llm_model_name="gpt-4o",
+)
+
+private_llm_fc_config = AgentConfig(
+    agent_type=AgentType.FUNCTION_CALLING,
+    main_llm_provider=ModelProvider.PRIVATE,
+    main_llm_model_name="gpt-4.1",
+    private_llm_api_base="http://localhost:8000/v1",
+    tool_llm_provider=ModelProvider.PRIVATE,
+    tool_llm_model_name="gpt-4.1",
+)
+
+
+# ========================================
+# Error Detection and Testing Utilities
+# ========================================
+
+def is_rate_limited(response_text: str) -> bool:
+    """
+    Check if a response indicates a rate limit error from any LLM provider.
+
+    Args:
+        response_text: The response text from the agent
+
+    Returns:
+        bool: True if the response indicates rate limiting
+    """
+    rate_limit_indicators = [
+        # Generic indicators
+        "Error code: 429",
+        "rate_limit_exceeded",
+        "Rate limit reached",
+        "rate limit",
+        "quota exceeded",
+        "usage limit",
+        # GROQ-specific
+        "tokens per day",
+        "TPD",
+        "service tier",
+        "on_demand",
+        "deepseek-r1-distill-llama-70b",
+        "Upgrade to Dev Tier",
+        "console.groq.com/settings/billing",
+        # OpenAI-specific
+        "requests per minute",
+        "RPM",
+        "tokens per minute",
+        "TPM",
+        # Anthropic-specific
+        "overloaded_error",
+        "Overloaded",
+        "APIStatusError",
+        "anthropic.APIStatusError",
+        "usage_limit_exceeded",
+        # General API limit indicators
+        "try again in",
+        "Please wait",
+        "Too many requests",
+        "throttled",
+        # Additional rate limit patterns
+        "Limit.*Used.*Requested",
+        "Need more tokens",
+    ]
+
+    response_lower = response_text.lower()
+    return any(
+        indicator.lower() in response_lower for indicator in rate_limit_indicators
+    )
+
+
+def is_api_key_error(response_text: str) -> bool:
+    """
+    Check if a response indicates an API key authentication error.
+
+    Args:
+        response_text: The response text from the agent
+
+    Returns:
+        bool: True if the response indicates API key issues
+    """
+    api_key_indicators = [
+        "Error code: 401",
+        "Invalid API Key",
+        "authentication",
+        "unauthorized",
+        "invalid_api_key",
+        "missing api key",
+        "api key not found",
+    ]
+
+    response_lower = response_text.lower()
+    return any(indicator.lower() in response_lower for indicator in api_key_indicators)
+
+
+def skip_if_rate_limited(
+    test_instance: unittest.TestCase, response_text: str, provider: str = "LLM"
+) -> None:
+    """
+    Skip a test if the response indicates rate limiting.
+
+    Args:
+        test_instance: The test case instance
+        response_text: The response text to check
+        provider: The name of the provider (for clearer skip messages)
+    """
+    if is_rate_limited(response_text):
+        test_instance.skipTest(f"{provider} rate limit reached - skipping test")
+
+
+def skip_if_api_key_error(
+    test_instance: unittest.TestCase, response_text: str, provider: str = "LLM"
+) -> None:
+    """
+    Skip a test if the response indicates API key issues.
+
+    Args:
+        test_instance: The test case instance
+        response_text: The response text to check
+        provider: The name of the provider (for clearer skip messages)
+    """
+    if is_api_key_error(response_text):
+        test_instance.skipTest(f"{provider} API key invalid/missing - skipping test")
+
+
+def skip_if_provider_error(
+    test_instance: unittest.TestCase, response_text: str, provider: str = "LLM"
+) -> None:
+    """
+    Skip a test if the response indicates common provider errors (rate limiting or API key issues).
+
+    Args:
+        test_instance: The test case instance
+        response_text: The response text to check
+        provider: The name of the provider (for clearer skip messages)
+    """
+    skip_if_rate_limited(test_instance, response_text, provider)
+    skip_if_api_key_error(test_instance, response_text, provider)
+
+
+class AgentTestMixin:
+    """
+    Mixin class providing utility methods for agent testing.
+    """
+
+    @contextmanager
+    def with_provider_fallback(self, provider: str = "LLM"):
+        """
+        Context manager that catches and handles provider errors from any agent method.
+
+        Args:
+            provider: Provider name for error messages
+
+        Usage:
+            with self.with_provider_fallback("GROQ"):
+                response = agent.chat("test")
+
+            with self.with_provider_fallback("GROQ"):
+                async for chunk in agent.astream_chat("test"):
+                    pass
+
+        Raises:
+            unittest.SkipTest: If rate limiting or API key errors occur
+        """
+        try:
+            yield
+        except Exception as e:
+            error_text = str(e)
+            if is_rate_limited(error_text) or is_api_key_error(error_text):
+                self.skipTest(f"{provider} error: {error_text}")
+            raise
+
+    def check_response_and_skip(self, response: Any, provider: str = "LLM") -> Any:
+        """
+        Check response content and skip test if provider errors are detected.
+
+        Args:
+            response: The response object from agent method
+            provider: Provider name for error messages
+
+        Returns:
+            The response object if no errors detected
+
+        Raises:
+            unittest.SkipTest: If rate limiting or API key errors detected in response
+        """
+        response_text = getattr(response, "response", str(response))
+        skip_if_provider_error(self, response_text, provider)
+        return response