versionhq 1.2.4.1__tar.gz → 1.2.4.3__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.4.1
-Summary: A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
+Version: 1.2.4.3
+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

{versionhq-1.2.4.1 → versionhq-1.2.4.3}/docs/core/agent-network/ref.md

@@ -72,34 +72,35 @@ tags:
 ### 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. |
+| :---                           | :---  | :--- | :--- |
+| **`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

{versionhq-1.2.4.1 → versionhq-1.2.4.3}/docs/core/task/reference.md

@@ -15,6 +15,8 @@
 | **`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 |
@@ -85,6 +87,7 @@
 
 | <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.                         |
 
@@ -111,7 +114,7 @@
 
 <hr>
 
-## SubClass `EvaluationItem`
+## Sub-class `EvaluationItem`
 
 ### Variables
 

{versionhq-1.2.4.1 → versionhq-1.2.4.3}/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._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 "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
@@ -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())

{versionhq-1.2.4.1 → versionhq-1.2.4.3}/docs/core/task/task-output.md

@@ -47,4 +47,15 @@ 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>

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

@@ -15,23 +15,20 @@ exclude = ["test*", "__pycache__", "*.egg-info"]
 
 [project]
 name = "versionhq"
-version = "1.2.4.1"
+version = "1.2.4.3"
 authors = [{ name = "Kuriko Iwai", email = "kuriko@versi0n.io" }]
