versionhq 1.1.12.4__tar.gz → 1.1.12.5__tar.gz

versionhq-1.1.12.5/.github/workflows/deploy_docs.yml

@@ -0,0 +1,30 @@
+name: Deploy Docs
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        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-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

{versionhq-1.1.12.4 → versionhq-1.1.12.5}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.1.12.4
-Summary: An agentic orchestration framework for multi-agent system that shares memory, knowledge base, and RAG tools.
+Version: 1.1.12.5
+Summary: An agentic orchestration framework for building agent networks that handle task automation without human interaction.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
         
@@ -77,6 +77,7 @@ Requires-Dist: numpy>=1.26.4; extra == "numpy"
 
 # Overview
 
+![DL](https://img.shields.io/badge/Download-15K+-red)
 ![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.1.12+-blue)
@@ -89,9 +90,9 @@ Agentic orchestration framework to deploy agent network and handle complex task
 **Visit:**
 
 - [PyPI](https://pypi.org/project/versionhq/)
-- [Github (LLM orchestration framework)](https://github.com/versionHQ/multi-agent-system)
-- [Use case](https://versi0n.io/) / [Quick demo](https://res.cloudinary.com/dfeirxlea/video/upload/v1737732977/pj_m_home/pnsyh5mfvmilwgt0eusa.mov)
 - [Docs](https://docs.versi0n.io)
+- [Github Repository](https://github.com/versionHQ/multi-agent-system)
+- [Playground](https://versi0n.io/)
 
 
 <hr />
@@ -105,15 +106,14 @@ Agentic orchestration framework to deploy agent network and handle complex task
 - [Quick Start](#quick-start)
   - [Generate agent networks and launch task execution:](#generate-agent-networks-and-launch-task-execution)
   - [Solo Agent:](#solo-agent)
-    - [Return a structured output with a summary in string.](#return-a-structured-output-with-a-summary-in-string)
+  - [Solo Agent:](#solo-agent-1)
   - [Supervising:](#supervising)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
 - [Setup](#setup)
-- [Set up a project](#set-up-a-project)
 - [Contributing](#contributing)
   - [Documentation](#documentation)
-  - [Customizing AI Agents](#customizing-ai-agents)
+  - [Customizing AI Agent](#customizing-ai-agent)
   - [Modifying RAG Functionality](#modifying-rag-functionality)
   - [Package Management with uv](#package-management-with-uv)
   - [Pre-Commit Hooks](#pre-commit-hooks)
@@ -158,7 +158,7 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 ### Generate agent networks and launch task execution:
 
-   ```
+   ```python
    from versionhq import form_agent_network
 
    network = form_agent_network(
@@ -173,9 +173,15 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 ### Solo Agent:
 
-#### Return a structured output with a summary in string.
+### Solo Agent:
+
+You can simply build an agent using `Agent` model.
 
-   ```
+By default, the agent prioritize JSON serializable output.
+
+But you can add a plane text summary of the structured output by using callbacks.
+
+   ```python
    from pydantic import BaseModel
    from versionhq import Agent, Task
 
@@ -200,23 +206,24 @@ You can specify a desired formation or allow the agents to determine it autonomo
    print(res)
    ```
 
-This will return `TaskOutput` instance that stores a response in plane text, JSON serializable dict, and Pydantic model: `CustomOutput` formats with a callback result, tool output (if given), and evaluation results (if given).
 
-   ```
+This will return a `TaskOutput` object that stores response in plane text, JSON, and Pydantic model: `CustomOutput` formats with a callback result, tool output (if given), and evaluation results (if given).
+
+   ```python
    res == TaskOutput(
-      task_id=UUID('<TASK UUID>')
+      task_id=UUID('<TASK UUID>'),
       raw='{\"test1\":\"random str\", \"test2\":[\"str item 1\", \"str item 2\", \"str item 3\"]}',
       json_dict={'test1': 'random str', 'test2': ['str item 1', 'str item 2', 'str item 3']},
-      pydantic=<class '__main__.CustomOutput'>
+      pydantic=<class '__main__.CustomOutput'>,
       tool_output=None,
-      callback_output='Hi! Here is the result: random str, str item 1, str item 2, str item 3',
+      callback_output='Hi! Here is the result: random str, str item 1, str item 2, str item 3', # returned a plain text summary
       evaluation=None
    )
    ```
 
 ### Supervising:
 
-   ```
+   ```python
    from versionhq import Agent, Task, ResponseField, Team, TeamMember
 
    agent_a = Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
@@ -281,26 +288,22 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 .github
 └── workflows/                # Github actions
 │
+docs/                         # Documentation built by MkDocs
+│
 src/
-└── versionhq/                # Orchestration frameworks
-│     ├── agent/              # Components
+└── versionhq/                # Orchestration framework package
+│     ├── agent/              # Core components
 │     └── llm/
 │     └── task/
-│     └── team/
 │     └── tool/
-│     └── cli/
-│     └── ...
-│     │
-│     ├── db/                 # Storage
-│     ├── chroma.sqlite3
 │     └── ...
 │
-└──tests/                     # Pytest
+└──tests/                     # Pytest - by core component and use cases in the docs
 │     └── agent/
 │     └── llm/
 │     └── ...
 │
-└── uploads/                  # Local repo to store the uploaded files
+└── uploads/                  # Local directory that stores uloaded files
 
 ```
 
@@ -308,10 +311,6 @@ src/
 
 ## Setup
 
-
-
-## Set up a project
-
 1. Install `uv` package manager:
 
       For MacOS:
@@ -396,6 +395,7 @@ src/
 
 
 ### Documentation
+
 * To edit the documentation, see `docs` repository and edit the respective component.
 
 * We use `mkdocs` to update the docs. You can run the doc locally at http://127.0.0.1:8000/:
@@ -404,8 +404,10 @@ src/
    uv run python3 -m mkdocs serve --clean
    ```
 
+* To add a new page, update `mkdocs.yml` in the root. Refer to [MkDocs official docs](https://squidfunk.github.io/mkdocs-material/getting-started/) for more details.
 
-### Customizing AI Agents
+
+### Customizing AI Agent
 
 To add an agent, use `sample` directory to add new `project`. You can define an agent with a specific role, goal, and set of tools.
 
@@ -470,27 +472,10 @@ Common issues and solutions:
 ## Frequently Asked Questions (FAQ)
 **Q. Where can I see if the agent is working?**
 
-> A. You can find a frontend app [here](https://versi0n.io) with real-world outbound use cases.
-> You can also test features [here](https://github.com/versionHQ/test-client-app) using React app.
+A. Visit [playground](https://versi0n.io).
+
 
 **Q. How do you analyze the customer?**
 
 > A. We employ soft clustering for each customer.
 > <img width="200" src="https://res.cloudinary.com/dfeirxlea/image/upload/v1732732628/pj_m_agents/ito937s5d5x0so8isvw6.png">
-
-
-**Q. When should I use a team vs an agent?**
-
-> A. In essence, use a team for intricate, evolving projects, and agents for quick, straightforward tasks.
-
-> Use a team when:
-
-> **Complex tasks**: You need to complete multiple, interconnected tasks that require sequential or hierarchical processing.
-
-> **Iterative refinement**: You want to iteratively improve upon the output through multiple rounds of feedback and revision.
-
-> Use an agent when:
-
-> **Simple tasks**: You have a straightforward, one-off task that doesn't require significant complexity or iteration.
-
-> **Human input**: You need to provide initial input or guidance to the agent, or you expect to review and refine the output.

{versionhq-1.1.12.4 → versionhq-1.1.12.5}/README.md

@@ -1,5 +1,6 @@
 # Overview
 
+![DL](https://img.shields.io/badge/Download-15K+-red)
 ![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.1.12+-blue)
@@ -12,9 +13,9 @@ Agentic orchestration framework to deploy agent network and handle complex task
 **Visit:**
 
 - [PyPI](https://pypi.org/project/versionhq/)
-- [Github (LLM orchestration framework)](https://github.com/versionHQ/multi-agent-system)
-- [Use case](https://versi0n.io/) / [Quick demo](https://res.cloudinary.com/dfeirxlea/video/upload/v1737732977/pj_m_home/pnsyh5mfvmilwgt0eusa.mov)
 - [Docs](https://docs.versi0n.io)
+- [Github Repository](https://github.com/versionHQ/multi-agent-system)
+- [Playground](https://versi0n.io/)
 
 
 <hr />
@@ -28,15 +29,14 @@ Agentic orchestration framework to deploy agent network and handle complex task
 - [Quick Start](#quick-start)
   - [Generate agent networks and launch task execution:](#generate-agent-networks-and-launch-task-execution)
   - [Solo Agent:](#solo-agent)
-    - [Return a structured output with a summary in string.](#return-a-structured-output-with-a-summary-in-string)
+  - [Solo Agent:](#solo-agent-1)
   - [Supervising:](#supervising)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
 - [Setup](#setup)
-- [Set up a project](#set-up-a-project)
 - [Contributing](#contributing)
   - [Documentation](#documentation)
-  - [Customizing AI Agents](#customizing-ai-agents)
+  - [Customizing AI Agent](#customizing-ai-agent)
   - [Modifying RAG Functionality](#modifying-rag-functionality)
   - [Package Management with uv](#package-management-with-uv)
   - [Pre-Commit Hooks](#pre-commit-hooks)
@@ -81,7 +81,7 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 ### Generate agent networks and launch task execution:
 
-   ```
+   ```python
    from versionhq import form_agent_network
 
    network = form_agent_network(
@@ -96,9 +96,15 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 ### Solo Agent:
 
-#### Return a structured output with a summary in string.
+### Solo Agent:
+
+You can simply build an agent using `Agent` model.
 
-   ```
+By default, the agent prioritize JSON serializable output.
+
+But you can add a plane text summary of the structured output by using callbacks.
+
+   ```python
    from pydantic import BaseModel
    from versionhq import Agent, Task
 
@@ -123,23 +129,24 @@ You can specify a desired formation or allow the agents to determine it autonomo
    print(res)
    ```
 
-This will return `TaskOutput` instance that stores a response in plane text, JSON serializable dict, and Pydantic model: `CustomOutput` formats with a callback result, tool output (if given), and evaluation results (if given).
 
-   ```
+This will return a `TaskOutput` object that stores response in plane text, JSON, and Pydantic model: `CustomOutput` formats with a callback result, tool output (if given), and evaluation results (if given).
+
+   ```python
    res == TaskOutput(
-      task_id=UUID('<TASK UUID>')
+      task_id=UUID('<TASK UUID>'),
       raw='{\"test1\":\"random str\", \"test2\":[\"str item 1\", \"str item 2\", \"str item 3\"]}',
       json_dict={'test1': 'random str', 'test2': ['str item 1', 'str item 2', 'str item 3']},
-      pydantic=<class '__main__.CustomOutput'>
+      pydantic=<class '__main__.CustomOutput'>,
       tool_output=None,
-      callback_output='Hi! Here is the result: random str, str item 1, str item 2, str item 3',
+      callback_output='Hi! Here is the result: random str, str item 1, str item 2, str item 3', # returned a plain text summary
       evaluation=None
    )
    ```
 
 ### Supervising:
 
-   ```
+   ```python
    from versionhq import Agent, Task, ResponseField, Team, TeamMember
 
    agent_a = Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
@@ -204,26 +211,22 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 .github
 └── workflows/                # Github actions
 │
+docs/                         # Documentation built by MkDocs
+│
 src/
-└── versionhq/                # Orchestration frameworks
-│     ├── agent/              # Components
+└── versionhq/                # Orchestration framework package
+│     ├── agent/              # Core components
 │     └── llm/
 │     └── task/
-│     └── team/
 │     └── tool/
-│     └── cli/
-│     └── ...
-│     │
-│     ├── db/                 # Storage
-│     ├── chroma.sqlite3
 │     └── ...
 │
-└──tests/                     # Pytest
+└──tests/                     # Pytest - by core component and use cases in the docs
 │     └── agent/
 │     └── llm/
 │     └── ...
 │
-└── uploads/                  # Local repo to store the uploaded files
+└── uploads/                  # Local directory that stores uloaded files
 
 ```
 
@@ -231,10 +234,6 @@ src/
 
 ## Setup
 
-
-
-## Set up a project
-
 1. Install `uv` package manager:
 
       For MacOS:
@@ -319,6 +318,7 @@ src/
 
 
 ### Documentation
+
 * To edit the documentation, see `docs` repository and edit the respective component.
 
 * We use `mkdocs` to update the docs. You can run the doc locally at http://127.0.0.1:8000/:
@@ -327,8 +327,10 @@ src/
    uv run python3 -m mkdocs serve --clean
    ```
 
+* To add a new page, update `mkdocs.yml` in the root. Refer to [MkDocs official docs](https://squidfunk.github.io/mkdocs-material/getting-started/) for more details.
 
-### Customizing AI Agents
+
+### Customizing AI Agent
 
 To add an agent, use `sample` directory to add new `project`. You can define an agent with a specific role, goal, and set of tools.
 
@@ -393,27 +395,10 @@ Common issues and solutions:
 ## Frequently Asked Questions (FAQ)
 **Q. Where can I see if the agent is working?**
 
-> A. You can find a frontend app [here](https://versi0n.io) with real-world outbound use cases.
-> You can also test features [here](https://github.com/versionHQ/test-client-app) using React app.
+A. Visit [playground](https://versi0n.io).
+
 
 **Q. How do you analyze the customer?**
 
 > A. We employ soft clustering for each customer.
 > <img width="200" src="https://res.cloudinary.com/dfeirxlea/image/upload/v1732732628/pj_m_agents/ito937s5d5x0so8isvw6.png">
-
-
-**Q. When should I use a team vs an agent?**
-
-> A. In essence, use a team for intricate, evolving projects, and agents for quick, straightforward tasks.
-
-> Use a team when:
-
-> **Complex tasks**: You need to complete multiple, interconnected tasks that require sequential or hierarchical processing.
-
-> **Iterative refinement**: You want to iteratively improve upon the output through multiple rounds of feedback and revision.
-
-> Use an agent when:
-
-> **Simple tasks**: You have a straightforward, one-off task that doesn't require significant complexity or iteration.
-
-> **Human input**: You need to provide initial input or guidance to the agent, or you expect to review and refine the output.

{versionhq-1.1.12.4 → versionhq-1.1.12.5}/docs/core/Agent.md

@@ -7,7 +7,7 @@ tags:
 
 # Agent
 
-<class><bold>class:</bold> versionhq.agent.model.<bold>Agent<bold></class>
+<class>`class` versionhq.agent.model.<bold>Agent<bold></class>
 
 Each agent has its unique knowledge and memory on the past task.
 
@@ -16,7 +16,7 @@ You can create one and assign the task or reassign another task to the existing
 
 ## Core usage
 
-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.
+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.
 
 ```python
 from versionhq import Agent
@@ -33,7 +33,7 @@ agent = Agent(
 
 ### Model optimization
 
-<variable>var: <bold>llm</bold>: Optional[str | LLM | Dict[str, Any]] = "gpt4o"</variable>
+`[var]`<bold>`llm: Optional[str | LLM | Dict[str, Any]] = "gpt-4o"`
 
 You can select a model or model provider that the agent will run on.
 
@@ -82,7 +82,7 @@ agent = Agent(
 ```
 
 
-We are testing some features on the following providers.
+Following models are under review.
 
 ```python
 "huggingface": [
@@ -143,7 +143,7 @@ We are testing some features on the following providers.
 
 ### Developer Prompt (System Prompt)
 
-<variable>var: <bold>backstory</bold>: Optional[str] = TEMPLATE_BACKSTORY</variable>
+`[var]`<bold>`backstory: Optional[str] = TEMPLATE_BACKSTORY`
 
 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.
 
@@ -183,8 +183,9 @@ 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 />
 
-<variable>var: <bold>use_developer_prompt</bold>: [bool] = True</variable>
+`[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.
 
@@ -202,7 +203,7 @@ agent = Agent(
 
 ### Delegation
 
-<variable>var: <bold>allow_delegation</bold>: [bool] = False</variable>
+`[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.
 
@@ -218,7 +219,7 @@ agent = Agent(
 
 ### Max Retry Limit
 
-<variable>var: <bold>max_retry_limit</bold>: Optional[int] = 2</variable>
+`[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.
 
@@ -234,7 +235,7 @@ agent = Agent(
 
 ### Maximum Number of Iterations (MaxIt)
 
-<variable>var: <bold>maxit</bold>: Optional[int] = 25</variable>
+`[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.
 
@@ -252,7 +253,7 @@ agent = Agent(
 
 ### Callbacks
 
-<variable>var: <bold>callbacks</bold>: Optional[List[Callable]] = None</variable>
+`[var]`<bold>`callbacks: Optional[List[Callable]] = None`</bold>
 
 You can add callback functions that the agent will run after executing any task.
 
@@ -320,7 +321,7 @@ agent = Agent(
 
 ### Context Window
 
-<variable>var: <bold>respect_context_window</bold>: [bool] = True</variable>
+`[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.
 
@@ -332,7 +333,7 @@ You can turn off this rule by setting `respect_context_window` False to have lar
 
 ### Max Tokens
 
-<variable>var: <bold>max_tokens</bold>: Optional[int] = None</variable>
+`[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.
 
@@ -340,7 +341,7 @@ By default, the agent will follow the default max_tokens of the model, but you c
 
 ### Maximum Execution Time
 
-<variable>var: <bold>max_execution_times</bold>: Optional[int] = None</variable>
+`[var]`<bold>`max_execution_times: Optional[int] = None`</bold>
 
 The maximum amount of wall clock time to spend in the execution loop.
 
@@ -348,7 +349,7 @@ By default, the agent will follow the default setting of the model.
 
 ### Maximum RPM (Requests Per Minute)
 
-<variable>var: <bold>max_rpm</bold>: Optional[int] = None</variable>
+`[var]`<bold>`max_rpm: Optional[int] = None`</bold>
 
 The maximum number of requests that the agent can send to the LLM.
 
@@ -356,7 +357,7 @@ By default, the agent will follow the default setting of the model. When the val
 
 ### Other LLM Configuration
 
-<variable>var: <bold>llm_xonfig</bold>: Optional[Dict[str, Any]] = None</variable>
+`[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.
 
@@ -385,17 +386,16 @@ agent = Agent(
     )
 
 print(agent.llm)
-
-*<class LLM(
-	max_tokens=3000,
-  temperature=1,
-  top_p=0.1,
-  n=1,
-  stream=False,
-  stream_options=None,
-  stop="test",
-  max_completion_tokens=10000,
-)>*
+# LLM(
+#     max_tokens=3000,
+#     temperature=1,
+#     top_p=0.1,
+#     n=1,
+#     stream=False,
+#     stream_options=None,
+#     stop="test",
+#     max_completion_tokens=10000,
+# )
 ```
 
 <hr />
@@ -404,7 +404,7 @@ print(agent.llm)
 
 ### Knowledge Sources
 
-<variable>var: <bold>knowledge_sources</bold>: Optional[List[KnowledgeSource]] = None</variable>
+`[var]`<bold>`knowledge_sources: Optional[List[KnowledgeSource]] = None`</bold>
 
 You can add knowledge sources to the agent in the following formats:
 
@@ -441,7 +441,7 @@ res = task.execute_sync(agent=agent)
 # "gold" in res.raw  == True
 ```
 
-Ref. Knowledge class
+* Reference: <bold>`Knowledge` class</bold>
 
 ---
 
@@ -449,7 +449,7 @@ Ref. Knowledge class
 
 ### Store task execution results in memory
 
-<variable>var: <bold>use_memory</bold>: bool = False</variable>
+`[var]`<bold>`use_memory: bool = False`</bold>
 
 By turning on the use_memory val True, the agent will create and store the task output and contextualize the memory when they execute the task.
 
@@ -484,7 +484,7 @@ RAGStorage(
 
 MEM0 Storage
 
-Ref. Memory class
+* Reference: <bold>`Memory`</bold> class
 
 <hr />
 
@@ -492,7 +492,7 @@ Ref. Memory class
 
 ### Model configuration
 
-<variable>var: <bold>config</bold>: Optional[Dict[str, Any]] = None</variable>
+`[var]`<bold>`config: Optional[Dict[str, Any]] = None`</bold>
 
 You can create an agent by using model config parameters instead.
 
@@ -522,5 +522,3 @@ agent = Agent(
 
 - Self-learning
 - Tool
-
-[LLM](https://www.notion.so/LLM-17e923685cf980999ac0e7f65cdb80b7?pvs=21)