@reaatech/guardrail-chain

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

Core types, chain orchestration, budget management, and utilities for the Guardrail Chain framework. This package is the foundation for all @reaatech/guardrail-chain-* packages and provides the Guardrail interface that every guardrail implementation must satisfy.

Installation

npm install @reaatech/guardrail-chain
# or
pnpm add @reaatech/guardrail-chain

Feature Overview

• Composable guardrail pipeline — chain input and output guardrails with budget-aware scheduling, priority ordering, and short-circuit-on-failure logic.
• Budget management — track latency and token budgets, skip non-essential guardrails under pressure, and prevent budget overruns.
• Fluent builder API — construct chains declaratively with ChainBuilder, or wire them programmatically with GuardrailChain.
• Retry with exponential backoff — transparent retry for transient failures, with configurable predicates, jitter, and caps.
• Circuit breaker — protect external-service guardrails from cascading failures with CLOSED/OPEN/HALF_OPEN state tracking.
• LRU cache — TTL-aware cache for guardrail results, with configurable eviction policy.
• Exported observability getter/setter functions — setLogger, setMetrics, setTracer re-exported from @reaatech/guardrail-chain-observability for single-import convenience.
• Zero runtime dependencies beyond @reaatech/guardrail-chain-observability — lightweight and tree-shakeable.
• Dual ESM/CJS output — works with import and require.

Quick Start

import {
  GuardrailChain,
  ChainBuilder,
  setLogger,
  ConsoleLogger,
  type Guardrail,
  type GuardrailResult,
  type ChainContext,
} from '@reaatech/guardrail-chain';
 
setLogger(new ConsoleLogger());
 
const chain = new ChainBuilder()
  .withBudget({ maxLatencyMs: 500, maxTokens: 4000 })
  .build();
 
const result = await chain.execute('What is the weather today?');
console.log(result.success ? 'Passed' : 'Failed');

Exports

Core Classes

Core Types

Factory Functions

Error Classes

Utility Classes

Utility Functions

Retry Types & Constants

Cache Types & Constants

Circuit Breaker Types & Constants

Re-exports from observability

For convenience, the following are re-exported from @reaatech/guardrail-chain-observability:

Usage Patterns

Building a chain with the fluent builder

import { ChainBuilder } from '@reaatech/guardrail-chain';
import { PIIRedaction, ToxicityFilter } from '@reaatech/guardrail-chain-guardrails';
 
const chain = new ChainBuilder()
  .withBudget({ maxLatencyMs: 500, maxTokens: 4000 })
  .withGuardrail(new PIIRedaction())
  .withGuardrail(new ToxicityFilter())
  .withSlowGuardrailSkipping(true)
  .withErrorHandling({ maxRetries: 2, retryDelayMs: 200 })
  .build();

Wrapping an external-service guardrail with a circuit breaker

import { CircuitBreaker, type Guardrail, type GuardrailResult, type ChainContext } from '@reaatech/guardrail-chain';
 
const breaker = new CircuitBreaker('moderation-api', {
  failureThreshold: 5,
  resetTimeoutMs: 30_000,
});
 
class ExternalModerationGuardrail implements Guardrail<string, string> {
  readonly id = 'external-moderation';
  readonly name = 'External Moderation';
  readonly type = 'output' as const;
  enabled = true;
 
  async execute(input: string, context: ChainContext): Promise<GuardrailResult<string>> {
    return breaker.execute(async () => {
      const response = await fetch('https://api.example.com/moderate', {
        method: 'POST',
        body: JSON.stringify({ text: input }),
      });
      const data = await response.json();
      return { passed: data.flagged === false, output: data.sanitized ?? input };
    }).catch(() => {
      return { passed: true, output: input }; // fail-open
    });
  }
}

Caching guardrail results

import { LRUCache, generateCorrelationId } from '@reaatech/guardrail-chain';
 
const cache = new LRUCache<string, boolean>({ maxSize: 500, ttlMs: 300_000 });
const correlationId = generateCorrelationId();

Related Packages

• @reaatech/guardrail-chain-guardrails — built-in guardrail implementations (PII, injection, toxicity, etc.)
• @reaatech/guardrail-chain-observability — pluggable logging, metrics, and tracing interfaces
• @reaatech/guardrail-chain-config — configuration loader and Zod-based validator

License

MIT