versionhq 1.1.12.5__tar.gz → 1.1.13.1__tar.gz

{versionhq-1.1.12.5 → versionhq-1.1.13.1}/.github/workflows/run_tests.yml

@@ -37,7 +37,7 @@ jobs:
           uv venv --python 3.12.8
           source .venv/bin/activate
           uv lock --upgrade
-          uv sync --all-extras
+          uv sync --all-extras --no-extra pygraphviz
 
       - name: Run tests
         run: uv run pytest tests -vv --cache-clear

{versionhq-1.1.12.5 → versionhq-1.1.13.1}/.gitignore

@@ -1,12 +1,12 @@
 deploy.py
 destinations.py
 
-entity_memory.py
-
 train.py
 
-# mkdocs.yml
-# docs/
+_memo
+_idea.py
+
+
 
 dist/
 lib/

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.1.12.5
-Summary: An agentic orchestration framework for building agent networks that handle task automation without human interaction.
+Version: 1.1.13.1
+Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
         
@@ -40,7 +40,7 @@ Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Software Development :: Build Tools
-Requires-Python: >=3.11
+Requires-Python: <3.13,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: regex==2024.11.6
@@ -74,10 +74,16 @@ Provides-Extra: pandas
 Requires-Dist: pandas>=2.2.3; extra == "pandas"
 Provides-Extra: numpy
 Requires-Dist: numpy>=1.26.4; extra == "numpy"
+Provides-Extra: pygraphviz
+Requires-Dist: pygraphviz>=1.14; extra == "pygraphviz"
+Provides-Extra: networkx
+Requires-Dist: networkx>=3.4.2; extra == "networkx"
+Provides-Extra: matplotlib
+Requires-Dist: matplotlib>=3.10.0; extra == "matplotlib"
 
 # Overview
 
