Guardrails SDK Reference

VermillioGuardrails Client

The VermillioGuardrails client is the primary interface for interacting with the Guardrails API.

Bases: VermillioBasePipelineClient

__init__

__init__(config: Optional[VermillioConfig] = None)

Initializes the Guardrails Client.

Parameters:

Name	Type	Description	Default
config	Optional[VermillioConfig]	An optional configuration object. If None, it attempts to load configuration from environment variables.	None

load

load(
    sources: list[GuardrailsExternalSource],
    context: Optional[str] = None,
) -> Optional[list[GuardrailsPipelineSource]]

Loads a list of sources into the guardrails pipeline. Processing occurs asynchronously.

Parameters:

Name	Type	Description	Default
sources	list[GuardrailsExternalSource]	A list of source objects to be loaded.	required
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.	None

Returns:

Type	Description
Optional[list[GuardrailsPipelineSource]]	Optional[list[GuardrailsPipelineSource]]: A list of loaded source objects if successful.

pipeline

pipeline() -> GuardrailsPipeline

Retrieves the configuration or definition of the current guardrails pipeline.

Returns:

Name	Type	Description
GuardrailsPipeline	GuardrailsPipeline	An object containing the pipeline definition.

results

results(
    id_or_source_id: str, context: Optional[str] = None
) -> Optional[GuardrailsPipelineResults]

Retrieves the analysis results for a specific source.

Parameters:

Name	Type	Description	Default
id_or_source_id	str	The unique identifier of the source to get results for.	required
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.	None

Returns:

Type	Description
Optional[GuardrailsPipelineResults]	Optional[GuardrailsPipelineResults]: An object containing IP matches and suggested revisions.

run

run(
    source: GuardrailsExternalSource,
    context: Optional[str] = None,
    timeout: float = 60,
    poll_rate: float = 1,
) -> Optional[GuardrailsPipelineSource]

Loads guardrails sources and waits (within a timeout) for the process to complete.

Parameters:

Name	Type	Description	Default
sources	list[GuardrailsExternalSource]	A list of sources to be analyzed.	required
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.	None
timeout	float	Optional maximum time in seconds to wait for the analysis.	60
poll_rate	float	Optional frequency in seconds at which to poll for updates.	1

Returns:

Type	Description
Optional[GuardrailsPipelineSource]	Optional[list[GuardrailsPipelineSource]]: The list of processed sources upon completion.

run_results

run_results(
    source: GuardrailsExternalSource,
    context: Optional[str] = None,
    timeout: float = 60,
    poll_rate: float = 1,
) -> Optional[GuardrailsPipelineResults]

Loads guardrails sources and waits (within a timeout) for completion, returning detailed analysis results.

Parameters:

Name	Type	Description	Default
source	GuardrailsExternalSource	The source to be analyzed.	required
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.	None
timeout	float	Maximum time in seconds to wait for results.	60
poll_rate	float	Frequency in seconds at which to poll for results.	1

Returns:

Type	Description
Optional[GuardrailsPipelineResults]	Optional[GuardrailsPipelineResults]: The results object containing match details, blocked topics, and suggested revisions.

source

source(
    id_or_source_id: str, context: Optional[str] = None
) -> Optional[GuardrailsPipelineSource]

Fetches details for a specific source.

Parameters:

Name	Type	Description	Default
id_or_source_id	str	The unique identifier or source ID to retrieve.	required
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.	None

Returns:

Type	Description
Optional[GuardrailsPipelineSource]	Optional[GuardrailsPipelineSource]: The source object if found.

sources

sources(
    context: Optional[str] = None,
    after_id: Optional[str] = None,
    limit: int = 10,
) -> Optional[list[GuardrailsPipelineSource]]

Lists previously loaded sources with pagination support.

Parameters:

Name	Type	Description	Default
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.	None
after_id	Optional[str]	The optional ID to start listing after for pagination.	None
limit	int	The maximum number of sources to return.	10

Returns:

Type	Description
Optional[list[GuardrailsPipelineSource]]	Optional[list[GuardrailsPipelineSource]]: A list of source objects if found.

status

status(
    context: Optional[str] = None,
) -> Optional[GuardrailsPipelineStatus]

Checks the health or operational status of the Guardrails service.

Returns:

Name	Type	Description
GuardrailsPipelineStatus	Optional[GuardrailsPipelineStatus]	An object indicating the current state of the pipeline.
context	Optional[str]	Optional context to use, uses GuardrailsPipeline.default_context if missing.

Guardrails Model Classes

These Pydantic models represent the inputs and outputs of the Guardrails service.

GuardrailsExternalSource pydantic-model

Bases: ExternalSource

Fields:

• source_id (Optional[str])
• media_id (Optional[str])
• asset_id (Optional[str])
• prompt (str)
• lyrics (Optional[str])

lyrics pydantic-field

lyrics: Optional[str] = None

Optional lyrics to include as part of the analysis.

prompt pydantic-field

prompt: str

The prompt to analyze

GuardrailsLoadRequest pydantic-model

Bases: PipelineLoadRequest

Fields:

• context (Optional[str])
• sources (list[GuardrailsExternalSource])

sources pydantic-field

sources: list[GuardrailsExternalSource]

List of source load to request to analyze.

GuardrailsMatchReason pydantic-model

Bases: BaseModel

