versionhq 1.1.12.1__py3-none-any.whl → 1.1.12.3__py3-none-any.whl

versionhq/task/TEMPLATES/Description.py

@@ -1,5 +1,5 @@
-EVALUATE="""Assess the accuracy and quality of the following task output to the task described below. Score based on the criterion (0-1, 0=worst, 1=best) and suggest improvements. Vary scores; don't assign identical values. Store criteria in the "criteria" field.
-Task: {task_description}
-Task Output: {task_output}
+EVALUATE="""Evaluate the provided task output against the given task description, assigning a score between 0 (worst) and 1 (best) based on the specified criteria. Scores should be numerical (integers or decimals). Provide specific suggestions for improvement. Do not assign identical scores to different criteria:
+Task output: {task_output}
+Task description: {task_description}
 Evaluation criteria: {eval_criteria}
 """

versionhq/task/__init__.py

@@ -1,9 +0,0 @@
-from enum import Enum
-
-
-class TaskOutputFormat(str, Enum):
-    """Enum that represents the output format of a task."""
-
-    JSON = "json"
-    PYDANTIC = "pydantic model"
-    RAW = "raw"

versionhq/task/evaluate.py

@@ -3,6 +3,8 @@ from typing_extensions import Self
 
 from pydantic import BaseModel, Field, model_validator
 
+from versionhq.memory.model import MemoryMetadata
+
 """
 Evaluate task output from accuracy, token consumption, latency perspectives, and mark the score from 0 to 1.
 """
@@ -59,10 +61,10 @@ class EvaluationItem(BaseModel):
     """
     criteria: str
     suggestion: str
-    score: int | float
+    score: float
 
     def _convert_score_to_score_format(self, weight: int = 1) -> ScoreFormat | None:
-        if self.score and isinstance(self.score, (int, float)):
+        if self.score and isinstance(self.score, float):
             return ScoreFormat(rate=self.score, weight=weight)
 
         else: return None
@@ -75,7 +77,6 @@ class Evaluation(BaseModel):
     tokens: int = Field(default=None, description="tokens consumed")
     responsible_agent: Any = Field(default=None, description="store agent instance that evaluates the outcome")
 
-
     @model_validator(mode="after")
     def set_up_responsible_agent(self) -> Self:
         from versionhq.agent.inhouse_agents import vhq_task_evaluator
@@ -83,6 +84,18 @@ class Evaluation(BaseModel):
         return self
 
 
