versionhq 1.1.12.4__tar.gz → 1.1.13.0__tar.gz

versionhq-1.1.13.0/.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.13.0}/.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.4 → versionhq-1.1.13.0}/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.13.0
+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
@@ -77,6 +77,7 @@ Requires-Dist: numpy>=1.26.4; extra == "numpy"
 
 # 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)
@@ -84,14 +85,14 @@ 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:**
 
 - [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 />
@@ -103,20 +104,17 @@ Agentic orchestration framework to deploy agent network and handle complex task
 - [Key Features](#key-features)
   - [Agent formation](#agent-formation)
 - [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)
-  - [Supervising:](#supervising)
+  - [Package installation](#package-installation)
+  - [Forming a agent network](#forming-a-agent-network)
+  - [Customizing AI agents](#customizing-ai-agents)
+  - [Supervising](#supervising)
 - [Technologies Used](#technologies-used)
 - [Project Structure](#project-structure)
-- [Setup](#setup)
-- [Set up a project](#set-up-a-project)
+- [Setting Up](#setting-up)
 - [Contributing](#contributing)
-  - [Documentation](#documentation)
-  - [Customizing AI Agents](#customizing-ai-agents)
-  - [Modifying RAG Functionality](#modifying-rag-functionality)
   - [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)
 
@@ -148,20 +146,20 @@ You can specify a desired formation or allow the agents to determine it autonomo
 
 ## 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
 
-   ```
-   from versionhq import form_agent_network
+   ```python
+   import versionhq as vhq
 
-   network = form_agent_network(
+   network = vhq.form_agent_network(
       task="YOUR AMAZING TASK OVERVIEW",
       expected_outcome="YOUR OUTCOME EXPECTATION",
    )
@@ -171,25 +169,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:
+### Customizing AI agents
 
-#### Return a structured output with a summary in string.
+You can simply build an agent using `Agent` model.
 
-   ```
+By default, the agent prioritize JSON serializable outputs over plane texts.
+
+
+   ```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,
@@ -200,47 +201,48 @@ 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:
+### Supervising
 
-   ```
-   from versionhq import Agent, Task, ResponseField, Team, TeamMember
+   ```python
+   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.
@@ -250,27 +252,33 @@ Tasks can be delegated to a team manager, peers in the team, or completely new a
 <hr />
 
 ## Technologies Used
+
 **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.
+
+* [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
+
+* [LiteLLM](https://docs.litellm.ai/docs/providers): Curation platform to access 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 />
 
@@ -281,36 +289,28 @@ 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
 
 ```
 
 <hr />
 
-## Setup
-
-
-
-## Set up a project
+## Setting Up
 
 1. Install `uv` package manager:
 
@@ -340,12 +340,12 @@ src/
    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
+   echo 3.12.8 >> .python-version
    ```
 
 
-3. Set up environment variables:
-   Create a `.env` file in the project root and add the following:
+3. Add secrets to `.env` file in the project root:
+
    ```
    LITELLM_API_KEY=your-litellm-api-key
    OPENAI_API_KEY=your-openai-api-key
@@ -362,65 +362,37 @@ src/
 
 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 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.
+   - 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
       ```
 
-   **pytest**
+   **Building a new pytest function**
 
-   * 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_`.
+   * Files added to the `tests` directory must end in `_test.py`.
 
-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
+   * Test functions within the files must begin with `test_`.
 
 
-**Optional**
-* Flag with `#! REFINEME` for any improvements needed and `#! FIXME` for any errors.
+4. Update `docs` accordingly.
 
-<!-- * 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`. -->
+5. Pull the latest version of source code from the main branch (`git pull origin main`) *Address conflicts if any.
 
-* `production` use case is available at `https://versi0n.io`. Currently, we are running alpha test.
+6. Commit your changes (`git add .` / `git commit -m 'Add your-amazing-feature'`)
 
+7. Push to the branch (`git push origin feature/your-amazing-feature`)
 
-### Documentation
-* To edit the documentation, see `docs` repository and edit the respective component.
+8. Open a pull request
 
-* We use `mkdocs` to update the docs. You can run the doc locally at http://127.0.0.1:8000/:
 
-   ```
-   uv run python3 -m mkdocs serve --clean
-   ```
-
-
-### Customizing AI Agents
-
-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.
-
-Your new agent needs to follow the `Agent` model defined in the `verionhq.agent.model.py`.
-
-You can also add any fields and functions to the `Agent` model **universally** by modifying `verionhq.agent.model.py`.
-
-
-### 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
@@ -451,46 +423,49 @@ Pre-commit hooks help maintain code quality by running checks for formatting, li
    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 doc 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.
 
-<hr />
+* 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.
 
-## Frequently Asked Questions (FAQ)
-**Q. Where can I see if the agent is working?**
+* Database connection issues: Check if the Chroma DB is properly initialized and accessible.
 
-> 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.
+* Memory errors: If processing large contracts, you may need to increase the available memory for the Python process.
 
-**Q. How do you analyze the customer?**
+* 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`.
 
-> 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">
+* 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.
 
-**Q. When should I use a team vs an agent?**
+* Issues related to `Python quit unexpectedly`: Check [this stackoverflow article](https://stackoverflow.com/questions/59888499/macos-catalina-python-quit-unexpectedly-error).
 
-> A. In essence, use a team for intricate, evolving projects, and agents for quick, straightforward tasks.
+* `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.
 
-> Use a team when:
+<hr />
 
-> **Complex tasks**: You need to complete multiple, interconnected tasks that require sequential or hierarchical processing.
+## Frequently Asked Questions (FAQ)
+**Q. Where can I see if the agent is working?**
 
-> **Iterative refinement**: You want to iteratively improve upon the output through multiple rounds of feedback and revision.
+A. Visit [playground](https://versi0n.io).
 
-> Use an agent when:
 
-> **Simple tasks**: You have a straightforward, one-off task that doesn't require significant complexity or iteration.
+**Q. How do you analyze the customer?**
 
-> **Human input**: You need to provide initial input or guidance to the agent, or you expect to review and refine the output.
+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">