-![DL](https://img.shields.io/badge/Download-15K+-red)
+[![DL](https://img.shields.io/badge/Download-15K+-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.1.12+-blue)
@@ -85,7 +91,7 @@ Requires-Dist: numpy>=1.26.4; extra == "numpy"
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
 
-Agentic orchestration framework to deploy agent network and handle complex task automation.
+A Python framework for agentic orchestration that handles complex task automation without human interaction.
 
 **Visit:**
 
@@ -103,20 +109,24 @@ Agentic orchestration framework to deploy agent network and handle complex task
 
 - [Key Features](#key-features)
   - [Agent formation](#agent-formation)
+  - [Graph Theory Concept](#graph-theory-concept)
+  - [Agent optimization](#agent-optimization)
 - [Quick Start](#quick-start)
-  - [Generate agent networks and launch task execution:](#generate-agent-networks-and-launch-task-execution)
-  - [Solo Agent:](#solo-agent)
-  - [Solo Agent:](#solo-agent-1)
-  - [Supervising:](#supervising)
+  - [Package installation](#package-installation)
+  - [Forming a agent network](#forming-a-agent-network)
+  - [Executing tasks](#executing-tasks)
+  - [Supervising](#supervising)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
-- [Setup](#setup)
+- [Setting Up a Project](#setting-up-a-project)
+  - [1. Installing package manager](#1-installing-package-manager)
+  - [2. Installing dependencies](#2-installing-dependencies)
+  - [3. Adding env secrets to .env file](#3-adding-env-secrets-to-env-file)
 - [Contributing](#contributing)
-  - [Documentation](#documentation)
-  - [Customizing AI Agent](#customizing-ai-agent)
-  - [Modifying RAG Functionality](#modifying-rag-functionality)
+  - [Steps](#steps)
   - [Package Management with uv](#package-management-with-uv)
   - [Pre-Commit Hooks](#pre-commit-hooks)
+  - [Documentation](#documentation)
 - [Trouble Shooting](#trouble-shooting)
 - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
 
@@ -146,22 +156,89 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 <hr />
 
+### Graph Theory Concept
+
+To completely automate task workflows, agents will build a `task-oriented network` by generating `nodes` that represent tasks and connecting them with dependency-defining `edges`.
+
+Each node is triggered by specific events and executed by an assigned agent once all dependencies are met.
+
+While the network automatically reconfigures itself, you retain the ability to direct the agents using `should_reform` variable.
+
+
+The following code snippet demonstrates the `TaskGraph` and its visualization, saving the diagram to the `uploads` directory.
+
+```python
+import versionhq as vhq
+
+task_graph = vhq.TaskGraph(directed=False, should_reform=True) # triggering auto formation
+
+task_a = vhq.Task(description="Research Topic")
+task_b = vhq.Task(description="Outline Post")
+task_c = vhq.Task(description="Write First Draft")
+
+node_a = task_graph.add_task(task=task_a)
+node_b = task_graph.add_task(task=task_b)
+node_c = task_graph.add_task(task=task_c)
+
+task_graph.add_dependency(
+   node_a.identifier, node_b.identifier,
+   type=vhq.DependencyType.FINISH_TO_START, weight=5, description="B depends on A"
+)
+task_graph.add_dependency(
+   node_a.identifier, node_c.identifier,
+   type=vhq.DependencyType.FINISH_TO_FINISH, lag=1, required=False, weight=3
+)
+
+task_graph.visualize()
+```
+
+<hr />
+
+### Agent optimization
+
+Agents are model-agnostic and can handle multiple tasks, leveraging their own and their peers' knowledge sources, memories, and tools.
+
+Agents are optimized during network formation, but customization is possible before or after.
+
+The following code snippet demonstrates agent customization:
+
+```python
+import versionhq as vhq
+
+agent = vhq.Agent(
+   role="Marketing Analyst",
+   goal="my amazing goal"
+) # assuming this agent was created during the network formation
+
+# update the agent
+agent.update(
+   llm="gemini-2.0", # updating LLM (Valid llm_config will be inherited to the new LLM.)
+   tools=[vhq.Tool(func=lambda x: x)], # adding tools
+   max_rpm=3,
+   knowledge_sources=["<KC1>", "<KS2>"], # adding knowledge sources. This will trigger the storage creation.
+   memory_config={"user_id": "0001"}, # adding memories
+   dummy="I am dummy" # <- invalid field will be automatically ignored
+)
+```
+
+<hr />
+
 ## Quick Start
 
-**Install `versionhq` package:**
+### Package installation
 
    ```
    pip install versionhq
    ```
 
-(Python 3.11 or higher)
+(Python 3.11 / 3.12)
 
-### Generate agent networks and launch task execution:
+### Forming a agent network
 
    ```python
-   from versionhq import form_agent_network
+   import versionhq as vhq
 
-   network = form_agent_network(
+   network = vhq.form_agent_network(
       task="YOUR AMAZING TASK OVERVIEW",
       expected_outcome="YOUR OUTCOME EXPECTATION",
    )
@@ -171,31 +248,28 @@ You can specify a desired formation or allow the agents to determine it autonomo
    This will form a network with multiple agents on `Formation` and return `TaskOutput` object with output in JSON, plane text, Pydantic model format with evaluation.
 
 
-### Solo Agent:
+### Executing tasks
 
-### Solo Agent:
+You can simply build an agent using `Agent` model and execute the task using `Task` class.
 
-You can simply build an agent using `Agent` model.
+By default, agents prioritize JSON over plane text outputs.
 
-By default, the agent prioritize JSON serializable output.
-
-But you can add a plane text summary of the structured output by using callbacks.
 
    ```python
+   import versionhq as vhq
    from pydantic import BaseModel
-   from versionhq import Agent, Task
 
    class CustomOutput(BaseModel):
       test1: str
       test2: list[str]
 
    def dummy_func(message: str, test1: str, test2: list[str]) -> str:
-      return f"{message}: {test1}, {", ".join(test2)}"
+      return f"""{message}: {test1}, {", ".join(test2)}"""
 
 
-   agent = Agent(role="demo", goal="amazing project goal")
+   agent = vhq.Agent(role="demo", goal="amazing project goal")
 
-   task = Task(
+   task = vhq.Task(
       description="Amazing task",
       pydantic_output=CustomOutput,
       callback=dummy_func,
@@ -221,33 +295,33 @@ This will return a `TaskOutput` object that stores response in plane text, JSON,
    )
    ```
 
-### Supervising:
+### Supervising
 
    ```python
-   from versionhq import Agent, Task, ResponseField, Team, TeamMember
+   import versionhq as vhq
 
-   agent_a = Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
-   agent_b = Agent(role="agent b", goal="My amazing goals", llm="llm-of-your-choice")
+   agent_a = vhq.Agent(role="agent a", goal="My amazing goals", llm="llm-of-your-choice")
+   agent_b = vhq.Agent(role="agent b", goal="My amazing goals", llm="llm-of-your-choice")
 
-   task_1 = Task(
+   task_1 = vhq.Task(
       description="Analyze the client's business model.",
-      response_fields=[ResponseField(title="test1", data_type=str, required=True),],
+      response_fields=[vhq.ResponseField(title="test1", data_type=str, required=True),],
       allow_delegation=True
    )
 
-    task_2 = Task(
+    task_2 = vhq.Task(
       description="Define the cohort.",
       response_fields=[ResponseField(title="test1", data_type=int, required=True),],
       allow_delegation=False
    )
 
-   team = Team(
+   team = vhq.Team(
       members=[
-         TeamMember(agent=agent_a, is_manager=False, task=task_1),
-         TeamMember(agent=agent_b, is_manager=True, task=task_2),
+         vhq.Member(agent=agent_a, is_manager=False, task=task_1),
+         vhq.Member(agent=agent_b, is_manager=True, task=task_2),
       ],
    )
-   res = team.kickoff()
+   res = team.launch()
    ```
 
 This will return a list with dictionaries with keys defined in the `ResponseField` of each task.
@@ -257,27 +331,41 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 <hr />
 
 ## Technologies Used
+
+**Graph Theory (Analysis and Visualization)**
+
+* [NetworkX](https://networkx.org/documentation/stable/reference/introduction.html): A Python package to analyze, create, and manipulate complex graph networks.
+* [Matplotlib](https://matplotlib.org/stable/index.html): Visualization library
+* [Graphviz](https://graphviz.org/about/): Graph visualization software
+
+
 **Schema, Data Validation**
-   - [Pydantic](https://docs.pydantic.dev/latest/): Data validation and serialization library for Python.
-   - [Upstage](https://console.upstage.ai/docs/getting-started/overview): Document processer for ML tasks. (Use `Document Parser API` to extract data from documents)
-   - [Docling](https://ds4sd.github.io/docling/): Document parsing
+
+* [Pydantic](https://docs.pydantic.dev/latest/): Data validation and serialization library for Python.
+* [Upstage](https://console.upstage.ai/docs/getting-started/overview): Document processer for ML tasks. (Use `Document Parser API` to extract data from documents)
+* [Docling](https://ds4sd.github.io/docling/): Document parsing
+
 
 **Storage**
-   - [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
-   - [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
-   - [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
 
-**LLM-curation**
-   - [LiteLLM](https://docs.litellm.ai/docs/providers): Curation platform to access LLMs
+* [mem0ai](https://docs.mem0.ai/quickstart#install-package): Agents' memory storage and management.
+* [Chroma DB](https://docs.trychroma.com/): Vector database for storing and querying usage data.
+* [SQLite](https://www.sqlite.org/docs.html): C-language library to implements a small SQL database engine.
+
+**LLM Integration**
+
+* [LiteLLM](https://docs.litellm.ai/docs/providers): Integration to diverse LLMs
 
 **Tools**
-   - [Composio](https://composio.dev/): Conect RAG agents with external tools, Apps, and APIs to perform actions and receive triggers. We use [tools](https://composio.dev/tools) and [RAG tools](https://app.composio.dev/app/ragtool) from Composio toolset.
+
+* [Composio](https://composio.dev/): Conect RAG agents with external tools, Apps, and APIs to perform actions and receive triggers. We use [tools](https://composio.dev/tools) and [RAG tools](https://app.composio.dev/app/ragtool) from Composio toolset.
 
 **Deployment**
-   - Python: Primary programming language. v3.13 is recommended.
-   - [uv](https://docs.astral.sh/uv/): Python package installer and resolver
-   - [pre-commit](https://pre-commit.com/): Manage and maintain pre-commit hooks
-   - [setuptools](https://pypi.org/project/setuptools/): Build python modules
+
+* **Python**: Primary programming language. v3.12.x is recommended
+* [uv](https://docs.astral.sh/uv/): Python package installer and resolver
+* [pre-commit](https://pre-commit.com/): Manage and maintain pre-commit hooks
+* [setuptools](https://pypi.org/project/setuptools/): Build python modules
 
 <hr />
 
@@ -303,30 +391,30 @@ src/
 │     └── llm/
 │     └── ...
 │
-└── uploads/                  # Local directory that stores uloaded files
+└── uploads/  [.gitignore]    # Local directory to store uploaded files such as graphviz diagrams generatd by `Network` class
 
 ```
 
 <hr />
 
-## Setup
+## Setting Up a Project
 
-1. Install `uv` package manager:
+### 1. Installing package manager
 
-      For MacOS:
+   For MacOS:
 
-      ```
-      brew install uv
-      ```
+   ```
+   brew install uv
+   ```
 
-      For Ubuntu/Debian:
+   For Ubuntu/Debian:
+   ```
+   sudo apt-get install uv
+   ```
 
-      ```
-      sudo apt-get install uv
-      ```
 
+### 2. Installing dependencies
 
-2. Install dependencies:
    ```
    uv venv
    source .venv/bin/activate
@@ -334,95 +422,89 @@ src/
    uv sync --all-extras
    ```
 
-* In case of AssertionError/module mismatch, run Python version control using `.pyenv`
-   ```
-   pyenv install 3.12.8
-   pyenv global 3.12.8  (optional: `pyenv global system` to get back to the system default ver.)
-   uv python pin 3.12.8
-   echo 3.12.8 > .python-version
-   ```
+   - AssertionError/module mismatch errors: Set up default Python version using `.pyenv`
+      ```
+      pyenv install 3.12.8
+      pyenv global 3.12.8  (optional: `pyenv global system` to get back to the system default ver.)
+      uv python pin 3.12.8
+      echo 3.12.8 >> .python-version
+      ```
 
+   - `pygraphviz` related errors: Run the following commands:
+      ```
+      brew install graphviz
+      uv pip install --config-settings="--global-option=build_ext" \
+      --config-settings="--global-option=-I$(brew --prefix graphviz)/include/" \
+      --config-settings="--global-option=-L$(brew --prefix graphviz)/lib/" \
+      pygraphviz
+      ```
+
+      * If the error continues, skip pygraphviz installation by:
+      ```
+      uv sync --all-extras --no-extra pygraphviz
+      ```
+
+   - `torch`/`Docling` related errors: Set up default Python version either `3.11.x` or `3.12.x` (same as AssertionError)
+
+### 3. Adding env secrets to .env file
+
+Create `.env` file in the project root and add following:
 
-3. Set up environment variables:
-   Create a `.env` file in the project root and add the following:
    ```
-   LITELLM_API_KEY=your-litellm-api-key
    OPENAI_API_KEY=your-openai-api-key
+   GEMINI_API_KEY=your-gemini-api-key
+   LITELLM_API_KEY=your-litellm-api-key
    COMPOSIO_API_KEY=your-composio-api-key
    COMPOSIO_CLI_KEY=your-composio-cli-key
-   [LLM_INTERFACE_PROVIDER_OF_YOUR_CHOICE]_API_KEY=your-api-key
+   [OTHER_LLM_INTERFACE_PROVIDER_OF_YOUR_CHOICE]_API_KEY=your-api-key
    ```
 
 <hr />
 
 ## Contributing
 
+`versionhq` is a open source project.
+
+### Steps
+
 1. Create your feature branch (`git checkout -b feature/your-amazing-feature`)
 
 2. Create amazing features
 
-3. Test the features using the `tests` directory.
+3. Add a test funcition to the `tests` directory and run **pytest**.
+
+   - Add secret values defined in `.github/workflows/run_test.yml` to your Github `repository secrets` located at settings > secrets & variables > Actions.
 
-   - Add a test function to respective components in the `tests` directory.
-   - Add your `LITELLM_API_KEY`, `OPENAI_API_KEY`, `COMPOSIO_API_KEY`, `DEFAULT_USER_ID` to the Github `repository secrets` located at settings > secrets & variables > Actions.
-   - Run a test.
+   - Run a following command:
       ```
       uv run pytest tests -vv --cache-clear
       ```
 
-   **pytest**
-
-   * When adding a new file to `tests`, name the file ended with `_test.py`.
-   * When adding a new feature to the file, name the feature started with `test_`.
-
-4. Pull the latest version of source code from the main branch (`git pull origin main`) *Address conflicts if any.
-5. Commit your changes (`git add .` / `git commit -m 'Add your-amazing-feature'`)
-6. Push to the branch (`git push origin feature/your-amazing-feature`)
-7. Open a pull request
-
-
-**Optional**
-* Flag with `#! REFINEME` for any improvements needed and `#! FIXME` for any errors.
-
-<!-- * Run a React demo app: [React demo app](https://github.com/versionHQ/test-client-app) to check it on the client endpoint.
-   ```
-   npm i
-   npm start
-   ```
-   The frontend will be available at `http://localhost:3000`. -->
-
-* `production` use case is available at `https://versi0n.io`. Currently, we are running alpha test.
-
-
-### Documentation
+   **Building a new pytest function**
 
-* To edit the documentation, see `docs` repository and edit the respective component.
+   * Files added to the `tests` directory must end in `_test.py`.
 
-* We use `mkdocs` to update the docs. You can run the doc locally at http://127.0.0.1:8000/:
+   * Test functions within the files must begin with `test_`.
 
-   ```
-   uv run python3 -m mkdocs serve --clean
-   ```
+   * Pytest priorities are `1. playground demo > 2. docs use cases > 3. other features`
 
-* 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.
 
+4. Update `docs` accordingly.
 
-### Customizing AI Agent
+5. Pull the latest version of source code from the main branch (`git pull origin main`) *Address conflicts if any.
 
-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.
+6. Commit your changes (`git add .` / `git commit -m 'Add your-amazing-feature'`)
 
-Your new agent needs to follow the `Agent` model defined in the `verionhq.agent.model.py`.
+7. Push to the branch (`git push origin feature/your-amazing-feature`)
 
-You can also add any fields and functions to the `Agent` model **universally** by modifying `verionhq.agent.model.py`.
+8. Open a pull request
 
 
-### Modifying RAG Functionality
+**Optional**
 
-The RAG system uses Chroma DB to store and query past campaign dataset. To update the knowledge base:
+* Flag with `#! REFINEME` for any improvements needed and `#! FIXME` for any errors.
 
-1. Add new files to the `uploads/` directory. (This will not be pushed to Github.)
-2. Modify the `tools.py` file to update the ingestion process if necessary.
-3. Run the ingestion process to update the Chroma DB.
+* `Playground` is available at `https://versi0n.io`.
 
 
 ### Package Management with uv
@@ -448,24 +530,44 @@ The RAG system uses Chroma DB to store and query past campaign dataset. To updat
 
 Pre-commit hooks help maintain code quality by running checks for formatting, linting, and other issues before each commit.
 
-* To skip pre-commit hooks (NOT RECOMMENDED)
+* To skip pre-commit hooks
    ```
    git commit --no-verify -m "your-commit-message"
    ```
 
+### Documentation
+
+* To edit the documentation, see `docs` repository and edit the respective component.
+
+* We use `mkdocs` to update the docs. You can run the docs locally at http://127.0.0.1:8000/.
+
+   ```
+   uv run python3 -m mkdocs serve --clean
+   ```
+
+* To add a new page, update `mkdocs.yml` in the root. Refer to [MkDocs documentation](https://squidfunk.github.io/mkdocs-material/getting-started/) for more details.
+
 <hr />
 
 ## Trouble Shooting
 
 Common issues and solutions:
-- API key errors: Ensure all API keys in the `.env` file are correct and up to date. Make sure to add `load_dotenv()` on the top of the python file to apply the latest environment values.
-- Database connection issues: Check if the Chroma DB is properly initialized and accessible.
-- Memory errors: If processing large contracts, you may need to increase the available memory for the Python process.
-- Issues related to the Python version: Docling/Pytorch is not ready for Python 3.13 as of Jan 2025. Use Python 3.12.x as default by running `uv venv --python 3.12.8` and `uv python pin 3.12.8`.
-- Issues related to dependencies: `rm -rf uv.lock`, `uv cache clean`, `uv venv`, and run `uv pip install -r requirements.txt -v`.
-- Issues related to the AI agents or RAG system: Check the `output.log` file for detailed error messages and stack traces.
-- Issues related to `Python quit unexpectedly`: Check [this stackoverflow article](https://stackoverflow.com/questions/59888499/macos-catalina-python-quit-unexpectedly-error).
-- `reportMissingImports` error from pyright after installing the package: This might occur when installing new libraries while VSCode is running. Open the command pallete (ctrl + shift + p) and run the Python: Restart language server task.
+
+* API key errors: Ensure all API keys in the `.env` file are correct and up to date. Make sure to add `load_dotenv()` on the top of the python file to apply the latest environment values.
+
+* Database connection issues: Check if the Chroma DB is properly initialized and accessible.
+
+* Memory errors: If processing large contracts, you may need to increase the available memory for the Python process.
+
+* Issues related to the Python version: Docling/Pytorch is not ready for Python 3.13 as of Jan 2025. Use Python 3.12.x as default by running `uv venv --python 3.12.8` and `uv python pin 3.12.8`.
+
+* Issues related to dependencies: `rm -rf uv.lock`, `uv cache clean`, `uv venv`, and run `uv pip install -r requirements.txt -v`.
+
+* Issues related to the AI agents or RAG system: Check the `output.log` file for detailed error messages and stack traces.
+
+* Issues related to `Python quit unexpectedly`: Check [this stackoverflow article](https://stackoverflow.com/questions/59888499/macos-catalina-python-quit-unexpectedly-error).
+
+* `reportMissingImports` error from pyright after installing the package: This might occur when installing new libraries while VSCode is running. Open the command pallete (ctrl + shift + p) and run the Python: Restart language server task.
 
 <hr />
 
@@ -477,5 +579,5 @@ 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">
+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">