+    def _create_memory_metadata(self) -> MemoryMetadata:
+        """
+        Create and store evaluation results in the memory metadata
+        """
+        eval_by = self.responsible_agent.role if self.responsible_agent else None
+        score = self.aggregate_score
+        eval_criteria = ", ".join([item.criteria for item in self.items]) if self.items else None
+        suggestion = self.suggestion_summary
+        memory_metadata = MemoryMetadata(eval_by=eval_by, score=score, eval_criteria=eval_criteria, suggestion=suggestion)
+        return memory_metadata
+
+
     @property
     def aggregate_score(self) -> float:
         """

versionhq/task/formation.py

@@ -0,0 +1,114 @@
+from typing import List
+from enum import Enum
+
+from pydantic import BaseModel
+
+from versionhq.task.model import Task
+from versionhq.agent.model import Agent
+from versionhq.team.model import Team, TeamMember, Formation
+from versionhq.agent.inhouse_agents  import vhq_formation_planner
+from versionhq._utils import Logger
+
+
+def form_agent_network(
+        task: str,
+        expected_outcome: str,
+        agents: List[Agent] = None,
+        context: str = None,
+        formation: Formation = None
+    ) -> Team | None:
+    """
+    Make a formation of agents from the given task description, agents (optional), context (optional), and expected outcome (optional).
+    """
+
+    if not task:
+        Logger(verbose=True).log(level="error", message="Missing task description.", color="red")
+        return None
+
+    if not expected_outcome:
+        Logger(verbose=True).log(level="error", message="Missing expected outcome.", color="red")
+        return None
+
+
+    try:
+        class Outcome(BaseModel):
+            formation: Enum
+            agent_roles: list[str]
+            task_descriptions: list[str]
+            leader_agent: str
+
+        vhq_task = Task(
+            description=f"""
+    Create a team of specialized agents designed to automate the following task and deliver the expected outcome. Consider the necessary roles for each agent with a clear task description. If you think we neeed a leader to handle the automation, return a leader_agent role as well, but if not, leave the a leader_agent role blank.
+    Task: {str(task)}
+    Expected outcome: {str(expected_outcome)}
+            """,
+            pydantic_output=Outcome
+        )
+
+        if formation:
+            vhq_task.description += f"Select 1 formation you think the best from the given Enum sets: {str(Formation.__dict__)}"
+
+        if agents:
+            vhq_task.description += "Consider adding following agents in the formation: " + ", ".join([agent.role for agent in agents if isinstance(agent, Agent)])
+
+        res = vhq_task.execute_sync(agent=vhq_formation_planner, context=context)
+        formation_ = Formation.SUPERVISING
+
+        if res.pydantic:
+            formation_keys = [k for k, v in Formation._member_map_.items() if k == res.pydantic.formation.upper()]
+
+            if formation_keys:
+                formation_ = Formation[formation_keys[0]]
+
+            created_agents = [Agent(role=item, goal=item) for item in res.pydantic.agent_roles]
+            created_tasks = [Task(description=item) for item in res.pydantic.task_descriptions]
+            team_tasks = []
+            members = []
+            leader = str(res.pydantic.leader_agent)
+
+            for i in range(len(created_agents)):
+                is_manager = bool(created_agents[i].role.lower() in leader.lower())
+                member = TeamMember(agent=created_agents[i], is_manager=is_manager)
+
+                if len(created_tasks) >= i:
+                    member.task = created_tasks[i]
+                    members.append(member)
+
+            if len(created_agents) < len(created_tasks):
+                team_tasks.extend(created_tasks[len(created_agents) - 1:len(created_tasks)])
+
+            members.sort(key=lambda x: x.is_manager == False)
+            team = Team(members=members, formation=formation_)
+            return team
+
+        else:
+            formation_keys = [k for k, v in Formation._member_map_.items() if k == res.json_dict["formation"].upper()]
+
+            if formation_keys:
+                formation_ = Formation[formation_keys[0]]
+
+            created_agents = [Agent(role=item, goal=item) for item in res.json_dict["agent_roles"]]
+            created_tasks = [Task(description=item) for item in res.json_dict["task_descriptions"]]
+            team_tasks = []
+            members = []
+            leader = str(res.json_dict["leader_agent"])
+
+            for i in range(len(created_agents)):
+                is_manager = bool(created_agents[i].role.lower() in leader.lower())
+                member = TeamMember(agent=created_agents[i], is_manager=is_manager)
+
+                if len(created_tasks) >= i:
+                    member.task = created_tasks[i]
+                    members.append(member)
+
+            if len(created_agents) < len(created_tasks):
+                team_tasks.extend(created_tasks[len(created_agents) - 1:len(created_tasks)])
+
+            members.sort(key=lambda x: x.is_manager == True)
+            team = Team(members=members, formation=formation_)
+            return team
+
+    except Exception as e:
+        Logger(verbose=True).log(level="error", message=f"Failed to create an agent network - return None. You can try with solo agent. Error: {str(e)}", color="red")
+        return None

versionhq/task/model.py

@@ -5,18 +5,17 @@ import uuid
 import inspect
 from concurrent.futures import Future
 from hashlib import md5
-from typing import Any, Dict, List, Set, Optional, Tuple, Callable, Type, TypeVar
+from typing import Any, Dict, List, Set, Optional, Callable, Type
 from typing_extensions import Annotated, Self
 
 from pydantic import UUID4, BaseModel, Field, PrivateAttr, field_validator, model_validator, InstanceOf, field_validator
 from pydantic_core import PydanticCustomError
 
-from versionhq._utils.process_config import process_config
-from versionhq.task import TaskOutputFormat
+
 from versionhq.task.log_handler import TaskOutputStorageHandler
 from versionhq.task.evaluate import Evaluation, EvaluationItem
 from versionhq.tool.model import Tool, ToolSet
-from versionhq._utils.logger import Logger
+from versionhq._utils import process_config, Logger
 
 
 class ResponseField(BaseModel):
@@ -77,9 +76,7 @@ class ResponseField(BaseModel):
             if self.properties:
                 for item in self.properties:
                     nested_p.update(**item._format_props())
-
-                    if item.required:
-                        nested_r.append(item.title)
+                    nested_r.append(item.title)
 
             props = {
                 "type": schema_type,
@@ -97,8 +94,6 @@ class ResponseField(BaseModel):
             if self.properties:
                 for item in self.properties:
                     p.update(**item._format_props())
-
-                    # if item.required:
                     r.append(item.title)
 
             props = {
@@ -204,12 +199,25 @@ class TaskOutput(BaseModel):
         eval_criteria = task.eval_criteria if task.eval_criteria else  ["Overall competitiveness", ]
 
         for item in eval_criteria:
-            task_1 = Task(
+            task_eval = Task(
                 description=EVALUATE.format(task_description=task.description, task_output=self.raw, eval_criteria=str(item)),
                 pydantic_output=EvaluationItem
             )
-            res_a = task_1.execute_sync(agent=self.evaluation.responsible_agent)
-            self.evaluation.items.append(EvaluationItem(**res_a.json_dict))
+            res = task_eval.execute_sync(agent=self.evaluation.responsible_agent)
+
+            if res.pydantic:
+                item = EvaluationItem(score=res.pydantic.score, suggestion=res.pydantic.suggestion, criteria=res.pydantic.criteria)
+                self.evaluation.items.append(item)
+
+            else:
+                try:
+                    item = EvaluationItem(
+                        score=float(res.json_dict["score"]), suggestion=res.json_dict["suggestion"], criteria=res.json_dict["criteria"]
+                    )
+                    self.evaluation.items.append(item)
+                except Exception as e:
+                    Logger(verbose=True).log(level="error", message=f"Failed to convert the evaluation items: {str(e)}", color="red")
+                    pass
 
         return self.evaluation
 
@@ -224,14 +232,6 @@ class TaskOutput(BaseModel):
 
     @property
     def json(self) -> Optional[str]:
-        if self.output_format != TaskOutputFormat.JSON:
-            raise ValueError(
-                """
-                Invalid output format requested.
-                If you would like to access the JSON output,
-                pleae make sure to set the output_json property for the task
-                """
-            )
         return json.dumps(self.json_dict)
 
 
@@ -239,7 +239,6 @@ class TaskOutput(BaseModel):
         return str(self.pydantic) if self.pydantic else str(self.json_dict) if self.json_dict else self.raw
 
 
-
 class Task(BaseModel):
     """
     Task to be executed by agents or teams.
