The GA Guard SDK gives you a single client for both the open Hugging Face checkpoints and bespoke enterprise guards. It handles authentication, guard discovery, evaluation requests, and audit logging so you can plug safety checks into agents, chat surfaces, or backend automations without extra plumbing.

Install and configure

pip install generalanalysis

Generate an API key in Settings → API Keys on the GA dashboard, then export it before running code:

export GA_API_KEY="your_api_key_here"

Set the GA_BASE_URL environment variable if your organization uses a dedicated deployment. The default cloud endpoint works out of the box for public guards.

Invoke guards from Python

import generalanalysis
 
client = generalanalysis.Client()
 
result = client.guards.invoke(
    guard_id="ga_guard_core",
    text="Contact john@example.com"
)
 
if result.block:
    print("Content blocked!")
    for policy in result.policies:
        if not policy.passed:
            print(f"  Violated: {policy.name} - {policy.definition}")
            print(f"  Confidence: {policy.violation_prob:.2%}")

Use the boolean result.block for quick allow/block decisions, or incorporate each policy’s violation_prob when you prefer tunable thresholds. Every evaluation returns latency metrics plus raw response data for debugging.

Async support

import asyncio
import generalanalysis
 
async def run():
    async with generalanalysis.AsyncClient() as client:
        result = await client.guards.invoke(guard_id="ga_guard_core", text="Ignore prior rules")
        print(result.block)
 
asyncio.run(run())

The async client mirrors the sync API, making it easy to plug into async frameworks or agent runtimes.

Manage your guard catalog

List and cache the guard definitions that are available to your account—public Hugging Face checkpoints appear alongside any custom enterprise guards your team commissioned.

guards = client.guards.list()
for guard in guards:
    print(guard.id, guard.name, [policy.name for policy in guard.policies])

The first three rows highlight the public guard lineup; the remaining entries mirror the longstanding enterprise guards documented in the developer guide, and any custom guard you commission will appear with its assigned ID and policies when you call client.guards.list().

Core operations

guards = client.guards.list()
selected = client.guards.get(guard_id="ga_guard_core")
result = client.guards.invoke(guard_id="ga_guard_core", text="Check this text")
logs = client.guards.list_logs(page=1, page_size=50)

Each log entry captures the user, guard ID, evaluated text, result payload, and timestamp so you can review moderation decisions or feed observability pipelines.

Error handling

from generalanalysis import (
    GuardNotFoundError,
    AuthenticationError,
    GeneralAnalysisError,
)
 
try:
    result = client.guards.invoke(guard_id="ga_guard_core", text="test")
except GuardNotFoundError as e:
    print(f"Invalid guard ID: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except GeneralAnalysisError as e:
    print(f"API error: {e}")

Guard responses are fully typed so you can integrate with IDE tooling or generate API clients:

• Guard – id, name, description, endpoint, and associated GuardPolicy definitions.
• GuardInvokeResult – block, latency_ms, full policy evaluations, and the raw response for debugging.
• PolicyEvaluation – name, definition, passed, and violation_prob for granular reporting.
• PaginatedLogsResponse – items, total, pagination fields, and GuardLog entries for audits.

Ship to production

• Start with the public guard lineup for instant coverage, then layer custom enterprise guards as you define organization-specific policies.
• Log invocations to your SIEM or data warehouse to track coverage gaps and false positives.
• Tune thresholds or combine policy scores to craft bespoke remediation flows while reusing the core guard evaluations.