versionhq 1.2.0.3__py3-none-any.whl → 1.2.1.0__py3-none-any.whl

versionhq/__init__.py

@@ -16,7 +16,7 @@ from versionhq.clients.workflow.model import MessagingWorkflow, MessagingCompone
 from versionhq.knowledge.model import Knowledge, KnowledgeStorage
 from versionhq.knowledge.source import PDFKnowledgeSource, CSVKnowledgeSource, JSONKnowledgeSource, TextFileKnowledgeSource, ExcelKnowledgeSource, StringKnowledgeSource
 from versionhq.knowledge.source_docling import DoclingSource
-from versionhq.network.model import TaskStatus, TaskGraph, Node, Edge, DependencyType
+from versionhq.graph.model import TaskStatus, TaskGraph, Node, Edge, DependencyType
 from versionhq.task.model import Task, TaskOutput, ResponseField, TaskExecutionType
 from versionhq.task.evaluate import Evaluation, EvaluationItem
 from versionhq.team.model import Team, TeamOutput, Formation, Member, TaskHandlingProcess
@@ -30,7 +30,7 @@ from versionhq.memory.model import ShortTermMemory,LongTermMemory, UserMemory, M
 from versionhq.task.formation import form_agent_network
 
 
-__version__ = "1.2.0.3"
+__version__ = "1.2.1.0"
 __all__ = [
     "Agent",
 

versionhq/_utils/logger.py

@@ -38,7 +38,7 @@ class Printer:
 class Logger(BaseModel):
     """
     Control CLI messages.
-    Color: red = error, yellow = warning, blue = info (from vhq), green = info (from third party)
+    Color: red = error, yellow = warning, blue = info (from vhq), green = info (from third parties)
     """
 
     verbose: bool = Field(default=True)

versionhq/{network → graph}/model.py

@@ -1,51 +1,37 @@
 import enum
 import uuid
+import networkx as nx
+import matplotlib.pyplot as plt
 from abc import ABC
 from typing import List, Any, Optional, Callable, Dict, Type, Tuple
 
-from pydantic import BaseModel, InstanceOf, Field, UUID4, PrivateAttr, field_validator, model_validator
+from pydantic import BaseModel, InstanceOf, Field, UUID4, PrivateAttr, field_validator
 from pydantic_core import PydanticCustomError
 
 from versionhq.task.model import Task, TaskOutput
 from versionhq.agent.model import Agent
 from versionhq._utils.logger import Logger
 
-try:
-   import networkx as nx
-except ImportError:
-    try:
-        import os
-        os.system("uv add networkx --optional networkx")
-        import networkx as nx
-    except:
-        try:
-            import os
-            os.system("pip install network --save")
-            import networkx as nx
-        except:
-            raise ImportError("networkx is not installed. Please install it with: uv add networkx --optional networkx")
-
-try:
-    import matplotlib.pyplot as plt
-except ImportError:
-    try:
-        import os
-        os.system("uv add matplotlib --optional matplotlib")
-        import matplotlib.pyplot as plt
-    except:
-        try:
-            import os
-            os.system("pip install matplotlib --save")
-            import matplotlib.pyplot as plt
-
-        except:
-            raise ImportError("matplotlib is not installed. Please install it with: uv add matplotlib --optional matplotlib")
 
-
-import networkx as nx
-import matplotlib.pyplot as plt
+def gen_network():
+    goal = "make a promo plan to increase gross sales of Temu, an ecommerce site with affordable items."
+    agent = Agent(
+        role="Network Generator", goal="draft a best graph with nodes (tasks) and edges", llm="gemini-2.0", maxit=1,
+        knowledge_sources=["https://en.wikipedia.org/wiki/Graph_theory", "https://www.temu.com", ]
+    )
+    class Outcome(BaseModel):
+        task_descriptions: list[str]
 
 
+    task = Task(
+        description="    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. ",
+        pydantic_output=Outcome
+    )
+    task = Task(
+        description="Form best network with nodes and edges for the task described as following: Draft a promo plan for the client.",
+        pydantic_output=Edge
+    )
+    res = task.execute(agent=agent)
 
 class TaskStatus(enum.Enum):
     """
@@ -71,21 +57,21 @@ class DependencyType(enum.Enum):
 
 
 
-class TriggerEvent(enum.Enum):
-    """
-    Concise enumeration of key trigger events for task execution.
-    """
-    IMMEDIATE = 0 # execute immediately
-    DEPENDENCIES_MET = 1  # All/required dependencies are satisfied
-    RESOURCES_AVAILABLE = 2  # Necessary resources are available
-    SCHEDULED_TIME = 3  # Scheduled start time or time window reached
-    EXTERNAL_EVENT = 4  # Triggered by an external event/message
-    DATA_AVAILABLE = 5  # Required data  is available both internal/external
-    APPROVAL_RECEIVED = 6  # Necessary approvals have been granted
-    STATUS_CHANGED = 7  # Relevant task/system status has changed
-    RULE_MET = 8  # A predefined rule or condition has been met
-    MANUAL_TRIGGER = 9  # Manually initiated by a user
-    ERROR_HANDLED = 10  # A previous error/exception has been handled
+# class TriggerEvent(enum.Enum):
+#     """
+#     Concise enumeration of key trigger events for task execution.
+#     """
+#     IMMEDIATE = 0 # execute immediately
+#     DEPENDENCIES_MET = 1  # All/required dependencies are satisfied
+#     RESOURCES_AVAILABLE = 2  # Necessary resources are available
+#     SCHEDULED_TIME = 3  # Scheduled start time or time window reached
+#     EXTERNAL_EVENT = 4  # Triggered by an external event/message
+#     DATA_AVAILABLE = 5  # Required data  is available both internal/external
+#     APPROVAL_RECEIVED = 6  # Necessary approvals have been granted
+#     STATUS_CHANGED = 7  # Relevant task/system status has changed
+#     RULE_MET = 8  # A predefined rule or condition has been met
+#     MANUAL_TRIGGER = 9  # Manually initiated by a user
+#     ERROR_HANDLED = 10  # A previous error/exception has been handled
 
 
 
@@ -96,8 +82,8 @@ class Node(BaseModel):
     id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True)
     task: InstanceOf[Task] = Field(default=None)
     # trigger_event: TriggerEvent = Field(default=TriggerEvent.IMMEDIATE, description="store trigger event for starting the task execution")
