vectara-agentic 0.1.15__tar.gz → 0.1.17__tar.gz

{vectara_agentic-0.1.15/vectara_agentic.egg-info → vectara_agentic-0.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vectara_agentic
-Version: 0.1.15
+Version: 0.1.17
 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,25 +16,25 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: llama-index==0.11.13
+Requires-Dist: llama-index==0.11.20
 Requires-Dist: llama-index-indices-managed-vectara==0.2.2
 Requires-Dist: llama-index-agent-llm-compiler==0.2.0
 Requires-Dist: llama-index-agent-openai==0.3.4
-Requires-Dist: llama-index-llms-openai==0.2.9
-Requires-Dist: llama-index-llms-anthropic==0.3.1
+Requires-Dist: llama-index-llms-openai==0.2.16
+Requires-Dist: llama-index-llms-anthropic==0.3.7
 Requires-Dist: llama-index-llms-together==0.2.0
 Requires-Dist: llama-index-llms-groq==0.2.0
-Requires-Dist: llama-index-llms-fireworks==0.2.0
-Requires-Dist: llama-index-llms-cohere==0.3.0
-Requires-Dist: llama-index-llms-gemini==0.3.5
+Requires-Dist: llama-index-llms-fireworks==0.2.2
+Requires-Dist: llama-index-llms-cohere==0.3.1
+Requires-Dist: llama-index-llms-gemini==0.3.7
 Requires-Dist: llama-index-tools-yahoo-finance==0.2.0
 Requires-Dist: llama-index-tools-arxiv==0.2.0
 Requires-Dist: llama-index-tools-database==0.2.0
 Requires-Dist: llama-index-tools-google==0.2.0
 Requires-Dist: llama-index-tools-tavily_research==0.2.0
+Requires-Dist: llama-index-tools-neo4j==0.2.0
 Requires-Dist: tavily-python==0.5.0
 Requires-Dist: yahoo-finance==1.4.0
-Requires-Dist: llama-index-tools-neo4j==0.2.0
 Requires-Dist: openinference-instrumentation-llama-index==3.0.2
 Requires-Dist: arize-phoenix==4.35.1
 Requires-Dist: arize-phoenix-otel==0.5.1
@@ -68,13 +68,29 @@ Requires-Dist: dill==0.3.8
 
 ## ✨ Overview
 
-`vectara-agentic` is a Python library for developing powerful AI assistants using Vectara and Agentic-RAG. It leverages the LlamaIndex Agent framework, customized for use with Vectara.
+`vectara-agentic` is a Python library for developing powerful AI assistants and agents using Vectara and Agentic-RAG. It leverages the LlamaIndex Agent framework, customized for use with Vectara.
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/vectara/py-vectara-agentic/main/.github/assets/diagram1.png" alt="Agentic RAG diagram" width="100%" style="vertical-align: middle;">
+</p>
 
-###  Key Features
+###  Features
 
+- Enables easy creation of custom AI assistants and agents.
+- Create a Vectara RAG tool with a single line of code.
 - Supports `ReAct`, `OpenAIAgent` and `LLMCompiler` agent types.
 - Includes pre-built tools for various domains (e.g., finance, legal).
-- Enables easy creation of custom AI assistants and agents.
+- Integrates with various LLM inference services like OpenAI, Anthropic, Gemini, GROQ, Together.AI, Cohere and Fireworks
+- Built-in support for observability with Arize Phoenix
+
+### 📚 Example AI Assistants
+
+Check out our example AI assistants:
+
+- [Financial Assistant](https://huggingface.co/spaces/vectara/finance-chat)
+- [Justice Harvard Teaching Assistant](https://huggingface.co/spaces/vectara/Justice-Harvard)
+- [Legal Assistant](https://huggingface.co/spaces/vectara/legal-agent)
+
 
 ###  Prerequisites
 
@@ -197,7 +213,15 @@ When creating a VectaraToolFactory, you can pass in a `vectara_api_key`, `vectar
 
 ## ℹ️ Additional Information
 
-###  Agent Diagnostics
+### About Custom Instructions for your Agent
+
+The custom instructions you provide to the agent guide its behavior.
+Here are some guidelines when creating your instructions:
+- Write precise and clear instructions, without overcomplicating.
+- Consider edge cases and unusual or atypical scenarios.
+- Be cautious to not over-specify behavior based on your primary use-case, as it may limit the agent's ability to behave properly in others.
+
+###  Diagnostics
 
 The `Agent` class defines a few helpful methods to help you understand the internals of your application. 
 * The `report()` method prints out the agent object’s type, the tools, and the LLMs used for the main agent and tool calling.
@@ -224,21 +248,43 @@ Then you can use Arize Phoenix in three ways:
 Now when you run your agent, all call traces are sent to Phoenix and recorded. 
 In addition, vectara-agentic also records `FCS` (factual consistency score, aka HHEM) values into Arize for every Vectara RAG call. You can see those results in the `Feedback` column of the arize UI.
 
-### About Custom Instructions
+## 🌐 API Endpoint
 
-The custom instructions you provide to the agent guide its behavior.
-Here are some guidelines when creating your instructions:
-- Write precise and clear instructions, without overcomplicating.
-- Consider edge cases and unusual or atypical scenarios.
-- Be cautious to not over-specify behavior based on your primary use-case, as it may limit the agent's ability to behave properly in others.
+`vectara-agentic` can be easily hosted locally or on a remote machine behind an API endpoint, by following theses steps:
 
-## 📚 Examples
+### Step 1: Setup your API key
+Ensure that you have your API key set up as an environment variable:
 
-Check out our example AI assistants:
+```
+export VECTARA_AGENTIC_API_KEY=<YOUR-ENDPOINT-API-KEY>
+```
 
-- [Financial Assistant](https://huggingface.co/spaces/vectara/finance-chat)
-- [Justice Harvard Teaching Assistant](https://huggingface.co/spaces/vectara/Justice-Harvard)
-- [Legal Assistant](https://huggingface.co/spaces/vectara/legal-agent)
+### Step 2: Start the API Server
+Initialize the agent and start the FastAPI server by following this example:
+
+
+```
+from agent import Agent
+from agent_endpoint import start_app
+agent = Agent(...)            # Initialize your agent with appropriate parameters
+start_app(agent)
+```
+
+You can customize the host and port by passing them as arguments to `start_app()`:
+* Default: host="0.0.0.0" and port=8000.
+For example:
+```
+start_app(agent, host="0.0.0.0", port=8000)
+```
+
+### Step 3: Access the API Endpoint
+Once the server is running, you can interact with it using curl or any HTTP client. For example:
+
+```
+curl -G "http://<remote-server-ip>:8000/chat" \
+--data-urlencode "message=What is Vectara?" \
+-H "X-API-Key: <YOUR-API-KEY>"
+```
 
 ## 🤝 Contributing
 

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/README.md

@@ -20,13 +20,29 @@
 
 ## ✨ Overview
 
-`vectara-agentic` is a Python library for developing powerful AI assistants using Vectara and Agentic-RAG. It leverages the LlamaIndex Agent framework, customized for use with Vectara.
+`vectara-agentic` is a Python library for developing powerful AI assistants and agents using Vectara and Agentic-RAG. It leverages the LlamaIndex Agent framework, customized for use with Vectara.
 
-###  Key Features
+<p align="center">
+<img src="https://raw.githubusercontent.com/vectara/py-vectara-agentic/main/.github/assets/diagram1.png" alt="Agentic RAG diagram" width="100%" style="vertical-align: middle;">
+</p>
+
+###  Features
 
+- Enables easy creation of custom AI assistants and agents.
+- Create a Vectara RAG tool with a single line of code.
 - Supports `ReAct`, `OpenAIAgent` and `LLMCompiler` agent types.
 - Includes pre-built tools for various domains (e.g., finance, legal).
-- Enables easy creation of custom AI assistants and agents.
+- Integrates with various LLM inference services like OpenAI, Anthropic, Gemini, GROQ, Together.AI, Cohere and Fireworks
+- Built-in support for observability with Arize Phoenix
+
+### 📚 Example AI Assistants
+
+Check out our example AI assistants:
+
+- [Financial Assistant](https://huggingface.co/spaces/vectara/finance-chat)
+- [Justice Harvard Teaching Assistant](https://huggingface.co/spaces/vectara/Justice-Harvard)
+- [Legal Assistant](https://huggingface.co/spaces/vectara/legal-agent)
+
 
 ###  Prerequisites
 
@@ -149,7 +165,15 @@ When creating a VectaraToolFactory, you can pass in a `vectara_api_key`, `vectar
 
 ## ℹ️ Additional Information
 
-###  Agent Diagnostics
+### About Custom Instructions for your Agent
+
+The custom instructions you provide to the agent guide its behavior.
+Here are some guidelines when creating your instructions:
+- Write precise and clear instructions, without overcomplicating.
+- Consider edge cases and unusual or atypical scenarios.
+- Be cautious to not over-specify behavior based on your primary use-case, as it may limit the agent's ability to behave properly in others.
+
+###  Diagnostics
 
 The `Agent` class defines a few helpful methods to help you understand the internals of your application. 
 * The `report()` method prints out the agent object’s type, the tools, and the LLMs used for the main agent and tool calling.
@@ -176,21 +200,43 @@ Then you can use Arize Phoenix in three ways:
 Now when you run your agent, all call traces are sent to Phoenix and recorded. 
 In addition, vectara-agentic also records `FCS` (factual consistency score, aka HHEM) values into Arize for every Vectara RAG call. You can see those results in the `Feedback` column of the arize UI.
 
-### About Custom Instructions
+## 🌐 API Endpoint
 
-The custom instructions you provide to the agent guide its behavior.
-Here are some guidelines when creating your instructions:
-- Write precise and clear instructions, without overcomplicating.
-- Consider edge cases and unusual or atypical scenarios.
-- Be cautious to not over-specify behavior based on your primary use-case, as it may limit the agent's ability to behave properly in others.
+`vectara-agentic` can be easily hosted locally or on a remote machine behind an API endpoint, by following theses steps:
 
-## 📚 Examples
+### Step 1: Setup your API key
+Ensure that you have your API key set up as an environment variable:
 
-Check out our example AI assistants:
+```
+export VECTARA_AGENTIC_API_KEY=<YOUR-ENDPOINT-API-KEY>
+```
 
-- [Financial Assistant](https://huggingface.co/spaces/vectara/finance-chat)
-- [Justice Harvard Teaching Assistant](https://huggingface.co/spaces/vectara/Justice-Harvard)
-- [Legal Assistant](https://huggingface.co/spaces/vectara/legal-agent)
+### Step 2: Start the API Server
+Initialize the agent and start the FastAPI server by following this example:
+
+
+```
+from agent import Agent
+from agent_endpoint import start_app
+agent = Agent(...)            # Initialize your agent with appropriate parameters
+start_app(agent)
+```
+
+You can customize the host and port by passing them as arguments to `start_app()`:
+* Default: host="0.0.0.0" and port=8000.
+For example:
+```
+start_app(agent, host="0.0.0.0", port=8000)
+```
+
+### Step 3: Access the API Endpoint
+Once the server is running, you can interact with it using curl or any HTTP client. For example:
+
+```
+curl -G "http://<remote-server-ip>:8000/chat" \
+--data-urlencode "message=What is Vectara?" \
+-H "X-API-Key: <YOUR-API-KEY>"
+```
 
 ## 🤝 Contributing
 

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/requirements.txt

@@ -1,22 +1,22 @@
-llama-index==0.11.13
+llama-index==0.11.20
 llama-index-indices-managed-vectara==0.2.2
 llama-index-agent-llm-compiler==0.2.0
 llama-index-agent-openai==0.3.4
-llama-index-llms-openai==0.2.9
-llama-index-llms-anthropic==0.3.1
+llama-index-llms-openai==0.2.16
+llama-index-llms-anthropic==0.3.7
 llama-index-llms-together==0.2.0
 llama-index-llms-groq==0.2.0
-llama-index-llms-fireworks==0.2.0
-llama-index-llms-cohere==0.3.0
-llama-index-llms-gemini==0.3.5
+llama-index-llms-fireworks==0.2.2
+llama-index-llms-cohere==0.3.1
+llama-index-llms-gemini==0.3.7
 llama-index-tools-yahoo-finance==0.2.0
 llama-index-tools-arxiv==0.2.0
 llama-index-tools-database==0.2.0
 llama-index-tools-google==0.2.0
 llama-index-tools-tavily_research==0.2.0
+llama-index-tools-neo4j==0.2.0
 tavily-python==0.5.0
 yahoo-finance==1.4.0
-llama-index-tools-neo4j==0.2.0
 openinference-instrumentation-llama-index==3.0.2
 arize-phoenix==4.35.1
 arize-phoenix-otel==0.5.1

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/setup.py

@@ -8,7 +8,7 @@ def read_requirements():
 
 setup(
     name="vectara_agentic",
-    version="0.1.15",
+    version="0.1.17",
     author="Ofer Mendelevitch",
     author_email="ofer@vectara.com",
     description="A Python package for creating AI Assistants and AI Agents with Vectara",

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/vectara_agentic/__init__.py

@@ -3,7 +3,7 @@ vectara_agentic package.
 """
 
 # Define the package version
-__version__ = "0.1.15"
+__version__ = "0.1.17"
 
 # Import classes and functions from modules
 # from .module1 import Class1, function1
@@ -12,6 +12,7 @@ __version__ = "0.1.15"
 
 # Any initialization code
 def initialize_package():
+    """print a message when the package is initialized."""
     print(f"Initializing vectara-agentic version {__version__}...")
 
 

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/vectara_agentic/_callback.py

@@ -66,7 +66,6 @@ class AgentCallbackHandler(BaseCallbackHandler):
 
     def _handle_agent_step(self, payload: dict) -> None:
         """Calls self.fn() with the information about agent step."""
-        print(f"Handling agent step: {payload}")
         if EventPayload.MESSAGES in payload:
             msg = str(payload.get(EventPayload.MESSAGES))
             if self.fn:

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/vectara_agentic/_observability.py

@@ -1,19 +1,21 @@
+"""
+Observability for Vectara Agentic.
+"""
 import os
 import json
+from typing import Optional, Union
 import pandas as pd
-
 from .types import ObserverType
 
 def setup_observer() -> bool:
     '''
     Setup the observer.
     '''
+    import phoenix as px
+    from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
+    from phoenix.otel import register
     observer = ObserverType(os.getenv("VECTARA_AGENTIC_OBSERVER_TYPE", "NO_OBSERVER"))
     if observer == ObserverType.ARIZE_PHOENIX:
-        import phoenix as px
-        from phoenix.otel import register
-        from openinference.instrumentation.llama_index import LlamaIndexInstrumentor
-
         phoenix_endpoint = os.getenv("PHOENIX_ENDPOINT", None)
         if not phoenix_endpoint:
             px.launch_app()
@@ -21,7 +23,7 @@ def setup_observer() -> bool:
         elif 'app.phoenix.arize.com' in phoenix_endpoint:   # hosted on Arizze
             phoenix_api_key = os.getenv("PHOENIX_API_KEY", None)
             if not phoenix_api_key:
-                raise Exception("Arize Phoenix API key not set. Please set PHOENIX_API_KEY environment variable.")
+                raise ValueError("Arize Phoenix API key not set. Please set PHOENIX_API_KEY environment variable.")
             os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={phoenix_api_key}"
             os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com"
             tracer_provider = register(endpoint=phoenix_endpoint, project_name="vectara-agentic")
@@ -29,12 +31,11 @@ def setup_observer() -> bool:
             tracer_provider = register(endpoint=phoenix_endpoint, project_name="vectara-agentic")
         LlamaIndexInstrumentor().instrument(tracer_provider=tracer_provider)
         return True
-    else:
-        print("No observer set.")
-        return False
+    print("No observer set.")
+    return False
 
 
-def _extract_fcs_value(output):
+def _extract_fcs_value(output: Union[str, dict]) -> Optional[float]:
     '''
     Extract the FCS value from the output.
     '''
@@ -49,7 +50,7 @@ def _extract_fcs_value(output):
     return None
 
 
-def _find_top_level_parent_id(row, all_spans):
+def _find_top_level_parent_id(row: pd.Series, all_spans: pd.DataFrame) -> Optional[str]:
     '''
     Find the top level parent id for the given span.
     '''
@@ -67,14 +68,13 @@ def _find_top_level_parent_id(row, all_spans):
     return current_id
 
 
-def eval_fcs():
+def eval_fcs() -> None:
     '''
     Evaluate the FCS score for the VectaraQueryEngine._query span.
     '''
+    import phoenix as px
     from phoenix.trace.dsl import SpanQuery
     from phoenix.trace import SpanEvaluations
-    import phoenix as px
-
     query = SpanQuery().select(
         "output.value",
         "parent_id",
@@ -83,8 +83,10 @@ def eval_fcs():
     client = px.Client()
     all_spans = client.query_spans(query, project_name="vectara-agentic")
     vectara_spans = all_spans[all_spans['name'] == 'VectaraQueryEngine._query'].copy()
-    vectara_spans['top_level_parent_id'] = vectara_spans.apply(lambda row: _find_top_level_parent_id(row, all_spans), axis=1)
-    vectara_spans['score'] = vectara_spans['output.value'].apply(lambda x: _extract_fcs_value(x))
+    vectara_spans['top_level_parent_id'] = vectara_spans.apply(
+        lambda row: _find_top_level_parent_id(row, all_spans), axis=1
+    )
+    vectara_spans['score'] = vectara_spans['output.value'].apply(_extract_fcs_value)
 
     vectara_spans.reset_index(inplace=True)
     top_level_spans = vectara_spans.copy()

{vectara_agentic-0.1.15 → vectara_agentic-0.1.17}/vectara_agentic/_prompts.py

@@ -7,10 +7,10 @@ GENERAL_INSTRUCTIONS = """
 - Use tools as your main source of information, do not respond without using a tool. Do not respond based on pre-trained knowledge.
 - When using a tool with arguments, simplify the query as much as possible if you use the tool with arguments.
   For example, if the original query is "revenue for apple in 2021", you can use the tool with a query "revenue" with arguments year=2021 and company=apple.
-- If you can't answer the question with the information provided by the tools, try to rephrase the question and call a tool again,
+- If you can't answer the question with the information provided by a tool, try to rephrase the question and call the tool again,
   or break the question into sub-questions and call a tool for each sub-question, then combine the answers to provide a complete response.
   For example if asked "what is the population of France and Germany", you can call the tool twice, once for each country.
-- If a query tool provides citations or references in markdown as part of its response, include the citations in your response.
+- If a query tool provides citations or references in markdown as part of its response, include the references in your response.
 - When providing links in your response, where possible put the name of the website or source of information for the displayed text. Don't just say 'source'.
 - If after retrying you can't get the information or answer the question, respond with "I don't know".
 - Your response should never be the input to a tool, only the output.
@@ -21,6 +21,14 @@ GENERAL_INSTRUCTIONS = """
 - If including latex equations in the markdown response, make sure the equations are on a separate line and enclosed in double dollar signs.
 - Always respond in the language of the question, and in text (no images, videos or code).
 - Always call the "get_bad_topics" tool to determine the topics you are not allowed to discuss or respond to.
+- If you are provided with database tools use them for analytical queries (such as counting, calculating max, min, average, sum, or other statistics).
+  For each database, the database tools include: x_list_tables, x_load_data, x_describe_tables, and x_load_sample_data, where 'x' in the database name.
+  The x_list_tables tool provides a list of available tables in the x database.
+  Always use the x_describe_tables tool to understand the schema of each table, before you access data from that table.
+  Always use the x_load_sample_data tool to understand the column names, and the unique values in each column, so you can use them in your queries.
+  Some times the user may ask for a specific column value, but the actual value in the table may be different, and you will need to use the correct value.
+- Never call x_load_data to retrieve values from each row in the table.
+- Do not mention table names or database names in your response.
 """
 
 #
@@ -65,10 +73,7 @@ IMPORTANT - FOLLOW THESE INSTRUCTIONS CAREFULLY:
 {INSTRUCTIONS}
 {custom_instructions}
 
-## Input
-The user will specify a task or a question in text.
-
-### Output Format
+## Output Format
 
 Please answer in the same language as the question and use the following format:
 
@@ -95,12 +100,12 @@ At that point, you MUST respond in the one of the following two formats (and do
 
 ```
 Thought: I can answer without using any more tools. I'll use the user's language to answer
-Answer: [your answer here (In the same language as the user's question, and maintain any references/citations)]
+Answer: [your answer here (In the same language as the user's question, and maintain any references)]
 ```
 
 ```
 Thought: I cannot answer the question with the provided tools.
-Answer: [your answer here (In the same language as the user's question, and maintain any references/citations)]
+Answer: [your answer here (In the same language as the user's question)]
 ```
 
 ## Current Conversation