versionhq 1.2.3.8__tar.gz → 1.2.4.2__tar.gz

{versionhq-1.2.3.8 → versionhq-1.2.4.2}/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.2
+Summary: Autonomous agent networks for task automation with multi-step reasoning.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
         
@@ -29,7 +29,7 @@ Project-URL: Homepage, https://versi0n.io
 Project-URL: Documentation, https://docs.versi0n.io
 Project-URL: Repository, https://github.com/versionHQ/multi-agent-system
 Project-URL: Issues, https://github.com/versionHQ/multi-agent-system/issues
-Keywords: orchestration framework,orchestration,ai agent,multi-agent system,RAG,agent,agentic orchestration,llm
+Keywords: autonomic agent networks,deep agent,agentic orchestration framework
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -47,12 +47,9 @@ License-File: LICENSE
 Requires-Dist: regex==2024.11.6
 Requires-Dist: requests>=2.32.3
 Requires-Dist: pydantic>=2.10.6
-Requires-Dist: werkzeug>=3.1.3
 Requires-Dist: typing>=0.0.0
 Requires-Dist: json-repair>=0.0.0
 Requires-Dist: litellm>=1.55.8
-Requires-Dist: openai>=1.64.0
-Requires-Dist: composio-openai>=0.6.9
 Requires-Dist: composio>=0.1.0
 Requires-Dist: setuptools>=75.6.0
 Requires-Dist: wheel>=0.45.1
@@ -60,10 +57,8 @@ Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: appdirs>=1.4.4
 Requires-Dist: langchain>=0.3.14
 Requires-Dist: langchain-openai>=0.2.14
-Requires-Dist: composio-langchain>=0.6.12
 Requires-Dist: chromadb>=0.6.3
 Requires-Dist: wheel>=0.45.1
-Requires-Dist: envoy>=0.0.3
 Requires-Dist: composio-core==0.7.0
 Requires-Dist: networkx>=3.4.2
 Requires-Dist: matplotlib>=3.10.0
@@ -88,15 +83,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 +149,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.2}/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.2/docs/core/agent-network/ref.md

@@ -0,0 +1,140 @@
+---
+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. |
+| **`self_learn`**               | bool | False | Whether to self-learn|
+| **`tools`**                    | List[InstanceOf[`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 during error handling. |
+| **`callbacks`**                | List[Callabale] | None | Stores a list of step callback functions. |
+| **`llm`**                      | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | Stores the main LLM. |
+| **`func_calling_llm`**         | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | Stores the function calling LLM. |
+| **`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.2/docs/core/task/reference.md

@@ -0,0 +1,126 @@
+## 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 |
+| **`should_test_run`**     | bool                                  | False                     | Whether to turn on auto-feedback learning             |
+| **`human`**               | bool                                  | False                     | Whether to ask human input during the task execution  |
+| **`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**                                               |
+| :---                                          | :---          | :---                                                          |
+| **`final`**                                   | Any           | Returns the final output of the task                          |
+| **`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>
+
+## Sub-class `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.2}/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.2}/docs/core/task/task-execution.md

@@ -3,39 +3,51 @@
 
 ## Prompt Engineering
 
-Prompts are generated automatically based on the task `description`, response format, context, agent `role`, and `goal`.
+Prompt messages are generated automatically based on the task `description`, response format, context, agent `role`, and `goal`.
 
 
 **Context**
 
-The following snippet demonstrates how to add `context` to the prompt.
+The following snippet demonstrates adding `context` from tools and sub tasks as well as `multi-modal content` to the prompt.
 
 ```python
 import versionhq as vhq
 
-sub_task_1 = vhq.Task(description="Run a sub demo part 1")
-sub_res = sub_task_1.execute()
+agent = vhq.Agent(llm="gemini-2.0", role="Content Interpretator", tools=[rag_tool])
+task = vhq.Task(description="dummy task", image="image file path")
+sub_task = vhq.Task(description="sub task")
+rag_tool = vhq.RagTool(url="https://github.com/chroma-core/chroma/issues/3233", query="What is the next action plan?")
 
-sub_task_2 = vhq.Task(description="Run a sub demo part 2")
 
-task = vhq.Task(description="Run a main demo")
+# Explicitly mentioned for explanation purpose. By default, `task.execute()` will trigger this formula.
+from versionhq._prompt.model import Prompt
+_, _, messages = Prompt(task=main_task, agent=agent, context=["context 1", "context 2", sub_task]).format_core()
 
-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)
-
-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
+assert messages[0]["role"] == "user"
+assert isinstance(messages[0]["content"], list) # adding context and image, file, audio data to the prompt
+assert messages[1]["role"] == "developer" # adding developer prompt
+assert messages[1]["content"] == agent.backstory
 ```
 
 Context can consist of `Task` objects, `TaskOutput` objects, plain text `strings`, or `lists` containing any of these.
 
 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.
 
+
+**Auto Feedback Learning**
+
+To automatically improve prompts, trigger `test_run` of the task.
+
+```python
+import versionhq as vhq
+
+task = vhq.Task(description="Create a short story.", should_test_run=True, human=True)
+res = task.execute()
+
+assert isinstance(res, vhq.TaskOutput)
+```
+
+
 <hr>
 
 ## Delegation
@@ -55,7 +67,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>
@@ -75,7 +87,7 @@ task = vhq.Task(
 )
 
 from unittest.mock import patch
-with patch.object(vhq.Agent, "execute_task", return_value="test") as execute:
+with patch.object(vhq.Agent, "execute_task", return_value=("user prompt", "dev prompt", "test")) as execute:
     res = task.execute()
     assert res.raw == "test"
     execute.assert_called_once_with(task=task, context=None, task_tools=list())
@@ -83,7 +95,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 +128,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 +156,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.2/docs/core/task/task-output.md

@@ -0,0 +1,61 @@
+---
+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)
+```
+
+
+The `TaskOutput` object has a `final` field that contains the task's definitive result.
+
+Result priority is: `callback` > `tool` (when tool_res_as_final is true) > `pydantic` > `json_dict` > `raw` output.
+
+
+```python
+assert res.final == res.callback_output
+```
+
+
+Ref. <a href="/core/task/reference/#taskoutput">List of variables and class methods</a>