-    in_degree_nodes: List[Any] = Field(default=None, description="list of Node objects")
-    out_degree_nodes: List[Any] = Field(default=None, description="list of Node objects")
+    in_degree_nodes: List[Any] = Field(default_factory=list, description="list of Node objects")
+    out_degree_nodes: List[Any] = Field(default_factory=list, description="list of Node objects")
     assigned_to: InstanceOf[Agent] = Field(default=None)
     status: TaskStatus = Field(default=TaskStatus.NOT_STARTED)
 
@@ -111,22 +97,6 @@ class Node(BaseModel):
     def is_independent(self) -> bool:
         return not self.in_degree_nodes and not self.out_degree_nodes
 
-    @property
-    def in_degrees(self) -> int:
-        return len(self.in_degree_nodes) if self.in_degree_nodes else 0
-
-    @property
-    def out_degrees(self) -> int:
-        return len(self.out_degree_nodes) if self.out_degree_nodes else 0
-
-    @property
-    def degrees(self) -> int:
-        return self.in_degrees + self.out_degrees
-
-    @property
-    def identifier(self) -> str:
-        """Unique identifier for the node"""
-        return f"{str(self.id)}"
 
     def handle_task_execution(self, agent: Agent = None, context: str = None) -> TaskOutput | None:
         """
@@ -144,15 +114,33 @@ class Node(BaseModel):
         self.status = TaskStatus.COMPLETED if res else TaskStatus.ERROR
         return res
 
+
+    @property
+    def in_degrees(self) -> int:
+        return len(self.in_degree_nodes) if self.in_degree_nodes else 0
+
+    @property
+    def out_degrees(self) -> int:
+        return len(self.out_degree_nodes) if self.out_degree_nodes else 0
+
+    @property
+    def degrees(self) -> int:
+        return self.in_degrees + self.out_degrees
+
+    @property
+    def identifier(self) -> str:
+        """Unique identifier for the node"""
+        return f"{str(self.id)}"
+
     def __str__(self):
         return self.identifier
 
 
-
 class Edge(BaseModel):
     """
     A class to store an edge object that connects source and target nodes.
     """
+
     source: Node = Field(default=None)
     target: Node = Field(default=None)
 
@@ -186,28 +174,28 @@ class Edge(BaseModel):
             case DependencyType.FINISH_TO_START:
                 """target starts after source finishes"""
                 if self.source.status == TaskStatus.COMPLETED:
-                    return self.condition(**self.conditon_kwargs) if self.condtion else True
+                    return self.condition(**self.conditon_kwargs) if self.condition else True
                 else:
                     return False
 
             case DependencyType.START_TO_START:
                 """target starts when source starts"""
                 if self.source.status != TaskStatus.NOT_STARTED:
-                    return self.condition(**self.conditon_kwargs) if self.condtion else True
+                    return self.condition(**self.conditon_kwargs) if self.condition else True
                 else:
                     return False
 
             case DependencyType.FINISH_TO_FINISH:
                 """target finish when source start"""
                 if self.source.status != TaskStatus.COMPLETED:
-                    return self.condition(**self.conditon_kwargs) if self.condtion else True
+                    return self.condition(**self.conditon_kwargs) if self.condition else True
                 else:
                     return False
 
             case DependencyType.START_TO_FINISH:
                 """target finishes when source start"""
                 if self.source.status == TaskStatus.IN_PROGRESS:
-                    return self.condition(**self.conditon_kwargs) if self.condtion else True
+                    return self.condition(**self.conditon_kwargs) if self.condition else True
                 else:
                     return False
 
@@ -217,19 +205,20 @@ class Edge(BaseModel):
         Activates the edge to initiate task execution of the target node.
         """
 
-        if not self.dependency_met():
-            Logger(verbose=True).log(level="warning", message="Dependencies not met. We'll return None.", color="yellow")
-            return None
-
         if not self.source or not self.target:
             Logger(verbose=True).log(level="warning", message="Cannot find source or target nodes. We'll return None.", color="yellow")
             return None
 
+        if not self.dependency_met():
+            Logger(verbose=True).log(level="warning", message="Dependencies not met. We'll see the source node status.", color="yellow")
+            return None
+
+
         if self.lag:
             import time
             time.sleep(self.lag)
 
-        context = self.source.task.task_output.raw if self.data_transfer else None
+        context = self.source.task.output.raw if self.data_transfer else None
         res = self.target.handle_task_execution(context=context)
         return res
 
