versionhq 1.1.13.0__py3-none-any.whl → 1.2.0.1__py3-none-any.whl

{versionhq-1.1.13.0.dist-info → versionhq-1.2.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: versionhq
-Version: 1.1.13.0
+Version: 1.2.0.1
 Summary: An agentic orchestration framework for building agent networks that handle task automation.
 Author-email: Kuriko Iwai <kuriko@versi0n.io>
 License: MIT License
@@ -74,13 +74,19 @@ 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)](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)
+![PyPI](https://img.shields.io/badge/PyPI-v1.2.0+-blue)
 ![python ver](https://img.shields.io/badge/Python-3.11+-purple)
 ![pyenv ver](https://img.shields.io/badge/pyenv-2.5.0-orange)
 
@@ -103,15 +109,21 @@ A Python framework for agentic orchestration that handles complex task automatio
 
 - [Key Features](#key-features)
   - [Agent formation](#agent-formation)
+  - [Graph Theory Concept](#graph-theory-concept)
+  - [Agent optimization](#agent-optimization)
 - [Quick Start](#quick-start)
   - [Package installation](#package-installation)
   - [Forming a agent network](#forming-a-agent-network)
-  - [Customizing AI agents](#customizing-ai-agents)
+  - [Executing tasks](#executing-tasks)
   - [Supervising](#supervising)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
-- [Setting Up](#setting-up)
+- [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)
+  - [Steps](#steps)
   - [Package Management with uv](#package-management-with-uv)
   - [Pre-Commit Hooks](#pre-commit-hooks)
   - [Documentation](#documentation)
@@ -144,6 +156,73 @@ 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
 
 ### Package installation
@@ -169,11 +248,11 @@ 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.
 
 
-### Customizing AI agents
+### Executing tasks
 
-You can simply build an agent using `Agent` model.
+You can simply build an agent using `Agent` model and execute the task using `Task` class.
 
-By default, the agent prioritize JSON serializable outputs over plane texts.
+By default, agents prioritize JSON over plane text outputs.
 
 
    ```python
@@ -189,7 +268,6 @@ By default, the agent prioritize JSON serializable outputs over plane texts.
 
 
    agent = vhq.Agent(role="demo", goal="amazing project goal")
-
    task = vhq.Task(
       description="Amazing task",
       pydantic_output=CustomOutput,
@@ -197,7 +275,7 @@ By default, the agent prioritize JSON serializable outputs over plane texts.
       callback_kwargs=dict(message="Hi! Here is the result: ")
    )
 
-   res = task.execute_sync(agent=agent, context="amazing context to consider.")
+   res = task.execute(agent=agent, context="amazing context to consider.")
    print(res)
    ```
 
@@ -253,21 +331,29 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 
 ## 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
 
+
 **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**
+**LLM Integration**
 
-* [LiteLLM](https://docs.litellm.ai/docs/providers): Curation platform to access LLMs
+* [LiteLLM](https://docs.litellm.ai/docs/providers): Integration to diverse LLMs
 
 **Tools**
 
@@ -290,6 +376,7 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 └── workflows/                # Github actions
 │
 docs/                         # Documentation built by MkDocs
+mkdocs.yml                    # MkDocs config
 │
 src/
 └── versionhq/                # Orchestration framework package
@@ -304,30 +391,32 @@ 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
+|
+pyproject.toml                # Project config
 
 ```
 
 <hr />
 
-## Setting Up
+## 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
@@ -335,29 +424,51 @@ 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
 
-3. Add secrets to `.env` file in the project root:
+Create `.env` file in the project root and add 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
@@ -365,6 +476,7 @@ src/
 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.
+
    - Run a following command:
       ```
       uv run pytest tests -vv --cache-clear
@@ -376,6 +488,8 @@ src/
 
    * Test functions within the files must begin with `test_`.
 
+   * Pytest priorities are `1. playground demo > 2. docs use cases > 3. other features`
+
 
 4. Update `docs` accordingly.
 
@@ -418,7 +532,7 @@ src/
 
 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"
    ```
@@ -427,7 +541,7 @@ Pre-commit hooks help maintain code quality by running checks for formatting, li
 
 * 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/:
+* 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

{versionhq-1.1.13.0.dist-info → versionhq-1.2.0.1.dist-info}/RECORD

@@ -1,4 +1,4 @@
-versionhq/__init__.py,sha256=lfts4IiFxMVN-gRb7eoit56jqfMgOSMG1C8803J_-UQ,2400
+versionhq/__init__.py,sha256=k5eLPCh71oIr_Rk7g31r0MUqFggA5sC41kO7V0V3E08,2783
 versionhq/_utils/__init__.py,sha256=dzoZr4cBlh-2QZuPzTdehPUCe9lP1dmRtauD7qTjUaA,158
 versionhq/_utils/i18n.py,sha256=TwA_PnYfDLA6VqlUDPuybdV9lgi3Frh_ASsb_X8jJo8,1483
 versionhq/_utils/logger.py,sha256=j9SlQPIefdVUlwpGfJY83E2BUt1ejWgZ2M2I8aMyQ3c,1579
@@ -7,7 +7,7 @@ versionhq/_utils/usage_metrics.py,sha256=NXF18dn5NNvGK7EsQ4AAghpR8ppYOjMx6ABenLL
 versionhq/_utils/vars.py,sha256=bZ5Dx_bFKlt3hi4-NNGXqdk7B23If_WaTIju2fiTyPQ,57
 versionhq/agent/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/agent/inhouse_agents.py,sha256=vSobrH1gXDWlaNsiges3sqETeUrEssRzQvCZCY2hQZA,2374
-versionhq/agent/model.py,sha256=8aJ4rdgGEph10DuB8zhJkiRWzQTZ2LGKNq1MTeQ9hM8,23342
+versionhq/agent/model.py,sha256=kSYCAiRxF62ztj-S-_KfN0mhPKikjbFZ0fy2Yj5J7Jo,25400
 versionhq/agent/parser.py,sha256=riG0dkdQCxH7uJ0AbdVdg7WvL0BXhUgJht0VtQvxJBc,4082
 versionhq/agent/rpm_controller.py,sha256=grezIxyBci_lDlwAlgWFRyR5KOocXeOhYkgN02dNFNE,2360
 versionhq/agent/TEMPLATES/Backstory.py,sha256=IAhGnnt6VUMe3wO6IzeyZPDNu7XE7Uiu3VEXUreOcKs,532
@@ -28,11 +28,13 @@ versionhq/knowledge/source.py,sha256=30VXsl3uHdM0wK0Dik3XfFxpNpEiy539PBNBvg0Y4-g
 versionhq/knowledge/source_docling.py,sha256=hhHn3rS4KVsFKEPWcfllM8VxSL86PckZdAHDZNQNOq8,5411
 versionhq/knowledge/storage.py,sha256=7oxCg3W9mFjYH1YmuH9kFtTbNxquzYFjuUjd_TlsB9E,8170
 versionhq/llm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/llm/llm_vars.py,sha256=3fax7EXNwCw1yapIoqRMmwgGmK3O37Wm1e8uvq8ObL4,7063
-versionhq/llm/model.py,sha256=QacjThF43Vfel6LIvSt5KkOZAbzo1jYjwFgFfhrv7ms,17174
+versionhq/llm/llm_vars.py,sha256=wjQK20cKvph6Vq1v71o4d16zBGcHlwq0bzOT_zWno7w,7041
+versionhq/llm/model.py,sha256=wlzDUMEyIOm808d1vzqu9gmbB4ch-s_EUvwFR60gR80,17177
 versionhq/memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/memory/contextual_memory.py,sha256=tCsOOAUnfrOL7YiakqGoi3uShzzS870TmGnlGd3z_A4,3556
 versionhq/memory/model.py,sha256=4wow2O3UuMZ0AbC2NyxddGZac3-_GjNZbK9wsA015NA,8145
+versionhq/network/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+versionhq/network/model.py,sha256=3L5mTfGUeoY63z3NiE_xI5yjN91WjYNWqd6CDXE38YY,20318
 versionhq/storage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/storage/base.py,sha256=p-Jas0fXQan_qotnRD6seQxrT2lj-uw9-SmHQhdppcs,355
 versionhq/storage/ltm_sqlite_storage.py,sha256=wdUiuwHfJocdk0UGqyrdU4S5Nae1rgsoRNu3LWmGFcI,3951
@@ -41,16 +43,16 @@ versionhq/storage/rag_storage.py,sha256=ScWC0vH327vnGw8UGscAOoIfqrq3mhvXT3vEKzHZ
 versionhq/storage/task_output_storage.py,sha256=E1t_Fkt78dPYIOl3MP7LfQ8oGtjlzxBuSNq_8ZXKho8,4573
 versionhq/storage/utils.py,sha256=ByYXPoEIGJYLUqz-DWjbCAnneNrH1otiYbp12SCILpM,747
 versionhq/task/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/task/evaluate.py,sha256=fBLL6sm763e3Ev6uU0tMqFRUVwAcBj6dLM5N062qHuc,3952
-versionhq/task/formation.py,sha256=QXFZfY604cpS79X7HEBmwFKn91H8jS3Ak6EhJGgaRIg,6355
+versionhq/task/evaluate.py,sha256=WdUgjbZL62XrxyWe5MTz29scfzwmuAHGxJ7GvAB8Fmk,3954
+versionhq/task/formation.py,sha256=iHhW2webMirYC78G8kHpaMTYjCdq7c3yFD2u2Egd8Eo,6350
 versionhq/task/formatter.py,sha256=N8Kmk9vtrMtBdgJ8J7RmlKNMdZWSmV8O1bDexmCWgU0,643
 versionhq/task/log_handler.py,sha256=LT7YnO7gcPR9IZS7eRvMjnHh8crMBFtqduxd8dxIbkk,1680
-versionhq/task/model.py,sha256=qbH_fMnkDqZUp-Sgd7LB7LMsXSaytMFMVffS5q3En1c,29160
-versionhq/task/structured_response.py,sha256=uVqgeUxNOACPe2hdc0RELSbtKd1vrwonfjXMOGTT0TI,4818
+versionhq/task/model.py,sha256=zAnZ-_5YKZRs43gpM2AL9IVtttq5GqGfqfCMj_Oyz9g,30624
+versionhq/task/structured_response.py,sha256=4q-hQPu7oMMHHXEzh9YW4SJ7N5eCZ7OfZ65juyl_jCI,5000
 versionhq/task/TEMPLATES/Description.py,sha256=V-4kh8xpQTKOcDMi2xnuP-fcNk6kuoz1_5tYBlDLQWQ,420
 versionhq/team/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-versionhq/team/model.py,sha256=qPsV3O3O2TIOT-3h142KVVFdO587LhoOeVkK2niZHEc,19062
-versionhq/team/team_planner.py,sha256=x1eLkdfQwW6w3Kyi_wVaVlA41TaNJDIYWhtEqp_OcaI,3675
+versionhq/team/model.py,sha256=kxrjF3RFGO9l3IsJIffI1nqgl_Vh5RLuhqrwIqbEoBY,19214
+versionhq/team/team_planner.py,sha256=Zc3zvhPR7T0O8RQoq9CKOrvrll4klemY1rONLFeJ96M,3663
 versionhq/tool/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 versionhq/tool/cache_handler.py,sha256=iL8FH7X0G-cdT0uhJwzuhLDaadTXOdfybZcDy151-es,1085
 versionhq/tool/composio_tool.py,sha256=38mEiVvTkuw1BLD233Bl1Gwxbpss1yfQiZLTWwX6BdA,8648
@@ -58,8 +60,8 @@ versionhq/tool/composio_tool_vars.py,sha256=FvBuEXsOQUYnN7RTFxT20kAkiEYkxWKkiVtg
 versionhq/tool/decorator.py,sha256=C4ZM7Xi2gwtEMaSeRo-geo_g_MAkY77WkSLkAuY0AyI,1205
 versionhq/tool/model.py,sha256=PO4zNWBZcJhYVur381YL1dy6zqurio2jWjtbxOxZMGI,12194
 versionhq/tool/tool_handler.py,sha256=2m41K8qo5bGCCbwMFferEjT-XZ-mE9F0mDUOBkgivOI,1416
-versionhq-1.1.13.0.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
-versionhq-1.1.13.0.dist-info/METADATA,sha256=zNnwZLvuWsZPjXoCrsa7PqD8iR1sJ2zUjjj8wV0QkfA,17365
-versionhq-1.1.13.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-versionhq-1.1.13.0.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
-versionhq-1.1.13.0.dist-info/RECORD,,
+versionhq-1.2.0.1.dist-info/LICENSE,sha256=cRoGGdM73IiDs6nDWKqPlgSv7aR4n-qBXYnJlCMHCeE,1082
+versionhq-1.2.0.1.dist-info/METADATA,sha256=SIMqOnM5upA8vno-gWhl5Is-yCSuXUlzYvxVX1Lve1A,21535
+versionhq-1.2.0.1.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+versionhq-1.2.0.1.dist-info/top_level.txt,sha256=DClQwxDWqIUGeRJkA8vBlgeNsYZs4_nJWMonzFt5Wj0,10
+versionhq-1.2.0.1.dist-info/RECORD,,