versionhq 1.1.6.4__py3-none-any.whl → 1.1.7.1__py3-none-any.whl

versionhq/__init__.py

@@ -17,7 +17,7 @@ from versionhq.team.model import Team, TeamOutput
 from versionhq.tool.model import Tool
 
 
-__version__ = "1.1.6.4"
+__version__ = "1.1.7.1"
 __all__ = [
     "Agent",
     "Customer",

versionhq/_utils/usage_metrics.py

@@ -7,18 +7,10 @@ class UsageMetrics(BaseModel):
     """
 
     total_tokens: int = Field(default=0, description="Total number of tokens used")
-    prompt_tokens: int = Field(
-        default=0, description="Number of tokens used in prompts"
-    )
-    cached_prompt_tokens: int = Field(
-        default=0, description="Number of cached prompt tokens used"
-    )
-    completion_tokens: int = Field(
-        default=0, description="Number of tokens used in completions"
-    )
-    successful_requests: int = Field(
-        default=0, description="Number of successful requests made"
-    )
+    prompt_tokens: int = Field(default=0, description="Number of tokens used in prompts")
+    cached_prompt_tokens: int = Field(default=0, description="Number of cached prompt tokens used")
+    completion_tokens: int = Field(default=0, description="Number of tokens used in completions")
+    successful_requests: int = Field(default=0, description="Number of successful requests made")
 
     def add_usage_metrics(self, usage_metrics: "UsageMetrics"):
         """

versionhq/agent/TEMPLATES/Backstory.py

@@ -0,0 +1,3 @@
+BACKSTORY="""You are a {role} with deep understanding of {knowledge} and highly skilled in {skillsets}.
+You have access to call the RAG tools that can {rag_tool_overview}. By leveraging these tools, your knowledge, and skillsets, you can identify competitive strategies that have been proven effective to achieve the goal: {goal}. Take these into consideration, create innovative solutions.
+"""

versionhq/agent/model.py

@@ -3,7 +3,8 @@ import uuid
 from abc import ABC
 from typing import Any, Dict, List, Optional, TypeVar, Union
 from dotenv import load_dotenv
-from pydantic import UUID4, BaseModel, Field, InstanceOf, PrivateAttr, model_validator
+from pydantic import UUID4, BaseModel, Field, InstanceOf, PrivateAttr, model_validator, field_validator
+from pydantic_core import PydanticCustomError
 
 from versionhq._utils.cache_handler import CacheHandler
 from versionhq._utils.logger import Logger
@@ -77,8 +78,9 @@ class TokenProcess:
 # @track_agent()
 class Agent(ABC, BaseModel):
     """
-    Base class for third-party agents that LLM runs.
-    The agent can execute tasks alone or team. When the agent belongs to team, it needs to prioritize the team.
+    Agent class that run on LLM.
+    Agents execute tasks alone or in the team, using RAG tools and knowledge base if any.
+    Agents will prioritize team tasks when they belong to the team.
     * (Temp) Comment out all the optional fields except for Team and LLM settings for convenience.
     """
 
@@ -90,96 +92,68 @@ class Agent(ABC, BaseModel):
     _times_executed: int = PrivateAttr(default=0)
 
     id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True)
-    agent_ops_agent_name: str = None
-    agent_ops_agent_id: str = None
     role: str = Field(description="role of the agent - used in summary and logs")
-    goal: str = Field(
-        description="concise goal of the agent (details are set in the Task instance)"
-    )
-    backstory: str = Field(description="context passed to the LLM")
+    goal: str = Field(description="concise goal of the agent (details are set in the Task instance)")
+    backstory: Optional[str] = Field(default=None, description="system context passed to the LLM")
+    knowledge: Optional[str] = Field(default=None)
+    skillsets: Optional[List[str]] = Field(default_factory=list)
 
     # tools
     tools: Optional[List[Any]] = Field(default_factory=list)
