versionhq 1.1.12.5__tar.gz → 1.1.13.0__tar.gz

{versionhq-1.1.12.5 → 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.5 → versionhq-1.1.13.0}/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.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,7 +77,7 @@ Requires-Dist: numpy>=1.26.4; extra == "numpy"
 
 # 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 +85,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:**
 
@@ -104,19 +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)
-  - [Solo Agent:](#solo-agent-1)
-  - [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)
+- [Setting Up](#setting-up)
 - [Contributing](#contributing)
-  - [Documentation](#documentation)
-  - [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)
+  - [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
 
    ```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 +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:
-
-### Solo Agent:
+### Customizing AI agents
 
 You can simply build an agent using `Agent` model.
 
-By default, the agent prioritize JSON serializable output.
+By default, the agent prioritize JSON serializable outputs over plane texts.
 
-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 +216,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 +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 />
 
@@ -309,7 +310,7 @@ src/
 
 <hr />
 
-## Setup
+## Setting Up
 
 1. Install `uv` package manager:
 
@@ -339,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
@@ -361,68 +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**
-
-   * 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
-
-* To edit the documentation, see `docs` repository and edit the respective component.
+   **Building a new pytest function**
 
-* We use `mkdocs` to update the docs. You can run the doc locally at http://127.0.0.1:8000/:
+   * Files added to the `tests` directory must end in `_test.py`.
 
-   ```
-   uv run python3 -m mkdocs serve --clean
-   ```
+   * Test functions within the files must begin with `test_`.
 
-* 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
@@ -453,19 +423,39 @@ 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.
+
+* 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 +467,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">