HallucinationGuard

HallucinationGuard is a Go SDK for validating and enforcing guardrails on LLM tool calls. It provides schema validation, policy enforcement, and extensibility for production-grade AI integrations.

⚠️ Experimental Notice

This package is currently experimental and still under active development.

We welcome your feedback and encourage you to report issues or suggest improvements.

Features

• Schema Validation: Structured validation of tool calls against JSON schemas
• Context-Aware Policies: Role-based, time-based, and session-based policy enforcement
• Conditional Logic: Complex conditional expressions for advanced policy rules
• Policy Priority: Hierarchical policy system with priority-based rule resolution
• Auto-Correction: Automatic tool name correction for common typos
• Thread-Safe: Safe for concurrent use in production environments
• Extensible: Custom schema loaders and policy engines

Installation

sh go get github.com/SafellmHub/hguard-go

Usage Example

Add HallucinationGuard to your agent with context-aware policies:

```go import ( "context" "log" "github.com/SafellmHub/hguard-go/pkg/hallucinationguard" )

type HGuardAgent struct { guard *hallucinationguard.Guard }

func NewHGuardAgent(schemaPath, policyPath string) *HGuardAgent { ctx := context.Background() guard := hallucinationguard.New() if err := guard.LoadSchemasFromFile(ctx, schemaPath); err != nil { log.Fatalf("Schema load error: %v", err) } if err := guard.LoadPoliciesFromFile(ctx, policyPath); err != nil { log.Fatalf("Policy load error: %v", err) } return &HGuardAgent{guard: guard} }

func (a *HGuardAgent) ValidateToolCall(ctx context.Context, toolCall hallucinationguard.ToolCall) hallucinationguard.ValidationResult { return a.guard.ValidateToolCall(ctx, toolCall) } ```

Context-Aware Policies

HallucinationGuard supports rich context-aware policies:

```yaml policies: # Role-based access control - toolname: admintool type: REJECT condition: "user.role != 'admin'" reason: "Only administrators can use this tool" priority: 10

# Parameter-based restrictions - toolname: transfermoney type: ALLOW condition: "user.role == 'admin' && params.amount < 1000" reason: "Small transfers allowed for admins" priority: 15

# Time-based restrictions - toolname: maintenancetool type: REJECT condition: "time.hour < 9 || time.hour > 17" reason: "Maintenance tools only available during business hours" priority: 5

# Session-based restrictions - toolname: sensitiveoperation type: REJECT condition: "'sensitiveoperation' in session.previouscalls" reason: "Operation already performed in this session" priority: 8 ```

Usage with Context

```go toolCall := hallucinationguard.ToolCall{ Name: "transfermoney", Parameters: map[string]interface{}{ "amount": 500, }, Context: &hallucinationguard.CallContext{ UserRole: "admin", UserID: "user123", SessionID: "session456", PreviousCalls: []string{"getbalance"}, UserPermissions: []string{"financialaccess"}, TimeOfDay: 14, // 2 PM Metadata: map[string]interface{}{ "subscriptiontier": "premium", }, }, }

result := guard.ValidateToolCall(ctx, toolCall) ```

Configuration

You can customize the Guard with functional options:

go guard := hallucinationguard.New( hallucinationguard.WithSchemaLoader(myCustomLoader), hallucinationguard.WithPolicyEngine(myCustomPolicyEngine), )

ValidationResult

The ValidationResult struct provides detailed information:

• ExecutionAllowed (bool): Whether the tool call is allowed.
• Error (string): Error message if validation failed.
• PolicyAction (string): Action taken by policy (ALLOW, REJECT, REWRITE, etc.).
• SuggestedCorrection (*ToolCall): Suggestion for correction if available.
• ToolCallID (string): ID of the validated tool call.
• Status (string): Status of the validation (approved, rejected, rewritten).
• Confidence (float64): Confidence score for the validation decision.

Policy Types

HallucinationGuard supports multiple policy types:

• ALLOW: Allow the tool call
• REJECT: Reject the tool call
• REWRITE: Auto-correct tool name to target
• LOG: Allow but log the call
• CONTEXT_REJECT: Reject based on context conditions

Thread Safety

The Guard is safe for concurrent use.

Extensibility

You can provide your own schema loader or policy engine by implementing the respective interfaces and passing them as options.

More

• Agent Scaffold: See the scaffold/ directory for a full agent scaffold and usage examples.
• Web Demo: See the webapp/ directory for a web demo and UI. Each has its own README for details.

License

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

Community

• Discord - Join our community
• GitHub Issues - Report bugs or request features
• [Contributing Guide] - Help improve HallucinationGuard. Create an issue and raise a PR!