Fields:

• highlight (Optional[list[str]])
• score (float)

highlight pydantic-field

highlight: Optional[list[str]] = None

Highlights of the parts of the prompt that matched, wrapped in {matching phrase}.

score pydantic-field

score: float

The score of the match, scoring is dependent on the type of rule that was matched.

GuardrailsPipelineResults pydantic-model

Bases: PipelineResults

Fields:

• id (str)
• status (PipelineSourceStatus)
• created_at (float)
• updated_at (Optional[float])
• source_id (Optional[str])
• source_path (Optional[str])
• prompt (str)
• lyrics (Optional[str])
• summary (Optional[GuardrailsResultsSummary])

lyrics pydantic-field

lyrics: Optional[str] = None

Optional lyrics to include as part of the analysis.

prompt pydantic-field

prompt: str

The prompt to analyze

summary pydantic-field

summary: Optional[GuardrailsResultsSummary] = None

The summary of the guardrails results, only present when status is 'Succeeded'

GuardrailsPipelineSource pydantic-model

Bases: PipelineSource

Fields:

• id (str)
• status (PipelineSourceStatus)
• created_at (float)
• updated_at (Optional[float])
• source_id (Optional[str])
• media_id (Optional[str])
• asset_id (Optional[str])
• prompt (str)
• lyrics (Optional[str])

lyrics pydantic-field

lyrics: Optional[str] = None

Optional lyrics to include as part of the analysis.

prompt pydantic-field

prompt: str

The prompt to analyze

GuardrailsPipelineStatus pydantic-model

Bases: PipelineStatus

Fields:

• pending_count (int)
• running_count (int)
• succeeded_count (int)
• errored_count (int)
• failed_count (int)
• pipeline (GuardrailsPipeline)

pipeline pydantic-field

pipeline: GuardrailsPipeline

The pipeline that this status is for.

GuardrailsResultsSummary pydantic-model

Bases: BaseModel

Fields:

• ip_profiles (list[str])
• action (GuardrailsActionType)
• reasons (list[GuardrailsSummarizeReason])
• revisions (Optional[list[str]])

action pydantic-field

action: GuardrailsActionType

Overall action derived from the reasons.

ip_profiles pydantic-field

ip_profiles: list[str]

List of ip profiles that were classified

reasons pydantic-field

reasons: list[GuardrailsSummarizeReason]

List of reasons that drive the final action.

revisions pydantic-field

revisions: Optional[list[str]] = None

List of revised prompts if any revisions were made.

GuardrailsRunRequest pydantic-model

Bases: PipelineRunRequest

Fields:

• context (Optional[str])
• source (GuardrailsExternalSource)

source pydantic-field

source: GuardrailsExternalSource

The source request to analyze and wait for.

GuardrailsSummarizeReason pydantic-model

Bases: BaseModel

Fields:

• reason (str)
• action (GuardrailsActionType)
• matching_profile (IpProfile)
• matching_rule (IpProfileRule)
• match (GuardrailsMatchReason)

action pydantic-field

action: GuardrailsActionType

The action that this reason tells us about the prompt.

match pydantic-field

match: GuardrailsMatchReason

The details for the match.

matching_profile pydantic-field

matching_profile: IpProfile

The profile that this reason matched.

matching_rule pydantic-field

matching_rule: IpProfileRule

The rule that this reason matched.

reason pydantic-field

reason: str

Friendly description of the reason.

IpProfile pydantic-model

Bases: BaseModel

Fields:

• name (str)
• display_name (Optional[str])
• aliases (list[str])
• category (IpProfileCategory)
• created_at (float)
• updated_at (Optional[float])
• summary (Optional[str])
• is_global (bool)

aliases pydantic-field

aliases: list[str] = []

A list of aliases of the IP Profile

category pydantic-field

category: IpProfileCategory = 'other'

The category this IP Profile belongs to

created_at pydantic-field

created_at: float

The epoch time in seconds of when this profile was created.

display_name pydantic-field

display_name: Optional[str] = None

The display name of the IP Profile

is_global pydantic-field

is_global: bool

Whether or not this profile is a global Vermillio managed profile.

name pydantic-field

name: str

The internal name of the IP Profile

summary pydantic-field

summary: Optional[str] = None

A summary of the IP Profile

updated_at pydantic-field

updated_at: Optional[float] = None

The last epoch time in seconds of when this profile was last updated.

IpProfileRule pydantic-model

Bases: BaseModel

Fields:

• name (str)
• display_name (Optional[str])
• match_type (GuardrailsMatchType)
• notes (Optional[str])
• created_at (float)
• updated_at (Optional[float])
• synced_at (Optional[float])

created_at pydantic-field

created_at: float

The epoch time in seconds of when this rule was created.

display_name pydantic-field

display_name: Optional[str] = None

The display name of the rule

match_type pydantic-field

match_type: GuardrailsMatchType

How this rule should be used, for matching/classification or blocking.

name pydantic-field

name: str

The name of the IP Profile Rule

notes pydantic-field

notes: Optional[str] = None

Notes containing details about this rule.

synced_at pydantic-field

synced_at: Optional[float] = None

The last epoch time in seconds of when this rule was last synced.

updated_at pydantic-field

updated_at: Optional[float] = None

The last epoch time in seconds of when this rule was last updated.