@@ -239,15 +228,14 @@ class Graph(ABC, BaseModel):
     An abstract class to store G using NetworkX library.
     """
 
-    _logger: Logger = PrivateAttr(default_factory=lambda: Logger(verbose=True))
     directed: bool = Field(default=False, description="Whether the graph is directed")
     graph: Type[nx.Graph] = Field(default=None)
     nodes: Dict[str, InstanceOf[Node]] = Field(default_factory=dict, description="identifier: Node - for the sake of ")
     edges: Dict[str, InstanceOf[Edge]] = Field(default_factory=dict)
 
     def __init__(self, directed: bool = False, **kwargs):
-      super().__init__(directed=directed, **kwargs)
-      self.graph = nx.DiGraph() if self.directed else nx.Graph()
+        super().__init__(directed=directed, **kwargs)
+        self.graph = nx.DiGraph() if self.directed else nx.Graph()
 
     def _return_node_object(self, node_identifier) -> Node | None:
         return [v for k, v in self.nodes.items() if k == node_identifier][0] if [v for k, v in self.nodes.items() if k == node_identifier] else None
@@ -259,7 +247,9 @@ class Graph(ABC, BaseModel):
     def add_edge(self, source: str, target: str, edge: Edge) -> None:
         self.graph.add_edge(source, target, **edge.model_dump())
         edge.source = self._return_node_object(source)
+        edge.source.out_degree_nodes.append(target)
         edge.target = self._return_node_object(target)
+        edge.target.in_degree_nodes.append(source)
         self.edges[(source, target)] = edge
 
     def add_weighted_edges_from(self, edges):
@@ -274,6 +264,28 @@ class Graph(ABC, BaseModel):
     def get_out_degree(self, node: Node) -> int:
         return self.graph.out_degree(node)
 
+    def find_start_nodes(self) -> Tuple[Node]:
+        return [v for k, v in self.nodes.items() if v.in_degrees == 0 and v.out_degrees > 0]
+
+    def find_end_nodes(self) ->  Tuple[Node]:
+        return [v for k, v in self.nodes.items() if v.out_degrees == 0 and v.in_degrees > 0]
+
+    def find_critical_end_node(self) -> Node | None:
+        """
+        Find a critical end node from all the end nodes to lead a conclusion of the entire graph.
+        """
+        end_nodes = self.find_end_nodes()
+        if not end_nodes:
+            return None
+
+        if len(end_nodes) == 1:
+            return end_nodes[0]
+
+        edges = [v for k, v in self.edges if isinstance(v, Edge) and v.source in end_nodes]
+        critical_edge = max(edges, key=lambda item: item['weight']) if edges else None
+        return critical_edge.target if critical_edge else None
+
+
     def find_path(self, source: Optional[str] | None, target: str, weight: Optional[Any] | None) -> Any:
         try:
             return nx.shortest_path(self.graph, source=source, target=target, weight=weight)
@@ -288,14 +300,14 @@ class Graph(ABC, BaseModel):
         Finds the critical path in the graph.
         Returns:
             A tuple containing:
-                - The critical path (a list of task names).
+                - The critical path (a list of edge identifiers).
                 - The duration of the critical path.
                 - A dictionary of all paths and their durations.
         """
 
         all_paths = {}
-        for start_node in (v for k, v in self.nodes.items() if v.in_degrees == 0): # Start from nodes with 0 in-degree
-            for end_node in (v for k, v in self.nodes.items() if v.out_degrees == 0): # End at nodes with 0 out-degree
+        for start_node in self.find_start_nodes():
+            for end_node in self.find_end_nodes(): # End at nodes with 0 out-degree
                 for edge in nx.all_simple_paths(self.graph, source=start_node.identifier, target=end_node.identifier):
                     edge_weight = sum(self.edges.get(item).weight if self.edges.get(item) else 0 for item in edge)
                     all_paths[tuple(edge)] = edge_weight
@@ -347,7 +359,26 @@ class TaskGraph(Graph):
     id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True)
     should_reform: bool = Field(default=False)
     status: Dict[str, TaskStatus] = Field(default_factory=dict, description="store identifier (str) and TaskStatus of all task_nodes")
-    outputs: Dict[str, TaskOutput] = Field(default_factory=dict, description="store identifire and TaskOutput")
+    outputs: Dict[str, TaskOutput] = Field(default_factory=dict, description="store node identifire and TaskOutput")
+    conclusion: Any = Field(default=None, description="store the final result of the entire task graph. critical path target/end node")
+
+
+    def _save(self, abs_file_path: str = None) -> None:
+        """
+        Save the graph image in the local directory.
+        """
+
+        try:
+            import os
+            project_root = os.path.abspath(os.getcwd())
+            abs_file_path = abs_file_path if abs_file_path else f"{project_root}/uploads"
+
+            os.makedirs(abs_file_path, exist_ok=True)
+            plt.savefig(f"{abs_file_path}/{str(self.id)}.png")
+
+        except Exception as e:
+            Logger().log(level="error", message=f"Failed to save the graph {str(self.id)}: {str(e)}", color="red")
+
 
     def add_task(self, task: Node | Task) -> Node:
         """Convert `task` to a Node object and add it to G"""