@@ -394,14 +393,6 @@ Ref. Output image: {output_formats_to_follow}
         return "\n".join(task_slices)
 
 
-    def _get_output_format(self) -> TaskOutputFormat:
-        if self.output_json == True:
-            return TaskOutputFormat.JSON
-        if self.output_pydantic == True:
-            return TaskOutputFormat.PYDANTIC
-        return TaskOutputFormat.RAW
-
-
     def _structure_response_format(self, data_type: str = "object", model_provider: str = "gemini") -> Dict[str, Any] | None:
         """
         Structure a response format either from`response_fields` or `pydantic_output`.
@@ -508,75 +499,59 @@ Ref. Output image: {output_formats_to_follow}
             self.description = self._original_description.format(**inputs)
 
 
-    def _create_short_term_memory(self, agent, task_output: TaskOutput) -> None:
+    def _create_short_and_long_term_memories(self, agent: Any, task_output: TaskOutput) -> None:
         """
-        After the task execution, create and save short-term memory of the responsible agent.
+        After the task execution, create and save short-term/long-term memories in the storage.
         """
-
         from versionhq.agent.model import Agent
-        from versionhq.memory.model import ShortTermMemory
-
-        try:
-            if isinstance(agent, Agent) and agent.use_memory == True:
-                if hasattr(agent, "short_term_memory"):
-                    agent.short_term_memory.save(value=task_output.raw, metadata={ "observation": self.description, }, agent=agent.role)
-                else:
-                    agent.short_term_memory = ShortTermMemory(agent=agent, embedder_config=agent.embedder_config)
-                    agent.short_term_memory.save(value=task_output.raw, metadata={ "observation": self.description, }, agent=agent.role)
+        from versionhq.memory.model import ShortTermMemory, MemoryMetadata, LongTermMemory
 
-        except Exception as e:
-            self._logger.log(level="error", message=f"Failed to add to short term memory: {str(e)}", color="red")
-            pass
+        agent = agent if isinstance(agent, Agent) else Agent(role=str(agent), goal=str(agent), use_memory=True)
 
-
-    def _create_long_term_memory(self, agent, task_output: TaskOutput) -> None:
-        """
-        Create and save long-term and entity memory items based on evaluation.
-        """
-        from versionhq.agent.model import Agent
-        from versionhq.memory.model import LongTermMemory, LongTermMemoryItem
+        if agent.use_memory == False:
+            return None
 
         try:
-            if isinstance(agent, Agent) and agent.use_memory == True:
-                evaluation = task_output.evaluation if task_output.evaluation else task_output.evaluate(task=self)
-
-                long_term_memory_item = LongTermMemoryItem(
-                    agent=str(agent.role),
-                    task=str(self.description),
-                    datetime=str(datetime.datetime.now()),
-                    quality=evaluation.aggregate_score,
-                    metadata={
-                        "suggestions": evaluation.suggestion_summary,
-                        "quality": evaluation.aggregate_score,
-                    },
-                )
+            evaluation = task_output.evaluation if task_output.evaluation else None
+            memory_metadata = evaluation._create_memory_metadata() if evaluation else MemoryMetadata()
+
+            agent.short_term_memory = agent.short_term_memory if agent.short_term_memory else ShortTermMemory(agent=agent, embedder_config=agent.embedder_config)
+            agent.short_term_memory.save(
+                task_description=str(self.description),
+                task_output=str(task_output.raw),
+                agent=str(agent.role),
+                metadata=memory_metadata
+            )
 
-                if hasattr(agent, "long_term_memory"):
-                    agent.long_term_memory.save(item=long_term_memory_item)
-                else:
-                    agent.long_term_memory = LongTermMemory(agent=agent)
-                    agent.long_term_memory.save(item=long_term_memory_item)
+            agent.long_term_memory = agent.long_term_memory if agent.long_term_memory else LongTermMemory()
+            agent.long_term_memory.save(
+                task_description=str(self.description),
+                task_output=str(task_output.raw),
+                agent=str(agent.role),
+                metadata=memory_metadata
+                )
 
         except AttributeError as e:
             self._logger.log(level="error", message=f"Missing attributes for long term memory: {str(e)}", color="red")
             pass
 
         except Exception as e:
-            self._logger.log(level="error", message=f"Failed to add to long term memory: {str(e)}", color="red")
+            self._logger.log(level="error", message=f"Failed to add to the memory: {str(e)}", color="red")
             pass
 
 
     # task execution
-    def execute_sync(self, agent, context: Optional[str] = None) -> TaskOutput:
+    def execute_sync(self, agent, context: Optional[str | List[Any]] = None) -> TaskOutput:
         """
         Execute the task synchronously.
         When the task has context, make sure we have executed all the tasks in the context first.
         """
 
         if self.context:
-            for task in self.context:
-                if task.output is None:
-                    task._execute_core(agent, context)
+            if isinstance(self.context, list):
+                for task in self.context:
+                    if isinstance(task, Task) and task.output is None:
+                        task._execute_core(agent, context)
 
         return self._execute_core(agent, context)
 
@@ -670,9 +645,7 @@ Ref. Output image: {output_formats_to_follow}
         if self.should_evaluate:
             task_output.evaluate(task=self, latency=self.latency, tokens=self.tokens)
 
-        self._create_short_term_memory(agent=agent, task_output=task_output)
-        self._create_long_term_memory(agent=agent, task_output=task_output)
-
+        self._create_short_and_long_term_memories(agent=agent, task_output=task_output)
 
         if self.callback and isinstance(self.callback, Callable):
             kwargs = { **self.callback_kwargs, **task_output.json_dict }
@@ -702,7 +675,7 @@ Ref. Output image: {output_formats_to_follow}
 
     @property
     def key(self) -> str:
-        output_format = TaskOutputFormat.JSON if self.response_fields else TaskOutputFormat.PYDANTIC if self.pydantic_output is not None else TaskOutputFormat.RAW
+        output_format = "json" if self.response_fields else "pydantic" if self.pydantic_output is not None else "raw"
         source = [self.description, output_format]
         return md5("|".join(source).encode(), usedforsecurity=False).hexdigest()
 

versionhq/task/structured_response.py

@@ -1,4 +1,4 @@
-from typing import Dict, Optional, Type, List, Any, TypeVar
+from typing import Dict, Type, List, Any
 
 from pydantic import BaseModel, Field, InstanceOf
 

versionhq/team/model.py

@@ -1,17 +1,16 @@
 import uuid
 import warnings
-import json
 from enum import Enum
 from dotenv import load_dotenv
 from concurrent.futures import Future
 from hashlib import md5
-from typing import Any, Dict, List, TYPE_CHECKING, Callable, Optional, Tuple
-from pydantic import UUID4, InstanceOf, Json, BaseModel, Field, PrivateAttr, field_validator, model_validator
+from typing import Any, Dict, List, Callable, Optional, Tuple
+from pydantic import UUID4, BaseModel, Field, PrivateAttr, field_validator, model_validator
 from pydantic._internal._generate_schema import GenerateSchema
 from pydantic_core import PydanticCustomError, core_schema
 
 from versionhq.agent.model import Agent
-from versionhq.task.model import Task, TaskOutput, ConditionalTask, TaskOutputFormat
+from versionhq.task.model import Task, TaskOutput, ConditionalTask
 from versionhq.task.formatter import create_raw_outputs
 from versionhq.team.team_planner import TeamPlanner
 from versionhq._utils.logger import Logger
@@ -38,6 +37,16 @@ load_dotenv(override=True)
 #         pass
 
 
+
+class Formation(str, Enum):
+    SOLO = 1
+    SUPERVISING = 2
+    NETWORK = 3
+    RANDOM = 4
+    HYBRID = 10
+    UNDEFINED = 0
+
+
 class TaskHandlingProcess(str, Enum):
     """
     Class representing the different processes that can be used to tackle multiple tasks.
