versionhq 1.2.1.8__tar.gz → 1.2.1.10__tar.gz

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.1.8
+Version: 1.2.1.10
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License

versionhq-1.2.1.8/docs/core/Agent.md → versionhq-1.2.1.10/docs/core/agent/index.md

@@ -27,9 +27,9 @@ agent = vhq.Agent(
 
 <hr />
 
-## Customization
+## Customizing
 
-### Model optimization
+**Model Optimization**
 
 `[var]`<bold>`llm: Optional[str | LLM | Dict[str, Any]] = "gpt-4o"`</bold>
 
@@ -47,7 +47,9 @@ agent = vhq.Agent(
 )
 ```
 
-### Switching models
+<hr/>
+
+**Switching Models**
 
 `[class method]`<bold>`update_llm(self, llm: Any = None, llm_config: Optional[Dict[str, Any]] = None) -> Self`<bold>
 
@@ -69,12 +71,14 @@ assert agent.llm.max_tokens == 3000
 
 <hr/>
 
-### Developer Prompt (System Prompt)
+**Developer Prompt (System Prompt)**
 
 `[var]`<bold>`backstory: Optional[str] = TEMPLATE_BACKSTORY`<bold>
 
 Backstory will be drafted automatically using the given role, goal and other values in the Agent model, and converted into the **developer prompt** when the agent executes the task.
 
+<hr/>
+
 **Backstory template (full) for auto drafting:**
 
 ```python
@@ -127,9 +131,11 @@ agent = vhq.Agent(
 )
 ```
 
-## Task Execution Rules
+<hr />
+
+## Executing Tasks
 
-### Delegation
+**Delegation**
 
 `[var]`<bold>`allow_delegation: [bool] = False`</bold>
 
@@ -145,7 +151,9 @@ agent = vhq.Agent(
 )
 ```
 
-### Max Retry Limit
+<hr />
+
+**Max Retry Limit**
 
 `[var]`<bold>`max_retry_limit: Optional[int] = 2`</bold>
 
@@ -161,7 +169,9 @@ agent = vhq.Agent(
 )
 ```
 
-### Maximum Number of Iterations (MaxIt)
+<hr />
+
+**Maximum Number of Iterations (maxit)**
 
 `[var]`<bold>`maxit: Optional[int] = 25`</bold>
 
@@ -179,76 +189,9 @@ agent = vhq.Agent(
 )
 ```
 
-### Callbacks
-
-`[var]`<bold>`callbacks: Optional[List[Callable]] = None`</bold>
-
-You can add callback functions that the agent will run after executing any task.
-
-By default, raw response from the agent will be added to the arguments of the callback function.
-
-e.g. Format a response after executing the task:
-
-```python
-import json
-import versionhq as vhq
-from typing import Dict, Any
-
-
-def format_response(res: str = None) -> str | Dict[str, Any]:
-	try:
-		r = json.dumps(eval(res))
-		formatted_res = json.loads(r)
-		return formatted_res
-	except:
-		return res
-
-agent = vhq.Agent(
-	role="Marketing Analyst",
-	goal="Coping with increased price competition in saturated markets.",
-	callbacks=[format_response]
-)
-```
-
-**Multiple callbacks to call**
-
-The callback functions are called in order of the list index referring to the task response and response from the previous callback functions by default.
-
-e.g. Validate an initial response from the assigned agent, and format the response.
-
-```python
-import json
-from typing import Dict, Any
-import versionhq as vhq
-
-def assessment(res: str) -> str:
-    try:
-        sub_agent = vhq.Agent(role="Validator", goal="Validate the given solutions.")
-        task = vhq.Task(
-            description=f"Assess the given solution based on feasibilities and fits to client's strategies, then refine the solution if necessary.\nSolution: {res}"
-        )
-        r = task.sync_execute(agent=sub_agent)
-        return r.raw
-
-    except:
-        return res
-
-def format_response(res: str = None) -> str | Dict[str, Any]:
-    try:
-        r = json.dumps(eval(res))
-        formatted_res = json.loads(r)
-        return formatted_res
-    except:
-        return res
-
-agent = vhq.Agent(
-    role="Marketing Analyst",
-    goal="Build solutions to address increased price competition in saturated markets",
-    callbacks=[assessment, format_response] # add multiple funcs as callbacks - executed in order of index
-)
-```
+<hr />
 
-### Context Window
+**Context Window**
 
 `[var]`<bold>`respect_context_window: [bool] = True`</bold>
 
@@ -260,7 +203,10 @@ By default, the agent will follow **the 80% rule** - where they only use 80% of
 
 You can turn off this rule by setting `respect_context_window` False to have larger context window.
 
-### Max Tokens
+
+<hr />
+
+**Max Tokens**
 
 `[var]`<bold>`max_tokens: Optional[int] = None`</bold>
 
@@ -268,7 +214,10 @@ Max tokens defines the maximum number of tokens in the generated response. Token
 
 By default, the agent will follow the default max_tokens of the model, but you can specify the max token to limit the length of the generated output.
 
-### Maximum Execution Time
+
+<hr />
+
+**Maximum Execution Time**
 
 `[var]`<bold>`max_execution_times: Optional[int] = None`</bold>
 
@@ -276,7 +225,10 @@ The maximum amount of wall clock time to spend in the execution loop.
 
 By default, the agent will follow the default setting of the model.
 
-### Maximum RPM (Requests Per Minute)
+
+<hr />
+
+**Maximum RPM (Requests Per Minute)**
 
 `[var]`<bold>`max_rpm: Optional[int] = None`</bold>
 
@@ -284,7 +236,9 @@ The maximum number of requests that the agent can send to the LLM.
 
 By default, the agent will follow the default setting of the model. When the value is given, we let the model sleep for 60 seconds when the number of executions exceeds the maximum requests per minute.
 
-### Other LLM Configuration
+<hr />
+
+**Other LLM Configuration**
 
 `[var]`<bold>`llm_config: Optional[Dict[str, Any]] = None`</bold>
 
@@ -326,12 +280,84 @@ print(agent.llm)
 #     max_completion_tokens=10000,
 # )
 ```
+<hr >
+
+## Callbacks
+
+`[var]`<bold>`callbacks: Optional[List[Callable]] = None`</bold>
+
+You can add callback functions that the agent will run after executing any task.
+
+By default, raw response from the agent will be added to the arguments of the callback function.
+
+e.g. Format a response after executing the task:
+
+```python
+import json
+import versionhq as vhq
+from typing import Dict, Any
+
+
+def format_response(res: str = None) -> str | Dict[str, Any]:
+	try:
+		r = json.dumps(eval(res))
+		formatted_res = json.loads(r)
+		return formatted_res
+	except:
+		return res
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+	callbacks=[format_response]
+)
+```
+
+<hr />
+
+**Multiple callbacks to call**
+
+The callback functions are called in order of the list index referring to the task response and response from the previous callback functions by default.
+
+e.g. Validate an initial response from the assigned agent, and format the response.
+
+```python
+import json
+from typing import Dict, Any
+import versionhq as vhq
+
+def assessment(res: str) -> str:
+    try:
+        sub_agent = vhq.Agent(role="Validator", goal="Validate the given solutions.")
+        task = vhq.Task(
+            description=f"Assess the given solution based on feasibilities and fits to client's strategies, then refine the solution if necessary.\nSolution: {res}"
+        )
+        r = task.sync_execute(agent=sub_agent)
+        return r.raw
+
+    except:
+        return res
+
+def format_response(res: str = None) -> str | Dict[str, Any]:
+    try:
+        r = json.dumps(eval(res))
+        formatted_res = json.loads(r)
+        return formatted_res
+    except:
+        return res
+
+agent = vhq.Agent(
+    role="Marketing Analyst",
+    goal="Build solutions to address increased price competition in saturated markets",
+    callbacks=[assessment, format_response] # add multiple funcs as callbacks - executed in order of index
+)
+```
 
 <hr />
 
-## Knowledge
+## Building Knowledge
 
-### Knowledge Sources
+**Knowlege Source**
 
 `[var]`<bold>`knowledge_sources: Optional[List[KnowledgeSource]] = None`</bold>
 
@@ -373,9 +399,9 @@ assert "gold" in res.raw  == True
 
 <hr />
 
-## Memory
+## Accessing Memories
 
-### Store task execution results in memory
+Store task execution results in memory
 
 `[var]`<bold>`use_memory: bool = False`</bold>
 
@@ -397,7 +423,9 @@ print(agent.long_term_memory)
 # returns LongTermMemory object.
 ```
 