-description = "A Python framework for autonomous agent networks that handle task automation with multi-step reasoning."
+description = "Autonomous agent networks for task automation with multi-step reasoning."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { file = "LICENSE" }
-keywords = ["orchestration framework", "orchestration", "ai agent", "multi-agent system", "RAG", "agent", "agentic orchestration", "llm"]
+keywords = ["autonomic agent networks", "deep agent", "agentic orchestration framework", ]
 dependencies = [
   "regex==2024.11.6",
   "requests>=2.32.3",
   "pydantic>=2.10.6",
-  "werkzeug>=3.1.3",
   "typing>=0.0.0",
   "json-repair>=0.0.0",
   "litellm>=1.55.8",
-  "openai>=1.64.0",
-  "composio-openai>=0.6.9",
   "composio>=0.1.0",
   "setuptools>=75.6.0",
   "wheel>=0.45.1",
@@ -39,10 +36,8 @@ dependencies = [
   "appdirs>=1.4.4",
   "langchain>=0.3.14",
   "langchain-openai>=0.2.14",
-  "composio-langchain>=0.6.12",
   "chromadb>=0.6.3",
   "wheel>=0.45.1",
-  "envoy>=0.0.3",
   "composio-core==0.7.0",
   "networkx>=3.4.2",
   "matplotlib>=3.10.0",

{versionhq-1.2.4.1 → versionhq-1.2.4.3}/requirements.txt

@@ -1,12 +1,9 @@
 regex==2024.11.6
 requests>=2.32.3
 pydantic>=2.10.6
-werkzeug>=3.1.3
 typing
 json-repair
 litellm>=1.55.8
-openai>=1.57.0
-composio-openai>=0.6.9
 composio>=0.1.0
 setuptools>=75.6.0
 wheel>=0.45.1
@@ -14,10 +11,8 @@ python-dotenv>=1.0.0
 appdirs>=1.4.4
 langchain>=0.3.14
 langchain-openai>=0.2.14
-composio-langchain>=0.6.12
 chromadb>=0.6.3
 wheel>=0.45.1
-envoy>=0.0.3
 composio-core==0.7.0
 networkx>=3.4.2
 matplotlib>=3.10.0

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

@@ -17,7 +17,7 @@ from versionhq.clients.workflow.model import MessagingWorkflow, MessagingCompone
 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.task_graph.model import TaskStatus, TaskGraph, Node, Edge, DependencyType, Condition, ConditionType
+from versionhq.task_graph.model import TaskStatus, TaskGraph, Node, Edge, DependencyType, Condition, ConditionType, ReformTriggerEvent
 from versionhq.task.model import Task, TaskOutput, ResponseField, TaskExecutionType
 from versionhq.task.evaluation import Evaluation, EvaluationItem
 from versionhq.tool.model import Tool, ToolSet
@@ -32,7 +32,7 @@ from versionhq.agent_network.formation import form_agent_network
 from versionhq.task_graph.draft import workflow
 
 
-__version__ = "1.2.4.1"
+__version__ = "1.2.4.3"
 __all__ = [
     "Agent",
 
@@ -70,6 +70,7 @@ __all__ = [
     "DependencyType",
     "Condition",
     "ConditionType",
+    "ReformTriggerEvent",
 
     "Task",
     "TaskOutput",

versionhq-1.2.4.3/src/versionhq/_prompt/auto_feedback.py

@@ -0,0 +1,103 @@
+from typing import List, Optional, Dict
+from typing_extensions import Self
+
+from pydantic import InstanceOf, Field
+
+from versionhq.agent.model import Agent
+from versionhq.task.model import Task
+from versionhq.task_graph.model import TaskGraph, Node, DependencyType, ReformTriggerEvent
+from versionhq._prompt.model import Prompt
+from versionhq._prompt.constants import REFLECT, INTEGRATE, parameter_sets
+
+
+class PromptFeedbackGraph(TaskGraph):
+    """A Pydantic class to handle auto prompt feedback cycle."""
+
+    _times_iteration: int = 0
+    user_prompts: Optional[Dict[str, str]] = Field(default_factory=dict) # { "0": "...", "1": "..."}
+    dev_prompts: Optional[Dict[str, str]] = Field(default_factory=dict)
+    prompts: Optional[Dict[str, InstanceOf[Prompt]]] = Field(default_factory=dict)
+
+
+    def __init__(self, prompt: InstanceOf[Prompt] = None, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+        if prompt:
+            user_prompt, dev_prompt, _ = prompt.format_core()
+            self.prompts = { self.key: prompt }
+            self.user_prompts = { self.key: user_prompt }
+            self.dev_prompts = { self.key: dev_prompt }
+
+
+    def _fetch_latest_prompt(self) -> InstanceOf[Prompt] | None:
+        return self.prompts[self.key] if self.key in self.prompts else None
+
+
+    def _generate_agents(self) -> List[Agent] | None:
+        agents = []
+        prompt = self._fetch_latest_prompt()
+
+        if not prompt:
+            return None
+
+        agent = prompt.agent
+        agent_params = agent.model_dump(exclude={"id", "llm", "llm_config", "self_learning"})
+        for params in parameter_sets:
+            agent = Agent(**agent_params, llm=agent.llm.model, llm_config={**params}, self_learning=True)
+            agents.append(agent)
+        return agents
+
+
+    def _reflect(self, original_response: str) -> Task:
+        description = REFLECT.format(original_prompt=self.original_prompt, original_response=original_response)
+        return Task(description=description)
+
+
+    def set_up_graph(self, **attributes) -> Self:
+        """Sets up a TaskGraph object with nodes and edges."""
+
+        prompt = self._fetch_latest_prompt()
+        base_task = prompt.task if prompt else None
+        base_agent = prompt.agent if prompt else None
+
+        if not base_task or not base_agent:
+            return None
+
+        agents = self._generate_agents()
+        if not agents:
+            return None
+
+        self.concl_template = base_task.pydantic_output if base_task.pydantic_output else base_task.response_fields if base_task.response_fields else None
+        base_agent.callbacks.append(self._reflect)
+        init_node = Node(task=base_task, assigned_to=base_agent)
+        self.add_node(init_node)
+
+        final_task = Task(description=INTEGRATE.format(original_prompt=self.original_prompt, responses=""))
+        final_node = Node(task=final_task, agent=base_agent)
+        self.add_node(node=final_node)
+
+        for agent in agents:
+            node = Node(task=base_task, assigned_to=agent)
+            self.add_node(node=node)
+            self.add_dependency(source=init_node.identifier, target=node.identifier, dependency_type=DependencyType.FINISH_TO_START, required=True)
+            self.add_dependency(source=node.identifier, target=final_node.identifier, dependency_type=DependencyType.FINISH_TO_START, required=True)
+
+        if attributes:
+            for k, v in attributes.items():
+                if hasattr(self, k):
+                    setattr(self, k, v)
+
+        return self
+
+    @property
+    def index(self) -> str:
+        """Returns an index to add new item."""
+        return str(len([k for k in self.user_prompts.keys()]))
+
+    @property
+    def original_prompt(self) -> str:
+        return str(self.user_prompts["0"]) + str(self.dev_prompts["0"])
+
+    @property
+    def key(self):
+        return str(self._times_iteration)

versionhq-1.2.4.3/src/versionhq/_prompt/constants.py

@@ -0,0 +1,30 @@
+REFLECT = "Here is the orignal prompt: {original_prompt}\nHere is the original response: {original_response}\nAnalyze the original prompt and repsonse, check for any pontential issue, and create an improved response."
+
+INTEGRATE = "Here is the original prompt: {original_prompt}\nHere are responses: {responses}. Help integrate them as a single response."
+
+parameter_sets = [
+    {
+        "temperature": 0.2,
+        "top_p": 0.5,
+        "max_tokens": 5000,
+        "frequency_penalty": 0.5,
+        "presence_penalty": 0.5,
+        "stop": ["\n\n", "###"],
+    },
+    {
+        "temperature": 0.7,
+        "top_p": 0.8,
+        "max_tokens": 8000,
+        "frequency_penalty": 0.3,
+        "presence_penalty": 0.3,
+        "stop": ["\n\n"],
+    },
+    {
+        "temperature": 1.0,
+        "top_p": 0.95,
+        "max_tokens": 12000,
+        "frequency_penalty": 0.0,
+        "presence_penalty": 0.0,
+        "stop": [],
+    }
+]