Skip to content
reaatech

@reaatech/guardrail-chain-config

npm v0.1.0

Loads and validates Guardrail Chain configuration from JSON, YAML, and environment variables, providing functions like `loadConfig`, `validateConfig`, and `validateConfigSafe` that deep-merge sources and validate against a Zod schema.

configconfigurationvalidationguardrail
npm →source →

@reaatech/guardrail-chain-config

npm version License: MIT CI

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

Configuration system for the Guardrail Chain framework — load guardrail chain configuration from JSON files, YAML files, and environment variables, with deep merging and Zod-based validation.

Installation

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

Feature Overview

  • Multi-source loading — load from JSON files (.json), YAML files (.yaml, .yml), and environment variables with a configurable prefix.
  • Deep merge — file config and environment overrides are deep-merged, with environment variables taking precedence.
  • Zod validation — all loaded configuration is validated against a Zod schema. Invalid config throws early with descriptive error messages.
  • Safe validation — validateConfigSafe() returns a result object instead of throwing, useful for programmatic validation at runtime.
  • Per-field environment overrides — set individual budget fields via environment variables without providing a full config.
  • Dual ESM/CJS output — works with import and require.

Quick Start

typescript
import { loadConfig, validateConfig } from '@reaatech/guardrail-chain-config';
import { GuardrailChain } from '@reaatech/guardrail-chain';
 
// Load from a YAML file with environment overrides
const config = await loadConfig({ filePath: './guardrail.config.yaml' });
 
// Or load from environment only
const envConfig = await loadConfig({ useEnv: true });
 
// Or validate a raw object
const rawConfig = validateConfig({
  budget: { maxLatencyMs: 500, maxTokens: 4000 },
});
 
const chain = new GuardrailChain(config);

API Reference

loadConfig(options?: LoadConfigOptions): Promise<LoadedConfig>

Loads configuration from file and/or environment, deep-merges the results, and returns a validated LoadedConfig.

typescript
const config = await loadConfig({
  filePath: './guardrail.yaml',
  useEnv: true,
  envPrefix: 'GUARDRAIL_CHAIN',
});

loadConfigFromFile(filePath: string): Promise<LoadedConfig>

Loads and validates configuration from a JSON or YAML file. Extension determines the parser.

typescript
const config = await loadConfigFromFile('./config.json');

loadConfigFromEnv(prefix?: string): Partial<LoadedConfig>

Loads configuration from environment variables. Supports:

  • {PREFIX}_CONFIG — raw JSON string of the full config.
  • {PREFIX}_BUDGET_MAX_LATENCY_MS — max latency budget in milliseconds.
  • {PREFIX}_BUDGET_MAX_TOKENS — max token budget.
  • {PREFIX}_BUDGET_SKIP_SLOW — skip slow guardrails ("true" / "false").
typescript
import { loadConfigFromEnv } from '@reaatech/guardrail-chain-config';
 
const config = loadConfigFromEnv('GUARDRAIL_CHAIN');
// { budget: { maxLatencyMs: 500, maxTokens: 4000, skipSlowGuardrailsUnderPressure: false } }

validateConfig(config: unknown): LoadedConfig

Validates a raw configuration object against the Zod schema. Throws ZodError on failure.

typescript
import { validateConfig } from '@reaatech/guardrail-chain-config';
 
const config = validateConfig({ budget: { maxLatencyMs: 500, maxTokens: 4000 } });

validateConfigSafe(config: unknown)

Validates and returns a result object — never throws.

typescript
import { validateConfigSafe } from '@reaatech/guardrail-chain-config';
 
const result = validateConfigSafe(rawInput);
if (result.success) {
  // result.config is the validated LoadedConfig
} else {
  // result.error is the ZodError with details
}

Return Type

PropertyTypeDescription
successbooleanWhether validation passed.
configLoadedConfig | undefinedThe validated config if success is true.
errorz.ZodError | undefinedThe validation error if success is false.

LoadConfigOptions

PropertyTypeDefaultDescription
filePathstring | undefined—Path to config file (.json, .yaml, or .yml).
useEnvboolean | undefinedtrueWhether to merge with environment variables.
envPrefixstring | undefinedGUARDRAIL_CHAINPrefix for environment variable lookups.

LoadedConfig

PropertyTypeRequiredDescription
budgetBudgetConfigYesBudget constraints — maxLatencyMs, maxTokens, skipSlowGuardrailsUnderPressure.
guardrailsGuardrailConfig[]NoPer-guardrail configuration overrides.
observabilityObservabilityConfigNoToggles for observability subsystems.

Usage Patterns

Configuration file (YAML)

yaml
# guardrail.config.yaml
budget:
  maxLatencyMs: 1000
  maxTokens: 8000
  skipSlowGuardrailsUnderPressure: true
 
guardrails:
  - id: pii-redaction
    type: input
    enabled: true
    timeout: 500
    essential: true
    priority: 10
 
observability:
  logger: true
  metrics: true
typescript
import { loadConfig } from '@reaatech/guardrail-chain-config';
 
const config = await loadConfig({ filePath: 'guardrail.config.yaml' });

Configuration file (JSON)

json
{
  "budget": {
    "maxLatencyMs": 500,
    "maxTokens": 4000
  }
}
typescript
const config = await loadConfig({ filePath: './config.json', useEnv: false });

Full config from environment variable

terminal
export GUARDRAIL_CHAIN_CONFIG='{"budget":{"maxLatencyMs":111,"maxTokens":222}}'
typescript
const config = await loadConfig({ useEnv: true });
// config.budget.maxLatencyMs === 111
// config.budget.maxTokens === 222

Individual field overrides

terminal
export GUARDRAIL_CHAIN_BUDGET_MAX_LATENCY_MS=750
export GUARDRAIL_CHAIN_BUDGET_MAX_TOKENS=2000
typescript
import { loadConfigFromEnv } from '@reaatech/guardrail-chain-config';
 
const config = loadConfigFromEnv();
// config.budget.maxLatencyMs === 750
// config.budget.maxTokens === 2000

Custom environment prefix

typescript
const config = await loadConfig({ useEnv: true, envPrefix: 'MY_APP' });
// Reads MY_APP_CONFIG, MY_APP_BUDGET_MAX_LATENCY_MS, etc.

Related Packages

License

MIT

All packagesguardrail-chain overview