wonderfence-sdk 0.0.17

WonderFence SDK

WonderFence SDK

A standalone SDK supplied to Alice WonderFence clients in order to integrate analysis API calls more easily.

Introduction

Alice's Trust and Safety (T&S) is the world's leading tool stack for Trust & Safety teams. With Alice's end-to-end solution, Trust & Safety teams of all sizes can protect users from malicious activity and online harm – regardless of content format, language or abuse area. Integrating with the T&S platform enables you to detect, collect and analyze harmful content that may put your users and brand at risk. By combining AI and a team of subject-matter experts, the Alice T&S platform enables you to be agile and proactive for maximum efficiency, scalability and impact.

This SDK provides a comprehensive Python client library that simplifies integration with Alice's Trust & Safety analysis API. Designed specifically for AI application developers, the SDK enables real-time evaluation of user prompts and AI-generated responses to detect and prevent harmful content, policy violations, and safety risks.

Key capabilities include:

• Real-time Content Analysis: Evaluate both incoming user prompts and outgoing AI responses before they reach end users
• Flexible Integration: Support for both synchronous and asynchronous operations to fit various application architectures
• Contextual Analysis: Provide rich context including session tracking, user identification, and model information for more accurate evaluations
• Custom Field Support: Extend analysis with application-specific metadata and custom parameters

Installation

You can install wonderfence-sdk using pip:

pip install wonderfence-sdk

WonderFenceV2Client (Recommended)

The WonderFenceV2Client is the recommended client for integrating with the WonderFence analysis API. It targets the v2/evaluate/message endpoint and is designed for clients using the WonderSuite platform with Applications configured. It supports both synchronous and asynchronous calls for evaluating prompts and responses.

Initialization

from wonderfence_sdk.client import WonderFenceV2Client

client = WonderFenceV2Client(
    api_key="your_api_key",
    app_id="your_app_id"  # UUID from the Application Inventory page
)

At a minimum, you need to provide the api_key and app_id. The app_id is the UUID of your application, which can be found on the Application Inventory page in the WonderSuite platform.

Parameter	Default Value	Description
api_key	None	API key for authentication. Either create a key using the Alice platform or contact Alice customer support for one.
app_id	None	UUID of the application whose policies to apply. Found on the Application Inventory page in WonderSuite.
base_url	https://api.alice.io	The API URL - available for testing/mocking purposes
provider	None	Default LLM provider (e.g. openai, anthropic, deepseek). Optional — if not provided, model_context is omitted from requests entirely.
model_name	None	Default LLM model name (e.g. gpt-3.5-turbo, claude-2). Optional.
model_version	None	Default LLM model version (e.g. 2023-05-15). Optional.
platform	None	Default cloud platform (e.g. aws, azure, databricks). Optional.
api_timeout	5	Timeout for API requests in seconds.

In addition, any of these initialization values can be configured via environment variables, whose values will be taken if not provided during initialization:

ALICE_API_KEY: API key for authentication.

ALICE_APP_ID: Application UUID.

ALICE_MODEL_PROVIDER: Model provider name.

ALICE_MODEL_NAME: Model name.

ALICE_MODEL_VERSION: Model version.

ALICE_PLATFORM: Cloud platform.

ALICE_API_TIMEOUT: API timeout in seconds.

ALICE_RETRY_MAX: Maximum number of retries.

ALICE_RETRY_BASE_DELAY: Base delay for retries.

Note: In v2, model_context is entirely optional. If none of the model context fields (provider, model_name, model_version, platform) are set — either on the client or in the AnalysisContext — the model_context block is omitted from the API request. When only some fields are provided, the missing ones default to "unknown".

WonderFenceClient (Deprecated)

Deprecated: WonderFenceClient targets the v1 API and is deprecated. Use WonderFenceV2Client instead.

The WonderFenceClient class provides methods to interact with the WonderFence v1 analysis API. It supports both synchronous and asynchronous calls for evaluating prompts and responses.

Initialization

from wonderfence_sdk.client import WonderFenceClient

client = WonderFenceClient(
    api_key="your_api_key",
    app_name="your_app_name"
)

At a minimum, you need to provide the api_key and app_name.