-    tool_handler: InstanceOf[ToolHandler] = Field(
-        default=None, description="handle tool cache and last used tool"
-    )
-
-    # team, rules of task executions
-    team: Optional[List[Any]] = Field(
-        default=None, description="Team to which the agent belongs"
-    )
-    allow_delegation: bool = Field(
-        default=False,
-        description="Enable agent to delegate and ask questions among each other",
-    )
-    allow_code_execution: Optional[bool] = Field(
-        default=False, description="Enable code execution for the agent."
-    )
-    max_retry_limit: int = Field(
-        default=2,
-        description="max. number of retries for the task execution when an error occurs. cascaed to the `invoke` function",
-    )
-    max_iter: Optional[int] = Field(
-        default=25,
-        description="max. number of iterations for an agent to execute a task",
-    )
-    step_callback: Optional[Any] = Field(
-        default=None,
-        description="Callback to be executed after each step of the agent execution",
-    )
+    tool_handler: InstanceOf[ToolHandler] = Field(default=None, description="handle tool cache and last used tool")
+
+    # team, task execution rules
+    team: Optional[List[Any]] = Field(default=None, description="Team to which the agent belongs")
+    allow_delegation: bool = Field(default=False,description="Enable agent to delegate and ask questions among each other")
+    allow_code_execution: Optional[bool] = Field(default=False, description="Enable code execution for the agent.")
+    max_retry_limit: int = Field(default=2,description="max. number of retries for the task execution when an error occurs. cascaed to the `invoke` function")
+    max_iter: Optional[int] = Field(default=25,description="max. number of iterations for an agent to execute a task")
+    step_callback: Optional[Any] = Field(default=None,description="Callback to be executed after each step of the agent execution")
 
     # llm settings cascaded to the LLM model
     llm: Union[str, InstanceOf[LLM], Any] = Field(default=None)
     function_calling_llm: Union[str, InstanceOf[LLM], Any] = Field(default=None)
-    respect_context_window: bool = Field(
-        default=True,
-        description="Keep messages under the context window size by summarizing content",
-    )
-    max_tokens: Optional[int] = Field(
-        default=None, description="max. number of tokens for the agent's execution"
-    )
-    max_execution_time: Optional[int] = Field(
-        default=None, description="max. execution time for an agent to execute a task"
-    )
-    max_rpm: Optional[int] = Field(
-        default=None,
-        description="max. number of requests per minute for the agent execution",
-    )
+    respect_context_window: bool = Field(default=True,description="Keep messages under the context window size by summarizing content")
+    max_tokens: Optional[int] = Field(default=None, description="max. number of tokens for the agent's execution")
+    max_execution_time: Optional[int] = Field(default=None, description="max. execution time for an agent to execute a task")
+    max_rpm: Optional[int] = Field(default=None, description="max. number of requests per minute for the agent execution")
 
     # prompt rules
-    use_system_prompt: Optional[bool] = Field(
-        default=True, description="Use system prompt for the agent"
-    )
-    system_template: Optional[str] = Field(
-        default=None, description="System format for the agent."
-    )
-    prompt_template: Optional[str] = Field(
-        default=None, description="Prompt format for the agent."
-    )
-    response_template: Optional[str] = Field(
-        default=None, description="Response format for the agent."
-    )
+    use_system_prompt: Optional[bool] = Field(default=True, description="Use system prompt for the agent")
+    system_template: Optional[str] = Field(default=None, description="System format for the agent.")
+    prompt_template: Optional[str] = Field(default=None, description="Prompt format for the agent.")
+    response_template: Optional[str] = Field(default=None, description="Response format for the agent.")
 
     # config, cache, error handling
-    config: Optional[Dict[str, Any]] = Field(
-        default=None, exclude=True, description="Configuration for the agent"
-    )
-    cache: bool = Field(
-        default=True, description="Whether the agent should use a cache for tool usage."
-    )
-    cache_handler: InstanceOf[CacheHandler] = Field(
-        default=None, description="An instance of the CacheHandler class."
-    )
-    formatting_errors: int = Field(
-        default=0, description="Number of formatting errors."
-    )
-    verbose: bool = Field(
-        default=True, description="Verbose mode for the Agent Execution"
-    )
+    config: Optional[Dict[str, Any]] = Field(default=None, exclude=True, description="Configuration for the agent")
+    cache: bool = Field(default=True, description="Whether the agent should use a cache for tool usage.")
+    cache_handler: InstanceOf[CacheHandler] = Field(default=None, description="An instance of the CacheHandler class.")
+    formatting_errors: int = Field(default=0, description="Number of formatting errors.")
+    verbose: bool = Field(default=True, description="Verbose mode for the Agent Execution")
+    agent_ops_agent_name: str = None
+    agent_ops_agent_id: str = None
+
 
     def __repr__(self):
         return f"Agent(role={self.role}, goal={self.goal}, backstory={self.backstory})"
 
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def _deny_user_set_id(cls, v: Optional[UUID4]) -> None:
+        if v:
+            raise PydanticCustomError("may_not_set_field", "This field is not to be set by the user.", {})
+
+
+    @model_validator(mode="after")
+    def validate_required_fields(self):
+        required_fields = ["role", "goal"]
+        for field in required_fields:
+            if getattr(self, field) is None:
+                raise ValueError( f"{field} must be provided either directly or through config")
+        return self
+
+
     @model_validator(mode="after")
     def set_up_llm(self):
         """
@@ -189,61 +163,27 @@ class Agent(ABC, BaseModel):
         """
 
         self.agent_ops_agent_name = self.role
