Documentation

Quick Start Guide

Get perfecX G-Rails up and running in your ML pipeline in under 5 minutes.

Prerequisites

Python 3.8+ or Node.js 16+
An existing ML model or AI application
A perfecX G-Rails API key (sign up at perfecxion.ai)
Basic understanding of AI safety and guardrails

Step 1: Install the SDK

Python

pip install perfecxion-g-rails

Node.js

npm install @perfecxion/g-rails

Step 2: Initialize perfecX G-Rails

Python Example

from perfecxion_g_rails import GRailsClient
from perfecxion_g_rails.guardrails import (
    ToxicityGuardrail,
    BiasGuardrail,
    HallucinationGuardrail,
    PIIGuardrail
)

# Initialize G-Rails client
grails = GRailsClient(
    api_key="your-api-key",
    environment="production"
)

# Configure guardrails for your use case
guardrails = grails.create_guardrail_set(
    name="production_safety",
    guardrails=[
        ToxicityGuardrail(threshold=0.7, action="block"),
        BiasGuardrail(
            protected_attributes=["gender", "race", "age"],
            max_disparity=0.05,
            action="warn"
        ),
        HallucinationGuardrail(
            fact_check=True,
            confidence_threshold=0.8,
            action="flag"
        ),
        PIIGuardrail(
            detect_types=["email", "phone", "ssn"],
            action="redact"
        )
    ]
)

Node.js Example

import { GRailsClient, Guardrails } from '@perfecxion/g-rails';

// Initialize G-Rails client
const grails = new GRailsClient({
    apiKey: 'your-api-key',
    environment: 'production'
});

// Configure guardrails
const guardrails = await grails.createGuardrailSet({
    name: 'production_safety',
    guardrails: [
        new Guardrails.ToxicityGuardrail({
            threshold: 0.7,
            action: 'block'
        }),
        new Guardrails.BiasGuardrail({
            protectedAttributes: ['gender', 'race', 'age'],
            maxDisparity: 0.05,
            action: 'warn'
        }),
        new Guardrails.HallucinationGuardrail({
            factCheck: true,
            confidenceThreshold: 0.8,
            action: 'flag'
        }),
        new Guardrails.PIIGuardrail({
            detectTypes: ['email', 'phone', 'ssn'],
            action: 'redact'
        })
    ]
});

Step 3: Integrate with Your AI Model

# Wrap your model with G-Rails protection
class SafeAIModel:
    def __init__(self, base_model, guardrails):
        self.model = base_model
        self.guardrails = guardrails
    
    def predict(self, input_text):
        # Pre-processing guardrails
        pre_check = self.guardrails.check_input(input_text)
        
        if pre_check.action == "block":
            return {
                "error": "Input blocked by safety guardrails",
                "reason": pre_check.violations
            }
        
        # Apply input modifications (e.g., PII redaction)
        safe_input = pre_check.modified_input or input_text
        
        # Get model prediction
        raw_output = self.model.predict(safe_input)
        
        # Post-processing guardrails
        post_check = self.guardrails.check_output(
            input=safe_input,
            output=raw_output
        )
        
        if post_check.action == "block":
            return {
                "error": "Output blocked by safety guardrails",
                "reason": post_check.violations
            }
        
        # Return safe output with guardrail metadata
        return {
            "output": post_check.modified_output or raw_output,
            "guardrail_report": {
                "checks_performed": post_check.checks,
                "modifications": post_check.modifications,
                "warnings": post_check.warnings
            }
        }

# Use the safe model
safe_model = SafeAIModel(your_existing_model, guardrails)
result = safe_model.predict("User input text here")

Step 4: Monitor Guardrail Performance

Track how your guardrails are performing and their impact on your model:

# Enable performance monitoring
grails.enable_monitoring({
    "track_latency": True,
    "track_violations": True,
    "track_modifications": True,
    "export_metrics": True
})

# Get real-time metrics
metrics = grails.get_metrics(
    guardrail_set_id=guardrails.id,
    time_range="last_hour"
)

print(f"Total requests: {metrics.total_requests}")
print(f"Blocked requests: {metrics.blocked_count} ({metrics.block_rate:.2%})")
print(f"Average latency: {metrics.avg_latency_ms}ms")
print(f"Most common violations: {metrics.top_violations}")

# Performance impact analysis
impact = grails.analyze_performance_impact(
    guardrail_set_id=guardrails.id,
    baseline_model_id="original_model"
)

print(f"Latency increase: {impact.latency_increase:.2%}")
print(f"Throughput impact: {impact.throughput_decrease:.2%}")
print(f"Safety improvement: {impact.safety_score_increase:.2%}")

Real-Time Dashboard

Monitor guardrail triggers and violations

Performance Metrics

Track latency and throughput impact

Violation Analytics

Understand patterns in safety violations

Custom Alerts

Set thresholds and get notifications

Step 5: Optimize Your Guardrails

# Use G-Rails optimization recommendations
recommendations = grails.get_optimization_recommendations(
    guardrail_set_id=guardrails.id,
    optimization_goals={
        "minimize_latency": 0.4,
        "maximize_safety": 0.6
    }
)

# Apply recommended optimizations
for rec in recommendations:
    print(f"Recommendation: {rec.description}")
    print(f"Expected improvement: {rec.expected_improvement}")
    
    if rec.auto_applicable:
        grails.apply_optimization(rec.id)

# A/B test different guardrail configurations
ab_test = grails.create_ab_test(
    name="toxicity_threshold_test",
    variants=[
        {"name": "strict", "config": {"toxicity_threshold": 0.6}},
        {"name": "balanced", "config": {"toxicity_threshold": 0.7}},
        {"name": "lenient", "config": {"toxicity_threshold": 0.8}}
    ],
    metrics=["block_rate", "user_satisfaction", "safety_score"],
    duration_hours=24
)

Common Integration Patterns

LangChain Integration

from langchain.chains import LLMChain
from perfecxion_g_rails import LangChainGuardrail

# Create guardrail-protected chain
protected_chain = LangChainGuardrail(
    chain=your_langchain,
    guardrails=guardrails,
    on_violation="return_safe_response"
)

# Use as normal LangChain
result = protected_chain.run("Tell me about AI safety")

OpenAI Integration

import openai
from perfecxion_g_rails import OpenAIGuardrail

# Wrap OpenAI client
safe_openai = OpenAIGuardrail(
    client=openai,
    guardrails=guardrails
)

# Use with automatic protection
response = safe_openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Next Steps

Read the full installation guide Explore the API reference View advanced guardrail configurations

Need Help?

Our team is here to help you implement effective AI safety guardrails.

Contact Support Browse Documentation