parlant-alice

Alice integration for Parlant - A Python package that provides content moderation and compliance checking for Parlant applications using Alice's threat analysis & detection services.

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.

Installation

You can install parlant-alice using pip:

pip install parlant-alice

Usage

Basic Usage

The parlant-alice package integrates with Parlant's framework to provide automatic content moderation and compliance checking. Here's how to use it:

from parlant.contrib.alice import Alice

# Configure Parlant server to use Alice moderation services
# Will use environment variables for configuration
async with p.Server(configure_container=Alice().configure_container) as server:

For the Alice integration to work, an API key and an application ID must be configured. The application ID is the ID (a UUID) of the application in Alice's Application Inventory; messages are evaluated against the policies assigned to that application. These and more can be supplied using environment variables. The following environment variables can be used to configure Alice integration:

Each evaluation is sent with the Parlant session ID as session_id and the session's customer ID as user_id, for both customer messages and agent replies. Sessions created without a customer belong to Parlant's shared guest customer, so they all report the same user; create a Parlant customer per end user to tell them apart. Both IDs must be 1–100 characters.

Create Alice inside your async main function, as in the examples below: the WonderFence client opens its HTTP session on the running event loop.

These values can also be passed directly when initializing the container:

from parlant.contrib.alice import Alice

async def main():
    moderation = Alice(api_key="<API_KEY>", app_id="<APP_ID>", blocked_message="This message was blocked")
    async with p.Server(configure_container=moderation.configure_container) as server:
        ...

Impact

Using Alice's moderation as shown will analyze messages sent by users to the AI agent, and the agent's response to them. This helps manage abusive messages, protect the application from malicious prompts and ensure the agent responses align to your policies.

User messages blocked by Alice will not reach the agent, but it will get a flagged message indication a censored user request. You can guide the agent to respond to such messages using the Parlant guidelines, like so:

await agent.create_guideline(
        condition="the customer's last message is censored",
        action="respond with a polite refusal to answer the question, mention that the message was censored based on guardrails analysis",
    )

Analysis of the agent responses works a bit different. If the Alice analysis marks the response as BLOCKED, the message itself will not be returned to the user, and instead a preconfigured block message will be returned. This message can be configured as described above. If a policy violation is detected but not flagged to be blocked, a warning is logged using Parlant's internal logger. This warning message will look like this: [warning ] [ReuwnpD7Gzn::process][MessageEventComposer][CannedResponseGenerator] Prevented sending a non-compliant message: 'However, I can't respond to your previous message because it was censored based on our guardrails analysis. If you have another question or need assistance, feel free to ask.'.

Example

Here is a complete example of setting up a Parlant server with Alice moderation:

import asyncio
import parlant.sdk as p
from parlant.contrib.alice import Alice

async def main():
    async with p.Server(configure_container=Alice(api_key="<API_KEY>", app_id="<APP_ID>").configure_container) as server:
        agent = await server.create_agent(
            name="Otto Carmen",
            description="You work at a computer parts store",
        )
        print(agent.id)

        blocked = await agent.create_guideline(
            condition="the customer's last message is censored",
            action="respond with a polite refusal to answer the question, mention that the message was censored based on guardrails analysis",
        )

asyncio.run(main())

And this is an example of a basic client that calls this server, and prints the messages returned by the agent to the console:

import asyncio
from parlant.client import ParlantClient

async def main():

    client = ParlantClient(base_url='http://localhost:8800')
    session = client.sessions.create(
        agent_id='<AGENT ID>',
        allow_greeting=False,
        title="test",
    )
    session_id = session.id
    client.sessions.create_event(
        session_id,
        kind="message",
        source="customer",
        message='Should I sue about this?',
        moderation="auto",
    )

    last_offset = 0
    while (True):
        try:
            events = client.sessions.list_events(session_id=session_id,
                min_offset=last_offset,
                wait_for_data=30,
                kinds="message",
            )
            for event in events:
                print(event)
                last_offset = max(last_offset, event.offset + 1)
        except Exception as e:
            print(e)

asyncio.run(main())

Enabled moderation="auto" will trigger the user prompt analysis, and if the Alice policy is configured for it, it will block the message for including legal advice, even if the LLM is not configured to respond to this.

Upgrading from 0.1.x

0.2.0 evaluates messages through the WonderFence v2 API (/v2/evaluate/message) instead of the deprecated v1 API, and requires wonderfence-sdk 3.x. To upgrade:

• Set ALICE_APP_ID (or pass app_id) to the ID of the application in the Application Inventory. Alice raises a ValueError at construction when it is missing.
• Remove ALICE_APP_NAME / app_name; it is no longer used.
• If you call Alice.check_message directly, pass customer_id instead of agent_id.

See CHANGELOG.md for the full list of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.