Examples#

Client Usage#

import os
from hyperbee import Hive

client = Hive(
    # This is the default and can be omitted
    api_key=os.environ.get("HIVE_API_KEY"),
)

chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "Say this is a test",
        }
    ],
    model="hive",
)

While you can provide an api_key keyword argument, we recommend using python-dotenv to add HIVE_API_KEY="My API Key" to your .env file so that your API Key is not stored in source control.

Async Client Usage#

Simply import AsyncHive instead of Hive and use await with each API call:

import os
import asyncio
from hyperbee import AsyncHive

client = AsyncHive(
    # This is the default and can be omitted
    api_key=os.environ.get("HIVE_API_KEY"),
)


async def main() -> None:
    chat_completion = await client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Say this is a test",
            }
        ],
        model="hive",
    )


asyncio.run(main())

Functionality between the synchronous and asynchronous clients is otherwise identical.

Pipeline Usage#

import os
from hyperbee import Hive

client = Hive(
    # This is the default and can be omitted
    api_key=os.environ.get("HIVE_API_KEY"),
)


 label = client.pipeline(
     model="hive",
     task_id= "classification",
     query= "It is sunny today.",
     candidate_labels= ["weather_condition", "economy","education"]
 )

 print(label)

The code snippet demonstrates how to use the Hive API for text classification. It creates a Hive client, sets up a pipeline with a chosen model (other models besides “hive” can be used) and the “classification” task ID (currently the only supported task), specifies the text to classify and candidate labels, and prints the predicted label.

Constrained Decoding Usage#

Constraint decoding ensures that the generated content adheres to a specific schema or format, which is achieved by providing a JSON schema. The provided code snippet demonstrates the usage of constraint decoding in a chat completion request using Hive.

import os
from hyperbee import Hive

client = Hive(
    # This is the default and can be omitted
    api_key=os.environ.get("HIVE_API_KEY"),
)

user_message = """
I'm currently configuring a wireless access point for our office network and I need to generate a JSON object that accurately represents its settings. The access point's SSID should be 'OfficeNetSecure', it uses WPA2-Enterprise as its security protocol, and it's capable of a bandwidth of up to 1300 Mbps on the 5 GHz band. This JSON object will be used to document our network configurations and to automate the setup process for additional access points in the future. Please provide a JSON object that includes these details.
"""

schema= """
{
    "title": "WirelessAccessPoint",
    "type": "object",
    "properties": {
        "ssid": {
            "title": "SSID",
            "type": "string"
        },
        "securityProtocol": {
            "title": "SecurityProtocol",
            "type": "string"
        },
        "bandwidth": {
            "title": "Bandwidth",
            "type": "string"
        }
    },
    "required": ["ssid", "securityProtocol", "bandwidth"]
}
"""

chat_completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": user_message,
        }
    ],
    model="hive",
    output_mode="JSON",
    json_schema=schema
)

print(chat_completion.choices[0].message.content)

The JSON schema defines the expected structure, column names (property names), and data types of the JSON object to be generated. It helps maintain consistency and accuracy in the output. However, using a JSON schema is optional and not always necessary. If a schema is not provided, the API will still generate a JSON object, but with less control over its structure and content.

The JSON schema used in the example follows a universal JSON schema format, specifying a title and data type for each property. The “required” field is used to indicate mandatory properties.

By utilizing constraint decoding with a JSON schema, the API can parse the information from the user message and generate a well-structured JSON object that accurately represents the configuration of the wireless access point.

Chat Demo#

This is a example code for chat demo with gradio.

Install necessary packages:

pip install gradio hyperbee

demo.py file:

from hyperbee import Hive
import gradio as gr
import os


client = Hive(
    api_key=os.environ["HIVE_API_KEY"],
)


def predict(message, history):
    history_openai_format = []
    for human, assistant in history:
        history_openai_format.append({"role": "user", "content": human})
        history_openai_format.append({"role": "assistant", "content": assistant})
    history_openai_format.append({"role": "user", "content": message})

    response = client.chat.completions.create(
        model="hive", messages=history_openai_format, temperature=0.4, stream=True
    )

    partial_message = ""
    for chunk in response:
        if chunk.choices[0].delta.content is not None:
            partial_message = partial_message + chunk.choices[0].delta.content
            yield partial_message

gr.ChatInterface(predict).launch(server_name="0.0.0.0", server_port=8080, share=True)

Run the demo.py file and open the browser with the link provided in the terminal.

python demo.py