versionhq 1.2.1.15__tar.gz → 1.2.1.17__tar.gz

{versionhq-1.2.1.15 → versionhq-1.2.1.17}/.github/workflows/deploy_docs.yml

@@ -16,15 +16,15 @@ jobs:
         run: |
           git config user.name github-actions[bot]
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-      # - uses: actions/setup-python@v5
-      #   with:
-      #     python-version: 3.12
-      # - run: echo "cache_id=$(date +%s)" >> $GITHUB_ENV
-      # - uses: actions/cache@v4
-      #   with:
-      #     key: mkdocs-material-${{ env.cache_id }}
-      #     path: .cache
-      #     restore-keys: |
-      #       mkdocs-material-
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - run: echo "cache_id=$(date +%s)" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
       - run: pip install mkdocs-material
       - run: mkdocs gh-deploy --force --clean

{versionhq-1.2.1.15 → versionhq-1.2.1.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.2.1.15
+Version: 1.2.1.17
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License

versionhq-1.2.1.17/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+This policy outlines the process for reporting security vulnerabilities affecting our systems, products, or services. We appreciate your efforts in helping us maintain a secure environment and take all vulnerability reports seriously.
+
+## Supported Versions
+
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 3.12.x  | :white_check_mark: |
+| 3.11.x  | :x:                |
+| < 3.11  | :x:                |
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please submit your findings through our [reporting platform](https://versi0n.io/contact-us).
+
+Please provide the following information in your report to help us understand and address the vulnerability effectively:
+
+- Detailed Description: Clearly describe the vulnerability, including its potential impact. Be as specific as possible, including affected systems, components, and URLs.
+
+- Steps to Reproduce: Provide a step-by-step guide on how to reproduce the vulnerability. This is crucial for our team to verify and address the issue quickly. Include screenshots or videos if helpful.
+
+- Affected Systems/Components: Specify the affected systems, software, or hardware. Include version numbers where applicable.
+
+- Your Contact Information: Provide your name and email address so we can contact you for further clarification or updates. We respect your privacy and will handle your information responsibly.
+
+
+### What to Expect:
+
+We will acknowledge receipt of your vulnerability report within three business days and provide updates on the progress of our investigation and remediation efforts.
+
+If the vulnerability is accepted, we will prioritize its remediation based on its severity and potential impact. We will work to address the issue as quickly as possible and may request further information from you during the process.
+
+By submitting a vulnerability report, you agree that you are not violating any applicable laws or regulations.
+
+We appreciate your cooperation in helping us maintain a secure environment.  If you have any questions about this policy, please contact us at [reporting platform](https://versi0n.io/contact-us).

versionhq-1.2.1.17/docs/core/agent/config.md

@@ -0,0 +1,209 @@
+
+<hr />
+
+## Optimizing Model
+
+**Model Optimization**
+
+`[var]`<bold>`llm: Optional[str | LLM | Dict[str, Any]] = "gpt-4o"`</bold>
+
+You can select a model or model provider that the agent will run on.
+
+By default, when the model provider name is provided, we will select the most cost-efficient model from the given provider.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with price competition in saturated markets",
+	llm="gemini-2.0"
+)
+```
+
+<hr/>
+
+
+**Other LLM Configuration**
+
+`[var]`<bold>`llm_config: Optional[Dict[str, Any]] = None`</bold>
+
+You can specify any other parameters that the agent needs to follow when they call the LLM. Else, the agent will follow the default settings given by the model provider.
+
+e.g. Expect longer context and form a short answer
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+    role="Marketing Analyst",
+    goal="Coping with increased price competition in saturated markets.",
+    respect_context_window=False,
+    max_execution_time=60,
+    max_rpm=5,
+    llm_config=dict(
+            temperature=1,
+            top_p=0.1,
+            n=1,
+            stop="answer",
+            dummy="I am dummy" # <- invalid field will be ignored automatically.
+        )
+    )
+
+assert isinstance(agent.llm, vhq.LLM)
+assert agent.llm.temperature == 1
+assert agent.llm.top_p == 0.1
+assert agent.llm.n == 1
+assert agent.llm.stop == "answer"
+```
+
+<hr>
+
+
+## Building Knowledge
+
+**Knowlege Source**
+
+`[var]`<bold>`knowledge_sources: Optional[List[KnowledgeSource]] = None`</bold>
+
+You can add knowledge sources to the agent in the following formats:
+
+- Plane text
+- Excel file
+- PPTX
+- PDF
+- CSV
+- JSON
+- HTML file
+
+The agent will run a query in the given knowledge source using the given context, then add the search results to the task prompt context.
+
+```python
+import versionhq as vhq
+
+content = "Kuriko's favorite color is gold, and she enjoy Japanese food."
+string_source = vhq.StringKnowledgeSource(content=content)
+
+agent = vhq.Agent(
+	role="Information Agent",
+	goal="Provide information based on knowledge sources",
+	knowledge_sources=[string_source,]
+)
+
+task = vhq.Task(
+	description="Answer the following question: What is Kuriko's favorite color?"
+)
+
+res = task.execute(agent=agent)
+assert "gold" in res.raw  == True
+```
+
+* Reference: <bold>`Knowledge` class</bold>
+
+<hr />
+
+## Accessing Memories
+
+Store task execution results in memory
+
+`[var]`<bold>`with_memory: bool = False`</bold>
+
+By turning on the with_memory val True, the agent will create and store the task output and contextualize the memory when they execute the task.
+
+```python
+from versionhq.task.model import Agent
+
+agent = vhq.Agent(
+	role="Researcher",
+	goal="You research about math.",
+	with_memory=True
+)
+
+assert isinstance(agent.short_term_memory, vhq.ShortTermMemory)
+assert isinstance(agent.long_term_memory, vhq.LongTermMemory)
+```
+
+<hr />
+
+**RAG Storage**
+
+When the agent is not given any `memory_config` values, they will create `RAGStorage` to store memory:
+
+```python
+RAGStorage(
+	type="stm", # short-term memory
+	allow_reset=True, # default = True. Explicitly mentioned.
+	embedder_config=None,
+	agents=[agent,]
+)
+```
+
+MEM0 Storage
+
+* Reference: <bold>`Memory`</bold> class
+
+<hr />
+
+## Updating Existing Agents
+
+**Model configuration**
+
+`[var]`<bold>`config: Optional[Dict[str, Any]] = None`</bold>
+
+You can create an agent by using model config parameters instead.
+
+e.g. Using config val
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	config=dict(
+		role="Marketing Analyst",
+		goal="Coping with increased price competition in saturated markets.",
+	)
+)
+```
+
+This is the same as the following:
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with price competition in saturated markets.",
+)
+```
+
+<hr />
+
+**Updating existing agents**
+
+`[class method]`<bold>`update(self, **kwargs) -> Self`</bold>
+
+You can update values of exsiting agents using `update` class method.
+
+This class method will safely trigger some setups that needs to be run before the agent start executing tasks.
+
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+    role="Marketing Analyst",
+    goal="Coping with price competition in saturated markets"
+)
+
+tool = vhq.Tool(func=lambda x: x)
+agent.update(
+    tools=[tool],
+    goal="my new goal", # updating the goal (this will trigger updating the developer_prompt.)
+    max_rpm=3,
+    knowledge_sources=["testing", "testing2"], # adding knowledge sources (this will trigger the storage creation.)
+    memory_config={"user_id": "0000"},
+    llm="gemini-2.0", # Updating model (The valid llm_config for the new model will be inherited.)
+    use_developer_prompt=False,
+    dummy="I am dummy" # <- Invalid field will be automatically ignored.
+)
+```

versionhq-1.2.1.17/docs/core/agent/index.md

@@ -0,0 +1,34 @@
+---
+tags:
+  - Agent Network
+---
+
+# Agent
+
+<class>`class` versionhq.agent.model.<bold>Agent<bold></class>
+
+A Pydantic class to store `Agent` objects and handle `Task` execution as well as `LLM` configuration.
+
+
+## Quick Start
+
+By defining its role and goal in a simple sentence, the AI agent will be set up to run on <bold>`gpt-4o`</bold> by default.
+
+Calling `.start()` method can start the agent operation, then generate response in text and JSON formats stored in the `TaskOutput` object.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with price competition in saturated markets"
+)
+
+res = agent.start(context="Planning a new campaign promotion starting this summer")
+
+assert agent.id
+assert isinstance(res, vhq.TaskOutput)
+assert res.json
+```
+
+Ref. <a href="/core/task">Task</a> class / <a href="/core/llm">LLM</a> class