@@ -365,7 +396,7 @@ class TaskGraph(Graph):
         """
 
         if not edge_attributes:
-            self._logger.log(level="error", message="Edge attributes are missing.", color="red")
+            Logger(verbose=True).log(level="error", message="Edge attributes are missing.", color="red")
 
         edge = Edge()
         for k in Edge.model_fields.keys():
@@ -382,14 +413,15 @@ class TaskGraph(Graph):
         if identifier in self.status:
             self.status[identifier] = status
         else:
-            self._logger.log(level="warning", message=f"Task '{identifier}' not found in the graph.", color="yellow")
+            Logger().log(level="warning", message=f"Task '{identifier}' not found in the graph.", color="yellow")
             pass
 
+
     def get_task_status(self, identifier):
         if identifier in self.status:
             return self.status[identifier]
         else:
-            self._logger.log(level="warning", message=f"Task '{identifier}' not found in the graph.", color="yellow")
+            Logger().log(level="warning", message=f"Task '{identifier}' not found in the graph.", color="yellow")
             return None
 
 
@@ -448,24 +480,6 @@ class TaskGraph(Graph):
         plt.show()
 
 
-    def _save(self, abs_file_path: str = None) -> None:
-        """
-        Save the graph image in the local directory.
-        """
-
-        try:
-            import os
-            project_root = os.path.abspath(os.getcwd())
-            abs_file_path = abs_file_path if abs_file_path else f"{project_root}/uploads"
-
-            os.makedirs(abs_file_path, exist_ok=True)
-
-            plt.savefig(f"{abs_file_path}/{str(self.id)}.png")
-
-        except Exception as e:
-            self._logger.log(level="error", message=f"Failed to save the graph {str(self.id)}: {str(e)}", color="red")
-
-
     def activate(self, target_node_identifier: Optional[str] = None) -> Tuple[TaskOutput | None, Dict[str, TaskOutput]]:
         """
         Starts to execute all nodes in the graph or a specific node if the target is given, following the given conditons of the edge obeject.
@@ -473,7 +487,7 @@ class TaskGraph(Graph):
         """
         if target_node_identifier:
             if not [k for k in self.nodes.keys() if k == target_node_identifier]:
-                self._logger.log(level="error", message=f"The node {str(target_node_identifier)} is not in the graph.", color="red")
+                Logger().log(level="error", message=f"The node {str(target_node_identifier)} is not in the graph.", color="red")
                 return None
 
             # find a shortest path to each in-degree node of the node and see if dependency met.
@@ -494,18 +508,62 @@ class TaskGraph(Graph):
             return res, self.outputs
 
         else:
-            if not self.edges or self.nodes:
-                self._logger.log(level="error", message="Needs at least 2 nodes and 1 edge to activate the graph. We'll return None.", color="red")
+            if not self.edges or not self.nodes:
+                Logger().log(level="error", message="TaskGraph needs at least 2 nodes and 1 edge to activate. We'll return None.", color="red")
                 return None
 
-            for edge in self.edges:
-                res = edge.activate()
-                if not res:
-                    break
+            start_nodes = self.find_start_nodes()
+            end_nodes = self.find_end_nodes()
+            critical_end_node = self.find_critical_end_node()
+            critical_path, _, _ = self.find_critical_path()
+            res = None
+
+            # When all nodes are completed, return the output of the critical end node or end node.
+            if end_nodes and len([node for node in end_nodes if node.status == TaskStatus.COMPLETED]) == len(end_nodes):
+                if critical_end_node:
+                    return critical_end_node.task.output, self.outputs
+
+                else:
+                    return [v.task.output.raw for k, v in end_nodes.items()][0], self.outputs
+
+            # Else, execute nodes connected with the critical_path
+            elif critical_path:
+                for item in critical_path:
+                    edge = [v for k, v in self.edges.items() if item in k]
+
+                    if edge:
+                        edge = edge[0]
 
-                node_identifier = edge.target.identifier
-                self.outputs.update({ node_identifier: res })
-                self.status.update({ node_identifier: edge.target.status })
+                        if edge.target.status == TaskStatus.COMPLETED:
+                            res = edge.target.output
 
-            last_task_output = [v for v in self.outputs.values()][len([v for v in self.outputs.values()]) - 1] if [v for v in self.outputs.values()] else None
-            return last_task_output, self.outputs
+                        else:
+                            res = edge.activate()
+                            node_identifier = edge.target.identifier
+                            self.outputs.update({ node_identifier: res })
+                            self.status.update({ node_identifier: edge.target.status })
+
+                            if not res and start_nodes:
+                                for node in start_nodes:
+                                    res = node.handle_task_execution()
+                                    self.outputs.update({ node.identifier: res })
+                                    self.status.update({ node.identifier: node.status })
+
+            # if no critical paths in the graph, simply start from the start nodes.
+            elif start_nodes:
+                for node in start_nodes:
+                    res = node.handle_task_execution()
+                    self.outputs.update({ node.identifier: res })
+                    self.status.update({ node.identifier: node.status })
+
+
+            # if none of above is applicable, try to activate all the edges.
+            else:
+                for k, edge in self.edges.items():
+                    res = edge.activate()
+                    node_identifier = edge.target.identifier
+                    self.outputs.update({ node_identifier: res })
+                    self.status.update({ node_identifier: edge.target.status })
+
+            # last_task_output = [v for v in self.outputs.values()][len([v for v in self.outputs.values()]) - 1] if [v for v in self.outputs.values()] else None
+            return res, self.outputs

versionhq/knowledge/source.py

@@ -265,7 +265,7 @@ class PDFKnowledgeSource(BaseFileKnowledgeSource):
                 import os
                 os.system("uv add pdfplumber --optional pdfplumber")
             except:
-                raise ImportError("pdfplumber is not installed. Please install it with: uv add pdfplumber")
+                raise ImportError("pdfplumber is not installed. Please install it with: uv add pdfplumber --optional pdfplumber")
 
 
     def add(self) -> None:

versionhq/task/formation.py

@@ -68,7 +68,7 @@ def form_agent_network(
 
         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.
+    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. When you have a leader_agent, the formation must be SUPERVISING or HYBRID.
     Task: {str(task)}
     Expected outcome: {str(expected_outcome)}
     Formation: {prompt_formation}
@@ -109,7 +109,7 @@ def form_agent_network(
                 team_tasks.extend(created_tasks[len(created_agents):len(created_tasks)])
 
             members.sort(key=lambda x: x.is_manager == False)
-            team = Team( members=members, formation=_formation,  team_tasks=team_tasks, planner_llm=vhq_formation_planner.llm)
+            team = Team(members=members, formation=_formation, team_tasks=team_tasks, planner_llm=vhq_formation_planner.llm)
             return team
 
         else:

versionhq/task/model.py

@@ -149,9 +149,16 @@ class ResponseField(BaseModel):
             return value
 
 
+    def _annotate(self, value: Any) -> Annotated:
+        """
+        Address Pydantic's `create_model`
+        """
+        return Annotated[self.type, value] if isinstance(value, self.type) else Annotated[str, str(value)]
+
+
     def create_pydantic_model(self, result: Dict, base_model: InstanceOf[BaseModel] | Any) -> Any:
         """
