versionhq 1.2.3.8__py3-none-any.whl → 1.2.4.1__py3-none-any.whl

versionhq/__init__.py

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

versionhq/_prompt/model.py

@@ -0,0 +1,147 @@
+from typing import Any, Dict, List
+from textwrap import dedent
+
+
+class Prompt:
+    """A class to format, store, and manage a prompt."""
+
+    task: Any = None
+    agent: Any = None
+    context: str = None
+
+
+    def __init__(self, task, agent):
+        from versionhq.task.model import Task
+        from versionhq.agent.model import Agent
+
+        self.task = task if isinstance(task, Task) else Task(description=str(task))
+        self.agent = agent if isinstance(agent, Agent) else Agent(role=str(agent))
+
+
+    def _draft_output_prompt(self) -> str:
+        output_prompt = ""
+
+        if self.task.pydantic_output:
+            output_prompt = f"""Your response MUST STRICTLY follow the given repsonse format:
+JSON schema: {str(self.task.pydantic_output)}
+"""
+
+        elif self.task.response_fields:
+            output_prompt, output_formats_to_follow = "", dict()
+            response_format = str(self.task._structure_response_format(model_provider=self.agent.llm.provider))
+            for item in self.task.response_fields:
+                if item:
+                    output_formats_to_follow[item.title] = f"<Return your answer in {item.data_type.__name__}>"
+
+            output_prompt = f"""Your response MUST be a valid JSON string that strictly follows the response format. Use double quotes for all keys and string values. Do not use single quotes, trailing commas, or any other non-standard JSON syntax.
+Response format: {response_format}
+Ref. Output image: {output_formats_to_follow}
+"""
+        else:
+            output_prompt = "You MUST Return your response as a valid JSON serializable string, enclosed in double quotes. Do not use single quotes, trailing commas, or other non-standard JSON syntax."
+
+        return dedent(output_prompt)
+
+
+    def _draft_context_prompt(self) -> str:
+        """
+        Create a context prompt from the given context in any format: a task object, task output object, list, dict.
+        """
+        from versionhq.task.model import Task, TaskOutput
+
+        context_to_add = None
+        if not self.context:
+            # Logger().log(level="error", color="red", message="Missing a context to add to the prompt. We'll return ''.")
+            return
+
+        match self.context:
+            case str():
+                context_to_add = self.context
+
+            case Task():
+                if not self.context.output:
+                    res = self.context.execute()
+                    context_to_add = res._to_context_prompt()
+
+                else:
+                    context_to_add = self.context.output.raw
+
+            case TaskOutput():
+                context_to_add = self.context._to_context_prompt()
+
+
+            case dict():
+                context_to_add = str(self.context)
+
+            case list():
+                res = ", ".join([self._draft_context_prompt(context=item) for item in self.context])
+                context_to_add = res
+
+            case _:
+                pass
+
+        return dedent(context_to_add)
+
+
+    def _draft_user_prompt(self) -> str:
+        output_prompt = self._draft_output_prompt()
+        task_slices = [self.task.description, output_prompt, ]
+
+        if self.context:
+            context_prompt = self._draft_context_prompt()
+            task_slices.insert(len(task_slices), f"Consider the following context when responding: {context_prompt}")
+
+        return "\n".join(task_slices)
+
+
+    def _format_content_prompt(self) -> Dict[str, str]:
+        """Formats and returns image_url content added to the messages."""
+
+        from versionhq._utils import is_valid_url
+
+        content_messages = {}
+
+        if self.task.image:
+            if is_valid_url(self.task.image):
+                content_messages.update({ "type": "image_url", "image_url": self.task.image })
+            else:
+                content_messages.update({ "type": "image_url", "image_url": { "url":  self.task.image }})
+
+        if self.task.file:
+            if is_valid_url(self.task.file):
+                content_messages.update({ "type": "image_url", "image_url": self.task.file })
+            else:
+                content_messages.update({ "type": "image_url", "image_url": { "url":  self.task.file }})
+
+        if self.task.audio:
+            from pathlib import Path
+            import base64
+
+            audio_bytes = Path(self.audio_file_path).read_bytes()
+            encoded_data = base64.b64encode(audio_bytes).decode("utf-8")
+            content_messages.update({  "type": "image_url", "image_url": "data:audio/mp3;base64,{}".format(encoded_data)})
+
+        return content_messages
+
+    @property
+    def messages(self) -> List[Dict[str, str]]:
+        user_prompt = self._draft_user_prompt()
+        content_prompt = self._format_content_prompt()
+
+        messages = []
+        messages.append(
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": user_prompt
+                    },
+                    content_prompt,
+                ]
+            })
+
+        if self.use_developer_prompt:
+            messages.append({ "role": "developer", "content": self.backstory })
+
+        return messages

versionhq/_utils/__init__.py

@@ -1,3 +1,4 @@
 from versionhq._utils.logger import Logger
 from versionhq._utils.process_config import process_config
 from versionhq._utils.vars import KNOWLEDGE_DIRECTORY, MAX_FILE_NAME_LENGTH
+from versionhq._utils.is_valid_url import is_valid_url

versionhq/_utils/is_valid_url.py

@@ -0,0 +1,15 @@
+from urllib.parse import urlparse
+
+
+def is_valid_url(url: str) -> bool:
+    try:
+        result = urlparse(url)
+        return all(
+            [
+                result.scheme in ("http", "https", "gs"),
+                result.netloc,
+                len(result.netloc.split(".")) >= 2,  # Ensure domain has TLD
+            ]
+        )
+    except Exception:
+        return False

versionhq/agent/model.py

@@ -12,8 +12,7 @@ from versionhq.tool.model import Tool, ToolSet, BaseTool
 from versionhq.knowledge.model import BaseKnowledgeSource, Knowledge
 from versionhq.memory.contextual_memory import ContextualMemory
 from versionhq.memory.model import ShortTermMemory, LongTermMemory, UserMemory