-### RAG Storage
+<hr />
+
+**RAG Storage**
 
 When the agent is not given any `memory_config` values, they will create `RAGStorage` to store memory:
 
@@ -418,7 +446,7 @@ MEM0 Storage
 
 ## Utilities
 
-### Model configuration
+**Model configuration**
 
 `[var]`<bold>`config: Optional[Dict[str, Any]] = None`</bold>
 
@@ -450,7 +478,7 @@ agent = vhq.Agent(
 
 <hr />
 
-### Updating model values
+**Updating existing agents**
 
 `[class method]`<bold>`update(self, **kwargs) -> Self`</bold>
 

versionhq-1.2.1.8/docs/core/task.md → versionhq-1.2.1.10/docs/core/task/index.md

@@ -435,7 +435,7 @@ Refer <a href="/core/task/task-output">TaskOutput</a> class for details.
 <hr>
 
 
-## Ref
+## Reference
 
 ### Variables
 

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/mkdocs.yml

@@ -94,6 +94,7 @@ theme:
     - header.autohide
     - navigation.tabs
     - navigation.path
+    - navigation.expand
     - navigation.top
     - navigation.footer
     - navigation.indexes
@@ -110,16 +111,18 @@ nav:
   - Home: 'index.md'
   - Quick Start: 'quickstart.md'
   - Core Components:
-    - Agent: 'core/agent.md'
-    - Task Graph: 'core/task-graph.md'
+    - Agent:
+      - 'core/agent/index.md'
+    - Task Graph:
+      - 'core/task-graph/index.md'
     - Task:
-      - Task: 'core/task.md'
+      - 'core/task/index.md'
       - ResponseField: 'core/task/response-field.md'
       - TaskOutput: 'core/task/task-output.md'
       - Evaluation: 'core/task/evaluation.md'
     - Tool: 'core/tool.md'
   - Tags: 'tags.md'
-  - Examples:
+  - Cases:
     - Playground: https://versi0n.io/playground
     - Experiment - Agent Performance: https://github.com/versionHQ/exp-agent-performance
   - Change Log: https://github.com/versionHQ/multi-agent-system/releases

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/pyproject.toml

@@ -15,7 +15,7 @@ exclude = ["test*", "__pycache__", "*.egg-info"]
 
 [project]
 name = "versionhq"
-version = "1.2.1.8"
+version = "1.2.1.10"
 authors = [{ name = "Kuriko Iwai", email = "kuriko@versi0n.io" }]
 description = "An agentic orchestration framework for building agent networks that handle task automation."
 readme = "README.md"

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/src/versionhq/__init__.py

@@ -31,7 +31,7 @@ from versionhq.task.formation import form_agent_network
 from versionhq.task_graph.draft import workflow
 
 
-__version__ = "1.2.1.8"
+__version__ = "1.2.1.10"
 __all__ = [
     "Agent",
 

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/src/versionhq/task_graph/draft.py

@@ -49,11 +49,12 @@ def workflow(final_output: Type[BaseModel], context: Any = None, human: bool = T
     )
 
     task = Task(
-        description=f"Design a resource-efficient workflow to achieve the following goal: {final_output_prompt}.  The workflow should consist of a list of tasks, each with the following information:\nname: A concise name of the task\ndescription: A concise description of the task.\nconnections: A list of target tasks that this task connects to.\ndependency_types: The type of dependency between this task and each of its connected task. Use the following dependency types: {dep_type_prompt}.\n\nPrioritize minimizing resource consumption (computation, memory, and data transfer) when defining tasks, connections, and dependencies.  Consider how data is passed between tasks and aim to reduce unnecessary data duplication or transfer.  Explain any design choices made to optimize resource usage.",
+        description=dedent(f"Design a resource-efficient workflow to achieve the following goal: {final_output_prompt}. The workflow should consist of a list of detailed tasks that represent decision making points, each with the following information:\nname: A concise name of the task\ndescription: A concise description of the task.\nconnections: A list of target tasks that this task connects to.\ndependency_types: The type of dependency between this task and each of its connected task. \noutput: key output from the task.\n\nUse the following dependency types: {dep_type_prompt}.\n\nPrioritize minimizing resource consumption (computation, memory, and data transfer) when defining tasks, connections, and dependencies.  Consider how data is passed between tasks and aim to reduce unnecessary data duplication or transfer. Explain any design choices made to optimize resource usage."),
         response_fields=[
             ResponseField(title="tasks", data_type=list, items=dict, properties=[
                     ResponseField(title="name", data_type=str),
                     ResponseField(title="description", data_type=str),
+                    ResponseField(title="output", data_type=str),
                     ResponseField(title="connections", data_type=list, items=str),
                     ResponseField(title="dependency_types", data_type=list, items=str),
                 ]
@@ -66,11 +67,20 @@ def workflow(final_output: Type[BaseModel], context: Any = None, human: bool = T
         return None
 
     task_items = res.json_dict["tasks"]
-    tasks = [Task(name=item["name"], description=item["description"]) for item in task_items]
-    nodes = [Node(task=task) for task in tasks]
+    tasks, nodes = [], []
+    for item in task_items:
+        class Output(BaseModel):
+            item["output"]: str
+
+        task = Task(name=item["name"], description=item["description"], pydantic_output=Output)
+        tasks.append(task)
+        nodes.append(Node(task=task))
+
+
     task_graph = TaskGraph(
         nodes={node.identifier: node for node in nodes},
-        concl=final_output,
+        concl_format=final_output,
+        concl=None,
         should_reform=True,
     )
 
@@ -79,23 +89,24 @@ def workflow(final_output: Type[BaseModel], context: Any = None, human: bool = T
             dependency_types = [DependencyType[dt] if DependencyType[dt] else DependencyType.FINISH_TO_START for dt in res["dependency_types"]]
 
             for i, target_task_name in enumerate(res["connections"]):
-                source = [v for k, v in task_graph.nodes.items() if v.task.name == res["name"]][0]
-                target = [v for k, v in task_graph.nodes.items() if v.task.name == target_task_name][0]
+                source = [v for v in task_graph.nodes.values() if v.task.name == res["name"]][0]
+                target = [v for v in task_graph.nodes.values() if v.task.name == target_task_name][0]
                 dependency_type = dependency_types[i]
-                task_graph.add_dependency(source_node_identifier=source.identifier, target_node_identifier=target.identifier, dependency_type=dependency_type)
+                task_graph.add_dependency(
+                    source_node_identifier=source.identifier, target_node_identifier=target.identifier, dependency_type=dependency_type)
+
 
-    ## test purpose
-    # task_graph.visualize()
+    task_graph.visualize()
 
-    # if human:
-    #     print('Proceed? Y/n:')
-    #     x = input()
+    if human:
+        print('Proceed? Y/n:')
+        x = input()
 
-    #     if x.lower() == "y":
-    #         print("ok. generating agent network")
+        if x.lower() == "y":
+            print("ok. generating agent network")
 
-    #     else:
-    #         request = input("request?")
-    #         print('ok. regenerating the graph based on your input: ', request)
+        else:
+            request = input("request?")
+            print('ok. regenerating the graph based on your input: ', request)
 
     return task_graph

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/src/versionhq/task_graph/model.py

@@ -1,12 +1,14 @@
+import matplotlib
+matplotlib.use('agg')
+
 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 typing_extensions import Self
 
-from pydantic import BaseModel, InstanceOf, Field, UUID4, field_validator, model_validator
+from pydantic import BaseModel, InstanceOf, Field, UUID4, field_validator
 from pydantic_core import PydanticCustomError
 
 from versionhq.task.model import Task, TaskOutput
@@ -60,7 +62,7 @@ class Node(BaseModel):
     def is_independent(self) -> bool:
         return not self.in_degree_nodes and not self.out_degree_nodes
 
-    def handle_task_execution(self, agent: Agent = None, context: str = None) -> TaskOutput | None:
+    def handle_task_execution(self, agent: Agent = None, context: str = None, format: Type[BaseModel] = None) -> TaskOutput | None:
         """
         Start task execution and update status accordingly.
         """
@@ -72,6 +74,7 @@ class Node(BaseModel):
             self.status = TaskStatus.ERROR
             return None
 
+        self.task.pydantic_output = self.task.pydantic_output if self.task.pydantic_output else format if type(format) == BaseModel else None
         res = self.task.execute(agent=agent, context=context)
         self.status = TaskStatus.COMPLETED if res else TaskStatus.ERROR
         return res
@@ -176,7 +179,7 @@ class Edge(BaseModel):
                     return False
 
 
-    def activate(self) -> TaskOutput | None:
+    def activate(self, format: Type[BaseModel] = None) -> TaskOutput | None:
         """
         Activates the edge to initiate task execution of the target node.
         """
@@ -194,7 +197,7 @@ class Edge(BaseModel):
             time.sleep(self.lag)
 
         context = self.source.task.output.raw if self.data_transfer else None
-        res = self.target.handle_task_execution(context=context)
+        res = self.target.handle_task_execution(context=context, format=format)
         return res
 
 
@@ -398,7 +401,7 @@ class TaskGraph(Graph):
         return self._return_node_object(identifier).status
 
 
-    def visualize(self, layout: str = None):
+    def visualize(self, layout: str = None, should_save: bool = False):
         from matplotlib.lines import Line2D
         from versionhq.task_graph.colors import white, black, darkgrey, grey, primary, orange, lightgreen, green, darkgreen, darkergreen
 
@@ -475,7 +478,9 @@ class TaskGraph(Graph):
 
         plt.legend(handles=legend_elements, loc='lower right')
         plt.title(f"vhq-Diagram {str(self.id)}")
-        self._save(title=f"vhq-Diagram {str(self.id)}")
+
+        if should_save:
+            self._save(title=f"vhq-Diagram {str(self.id)}")
         plt.show(block=False)
 
 
@@ -559,5 +564,7 @@ class TaskGraph(Graph):
                     node_identifier = edge.target.identifier
                     self.outputs.update({ node_identifier: res })
 
+            self.concl = res
+            self.concl_template = self.concl_template if self.concl_template else res.pydantic.__class__ if res.pydantic else None
             # 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-1.2.1.8 → versionhq-1.2.1.10}/src/versionhq.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.1.8
+Version: 1.2.1.10
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/src/versionhq.egg-info/SOURCES.txt

@@ -23,13 +23,13 @@ docs/quickstart.md
 docs/tags.md
 docs/_logos/favicon.ico
 docs/_logos/logo192.png
-docs/core/Agent.md
-docs/core/task-graph.md
-docs/core/task.md
 docs/core/tool.md
+docs/core/agent/index.md
 docs/core/task/evaluation.md
+docs/core/task/index.md
 docs/core/task/response-field.md
 docs/core/task/task-output.md
+docs/core/task-graph/index.md
 docs/stylesheets/main.css
 src/versionhq/__init__.py
 src/versionhq.egg-info/PKG-INFO

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/tests/formation_test.py

@@ -33,7 +33,6 @@ def _test_specific_formation():
             task="Describe the color of the sky by weather condition",
             expected_outcome="Dict that pairs color of the sky with specific weather condition",
             formation=item,
-
         )
 
         assert isinstance(network, vhq.AgentNetwork)

{versionhq-1.2.1.8 → versionhq-1.2.1.10}/tests/task_graph/doc_test.py

@@ -31,8 +31,4 @@ def test_create_and_activate_network():
 
     assert last_task_output is not None and 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()]
-
-    task_graph.visualize()
-
-
-test_create_and_activate_network()
+    assert task_graph.concl == last_task_output and task_graph.concl_template == None

versionhq-1.2.1.10/tests/task_graph/task_graph_test.py

@@ -0,0 +1,27 @@
+from unittest.mock import patch
+
+
+def test_draft():
+    import versionhq as vhq
+    from pydantic import BaseModel
+
+    class Trip(BaseModel):
+        name: str
+        location: str
+        description: str
+        date: str
+        cousine: str
+        why_its_suitable: str
+
+
+    with patch('builtins.input', return_value='Y'):
+        task_graph = vhq.workflow(
+            Trip,
+            context="Planning a suprise day trip for my friend to celebrate her birthday. We live in CA and we like to have Korean food.",
+            human=True
+        )
+
+        assert task_graph
+        assert [k == node.identifier and node.task and isinstance(node, vhq.Node) for k, node in task_graph.nodes.items()]
+        assert [isinstance(edge.dependency_type, vhq.DependencyType) and isinstance(edge, vhq.Edge) for k, edge in task_graph.edges.items()]
+        assert [k in task_graph.nodes.keys() and v.status == vhq.TaskStatus.NOT_STARTED for k, v in task_graph.nodes.items()]