-        Create a Pydantic model from the given result
+        Create a Pydantic model from the given result.
         """
         for k, v in result.items():
             if k is not self.title:
@@ -164,14 +171,6 @@ class ResponseField(BaseModel):
         return base_model
 
 
-    def _annotate(self, value: Any) -> Annotated:
-        """
-        Address Pydantic's `create_model`
-        """
-        return Annotated[self.type, value] if isinstance(value, self.type) else Annotated[str, str(value)]
-
-
-
 class TaskOutput(BaseModel):
     """
     A class to store the final output of the given task in raw (string), json_dict, and pydantic class formats.

versionhq/team/model.py

@@ -27,33 +27,25 @@ def match_type(self, obj):
 
 GenerateSchema.match_type = match_type
 warnings.filterwarnings("ignore", category=SyntaxWarning, module="pysbd")
-load_dotenv(override=True)
-
-# agentops = None
-# if os.environ.get("AGENTOPS_API_KEY"):
-#     try:
-#         import agentops  # type: ignore
-#     except ImportError:
-#         pass
-
 
 
 class Formation(str, Enum):
     UNDEFINED = 0
     SOLO = 1
     SUPERVISING = 2
-    NETWORK = 3
+    SQUAD = 3
     RANDOM = 4
     HYBRID = 10
 
 
 class TaskHandlingProcess(str, Enum):
     """
-    Class representing the different processes that can be used to tackle multiple tasks.
+    A class representing task handling processes to tackle multiple tasks.
+    When the team has multiple tasks that connect with edges, follow the edge conditions.
     """
-    sequential = "sequential"
-    hierarchical = "hierarchical"
-    consensual = "consensual"
+    SEQUENT = 1
+    HIERARCHY = 2
+    CONSENSUAL = 3 # either from managers or peers or (human) - most likely controlled by edge
 
 
 class TeamOutput(TaskOutput):
@@ -63,19 +55,16 @@ class TeamOutput(TaskOutput):
 
     team_id: UUID4 = Field(default_factory=uuid.uuid4, frozen=True, description="store the team ID that generate the TeamOutput")
     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")