versionhq-1.2.1.17/docs/core/agent/ref.md

@@ -0,0 +1,40 @@
+## Variables
+
+| <div style="width:160px">**Variable**</div> | **Data Type** | **Default** | **Nullable** | **Description** |
+| :---               | :---  | :--- | :--- | :--- |
+| **`id`**   | UUID4 | uuid.uuid4() | False | Stores auto-generated ID as identifier. Not editable. |
+| **`role`**   | str | None | False | Stores a role of the agent. |
+| **`goal`**   | str | None | False | Stores a goal of the agent. |
+| **`backstory`**  | str | None | True | Stores backstory of the agent. Utilized as system prompt. |
+| **`tools`**  | List[InstanceOf[`Tool` \| `ToolSet`] \| Type[`Tool`]] | None | True | Stores tools to be used when executing a task. |
+| **`knowledge_sources`**  | List[`BaseKnowledgeSource` \| Any] | None | True | Stores knowledge sources in text, file path, or url. |
+| **`embedder_config`** | Dict[str, Any] | None | True | 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 | True | Stores configuration of the memory. |
+| **`short_term_memory`** | InstanceOf[`ShortTermMemory`] | None | True | Stores `ShortTermMemory` object. |
+| **`long_term_memory`** | InstanceOf[`LongTermMemory`] | None | True | Stores `LongTermMemory` object. |
+| **`user_memory`** | InstanceOf[`UserMemory`] | None | True | Stores `UserMemory` object. |
+| **`use_developer_prompt`** |  bool | True | - | Whether to use the system (developer) prompt when calling the model. |
+| **`developer_promt_template`** | str | None | True | File path to the prompt template. |
+| **`user_promt_template`** | str | None | True | File path to the prompt template. |
+| **`networks`** | List[Any] | list() | True | 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 | True | Stores a list of callback functions that must be called after every task execution completed.|
+| **`llm`** | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | False | Stores the main model that the agent runs on. |
+| **`func_calling_llm`** | str \| InstanceOf[`LLM`] \| Dict[str, Any] | None | False | 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 | True | Stores maximum execution time in seconds. |
+| **`max_rpm`** | int | None | True | Stores maximum number of requests per minute. |
+| **`llm_config`** | Dict[str, Any] | None | True | Stores configuration of `LLM` object. |
+| **`config`** | Dict[str, Any] | None | True | Stores model config. |
+
+
+## Class Methods
+
+| <div style="width:120px">**Method**</div> | **Params** | **Returns** | **Description** |
+| :---               | :---  | :--- | :--- |
+| **`update`** | **kwargs: Any  | Self | Updates agents with given kwargs. Invalid keys will be ignored. |
+| **`start`** | context: Any = None <br> tool_res_as_final: bool = False  | `TaskOutput` \| None  | Starts to operate the agent. |
+| **`execute_task`** | task: [Task] <br> context: Any = None <br> task_tools: Optional[List[Tool \| ToolSet]] = list() | str | Returns response from the model in plane text format. |

