versionhq 1.2.1.7__tar.gz → 1.2.1.9__tar.gz

{versionhq-1.2.1.7 → versionhq-1.2.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.1.7
+Version: 1.2.1.9
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -81,7 +81,7 @@ Requires-Dist: pygraphviz>=1.14; extra == "pygraphviz"
 
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-17K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-20K+-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.1+-blue)
@@ -93,11 +93,10 @@ Agentic orchestration framework for multi-agent networks and task graphs for com
 
 **Visit:**
 
-- [PyPI](https://pypi.org/project/versionhq/)
+- [Playground](https://versi0n.io/playground)
 - [Docs](https://docs.versi0n.io)
 - [Github Repository](https://github.com/versionHQ/multi-agent-system)
-- [Playground](https://versi0n.io/)
-
+- [PyPI](https://pypi.org/project/versionhq/)
 
 <hr />
 
@@ -594,10 +593,4 @@ Common issues and solutions:
 ## Frequently Asked Questions (FAQ)
 **Q. Where can I see if the agent is working?**
 
-A. Visit [playground](https://versi0n.io).
-
-
-**Q. How do you analyze the customer?**
-
-A. We employ soft clustering for each customer.
-<img width="200" src="https://res.cloudinary.com/dfeirxlea/image/upload/v1732732628/pj_m_agents/ito937s5d5x0so8isvw6.png">
+A. Visit [playground](https://versi0n.io/playground).

{versionhq-1.2.1.7 → versionhq-1.2.1.9}/README.md

@@ -1,6 +1,6 @@
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-17K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-20K+-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.1+-blue)
@@ -12,11 +12,10 @@ Agentic orchestration framework for multi-agent networks and task graphs for com
 
 **Visit:**
 
-- [PyPI](https://pypi.org/project/versionhq/)
+- [Playground](https://versi0n.io/playground)
 - [Docs](https://docs.versi0n.io)
 - [Github Repository](https://github.com/versionHQ/multi-agent-system)
-- [Playground](https://versi0n.io/)
-
+- [PyPI](https://pypi.org/project/versionhq/)
 
 <hr />
 
@@ -513,10 +512,4 @@ Common issues and solutions:
 ## Frequently Asked Questions (FAQ)
 **Q. Where can I see if the agent is working?**
 
-A. Visit [playground](https://versi0n.io).
-
-
-**Q. How do you analyze the customer?**
-
-A. We employ soft clustering for each customer.
-<img width="200" src="https://res.cloudinary.com/dfeirxlea/image/upload/v1732732628/pj_m_agents/ito937s5d5x0so8isvw6.png">
+A. Visit [playground](https://versi0n.io/playground).

versionhq-1.2.1.7/docs/core/Agent.md → versionhq-1.2.1.9/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.7/docs/core/task.md → versionhq-1.2.1.9/docs/core/task/index.md

@@ -9,7 +9,7 @@ tags:
 
 A class to store and manage information for individual tasks, including their assignment to agents or agent networks, and dependencies via a node-based system that tracks conditions and status.
 
-Ref. Node / Edge / TaskGraph class
+Ref. Node / Edge / <a href="/core/task-graph">TaskGraph</a> class
 
 <hr />
 
@@ -284,6 +284,7 @@ Context can consist of `Task` objects, `TaskOutput` objects, plain text `strings
 
 In this scenario, `sub_task_2` executes before the main task. Its string output is then incorporated into the main task's context prompt on top of other context before the main task is executed.
 
+<hr>
 
 ## Executing
 
@@ -298,7 +299,6 @@ import versionhq as vhq
 
 task = vhq.Task(
     description="return the output following the given prompt.",
-    response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True)],
     allow_delegation=True
 )
 task.execute()
@@ -308,47 +308,169 @@ assert "vhq-Delegated-Agent" in task.processed_agents # delegated agent
 assert task.delegations ==1
 ```
 
+<hr>
 
-<!--
+**SYNC - ASYNC**
 
-## Callbacks
-    callback: Optional[Callable] = Field(default=None, description="callback to be executed after the task is completed.")
-    callback_kwargs: Optional[Dict[str, Any]] = Field(default_factory=dict, description="kwargs for the callback when the callback is callable")
+`[var]`<bold>`type: bool = False`</bold>
 
+You can specify whether the task will be executed asynchronously.
 
-### tools
-    tools: Optional[List[ToolSet | Tool | Any]] = Field(default_factory=list, description="tools that the agent can use aside from their tools")
-    can_use_agent_tools: bool = Field(default=False, description="whether the agent can use their own tools when executing the task")
-    tool_res_as_final: bool = Field(default=False, description="when set True, tools res will be stored in the `TaskOutput`")
+```python
+import versionhq as vhq
 
+task = vhq.Task(
+    description="Return a word: 'test'",
+    type=vhq.TaskExecutionType.ASYNC # default: vhq.TaskExecutionType.SYNC
+)
 
+from unittest.mock import patch
+with patch.object(vhq.Agent, "execute_task", return_value="test") as execute:
+    res = task.execute()
+    assert res.raw == "test"
+    execute.assert_called_once_with(task=task, context=None, task_tools=list())
+```
 
+<hr>
 
-## Executing tasks
- EXECUTION type
+**Using tools**
 
-### Sync
+`[var]`<bold>`tools: Optional[List[ToolSet | Tool | Any]] = None`</bold>
 
-<hr />
+`[var]`<bold>`tool_res_as_final: bool = False`</bold>
 
-### Async
 
-<hr />
+Tasks can directly store tools explicitly called by the agent.
 
-### Assigning agents
+If the results from the tool should be the final results, set `tool_res_as_final` True.
 
-<hr />
+This will allow the agent to store the tool results in the `tool_output` field of `TaskOutput` object.
 
-### Context
 
+```python
+import versionhq as vhq
+from typing import Callable
+
+def random_func(message: str) -> str:
+    return message + "_demo"
+
+tool = vhq.Tool(name="tool", func=random_func)
+tool_set = vhq.ToolSet(tool=tool, kwargs=dict(message="empty func"))
+task = vhq.Task(
+    description="execute the given tools",
+    tools=[tool_set,], # stores tools
+    tool_res_as_final=True, # stores tool results in TaskOutput object
+)
+
+res = task.execute()
+assert res.tool_output == "empty func_demo"
+```
+
+Ref. <a href="/core/tool">Tool</a> class / <a href="/core/task/task-output">TaskOutput</a> class
+
+<hr>
+
+**Using agents' tools**
+
+`[var]`<bold>`can_use_agent_tools: bool = True`</bold>
+
+Tasks can explicitly stop/start using agent tools on top of the tools stored in the task object.
+
+```python
+import versionhq as vhq
+
+simple_tool = vhq.Tool(name="simple tool", func=lambda x: "simple func")
+agent = vhq.Agent(role="demo", goal="execute tools", tools=[simple_tool,])
+task = vhq.Task(
+    description="execute tools",
+    can_use_agent_tools=True, # Flagged
+    tool_res_as_final=True
+)
+res = task.execute(agent=agent)
+assert res.tool_output == "simple func"
+```
 
+<hr>
+
+## Callback
+
+`[var]`<bold>`callback: Optional[Callable] = None`</bold>
+
+`[var]`<bold>`callback_kwargs: Optional[Dict[str, Any]] = dict()`</bold>
+
+After executing the task, you can run a `callback` function with `callback_kwargs` and task output as parameters.
+
+Callback results will be stored in `callback_output` filed of the `TaskOutput` object.
+
+```python
+import versionhq as vhq
+
+def callback_func(condition: str, test1: str):
+    return f"Result: {test1}, condition added: {condition}"
+
+task = vhq.Task(
+    description="return the output following the given prompt.",
+    callback=callback_func,
+    callback_kwargs=dict(condition="demo for pytest")
+)
+res = task.execute()
+
+assert res and isinstance(res, vhq.TaskOutput)
+assert res.task_id is task.id
+assert "demo for pytest" in res.callback_output
+```
+
+<hr>
 
 ## Evaluating
 
-    should_evaluate: bool = Field(default=False, description="True to run the evaluation flow")
-    eval_criteria: Optional[List[str]] = Field(default_factory=list, description="criteria to evaluate the outcome. i.e., fit to the brand tone")
+`[var]`<bold>`should_evaluate: bool = False`</bold>
+
+`[var]`<bold>`eval_criteria: Optional[List[str]] = list()`</bold>
+
+You can turn on customized evaluations using the given criteria.
+
+Refer <a href="/core/task/task-output">TaskOutput</a> class for details.
+
+<hr>
+
+
+## Reference
+
+### Variables
+
+| <div style="width:160px">**Variable**</div> | **Data Type** | **Default** | **Nullable** | **Description** |
+| :---               | :---  | :--- | :--- | :--- |
+| **`id`**   | UUID  | uuid.uuid4() | False | Stores task `id` as an identifier. |
+| **`name`**       | Optional[str]   | None | True | Stores a task name (Inherited as `node` identifier if the task is dependent) |
+| **`description`**       | str   | None | False | Required field to store a concise task description |
+| **`pydantic_output`** | Optional[Type[BaseModel]] | None | True | Stores pydantic custom output class for structured response |
+| **`response_fields`** | Optional[List[ResponseField]]  | list() | True | Stores JSON formats for stuructured response |
+| **`tools`** |  Optional[List[ToolSet | Tool | Any]] | None | True | Stores tools to be called when the agent executes the task. |
+| **`can_use_agent_tools`** |  bool | True | - | Whether to use the agent tools |
+| **`tool_res_as_final`** |  bool | False | - | Whether to make the tool response a final response from the agent |
+| **`execution_type`** | TaskExecutionType  | TaskExecutionType.SYNC | - | Sync or async execution |
+| **`allow_delegation`** | bool  | False | - | Whether to allow the agent to delegate the task to another agent |
+| **`callback`** | Optional[Callable] | None | True | Callback function to be executed after LLM calling |
+| **`callback_kwargs`** | Optional[Dict[str, Any]] | dict() | True | Args for the callback function (if any)|
+| **`should_evaluate`** | bool | False | - | Whether to evaluate the task output using eval criteria |
+| **`eval_criteria`** | Optional[List[str]] | list() | True | Evaluation criteria given by the human client |
+| **`processed_agents`** | Set[str] | set() | True | [Ops] Stores roles of the agents executed the task |
+| **`tool_errors`** | int | 0 | True | [Ops] Stores number of tool errors |
+| **`delegation`** | int | 0 | True | [Ops] Stores number of agent delegations |
+| **`output`** | Optional[TaskOutput] | None | True | [Ops] Stores `TaskOutput` object after the execution |
+
+
+### Class Methods
+
+| <div style="width:120px">**Method**</div> |  <div style="width:300px">**Params**</div> | **Returns** | **Description** |
+| :---               | :---  | :--- | :--- |
+| **`execute`**  | <p>type: TaskExecutionType = None<br>agent: Optional["vhq.Agent"] = None<br>context: Optional[Any] = None</p> | InstanceOf[`TaskOutput`] or None (error) |  A main method to handle task execution. Auto-build an agent when the agent is not given. |
 
 
-## Recording
+### Properties
 
-output: Optional[TaskOutput] = Field(default=None, description="store the final task output in TaskOutput class") -->
+| <div style="width:120px">**Property**</div> | **Returns** | **Description** |
+| :---               | :---  | :--- |
+| **`key`**   | str | Returns task key based on its description and output format. |
+| **`summary`**  | str   | Returns a summary of the task based on its id, description and tools. |

{versionhq-1.2.1.7 → versionhq-1.2.1.9}/docs/core/task/response-field.md

@@ -7,7 +7,7 @@ tags:
 
 <class>`class` versionhq.task.model.<bold>ResponseField<bold></class>
 
-A Pydantic class to store response formats to create JSON response schema.
+A Pydantic class to store response formats to generate a structured response in JSON.
 
 <hr/>
 
@@ -105,7 +105,7 @@ Agents can handle **one layer** of nested items usign `properties` and `items` f
 
 We highly recommend to use `gemini-x` or `gpt-x` to get stable results.
 
-### List with Object
+### Object in List
 
 ```python
 import versionhq as vhq
@@ -129,7 +129,7 @@ list_with_objects = vhq.ResponseField(
 
 <hr />
 
-### List with List
+### List in List
 
 ```python
 import versionhq as vhq
@@ -150,7 +150,7 @@ list_with_list = vhq.ResponseField(
 
 <hr />
 
-### Object with List
+### List in Object
 
 ```python
 import versionhq as vhq
@@ -173,7 +173,7 @@ dict_with_list = vhq.ResponseField(
 
 <hr />
 
-### Object with Object
+### Object in Object
 
 ```python
 import versionhq as vhq

versionhq-1.2.1.7/docs/core/task-graph.md → versionhq-1.2.1.9/docs/core/task-graph/index.md

@@ -23,7 +23,7 @@ The following example demonstrates a simple concept of a `supervising` agent net
 You can define nodes and edges mannually by creating nodes from tasks, and defining edges.
 
 
-### Generating TaskGraph
+### Generating
 
 ```python
 import versionhq as vhq
@@ -57,7 +57,7 @@ assert critical_path  and duration  and paths
 ```
 
 
-### Activating TaskGraph
+### Activating
 
 Calling `.activate()` begins execution of the graph's nodes, respecting dependencies [`dependency-met`] and prioritizing the critical path.