versionhq 1.2.1.2__tar.gz → 1.2.1.3__tar.gz

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/.github/workflows/deploy_docs.yml

@@ -26,5 +26,5 @@ jobs:
           path: .cache
           restore-keys: |
             mkdocs-material-
-      - run: pip install mkdocs-material 
-      - run: mkdocs gh-deploy --force
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force --clean

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/.gitignore

@@ -7,25 +7,28 @@ _memo
 _idea.py
 
 
-
 dist/
 lib/
 build/
 .pypirc
+*egg-info/
+
 uploads/
 sample_dataset/
 chroma.sqlite3
-*egg-info/
+
 test/
 db/
 rc-tests/*
 temp/*
 .vscode/*
 assets/*
+
 memo.txt
 site/
-_logs/
 
+_logs/
+.cache
 __pycache__
 .ruff_cache/
 .pytest_cache/

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.1.2
+Version: 1.2.1.3
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -89,7 +89,7 @@ Requires-Dist: pygraphviz>=1.14; extra == "pygraphviz"
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
-A Python framework for agentic orchestration that handles complex task automation without human interaction.
+Agentic orchestration framework for multi-agent networks and task graph for complex task automation.
 
 **Visit:**
 
@@ -188,7 +188,14 @@ task_graph.add_dependency(
    type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3
 )
 
+# To visualize the graph:
 task_graph.visualize()
+
+# To start executing nodes:
+latest_output, outputs = task_graph.activate()
+
+assert isinstance(last_task_output, vhq.TaskOutput)
+assert [k in task_graph.nodes.keys() and v and isinstance(v, vhq.TaskOutput) for k, v in outputs.items()]
 ```
 
 <hr />
@@ -346,34 +353,34 @@ Tasks can be delegated to a manager, peers within the agent network, or a comple
 
 ## Technologies Used
 
-**Task Graph**
-
-* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks.
-* [Matplotlib](https://matplotlib.org/stable/index.html): Visualization library
-* [Graphviz](https://graphviz.org/about/): Graph visualization software
-
-
 **Schema, Data Validation**
 
 * [Pydantic](https://docs.pydantic.dev/latest/): Data validation and serialization library for Python.
 * [Upstage](https://console.upstage.ai/docs/getting-started/overview): Document processer for ML tasks. (Use `Document Parser API` to extract data from documents)
 * [Docling](https://ds4sd.github.io/docling/): Document parsing
 
+**Workflow, Task Graph**
 
-**Storage**
-
-* [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
-* [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
-* [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
+* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks.
+* [Matplotlib](https://matplotlib.org/stable/index.html): For graph visualization.
+* [Graphviz](https://graphviz.org/about/): For graph visualization.
 
-**LLM Integration**
+**LLM Curation**
 
-* [LiteLLM](https://docs.litellm.ai/docs/providers): Integration to diverse LLMs
+* [LiteLLM](https://docs.litellm.ai/docs/providers): LLM orchestration platform
 
 **Tools**
 
 * [Composio](https://composio.dev/): Conect RAG agents with external tools, Apps, and APIs to perform actions and receive triggers. We use [tools](https://composio.dev/tools) and [RAG tools](https://app.composio.dev/app/ragtool) from Composio toolset.
 
+
+**Storage**
+
+* [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
+* [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
+* [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
+
+
 **Deployment**
 
 * **Python**: Primary programming language. v3.12.x is recommended

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/README.md

@@ -8,7 +8,7 @@
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
-A Python framework for agentic orchestration that handles complex task automation without human interaction.
+Agentic orchestration framework for multi-agent networks and task graph for complex task automation.
 
 **Visit:**
 
@@ -107,7 +107,14 @@ task_graph.add_dependency(
    type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3
 )
 
+# To visualize the graph:
 task_graph.visualize()
+
+# To start executing nodes:
+latest_output, outputs = task_graph.activate()
+
+assert isinstance(last_task_output, vhq.TaskOutput)
+assert [k in task_graph.nodes.keys() and v and isinstance(v, vhq.TaskOutput) for k, v in outputs.items()]
 ```
 
 <hr />
@@ -265,34 +272,34 @@ Tasks can be delegated to a manager, peers within the agent network, or a comple
 
 ## Technologies Used
 
-**Task Graph**
-
-* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks.
-* [Matplotlib](https://matplotlib.org/stable/index.html): Visualization library
-* [Graphviz](https://graphviz.org/about/): Graph visualization software
-
-
 **Schema, Data Validation**
 
 * [Pydantic](https://docs.pydantic.dev/latest/): Data validation and serialization library for Python.
 * [Upstage](https://console.upstage.ai/docs/getting-started/overview): Document processer for ML tasks. (Use `Document Parser API` to extract data from documents)
 * [Docling](https://ds4sd.github.io/docling/): Document parsing
 
+**Workflow, Task Graph**
 
-**Storage**
-
-* [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
-* [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
-* [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
+* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks.
+* [Matplotlib](https://matplotlib.org/stable/index.html): For graph visualization.
+* [Graphviz](https://graphviz.org/about/): For graph visualization.
 
-**LLM Integration**
+**LLM Curation**
 
-* [LiteLLM](https://docs.litellm.ai/docs/providers): Integration to diverse LLMs
+* [LiteLLM](https://docs.litellm.ai/docs/providers): LLM orchestration platform
 
 **Tools**
 
 * [Composio](https://composio.dev/): Conect RAG agents with external tools, Apps, and APIs to perform actions and receive triggers. We use [tools](https://composio.dev/tools) and [RAG tools](https://app.composio.dev/app/ragtool) from Composio toolset.
 
+
+**Storage**
+
+* [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
+* [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
+* [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
+
+
 **Deployment**
 
 * **Python**: Primary programming language. v3.12.x is recommended

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/docs/core/Agent.md

@@ -1,8 +1,6 @@
 ---
 tags:
-  - HTML5
-  - JavaScript
-  - CSS
+  - Agent Network
 ---
 
 # Agent
@@ -14,7 +12,7 @@ Each agent has its unique knowledge and memory on the past task.
 You can create one and assign the task or reassign another task to the existing agent after fine-tuning.
 
 
-## Core usage
+## Quick Start
 
 By defining its role and goal in a simple sentence, the AI agent will be set up to run on <bold>`gpt-4o`</bold> by default.
 

versionhq-1.2.1.3/docs/core/task/evaluation.md

@@ -0,0 +1,8 @@
+---
+tags:
+  - Task Graph
+---
+
+# Evaluation
+
+Under drafting

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/docs/core/task/response-field.md

@@ -1,23 +1,29 @@
 ---
 tags:
-  - HTML5
-  - JavaScript
-  - CSS
+  - Task Graph
 ---
 
-# ResponseField
+# Response Field
 
 <class>`class` versionhq.task.model.<bold>ResponseField<bold></class>
 
-A class to store response formats to create JSON response schema.
+A Pydantic class to store response formats to create JSON response schema.
 
 <hr/>
 
-## Core Usage
+## Variables
 
-`[var]`<bold>`title: str = None`</bold>
+| <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. |
 
-`[var]`<bold>`data_type: Type = None`</bold>
+
+**Quick Start**
 
 Define a response format with field titles and data types.
 

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

@@ -0,0 +1,79 @@
+---
+tags:
+  - Task Graph
+---
+
+# Task Output
+
+<class>`class` versionhq.task.model.<bold>TaskOutput<bold></class>
+
+A Pydantic class to store and manage response from the `Task` object.
+
+<hr />
+
+## Variables
+
+| <div style="width:120px">**Variable**</div> | **Data Type** | **Default** | **Nullable** | **Description** |
+| :---               | :---  | :--- | :--- | :--- |
+| **`task_id`**   | UUID  | uuid.uuid4() | False | Stores task `id` as an identifier. |
+| **`raw`**       | str   | None | False | Stores response in plane text format. `None` or `""` when the model returned errors.|
+| **`json_dict`** | Dict[str, Any] | None | False | 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 | True | Populates and stores Pydantic class defined in the `pydantic_output` field. `None` if `pydantic_output` is NOT given. |
+| **`tool_output`** |  Optional[Any] | None | True | Stores results from the tools of the task or agents ONLY when `tool_res_as_final` set as `True`. |
+| **`callback_output`** |  Optional[Any] | None | True | Stores results from callback functions if any. |
+| **`evaluation`** |  Optional[InstanceOf[`Evaluation`]] | None | True | Stores overall evaluations and usage of the task output. |
+
+
+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)
+```
+
+
+## Class Methods
+
+| <div style="width:120px">**Method**</div> | **Params** | **Returns** | **Description** |
+| :---               | :---  | :--- | :--- |
+| **`evaluate`**   | task: InstanceOf[`Task`]  | InstanceOf[`Evaluation`]  | Evaluates task output based on the criteria |
+
+Ref. <a href="/core/task/evaluation">Evaluation</a> class
+
+## Property
+
+| <div style="width:120px">**Property**</div> | **Returns** | **Description** |
+| :---               | :---  | :--- |
+| **`aggregate_score`**   | float | Calucurates weighted average eval scores of the task output. |
+| **`json_string`**       | str   | Returns `json_dict` in string format. |

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/docs/core/task-graph.md

@@ -1,8 +1,6 @@
 ---
 tags:
-  - HTML5
-  - JavaScript
-  - CSS
+  - Task Graph
 ---
 
 # TaskGraph
@@ -18,7 +16,7 @@ The following example demonstrates a simple concept of a `supervising` agent net
 <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1739337639/pj_m_home/zfg4ccw1m1ww1tpnb0pa.png">
 
 
-## Core Usage
+## Quick Start
 
 `TaskGraph` needs at least two `nodes` and one `edges` to connect the nodes to function.
 

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/docs/core/task.md

@@ -1,8 +1,6 @@
 ---
 tags:
-  - HTML5
-  - JavaScript
-  - CSS
+  - Task Graph
 ---
 
 # Task
@@ -15,7 +13,7 @@ Ref. Node / Edge / TaskGraph class
 
 <hr />
 
-## Core usage
+## Quick Start
 
 Create a task by defining its description in one simple sentence. The `description` will be used for task prompting later.
 
@@ -46,9 +44,7 @@ assert task.processed_agents is not None # Agents will be automatically assigned
 
 <hr />
 
-## Customizing tasks
-
-### Structured outputs
+## Structured Response
 
 By default, agents will generate plane text and JSON outputs, and store them in the `TaskOutput` object.
 
@@ -60,7 +56,7 @@ But you can choose to generate Pydantic class or specifig JSON object as respons
 
 **1. Pydantic**
 
-`[var]`<bold>`pydantic_output: Optional[Type[BaseModel]] = "None"`</bold>
+`[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.
 
@@ -111,7 +107,7 @@ assert [
 
 **2. JSON**
 
-`[var]`<bold>`response_fields: List[InstanceOf[ResponseField]] = "None"`</bold>
+`[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.
 
@@ -187,6 +183,7 @@ assert [v and type(v) == task.response_fields[i].data_type for i, (k, v) in enum
 
 * Ref. <a href="/core/task/response-field">`ResponseField`</a> class
 
+<hr />
 
 **Structuring reponse format**
 
@@ -236,28 +233,82 @@ def format_response(sub: InstanceOf[Sub], main1: list[Any], main2: dict[str, Any
 
 # 3. Execute
 main_task = vhq.Task(
-    description="generate random values that strictly follows the given format.",
+    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.
+res = main_task.execute(context=sub_res.raw) # [Optional] Adding sub_task as a context.
 
 assert [item for item in res.callback_output.main1 if isinstance(item, Sub)]
 ```
 
 To automate these manual setups, refer to <a href="/core/agent-network">AgentNetwork</a> class.
 
+<hr />
+
+## Prompting
+
+`[class method]`<bold>`prompt(self, model_provider: str = None, context: Optional[Any] = None) -> str`</bold>
+
+Prompts 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.
+
+```python
+import versionhq as vhq
+
+sub_task_1 = vhq.Task(description="Run a sub demo part 1")
+sub_res = sub_task_1.execute()
+sub_task_2 = vhq.Task(description="Run a sub demo part 2")
+task = vhq.Task(description="Run a main demo")
+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.raw in  task_prompt
+assert sub_task_2.output.raw in task_prompt
+assert "context to add in string" in task_prompt
+assert res
+```
+
+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.
 
-<!-- ### 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)
 
+## Executing
 
-### Execution rules
-EXECUTION type
-    allow_delegation: bool = Field(default=False, description="ask other agents for help and run the task instead")
+**Agent delegation**
+
+`[var]`<bold>`allow_delegation: bool = False`</bold>
+
+You can assign another agent to complete the task:
+
+```python
+import versionhq as vhq
+
+task = vhq.Task(
+    description="return the output following the given prompt.",
+    response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True)],
+    allow_delegation=True
+)
+task.execute()
+
+assert task.output is not None
+assert "vhq-Delegated-Agent" in task.processed_agents # delegated agent
+assert task.delegations ==1
+```
+
+
+<!--
+
+## Callbacks
     callback: Optional[Callable] = Field(default=None, description="callback to be executed after the task is completed.")
     callback_kwargs: Optional[Dict[str, Any]] = Field(default_factory=dict, description="kwargs for the callback when the callback is callable")
 
@@ -265,12 +316,13 @@ EXECUTION type
 ### 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`") -->
+    tool_res_as_final: bool = Field(default=False, description="when set True, tools res will be stored in the `TaskOutput`")
+
 
 
-<hr />
 
 ## Executing tasks
+ EXECUTION type
 
 ### Sync
 
@@ -288,13 +340,12 @@ EXECUTION type
 
 
 
-## Evaluating task outputs
-<!--
-    # evaluation
+## Evaluating
+
     should_evaluate: bool = Field(default=False, description="True to run the evaluation flow")
-    eval_criteria: Optional[List[str]] = Field(default_factory=list, description="criteria to evaluate the outcome. i.e., fit to the brand tone") -->
+    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") -->
+output: Optional[TaskOutput] = Field(default=None, description="store the final task output in TaskOutput class") -->

{versionhq-1.2.1.2 → versionhq-1.2.1.3}/docs/core/tool.md

@@ -1,8 +1,6 @@
 ---
 tags:
-  - HTML5
-  - JavaScript
-  - CSS
+  - Utils
 ---
 
 # Tool
@@ -11,7 +9,7 @@ tags:
 
 Tool is an unique function that the agent can utilize when they execute the task with or without LLM.
 
-## Core usage
+## Quick Start
 
 By defining the function, you can let the agent start to use it when they get an approval.