-        unaccepted_attributes = [
-            "AWS_ACCESS_KEY_ID",
-            "AWS_SECRET_ACCESS_KEY",
-            "AWS_REGION_NAME",
-        ]
-        callbacks = (
-            [
-                self.step_callback,
-            ]
-            if self.step_callback is not None
-            else []
-        )
+        unaccepted_attributes = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_REGION_NAME"]
+        callbacks = ([self.step_callback,]if self.step_callback is not None else [])
 
         if isinstance(self.llm, LLM):
             self.llm.timeout = self.max_execution_time
             self.llm.max_tokens = self.max_tokens
-            self.llm.context_window_size = (
-                self.llm.get_context_window_size()
-                if self.respect_context_window == True
-                else DEFAULT_CONTEXT_WINDOW
-            )
+            self.llm.context_window_size = (self.llm.get_context_window_size() if self.respect_context_window == True else DEFAULT_CONTEXT_WINDOW)
             self.llm.callbacks = callbacks
 
-        elif isinstance(self.llm, str):
-            self.llm = LLM(
-                model=self.llm,
-                timeout=self.max_execution_time,
-                max_tokens=self.max_tokens,
-                callbacks=callbacks,
-            )
-
-            context_window_size = (
-                self.llm.get_context_window_size()
-                if self.respect_context_window == True
-                else DEFAULT_CONTEXT_WINDOW
-            )
-            self.llm.context_window_size = context_window_size
-
-        elif self.llm is None:
-            model_name = os.environ.get(
-                "LITELLM_MODEL_NAME", os.environ.get("MODEL", "gpt-4o-mini")
-            )
+        elif isinstance(self.llm, str) or self.llm is None:
+            model_name = os.environ.get("LITELLM_MODEL_NAME", os.environ.get("MODEL", "gpt-3.5-turbo"))
             llm_params = {
-                "model": model_name,
+                "model": model_name if self.llm is None else self.llm,
                 "timeout": self.max_execution_time,
                 "max_tokens": self.max_tokens,
                 "callbacks": callbacks,
+                "api_key": os.environ.get("LITELLM_API_KEY", None),
+                "base_url": os.environ.get("OPENAI_API_BASE", os.environ.get("OPENAI_BASE_URL", None))
             }
-            api_base = os.environ.get(
-                "OPENAI_API_BASE", os.environ.get("OPENAI_BASE_URL", None)
-            )
-            if api_base:
-                llm_params["base_url"] = api_base
 
-            set_provider = model_name.split("/")[0] if "/" in model_name else "openai"
+            set_provider = model_name.split("/")[0] if "/" in model_name else "openai" #! REFINEME
             for provider, env_vars in LLM_VARS.items():
                 if provider == set_provider:
                     for env_var in env_vars:
@@ -252,17 +192,9 @@ class Agent(ABC, BaseModel):
                         if key_name and key_name not in unaccepted_attributes:
                             env_value = os.environ.get(key_name)
                             if env_value:
-                                key_name = (
-                                    "api_key" if "API_KEY" in key_name else key_name
-                                )
-                                key_name = (
-                                    "api_base" if "API_BASE" in key_name else key_name
-                                )
-                                key_name = (
-                                    "api_version"
-                                    if "API_VERSION" in key_name
-                                    else key_name
-                                )
+                                key_name = ("api_key" if "API_KEY" in key_name else key_name)
+                                key_name = ("api_base" if "API_BASE" in key_name else key_name)
+                                key_name = ("api_version" if "API_VERSION" in key_name else key_name)
                                 llm_params[key_name] = env_value
                         elif env_var.get("default", False):
                             for key, value in env_var.items():
