hivetrace 1.1.3

Hivetrace SDK for monitoring LLM applications

Hivetrace SDK

Description

Hivetrace SDK is designed for integration with the Hivetrace service, providing monitoring of user prompts and LLM responses.

Installation

Install the SDK via pip:

pip install hivetrace

Usage

from hivetrace.hivetrace import HivetraceSDK

Initialize the SDK

hivetrace = HivetraceSDK()

Send a user prompt

response = hivetrace.input(
    application_id="your-application-id", # get after registering the application in the UI
    message="User prompt here"
)

Send a response from your LLM

response = hivetrace.output(
    application_id="your-application-id", # get after registering the application in the UI
    message="LLM response here"
)

Send a function call

response = hivetrace.function_call(
    application_id="your-application-id",
    tool_call_id="your-tool-call-id", # get id from LLM tool_calls/function_calls
    func_name="your_funcion",
    func_args="{'param': value}",
    func_result="{'result': values}", # nullable
    addtional_parameters=...,
)

Example with additional parameters

response = hivetrace.input(
    application_id="your-application-id",
    message="User prompt here",
    additional_parameters={
        "session_id": "your-session-id",
        "user_id": "your-user-id",
        "agents": {
            "agent-1-id": {"name": "Agent 1", "description": "Agent description"},
            "agent-2-id": {"name": "Agent 2"},
            "agent-3-id": {}
        }
    }
)

API

input(application_id: str, message: str, additional_parameters: dict = None) -> dict

Sends a user prompt to Hivetrace.

• application_id - Application identifier (must be a valid UUID, created in the UI)
• message - User prompt
• additional_parameters - Dictionary of additional parameters (optional)

Response Example for input()

{
    "status": "processed",
    "monitoring_result": {
        "is_toxic": false,
        "type_of_violation": "benign",
        "token_count": 9,
        "token_usage_warning": false,
        "token_usage_unbounded": false
    }
}

output(application_id: str, message: str, additional_parameters: dict = None) -> dict

Sends an LLM response to Hivetrace.

• application_id - Application identifier (must be a valid UUID, created in the UI)
• message - LLM response
• additional_parameters - Dictionary of additional parameters (optional)

Response Example for output()

{
    "status": "processed",
    "monitoring_result": {
        "is_toxic": false,
        "type_of_violation": "safe",
        "token_count": 21,
        "token_usage_warning": false,
        "token_usage_unbounded": false
    }
}

function_call(application_id: str, tool_call_id: str, func_name: str, func_args: str, func_result: Optional[str],additional_parameters: dict = None) -> dict

Sends an function call to Hivetrace.

• application_id - Application identifier (must be a valid UUID, created in the UI)
• tool_call_id - Identifier of function call returned by LLM API
• func_name - Name of function
• func_args - Arguments for function execution returned by LLM API
• func_result - Result of function execution (optional)
• additional_parameters - Dictionary of additional parameters (optional)

Response Example for function_call()

{
    "status": "processed",
    "monitoring_result": "PASS", 
    // Function Call monitoring is not implemented yet 
}

Additional Parameters

The additional_parameters argument is an optional dictionary that allows passing extra metadata along with requests. It may include:

• user_id (str, optional) – Unique user identifier (must be a valid UUID).
• session_id (str, optional) – UUID representing a session.
• agents (dict, optional) – Dictionary where keys are agent IDs (must be valid UUIDs) and values contain agent metadata:
  • name (str, optional) – Agent's name. If not provided, it will be automatically generated based on parts of its ID.
  • description (str, optional) – Description of the agent.

If user_id is not found in the system, it will be automatically created. Agents provided in the request will also be automatically registered in the system and can be viewed in the UI.

Configuration

The SDK loads configuration from environment variables. The allowed domain (HIVETRACE_URL) and access token (HIVETRACE_ACCESS_TOKEN) is automatically retrieved from the environment.

Configuration Sources

Hivetrace SDK can retrieve the configuration from the following sources:

1. .env File: Place a .env file in your project directory containing:

   HIVETRACE_URL=https://your-hivetrace-instance.com
   HIVETRACE_ACCESS_TOKEN=your-access-token
   

   The SDK will automatically load this.

License

This project is licensed under the Apache License 2.0.