versionhq 1.2.3.8__tar.gz → 1.2.4.1__tar.gz

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.3.8
-Summary: An agentic orchestration framework for building agent networks that handle task automation.
+Version: 1.2.4.1
+Summary: A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
         
@@ -88,15 +88,15 @@ Requires-Dist: torchvision>=0.21.0; extra == "torch"
 
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-20K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-30K+-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.2+-blue)
+![PyPI](https://img.shields.io/badge/PythonSDK-v1.2.4+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11|3.12|3.13-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
-Agentic orchestration framework for multi-agent networks and task graphs for complex task automation.
+A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
 
 **Visit:**
 
@@ -154,11 +154,11 @@ 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** | **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> |
-| **Use case** | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
+|                 | **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> |
+| **Use case**    | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
 
 <hr />
 

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/README.md

@@ -1,14 +1,14 @@
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-20K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-30K+-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.2+-blue)
+![PyPI](https://img.shields.io/badge/PythonSDK-v1.2.4+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11|3.12|3.13-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
-Agentic orchestration framework for multi-agent networks and task graphs for complex task automation.
+A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
 
 **Visit:**
 
@@ -66,11 +66,11 @@ 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** | **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> |
-| **Use case** | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
+|                 | **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> |
+| **Use case**    | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
 
 <hr />
 

versionhq-1.2.4.1/docs/core/agent-network/ref.md

@@ -0,0 +1,139 @@
+---
+tags:
+  - Agent Network
+---
+
+
+## Class `AgentNetwork`
+
+### Variable
+
+| <div style="width:200px">**Variable**</div> | **Data Type** | **Default**                     | **Description**                                       |
+| :---                          | :---                        | :---                            | :---                                                  |
+| **`id`**                      | UUID4                       | uuid.uuid4()                    | Stores auto-generated ID as identifier. Not editable. |
+| **`name`**                    | str                         | None                            | Stores a name of the network.                         |
+| **`members`**                 | List[`Member`]              | list()                          | Stores a list of `Member` objects.                    |
+| **`formation`**               | `Formation`                 | None                            | Stores `Formation` enum.                              |
+| **`should_reform`**           | bool                        | False                           | Whether to reform the network during the activation.  |
+| **`network_tasks`**           | List[`Task`]                | list()                          | A list of `Task` objects unassigned to any network members. |
+| **`prompt_file`**             | str                         | None                            | Absolute file path to the prompt file w/ JSON formatted prompt. |
+| **`process`**                 | `TaskHandlingProcess`       | TaskHandlingProcess.SEQUENTIAL  | Enum of the task handling process.                    |
+| **`consent_trigger`**         | Callable[..., Any]          | None                            | A trigger event (func) for consentual processing.     |
+| **`pre_launch_callbacks`**    | List[Callable[..., Any]]    | list()                          | Stores callbacks to run before the network launch.    |
+| **`post_launch_callbacks`**   | List[Callable[..., Any]]    | list()                          | Stores callbacks to run after the network launch.     |
+| **`step_callbacks`**          | Callable[..., Any]          | None                            | Stores callbacks to run at every step of each member agent takes during the activation. |
+| **`cache`**                   | bool                        | True                            | Whether to store cache.                               |
+| **`execution_logs`**          |  List[Dict[str, Any]]       | list()                          | Stores a list of execution logs of all the tasks in the network. |
+
+
+### Class Methods
+
+| <div style="width:200px">**Method**</div> | **Params** | **Returns** | **Description** |
+| :---                                      | :---  | :--- | :--- |
+| **`launch`**                              | kwargs_pre: Optional[Dict[str, str]] = None <br> kwargs_post: Optional[Dict[str, Any]] = None <br> start_index: int = None | Tuple[TaskOutput, TaskGraph]: | Core method to launch the network and execute tasks |
+
+
+### Properties
+
+| <div style="width:200px">**Property**</div>   | **Returns**                 | **Description**                       |
+| :---                                          | :---                        | :---                                  |
+| **`key`**                                     | str                         | Unique identifier.                    |
+| **`managers`**                                | List[InstanceOf[`Member`]]  | A list of manager members.            |
+| **`manager_tasks`**                           | List[InstanceOf[`Task`]]    | A list of tasks handled by managers.  |
+| **`tasks`**                                   | List[InstanceOf[`Task`]]    | All the tasks in the network.         |
+| **`unassigned_member_tasks`**                 | List[InstanceOf[`Task`]]    | Unassigned member-level tasks.        |
+
+
+<hr>
+
+## Class `Member`
+
+### Variable
+
+| <div style="width:200px">**Variable**</div> | **Data Type** | **Default** | **Description**                                                             |
+| :---                        | :---                          | :---        |  :---                                                                       |
+| **`agent`**                 | InstanceOf[`Agent`]           | None        | Agent as a member                                                           |
+| **`is_manager`**            | bool                          | False       | Whether the member is a manager.                                            |
+| **`can_share_knowledge`**   | bool                          | True        | Whether the member can share its knowledge among the other network members. |
+| **`can_share_memory`**      | bool                          | True        | Whether the member can share its memories among the other network members.  |
+| **`tasks`**                 | List[InstanceOf[`Task`]]      | list()      | Assinged tasks.                                                             |
+
+
+### Properties
+
+| <div style="width:200px">**Property**</div> | **Returns** | **Description**                               |
+| :---                                        | :---        | :---                                          |
+| **`is_idling`**                             | bool        | Whether it has unprocessed assgined task/s    |
+
+<hr>
+
+## Class `Agent`
+
+### Variables
+
+| <div style="width:200px">**Variable**</div> | **Data Type** | **Default** | **Description** |
+| :---                                        | :---  | :--- | :--- |
+| **`id`**                                    | UUID4 | uuid.uuid4() | Stores auto-generated ID as identifier. Not editable. |
+| **`role`**                                  | str | None | Stores a role of the agent. |
+| **`goal`**                                  | str | None | Stores a goal of the agent. |
+| **`backstory`**                             | str | None | Stores backstory of the agent. Utilized as system prompt. |
+| **`tools`**                                 | List[InstanceOf[`Tool` \| `ToolSet`] \| Type[`Tool`]] | None | Stores tools to be used when executing a task. |
+| **`knowledge_sources`**                     | List[`BaseKnowledgeSource` \| Any]  | None | Stores knowledge sources in text, file path, or url. |
+| **`embedder_config`**                       | Dict[str, Any] | None | Stores embedding configuration for storing knowledge sources. |
+| **`with_memory`**                           | bool | False | Whether to store tasks and results in memory. |
+| **`memory_config`**                         | Dict[str, Any] | None | Stores configuration of the memory. |
+| **`short_term_memory`**                     | InstanceOf[`ShortTermMemory`] | None | Stores `ShortTermMemory` object. |
+| **`long_term_memory`**                      | InstanceOf[`LongTermMemory`] | None | Stores `LongTermMemory` object. |
+| **`user_memory`**                           | InstanceOf[`UserMemory`] | None | Stores `UserMemory` object. |
+| **`use_developer_prompt`**                  |  bool | True | Whether to use the system (developer) prompt when calling the model. |
+| **`developer_promt_template`**              | str | None | File path to the prompt template. |
+| **`user_promt_template`**                   | str | None | File path to the prompt template. |
+| **`networks`**                              | List[Any]   | list() | Stores a list of agent networks that the agent belongs to. |
+| **`allow_delegation`**                      | bool | False | Whether the agent can delegate assinged tasks to another agent. |
+| **`max_retry_limit`**                       | int | 2 | Maximum number of retries when the task execution failed. |
+| **`maxit`**                                 | int | 25 | Maximum number of total optimization loops conducted when an error occues during the task execution. |
+| **`callbacks`**                             | List[Callabale] | None | Stores a list of callback functions that must be called after every task execution completed.|
+| **`llm`**                                   | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | Stores the main model that the agent runs on. |
+| **`func_calling_llm`**                      | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | Stores the function calling model that the agent runs on. |
+| **`respect_context_window`**                | bool | True | Whether to follow the main model's maximum context window size. |
+| **`max_execution_time`**                    | int | None | Stores maximum execution time in seconds. |
+| **`max_rpm`**                               | int | None | Stores maximum number of requests per minute. |
+| **`llm_config`**                            | Dict[str, Any] | None | Stores configuration of `LLM` object. |
+| **`config`**                                | Dict[str, Any] | None | Stores model config. |
+
+
+### Class Methods
+
+| <div style="width:200px">**Method**</div> | **Params** | **Returns** | **Description** |
+| :---  | :--- | :--- | :--- |
+| **`update`** | **kwargs: Any  | Self | Updates agents with given kwargs. Invalid keys will be ignored. |
+| **`start`** | context: Any = None <br> tool_res_as_final: bool = False  | `TaskOutput` \| None  | Starts to operate the agent. |
+| **`execute_task`** | task: [Task] <br> context: Any = None <br> task_tools: Optional[List[Tool \| ToolSet]] = list() | str | Returns response from the model in plane text format. |
+
+
+### Properties
+
+| <div style="width:200px">**Property**</div> | **Returns** | **Description**                                                 |
+| :---                                        | :---        | :---                                                            |
+| **`key`**                                   | str         | Unique identifier of the agent using its ID and sanitized role. |
+
+
+## ENUM `Formation`
+
+```python
+class Formation(str, Enum):
+    SOLO = 1
+    SUPERVISING = 2
+    SQUAD = 3
+    RANDOM = 4
+    HYBRID = 10
+```
+
+## ENUM `TaskHandlingProcess`
+
+```python
+class TaskHandlingProcess(str, Enum):
+    HIERARCHY = 1
+    SEQUENTIAL = 2
+    CONSENSUAL = 3
+```

versionhq-1.2.4.1/docs/core/task/reference.md

@@ -0,0 +1,123 @@
+## Class `Task`
+
+### Variables
+
+| <div style="width:160px">**Variable**</div> | **Data Type**       | **Default**               | **Description**                   |
+| :---                      | :---                                  | :---                      | :---                              |
+| **`id`**                  | UUID                                  | uuid.uuid4()              | Stores task `id` as an identifier. |
+| **`name`**                | Optional[str]                         | None                      | Stores a task name (Inherited as `node` identifier if the task is dependent) |
+| **`description`**         | str                                   | None                      | Required field to store a concise task description |
+| **`pydantic_output`**     | Optional[Type[BaseModel]]             | None                      | Stores pydantic custom output class for structured response |
+| **`response_fields`**     | Optional[List[ResponseField]]         | list()                    | Stores JSON formats for stuructured response |
+| **`tools`**               | Optional[List[BaseTool \| ToolSet]]   | None                      | 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 a tool output as a final response from the agent |
+| **`image`**               | Optional[str]                         | None                      | Stores an absolute file path or URL to the image file in string |
+| **`file`**                | Optional[str]                         | None                      | Stores an absolute file path or URL to the file in string |
+| **`audio`**               | Optional[str]                         | None                      | Stores an absolute file path or URL to the audio file in string |
+| **`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                      | Callback function to be executed after LLM calling |
+| **`callback_kwargs`**     | Optional[Dict[str, Any]]              | dict()                    | 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()                    | Evaluation criteria given by the human client |
+| **`fsls`**                | Optional[List[str]]                   | None                      | Examples of competitive and/or weak responses |
+| **`processed_agents`**    | Set[str]                              | set()                     | Stores keys of agents that executed the task |
+| **`output`**              | Optional[TaskOutput]                  | None                      | Stores `TaskOutput` object after the execution |
+
+
+### Class Methods
+
+| <div style="width:160px">**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. |
+
+
+### Properties
+
+| <div style="width:160px">**Property**</div>   | **Data_Type** | **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.     |
+
+<hr>
+
+## Class `ResponseField`
+
+### Variables
+
+| <div style="width:160px">**Variable**</div> | **Data Type**   | **Default**   | **Description**                                       |
+| :---              | :---                                      | :---          | :---                                                  |
+| **`title`**       | str                                       | None          | Stores a field title.                                 |
+| **`data_type`**   | Type                                      | None          | Stores data type of the response.                     |
+| **`items`**       | Type                                      | None          | Stores data type of items in the list. `None` when `data_type` is not list. |
+| **`properties`**  | List[`ResponseField`]                     | None          | Stores properties in a list of `ResponseFormat` objects when the `data_type` is dict. |
+| **`nullable`**    | bool                                      | False         | If the field is nullable.                             |
+| **`config`**      | Dict[str, Any]                            | None          | Stores other configs passed to response schema.       |
+
+
+<hr>
+
+## Class `TaskOutput`
+
+### Variables
+
+| <div style="width:160px">**Variable**</div>       | **Data Type** | **Default**   |  **Description**                                      |
+| :---                      | :---                                  | :---          | :---                                                  |
+| **`task_id`**             | UUID                                  | uuid.uuid4()  | Stores task `id` as an identifier.                    |
+| **`raw`**                 | str                                   | None          | Stores response in plane text format. `None` or `""` when the model returned errors.|
+| **`json_dict`**           | Dict[str, Any]                        | None          | Stores response in JSON serializable dictionary. When the system failed formatting or executing tasks without response_fields, `{ output: <res.raw> }` will be returned. |
+| **`pydantic`**            | Type[`BaseModel`]                     | None          | Populates and stores Pydantic class object defined in the `pydantic_output` field if given. |
+| **`tool_output`**         | Optional[Any]                         | None          | Stores results from the tools of the task or agents ONLY when `tool_res_as_final` set as `True`. |
+| **`callback_output`**     | Optional[Any]                         | None          | Stores results from callback functions if any. |
+| **`latency`**             | Optional[float]                       | None          | Stores job latency in milseconds. |
+| **`evaluation`**          | Optional[InstanceOf[`Evaluation`]]    | None          | Stores overall evaluations and usage of the task output. |
+
+
+### Class Methods
+
+| <div style="width:160px">**Method**</div> | **Params** | **Returns** | **Description** |
+| :---                   | :---  | :--- | :--- |
+| **`evaluate`**         | task: InstanceOf[`Task`]  | InstanceOf[`Evaluation`]  | Evaluates task output based on the criteria |
+
+
+### Properties
+
+| <div style="width:160px">**Property**</div>   | **Data_Type** | **Description**                                               |
+| :---                                          | :---          | :---                                                          |
+| **`aggregate_score`**                         | float         | Calucurates weighted average eval scores of the task output.  |
+| **`json_string`**                             | str           | Returns `json_dict` in string format.                         |
+
+
+<hr>
+
+## Class `Evaluation`
+
+### Variables
+
+| <div style="width:160px">**Variable**</div> | **Data Type**   | **Default**   |  **Description**                                  |
+| :---              | :---                                      | :---          | :---                                              |
+| **`items`**       | List[InstanceOf[EvaluationItem]]          | list()        | Stores evaluation items.                          |
+| **`eval_by`**     | Optional[InstanceOf[Agent]]               | None          | Stores an agent assigned to evaluate the output.  |
+
+
+### Properties
+
+| <div style="width:160px">**Property**</div>   | **Data_Type**   | **Description**                                               |
+| :---                                          | :---          | :---                                                          |
+| **`aggregate_score`**                         | float         | Calucurates weighted average eval scores of the task output.  |
+| **`suggestion_summary`**                      | str           | Returns summary of the suggestions.                           |
+
+
+<hr>
+
+## SubClass `EvaluationItem`
+
+### Variables
+
+| <div style="width:160px">**Variable**</div>   | **Data Type** | **Default**   |  **Description**                                              |
+| :---                                          | :---          | :---          | :---                                                          |
+| **`criteria`**                                | str           | None          | Stores evaluation criteria given by the client.               |
+| **`suggestion`**                              | str           | None          | Stores suggestion on improvement from the evaluator agent.    |
+| **`score`**                                   | float         | None          | Stores the score on a 0 to 1 scale.                           |
+| **`weight`**                                  | int           | None          | Stores the weight (importance of the criteria) at any scale.  |

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/docs/core/task/response-field.md

@@ -4,20 +4,6 @@
 
 A Pydantic class to store response formats to generate a structured response in JSON.
 
-<hr/>
-
-## Variables
-
-| <div style="width:120px">**Variable**</div> | **Data Type** | **Default** | **Nullable** | **Description** |
-| :---               | :---  | :--- | :--- | :--- |
-| **`title`**   | str | None | False | Stores a field title. |
-| **`data_type`**       | Type | None | False | Stores data type of the response. |
-| **`items`** | Type | None | True | Stores data type of items in the list. Can leave it None when `data_type` is not list. |
-| **`properties`** | List[`ResponseField`] | None | True | Stores properties as a list of `ResponseFormat` objects when the `data_type` is dict. |
-| **`nullable`** |  bool | False | False | If the field is nullable. |
-| **`config`** | Dict[str, Any] | None | True | Stores other configs passed to response schema. |
-
-
 **Quick Start**
 
 Define a response format with field titles and data types.
@@ -210,3 +196,5 @@ response_field = vhq.ResponseField(
 # Agent output:
 # summary-with-config: <AGENT_RESPONSE_IN_STRING>
 ```
+
+Ref. <a href="/core/task/reference/#responsefield">List of variables</a>

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/docs/core/task/task-execution.md

@@ -24,10 +24,10 @@ context = [sub_res, sub_task_2, "context to add in string"]
 res = task.execute(context=context)
 
 # Explicitly mentioned. `task.execute()` will trigger the following:
-task_prompt = task._prompt(context=context)
+task_prompt = task._user_prompt(context=context)
 
-assert sub_res.to_context_prompt() in task_prompt
-assert sub_task_2.output and sub_task_2.output.to_context_prompt() in task_prompt  # sub tasks' outputs are included in the task prompt.
+assert sub_res._to_context_prompt() in task_prompt
+assert sub_task_2.output and sub_task_2.output._to_context_prompt() in task_prompt  # sub tasks' outputs are included in the task prompt.
 assert "context to add in string" in task_promp
 assert res
 ```
@@ -55,7 +55,7 @@ task.execute()
 
 assert task.output is not None
 assert task.processed_agents is not None # auto assigned
-assert task.delegations ==1
+assert task._delegations ==1
 ```
 
 <hr>
@@ -83,7 +83,7 @@ with patch.object(vhq.Agent, "execute_task", return_value="test") as execute:
 
 <hr>
 
-## Using Tools
+## Tools
 
 `[var]`<bold>`tools: Optional[List[ToolSet | Tool | Any]] = None`</bold>
 
@@ -116,7 +116,9 @@ 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
+Ref 1. <a href="/core/tool">Tool</a> class / <a href="/core/rag-tool">RAGTool</a> class
+
+Ref 2. <a href="/core/task/task-output">TaskOutput</a> class
 
 <hr>
 
@@ -142,6 +144,29 @@ assert res.tool_output == "simple func"
 
 <hr>
 
+## Image, Audio, File Content
+
+Refer the content by adding an absolute file path to the content file or URL to the task object.
+
+
+```python
+import versionhq as vhq
+from pathlib import Path
+
+current_dir = Path(__file__).parent.parent
+file_path = current_dir / "_sample/screenshot.png"
+audio_path = current_dir / "_sample/sample.mp3"
+
+task = vhq.Task(description="Summarize the given content", image=str(file_path), audio=str(audio_path))
+res = task.execute(agent=vhq.Agent(llm="gemini-2.0", role="Content Interpretator"))
+
+assert res.raw is not None
+```
+
+* Audio files are only applicable to `gemini` models.
+
+<hr>
+
 ## Callbacks
 
 `[var]`<bold>`callback: Optional[Callable] = None`</bold>

versionhq-1.2.4.1/docs/core/task/task-output.md

@@ -0,0 +1,50 @@
+---
+tags:
+  - Task Graph
+---
+
+# Task Output
+
+<class>`class` versionhq.task.model.<bold>TaskOutput<bold></class>
+
+A Pydantic class to store and manage results of `Task`.
+
+The following snippet demonstrates the  `TaskOutput` object when the task is all-in with Pydantic response format, callbacks, tools, and evaluation.
+
+```python
+import versionhq as vhq
+from pydantic import BaseModel
+
+class CustomOutput(BaseModel):
+    test1: str
+    test2: list[str]
+
+def dummy_tool():
+    return "dummy"
+
+def summarize_response(message: str, test1: str, test2: list[str]) -> str:
+    return f"""{message}: {test1}, {", ".join(test2)}"""
+
+task = vhq.Task(
+    description="Research a topic to teach a kid aged 6 about math.",
+    pydantic_output=CustomOutput,
+    tools=[dummy_tool],
+    callback=summarize_response,
+    callback_kwargs=dict(message="Hi! Here is the result: "),
+    should_evaluate=True, # triggers evaluation
+    eval_criteria=["Uniquness", "Fit to audience",],
+
+)
+res = task.execute()
+
+assert res.task_id == task.id
+assert res.raw
+assert res.json_dict
+assert res.pydantic.test1 and res.pydantic.test2
+assert "Hi! Here is the result: " in res.callback_output
+assert res.pydantic.test1 in res.callback_output and ", ".join(res.pydantic.test2) in res.callback_output
+assert res.tool_output is None
+assert res.evaluation and isinstance(res.evaluation, vhq.Evaluation)
+```
+
+Ref. <a href="/core/task/reference/#taskoutput">List of variables and class methods</a>

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/docs/index.md

@@ -1,26 +1,25 @@
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-20K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-30K+-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.2+-blue)
+![PyPI](https://img.shields.io/badge/PythonSDK-v1.2.4+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11|3.12|3.13-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
-A Python framework for agentic orchestration that handles complex task automation.
+A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
 
 **Visit:**
 
-- [Playground](https://versi0n.io/playground)
-- [PyPI](https://pypi.org/project/versionhq/)
-- [Docs](https://docs.versi0n.io)
+- [Playground](https://versi0n.io/)
+- [Documentation](https://docs.versi0n.io)
+- [Github](https://github.com/versionHQ/)
+- [Python SDK](https://pypi.org/project/versionhq/)
 
-**Contribute:**
-
-- [Github Repository](https://github.com/versionHQ/multi-agent-system)
 
 <hr />
 
+
 ## Key Features
 
 `versionhq` is a Python framework designed for automating complex, multi-step tasks using autonomous agent networks.
@@ -28,18 +27,18 @@ A Python framework for agentic orchestration that handles complex task automatio
 Users can either configure their agents and network manually or allow the system to automatically manage the process based on provided task goals.
 
 
-### Agent Network
+###  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** | **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> |
-| **Use case** | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
+|                 | **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> |
+| **Use case**    | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
 
 <hr />
 

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/pyproject.toml

@@ -15,9 +15,9 @@ exclude = ["test*", "__pycache__", "*.egg-info"]
 
 [project]
 name = "versionhq"
-version = "1.2.3.8"
+version = "1.2.4.1"
 authors = [{ name = "Kuriko Iwai", email = "kuriko@versi0n.io" }]
-description = "An agentic orchestration framework for building agent networks that handle task automation."
+description = "A Python framework for autonomous agent networks that handle task automation with multi-step reasoning."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { file = "LICENSE" }
@@ -93,7 +93,6 @@ torch = [
     "torchvision>=0.21.0",
 ]
 
-
 [tool.uv]
 dev-dependencies = [
   "mypy>=1.10.0",

{versionhq-1.2.3.8 → versionhq-1.2.4.1}/src/versionhq/__init__.py

@@ -32,7 +32,7 @@ from versionhq.agent_network.formation import form_agent_network
 from versionhq.task_graph.draft import workflow
 
 
-__version__ = "1.2.3.8"
+__version__ = "1.2.4.1"
 __all__ = [
     "Agent",