@@ -47,25 +56,25 @@ class TaskHandlingProcess(str, Enum):
     consensual = "consensual"
 
 
-class TeamOutput(BaseModel):
+class TeamOutput(TaskOutput):
     """
-    Store outputs of the tasks handled by the team.
-    `json_dict` and `raw` store overall output of tasks that handled by the team,
-    while `task_output_list` stores each TaskOutput instance to the tasks handled by the team members.
-    Note that `raw` and `json_dict` will be prioritized as TeamOutput to refer over `task_output_list`.
+    A class to store output from the team, inherited from TaskOutput class.
     """
 
     team_id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True, description="store the team ID that generate the TeamOutput")
-    raw: str = Field(default="", description="raw output of the team lead task handled by the team leader")
-    pydantic: Optional[Any] = Field(default=None, description="`raw` converted to the abs. pydantic model")
-    json_dict: Dict[str, Any] = Field(default=None, description="`raw` converted to dictionary")
-    task_output_list: list[TaskOutput] = Field(default=list, description="store output of all the tasks that the team has executed")
+    task_description: str = Field(default=None, description="store initial request (task description) from the client")
+    task_outputs: list[TaskOutput] = Field(default=list, description="store outputs of all tasks that the team has executed")
     token_usage: UsageMetrics = Field(default=dict, description="processed token summary")
 
