versionhq 1.2.0.4__tar.gz → 1.2.1.1__tar.gz

{versionhq-1.2.0.4 → versionhq-1.2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.0.4
+Version: 1.2.1.1
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -81,10 +81,10 @@ Requires-Dist: pygraphviz>=1.14; extra == "pygraphviz"
 
 # 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)
 
@@ -106,14 +106,16 @@ 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)
   - [Executing tasks](#executing-tasks)
   - [Supervising](#supervising)
+- [Supervising](#supervising-1)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
 - [Setting Up a Project](#setting-up-a-project)
@@ -139,14 +141,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> |
@@ -192,7 +194,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.
 
@@ -292,42 +306,50 @@ This will return a `TaskOutput` object that stores response in plane text, JSON,
 
 ### Supervising
 
-   ```python
-   import versionhq as vhq
+## Supervising
 
-   agent_a = vhq.Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
-   agent_b = vhq.Agent(role="agent b", goal="My amazing goals", llm="llm-of-your-choice")
+To create an agent network with one or more manager agents, designate members using the `is_manager` tag.
 
-   task_1 = vhq.Task(
-      description="Analyze the client's business model.",
-      response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True),],
-      allow_delegation=True
-   )
+```python
+import versionhq as vhq
 
-    task_2 = vhq.Task(
-      description="Define the cohort.",
-      response_fields=[ResponseField(title="test1", data_type=int, required=True),],
-      allow_delegation=False
-   )
+agent_a = vhq.Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
+agent_b = vhq.Agent(role="agent b", goal="My amazing goals", llm="llm-of-your-choice")
 
-   team = vhq.Team(
-      members=[
-         vhq.Member(agent=agent_a, is_manager=False, task=task_1),
-         vhq.Member(agent=agent_b, is_manager=True, task=task_2),
-      ],
-   )
-   res = team.launch()
-   ```
+task_1 = vhq.Task(
+   description="Analyze the client's business model.",
+   response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True),],
+   allow_delegation=True
+)
+
+task_2 = vhq.Task(
+   description="Define a cohort.",
+   response_fields=[vhq.ResponseField(title="test1", data_type=int, required=True),],
+   allow_delegation=False
+)
+
+network =vhq.AgentNetwork(
+   members=[
+      vhq.Member(agent=agent_a, is_manager=False, tasks=[task_1]),
+      vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager
+   ],
+)
+res = network.launch()
+
+assert isinstance(res, vhq.NetworkOutput)
+assert not [item for item in task_1.processed_agents if "vhq-Delegated-Agent" == item]
+assert [item for item in task_1.processed_agents if "agent b" == item]
+```
 
 This will return a list with dictionaries with keys defined in the `ResponseField` of each task.
 
-Tasks can be delegated to a team manager, peers in the team, or completely new agent.
+Tasks can be delegated to a manager, peers within the agent network, or a completely new agent.
 
 <hr />
 
 ## Technologies Used
 
-**Graph Theory (Analysis and Visualization)**
+**Task Graph**
 
 * [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

{versionhq-1.2.0.4 → versionhq-1.2.1.1}/README.md

@@ -1,9 +1,9 @@
 # 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)
 
@@ -25,14 +25,16 @@ 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)
   - [Executing tasks](#executing-tasks)
   - [Supervising](#supervising)
+- [Supervising](#supervising-1)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
 - [Setting Up a Project](#setting-up-a-project)
@@ -58,14 +60,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> |
@@ -111,7 +113,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.
 
@@ -211,42 +225,50 @@ This will return a `TaskOutput` object that stores response in plane text, JSON,
 
 ### Supervising
 
-   ```python
-   import versionhq as vhq
+## Supervising
 
-   agent_a = vhq.Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
-   agent_b = vhq.Agent(role="agent b", goal="My amazing goals", llm="llm-of-your-choice")
+To create an agent network with one or more manager agents, designate members using the `is_manager` tag.
 
-   task_1 = vhq.Task(
-      description="Analyze the client's business model.",
-      response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True),],
-      allow_delegation=True
-   )
+```python
+import versionhq as vhq
 
-    task_2 = vhq.Task(
-      description="Define the cohort.",
-      response_fields=[ResponseField(title="test1", data_type=int, required=True),],
-      allow_delegation=False
-   )
+agent_a = vhq.Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
+agent_b = vhq.Agent(role="agent b", goal="My amazing goals", llm="llm-of-your-choice")
 
-   team = vhq.Team(
-      members=[
-         vhq.Member(agent=agent_a, is_manager=False, task=task_1),
-         vhq.Member(agent=agent_b, is_manager=True, task=task_2),
-      ],
-   )
-   res = team.launch()
-   ```
+task_1 = vhq.Task(
+   description="Analyze the client's business model.",
+   response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True),],
+   allow_delegation=True
+)
+
+task_2 = vhq.Task(
+   description="Define a cohort.",
+   response_fields=[vhq.ResponseField(title="test1", data_type=int, required=True),],
+   allow_delegation=False
+)
+
+network =vhq.AgentNetwork(
+   members=[
+      vhq.Member(agent=agent_a, is_manager=False, tasks=[task_1]),
+      vhq.Member(agent=agent_b, is_manager=True, tasks=[task_2]), # Agent B as a manager
+   ],
+)
+res = network.launch()
+
+assert isinstance(res, vhq.NetworkOutput)
+assert not [item for item in task_1.processed_agents if "vhq-Delegated-Agent" == item]
+assert [item for item in task_1.processed_agents if "agent b" == item]
+```
 
 This will return a list with dictionaries with keys defined in the `ResponseField` of each task.
 
-Tasks can be delegated to a team manager, peers in the team, or completely new agent.
+Tasks can be delegated to a manager, peers within the agent network, or a completely new agent.
 
 <hr />
 
 ## Technologies Used
 
-**Graph Theory (Analysis and Visualization)**
+**Task Graph**
 
 * [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

versionhq-1.2.1.1/docs/core/task/response-field.md

@@ -0,0 +1,211 @@
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# ResponseField
+
+<class>`class` versionhq.task.model.<bold>ResponseField<bold></class>
+
+A class to store response formats to create JSON response schema.
+
+<hr/>
+
+## Core Usage
+
+`[var]`<bold>`title: str = None`</bold>
+
+`[var]`<bold>`data_type: Type = None`</bold>
+
+Define a response format with field titles and data types.
+
+
+```python
+import versionhq as vhq
+
+response_field = vhq.ResponseField(
+  title="summary",
+  data_type=str,
+  nullable=False, # default = False. Explicitly mentioned.
+)
+
+## Agent output:
+#  "summary": <AGENT_RESPONSE_IN_STRING>
+```
+
+### Object
+
+`[var]`<bold>`properties: List[InstanceOf[ResponseField]] = None`</bold>
+
+To format an object, add `ResponseField` objects to the `properties` fields.
+
+Missing properties for dict will trigger an error.
+
+```python
+import versionhq as vhq
+
+response_field = vhq.ResponseField(
+  title="dict-summary",
+  data_type=dict,
+  nullable=False,
+  properties=[
+    vhq.ResponseField(title="summary-1", data_type=str),
+    vhq.ResponseField(title="summary-2", data_type=int),
+  ]
+)
+
+## Agent output:
+#  dict-summary: {
+#   "summary-1": <AGENT_RESPONSE_1_IN_STRING>,
+#   "summary-2": <AGENT_RESPONSE_2_IN_INTEGER>,
+# }
+```
+
+<hr />
+
+### List
+
+`[var]`<bold>`items: Optional[Type] = None`</bold>
+
+To format a list, add data types of the list items to the `items` field.
+
+Missing items for list will trigger an error.
+
+```python
+import versionhq as vhq
+
+response_field = vhq.ResponseField(
+  title="list-summary",
+  data_type=list,
+  nullable=False,
+  items=str
+)
+
+## Agent output:
+#  list-summary: [
+#     <AGENT_RESPONSE_1_IN_STRING>,
+#     <AGENT_RESPONSE_2_IN_STRING>,
+#     ...
+# ]
+```
+
+<hr />
+
+## Nesting
+
+Agents can handle **one layer** of nested items usign `properties` and `items` fields.
+
+We highly recommend to use `gemini-x` or `gpt-x` to get stable results.
+
+### List with Object
+
+```python
+import versionhq as vhq
+
+list_with_objects = vhq.ResponseField(
+  title="parent",
+  data_type=list,
+  items=dict,
+  properties=[
+    vhq.ResponseField(title="nest-1", data_type=str),
+    vhq.ResponseField(title="nest-2", data_type=float),
+  ]
+)
+
+# Agent output
+# parent: [
+#   { "nest-1": <AGENT_RESOPONSE_IN_STRING>},
+#   { "nest-2": <AGENT_RESOPONSE_IN_NUMBER>},
+# ]
+```
+
+<hr />
+
+### List with List
+
+```python
+import versionhq as vhq
+
+list_with_list = vhq.ResponseField(
+  title="parent",
+  data_type=list,
+  items=list
+)
+
+# Agent output
+# parent: [
+#   [<AGENT_RESOPONSE_IN_STRING>, ...],
+#   [<AGENT_RESOPONSE_IN_STRING>, ...]
+#   ...
+# ]
+```
+
+<hr />
+
+### Object with List
+
+```python
+import versionhq as vhq
+
+dict_with_list = vhq.ResponseField(
+  title="parent",
+  data_type=dict,
+  properties=[
+    vhq.ResponseField(title="nest-1", data_type=list, items=str),
+    vhq.ResponseField(title="nest-2", data_type=list, items=int),
+  ]
+)
+
+# Agent output
+# parent: {
+#   nest-1: [<AGENT_RESOPONSE_IN_STRING>, ...],
+#   nest-2: [<AGENT_RESOPONSE_IN_INTEGER>, ...]
+# }
+```
+
+<hr />
+
+### Object with Object
+
+```python
+import versionhq as vhq
+
+dict_with_dict = vhq.ResponseField(
+  title="parent",
+  data_type=dict,
+  properties=[
+    vhq.ResponseField(title="nest-1", data_type=dict, properties=[
+      vhq.ResponseField(title="nest-1-1", data_type=str)
+    ]),
+    vhq.ResponseField(title="nest-2", data_type=list, items=int),
+  ]
+)
+
+# Agent output
+# parent: {
+#   nest-1: { nest-1-1: <AGENT_RESOPONSE_IN_STRING>, },
+#   nest-2: [<AGENT_RESOPONSE_IN_INTEGER>, ...]
+# }
+```
+
+### Config
+
+`[var]`<bold>`config: Optional[Dict[str, Any]] = {}`</bold>
+
+You can add other configs you want to pass to the LLM.
+
+```python
+import versionhq as vhq
+
+response_field = vhq.ResponseField(
+  title="summary-with-config",
+  data_type=str,
+  nullable=False,
+  config=dict(required=False, )
+)
+
+# Agent output:
+# summary-with-config: <AGENT_RESPONSE_IN_STRING>
+```

{versionhq-1.2.0.4 → versionhq-1.2.1.1}/docs/core/task/task-output.md

@@ -7,7 +7,7 @@ tags:
 
 # TaskOutput
 
-<class>`class` versionhq.tasks.model.<bold>TaskOutput<bold></class>
+<class>`class` versionhq.task.model.<bold>TaskOutput<bold></class>
 
 A class to store and manage output from the `Task` object.
 

versionhq-1.2.1.1/docs/core/task-graph.md

@@ -0,0 +1,83 @@
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# TaskGraph
+
+<class>`class` versionhq.graph.model.<bold>TaskGraph<bold></class>
+
+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">
+
+
+## Core Usage
+
+`TaskGraph` needs at least two `nodes` and one `edges` to connect the nodes to function.
+
+You can define nodes and edges mannually by creating nodes from tasks, and defining edges.
+
+
+### Generating TaskGraph
+
+```python
+import versionhq as vhq
+
+task_graph = vhq.TaskGraph(directed=False, should_reform=True)
+
+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
+)
+
+critical_path, duration, paths = task_graph.find_critical_path()
+
+import uuid
+assert isinstance(task_graph, vhq.TaskGraph)
+assert [type(k) == uuid.uuid4 and isinstance(v, vhq.Node) and isinstance(v.task, vhq.Task) for k, v in task_graph.nodes.items()]
+assert [type(k) == uuid.uuid4 and isinstance(v, vhq.Edge) for k, v in task_graph.edges.items()]
+assert critical_path  and duration  and paths
+```
+
+
+### Activating TaskGraph
+
+Calling `.activate()` begins execution of the graph's nodes, respecting dependencies [`dependency-met`] and prioritizing the critical path.
+
+
+**[NOTES]**
+
+- If all nodes are already complete, outputs are returned without further execution.
+
+- If no critical path is found, execution begins with any dependency-met start nodes.
+
+
+```python
+import versionhq as vhq
+
+# Inherting the `task_graph` object in the previous code snippet,
+
+last_task_output, outputs = task_graph.activate()
+
+assert isinstance(last_task_output, vhq.TaskOutput)
+assert [k in task_graph.nodes.keys() and v and isinstance(v, vhq.TaskOutput) for k, v in outputs.items()]
+```