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

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.3.8"
+__version__ = "1.2.4.2"
 __all__ = [
     "Agent",
 
@@ -70,6 +70,7 @@ __all__ = [
     "DependencyType",
     "Condition",
     "ConditionType",
+    "ReformTriggerEvent",
 
     "Task",
     "TaskOutput",

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/_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": [],
+    }
+]

versionhq/_prompt/model.py

@@ -0,0 +1,218 @@
+
+from typing import Dict, List, Tuple, Any
+from textwrap import dedent
+
+from pydantic import InstanceOf
+
+from versionhq._utils import is_valid_url
+
+
+class Prompt:
+    """A class to format, store, and manage a prompt."""
+
+    task: Any = None
+    agent: Any = None
+    context: Any = None
+
+
+    def __init__(self, task, agent, context):
+        from versionhq.agent.model import Agent
+        from versionhq.task.model import Task
+
+        self.task = task if isinstance(task, Task) else Task(description=str(task))
+        self.agent = agent if isinstance(agent, Agent) else Agent(role=str(agent))
+        self.context = context
+
+
+    def _draft_output_prompt(self) -> str:
+        """Drafts prompt for output either from `pydantic_output` or `response_fields`"""
+
+        from versionhq.llm.model import DEFAULT_MODEL_PROVIDER_NAME
+
+        output_prompt = ""
+        model_provider = self.agent.llm.provider if self.agent else DEFAULT_MODEL_PROVIDER_NAME
+
+        if self.task.pydantic_output:
+            output_prompt, output_formats_to_follow = "", dict()
+            response_format = str(self.task._structure_response_format(model_provider=model_provider))
+            for k, v in self.task.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.task.response_fields:
+            output_prompt, output_formats_to_follow = "", dict()
+            response_format = str(self.task._structure_response_format(model_provider=model_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. Use double quotes for all keys and string values. Do NOT use single quotes, trailing commas, or other non-standard JSON syntax."
+
+        return dedent(output_prompt)
+
+
+    def _draft_context_prompt(self, context: Any = None) -> 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 context:
+            return context_to_add
+
+        match context:
+            case str():
+                context_to_add = context
+
+            case Task():
+                if not context.output:
+                    res = context.execute()
+                    context_to_add = res._to_context_prompt()
+
+                else:
+                    context_to_add = context.output.raw
+
+            case TaskOutput():
+                context_to_add = context._to_context_prompt()
+
+
+            case dict():
+                context_to_add = str(context)
+
+            case list():
+                res = ", ".join([self._draft_context_prompt(context=item) for item in context])
+                context_to_add = res
+
+            case _:
+                pass
+
+        return dedent(context_to_add)
+
+
+    def _format_content_prompt(self) -> Dict[str, str]:
+        """Formats content (file, image, audio) prompt message."""
+
+        import base64
+        from pathlib import Path
+
+        content_messages = {}
+
+        if self.task.image:
+            with open(self.task.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.task.file:
+            if is_valid_url(self.task.file):
+                content_messages.update({ "type": "image_url", "image_url": self.file })
+
+        if self.task.audio and self.agent.llm.provider == "gemini":
+            audio_bytes = Path(self.task.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 _find_rag_tools(self) -> List[InstanceOf[Any]]:
+        """Find RAG tools from the agent and task object."""
+
+        from versionhq.tool.rag_tool import RagTool
+
+        tools = []
+        if self.task.tools:
+            [tools.append(item) for item in self.task.tools if isinstance(item, RagTool)]
+
+        if self.agent.tools and self.task.can_use_agent_tools:
+            [tools.append(item) for item in self.agent.tools if isinstance(item, RagTool)]
+
+        return tools
+
+
+    def draft_user_prompt(self) -> str:
+        """Draft task prompts from its description and context."""
+
+        output_prompt = self._draft_output_prompt()
+        task_slices = [self.task.description, output_prompt, ]
+
+        if self.context:
+            context_prompt = self._draft_context_prompt(context=self.context)
+            task_slices.insert(len(task_slices), f"Consider the following context when responding: {context_prompt}")
+
+        return "\n".join(task_slices)
+
+
+    def format_core(self, rag_tools: List[Any] = None) -> Tuple[str, str, List[Dict[str, str]]]:
+        """Formats prompt messages sent to the LLM, then returns task prompt, developer prompt, and messages."""
+
+        from versionhq.knowledge._utils import extract_knowledge_context
+        from versionhq.memory.contextual_memory import ContextualMemory
+
+        user_prompt = self.draft_user_prompt()
+        rag_tools = rag_tools if rag_tools else self._find_rag_tools()
+
+        if self.agent._knowledge:
+            agent_knowledge = self.agent._knowledge.query(query=[user_prompt,], limit=5)
+            if agent_knowledge:
+                agent_knowledge_context = extract_knowledge_context(knowledge_snippets=agent_knowledge)
+                if agent_knowledge_context:
+                    user_prompt += agent_knowledge_context
+
+        if rag_tools:
+            for item in rag_tools:
+                rag_tool_context = item.run(agent=self.agent, query=self.task.description)
+                if rag_tool_context:
+                    user_prompt += ",".join(rag_tool_context) if isinstance(rag_tool_context, list) else str(rag_tool_context)
+
+        if self.agent.with_memory == True:
+            contextual_memory = ContextualMemory(
+                memory_config=self.agent.memory_config, stm=self.agent.short_term_memory, ltm=self.agent.long_term_memory, um=self.agent.user_memory
+            )
+            context_str = self._draft_context_prompt(context=self.context)
+            query = f"{self.task.description} {context_str}".strip()
+            memory = contextual_memory.build_context_for_task(query=query)
+            if memory.strip() != "":
+                user_prompt += memory.strip()
+
+
+        ## comment out - training
+        # if self.agent.networks and self.agent.networks._train:
+        #     user_prompt = self.agent._training_handler(user_prompt=user_prompt)
+        # else:
+        #     user_prompt = self.agent._use_trained_data(user_prompt=user_prompt)
+
+
+        content_prompt = self._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.agent.use_developer_prompt:
+            messages.append({ "role": "developer", "content": self.agent.backstory })
+
+        return user_prompt, self.agent.backstory if self.agent.use_developer_prompt else None, 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

@@ -10,10 +10,8 @@ from pydantic_core import PydanticCustomError
 from versionhq.agent.rpm_controller import RPMController
 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)
@@ -33,6 +31,7 @@ class Agent(BaseModel):
     _logger_config: Dict[str, Any] = PrivateAttr(default=dict(verbose=True, info_file_save=True))
 
     api_key: Optional[str] = Field(default=None)
+    self_learn: bool = Field(default=False)
     config: Optional[Dict[str, Any]] = Field(default=None, exclude=True, description="values to add to the Agent class")
 
     id: UUID4 = Field(default_factory=uuid.uuid4, frozen=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):
@@ -338,25 +337,6 @@ class Agent(BaseModel):
         return llm
 
 
-    def _update_llm(self, llm: Any = None, llm_config: Optional[Dict[str, Any]] = None) -> Self:
-        """
-        Update llm and llm_config of the exsiting agent. (Other conditions will remain the same.)
-        """
-
-        if not llm and not llm_config:
-            Logger(**self._logger_config, filename=self.key).log(level="error", message="Missing llm or llm_config values to update", color="red")
-            pass
-
-        self.llm = llm
-        if llm_config:
-            if self.llm_config:
-                self.llm_config.update(llm_config)
-            else:
-                self.llm_config = llm_config
-
-        return self.set_up_llm()
-
-
     def _train(self) -> Self:
         """
         Fine-tuned the base model using OpenAI train framework.
@@ -369,7 +349,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 +365,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()
@@ -428,6 +403,25 @@ class Agent(BaseModel):
                 raise ValueError("Invalid response from LLM call - None or empty.")
 
 
+    def _update_llm(self, llm: Any = None, llm_config: Optional[Dict[str, Any]] = None) -> Self:
+        """
+        Updates llm and llm_config of the exsiting agent. (Other conditions will remain the same.)
+        """
+
+        if not llm and not llm_config:
+            Logger(**self._logger_config, filename=self.key).log(level="error", message="Missing llm or llm_config values to update", color="red")
+            pass
+
+        self.llm = llm
+        if llm_config:
+            if self.llm_config:
+                self.llm_config.update(llm_config)
+            else:
+                self.llm_config = llm_config
+
+        return self.set_up_llm()
+
+
     def update(self, **kwargs) -> Self:
         """
         Update the existing agent. Address variables that require runnning set_up_x methods first, then update remaining variables.
@@ -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,19 +492,20 @@ 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
 
 
     def execute_task(self, task, context: Optional[Any] = None, task_tools: Optional[List[Tool | ToolSet]] = list()) -> str:
-        """
-        Format a task prompt, adding context from knowledge and memory (if given), and invoke LLM.
-        """
+        """Handling task execution."""
 
         from versionhq.task.model import Task
         from versionhq.tool.rag_tool import RagTool
-        from versionhq.knowledge._utils import extract_knowledge_context
+        from versionhq._prompt.model import Prompt
 
         task: InstanceOf[Task] = task
         all_tools: Optional[List[Tool | ToolSet | RagTool | Type[BaseTool]]] = task_tools + self.tools if task.can_use_agent_tools else task_tools
@@ -520,41 +515,12 @@ 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)
-
-        if self._knowledge:
-            agent_knowledge = self._knowledge.query(query=[task_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
-
-        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)
-
-        if self.with_memory == True:
-            contextual_memory = ContextualMemory(
-                memory_config=self.memory_config, stm=self.short_term_memory, ltm=self.long_term_memory, um=self.user_memory
-            )
-            context_str = task._draft_context_prompt(context=context)
-            query = f"{task.description} {context_str}".strip()
-            memory = contextual_memory.build_context_for_task(query=query)
-            if memory.strip() != "":
-                task_prompt += memory.strip()
-
-        ## comment out for now
-        # if self.networks and self.networks._train:
-        #     task_prompt = self._training_handler(task_prompt=task_prompt)
-        # else:
-        #     task_prompt = self._use_trained_data(task_prompt=task_prompt)
+        user_prompt, dev_prompt, messages = Prompt(task=task, agent=self, context=context).format_core(rag_tools=rag_tools)
 
         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,
@@ -564,7 +530,7 @@ class Agent(BaseModel):
         except Exception as e:
             self._times_executed += 1
             Logger(**self._logger_config, filename=self.key).log(level="error", message=f"The agent failed to execute the task. Error: {str(e)}", color="red")
-            raw_response = self.execute_task(task, context, task_tools)
+            user_prompt, dev_prompt, raw_response = self.execute_task(task, context, task_tools)
 
             if self._times_executed > self.max_retry_limit:
                 Logger(**self._logger_config, filename=self.key).log(level="error", message=f"Max retry limit has exceeded.", color="red")
@@ -573,7 +539,7 @@ class Agent(BaseModel):
         if self.max_rpm and self._rpm_controller:
             self._rpm_controller.stop_rpm_counter()
 
-        return raw_response
+        return user_prompt, dev_prompt, raw_response
 
 
     @property