-
+    task_outputs: list[TaskOutput] = Field(default=list, description="store TaskOutput objects 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)
@@ -88,7 +77,7 @@ class TeamOutput(TaskOutput):
 
 class Member(BaseModel):
     """
-    A class to store a member in the network and connect the agent as a member with tasks and sharable settings.
+    A class to store a member in the team and connect the agent as a member with tasks and memory/knowledge share settings.
     """
     agent: Agent | None = Field(default=None)
     is_manager: bool = Field(default=False)
@@ -103,7 +92,8 @@ class Member(BaseModel):
 
 class Team(BaseModel):
     """
-    A class to store agent network that shares knowledge, memory and tools among the members.
+    A class to store a team with members and tasks.
+    Tasks can be 1. multiple individual tasks, 2. multiple dependant tasks connected via Graph, and 3. hybrid.
     """
 
     __hash__ = object.__hash__
@@ -123,7 +113,7 @@ class Team(BaseModel):
 
     # task execution rules
     prompt_file: str = Field(default="", description="absolute path to the prompt json file")
-    process: TaskHandlingProcess = Field(default=TaskHandlingProcess.sequential)
+    process: TaskHandlingProcess = Field(default=TaskHandlingProcess.SEQUENT)
 
     # callbacks
     pre_launch_callbacks: List[Callable[[Optional[Dict[str, Any]]], Optional[Dict[str, Any]]]] = Field(
@@ -174,21 +164,19 @@ class Team(BaseModel):
 
 
     @model_validator(mode="after")
-    def check_manager_llm(self):
+    def check_manager(self):
         """
         Check if the team has a manager
         """
-
-        if self.process == TaskHandlingProcess.hierarchical or self.formation == Formation.SUPERVISING:
+        if self.process == TaskHandlingProcess.HIERARCHY or self.formation == Formation.SUPERVISING:
             if not self.managers:
                 self._logger.log(level="error", message="The process or formation created needs at least 1 manager agent.", color="red")
-                raise PydanticCustomError(
-                    "missing_manager_llm_or_manager","Attribute `manager_llm` or `manager` is required when using hierarchical process.", {})
+                raise PydanticCustomError("missing_manager", "`manager` is required when using hierarchical process.", {})
 
-            ## comment out for the formation flexibilities
-            # if self.managers and (self.manager_tasks is None or self.team_tasks is None):
-            #     self._logger.log(level="error", message="The manager is idling. At least 1 task needs to be assigned to the manager.", color="red")
-            #     raise PydanticCustomError("missing_manager_task", "manager needs to have at least one manager task or team task.", {})
+        ## comment out for the formation flexibilities
+        # if self.managers and (self.manager_tasks is None or self.team_tasks is None):
+        #     self._logger.log(level="error", message="The manager is idling. At least 1 task needs to be assigned to the manager.", color="red")
+        #     raise PydanticCustomError("missing_manager_task", "manager needs to have at least one manager task or team task.", {})
 
         return self
 
@@ -198,7 +186,7 @@ class Team(BaseModel):
         """
         Sequential task processing without any team tasks require a task-agent pairing.
         """
-        if self.process == TaskHandlingProcess.sequential and self.team_tasks is None:
+        if self.process == TaskHandlingProcess.SEQUENT and self.team_tasks is None:
             for task in self.tasks:
                 if not [member.task == task for member in self.members]:
                     self._logger.log(level="error", message=f"The following task needs a dedicated agent to be assinged: {task.description}", color="red")
@@ -278,31 +266,6 @@ class Team(BaseModel):
         return task_outputs
 
 
-    def _create_team_output(self, task_outputs: List[TaskOutput], lead_task_output: TaskOutput = None) -> TeamOutput:
-        """
-        Take the output of the first task or the lead task output as the team output `raw` value.
-        Note that `tasks` are already sorted by the importance.
-        """
-
-        if not task_outputs:
-            self._logger.log(level="error", message="Missing task outcomes. Failed to launch the task.", color="red")
-            raise ValueError("Failed to launch tasks")
-
-        final_task_output = lead_task_output if lead_task_output is not None else task_outputs[0] #! REFINEME
-        # final_string_output = final_task_output.raw
-        # self._finish_execution(final_string_output)
-        token_usage = self._calculate_usage_metrics()
-
-        return TeamOutput(
-            team_id=self.id,
-            raw=final_task_output.raw,
-            json_dict=final_task_output.json_dict,
-            pydantic=final_task_output.pydantic,
-            task_outputs=task_outputs,
-            token_usage=token_usage,
-        )
-
-
     def _calculate_usage_metrics(self) -> UsageMetrics:
         """
         Calculate and return the usage metrics that consumed by the team.
@@ -371,14 +334,29 @@ class Team(BaseModel):
                     lead_task_output = task_output
 
                 task_outputs.append(task_output)
-                # self._process_task_result(task, task_output)
                 task._store_execution_log(task_index, was_replayed, self._inputs)
 
 
         if futures:
             task_outputs = self._process_async_tasks(futures, was_replayed)
 
-        return self._create_team_output(task_outputs, lead_task_output)
+        if not task_outputs:
+            self._logger.log(level="error", message="Missing task outcomes. Failed to launch the task.", color="red")
+            raise ValueError("Failed to launch tasks")
+
+        final_task_output = lead_task_output if lead_task_output is not None else task_outputs[0] #! REFINEME
+
+        # token_usage = self._calculate_usage_metrics() #! combining with Eval
+
+        return TeamOutput(
+            team_id=self.id,
+            raw=final_task_output.raw,
+            json_dict=final_task_output.json_dict,
+            pydantic=final_task_output.pydantic,
+            task_outputs=task_outputs,
+            # token_usage=token_usage,
+        )
+
 
 
     def launch(self, kwargs_pre: Optional[Dict[str, str]] = None, kwargs_post: Optional[Dict[str, Any]] = None) -> TeamOutput:
@@ -412,7 +390,7 @@ class Team(BaseModel):
                 agent.callbacks.append(self.step_callback)
 
         if self.process is None:
-            self.process = TaskHandlingProcess.sequential
+            self.process = TaskHandlingProcess.SEQUENT
 
         result = self._execute_tasks(self.tasks)
 

{versionhq-1.2.0.3.dist-info → versionhq-1.2.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.0.3
+Version: 1.2.1.0
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -64,6 +64,8 @@ Requires-Dist: chromadb>=0.6.3
 Requires-Dist: wheel>=0.45.1
 Requires-Dist: envoy>=0.0.3
 Requires-Dist: composio-core==0.7.0
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: matplotlib>=3.10.0
 Provides-Extra: docling
 Requires-Dist: docling>=2.17.0; extra == "docling"
 Provides-Extra: mem0ai
@@ -76,17 +78,13 @@ Provides-Extra: numpy
 Requires-Dist: numpy>=1.26.4; extra == "numpy"
 Provides-Extra: pygraphviz
 Requires-Dist: pygraphviz>=1.14; extra == "pygraphviz"
-Provides-Extra: networkx
-Requires-Dist: networkx>=3.4.2; extra == "networkx"
-Provides-Extra: matplotlib
-Requires-Dist: matplotlib>=3.10.0; extra == "matplotlib"
 
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-15K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-17K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
 ![MIT license](https://img.shields.io/badge/License-MIT-green)
 [![Publisher](https://github.com/versionHQ/multi-agent-system/actions/workflows/publish.yml/badge.svg)](https://github.com/versionHQ/multi-agent-system/actions/workflows/publish.yml)
-![PyPI](https://img.shields.io/badge/PyPI-v1.2.0+-blue)
+![PyPI](https://img.shields.io/badge/PyPI-v1.2.1+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11/3.12-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
@@ -108,9 +106,10 @@ A Python framework for agentic orchestration that handles complex task automatio
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 - [Key Features](#key-features)
-  - [Agent formation](#agent-formation)
+  - [Agent Network](#agent-network)
   - [Graph Theory Concept](#graph-theory-concept)
-  - [Agent optimization](#agent-optimization)
+  - [Task Graph](#task-graph)
+  - [Optimization](#optimization)
 - [Quick Start](#quick-start)
   - [Package installation](#package-installation)
   - [Forming a agent network](#forming-a-agent-network)
@@ -141,14 +140,14 @@ A Python framework for agentic orchestration that handles complex task automatio
 Agents are model-agnostic, and will improve task output, while oprimizing token cost and job latency, by sharing their memory, knowledge base, and RAG tools with other agents in the network.
 
 
-###  Agent formation
+###  Agent Network
 
 Agents adapt their formation based on task complexity.
 
 You can specify a desired formation or allow the agents to determine it autonomously (default).
 
 
-|  | **Solo Agent** | **Supervising** | **Network** | **Random** |
+|  | **Solo Agent** | **Supervising** | **Squad** | **Random** |
 | :--- | :--- | :--- | :--- | :--- |
 | **Formation** | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/rbgxttfoeqqis1ettlfz.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/zhungor3elxzer5dum10.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/dnusl7iy7kiwkxwlpmg8.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/sndpczatfzbrosxz9ama.png" alt="solo" width="200"> |
 | **Usage** | <ul><li>A single agent with tools, knowledge, and memory.</li><li>When self-learning mode is on - it will turn into **Random** formation.</li></ul> | <ul><li>Leader agent gives directions, while sharing its knowledge and memory.</li><li>Subordinates can be solo agents or networks.</li></ul> | <ul><li>Share tasks, knowledge, and memory among network members.</li></ul> | <ul><li>A single agent handles tasks, asking help from other agents without sharing its memory or knowledge.</li></ul> |
@@ -194,7 +193,19 @@ task_graph.visualize()
 
 <hr />
 
-### Agent optimization
+### Task Graph
+
+A `TaskGraph` represents tasks as `nodes` and their execution dependencies as `edges`, automating rule-based execution.
+
+`Agent Networks` can handle `TaskGraph` objects by optimizing their formations.
+
+The following example demonstrates a simple concept of a `supervising` agent network handling a task graph with three tasks and one critical edge.
+
+<img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1739337639/pj_m_home/zfg4ccw1m1ww1tpnb0pa.png">
+
+<hr />
+
+### Optimization
 
 Agents are model-agnostic and can handle multiple tasks, leveraging their own and their peers' knowledge sources, memories, and tools.
 

{versionhq-1.2.0.3.dist-info → versionhq-1.2.1.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
-versionhq/__init__.py,sha256=RZZvNni2Slrj-OaK0N9me8CaK5AvO4Ui566sGeF1oVc,2783
+versionhq/__init__.py,sha256=OvDVdnABXYcdjKCYL58tOw2duy59rQ2lxc7e1AoxUjc,2781
 versionhq/_utils/__init__.py,sha256=dzoZr4cBlh-2QZuPzTdehPUCe9lP1dmRtauD7qTjUaA,158
 versionhq/_utils/i18n.py,sha256=TwA_PnYfDLA6VqlUDPuybdV9lgi3Frh_ASsb_X8jJo8,1483
-versionhq/_utils/logger.py,sha256=j9SlQPIefdVUlwpGfJY83E2BUt1ejWgZ2M2I8aMyQ3c,1579
+versionhq/_utils/logger.py,sha256=2qkODR6y8ApOoMjQZVecTboXvCLrMy2v_mTSOnNMKFY,1581
 versionhq/_utils/process_config.py,sha256=jbPGXK2Kb4iyCugJ3FwRJuU0wL5Trq2x4xFQz2uOyFY,746
 versionhq/_utils/usage_metrics.py,sha256=NXF18dn5NNvGK7EsQ4AAghpR8ppYOjMx6ABenLLHnmM,1066
 versionhq/_utils/vars.py,sha256=bZ5Dx_bFKlt3hi4-NNGXqdk7B23If_WaTIju2fiTyPQ,57
@@ -20,11 +20,13 @@ versionhq/clients/product/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 versionhq/clients/product/model.py,sha256=3w__pug9XRe4LIm9wX8C8WKqi40r081Eb1q2vWk9UaU,3694
 versionhq/clients/workflow/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/clients/workflow/model.py,sha256=FNftenLLoha0bkivrjId32awLHAkBwIT8iNljdic_bw,6003
+versionhq/graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+versionhq/graph/model.py,sha256=k4NbNn0D3r3ujfkQHOsfiiEJRxZx7iK5DczBnOyn1ik,23912
 versionhq/knowledge/__init__.py,sha256=qW7IgssTA4_bFFV9ziOcYRfGjlq1c8bkb-HnfWknpuQ,567
 versionhq/knowledge/_utils.py,sha256=YWRF8U533cfZes_gZqUvdj-K24MD2ri1R0gjc_aPYyc,402
 versionhq/knowledge/embedding.py,sha256=KfHc__1THxb5jrg1EMrF-v944RDuIr2hE0l-MtM3Bp0,6826
 versionhq/knowledge/model.py,sha256=w29mrJv1kiznCh4P4yJMUQxIuyRw1Sk0XYtBXzCxaG4,1786
-versionhq/knowledge/source.py,sha256=30VXsl3uHdM0wK0Dik3XfFxpNpEiy539PBNBvg0Y4-g,13609
+versionhq/knowledge/source.py,sha256=HxlwK7E5qWMknJeswnFCCdTIOB01hV4JrEiMGkp7j1E,13631
 versionhq/knowledge/source_docling.py,sha256=hhHn3rS4KVsFKEPWcfllM8VxSL86PckZdAHDZNQNOq8,5411
 versionhq/knowledge/storage.py,sha256=7oxCg3W9mFjYH1YmuH9kFtTbNxquzYFjuUjd_TlsB9E,8170
 versionhq/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -33,8 +35,6 @@ versionhq/llm/model.py,sha256=wlzDUMEyIOm808d1vzqu9gmbB4ch-s_EUvwFR60gR80,17177
 versionhq/memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/memory/contextual_memory.py,sha256=tCsOOAUnfrOL7YiakqGoi3uShzzS870TmGnlGd3z_A4,3556
 versionhq/memory/model.py,sha256=4wow2O3UuMZ0AbC2NyxddGZac3-_GjNZbK9wsA015NA,8145
-versionhq/network/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/network/model.py,sha256=AfakEac4twHIIextUzrV5S-9qzrpaEEoaku6b9cg74A,20612
 versionhq/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/storage/base.py,sha256=p-Jas0fXQan_qotnRD6seQxrT2lj-uw9-SmHQhdppcs,355
 versionhq/storage/ltm_sqlite_storage.py,sha256=wdUiuwHfJocdk0UGqyrdU4S5Nae1rgsoRNu3LWmGFcI,3951
@@ -44,14 +44,14 @@ versionhq/storage/task_output_storage.py,sha256=E1t_Fkt78dPYIOl3MP7LfQ8oGtjlzxBu
 versionhq/storage/utils.py,sha256=ByYXPoEIGJYLUqz-DWjbCAnneNrH1otiYbp12SCILpM,747
 versionhq/task/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/task/evaluate.py,sha256=WdUgjbZL62XrxyWe5MTz29scfzwmuAHGxJ7GvAB8Fmk,3954
-versionhq/task/formation.py,sha256=iHhW2webMirYC78G8kHpaMTYjCdq7c3yFD2u2Egd8Eo,6350
+versionhq/task/formation.py,sha256=8YQxGZ7cs7Q-a7UnwheHxXei9LSt1AWpCQmQiN1ZkgI,6423
 versionhq/task/formatter.py,sha256=N8Kmk9vtrMtBdgJ8J7RmlKNMdZWSmV8O1bDexmCWgU0,643
 versionhq/task/log_handler.py,sha256=LT7YnO7gcPR9IZS7eRvMjnHh8crMBFtqduxd8dxIbkk,1680
-versionhq/task/model.py,sha256=zAnZ-_5YKZRs43gpM2AL9IVtttq5GqGfqfCMj_Oyz9g,30624
+versionhq/task/model.py,sha256=aXsFRhpmIyfoYpF8BU2cBU4nh4OsaSxc9D98DJ9auqE,30624
 versionhq/task/structured_response.py,sha256=4q-hQPu7oMMHHXEzh9YW4SJ7N5eCZ7OfZ65juyl_jCI,5000
 versionhq/task/TEMPLATES/Description.py,sha256=V-4kh8xpQTKOcDMi2xnuP-fcNk6kuoz1_5tYBlDLQWQ,420
 versionhq/team/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/team/model.py,sha256=kxrjF3RFGO9l3IsJIffI1nqgl_Vh5RLuhqrwIqbEoBY,19214
+versionhq/team/model.py,sha256=88l2lxlAZGIauRJr607IMbV7jP3FIvveVHrT7O4AVpk,18614
 versionhq/team/team_planner.py,sha256=Zc3zvhPR7T0O8RQoq9CKOrvrll4klemY1rONLFeJ96M,3663
 versionhq/tool/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/tool/cache_handler.py,sha256=iL8FH7X0G-cdT0uhJwzuhLDaadTXOdfybZcDy151-es,1085
@@ -60,8 +60,8 @@ versionhq/tool/composio_tool_vars.py,sha256=FvBuEXsOQUYnN7RTFxT20kAkiEYkxWKkiVtg
 versionhq/tool/decorator.py,sha256=C4ZM7Xi2gwtEMaSeRo-geo_g_MAkY77WkSLkAuY0AyI,1205
 versionhq/tool/model.py,sha256=PO4zNWBZcJhYVur381YL1dy6zqurio2jWjtbxOxZMGI,12194
 versionhq/tool/tool_handler.py,sha256=2m41K8qo5bGCCbwMFferEjT-XZ-mE9F0mDUOBkgivOI,1416
-versionhq-1.2.0.3.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
-versionhq-1.2.0.3.dist-info/METADATA,sha256=PCPwZZLO_mShcOc9JS8M41tukqGVlk_cdYtFvU-OJ5s,21462
-versionhq-1.2.0.3.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-versionhq-1.2.0.3.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
-versionhq-1.2.0.3.dist-info/RECORD,,
+versionhq-1.2.1.0.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
+versionhq-1.2.1.0.dist-info/METADATA,sha256=Ilxj9ZEYzoFzEnzdDE6umFKruSRN3pmcm_D2LvpVi8A,21854
+versionhq-1.2.1.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+versionhq-1.2.1.0.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
+versionhq-1.2.1.0.dist-info/RECORD,,