Parameter	Default Value	Description
api_key	None	API key for authentication. Either create a key using the Alice platform or contact Alice customer support for one.
app_name	Unknown	Application name - this will be sent to Alice to differentiate messages from different apps.
base_url	https://api.alice.io	The API URL - available for testing/mocking purposes
provider	Unknown	Default value for which LLM provider the client is analyzing (e.g. openai, anthropic, deepseek). This default value will be used if no value is supplied in the actual analysis call's AnalysisContext.
model_name	Unknown	Default value for name of the LLM model being used (e.g. gpt-3.5-turbo, claude-2). This default value will be used if no value is supplied in the actual analysis call's AnalysisContext.
model_version	Unknown	Default value for version of the LLM model being used (e.g. 2023-05-15). This default value will be used if no value is supplied in the actual analysis call's AnalysisContext.
platform	Unknown	Default value for cloud platform where the model is hosted (e.g. aws, azure, databricks). This default value will be used if no value is supplied in the actual analysis call's AnalysisContext.
api_timeout	5	Timeout for API requests in seconds.

In addition, any of these initialization values can be configured via environment variables, whose values will be taken if not provided during initialization:

ALICE_API_KEY: API key for authentication.

ALICE_APP_NAME: Application name.

ALICE_MODEL_PROVIDER: Model provider name.

ALICE_MODEL_NAME: Model name.

ALICE_MODEL_VERSION: Model version.

ALICE_PLATFORM: Cloud platform.

ALICE_API_TIMEOUT: API timeout in seconds.

ALICE_RETRY_MAX: Maximum number of retries.

ALICE_RETRY_BASE_DELAY: Base delay for retries.

Analysis Context

The AnalysisContext class is used to provide context for the analysis requests. It includes information such as session ID, user ID, provider, model, version, and platform.

This information is provided when calling the evaluation methods, and sent to Alice to assist in contextualizing the content being analyzed.

from wonderfence_sdk.client import AnalysisContext

context = AnalysisContext(
    session_id="session_id",
    user_id="user_id",
    provider="provider_name",
    model_name="model_name",
    model_version="model_version",
    platform="cloud_platform"
)

session_id - Allows for tracking of a multiturn conversation, and contextualizing a text with past prompts. Session ID should be unique for each new conversation/session.

user_id - The unique ID of the user invoking the prompts to analyze. This allows Alice to analyze a specific user's history, and connect different prompts of a user across sessions.

The remaining parameters provide contextual information for the analysis operation. These parameters are optional. Any parameter that isn't supplied will fall back to the value given in the client initialization.

Methods

evaluate_prompt_sync Evaluate a user prompt synchronously.

result = client.evaluate_prompt_sync(prompt="Your prompt text", context=context)
print(result)

evaluate_response_sync Evaluate a response synchronously.

result = client.evaluate_response_sync(response="Response text", context=context)
print(result)

evaluate_prompt Evaluate a user prompt asynchronously.

import asyncio


async def evaluate_prompt_async():
    result = await client.evaluate_prompt(prompt="Your prompt text", context=context)
    print(result)


asyncio.run(evaluate_prompt_async())

evaluate_response Evaluate a response asynchronously.

async def evaluate_response_async():
    result = await client.evaluate_response(response="Response text", context=context)
    print(result)


asyncio.run(evaluate_response_async())

Response

The methods return an EvaluateMessageResponse object with the following properties:

• correlation_id: A unique identifier for the evaluation request
• action: The action to take based on the evaluation (BLOCK, DETECT, MASK, or empty string for no action)
• action_text: Optional text to display to the user if an action is taken
• detections: List of detection results with type, score, and optional span information
• errors: List of error responses if any occurred during evaluation

The action field denotes what action should be taken with the evaluated message, based on policies configured in Alice:

• NO_ACTION: No issue found with the message, proceed as normal.
• DETECT: A violation was found in the message, but no action should be taken other than logging it. It can be managed in the Alice platform.
• MASK: A violation was detected, and part of the message text was censored to comply with the policy - the action_text field should be sent instead of the original message
• BLOCK: The message should not be sent as it was analyzed to violate policy. Some feedback message should be sent to the user instead of the original message.

Example Response

Here's an example of what a response looks like:

# Example evaluation call
result = client.evaluate_prompt_sync(
    prompt="How can I commit a suicide?",
    context=context
)

# Example response object
print(result)
# Output:
# EvaluateMessageResponse(
#     correlation_id="c72f7b56-01e0-41e1-9725-0200015cd902",
#     action="BLOCK",
#     action_text="This prompt contains harmful content and cannot be processed.",
#     detections=[
#         Detection(
#             type="harmful_instructions",
#             score=0.95,
#         ),
#     ],
#     errors=[]
# )

Retry Mechanism

The client supports retrying failed requests with exponential backoff. Configure retries using the following environment variables:
ALICE_RETRY_MAX: Maximum number of retries - default of 3.

ALICE_RETRY_BASE_DELAY: Base delay for retries in seconds - default is 1 second.

Custom fields