+
+    def return_all_task_outputs(self) -> List[Dict[str, Any]]:
+        res = [output.json_dict for output in self.task_outputs]
+        return res
+
+
     def __str__(self):
         return (str(self.pydantic) if self.pydantic else str(self.json_dict) if self.json_dict else self.raw)
 
-
     def __getitem__(self, key):
         if self.pydantic and hasattr(self.pydantic, key):
             return getattr(self.pydantic, key)
@@ -75,35 +84,6 @@ class TeamOutput(BaseModel):
             raise KeyError(f"Key '{key}' not found in the team output.")
 
 
-    @property
-    def json(self) -> Optional[str]:
-        if self.tasks_output[-1].output_format != TaskOutputFormat.JSON:
-            raise ValueError(
-                "No JSON output found in the final task. Please make sure to set the output_json property in the final task in your team."
-            )
-        return json.dumps(self.json_dict)
-
-
-    def to_dict(self) -> Dict[str, Any]:
-        """
-        Convert pydantic / raw output into dict and return the dict.
-        When we only have `raw` output, return `{ output: raw }` to avoid an error
-        """
-
-        output_dict = {}
-        if self.json_dict:
-            output_dict.update(self.json_dict)
-        elif self.pydantic:
-            output_dict.update(self.pydantic.model_dump())
-        else:
-            output_dict.upate({ "output": self.raw })
-        return output_dict
-
-
-    def return_all_task_outputs(self) -> List[Dict[str, Any]]:
-        res = [output.json_dict for output in self.task_output_list]
-        return res
-
 
 class TeamMember(BaseModel):
     """
@@ -134,6 +114,7 @@ class Team(BaseModel):
     id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True)
     name: Optional[str] = Field(default=None)
     members: List[TeamMember] = Field(default_factory=list)
+    formation: Optional[Formation] = Field(default=None)
 
     # formation planning
     planning_llm: Optional[Any] = Field(default=None, description="llm to generate formation")
@@ -324,7 +305,7 @@ class Team(BaseModel):
             raw=final_task_output.raw,
             json_dict=final_task_output.json_dict,
             pydantic=final_task_output.pydantic,
-            task_output_list=task_outputs,
+            task_outputs=task_outputs,
             token_usage=token_usage,
         )
 
@@ -406,9 +387,9 @@ class Team(BaseModel):
         return self._create_team_output(task_outputs, lead_task_output)
 
 
-    def kickoff(self, kwargs_before: Optional[Dict[str, str]] = None, kwargs_after: Optional[Dict[str, Any]] = None) -> TeamOutput:
+    def launch(self, kwargs_before: Optional[Dict[str, str]] = None, kwargs_after: Optional[Dict[str, Any]] = None) -> TeamOutput:
         """
