The Pilcrow™ — Node.js / TypeScript SDK

Official Node.js SDK for The Pilcrow™ — the deterministic AI governance linter by ENTRUST AI.

Lint AI-generated text against a Protocol Contract. Get a binary RELEASE / REJECT verdict, cryptographic audit tokens, and repair guidance — deterministically, every time.

Install

npm install @entrustai/pilcrow

Requires Node.js ≥ 18 (uses native fetch — zero runtime dependencies).

Quick Start

1 — Check any text

import { PilcrowClient } from '@entrustai/pilcrow';

const client = new PilcrowClient({
  apiKey: 'pk_...',
  workspaceId: 'ws_...',
});

const result = await client.check(
  'The patient should probably take this medication.'
);

console.log(result.verdict);          // "REJECT"
console.log(result.repair_guidance);  // ["Remove hedging language (probably)..."]
console.log(result.audit_token);      // cryptographic attestation
console.log(result.score.score);      // e.g. 62

2 — Self-Healing Guardrails ✦ The Magic

Drop any async LLM callable in. The SDK calls it, lints the output, and automatically re-prompts with deterministic repair guidance until RELEASE — or throws with the last result attached.

Works with OpenAI, Anthropic, AWS Bedrock, LangChain, LlamaIndex, or any async function that takes a string and returns a string.

import { PilcrowClient, PilcrowMaxRetriesExceeded } from '@entrustai/pilcrow';
import OpenAI from 'openai';

const client = new PilcrowClient({
  apiKey: 'pk_...',
  workspaceId: 'ws_...',
});

const openai = new OpenAI();

async function myLlm(prompt: string): Promise<string> {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: prompt }],
  });
  return response.choices[0].message.content ?? '';
}

try {
  const result = await client.withGuardrails({
    llmCallable: myLlm,
    prompt: 'Write a medical discharge summary for patient Jane Doe.',
    maxRetries: 3,
  });

  console.log(result.text);        // Compliant output — guaranteed
  console.log(result.attempts);    // e.g. 2 (needed one retry)
  console.log(result.audit_token); // cryptographic attestation

} catch (err) {
  if (err instanceof PilcrowMaxRetriesExceeded) {
    console.error('Max retries exhausted:', err.lastResult.findings);
    // Route to human review queue
  }
}

With Anthropic

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();

async function claudeLlm(prompt: string): Promise<string> {
  const message = await anthropic.messages.create({
    model: 'claude-opus-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: prompt }],
  });
  const block = message.content[0];
  return block.type === 'text' ? block.text : '';
}

const result = await client.withGuardrails({
  llmCallable: claudeLlm,
  prompt: 'Summarize the quarterly earnings report.',
  maxRetries: 3,
});

API Reference

new PilcrowClient(options)

| Option | Type | Required | Default | |---|---|---|---| | apiKey | string | ✓ | — | | workspaceId | string | ✓ | — | | baseUrl | string | | https://pilcrow.entrustai.co | | timeoutMs | number | | 30000 |

client.check(text, options?): Promise<CheckResult>

Lint a string against your Protocol Contract.

interface CheckResult {
  verdict: 'RELEASE' | 'REJECT';
  score: { score: number; grade: string; violations: number; warnings: number };
  findings: Finding[];
  repair_guidance: string[];
  audit_token: string;
  protocol_version: string;
  model?: string;
}

client.withGuardrails(options): Promise<GuardrailsResult>

Auto-retry middleware.

interface WithGuardrailsOptions {
  llmCallable: (prompt: string) => Promise<string>;
  prompt: string;
  maxRetries?: number;  // default: 3
  protocolVersion?: string;
  model?: string;
}

interface GuardrailsResult {
  text: string;
  attempts: number;
  final_check: CheckResult;
  check_results: CheckResult[];
  audit_token: string;
}

Throws PilcrowMaxRetriesExceeded if RELEASE is not achieved. The exception carries .lastResult (the final CheckResult) so you can log findings or route to a human review queue.

Error Types

| Class | When | |---|---| | PilcrowError | Base class for all SDK errors | | PilcrowAuthError | Invalid API key or workspace ID (HTTP 401/403) | | PilcrowAPIError | Unexpected API error (.status, .body attached) | | PilcrowContractError | Unexpected response shape from API | | PilcrowMaxRetriesExceeded | withGuardrails() exhausted retries (.lastResult attached) |

Get an API Key

Visit entrustai.co to get your API key and workspace ID.

© 2026 ENTRUST AI. The Pilcrow is a trademark of ENTRUST AI.