versionhq 1.1.13.1__tar.gz → 1.2.0.2__tar.gz

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.1.13.1
+Version: 1.2.0.2
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -86,8 +86,8 @@ Requires-Dist: matplotlib>=3.10.0; extra == "matplotlib"
 [![DL](https://img.shields.io/badge/Download-15K+-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.1.12+-blue)
-![python ver](https://img.shields.io/badge/Python-3.11+-purple)
+![PyPI](https://img.shields.io/badge/PyPI-v1.2.0+-blue)
+![python ver](https://img.shields.io/badge/Python-3.11/3.12-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
@@ -266,9 +266,6 @@ By default, agents prioritize JSON over plane text outputs.
    def dummy_func(message: str, test1: str, test2: list[str]) -> str:
       return f"""{message}: {test1}, {", ".join(test2)}"""
 
-
-   agent = vhq.Agent(role="demo", goal="amazing project goal")
-
    task = vhq.Task(
       description="Amazing task",
       pydantic_output=CustomOutput,
@@ -276,7 +273,7 @@ By default, agents prioritize JSON over plane text outputs.
       callback_kwargs=dict(message="Hi! Here is the result: ")
    )
 
-   res = task.execute_sync(agent=agent, context="amazing context to consider.")
+   res = task.execute(context="amazing context to consider.")
    print(res)
    ```
 
@@ -377,6 +374,7 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 └── workflows/                # Github actions
 │
 docs/                         # Documentation built by MkDocs
+mkdocs.yml                    # MkDocs config
 │
 src/
 └── versionhq/                # Orchestration framework package
@@ -392,6 +390,8 @@ src/
 │     └── ...
 │
 └── uploads/  [.gitignore]    # Local directory to store uploaded files such as graphviz diagrams generatd by `Network` class
+|
+pyproject.toml                # Project config
 
 ```
 

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/README.md

@@ -3,8 +3,8 @@
 [![DL](https://img.shields.io/badge/Download-15K+-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.1.12+-blue)
-![python ver](https://img.shields.io/badge/Python-3.11+-purple)
+![PyPI](https://img.shields.io/badge/PyPI-v1.2.0+-blue)
+![python ver](https://img.shields.io/badge/Python-3.11/3.12-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
@@ -183,9 +183,6 @@ By default, agents prioritize JSON over plane text outputs.
    def dummy_func(message: str, test1: str, test2: list[str]) -> str:
       return f"""{message}: {test1}, {", ".join(test2)}"""
 
-
-   agent = vhq.Agent(role="demo", goal="amazing project goal")
-
    task = vhq.Task(
       description="Amazing task",
       pydantic_output=CustomOutput,
@@ -193,7 +190,7 @@ By default, agents prioritize JSON over plane text outputs.
       callback_kwargs=dict(message="Hi! Here is the result: ")
    )
 
-   res = task.execute_sync(agent=agent, context="amazing context to consider.")
+   res = task.execute(context="amazing context to consider.")
    print(res)
    ```
 
@@ -294,6 +291,7 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 └── workflows/                # Github actions
 │
 docs/                         # Documentation built by MkDocs
+mkdocs.yml                    # MkDocs config
 │
 src/
 └── versionhq/                # Orchestration framework package
@@ -309,6 +307,8 @@ src/
 │     └── ...
 │
 └── uploads/  [.gitignore]    # Local directory to store uploaded files such as graphviz diagrams generatd by `Network` class
+|
+pyproject.toml                # Project config
 
 ```
 

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/docs/core/Agent.md

@@ -367,7 +367,7 @@ task = Task(
 	description="Answer the following question: What is Kuriko's favorite color?"
 )
 
-res = task.execute_sync(agent=agent)
+res = task.execute(agent=agent)
 assert "gold" in res.raw  == True
 ```
 

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

@@ -0,0 +1,14 @@
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# ResponseField
+
+<class>`class` versionhq.task.model.<bold>ResponseField<bold></class>
+
+A class to store response formats to create JSON response schema.
+
+<hr/>

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

@@ -0,0 +1,14 @@
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# TaskOutput
+
+<class>`class` versionhq.tasks.model.<bold>TaskOutput<bold></class>
+
+A class to store and manage output from the `Task` object.
+
+<hr />

versionhq-1.2.0.2/docs/core/task.md

@@ -0,0 +1,282 @@
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# Task
+
+<class>`class` versionhq.tasks.model.<bold>Task<bold></class>
+
+A class to store and manage information for individual tasks, including their assignment to agents or teams, and dependencies via a node-based system that tracks conditions and status.
+
+Ref. Node / Edge / TaskGraph class
+
+<hr />
+
+## Core usage
+
+Create a task by defining its description in one simple sentence. The `description` will be used for task prompting later.
+
+Each task will be assigned a unique ID as an identifier.
+
+```python
+import versionhq as vhq
+
+task = vhq.Task(description="MY AMAZING TASK")
+
+import uuid
+assert uuid.UUID(str(task.id), version=4)
+```
+
+
+And you can simply execute the task by calling `.execute()` function.
+
+```python
+import versionhq as vhq
+
+task = vhq.Task(description="MY AMAZING TASK")
+res = task.execute()
+
+assert isinstance(res, vhq.TaskOutput) # Generates TaskOutput object
+assert res.raw and res.json # By default, TaskOutput object stores output in plane text and json formats.
+assert task.processed_agents is not None # Agents will be automatically assigned to the given task.
+```
+
+<hr />
+
+## Customizing tasks
+
+### Structured outputs
+
+By default, agents will generate plane text and JSON outputs, and store them in the `TaskOutput` object.
+
+* Ref. <a href="/core/task/task-output">`TaskOutput`</a> class
+
+But you can choose to generate Pydantic class or specifig JSON object as response.
+
+<hr />
+
+**1. Pydantic**
+
+`[var]`<bold>`pydantic_output: Optional[Type[BaseModel]] = "None"`</bold>
+
+Create and add a `custom Pydantic class` as a structured response format to the `pydantic_output` field.
+
+The custom class can accept **one layer of a nested child** as you can see in the following code snippet:
+
+```python
+import versionhq as vhq
+from pydantic import BaseModel
+from typing import Any
+
+
+# 1. Define Pydantic class using description (optional), annotation and field name.
+class Demo(BaseModel):
+    """
+    A demo pydantic class to validate the outcome with various nested data types.
+    """
+    demo_1: int
+    demo_2: float
+    demo_3: str
+    demo_4: bool
+    demo_5: list[str]
+    demo_6: dict[str, Any]
+    demo_nest_1: list[dict[str, Any]] # 1 layer of nested child is ok.
+    demo_nest_2: list[list[str]]
+    demo_nest_3: dict[str, list[str]]
+    demo_nest_4: dict[str, dict[str, Any]]
+    # error_1: list[list[dict[str, list[str]]]] # <- Trigger 400 error due to 2+ layers of nested child.
+    # error_2: InstanceOf[AnotherPydanticClass] # <- Trigger 400 error due to non-typing annotation.
+    # error_3: list[InstanceOf[AnotherPydanticClass]] # <- Same as above
+
+# 2. Define a task
+task = vhq.Task(
+    description="generate random output that strictly follows the given format",
+    pydantic_output=Demo,
+)
+
+# 3. Execute
+res = task.execute()
+
+assert isinstance(res, vhq.TaskOutput)
+assert res.raw and res.json
+assert isinstance(res.raw, str) and isinstance(res.json_dict, dict)
+assert [
+    getattr(res.pydantic, k) and v.annotation == Demo.model_fields[k].annotation
+    for k, v in res.pydantic.model_fields.items()
+]
+```
+
+**2. JSON**
+
+`[var]`<bold>`response_fields: List[InstanceOf[ResponseField]] = "None"`</bold>
+
+Similar to Pydantic, JSON output structure can be defined by using a list of `ResponseField` objects.
+
+The following code snippet demonstrates how to use `ResponseField` to generate output with a maximum of one level of nesting.
+
+Custom JSON outputs can accept **one layer of a nested child**.
+
+**[NOTES]**
+
+- `demo_response_fields` in the following case is identical to the previous Demo class, except that titles are specified for nested fields.
+
+- Agents generate JSON output by default, whether or not `response_fields` are used.
+
+- However, response_fields are REQUIRED to specify JSON key titles and data types.
+
+```python
+import versionhq as vhq
+
+# 1. Define a list of ResponseField objects.
+demo_response_fields = [
+    vhq.ResponseField(title="demo_1", data_type=int),
+    vhq.ResponseField(title="demo_2", data_type=float),
+    vhq.ResponseField(title="demo_3", data_type=str),
+    vhq.ResponseField(title="demo_4", data_type=bool),
+    vhq.ResponseField(title="demo_5", data_type=list, items=str),
+    vhq.ResponseField(title="demo_6", data_type=dict, properties=[vhq.ResponseField(title="demo-item", data_type=str)]),
+    vhq.ResponseField(title="demo_nest_1", data_type=list, items=str, properties=([
+        vhq.ResponseField(title="nest1", data_type=dict, properties=[vhq.ResponseField(title="nest11", data_type=str)])
+    ])), # you can specify field title of nested items
+    vhq.ResponseField(title="demo_nest_2", data_type=list, items=list),
+    vhq.ResponseField(title="demo_nest_3", data_type=dict, properties=[
+        vhq.ResponseField(title="nest1", data_type=list, items=str)
+    ]),
+    vhq.ResponseField(title="demo_nest_4", data_type=dict, properties=[
+        vhq.ResponseField(title="nest1", data_type=dict, properties=[vhq.ResponseField(title="nest12", data_type=str)])
+    ])
+]
+
+
+# 2. Define a task
+task = vhq.Task(
+    description="Output random values strictly following the data type defined in the given response format.",
+    response_fields=demo_response_fields
+)
+
+
+# 3. Execute
+res = task.execute()
+
+assert isinstance(res, vhq.TaskOutput) and res.task_id is task.id
+assert res.raw and res.json and res.pydantic is None
+assert [v and type(v) == task.response_fields[i].data_type for i, (k, v) in enumerate(res.json_dict.items())]
+```
+
+* Ref. <a href="/core/task/response-field">`ResponseField`</a> class
+
+
+**Structuring reponse format**
+
+- Higlhy recommends assigning agents optimized for `gemini-x` or `gpt-x` to produce structured outputs with nested items.
+
+- To generate response with more than 2 layers of nested items, seperate them into multipe tasks or utilize nodes.
+
+The following case demonstrates to returning a `Main` class that contains a nested `Sub` class.
+
+**[NOTES]**
+
+- Using `callback` functions to format the final response. (You can try other functions suitable for your use case.)
+
+- Passing parameter: `sub` to the callback function via the `callback_kwargs` variable.
+
+- By default, the outputs of `main_task` are automatically passed to the callback function; you do NOT need to explicitly define them.
+
+- Callback results will be stored in the `callback_output` field of the `TaskOutput` class.
+
+
+```python
+import versionhq as vhq
+from pydantic import BaseModel
+from typing import Any
+
+# 1. Define and execute a sub task with Pydantic output.
+class Sub(BaseModel):
+    sub1: list[dict[str, Any]]
+    sub2: dict[str, Any]
+
+sub_task = vhq.Task(
+    description="generate random values that strictly follows the given format.",
+    pydantic_output=Sub
+)
+sub_res = sub_task.execute()
+
+# 2. Define a main task, callback function to format the final response.
+class Main(BaseModel):
+    main1: list[Any] # <= assume expecting to store Sub object in this field.
+    # error_main1: list[InstanceOf[Sub]]  # as this will trigger 400 error!
+    main2: dict[str, Any]
+
+def format_response(sub: InstanceOf[Sub], main1: list[Any], main2: dict[str, Any]) -> Main:
+    main1.append(sub)
+    main = Main(main1=main1, main2=main2)
+    return main
+
+# 3. Execute
+main_task = vhq.Task(
+    description="generate random values that strictly follows the given format.",
+    pydantic_output=Main,
+    callback=format_response,
+    callback_kwargs=dict(sub=Sub(sub1=sub_res.pydantic.sub1, sub2=sub_res.pydantic.sub2)),
+)
+res = main_task.execute(context=sub_res.raw) # [Optional] Adding sub_task's response as context.
+
+assert [item for item in res.callback_output.main1 if isinstance(item, Sub)]
+```
+
+To skip these manual setups, refer to Node/Graph pages.
+
+
+<!-- ### Context
+  # task setup
+    context: Optional[List["Task"]] = Field(default=None, description="other tasks whose outputs should be used as context")
+    prompt_context: Optional[str] = Field(default=None)
+
+
+### Execution rules
+EXECUTION type
+    allow_delegation: bool = Field(default=False, description="ask other agents for help and run the task instead")
+
+    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")
+
+
+### 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`") -->
+
+
+<hr />
+
+## Executing tasks
+
+### Sync
+
+<hr />
+
+### Async
+
+<hr />
+
+### Assigning agents
+
+<hr />
+
+### Context
+
+
+
+## Evaluating task outputs
+<!--
+    # evaluation
+    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") -->
+
+
+## Recording
+
+<!-- output: Optional[TaskOutput] = Field(default=None, description="store the final task output in TaskOutput class") -->

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/docs/core/tool.md

@@ -253,7 +253,7 @@ task = Task(
 	tool_res_as_final=True
 )
 
-res = task.execute_sync(agent=agent)
+res = task.execute(agent=agent)
 print(res)
 # demo func
 ```
@@ -279,7 +279,7 @@ task = Task(
 	tool_res_as_final=True
 )
 
-res = task.execute_sync(agent=agent)
+res = task.execute(agent=agent)
 print(res.tool_output)
 # demo func
 ```
@@ -301,7 +301,7 @@ task = Task(
 	tool_res_as_final=True
 )
 
-res = task.execute_sync(agent=agent)
+res = task.execute(agent=agent)
 print(res.tool_output)
 # "demo func"
 
@@ -356,7 +356,7 @@ task = Task(
 	tool_res_as_final=True
 )
 
-res = task.execute_sync(agent=agent)
+res = task.execute(agent=agent)
 print(res)
 # empty func_demo
 ```

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/docs/index.md

@@ -10,7 +10,7 @@ tags:
 [![DL](https://img.shields.io/badge/Download-15K+-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.1.12+-blue)
+![PyPI](https://img.shields.io/badge/PyPI-v1.2.0+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11/3.12-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/docs/quickstart.md

@@ -64,7 +64,7 @@ Agents can execute tasks using `Task` model and return JSON format by default wi
       callback_kwargs=dict(message="Hi! Here is the result: ")
    )
 
-   res = task.execute_sync(agent=agent, context="amazing context to consider.")
+   res = task.execute(agent=agent, context="amazing context to consider.")
    print(res)
    ```
 

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/mkdocs.yml

@@ -110,14 +110,12 @@ nav:
   - Quick Start: 'quickstart.md'
   - Core Components:
     - Agent: 'core/agent.md'
+    - Task:
+      - Overview: 'core/task.md'
+      - ResponseField: 'core/task/response-field.md'
+      - TaskOutput: 'core/task/task-output.md'
     - Tool: 'core/tool.md'
-  #   - Task: 'core/task.md'
   #   - Compoio Tools: 'core/composio-tool.md'
-  # - How to Guides:
-  #   - Form agent networks: 'guides/form-agent-network.md'
-  #   - Create custom tools: 'guides/create-custom-tool.md'
-  #   - Customize Agent: 'guides/customize-agent.md'
-  #   - Connect to any LLM: 'guides/connect-to-any-llm.md'
   - Examples:
     - Playground: https://versi0n.io
     - Experiment - Agent Performance: https://github.com/versionHQ/exp-agent-performance

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/pyproject.toml

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

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/src/versionhq/__init__.py

@@ -17,7 +17,7 @@ from versionhq.knowledge.model import Knowledge, KnowledgeStorage
 from versionhq.knowledge.source import PDFKnowledgeSource, CSVKnowledgeSource, JSONKnowledgeSource, TextFileKnowledgeSource, ExcelKnowledgeSource, StringKnowledgeSource
 from versionhq.knowledge.source_docling import DoclingSource
 from versionhq.network.model import TaskStatus, TaskGraph, Node, Edge, DependencyType
-from versionhq.task.model import Task, TaskOutput, ConditionalTask, ResponseField
+from versionhq.task.model import Task, TaskOutput, ResponseField, TaskExecutionType
 from versionhq.task.evaluate import Evaluation, EvaluationItem
 from versionhq.team.model import Team, TeamOutput, Formation, Member, TaskHandlingProcess
 from versionhq.tool.model import Tool, ToolSet
@@ -30,7 +30,7 @@ from versionhq.memory.model import ShortTermMemory,LongTermMemory, UserMemory, M
 from versionhq.task.formation import form_agent_network
 
 
-__version__ = "1.1.13.1"
+__version__ = "1.2.0.2"
 __all__ = [
     "Agent",
 
@@ -64,8 +64,8 @@ __all__ = [
 
     "Task",
     "TaskOutput",
-    "ConditionalTask",
     "ResponseField",
+    "TaskExecutionType",
 
     "Evaluation",
     "EvaluationItem",

{versionhq-1.1.13.1 → versionhq-1.2.0.2}/src/versionhq/agent/model.py

@@ -584,4 +584,4 @@ class Agent(BaseModel):
 
 
     def __repr__(self):
-        return f"Agent(role={self.role}, goal={self.goal}, backstory={self.backstory})"
+        return f"Agent(role={self.role}, goal={self.goal}"