versionhq-1.2.1.17/docs/core/agent/task-handling.md

@@ -0,0 +1,245 @@
+
+## Prompting
+
+**Developer Prompt (System Prompt)**
+
+`[var]`<bold>`backstory: Optional[str] = TEMPLATE_BACKSTORY`<bold>
+
+Backstory will be drafted automatically using the given role, goal and other values in the Agent model, and converted into the **developer prompt** when the agent executes the task.
+
+<hr/>
+
+**Backstory template (full) for auto drafting:**
+
+```python
+BACKSTORY_FULL="""You are an expert {role} highly skilled in {skills}. You have abilities to query relevant information from the given knowledge sources and use tools such as {tools}. Leveraging these, you will identify competitive solutions to achieve the following goal: {goal}."""
+```
+
+For example, the following agent’s backstory will be auto drafted using a simple template.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with price competition in saturated markets"
+)
+
+print(agent.backstory)
+
+# You are an expert marketing analyst with relevant skillsets and abilities to query relevant information from the given knowledge sources. Leveraging these, you will identify competitive solutions to achieve the following goal: coping with price competition in saturated markets.
+```
+
+You can also specify your own backstory by simply adding the value to the backstory field of the Agent model:
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+    backstory="You are a marketing analyst for a company in a saturated market. The market is becoming increasingly price-competitive, and your company's profit margins are shrinking. Your primary goal is to develop and implement strategies to help your company maintain its market share and profitability in this challenging environment."
+)
+
+print(agent.backstory)
+
+# You are a marketing analyst for a company in a saturated market. The market is becoming increasingly price-competitive, and your company's profit margins are shrinking. Your primary goal is to develop and implement strategies to help your company maintain its market share and profitability in this challenging environment.
+```
+<hr />
+
+`[var]`<bold>`use_developer_prompt: [bool] = True`</bold>
+
+You can turn off the system prompt by setting `use_developer_prompt` False. In this case, the backstory is ignored when the agent call the LLM.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+    use_developer_prompt=False # default - True
+)
+```
+
+<hr >
+
+## Executing Tasks
+
+**Delegation**
+
+`[var]`<bold>`allow_delegation: [bool] = False`</bold>
+
+When the agent is occupied with other tasks or not capable enough to the given task, you can delegate the task to another agent or ask another agent for additional information. The delegated agent will be selected based on nature of the given task and/or tool.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+	allow_delegation=True
+)
+```
+
+<hr />
+
+**Max Retry Limit**
+
+`[var]`<bold>`max_retry_limit: Optional[int] = 2`</bold>
+
+You can define how many times the agent can retry the execution under the same given conditions when it encounters an error.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+	max_retry_limit=3
+)
+```
+
+<hr />
+
+**Maximum Number of Iterations (maxit)**
+
+`[var]`<bold>`maxit: Optional[int] = 25`</bold>
+
+You can also define the number of loops that the agent will run after it encounters an error.
+
+i.e., The agent will stop the task execution after the 30th loop.
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+    maxit=30 # default = 25
+)
+```
+
+<hr />
+
+**Context Window**
+
+`[var]`<bold>`respect_context_window: [bool] = True`</bold>
+
+A context window determines the amount of text that the model takes into account when generating a response.
+
+By adjusting the context window, you can control the level of context the model considers while generating the output. A smaller context window focuses on immediate context, while a larger context window provides a broader context.
+
+By default, the agent will follow **the 80% rule** - where they only use 80% of the context window limit of the LLM they run on.
+
+You can turn off this rule by setting `respect_context_window` False to have larger context window.
+
+
+<hr />
+
+**Max Tokens**
+
+`[var]`<bold>`max_tokens: Optional[int] = None`</bold>
+
+Max tokens defines the maximum number of tokens in the generated response. Tokens can be thought of as the individual units of text, which can be words or characters.
+
+By default, the agent will follow the default max_tokens of the model, but you can specify the max token to limit the length of the generated output.
+
+
+<hr />
+
+**Maximum Execution Time**
+
+`[var]`<bold>`max_execution_times: Optional[int] = None`</bold>
+
+The maximum amount of wall clock time to spend in the execution loop.
+
+By default, the agent will follow the default setting of the model.
+
+
+<hr />
+
+**Maximum RPM (Requests Per Minute)**
+
+`[var]`<bold>`max_rpm: Optional[int] = None`</bold>
+
+The maximum number of requests that the agent can send to the LLM.
+
+By default, the agent will follow the default setting of the model. When the value is given, we let the model sleep for 60 seconds when the number of executions exceeds the maximum requests per minute.
+
+<hr />
+
+
+## Callbacks
+
+`[var]`<bold>`callbacks: Optional[List[Callable]] = None`</bold>
+
+You can add callback functions that the agent will run after executing any task.
+
+By default, raw response from the agent will be added to the arguments of the callback function.
+
+e.g. Format a response after executing the task:
+
+```python
+import json
+from typing import Dict, Any
+
+import versionhq as vhq
+
+def format_response(res: str = None) -> str | Dict[str, Any]:
+	try:
+		r = json.dumps(eval(res))
+		formatted_res = json.loads(r)
+		return formatted_res
+	except:
+		return res
+
+agent = vhq.Agent(
+	role="Marketing Analyst",
+	goal="Coping with increased price competition in saturated markets.",
+	callbacks=[format_response]
+)
+res = agent.start()
+
+assert res.callback_output
+```
+
+<hr />
+
+**Multiple callbacks to call**
+
+The callback functions are called in order of the list index referring to the task response and response from the previous callback functions by default.
+
+e.g. Validate an initial response from the assigned agent, and format the response.
+
+```python
+import json
+from typing import Dict, Any
+
+import versionhq as vhq
+
+def assessment(res: str) -> str:
+    try:
+        sub_agent = vhq.Agent(role="Validator", goal="Validate the given solutions.")
+        task = vhq.Task(
+            description=f"Assess the given solution based on feasibilities and fits to client's strategies, then refine the solution if necessary.\nSolution: {res}"
+        )
+        r = task.sync_execute(agent=sub_agent)
+        return r.raw
+
+    except:
+        return res
+
+def format_response(res: str = None) -> str | Dict[str, Any]:
+    try:
+        r = json.dumps(eval(res))
+        formatted_res = json.loads(r)
+        return formatted_res
+    except:
+        return res
+
+agent = vhq.Agent(
+    role="Marketing Analyst",
+    goal="Build solutions to address increased price competition in saturated markets",
+    callbacks=[assessment, format_response] # add multiple funcs as callbacks - executed in order of index
+)
+```

versionhq-1.2.1.17/docs/core/agent-network/index.md

@@ -0,0 +1,43 @@
+---
+tags:
+  - Agent Network
+---
+
+# Agent Network
+
+<class>`class` versionhq.agent_network.model.<bold>AgentNetwork<bold></class>
+
+A Pydantic class to store `AgentNetwork` objects that handle multiple agent formations for the task execution.
+
+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. |
+
+<hr>
+
+## Quick Start
+
+By default, lead agents will determine the best network formation autonomously based on the given task and its goal.
+
+Calling `.launch()` method can start executing tasks by the network, then generate a response in text and JSON formats stored in the `TaskOutput` object.
+
+```python
+import versionhq as vhq
+
+network = vhq.form_agent_network(
+  task=f"create a promo plan to attract a client",
+  expected_outcome='media mix, key messages, and CTA targets.'
+)
+
+res = network.launch()
+
+assert isinstance(res, vhq.TaskOutput)
+```
+
+Ref. <a href="/core/task-output">TaskOutput</a> class
+
+Visit <a href="https://versi0n.io">Playground</a>.