@@ -270,34 +202,22 @@ class Agent(ABC, BaseModel):
                                     if key in os.environ:
                                         llm_params[key] = value
             self.llm = LLM(**llm_params)
-            context_window_size = (
-                self.llm.get_context_window_size()
-                if self.respect_context_window == True
-                else DEFAULT_CONTEXT_WINDOW
-            )
+            context_window_size = (self.llm.get_context_window_size() if self.respect_context_window == True else DEFAULT_CONTEXT_WINDOW)
             self.llm.context_window_size = context_window_size
 
         else:
             llm_params = {
-                "model": (
-                    getattr(self.llm, "model_name")
-                    or getattr(self.llm, "deployment_name")
-                    or str(self.llm)
-                ),
-                "max_tokens": (
-                    getattr(self.llm, "max_tokens") or self.max_tokens or 3000
-                ),
+                "model": (getattr(self.llm, "model_name") or getattr(self.llm, "deployment_name") or str(self.llm)),
+                "max_tokens": (getattr(self.llm, "max_tokens") or self.max_tokens or 3000),
                 "timeout": getattr(self.llm, "timeout", self.max_execution_time),
                 "callbacks": getattr(self.llm, "callbacks") or callbacks,
                 "temperature": getattr(self.llm, "temperature", None),
                 "logprobs": getattr(self.llm, "logprobs", None),
-                "api_key": getattr(self.llm, "api_key", None),
+                "api_key": getattr(self.llm, "api_key", os.environ.get("LITELLM_API_KEY", None)),
                 "base_url": getattr(self.llm, "base_url", None),
                 "organization": getattr(self.llm, "organization", None),
             }
-            llm_params = {
-                k: v for k, v in llm_params.items() if v is not None
-            }  # factor out None values
+            llm_params = {  k: v for k, v in llm_params.items() if v is not None }
             self.llm = LLM(**llm_params)
 
         """
@@ -348,6 +268,7 @@ class Agent(ABC, BaseModel):
                     )
         return self
 
+
     @model_validator(mode="after")
     def set_up_tools(self):
         """
@@ -371,13 +292,30 @@ class Agent(ABC, BaseModel):
 
         return self
 
+
+    @model_validator(mode="after")
+    def set_up_backstory(self):
+        """
+        Set up the backstory using a templated BACKSTORY when the backstory is None
+        """
+
+        if self.backstory is None:
+            from versionhq.agent.TEMPLATES.Backstory import BACKSTORY
+            backstory = BACKSTORY.format(
+                role=self.role,
+                knowledge=self.knowledge if isinstance(self.knowledge, str) else None,
+                skillsets=", ".join([item for item in self.skillsets]),
+                rag_tool_overview=", ".join([item.name for item in self.tools]),
+                goal=self.goal,
+            )
+            self.backstory = backstory
+
+        return self
+
+
     def invoke(
-        self,
-        prompts: str,
-        output_formats: List[TaskOutputFormat],
-        response_fields: List[ResponseField],
-        **kwargs,
-    ) -> Dict[str, Any]:
+            self, prompts: str, output_formats: List[TaskOutputFormat], response_fields: List[ResponseField], **kwargs
+            ) -> Dict[str, Any]:
         """
         Receive the system prompt in string and create formatted prompts using the system prompt and the agent's backstory.
         Then call the base model.
@@ -402,9 +340,7 @@ class Agent(ABC, BaseModel):
         task_execution_counter += 1
         print("Agent's #1 res: ", response)
 
-        if (
-            response is None or response == ""
-        ) and task_execution_counter < self.max_retry_limit:
+        if (response is None or response == "") and task_execution_counter < self.max_retry_limit:
             while task_execution_counter <= self.max_retry_limit:
                 response = self.llm.call(
                     messages=messages,
@@ -421,6 +357,7 @@ class Agent(ABC, BaseModel):
 
         return {"output": response.output if hasattr(response, "output") else response}
 
+
     def execute_task(self, task, context: Optional[str] = None) -> str:
         """
         Execute the task and return the output in string.
@@ -430,8 +367,8 @@ class Agent(ABC, BaseModel):
         """
 
         task_prompt = task.prompt()
-        # if context:
-        #     task_prompt = self.i18n.slice("task_with_context").format(task=task_prompt, context=context)
+        if context:
+            task_prompt += context
 
         tool_results = []
         if task.tools_called: