Coralogix Guardrails

TypeScript SDK for protecting your LLM applications with content evaluation.

Coralogix Guardrails lets you evaluate prompts and LLM responses against configurable checks — PII, prompt injection, toxicity, and your own custom criteria — before they reach an LLM or your users. When a guardrail is triggered the SDK throws (or returns the results, if you prefer), and every check is emitted as an OpenTelemetry span so you can observe and audit guardrail activity in Coralogix. Use it to add a safety and compliance layer around any LLM-powered feature.

Installation

npm install @coralogix/cx-guardrails @opentelemetry/api

Note: @opentelemetry/api is a required peer dependency (the SDK creates OpenTelemetry spans), so install it alongside the SDK.

Getting Started

| Method | Use Case | Input | |--------|----------|-------| | guardPrompt() | Guard user input before LLM call | prompt | | guardResponse() | Guard LLM output after generation | response, prompt (optional) | | guard() | Full control over message history | List of messages |

Available Guardrails

| Guardrail | Description | Usage | |-----------|-------------|-------| | PII Detection | Detects personally identifiable information | pii() | | Prompt Injection | Detects attempts to manipulate LLM behavior | promptInjection() | | Toxicity | Detects toxic, harmful, or offensive content | toxicity() | | Custom | Define your own evaluation criteria | custom({ name, instructions, ... }) |

import {
  Guardrails,
  pii,
  promptInjection,
  GuardrailsTriggered,
  setupExportToCoralogix,
} from "@coralogix/cx-guardrails";

const tracing = setupExportToCoralogix({ serviceName: "my-service" });

const guardrails = new Guardrails();

async function main() {
  await guardrails.guardedSession(async () => {
    try {
      await guardrails.guardPrompt([pii(), promptInjection()], "User input here");

      const response = "...";

      await guardrails.guardResponse([pii(), promptInjection()], response);
    } catch (e) {
      if (e instanceof GuardrailsTriggered) {
        for (const v of e.triggered) {
          console.log(`Blocked: ${v.guardrailType}`);
        }
      }
    }
  });

  await tracing.shutdown();
}

main();

PII Detection

import { pii, PIICategory } from "@coralogix/cx-guardrails";

pii(); // All categories, default threshold 0.7
pii({ categories: [PIICategory.EMAIL_ADDRESS, PIICategory.PHONE_NUMBER], threshold: 0.8 });

Categories: email_address, phone_number, credit_card, iban_code, us_ssn

Prompt Injection Detection

import { promptInjection } from "@coralogix/cx-guardrails";

promptInjection(); // Default threshold 0.7
promptInjection({ threshold: 0.8 });

Toxicity Detection

import { toxicity } from "@coralogix/cx-guardrails";

toxicity(); // Default threshold 0.7
toxicity({ threshold: 0.8 });

Custom Guardrails

Define your own evaluation criteria to detect specific content patterns:

import { custom } from "@coralogix/cx-guardrails";

custom({
  name: "financial_advice_detector",
  instructions:
    "Analyze the {response} and the {prompt} for any financial advice or investment recommendations.",
  violates: "Response contains specific financial advice or investment recommendations.",
  safe: "Response provides general information without specific investment advice.",
  threshold: 0.7,
  examples: [
    {
      conversation: "User: Should I buy Tesla stock?\nAssistant: Yes, buy it now!",
      score: 1, // 1 = violates
    },
    {
      conversation:
        "User: What is a stock?\nAssistant: A stock represents ownership in a company.",
      score: 0, // 0 = safe
    },
  ],
});

Required fields:

• name: The guardrail's name
• instructions: Evaluation instructions (must contain {prompt}, {response}, or {history})
• violates: Description of what constitutes a violation
• safe: Description of what constitutes safe content

Optional fields:

• threshold: Detection threshold (default: 0.7)
• examples: List of example conversations with expected scores
• shouldIncludeSystemPrompt: Include system prompt in evaluation (default: false)
• category: "security" or "quality" (default: "quality")

Magic Words

Use placeholder tags in your instructions to reference conversation content. At least one magic word is required.

| Magic Word | Description | Replaced With | Evaluation Target | |------------|-------------|---------------|-------------------| | {prompt} | User's input | The last user message | Prompt | | {response} | Assistant's output | The last assistant response | Response | | {history} | Full conversation | All messages in the conversation | Response |

Using guard() for Full Control

import { GuardrailsTarget, pii } from "@coralogix/cx-guardrails";

const messages = [
  { role: "user", content: "Hello" },
  { role: "assistant", content: "Hi there!" },
];

await guardrails.guard([pii()], messages, GuardrailsTarget.RESPONSE);

With Tool Calls

const messages = [
  { role: "user", content: "What's the weather in Paris?" },
  {
    role: "assistant",
    content: JSON.stringify({
      tool_calls: [
        {
          id: "call_123",
          type: "function",
          function: { name: "get_weather", arguments: '{"location": "Paris"}' },
        },
      ],
    }),
  },
  { role: "tool", content: "The weather in Paris is 22C and sunny." },
  { role: "assistant", content: "The weather in Paris is 22C and sunny." },
];

await guardrails.guard([pii()], messages, GuardrailsTarget.RESPONSE);

Configuration

Environment Variables

export CX_GUARDRAILS_TOKEN="your-guardrails-api-key"
export CX_GUARDRAILS_ENDPOINT="https://your-domain.coralogix.com/api/v1/guardrails/guard"
export CX_TOKEN="your-coralogix-api-key"
export CX_ENDPOINT="https://your-domain.coralogix.com"
export CX_APPLICATION_NAME="my-app"      # Optional, default "Unknown"
export CX_SUBSYSTEM_NAME="my-subsystem"  # Optional, default "Unknown"

Client Configuration

const guardrails = new Guardrails({
  apiKey: "your-api-key",
  cxGuardrailsEndpoint: "https://your-domain.coralogix.com/api/v1/guardrails/guard",
  timeout: 2,      // Timeout in seconds (default: 10)
  maxRetries: 3,   // Retry attempts on timeout/connection errors (default: 3)
});

Testing Connectivity

Use testConnection() to verify the SDK can reach the Guardrails API — useful on startup or in a health check. It returns the API response on success and throws on failure:

const guardrails = new Guardrails();

try {
  await guardrails.testConnection();
  console.log("Guardrails API is reachable");
} catch (e) {
  console.error("Guardrails API is unreachable", e);
}

Suppress Exceptions

To return results instead of throwing GuardrailsTriggered:

export DISABLE_GUARDRAILS_TRIGGERED_EXCEPTION=true

Error Handling

import {
  GuardrailsTriggered,
  GuardrailsConfigError,
  GuardrailsAPITimeoutError,
  GuardrailsAPIConnectionError,
  GuardrailsAPIResponseError,
} from "@coralogix/cx-guardrails";

try {
  await guardrails.guardPrompt([pii()], "test");
} catch (e) {
  if (e instanceof GuardrailsTriggered) {
    for (const v of e.triggered) {
      console.log(`${v.guardrailType}`);
    }
  } else if (e instanceof GuardrailsConfigError) {
    // Invalid configuration or input (e.g. missing endpoint, invalid role)
  } else if (e instanceof GuardrailsAPITimeoutError) {
    // Request timed out (retried up to maxRetries before throwing)
  } else if (e instanceof GuardrailsAPIConnectionError) {
    // Network error (retried up to maxRetries before throwing)
  } else if (e instanceof GuardrailsAPIResponseError) {
    console.log(`HTTP ${e.statusCode}`);
  }
}

OpenTelemetry Tracing

The SDK automatically creates OpenTelemetry spans for each guardrail check. Call setupExportToCoralogix() to export spans to Coralogix:

const tracing = setupExportToCoralogix({
  serviceName: "my-llm-app",
  applicationName: "my-app",       // Falls back to CX_APPLICATION_NAME
  subsystemName: "my-subsystem",   // Falls back to CX_SUBSYSTEM_NAME
  coralogixToken: "...",           // Falls back to CX_TOKEN
  coralogixEndpoint: "...",        // Falls back to CX_ENDPOINT
  useBatchProcessor: true,         // Use BatchSpanProcessor (default: true)
});

// ... run guardrail checks ...

// Flush spans before process exit
await tracing.shutdown();

| Span Name | Kind | When | |-----------|------|------| | cx.guardrails.session | Internal | guardedSession() | | guardrails.prompt | Client | guardPrompt() / guard(..., PROMPT) | | guardrails.response | Client | guardResponse() / guard(..., RESPONSE) | | cx.guardrails.test | Client | testConnection() |

Span Attributes

• cx.application.name - Application name
• cx.subsystem.name - Subsystem name
• guardrails.triggered - Whether any guardrail was triggered
• guardrails.prompt.{n} - Evaluated prompt text
• guardrails.response.{n} - Evaluated response text
• gen_ai.{target}.guardrails.{type}.score - Guardrail score
• gen_ai.{target}.guardrails.{type}.threshold - Guardrail threshold
• gen_ai.{target}.guardrails.{type}.triggered - Whether score exceeded threshold

License

Apache 2.0 - See LICENSE for details.