-from versionhq._utils.logger import Logger
-from versionhq._utils.process_config import process_config
+from versionhq._utils import Logger, process_config, is_valid_url
 
 
 load_dotenv(override=True)
@@ -217,7 +216,7 @@ class Agent(BaseModel):
                     if isinstance(item, BaseKnowledgeSource):
                         knowledge_sources.append(item)
 
-                    elif isinstance(item, str) and "http" in item and DoclingSource._validate_url(url=item) == True:
+                    elif isinstance(item, str) and "http" in item and is_valid_url(url=item) == True:
                         docling_fp.append(item)
 
                     elif isinstance(item, str):
@@ -369,7 +368,7 @@ class Agent(BaseModel):
 
     def _invoke(
         self,
-        prompts: str,
+        messages: List[Dict[str, str]] = None,
         response_format: Optional[Dict[str, Any]] = None,
         tools: Optional[List[InstanceOf[Tool]| InstanceOf[ToolSet] | Type[Tool]]] = None,
         tool_res_as_final: bool = False,
@@ -385,11 +384,6 @@ class Agent(BaseModel):
         iterations = 0
         raw_response = None
 
-        messages = []
-        messages.append({ "role": "user", "content": prompts })
-        if self.use_developer_prompt:
-            messages.append({ "role": "developer", "content": self.backstory })
-
         try:
             if self._rpm_controller and self.max_rpm:
                 self._rpm_controller.check_or_wait()
@@ -480,7 +474,7 @@ class Agent(BaseModel):
         return self
 
 
-    def start(self, context: Any = None, tool_res_as_final: bool = False) -> Any | None:
+    def start(self, context: Any = None, tool_res_as_final: bool = False, image: str = None, file: str = None, audio: str = None) -> Any | None:
         """
         Defines and executes a task when it is not given and returns TaskOutput object.
         """
@@ -498,6 +492,9 @@ class Agent(BaseModel):
             description=f"Generate a simple result in a sentence to achieve the goal: {self.goal if self.goal else self.role}. If needed, list up necessary steps in concise manner.",
             pydantic_output=Output,
             tool_res_as_final=tool_res_as_final,
+            image=image, #REFINEME - query memory/knowledge or self create
+            file=file,
+            audio=audio,
         )
         res = task.execute(agent=self, context=context)
         return res
@@ -520,20 +517,20 @@ class Agent(BaseModel):
         if self.max_rpm and self._rpm_controller:
             self._rpm_controller._reset_request_count()
 
-        task_prompt = task._prompt(model_provider=self.llm.provider, context=context)
+        user_prompt = task._user_prompt(model_provider=self.llm.provider, context=context)
 
         if self._knowledge:
-            agent_knowledge = self._knowledge.query(query=[task_prompt,], limit=5)
+            agent_knowledge = self._knowledge.query(query=[user_prompt,], limit=5)
             if agent_knowledge:
                 agent_knowledge_context = extract_knowledge_context(knowledge_snippets=agent_knowledge)
                 if agent_knowledge_context:
-                    task_prompt += agent_knowledge_context
+                    user_prompt += agent_knowledge_context
 
         if rag_tools:
             for item in rag_tools:
                 rag_tool_context = item.run(agent=self, query=task.description)
                 if rag_tool_context:
-                    task_prompt += ",".join(rag_tool_context) if isinstance(rag_tool_context, list) else str(rag_tool_context)
+                    user_prompt += ",".join(rag_tool_context) if isinstance(rag_tool_context, list) else str(rag_tool_context)
 
         if self.with_memory == True:
             contextual_memory = ContextualMemory(
@@ -543,18 +540,39 @@ class Agent(BaseModel):
             query = f"{task.description} {context_str}".strip()
             memory = contextual_memory.build_context_for_task(query=query)
             if memory.strip() != "":
-                task_prompt += memory.strip()
+                user_prompt += memory.strip()
 
         ## comment out for now
         # if self.networks and self.networks._train:
-        #     task_prompt = self._training_handler(task_prompt=task_prompt)
+        #     user_prompt = self._training_handler(user_prompt=user_prompt)
         # else:
-        #     task_prompt = self._use_trained_data(task_prompt=task_prompt)
+        #     user_prompt = self._use_trained_data(user_prompt=user_prompt)
+
+        content_prompt = task._format_content_prompt()
+
+        messages = []
+        if content_prompt:
+            messages.append(
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "text",
+                            "text": user_prompt
+                        },
+                        content_prompt,
+                    ]
+                })
+        else:
+            messages.append({ "role": "user", "content": user_prompt })
+
+        if self.use_developer_prompt:
+            messages.append({ "role": "developer", "content": self.backstory })
 
         try:
             self._times_executed += 1
             raw_response = self._invoke(
-                prompts=task_prompt,
+                messages=messages,
                 response_format=task._structure_response_format(model_provider=self.llm.provider),
                 tools=tools,
                 tool_res_as_final=task.tool_res_as_final,

versionhq/agent_network/formation.py

@@ -47,9 +47,12 @@ def form_agent_network(
                         Logger(verbose=True).log(level="warning", message=f"The formation {formation} is invalid. We'll recreate a valid formation.", color="yellow")
                         formation = None
 
-                case int() | float():
+                case int():
                     formation = Formation(int(formation))
 
+                case float():
+                    formation = Formation(round(formation))
+
                 case _:
                     Logger(verbose=True).log(level="warning", message=f"The formation {formation} is invalid. We'll recreate a valid formation.", color="yellow")
                     formation = None
@@ -64,14 +67,14 @@ def form_agent_network(
     prompt_expected_outcome = expected_outcome if isinstance(expected_outcome, str) else str(expected_outcome.model_dump()) if type(expected_outcome) == BaseModel else ""
 
     class Outcome(BaseModel):
-        formation: Enum
+        formation: str
         agent_roles: list[str]
         task_descriptions: list[str]
         task_outcomes: list[list[str]]
         leader_agent: str
 
     vhq_task = Task(
-        description=f"Design a team of specialized agents to fully automate the following task and achieve the expected outcome. For each agent, define its role, task description, and expected outputs via the task with items in a list. Then specify the team formation if the formation is not given. If you think SUPERVISING or HYBRID is the best formation, include a leader_agent role, else leave the leader_agent role blank.\nTask: {str(task)}\nExpected outcome: {prompt_expected_outcome}\nFormation: {prompt_formation}",
+        description=f"Design a team of specialized agents to fully automate the following task and achieve the expected outcome. For each agent, define its role, task description, and expected outputs via the task with items in a list. Then specify the formation if the formation is not given. If you think SUPERVISING or HYBRID is the best formation, include a leader_agent role, else leave the leader_agent role blank.\nTask: {str(task)}\nExpected outcome: {prompt_expected_outcome}\nFormation: {prompt_formation}",
         pydantic_output=Outcome
     )
 
@@ -80,8 +83,12 @@ def form_agent_network(
 
     res = vhq_task.execute(agent=vhq_formation_planner, context=context)
 
-    formation_keys = ([k for k in Formation._member_map_.keys() if k == res.pydantic.formation.upper()]
-                      if res.pydantic else [k for k in Formation._member_map_.keys() if k == res.json_dict["formation"].upper()])
+    formation_keys = []
+    if hasattr(res.pydantic, "formation"):
+        formation_keys = [k for k in Formation._member_map_.keys() if k == res.pydantic.formation.upper()]
+    elif "formation" in res.json_dict:
+        formation_keys = [k for k in Formation._member_map_.keys() if k == res.json_dict["formation"].upper()]
+
     _formation = Formation[formation_keys[0]] if formation_keys else Formation.SUPERVISING
 
     network_tasks = []

versionhq/agent_network/model.py

@@ -306,12 +306,8 @@ class AgentNetwork(BaseModel):
         return res, task_graph
 
 
-    def launch(
-            self, kwargs_pre: Optional[Dict[str, str]] = None, kwargs_post: Optional[Dict[str, Any]] = None, start_index: int = None
-        ) -> Tuple[TaskOutput, TaskGraph]:
-        """
-        Launch the agent network - executing tasks and recording their outputs.
-        """
+    def launch(self, kwargs_pre: Optional[Dict[str, str]] = None, kwargs_post: Optional[Dict[str, Any]] = None, start_index: int = None) -> Tuple[TaskOutput, TaskGraph]:
+        """Launches agent network by executing tasks in the network and recording the outputs"""
 
         self._assign_tasks()
 

versionhq/knowledge/source_docling.py

@@ -1,6 +1,5 @@
 from pathlib import Path
-from typing import Iterator, List, Optional
-from urllib.parse import urlparse
+from typing import Iterator, List
 
 try:
     from docling.datamodel.base_models import InputFormat
@@ -20,7 +19,7 @@ from pydantic import Field
 
 from versionhq.knowledge.source import BaseKnowledgeSource
 from versionhq.storage.utils import fetch_db_storage_path
-from versionhq._utils.vars import KNOWLEDGE_DIRECTORY
+from versionhq._utils import KNOWLEDGE_DIRECTORY, is_valid_url
 
 
 class DoclingSource(BaseKnowledgeSource):
@@ -83,21 +82,6 @@ class DoclingSource(BaseKnowledgeSource):
             yield chunk.text
 
 
-    @staticmethod
-    def _validate_url(url: str) -> bool:
-        try:
-            result = urlparse(url)
-            return all(
-                [
-                    result.scheme in ("http", "https"),
-                    result.netloc,
-                    len(result.netloc.split(".")) >= 2,  # Ensure domain has TLD
-                ]
-            )
-        except Exception:
-            return False
-
-
     def model_post_init(self, _) -> None:
         self.valid_file_paths = self.validate_content()
         self.content.extend(self._load_content())
@@ -109,7 +93,7 @@ class DoclingSource(BaseKnowledgeSource):
             if isinstance(path, str):
                 if path.startswith(("http://", "https://")):
                     try:
-                        if self._validate_url(path):
+                        if is_valid_url(path):
                             processed_paths.append(path)
                         else:
                             raise ValueError(f"Invalid URL format: {path}")

versionhq/llm/model.py

@@ -8,12 +8,13 @@ from contextlib import contextmanager
 from typing import Any, Dict, List, Optional
 from typing_extensions import Self
 
+import litellm
 from litellm import JSONSchemaValidationError, get_supported_openai_params
 from pydantic import BaseModel, Field, PrivateAttr, model_validator, ConfigDict
 
 from versionhq.llm.llm_vars import LLM_CONTEXT_WINDOW_SIZES, MODELS, PARAMS, PROVIDERS, ENDPOINT_PROVIDERS, ENV_VARS
 from versionhq.tool.model import Tool, ToolSet
-from versionhq._utils.logger import Logger
+from versionhq._utils import Logger
 
 
 load_dotenv(override=True)
@@ -47,7 +48,6 @@ class FilteredStream:
 @contextmanager
 def suppress_warnings():
     with warnings.catch_warnings():
-        import litellm
         litellm.set_verbose = False
         warnings.filterwarnings(action="ignore")
         old_stdout = sys.stdout
@@ -102,7 +102,6 @@ class LLM(BaseModel):
         """
         Validate the given model, provider, interface provider.
         """
-        import litellm
         litellm.drop_params = True
 
         self._init_model_name = self.model
@@ -180,7 +179,6 @@ class LLM(BaseModel):
         """
         Set up valid config params after setting up a valid model, provider, interface provider names.
         """
-        import litellm
         litellm.drop_params = True
 
         self._tokens = 0
@@ -208,9 +206,7 @@ class LLM(BaseModel):
         valid_config, valid_keys = dict(), list()
 
         if self.model:
-            valid_keys = get_supported_openai_params(
-                model=self.model, custom_llm_provider=self.endpoint_provider, request_type="chat_completion"
-            )
+            valid_keys = get_supported_openai_params(model=self.model, custom_llm_provider=self.endpoint_provider, request_type="chat_completion")
 
         if not valid_keys:
             valid_keys = PARAMS.get("common")
@@ -269,7 +265,6 @@ class LLM(BaseModel):
 
 
     def _supports_stop_words(self) -> bool:
-        import litellm
         supported_params = get_supported_openai_params(model=self.model, custom_llm_provider=self.endpoint_provider)
         return "stop" in supported_params if supported_params else False
 
@@ -282,7 +277,6 @@ class LLM(BaseModel):
 
 
     def _set_callbacks(self, callbacks: List[Any]):
-        import litellm
         callback_types = [type(callback) for callback in callbacks]
         for callback in litellm.success_callback[:]:
             if type(callback) in callback_types:
@@ -306,7 +300,6 @@ class LLM(BaseModel):
         """
         Execute LLM based on the agent's params and model params.
         """
-        import litellm
         litellm.drop_params = True
         litellm.set_verbose = True
 
@@ -318,8 +311,12 @@ class LLM(BaseModel):
                 res, tool_res = None, ""
                 cred = self._set_env_vars()
 
-                if not tools:
+                if self.provider == "gemini":
+                    self.response_format = { "type": "json_object" } if not tools else None
+                else:
                     self.response_format = response_format
+
+                if not tools:
                     params = self._create_valid_params(config=config)
                     res = litellm.completion(model=self.model, messages=messages, stream=False, **params, **cred)
                     self._tokens += int(res["usage"]["total_tokens"])
@@ -327,7 +324,6 @@ class LLM(BaseModel):
 
                 else:
                     try:
-                        self.response_format = { "type": "json_object" }  if tool_res_as_final and self.provider != "gemini" else response_format
                         self.tools = [item.tool.properties if isinstance(item, ToolSet) else item.properties for item in tools]
                         params = self._create_valid_params(config=config)
                         res = litellm.completion(model=self.model, messages=messages, **params, **cred)

versionhq/task/evaluation.py

@@ -16,7 +16,7 @@ class EvaluationItem(BaseModel):
     criteria: str
     suggestion: str
     score: float
-    weight: int = 1
+    weight: int
 
 
 class Evaluation(BaseModel):

versionhq/task/model.py

@@ -16,7 +16,7 @@ from pydantic_core import PydanticCustomError
 import versionhq as vhq
 from versionhq.task.evaluation import Evaluation, EvaluationItem
 from versionhq.tool.model import Tool, ToolSet
-from versionhq._utils import process_config, Logger
+from versionhq._utils import process_config, Logger, is_valid_url
 
 
 class TaskExecutionType(enum.Enum):
@@ -187,7 +187,7 @@ class TaskOutput(BaseModel):
     evaluation: Optional[InstanceOf[Evaluation]] = Field(default=None, description="stores overall evaluation of the task output. stored in ltm")
 
 
-    def to_context_prompt(self) -> str:
+    def _to_context_prompt(self) -> str:
         """
         Returns response in string as a prompt context.
         """
@@ -288,6 +288,10 @@ class Task(BaseModel):
     can_use_agent_tools: bool = Field(default=True, 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`")
 
+    image: Optional[str] = Field(default=None, description="absolute file path or url in string")
+    file: Optional[str] = Field(default=None, description="absolute file path or url in string")
+    audio: Optional[str] = Field(default=None,  description="absolute file path or url in string")
+
     # executing
     execution_type: TaskExecutionType = Field(default=TaskExecutionType.SYNC)
     allow_delegation: bool = Field(default=False, description="whether to delegate the task to another agent")
@@ -301,9 +305,10 @@ class Task(BaseModel):
 
     # recording
     _tokens: int = 0
+    _tool_errors: int = 0
+    _format_errors: int = 0
+    _delegations: int = 0
     processed_agents: Set[str] = Field(default_factory=set, description="store keys of the agents that executed the task")
-    tool_errors: int = 0
-    delegations: int = 0
     output: Optional[TaskOutput] = Field(default=None, description="store the final TaskOutput object")
 
 
@@ -346,19 +351,19 @@ class Task(BaseModel):
         return self
 
 
-    def _draft_output_prompt(self, model_provider: str) -> str:
-        """
-        Draft prompts on the output format by converting `
-        """
-
+    def _draft_output_prompt(self, model_provider: str = None) -> str:
         output_prompt = ""
 
         if self.pydantic_output:
-            output_prompt = f"""
-Your response MUST STRICTLY follow the given repsonse format:
-JSON schema: {str(self.pydantic_output)}
-"""
+            output_prompt, output_formats_to_follow = "", dict()
+            response_format = str(self._structure_response_format(model_provider=model_provider))
+            for k, v in self.pydantic_output.model_fields.items():
+                output_formats_to_follow[k] = f"<Return your answer in {v.annotation}>"
 
+            output_prompt = f"""Your response MUST be a valid JSON string that strictly follows the response format. Use double quotes for all keys and string values. Do not use single quotes, trailing commas, or any other non-standard JSON syntax.
+Response format: {response_format}
+Ref. Output image: {output_formats_to_follow}
+"""
         elif self.response_fields:
             output_prompt, output_formats_to_follow = "", dict()
             response_format = str(self._structure_response_format(model_provider=model_provider))
@@ -366,13 +371,16 @@ JSON schema: {str(self.pydantic_output)}
                 if item:
                     output_formats_to_follow[item.title] = f"<Return your answer in {item.data_type.__name__}>"
 
-            output_prompt = f"""
-Your response MUST be a valid JSON string that strictly follows the response format. Use double quotes for all keys and string values. Do not use single quotes, trailing commas, or any other non-standard JSON syntax.
+            output_prompt = f"""Your response MUST be a valid JSON string that strictly follows the response format. Use double quotes for all keys and string values. Do not use single quotes, trailing commas, or any other non-standard JSON syntax.
 Response format: {response_format}
 Ref. Output image: {output_formats_to_follow}
 """
+        # elif not self.tools or self.can_use_agent_tools == False:
         else:
-            output_prompt = "You MUST Return your response as a valid JSON serializable string, enclosed in double quotes. Do not use single quotes, trailing commas, or other non-standard JSON syntax."
+            output_prompt = "You MUST return your response as a valid JSON serializable string, enclosed in double quotes. Use double quotes for all keys and string values. Do NOT use single quotes, trailing commas, or other non-standard JSON syntax."
+
+        # else:
+        #     output_prompt = "You will return a response in a concise manner."
 
         return dedent(output_prompt)
 
@@ -394,13 +402,13 @@ Ref. Output image: {output_formats_to_follow}
             case Task():
                 if not context.output:
                     res = context.execute()
-                    context_to_add = res.to_context_prompt()
+                    context_to_add = res._to_context_prompt()
 
                 else:
                     context_to_add = context.output.raw
 
             case TaskOutput():
-                context_to_add = context.to_context_prompt()
+                context_to_add = context._to_context_prompt()
 
 
             case dict():
@@ -416,7 +424,7 @@ Ref. Output image: {output_formats_to_follow}
         return dedent(context_to_add)
 
 
-    def _prompt(self, model_provider: str = None, context: Optional[Any] = None) -> str:
+    def _user_prompt(self, model_provider: str = None, context: Optional[Any] = None) -> str:
         """
         Format the task prompt and cascade it to the agent.
         """
@@ -430,11 +438,36 @@ Ref. Output image: {output_formats_to_follow}
         return "\n".join(task_slices)
 
 
+    def _format_content_prompt(self) -> Dict[str, str]:
+        """Formats content (file, image, audio) prompts that added to the messages sent to the LLM."""
+
+        from pathlib import Path
+        import base64
+
+        content_messages = {}
+
+        if self.image:
+            with open(self.image, "rb") as file:
+                content = file.read()
+                if content:
+                    encoded_file = base64.b64encode(content).decode("utf-8")
+                    img_url = f"data:image/jpeg;base64,{encoded_file}"
+                    content_messages.update({ "type": "image_url", "image_url": { "url": img_url }})
+
+        if self.file:
+            if is_valid_url(self.file):
+                content_messages.update({ "type": "image_url", "image_url": self.file })
+
+        if self.audio:
+            audio_bytes = Path(self.audio).read_bytes()
+            encoded_data = base64.b64encode(audio_bytes).decode("utf-8")
+            content_messages.update({  "type": "image_url", "image_url": "data:audio/mp3;base64,{}".format(encoded_data)})
+
+        return content_messages
+
+
     def _structure_response_format(self, data_type: str = "object", model_provider: str = "gemini") -> Dict[str, Any] | None:
-        """
-        Structure a response format either from`response_fields` or `pydantic_output`.
-        1 nested item is accepted.
-        """
+        """Structures `response_fields` or `pydantic_output` to a LLM response format."""
 
         from versionhq.task.structured_response import StructuredOutput
 
@@ -452,7 +485,7 @@ Ref. Output image: {output_formats_to_follow}
                         required_fields.append(item.title)
 
                 response_schema = {
-                    "type": "object",
+                    "type": data_type,
                     "properties": properties,
                     "required": required_fields,
                     "additionalProperties": False,
@@ -469,10 +502,43 @@ Ref. Output image: {output_formats_to_follow}
             return response_format
 
 
+    def _sanitize_raw_output(self, raw: str) -> Dict[str, str]:
+        """Sanitizes raw output and prepare for json.loads"""
+
+        import re
+        import ast
+
+        output, j = None, None
+        r = str(raw).strip()
+        r = r.replace("true", "True").replace("false", "False").replace("```json", '"').replace("```", '"').replace('\n', '').replace('\\', '')
+        r = re.sub("^'", '"', r)
+        r = re.sub(r"'\b", '"', r)
+        r = r.strip()
+        r = r.replace("  ", "")
+        try:
+            output = json.loads(r)
+        except:
+            try: j = json.dumps(eval(r))
+            except:
+                try: j = json.dumps(str(r))
+                except: j = r
+            output = json.loads(j)
+
+        if isinstance(output, dict):
+            return output
+        else:
+            try:
+                output = ast.literal_eval(j)
+            except:
+                output = ast.literal_eval(r)
+
+            return output if isinstance(output, dict) else { "output": str(r) }
+
+
     def _create_json_output(self, raw: str) -> Dict[str, Any]:
-        """
-        Create json (dict) output from the raw output and `response_fields` information.
-        """
+        """Creates JSON output from the raw output."""
+
+        output = None
 
         if raw is None or raw == "":
             Logger().log(level="warning", message="The model returned an empty response. Returning an empty dict.", color="yellow")
@@ -480,27 +546,14 @@ Ref. Output image: {output_formats_to_follow}
             return output
 
         try:
-            r = str(raw).replace("true", "True").replace("false", "False")
-            j = json.dumps(eval(r))
-            output = json.loads(j)
+            output = json.loads(raw)
             if isinstance(output, dict):
                 return output
-
             else:
-                r = str(raw).strip().replace("{'", '{"').replace("{ '", '{"').replace("': '", '": "').replace("'}", '"}').replace("' }", '"}').replace("', '", '", "').replace("['", '["').replace("[ '", '[ "').replace("']", '"]').replace("' ]", '" ]').replace("{\n'", '{"').replace("{\'", '{"').replace("true", "True").replace("false", "False").replace('\"', "'")
-                j = json.dumps(eval(r))
-                output = json.loads(j)
-
-                if isinstance(output, dict):
-                    return output
-
-                else:
-                    import ast
-                    output = ast.literal_eval(r)
-                    return output if isinstance(output, dict) else { "output": str(r) }
-
+               output = self._sanitize_raw_output(raw=raw)
+               return output
         except:
-            output = { "output": str(raw) }
+            output = self._sanitize_raw_output(raw=raw)
             return output
 
 
@@ -674,7 +727,7 @@ Ref. Output image: {output_formats_to_follow}
         if self.allow_delegation == True:
             agent_to_delegate = self._select_agent_to_delegate(agent=agent)
             agent = agent_to_delegate
-            self.delegations += 1
+            self._delegations += 1
 
         if self.tool_res_as_final == True:
             started_at = datetime.datetime.now()

versionhq/task/structured_response.py

@@ -38,7 +38,9 @@ class StructuredObject:
             description = self.field.description if hasattr(self.field, "description") and self.field.description is not None else ""
             field_name = self.field.__name__ if hasattr(self.field, "__name__") and self.field.__name__ else self.title
             self.properties.update({ field_name : { "type": SchemaType(self.field.annotation.__args__).convert() }})
-            self.required.append(field_name)
+
+            if field_name not in self.required:
+                self.required.append(field_name)
 
             return {
                 self.title: {

versionhq/task_graph/draft.py

@@ -33,12 +33,11 @@ def workflow(final_output: Type[BaseModel], context: Any = None, human: bool = F
 
     dep_type_prompt = ", ".join([k for k in DependencyType._member_map_.keys()])
 
-    graph_expert = Agent(
-        role="vhq-G Expert",
+    vhq_graph_expert = Agent(
+        role="vhq-Graph Expert",
         goal="design the most resource-efficient workflow graph to achieve the given goal",
         knowledge_sources=[
             "https://en.wikipedia.org/wiki/Graph_theory",
-            # "https://www.geeksforgeeks.org/graph-data-structure-and-algorithms/?ref=lbp",
             "https://www.geeksforgeeks.org/graph-and-its-representations/",
             ", ".join([k for k in DependencyType._member_map_.keys()]),
         ],
@@ -60,12 +59,16 @@ def workflow(final_output: Type[BaseModel], context: Any = None, human: bool = F
             ])
         ]
     )
-    res = task.execute(agent=graph_expert, context=[context_prompt, context])
+    res = task.execute(agent=vhq_graph_expert, context=[context_prompt, context])
 
     if not res:
         return None
 
-    task_items = res.json_dict["tasks"]
+    task_items = res.json_dict["tasks"] if "tasks" in res.json_dict else []
+
+    if not task_items:
+        return None
+
     tasks, nodes = [], []
 
     for item in task_items:
@@ -92,7 +95,6 @@ def workflow(final_output: Type[BaseModel], context: Any = None, human: bool = F
                 task_graph.add_dependency(
                     source=source.identifier, target=target.identifier, dependency_type=dependency_type)
 
-
     task_graph.visualize()
 
     if human:

{versionhq-1.2.3.8.dist-info → versionhq-1.2.4.1.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.3.8
-Summary: An agentic orchestration framework for building agent networks that handle task automation.
+Version: 1.2.4.1
+Summary: A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
         
@@ -88,15 +88,15 @@ Requires-Dist: torchvision>=0.21.0; extra == "torch"
 
 # Overview
 
-[![DL](https://img.shields.io/badge/Download-20K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
+[![DL](https://img.shields.io/badge/Download-30K+-red)](https://clickpy.clickhouse.com/dashboard/versionhq)
 ![MIT license](https://img.shields.io/badge/License-MIT-green)
 [![Publisher](https://github.com/versionHQ/multi-agent-system/actions/workflows/publish.yml/badge.svg)](https://github.com/versionHQ/multi-agent-system/actions/workflows/publish.yml)
-![PyPI](https://img.shields.io/badge/PyPI-v1.2.2+-blue)
+![PyPI](https://img.shields.io/badge/PythonSDK-v1.2.4+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11|3.12|3.13-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
-Agentic orchestration framework for multi-agent networks and task graphs for complex task automation.
+A Python framework for autonomous agent networks that handle task automation with multi-step reasoning.
 
 **Visit:**
 
@@ -154,11 +154,11 @@ Agents adapt their formation based on task complexity.
 You can specify a desired formation or allow the agents to determine it autonomously (default).
 
 
-|  | **Solo Agent** | **Supervising** | **Squad** | **Random** |
-| :--- | :--- | :--- | :--- | :--- |
-| **Formation** | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/rbgxttfoeqqis1ettlfz.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/zhungor3elxzer5dum10.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/dnusl7iy7kiwkxwlpmg8.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/sndpczatfzbrosxz9ama.png" alt="solo" width="200"> |
-| **Usage** | <ul><li>A single agent with tools, knowledge, and memory.</li><li>When self-learning mode is on - it will turn into **Random** formation.</li></ul> | <ul><li>Leader agent gives directions, while sharing its knowledge and memory.</li><li>Subordinates can be solo agents or networks.</li></ul> | <ul><li>Share tasks, knowledge, and memory among network members.</li></ul> | <ul><li>A single agent handles tasks, asking help from other agents without sharing its memory or knowledge.</li></ul> |
-| **Use case** | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
+|                 | **Solo Agent**  | **Supervising**  | **Squad**         | **Random**      |
+| :---            | :---            | :---             | :---              | :---            |
+| **Formation**   | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/rbgxttfoeqqis1ettlfz.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/zhungor3elxzer5dum10.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/dnusl7iy7kiwkxwlpmg8.png" alt="solo" width="200"> | <img src="https://res.cloudinary.com/dfeirxlea/image/upload/v1738818211/pj_m_agents/sndpczatfzbrosxz9ama.png" alt="solo" width="200"> |
+| **Usage**       | <ul><li>A single agent with tools, knowledge, and memory.</li><li>When self-learning mode is on - it will turn into **Random** formation.</li></ul> | <ul><li>Leader agent gives directions, while sharing its knowledge and memory.</li><li>Subordinates can be solo agents or networks.</li></ul> | <ul><li>Share tasks, knowledge, and memory among network members.</li></ul> | <ul><li>A single agent handles tasks, asking help from other agents without sharing its memory or knowledge.</li></ul> |
+| **Use case**    | An email agent drafts promo message for the given audience. | The leader agent strategizes an outbound campaign plan and assigns components such as media mix or message creation to subordinate agents. | An email agent and social media agent share the product knowledge and deploy multi-channel outbound campaign. | 1. An email agent drafts promo message for the given audience, asking insights on tones from other email agents which oversee other clusters. 2. An agent calls the external agent to deploy the campaign. |
 
 <hr />
 

{versionhq-1.2.3.8.dist-info → versionhq-1.2.4.1.dist-info}/RECORD

@@ -1,6 +1,8 @@
-versionhq/__init__.py,sha256=-XmzMUZrIz4XrCUOjV4K8kAbNGaSeptDjYOyWfMUYOc,2980
-versionhq/_utils/__init__.py,sha256=d-vYVcORZKG-kkLe_fzE8VbViDpAk9DDOKe2fVK25ew,178
+versionhq/__init__.py,sha256=8lc6ZRR-zxO1Bmqh3OsFM1GD_SDxufX0ebdyTsMrMsE,2980
+versionhq/_prompt/model.py,sha256=U2Uba84nVljMN4U6ALGGhVPr1aM4C9AUDTo-_WzTCYs,5205
+versionhq/_utils/__init__.py,sha256=llXOcGFlR9YF5iMI5uFb4twvM9wo-vmoMw8y1KzQVVc,233
 versionhq/_utils/i18n.py,sha256=TwA_PnYfDLA6VqlUDPuybdV9lgi3Frh_ASsb_X8jJo8,1483
+versionhq/_utils/is_valid_url.py,sha256=m8Mswvb-90FJtx1Heq6hPFDbwGgrv_R3wSbZQmEPM9Q,379
 versionhq/_utils/llm_as_a_judge.py,sha256=RM0oYfoeanuUyUL3Ewl6_8Xn1F5Axd285UMH46kxG1I,2378
 versionhq/_utils/logger.py,sha256=iHxGjm3BvUo5dHKLU88_pc0Z45wzSHOjyJGQkb7OADk,3255
 versionhq/_utils/process_config.py,sha256=YTGY_erW335RfceQfzS18YAqq-AAb-iSvKSjN7noD2E,782
@@ -8,14 +10,14 @@ versionhq/_utils/usage_metrics.py,sha256=xgYGRW3OTuK9EJyi3QYJeYcJl7dL27olcWaLo_7
 versionhq/_utils/vars.py,sha256=bZ5Dx_bFKlt3hi4-NNGXqdk7B23If_WaTIju2fiTyPQ,57
 versionhq/agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/agent/inhouse_agents.py,sha256=BPkvEyMH8VnZWsMeCwsGplDT_kLwlIejeRcr-6ItGqQ,2637
-versionhq/agent/model.py,sha256=xKfg20EdL11HiFbG7V7ErHlFSDpvh5lopnHDfWULJM4,25996
+versionhq/agent/model.py,sha256=mXc_sYbrH_-dbuMnlxMArCCjxmP36MMaSWM-1lS5rKI,26600
 versionhq/agent/parser.py,sha256=riG0dkdQCxH7uJ0AbdVdg7WvL0BXhUgJht0VtQvxJBc,4082
 versionhq/agent/rpm_controller.py,sha256=grezIxyBci_lDlwAlgWFRyR5KOocXeOhYkgN02dNFNE,2360
 versionhq/agent/TEMPLATES/Backstory.py,sha256=dkfuATUQ2g2WoUKkmgAIch-RB--bektGoQaUlsDOn0g,529
 versionhq/agent/TEMPLATES/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/agent_network/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/agent_network/formation.py,sha256=CYKNUeKC392wW3leIDIAaGiKADSsumC_vTe0VOnNwRs,7901
-versionhq/agent_network/model.py,sha256=aSGZf-ZLi4I2Da9-RW8CfZ32hk9MN_RIT9Cl4xvHlE8,16050
+versionhq/agent_network/formation.py,sha256=8lFOxp9f9rG3UdXiyDbDbrtHG9nNO2lkAOLpUSQXjyo,8067
+versionhq/agent_network/model.py,sha256=-vLBqPCtfLxTf17toJkE7Gkxg1SwlrA-Frf2Pc_uB50,16021
 versionhq/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/clients/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/clients/customer/__init__.py,sha256=-YXh1FQfvpfLacK8SUC7bD7Wx_eIEi4yrkCC_cUasFg,217
@@ -29,11 +31,11 @@ versionhq/knowledge/_utils.py,sha256=YWRF8U533cfZes_gZqUvdj-K24MD2ri1R0gjc_aPYyc
 versionhq/knowledge/embedding.py,sha256=KfHc__1THxb5jrg1EMrF-v944RDuIr2hE0l-MtM3Bp0,6826
 versionhq/knowledge/model.py,sha256=ixH8n5kLtJEp1nPAFYA0piYm-n0nnFDtWFp0r9YEVAs,1787
 versionhq/knowledge/source.py,sha256=-hEUPtJUHHMx4rUKtiHl19J8xAMw-WVBw34zwa2jZ08,13630
-versionhq/knowledge/source_docling.py,sha256=dcu1ITqPXwWZ_lK-6tykEKhhC82eNRTMoWRpxK9Kzls,5441
+versionhq/knowledge/source_docling.py,sha256=XpavmLvh4dLcuTikj8MCE9KG52oQMafy7_wBneliMK0,4994
 versionhq/knowledge/storage.py,sha256=Kd-4r6aWM5EDaoXrzKXbgi1hY6tysSQARPGXM95qMmU,8266
 versionhq/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/llm/llm_vars.py,sha256=qSG-_pYeWksdMmwASXpjQqf97fMovsY4lNTSCHQF88k,5694
-versionhq/llm/model.py,sha256=W9zcrC18zEz8BKKG2HJ2rO-8rdphif7sdiAHNc9oJbU,17400
+versionhq/llm/model.py,sha256=P4J6ZU0vY5HU7XHLelz7oznPmeEElHPFsAo-2Vd8DQ0,17255
 versionhq/memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/memory/contextual_memory.py,sha256=QEMVvHuEXxY7M6-12S8HhyFKf108KfX8Zzt7paPW048,3882
 versionhq/memory/model.py,sha256=VQR1229t7GQPMItlGAHLtJrb6LrZfSoRA1DRW4z0SOU,8234
@@ -45,14 +47,14 @@ versionhq/storage/rag_storage.py,sha256=bS2eE874obarYl-4hT6ZWYWTRsqtfuGpKgKzERmM
 versionhq/storage/task_output_storage.py,sha256=M8vInLJ5idGAq17w1juHKXtyPyF-B-rK_P8UcqD-Px8,5357
 versionhq/storage/utils.py,sha256=r5ghA_ktdR2IuzlzKqZYCjsNxztEMzyhWLneA4cFuWY,748
 versionhq/task/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/task/evaluation.py,sha256=yKnqj3UwdNAMaFEBZmWWf0Hc09-M9hM8VETnaovlFco,3817
+versionhq/task/evaluation.py,sha256=qQSA5ZWTWA3he54ystsYpTKXJWv68gBL6DCq8ZW1bl8,3813
 versionhq/task/formatter.py,sha256=N8Kmk9vtrMtBdgJ8J7RmlKNMdZWSmV8O1bDexmCWgU0,643
-versionhq/task/model.py,sha256=8HQLzzAfM03gHL5M_7oL7UW-mZvI7rPCJ2Jxsv49VtI,29122
-versionhq/task/structured_response.py,sha256=4q-hQPu7oMMHHXEzh9YW4SJ7N5eCZ7OfZ65juyl_jCI,5000
+versionhq/task/model.py,sha256=YawjfqUwmOynoFlO_3L7qVbK8PmF-V6dUA-Ox_55kpU,31415
+versionhq/task/structured_response.py,sha256=tqOHpch8CVmMj0aZXjdDWtPNcVmBW8DVZnBvPBwS4PM,5053
 versionhq/task/TEMPLATES/Description.py,sha256=hKhpbz0ztbkUMXz9KiL-P40fis9OB5ICOdL9jCtgAhU,864
 versionhq/task_graph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/task_graph/colors.py,sha256=naJCx4Vho4iuJtbW8USUXb-M5uYvd5ds2p8qbjUfRus,669
-versionhq/task_graph/draft.py,sha256=l18XacRsbDhAv6CvKMnUMI26IDuizA1UNWHbL1q5gn4,5099
+versionhq/task_graph/draft.py,sha256=K14J90Heii2JiCOsQsz1uE0NWout-lr8wpJbk-KEYfI,5099
 versionhq/task_graph/model.py,sha256=3DzZXP4SSJP3xdgZfkJDgFXUjQ05CSYFoisShfmSdcs,26582
 versionhq/tool/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/tool/cache_handler.py,sha256=iL8FH7X0G-cdT0uhJwzuhLDaadTXOdfybZcDy151-es,1085
@@ -62,8 +64,8 @@ versionhq/tool/decorator.py,sha256=C4ZM7Xi2gwtEMaSeRo-geo_g_MAkY77WkSLkAuY0AyI,1
 versionhq/tool/model.py,sha256=ve9C4WyiRjQigOU0hRWVxtSUWAQNntlmeW-_DL0_lJY,12328
 versionhq/tool/rag_tool.py,sha256=dW5o-83V4bMFFJEj3PUm7XjblwrYJGmZVBlCpPj6CeM,3852
 versionhq/tool/tool_handler.py,sha256=2m41K8qo5bGCCbwMFferEjT-XZ-mE9F0mDUOBkgivOI,1416
-versionhq-1.2.3.8.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
-versionhq-1.2.3.8.dist-info/METADATA,sha256=c-aVXe5FBs_a_YPXQN4HBxfAJZv7ZxR0c1f_5cAsuKg,21262
-versionhq-1.2.3.8.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
-versionhq-1.2.3.8.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
-versionhq-1.2.3.8.dist-info/RECORD,,
+versionhq-1.2.4.1.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
+versionhq-1.2.4.1.dist-info/METADATA,sha256=v3Va4NIWCPW_pdVWCSljRqCaDcmXjg_xV3mwybmszrA,21380
+versionhq-1.2.4.1.dist-info/WHEEL,sha256=jB7zZ3N9hIM9adW7qlTAyycLYW9npaWKLRzaoVcLKcM,91
+versionhq-1.2.4.1.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
+versionhq-1.2.4.1.dist-info/RECORD,,