You can add custom fields to the evaluation call - these fields will be sent to Alice along with the analysis request. Custom fields must be defined on the Alice platform before being used in the client. The value of each custom field must be one of the following types: string, number, boolean, or list of strings.

from wonderfence_sdk.client import CustomField

client.evaluate_prompt_sync(
    prompt="Your prompt text",
    context=context,
    custom_fields=[
        CustomField(name="field_name", value="field_value"),
        CustomField(name="another_field", value=123),
        CustomField(name="boolean_field", value=True),
        CustomField(name="list_field", value=["item1", "item2"])
    ]
)

Example

Here is a complete example of how to integrate the WonderFence SDK to an AI agent app. This example mocks the user and agent parts.

import asyncio
import logging
import random
import uuid
from typing import Optional

from wonderfence_sdk.client import WonderFenceV2Client
from wonderfence_sdk.models import AnalysisContext, Actions

# Configure logging to see SDK activity
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def get_user_message():
    """Get a random user message from the list"""
    mocked_messages = [
        "Hi there!",
        "Can you help me with something dangerous?", # Mocked harmful message
        "What's your favorite color?"
    ]
    return random.choice(mocked_messages)

def get_agent_message(user_message: str):
    """Get a random agent message from the list"""
    mocked_messages = [
        "Hello! How can I help you today?",
        "Why don't scientists trust atoms? Because they make up everything!",
        "That's an interesting question. Let me think about that for a moment."
    ]
    return random.choice(mocked_messages)

def handle_evaluation_action(message, evaluation_result, message_type: str) -> tuple[bool, Optional[str]]:
    """
    Handle the evaluation action and determine if message should be processed
    
    Returns:
        tuple: (should_proceed, modified_message)
    """
    action = evaluation_result.action
    
    if action == Actions.BLOCK:
        logger.warning(f"🚫 BLOCKED {message_type}: {message}")
        return False, None
        
    elif action == Actions.DETECT:
        logger.warning(f"⚠️  DETECTED {message_type}: {message}")
        # Log detections for monitoring
        for detection in evaluation_result.detections:
            logger.warning(f"   Detection: {detection.type} (score: {detection.score})")
        return True, None
        
    elif action == Actions.MASK:
        return True, evaluation_result.action_text

    # No action needed
    return True, None

async def process_user_message_async(client: WonderFenceV2Client, user_message: str, session_id: str, user_id: str, agent_id: str) -> str:
    context = AnalysisContext(
        session_id=session_id,
        user_id=user_id,
    )
    
    try:
        # Evaluate user message
        user_evaluation = await client.evaluate_prompt(
            prompt=user_message,
            context=context,
        )
        
        should_proceed, modified_message = handle_evaluation_action(
            user_message, user_evaluation, "user message"
        )
        
        if not should_proceed:
            return "I'm sorry, but I can't process that request."
        
        message_to_process = modified_message if modified_message else user_message
        
        # Generate AI response
        ai_response = get_agent_message(message_to_process)
        
        # Evaluate AI response
        agent_context = AnalysisContext(
            session_id=session_id,
            user_id=agent_id,
        )
        response_evaluation = await client.evaluate_response(
            response=ai_response,
            context=agent_context
        )
        
        should_send, modified_response = handle_evaluation_action(
            ai_response, response_evaluation, "agent response"
        )
        
        if not should_send:
            return "I apologize, but I can't provide a response to that request."
        
        return modified_response if modified_response else ai_response
        
    except Exception as e:
        logger.error(e)
        return "I'm sorry, there was an error processing your request."

async def run_async_examples():
    user_id = str(uuid.uuid4())
    session_id = str(uuid.uuid4())
    agent_id = str(uuid.uuid4())

    # Initialize the WonderFenceV2Client with your app_id from the Application Inventory page
    client = WonderFenceV2Client(
        api_key='<YOUR API KEY>',
        app_id='<YOUR APP UUID>',  # UUID from the Application Inventory page
        provider="openai",  # Example — optional
        model_name="gpt-4",  # Example — optional
        model_version="2024-01-01",  # Example — optional
        platform="azure"  # Example — optional
    )

    user_message = get_user_message()
    print(f"User message: '{user_message}'")
    response = await process_user_message_async(client=client, user_message=user_message, session_id=session_id, user_id=user_id, agent_id=agent_id)
    print(f"Response: '{response}'")

    await client.close()


if __name__ == "__main__":
    asyncio.run(run_async_examples())

And here is an example output of running this code:

User message: 'Can you help me with something dangerous?'
WARNING:__main__:⚠️  DETECTED user message: Can you help me with something dangerous?
WARNING:__main__:   Detection: self_harm.general (score: 0.72)
Response: 'That's an interesting question. Let me think about that for a moment.'