-        Kickoff the team:
+        Confirm and launch the formation - execute tasks and record outputs.
         0. Assign an agent to a task - using conditions (manager prioritizes team_tasks) and planning_llm.
         1. Address `before_kickoff_callbacks` if any.
         2. Handle team members' tasks in accordance with the process.

versionhq/team/team_planner.py

@@ -8,7 +8,11 @@ load_dotenv(override=True)
 
 class TeamPlanner:
     """
-    Assign agents to multiple tasks.
+    A class to handle agent formations based on the given task description.
+    1) complexity
+    2) agent built (or use given agents)
+    3) knowledge, memory sharing
+    4) form a team
     """
 
     from versionhq.task.model import Task, ResponseField, TaskOutput
@@ -59,7 +63,6 @@ class TeamPlanner:
         return new_member_list
 
 
-
     def _handle_task_planning(self, context: Optional[str] = None, tools: Optional[str] = None) -> TaskOutput:
         """
         Handles the team planning by creating detailed step-by-step plans for each task.

versionhq/tool/model.py

@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
 from inspect import signature
 from typing import Any, Dict, Callable, Type, Optional, get_args, get_origin, get_type_hints
 from typing_extensions import Self
-from pydantic import InstanceOf, BaseModel, ConfigDict, Field, field_validator, model_validator, PrivateAttr, create_model
+from pydantic import InstanceOf, BaseModel, Field, field_validator, model_validator, PrivateAttr, create_model
 from pydantic_core import PydanticCustomError
 
 from versionhq.llm.llm_vars import SchemaType