versionhq 1.1.13.0__py3-none-any.whl → 1.1.13.1__py3-none-any.whl

versionhq/__init__.py

@@ -8,12 +8,15 @@ from dotenv import load_dotenv
 load_dotenv(override=True)
 
 from versionhq.agent.model import Agent
+from versionhq.llm.model import LLM
+from versionhq.llm.llm_vars import LLM_CONTEXT_WINDOW_SIZES, PARAMS, PROVIDERS, MODELS
 from versionhq.clients.customer.model import Customer
 from versionhq.clients.product.model import Product, ProductProvider
 from versionhq.clients.workflow.model import MessagingWorkflow, MessagingComponent
 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.task.model import Task, TaskOutput, ConditionalTask, ResponseField
 from versionhq.task.evaluate import Evaluation, EvaluationItem
 from versionhq.team.model import Team, TeamOutput, Formation, Member, TaskHandlingProcess
@@ -27,10 +30,16 @@ from versionhq.memory.model import ShortTermMemory,LongTermMemory, UserMemory, M
 from versionhq.task.formation import form_agent_network
 
 
-__version__ = "1.1.13.0"
+__version__ = "1.1.13.1"
 __all__ = [
     "Agent",
 
+    "LLM",
+    "LLM_CONTEXT_WINDOW_SIZES",
+    "PARAMS",
+    "PROVIDERS",
+    "MODELS",
+
     "Customer",
     "Product",
     "ProductProvider",
@@ -47,6 +56,12 @@ __all__ = [
     "StringKnowledgeSource",
     "DoclingSource",
 
+    "TaskStatus",
+    "TaskGraph",
+    "Node",
+    "Edge",
+    "DependencyType",
+
     "Task",
     "TaskOutput",
     "ConditionalTask",

versionhq/agent/model.py

@@ -23,25 +23,6 @@ load_dotenv(override=True)
 T = TypeVar("T", bound="Agent")
 
 
-# def mock_agent_ops_provider():
-#     def track_agent(*args, **kwargs):
-#         def noop(f):
-#             return f
-#         return noop
-#     return track_agent
-
-# track_agent = mock_agent_ops_provider()
-
-# agentops = None
-# if os.environ.get("AGENTOPS_API_KEY"):
-#     try:
-#         from agentops import track_agent
-#     except ImportError:
-#         track_agent = mock_agent_ops_provider()
-# else:
-#    track_agent = mock_agent_ops_provider()
-
-
 class TokenProcess:
     total_tokens: int = 0
     prompt_tokens: int = 0
@@ -76,10 +57,9 @@ class TokenProcess:
 # @track_agent()
 class Agent(BaseModel):
     """
-    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.
+    A class to store agent information.
+    Agents must have `role`, `goal`, and `llm` = DEFAULT_MODEL_NAME as default.
+    Then run validation on `backstory`, `llm`, `tools`, `rpm` (request per min), `knowledge`, and `memory`.
     """
 
     __hash__ = object.__hash__
@@ -132,8 +112,6 @@ class Agent(BaseModel):
 
     # cache, error, ops handling
     formatting_errors: int = Field(default=0, description="number of formatting errors.")
-    agent_ops_agent_name: str = None
-    agent_ops_agent_id: str = None
 
 
     @field_validator("id", mode="before")
@@ -161,9 +139,8 @@ class Agent(BaseModel):
     @model_validator(mode="after")
     def set_up_llm(self) -> Self:
         """
-        Set up `llm` and `function_calling_llm` as valid LLM objects using the given values.
+        Set up `llm` and `function_calling_llm` as valid LLM objects using the given kwargs.
         """
-        self.agent_ops_agent_name = self.role
         self.llm = self._convert_to_llm_object(llm=self.llm)
 
         function_calling_llm = self.function_calling_llm if self.function_calling_llm else self.llm if self.llm else None
@@ -177,12 +154,15 @@ class Agent(BaseModel):
         return self
 
 
-    def _convert_to_llm_object(self, llm: Any | None) -> LLM:
+    def _convert_to_llm_object(self, llm: Any = None) -> LLM:
         """
         Convert the given value to LLM object.
         When `llm` is dict or self.llm_config is not None, add these values to the LLM object after validating them.
         """
-        llm = llm if llm is not None else DEFAULT_MODEL_NAME
+        llm = llm if llm else self.llm if self.llm else DEFAULT_MODEL_NAME
+
+        if not llm:
+            pass
 
         match llm:
             case LLM():
@@ -380,16 +360,16 @@ class Agent(BaseModel):
         Set up memories: stm, ltm, and um
         """
 
-        if self.use_memory == True:
-            self.long_term_memory = self.long_term_memory if self.long_term_memory else LongTermMemory()
-            self.short_term_memory = self.short_term_memory if self.short_term_memory else ShortTermMemory(agent=self, embedder_config=self.embedder_config)
+        # if self.use_memory == True:
+        self.long_term_memory = self.long_term_memory if self.long_term_memory else LongTermMemory()
+        self.short_term_memory = self.short_term_memory if self.short_term_memory else ShortTermMemory(agent=self, embedder_config=self.embedder_config)
 
-            if hasattr(self, "memory_config") and self.memory_config is not None:
-                user_id = self.memory_config.get("user_id", None)
-                if user_id:
-                    self.user_memory = self.user_memory if self.user_memory else UserMemory(agent=self, user_id=user_id)
-            else:
-                self.user_memory = None
+        if hasattr(self, "memory_config") and self.memory_config is not None:
+            user_id = self.memory_config.get("user_id", None)
+            if user_id:
+                self.user_memory = self.user_memory if self.user_memory else UserMemory(agent=self, user_id=user_id)
+        else:
+            self.user_memory = None
 
         return self
 
@@ -402,6 +382,78 @@ class Agent(BaseModel):
             pass
 
 
+    def update_llm(self, llm: Any = None, llm_config: Optional[Dict[str, Any]] = None) -> Self:
+        """
+        Update llm and llm_config of the exsiting agent. (Other conditions will remain the same.)
+        """
+
+        if not llm and not llm_config:
+            self._logger.log(level="error", message="Missing llm or llm_config values to update", color="red")
+            pass
+
+        self.llm = llm
+        if llm_config:
+            if self.llm_config:
+                self.llm_config.update(llm_config)
+            else:
+                self.llm_config = llm_config
+
+        return self.set_up_llm()
+
+
+    def update(self, **kwargs) -> Self:
+        """
+        Update the existing agent. Address variables that require runnning set_up_x methods first, then update remaining variables.
+        """
+
+        if not kwargs:
+            self._logger.log(level="error", message="Missing values to update", color="red")
+            return self
+
+        for k, v in kwargs.items():
+            match k:
+                case "tools":
+                    self.tools = kwargs.get(k, self.tools)
+                    self.set_up_tools()
+
+                case "role" | "goal":
+                    self.role = kwargs.get("role", self.role)
+                    self.goal = kwargs.get("goal", self.goal)
+                    if not self.backstory:
+                        self.set_up_backstory()
+
+                    if self.backstory:
+                        self.backstory += f"new role: {self.role}, new goal: {self.goal}"
+
+                case "max_rpm":
+                    self.max_rpm = kwargs.get(k, self.max_rpm)
+                    self.set_up_rpm()
+
+                case "knowledge_sources":
+                    self.knowledge_sources = kwargs.get("knowledge_sources", self.knowledge_sources)
+                    self.set_up_knowledge()
+
+                case "use_memory" | "memory_config":
+                    self.use_memory = kwargs.get("use_memory", self.use_memory)
+                    self.memory_config = kwargs.get("memory_config", self.memory_config)
+                    self.set_up_memory()
+
+                case "llm" | "llm_config":
+                    self.llm = kwargs.get("llm", self.llm)
+                    self.llm_config = kwargs.get("llm_config", self.llm_config)
+                    self.update_llm(llm=self.llm, llm_config=self.llm_config)
+
+                case _:
+                    try:
+                        setattr(self, k, v)
+                    except Exception as e:
+                        self._logger.log(level="error", message=f"Failed to update the key: {k} We'll skip. Error: {str(e)}", color="red")
+                        pass
+
+        return self
+
+
+
     def invoke(
         self,
         prompts: str,

versionhq/llm/llm_vars.py

@@ -1,4 +1,3 @@
-from enum import Enum
 from typing import Type
 
 JSON_URL = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json"

versionhq/llm/model.py

@@ -111,7 +111,7 @@ class LLM(BaseModel):
 
 
     @model_validator(mode="after")
-    def validate_model_providers(self) -> Self:
+    def validate_model_and_provider(self) -> Self:
         """
         Validate the given model, provider, interface provider.
         """

versionhq/network/model.py

@@ -0,0 +1,394 @@
+import enum
+import uuid
+from abc import ABC
+from typing import List, Any, Optional, Callable, Dict, Type
+
+from pydantic import BaseModel, InstanceOf, Field, UUID4, PrivateAttr, field_validator
+from pydantic_core import PydanticCustomError
+
+from versionhq.task.model import Task
+from versionhq.agent.model import Agent
+from versionhq._utils.logger import Logger
+
+
+try:
+   import networkx as ntx
+except ImportError:
+    try:
+        import os
+        os.system("uv add networkx --optional networkx")
+        import networkx as ntx
+    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:
+        raise ImportError("matplotlib is not installed. Please install it with: uv add matplotlib --optional matplotlib")
+
+import networkx as nx
+import matplotlib.pyplot as plt
+
+
+
+class TaskStatus(enum.Enum):
+    """
+    Enum to track the task execution status
+    """
+    NOT_STARTED = 1
+    IN_PROGRESS = 2
+    BLOCKED = 3      # task is waiting for its dependant tasks to complete. resumption set as AUTO.
+    COMPLETED = 4
+    DELAYED = 5      # task has begun - but is taking longer than expected duration and behind schedule.
+    ON_HOLD = 6      # task is temporarily & intentionally paused due to external factors and/or decisions. resumption set as DECISION.
+
+
+
+class DependencyType(enum.Enum):
+    """
+    Concise enumeration of the edge type.
+    """
+
+    FINISH_TO_START = "FS"  # Task B starts after Task A finishes
+    START_TO_START = "SS"  # Task B starts when Task A starts
+    FINISH_TO_FINISH = "FF"  # Task B finishes when Task A finishes
+    START_TO_FINISH = "SF"  # Task B finishes when Task A starts
+
+
+
+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 Node(BaseModel):
+    """
+    A class to store a node object.
+    """
+    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 to execute the task")
+    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")
+    assigned_to: InstanceOf[Agent] = Field(default=None)
+    status: TaskStatus = Field(default=TaskStatus.NOT_STARTED)
+
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def _deny_id(cls, v: Optional[UUID4]) -> None:
+        if v:
+            raise PydanticCustomError("may_not_set_field", "This field is not to be set by the user.", {})
+
+    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 __str__(self):
+        return self.identifier
+
+
+class Edge(BaseModel):
+    """
+    A class to store an edge object that connects multiple nodes as dependencies.
+    """
+    description: Optional[str] = Field(default=None)
+
+    type: DependencyType = Field(default=DependencyType.FINISH_TO_START)
+    weight: Optional[float] = Field(default=None, description="duration or weight of the dependency: 1 light 10 heavy")
+    lag: Optional[float] = Field(default=None, description="lag time for the dependency to be executed")
+    constraint: Optional[str] = Field(default=None, description="constraint to consider executing the dependency")
+    priority: Optional[int] = Field(default=None, description="priority of the dependency if multiple depencencies are given")
+
+    data_transfer: bool = Field(True, description="whether the data transfer is required")
+    data_format: Optional[str] = Field(default=None, description="Format of data transfer")
+
+    # execution logic
+    required: bool = Field(True, description="whether the execution of the dependency is required - False = conditional, optional task")
+    condition: Optional[Callable] = Field(default=None, description="conditional function to start executing the dependency")
+
+
+    def is_dependency_met(self, predecessor_node: Node = None) -> bool:
+        """
+        Define if the dependency is ready to execute:
+
+        required	condition	Dependency Met?	Dependent Task Can Start?
+        True	Not Given	Predecessor task finished	Yes (if other deps met)
+        True	Given	Predecessor task finished and condition True	Yes (if other deps met)
+        False	Not Given	Always (regardless of predecessor status)	Yes (if other deps met)
+        False	Given	Condition True (predecessor status irrelevant)	Yes (if other deps met)
+        """
+
+        if self.required:
+            if predecessor_node.status == TaskStatus.COMPLETED:
+                return self.condition() if self.condtion else True
+            else:
+                return False
+        else:
+            return self.condition() if self.condition else True
+
+
+
+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()
+
+    def add_node(self, node: Node) -> None:
+        self.graph.add_node(node.identifier, **node.model_dump())
+        self.nodes[node.identifier] = node
+
+    def add_edge(self, source: str, target: str, edge: Edge) -> None:
+        self.graph.add_edge(source, target, **edge.model_dump())
+        self.edges[(source, target)] = edge
+
+    def add_weighted_edges_from(self, edges):
+        self.graph.add_weighted_edges_from(edges)
+
+    def get_neighbors(self, node: Node) -> List[Node]:
+        return list(self.graph.neighbors(node))
+
+    def get_in_degree(self, node: Node) -> int:
+        return self.graph.in_degree(node)
+
+    def get_out_degree(self, node: Node) -> int:
+        return self.graph.out_degree(node)
+
+    def find_path(self, source: str, target: str, weight: Any) -> Any:
+        try:
+            return nx.shortest_path(self.graph, source=source, target=target, weight=weight)
+        except nx.NetworkXNoPath:
+            return None
+
+    def find_all_paths(self,  source: str, target: str) -> List[Any]:
+        return list(nx.all_simple_paths(self.graph, source=source, target=target))
+
+
+    def find_critical_path(self) -> tuple[List[Any], int, Dict[str, int]]:
+        """
+        Finds the critical path in the graph.
+        Returns:
+            A tuple containing:
+                - The critical path (a list of task names).
+                - 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 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
+
+        if not all_paths:
+            return [], 0, all_paths
+
+        critical_path = max(all_paths, key=all_paths.get)
+        critical_duration = all_paths[critical_path]
+
+        return list(critical_path), critical_duration, all_paths
+
+
+    def is_circled(self, node: Node) -> bool:
+        """Check if there's a path from the node to itself and return bool."""
+        try:
+            path = nx.shortest_path(self.graph, source=node, target=node)
+            return True if path else False
+        except nx.NetworkXNoPath:
+            return False
+
+
+    def visualize(self, title: str = "Graph Visualization", pos: Any = None, **graph_config):
+        pos = pos if pos else nx.spring_layout(self.graph, seed=42)
+        nx.draw(
+            self.graph,
+            pos,
+            with_labels=True, node_size=700, node_color="skyblue", font_size=10, font_color="black", arrowstyle='-|>', arrowsize=20, arrows=True,
+            **graph_config
+        )
+        edge_labels = {}
+        for u, v, data in self.graph.edges(data=True):
+            edge = self.edges.get((u,v))
+            if edge:
+                label_parts = []
+                if edge.type:
+                    label_parts.append(f"Type: {edge.type}")
+                if edge.duration is not None:
+                    label_parts.append(f"Duration: {edge.duration}")
+                if edge.lag is not None:
+                    label_parts.append(f"Lag: {edge.lag}")
+                edge_labels[(u, v)] = "\n".join(label_parts)  # Combine labels with newlines
+        nx.draw_networkx_edge_labels(self.graph, pos, edge_labels=edge_labels)
+        plt.title(title)
+        plt.show()
+
+
+
+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")
+
+
+    def add_task(self, task: Node | Task) -> Node:
+        """Convert `task` to a Node object and add it to G"""
+        task_node = task if isinstance(task, Node) else Node(task=task)
+        self.add_node(task_node)
+        self.status[task_node.identifier] = TaskStatus.NOT_STARTED
+        return task_node
+
+
+    def add_dependency(
+            self, source_task_node_identifier: str, target_task_node_identifier: str, **edge_attributes
+        ) -> None:
+        """
+        Add an edge that connect task 1 (source) and task 2 (target) using task_node.name as an identifier
+        """
+
+        if not edge_attributes:
+            self._logger.log(level="error", message="Edge attributes are missing.", color="red")
+
+        edge = Edge()
+        for k in Edge.model_fields.keys():
+            v = edge_attributes.get(k, None)
+            if v:
+                setattr(edge, k, v)
+            else:
+                pass
+
+        self.add_edge(source_task_node_identifier, target_task_node_identifier, edge)
+
+
+    def set_task_status(self, identifier: str, status: TaskStatus) -> None:
+        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")
+            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")
+            return None
+
+
+    def visualize(self, layout: str = None):
+        try:
+            pos = nx.drawing.nx_agraph.graphviz_layout(self.graph, prog='dot') # 'dot', 'neato', 'fdp', 'sfdp'
+        except ImportError:
+            pos = nx.spring_layout(self.graph, seed=42) # REFINEME - layout
+
+        node_colors = list()
+        for k, v in self.graph.nodes.items():
+            status = self.get_task_status(identifier=k)
+            if status == TaskStatus.NOT_STARTED:
+                node_colors.append("skyblue")
+            elif status == TaskStatus.IN_PROGRESS:
+                node_colors.append("lightgreen")
+            elif status == TaskStatus.BLOCKED:
+                node_colors.append("lightcoral")
+            elif status == TaskStatus.COMPLETED:
+                node_colors.append("black")
+            elif status == TaskStatus.DELAYED:
+                node_colors.append("orange")
+            elif status == TaskStatus.ON_HOLD:
+                node_colors.append("yellow")
+            else:
+                node_colors.append("grey")
+
+        critical_paths, duration, paths = self.find_critical_path()
+        edge_colors = ['red' if (u, v) in zip(critical_paths, critical_paths[1:]) else 'black' for u, v in self.graph.edges()]
+        edge_widths = []
+
+        for k, v in self.edges.items():
+            # edge_weights = nx.get_edge_attributes(self.graph, 'weight')
+            # edge_colors.append(plt.cm.viridis(v.weight / max(edge_weights.values())))
+            edge_widths.append(v.weight * 0.5)  # Width proportional to weight (adjust scaling as needed)
+
+        nx.draw(
+            self.graph, pos,
+            with_labels=True,
+            node_size=700,
+            node_color=node_colors,
+            font_size=10,
+            font_color="black",
+            edge_color=edge_colors,
+            width=edge_widths,
+            arrows=True,
+            arrowsize=20,
+            arrowstyle='-|>'
+        )
+
+        edge_labels = nx.get_edge_attributes(G=self.graph, name="edges")
+        nx.draw_networkx_edge_labels(self.graph, pos, edge_labels=edge_labels)
+
+        plt.title("Project Network Diagram")
+        self._save()
+        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")

{versionhq-1.1.13.0.dist-info → versionhq-1.1.13.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.1.13.0
+Version: 1.1.13.1
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -74,6 +74,12 @@ Provides-Extra: pandas
 Requires-Dist: pandas>=2.2.3; extra == "pandas"
 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
 
@@ -103,15 +109,21 @@ A Python framework for agentic orchestration that handles complex task automatio
 
 - [Key Features](#key-features)
   - [Agent formation](#agent-formation)
+  - [Graph Theory Concept](#graph-theory-concept)
+  - [Agent optimization](#agent-optimization)
 - [Quick Start](#quick-start)
   - [Package installation](#package-installation)
   - [Forming a agent network](#forming-a-agent-network)
-  - [Customizing AI agents](#customizing-ai-agents)
+  - [Executing tasks](#executing-tasks)
   - [Supervising](#supervising)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
-- [Setting Up](#setting-up)
+- [Setting Up a Project](#setting-up-a-project)
+  - [1. Installing package manager](#1-installing-package-manager)
+  - [2. Installing dependencies](#2-installing-dependencies)
+  - [3. Adding env secrets to .env file](#3-adding-env-secrets-to-env-file)
 - [Contributing](#contributing)
+  - [Steps](#steps)
   - [Package Management with uv](#package-management-with-uv)
   - [Pre-Commit Hooks](#pre-commit-hooks)
   - [Documentation](#documentation)
@@ -144,6 +156,73 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 <hr />
 
+### Graph Theory Concept
+
+To completely automate task workflows, agents will build a `task-oriented network` by generating `nodes` that represent tasks and connecting them with dependency-defining `edges`.
+
+Each node is triggered by specific events and executed by an assigned agent once all dependencies are met.
+
+While the network automatically reconfigures itself, you retain the ability to direct the agents using `should_reform` variable.
+
+
+The following code snippet demonstrates the `TaskGraph` and its visualization, saving the diagram to the `uploads` directory.
+
+```python
+import versionhq as vhq
+
+task_graph = vhq.TaskGraph(directed=False, should_reform=True) # triggering auto formation
+
+task_a = vhq.Task(description="Research Topic")
+task_b = vhq.Task(description="Outline Post")
+task_c = vhq.Task(description="Write First Draft")
+
+node_a = task_graph.add_task(task=task_a)
+node_b = task_graph.add_task(task=task_b)
+node_c = task_graph.add_task(task=task_c)
+
+task_graph.add_dependency(
+   node_a.identifier, node_b.identifier,
+   type=vhq.DependencyType.FINISH_TO_START, weight=5, description="B depends on A"
+)
+task_graph.add_dependency(
+   node_a.identifier, node_c.identifier,
+   type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3
+)
+
+task_graph.visualize()
+```
+
+<hr />
+
+### Agent optimization
+
+Agents are model-agnostic and can handle multiple tasks, leveraging their own and their peers' knowledge sources, memories, and tools.
+
+Agents are optimized during network formation, but customization is possible before or after.
+
+The following code snippet demonstrates agent customization:
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+   role="Marketing Analyst",
+   goal="my amazing goal"
+) # assuming this agent was created during the network formation
+
+# update the agent
+agent.update(
+   llm="gemini-2.0", # updating LLM (Valid llm_config will be inherited to the new LLM.)
+   tools=[vhq.Tool(func=lambda x: x)], # adding tools
+   max_rpm=3,
+   knowledge_sources=["<KC1>", "<KS2>"], # adding knowledge sources. This will trigger the storage creation.
+   memory_config={"user_id": "0001"}, # adding memories
+   dummy="I am dummy" # <- invalid field will be automatically ignored
+)
+```
+
+<hr />
+
 ## Quick Start
 
 ### Package installation
@@ -169,11 +248,11 @@ You can specify a desired formation or allow the agents to determine it autonomo
    This will form a network with multiple agents on `Formation` and return `TaskOutput` object with output in JSON, plane text, Pydantic model format with evaluation.
 
 
-### Customizing AI agents
+### Executing tasks
 
-You can simply build an agent using `Agent` model.
+You can simply build an agent using `Agent` model and execute the task using `Task` class.
 
-By default, the agent prioritize JSON serializable outputs over plane texts.
+By default, agents prioritize JSON over plane text outputs.
 
 
    ```python
@@ -253,21 +332,29 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 
 ## Technologies Used
 
+**Graph Theory (Analysis and Visualization)**
+
+* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks.
+* [Matplotlib](https://matplotlib.org/stable/index.html): Visualization library
+* [Graphviz](https://graphviz.org/about/): Graph visualization software
+
+
 **Schema, Data Validation**
 
 * [Pydantic](https://docs.pydantic.dev/latest/): Data validation and serialization library for Python.
 * [Upstage](https://console.upstage.ai/docs/getting-started/overview): Document processer for ML tasks. (Use `Document Parser API` to extract data from documents)
 * [Docling](https://ds4sd.github.io/docling/): Document parsing
 
+
 **Storage**
 
 * [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
 * [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
 * [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
 
-**LLM-curation**
+**LLM Integration**
 
-* [LiteLLM](https://docs.litellm.ai/docs/providers): Curation platform to access LLMs
+* [LiteLLM](https://docs.litellm.ai/docs/providers): Integration to diverse LLMs
 
 **Tools**
 
@@ -304,30 +391,30 @@ src/
 │     └── llm/
 │     └── ...
 │
-└── uploads/                  # Local directory that stores uloaded files
+└── uploads/  [.gitignore]    # Local directory to store uploaded files such as graphviz diagrams generatd by `Network` class
 
 ```
 
 <hr />
 
-## Setting Up
+## Setting Up a Project
 
-1. Install `uv` package manager:
+### 1. Installing package manager
 
-      For MacOS:
+   For MacOS:
 
-      ```
-      brew install uv
-      ```
+   ```
+   brew install uv
+   ```
 
-      For Ubuntu/Debian:
+   For Ubuntu/Debian:
+   ```
+   sudo apt-get install uv
+   ```
 
-      ```
-      sudo apt-get install uv
-      ```
 
+### 2. Installing dependencies
 
-2. Install dependencies:
    ```
    uv venv
    source .venv/bin/activate
@@ -335,29 +422,51 @@ src/
    uv sync --all-extras
    ```
 
-* In case of AssertionError/module mismatch, run Python version control using `.pyenv`
-   ```
-   pyenv install 3.12.8
-   pyenv global 3.12.8  (optional: `pyenv global system` to get back to the system default ver.)
-   uv python pin 3.12.8
-   echo 3.12.8 >> .python-version
-   ```
+   - AssertionError/module mismatch errors: Set up default Python version using `.pyenv`
+      ```
+      pyenv install 3.12.8
+      pyenv global 3.12.8  (optional: `pyenv global system` to get back to the system default ver.)
+      uv python pin 3.12.8
+      echo 3.12.8 >> .python-version
+      ```
 
+   - `pygraphviz` related errors: Run the following commands:
+      ```
+      brew install graphviz
+      uv pip install --config-settings="--global-option=build_ext" \
+      --config-settings="--global-option=-I$(brew --prefix graphviz)/include/" \
+      --config-settings="--global-option=-L$(brew --prefix graphviz)/lib/" \
+      pygraphviz
+      ```
+
+      * If the error continues, skip pygraphviz installation by:
+      ```
+      uv sync --all-extras --no-extra pygraphviz
+      ```
+
+   - `torch`/`Docling` related errors: Set up default Python version either `3.11.x` or `3.12.x` (same as AssertionError)
+
+### 3. Adding env secrets to .env file
 
-3. Add secrets to `.env` file in the project root:
+Create `.env` file in the project root and add following:
 
    ```
-   LITELLM_API_KEY=your-litellm-api-key
    OPENAI_API_KEY=your-openai-api-key
+   GEMINI_API_KEY=your-gemini-api-key
+   LITELLM_API_KEY=your-litellm-api-key
    COMPOSIO_API_KEY=your-composio-api-key
    COMPOSIO_CLI_KEY=your-composio-cli-key
-   [LLM_INTERFACE_PROVIDER_OF_YOUR_CHOICE]_API_KEY=your-api-key
+   [OTHER_LLM_INTERFACE_PROVIDER_OF_YOUR_CHOICE]_API_KEY=your-api-key
    ```
 
 <hr />
 
 ## Contributing
 
+`versionhq` is a open source project.
+
+### Steps
+
 1. Create your feature branch (`git checkout -b feature/your-amazing-feature`)
 
 2. Create amazing features
@@ -365,6 +474,7 @@ src/
 3. Add a test funcition to the `tests` directory and run **pytest**.
 
    - Add secret values defined in `.github/workflows/run_test.yml` to your Github `repository secrets` located at settings > secrets & variables > Actions.
+
    - Run a following command:
       ```
       uv run pytest tests -vv --cache-clear
@@ -376,6 +486,8 @@ src/
 
    * Test functions within the files must begin with `test_`.
 
+   * Pytest priorities are `1. playground demo > 2. docs use cases > 3. other features`
+
 
 4. Update `docs` accordingly.
 
@@ -418,7 +530,7 @@ src/
 
 Pre-commit hooks help maintain code quality by running checks for formatting, linting, and other issues before each commit.
 
-* To skip pre-commit hooks (NOT RECOMMENDED)
+* To skip pre-commit hooks
    ```
    git commit --no-verify -m "your-commit-message"
    ```
@@ -427,7 +539,7 @@ Pre-commit hooks help maintain code quality by running checks for formatting, li
 
 * To edit the documentation, see `docs` repository and edit the respective component.
 
-* We use `mkdocs` to update the docs. You can run the doc locally at http://127.0.0.1:8000/:
+* We use `mkdocs` to update the docs. You can run the docs locally at http://127.0.0.1:8000/.
 
    ```
    uv run python3 -m mkdocs serve --clean

{versionhq-1.1.13.0.dist-info → versionhq-1.1.13.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-versionhq/__init__.py,sha256=lfts4IiFxMVN-gRb7eoit56jqfMgOSMG1C8803J_-UQ,2400
+versionhq/__init__.py,sha256=JJMdTbmmTzzublAjg3tFmOm13CKLwVsNz3cdsDP0bJQ,2780
 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
@@ -7,7 +7,7 @@ versionhq/_utils/usage_metrics.py,sha256=NXF18dn5NNvGK7EsQ4AAghpR8ppYOjMx6ABenLL
 versionhq/_utils/vars.py,sha256=bZ5Dx_bFKlt3hi4-NNGXqdk7B23If_WaTIju2fiTyPQ,57
 versionhq/agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/agent/inhouse_agents.py,sha256=vSobrH1gXDWlaNsiges3sqETeUrEssRzQvCZCY2hQZA,2374
-versionhq/agent/model.py,sha256=8aJ4rdgGEph10DuB8zhJkiRWzQTZ2LGKNq1MTeQ9hM8,23342
+versionhq/agent/model.py,sha256=NLHQPYqYFg9GX3NoDP1Rs3vHFlYv6Fl6JZ4QlNOYMn0,25429
 versionhq/agent/parser.py,sha256=riG0dkdQCxH7uJ0AbdVdg7WvL0BXhUgJht0VtQvxJBc,4082
 versionhq/agent/rpm_controller.py,sha256=grezIxyBci_lDlwAlgWFRyR5KOocXeOhYkgN02dNFNE,2360
 versionhq/agent/TEMPLATES/Backstory.py,sha256=IAhGnnt6VUMe3wO6IzeyZPDNu7XE7Uiu3VEXUreOcKs,532
@@ -28,11 +28,13 @@ versionhq/knowledge/source.py,sha256=30VXsl3uHdM0wK0Dik3XfFxpNpEiy539PBNBvg0Y4-g
 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
-versionhq/llm/llm_vars.py,sha256=3fax7EXNwCw1yapIoqRMmwgGmK3O37Wm1e8uvq8ObL4,7063
-versionhq/llm/model.py,sha256=QacjThF43Vfel6LIvSt5KkOZAbzo1jYjwFgFfhrv7ms,17174
+versionhq/llm/llm_vars.py,sha256=wjQK20cKvph6Vq1v71o4d16zBGcHlwq0bzOT_zWno7w,7041
+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=npSV5RUYdmkM9cMGkNLiKD4vYb3yNVyh6qCdNKkVIN8,15223
 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
@@ -58,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.1.13.0.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
-versionhq-1.1.13.0.dist-info/METADATA,sha256=zNnwZLvuWsZPjXoCrsa7PqD8iR1sJ2zUjjj8wV0QkfA,17365
-versionhq-1.1.13.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-versionhq-1.1.13.0.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
-versionhq-1.1.13.0.dist-info/RECORD,,
+versionhq-1.1.13.1.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
+versionhq-1.1.13.1.dist-info/METADATA,sha256=QAjiAx25V2-0nc9PGPNII3-31IHw8hHAghUfdQxZogA,21448
+versionhq-1.1.13.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+versionhq-1.1.13.1.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
+versionhq-1.1.13.1.dist-info/RECORD,,