Hive Agent Kit

This library provides you with an easy way to create and run Hive Agents.

Project Requirements

Install Python (>= 3.11):

• Download from the official Python website.

• Follow the installation instructions for your OS.

Acquiring an OpenAI API Key:

• Sign up or log in to your OpenAI account at OpenAI API.

• Navigate to the API section and generate a new API key.

Refer to the OpenAI Rate Limits for detailed information.

Supported Large Language Models (LLMs)

Here are the supported large language models in Hive Agent:

OpenAI

• gpt-4o

• gpt-4o-mini

• gpt-4-turbo

• gpt-4

• gpt-3.5-turbo

• gpt-3.5-turbo-instruct

Anthropic

• claude-3-opus-20240229

• claude-3-sonnet-20240229

• claude-3-haiku-20240307

MistralAI

• mistral-large-latest

• mistral-small-latest

• open-mixtral-8x22b

• codestral-latest

Popular Open Source LLMs

• llama3.1:latest

• llava

• gemma2:2b

• gemma2

• gemma:7b

• gemma:2b

• gemma2:27b

• codegemma

• mistral-nemo

• deepseek-coder-v2

• phi3:mini

• phi3:medium

• command-r

• command-r-plus

• and any supported by Ollama

Installation

You can either directly install from pip:

pip install git+https://github.com/hivenetwork-ai/hive-agent-py.git@main

Or add it to your requirements.txt file:

hive-agent @ git+https://github.com/hivenetwork-ai/hive-agent-py@main

Optional Dependencies

To install with the optional web3 dependencies, you can specify them as follows:

pip install git+https://github.com/hivenetwork-ai/hive-agent-py.git@main#egg=hive-agent[web3]

Or add it to your requirements.txt file:

hive-agent[web3] @ git+https://github.com/hivenetwork-ai/hive-agent-py@main

Environment Setup

• You need to specify an OPENAI_API_KEY in a .env file in this directory.

• Make a copy of the .env.example file and rename it to .env.

Configuration Setup

To use a configuration file with your HiveAgent, follow these steps:

1. Create a Configuration File:

   Create a TOML file (e.g., hive_config.toml) in your project directory. (See hive_config_example.toml).

2. Specify the Configuration Path:

   When creating a HiveAgent instance, provide the relative or absolute path to your configuration file.

from hive_agent import HiveAgent

import os

def get_config_path(filename):
    return os.path.abspath(os.path.join(os.path.dirname(__file__), filename))

simple_agent = HiveAgent(
    name="Simple Agent",
    functions=[],
    instruction="your instructions for this agent's goal",
    config_path=get_config_path("hive_config.toml") # ./hive_config.toml works too 
)

Usage

First, import the HiveAgent class:

from hive_agent import HiveAgent

Load your environment variables:

from dotenv import load_dotenvload_dotenv()

Then create a HiveAgent instance:

my_agent = HiveAgent(
    name="my_agent",
    functions=[],
    instruction="your instructions for this agent's goal",
)

Then, run your agent:

my_agent.run()

Finally, call the API endpoint, /api/v1/chat, to see the result:

curl --location 'localhost:8000/api/v1/chat' \
--header 'Content-Type: application/json' \
--data '{
    "user_id": "user123",
    "session_id": "session123",
    "chat_data": {
        "messages": [
            { "role": "user", "content": "Who is Satoshi Nakamoto?" }
        ]
    }
}'

Adding tools

You can create tools that help your agent handle more complex tasks. Here's an example:

import os
from typing import Optional, Dict
from web3 import Web3
from hive_agent import HiveAgent
from dotenv import load_dotenv

load_dotenv()

rpc_url = os.getenv("RPC_URL") # add an ETH Mainnet HTTP RPC URL to your `.env` file

def get_transaction_receipt(transaction_hash: str) -> Optional[Dict]:
    """
    Fetches the receipt of a specified transaction on the Ethereum blockchain and returns it as a dictionary.

    :param transaction_hash: The hash of the transaction to fetch the receipt for.
    :return: A dictionary containing the transaction receipt details, or None if the transaction cannot be found.
    """
    web3 = Web3(Web3.HTTPProvider(rpc_url))

    if not web3.is_connected():
        print("unable to connect to Ethereum")
        return None

    try:
        transaction_receipt = web3.eth.get_transaction_receipt(transaction_hash)
        return dict(transaction_receipt)
    except Exception as e:
        print(f"an error occurred: {e}")
        return None

if __name__ == "__main__":
    my_agent = HiveAgent(
        name="my_agent",
        functions=[get_transaction_receipt]
    )
    
    my_agent.run()

    """
    [1] send a request:
    
    ```
    curl --location 'localhost:8000/api/v1/chat' \
    --header 'Content-Type: application/json' \
    --data '{
        "user_id": "user123",
        "session_id": "session123",
        "chat_data": {
            "messages": [
                { "role": "user", "content": "Which address initiated this transaction - 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060?" }
            ]
        }
    }'
    ```
    
    [2] result:
    
    The address that initiated the transaction with hash 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060 is 0xA1E4380A3B1f749673E270229993eE55F35663b4.
    """

Adding Retriever

You can add retriever tools to create vector embeddings and retrieve semantic information. It will create vector index for every pdf documents under 'hive-agent-data/files/user' folder and can filter files with required_exts parameter.

• Hive agent supports ".md", '.mdx' ,".txt", '.csv', '.docx', '.pdf' file types.

• Hive agent supports 4 type of retriever (basic, chroma, pinecone-serverless, pinecone-pod) and controlled with retrieval_tool parameter.

Read the full tutorial here.