@entrustai/pilcrow 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ENTRUST AI (entrustai.co)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# The Pilcrow™ — Node.js / TypeScript SDK
+
+Official Node.js SDK for [The Pilcrow™](https://entrustai.co) — 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
+
+```bash
+npm install @entrustai/pilcrow
+```
+
+**Requires Node.js ≥ 18** (uses native `fetch` — zero runtime dependencies).
+
+## Quick Start
+
+### 1 — Check any text
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+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. 
+
+```typescript
+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](https://entrustai.co) to get your API key and workspace ID.
+
+---
+
+© 2026 ENTRUST AI. The Pilcrow is a trademark of ENTRUST AI.

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import type { PilcrowClientOptions, CheckOptions, CheckResult, GuardrailsResult, WithGuardrailsOptions } from "./types.js";
+export declare class PilcrowClient {
+    private readonly apiKey;
+    private readonly workspaceId;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(options: PilcrowClientOptions);
+    /**
+     * Lint a piece of AI-generated text against your Protocol Contract.
+     * Returns a CheckResult with verdict (RELEASE | REJECT), findings,
+     * repair guidance, and a cryptographic audit token.
+     *
+     * @example
+     * const result = await client.check("The patient should probably take this.");
+     * console.log(result.verdict);          // "REJECT"
+     * console.log(result.repair_guidance);  // ["Remove hedging language..."]
+     */
+    check(text: string, options?: CheckOptions): Promise<CheckResult>;
+    /**
+     * Auto-retry middleware. Calls your LLM, lints the output, and automatically
+     * re-prompts with deterministic repair guidance until RELEASE or maxRetries
+     * is exhausted.
+     *
+     * Works with any async function that accepts a string and returns a string:
+     * OpenAI, Anthropic, AWS Bedrock, LangChain, LlamaIndex, custom callables.
+     *
+     * @throws {PilcrowMaxRetriesExceeded} if RELEASE is not achieved.
+     *   Inspect error.lastResult to log or route to human review.
+     *
+     * @example
+     * 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
+     * console.log(result.audit_token); // Cryptographic attestation
+     */
+    withGuardrails(options: WithGuardrailsOptions): Promise<GuardrailsResult>;
+    private _buildRepairPrompt;
+    private _post;
+    private _parseCheckResult;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAMpB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,oBAAoB;IAYzC;;;;;;;;;OASG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAc3E;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA8C/E,OAAO,CAAC,kBAAkB;YAkBZ,KAAK;IAoCnB,OAAO,CAAC,iBAAiB;CAyC1B"}

package/dist/client.js

@@ -0,0 +1,182 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// The Pilcrow™ Node.js SDK — PilcrowClient
+// © 2026 ENTRUST AI (entrustai.co). All rights reserved.
+// ─────────────────────────────────────────────────────────────────────────────
+import { PilcrowAuthError, PilcrowAPIError, PilcrowContractError, PilcrowMaxRetriesExceeded, } from "./exceptions.js";
+const DEFAULT_BASE_URL = "https://pilcrow.entrustai.co";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 3;
+export class PilcrowClient {
+    apiKey;
+    workspaceId;
+    baseUrl;
+    timeoutMs;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new PilcrowAuthError("apiKey is required.");
+        if (!options.workspaceId)
+            throw new PilcrowAuthError("workspaceId is required.");
+        this.apiKey = options.apiKey;
+        this.workspaceId = options.workspaceId;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    // ─── Low-level: check() ──────────────────────────────────────────────────
+    /**
+     * Lint a piece of AI-generated text against your Protocol Contract.
+     * Returns a CheckResult with verdict (RELEASE | REJECT), findings,
+     * repair guidance, and a cryptographic audit token.
+     *
+     * @example
+     * const result = await client.check("The patient should probably take this.");
+     * console.log(result.verdict);          // "REJECT"
+     * console.log(result.repair_guidance);  // ["Remove hedging language..."]
+     */
+    async check(text, options = {}) {
+        const payload = {
+            text,
+            workspaceId: this.workspaceId,
+            ...(options.protocolVersion && { protocolVersion: options.protocolVersion }),
+            ...(options.model && { model: options.model }),
+        };
+        const data = await this._post("/pilcrow/check", payload);
+        return this._parseCheckResult(data);
+    }
+    // ─── High-level: withGuardrails() ────────────────────────────────────────
+    /**
+     * Auto-retry middleware. Calls your LLM, lints the output, and automatically
+     * re-prompts with deterministic repair guidance until RELEASE or maxRetries
+     * is exhausted.
+     *
+     * Works with any async function that accepts a string and returns a string:
+     * OpenAI, Anthropic, AWS Bedrock, LangChain, LlamaIndex, custom callables.
+     *
+     * @throws {PilcrowMaxRetriesExceeded} if RELEASE is not achieved.
+     *   Inspect error.lastResult to log or route to human review.
+     *
+     * @example
+     * 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
+     * console.log(result.audit_token); // Cryptographic attestation
+     */
+    async withGuardrails(options) {
+        const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const checkOptions = {
+            protocolVersion: options.protocolVersion,
+            model: options.model,
+        };
+        const checkResults = [];
+        let currentPrompt = options.prompt;
+        let lastText = "";
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            // 1. Call the LLM
+            lastText = await options.llmCallable(currentPrompt);
+            // 2. Lint the output
+            const result = await this.check(lastText, checkOptions);
+            checkResults.push(result);
+            // 3. RELEASE — we're done
+            if (result.verdict === "RELEASE") {
+                return {
+                    text: lastText,
+                    attempts: attempt,
+                    final_check: result,
+                    check_results: checkResults,
+                    audit_token: result.audit_token,
+                };
+            }
+            // 4. REJECT — build a context-aware repair prompt for the next attempt
+            if (attempt < maxRetries) {
+                currentPrompt = this._buildRepairPrompt(options.prompt, lastText, result.repair_guidance);
+            }
+        }
+        // All retries exhausted — throw with last result attached
+        throw new PilcrowMaxRetriesExceeded(maxRetries, checkResults[checkResults.length - 1]);
+    }
+    // ─── Internal helpers ────────────────────────────────────────────────────
+    _buildRepairPrompt(originalPrompt, rejectedDraft, repairGuidance) {
+        const guidanceList = repairGuidance
+            .map((g, i) => `${i + 1}. ${g}`)
+            .join("\n");
+        return (`ORIGINAL INSTRUCTIONS\n${originalPrompt}\n\n` +
+            `--- YOUR PREVIOUS DRAFT ---\n${rejectedDraft}\n\n` +
+            `COMPLIANCE CORRECTIONS REQUIRED\n` +
+            `Your previous draft was rejected by the compliance linter. ` +
+            `Rewrite it addressing every item below:\n${guidanceList}`);
+    }
+    async _post(path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "x-api-key": this.apiKey,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new PilcrowAPIError(0, `Network error: ${msg}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status === 401 || response.status === 403) {
+            throw new PilcrowAuthError("Invalid API key or workspace ID.");
+        }
+        const data = await response.json().catch(() => null);
+        if (!response.ok) {
+            throw new PilcrowAPIError(response.status, data);
+        }
+        return data;
+    }
+    _parseCheckResult(data) {
+        if (typeof data !== "object" || data === null) {
+            throw new PilcrowContractError("Unexpected API response shape.");
+        }
+        const d = data;
+        if (!d.gate || !d.score || !d.findings) {
+            throw new PilcrowContractError("Missing required fields in API response.");
+        }
+        const gate = d.gate;
+        const score = d.score;
+        const findings = d.findings.map((f) => {
+            const fi = f;
+            return {
+                rule: String(fi.rule ?? ""),
+                message: String(fi.message ?? ""),
+                severity: (fi.severity ?? "info"),
+                weight: Number(fi.weight ?? 0),
+            };
+        });
+        const repairGuidance = Array.isArray(d.repair_guidance)
+            ? d.repair_guidance.map(String)
+            : (gate.reasons ?? []).map(String);
+        return {
+            verdict: String(gate.status ?? "REJECT"),
+            score: {
+                score: Number(score.score ?? 0),
+                grade: String(score.grade ?? ""),
+                violations: Number(score.violations ?? 0),
+                warnings: Number(score.warnings ?? 0),
+            },
+            findings,
+            repair_guidance: repairGuidance,
+            audit_token: String(d.audit_token ?? d.auditToken ?? ""),
+            protocol_version: String(d.protocolVersion ?? d.protocol_version ?? ""),
+            model: d.model ? String(d.model) : undefined,
+            meta: typeof d.meta === "object" ? d.meta : undefined,
+        };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,2CAA2C;AAC3C,yDAAyD;AACzD,gFAAgF;AAEhF,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAUzB,MAAM,gBAAgB,GAAG,8BAA8B,CAAC;AACxD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAE9B,MAAM,OAAO,aAAa;IACP,MAAM,CAAS;IACf,WAAW,CAAS;IACpB,OAAO,CAAS;IAChB,SAAS,CAAS;IAEnC,YAAY,OAA6B;QACvC,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,MAAM,IAAI,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;QACvE,IAAI,CAAC,OAAO,CAAC,WAAW;YAAE,MAAM,IAAI,gBAAgB,CAAC,0BAA0B,CAAC,CAAC;QAEjF,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC3D,CAAC;IAED,4EAA4E;IAE5E;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,UAAwB,EAAE;QAClD,MAAM,OAAO,GAAG;YACd,IAAI;YACJ,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,GAAG,CAAC,OAAO,CAAC,eAAe,IAAI,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC;YAC5E,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;SAC/C,CAAC;QAEF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;QACzD,OAAO,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,4EAA4E;IAE5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,cAAc,CAAC,OAA8B;QACjD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;QAC7D,MAAM,YAAY,GAAiB;YACjC,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC;QAEF,MAAM,YAAY,GAAkB,EAAE,CAAC;QACvC,IAAI,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;QACnC,IAAI,QAAQ,GAAG,EAAE,CAAC;QAElB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YACvD,kBAAkB;YAClB,QAAQ,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;YAEpD,qBAAqB;YACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;YACxD,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAE1B,0BAA0B;YAC1B,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBACjC,OAAO;oBACL,IAAI,EAAE,QAAQ;oBACd,QAAQ,EAAE,OAAO;oBACjB,WAAW,EAAE,MAAM;oBACnB,aAAa,EAAE,YAAY;oBAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;iBAChC,CAAC;YACJ,CAAC;YAED,uEAAuE;YACvE,IAAI,OAAO,GAAG,UAAU,EAAE,CAAC;gBACzB,aAAa,GAAG,IAAI,CAAC,kBAAkB,CACrC,OAAO,CAAC,MAAM,EACd,QAAQ,EACR,MAAM,CAAC,eAAe,CACvB,CAAC;YACJ,CAAC;QACH,CAAC;QAED,0DAA0D;QAC1D,MAAM,IAAI,yBAAyB,CAAC,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;IAED,4EAA4E;IAEpE,kBAAkB,CACxB,cAAsB,EACtB,aAAqB,EACrB,cAAwB;QAExB,MAAM,YAAY,GAAG,cAAc;aAChC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;aAC/B,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,OAAO,CACL,0BAA0B,cAAc,MAAM;YAC9C,gCAAgC,aAAa,MAAM;YACnD,mCAAmC;YACnC,6DAA6D;YAC7D,4CAA4C,YAAY,EAAE,CAC3D,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,IAAa;QAC7C,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAEnE,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC1B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,WAAW,EAAE,IAAI,CAAC,MAAM;iBACzB;gBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAY,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7D,MAAM,IAAI,eAAe,CAAC,CAAC,EAAE,kBAAkB,GAAG,EAAE,CAAC,CAAC;QACxD,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvD,MAAM,IAAI,gBAAgB,CAAC,kCAAkC,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;QAErD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnD,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,iBAAiB,CAAC,IAAa;QACrC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAC9C,MAAM,IAAI,oBAAoB,CAAC,gCAAgC,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;YACvC,MAAM,IAAI,oBAAoB,CAAC,0CAA0C,CAAC,CAAC;QAC7E,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,CAAC,IAA+B,CAAC;QAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAgC,CAAC;QACjD,MAAM,QAAQ,GAAI,CAAC,CAAC,QAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACnD,MAAM,EAAE,GAAG,CAA4B,CAAC;YACxC,OAAO;gBACL,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC;gBAC3B,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,IAAI,EAAE,CAAC;gBACjC,QAAQ,EAAE,CAAC,EAAE,CAAC,QAAQ,IAAI,MAAM,CAAqC;gBACrE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,CAAC;aAC/B,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,cAAc,GAAa,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YAC/D,CAAC,CAAE,CAAC,CAAC,eAA6B,CAAC,GAAG,CAAC,MAAM,CAAC;YAC9C,CAAC,CAAC,CAAC,IAAI,CAAC,OAAoB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAElD,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAyB;YAChE,KAAK,EAAE;gBACL,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;gBAC/B,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC;gBAChC,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;gBACzC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;aACtC;YACD,QAAQ;YACR,eAAe,EAAE,cAAc;YAC/B,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC;YACxD,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAC;YACvE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS;YAC5C,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAC,CAAC,IAAgC,CAAC,CAAC,CAAC,SAAS;SACnF,CAAC;IACJ,CAAC;CACF"}

package/dist/exceptions.d.ts

@@ -0,0 +1,29 @@
+import type { CheckResult } from "./types.js";
+/** Base error for all Pilcrow SDK errors. */
+export declare class PilcrowError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the API key or workspace ID is rejected (HTTP 401 / 403). */
+export declare class PilcrowAuthError extends PilcrowError {
+    constructor(message?: string);
+}
+/** Thrown when the API returns an unexpected error response. */
+export declare class PilcrowAPIError extends PilcrowError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+/** Thrown when the contract shape returned by the API is unexpected. */
+export declare class PilcrowContractError extends PilcrowError {
+    constructor(message: string);
+}
+/**
+ * Thrown by withGuardrails() when max retries are exhausted without a RELEASE.
+ * Inspect `lastResult` to log findings, route to human review, or alert.
+ */
+export declare class PilcrowMaxRetriesExceeded extends PilcrowError {
+    readonly lastResult: CheckResult;
+    readonly attempts: number;
+    constructor(attempts: number, lastResult: CheckResult);
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,6CAA6C;AAC7C,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,SAAqC;CAIzD;AAED,gEAAgE;AAChE,qBAAa,eAAgB,SAAQ,YAAY;IAC/C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,IAAI,EAAE,OAAO,CAAC;gBAElB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM1C;AAED,wEAAwE;AACxE,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,YAAY;IACzD,SAAgB,UAAU,EAAE,WAAW,CAAC;IACxC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW;CAStD"}

package/dist/exceptions.js

@@ -0,0 +1,52 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// The Pilcrow™ Node.js SDK — Exceptions
+// © 2026 ENTRUST AI (entrustai.co). All rights reserved.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Base error for all Pilcrow SDK errors. */
+export class PilcrowError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PilcrowError";
+    }
+}
+/** Thrown when the API key or workspace ID is rejected (HTTP 401 / 403). */
+export class PilcrowAuthError extends PilcrowError {
+    constructor(message = "Invalid API key or workspace ID.") {
+        super(message);
+        this.name = "PilcrowAuthError";
+    }
+}
+/** Thrown when the API returns an unexpected error response. */
+export class PilcrowAPIError extends PilcrowError {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Pilcrow API error: HTTP ${status}`);
+        this.name = "PilcrowAPIError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Thrown when the contract shape returned by the API is unexpected. */
+export class PilcrowContractError extends PilcrowError {
+    constructor(message) {
+        super(message);
+        this.name = "PilcrowContractError";
+    }
+}
+/**
+ * Thrown by withGuardrails() when max retries are exhausted without a RELEASE.
+ * Inspect `lastResult` to log findings, route to human review, or alert.
+ */
+export class PilcrowMaxRetriesExceeded extends PilcrowError {
+    lastResult;
+    attempts;
+    constructor(attempts, lastResult) {
+        super(`Pilcrow: max retries (${attempts}) exhausted — final verdict: REJECT. ` +
+            `Inspect lastResult for findings.`);
+        this.name = "PilcrowMaxRetriesExceeded";
+        this.attempts = attempts;
+        this.lastResult = lastResult;
+    }
+}
+//# sourceMappingURL=exceptions.js.map

package/dist/exceptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.js","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,wCAAwC;AACxC,yDAAyD;AACzD,gFAAgF;AAIhF,6CAA6C;AAC7C,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,OAAO,gBAAiB,SAAQ,YAAY;IAChD,YAAY,OAAO,GAAG,kCAAkC;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,gEAAgE;AAChE,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAC/B,MAAM,CAAS;IACf,IAAI,CAAU;IAE9B,YAAY,MAAc,EAAE,IAAa;QACvC,KAAK,CAAC,2BAA2B,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,wEAAwE;AACxE,MAAM,OAAO,oBAAqB,SAAQ,YAAY;IACpD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,yBAA0B,SAAQ,YAAY;IACzC,UAAU,CAAc;IACxB,QAAQ,CAAS;IAEjC,YAAY,QAAgB,EAAE,UAAuB;QACnD,KAAK,CACH,yBAAyB,QAAQ,uCAAuC;YACxE,kCAAkC,CACnC,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PilcrowClient } from "./client.js";
+export { PilcrowError, PilcrowAuthError, PilcrowAPIError, PilcrowContractError, PilcrowMaxRetriesExceeded, } from "./exceptions.js";
+export type { Severity, Verdict, Finding, Score, CheckResult, GuardrailsResult, PilcrowClientOptions, CheckOptions, WithGuardrailsOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,KAAK,EACL,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,YAAY,EACZ,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// The Pilcrow™ Node.js SDK
+// © 2026 ENTRUST AI (entrustai.co). All rights reserved.
+// ─────────────────────────────────────────────────────────────────────────────
+export { PilcrowClient } from "./client.js";
+export { PilcrowError, PilcrowAuthError, PilcrowAPIError, PilcrowContractError, PilcrowMaxRetriesExceeded, } from "./exceptions.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,2BAA2B;AAC3B,yDAAyD;AACzD,gFAAgF;AAEhF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+export type Severity = "violation" | "warning" | "info";
+export type Verdict = "RELEASE" | "REJECT";
+/** A single rule finding returned by the linter. */
+export interface Finding {
+    rule: string;
+    message: string;
+    severity: Severity;
+    weight: number;
+}
+/** Score block returned with every lint result. */
+export interface Score {
+    score: number;
+    grade: string;
+    violations: number;
+    warnings: number;
+}
+/** The result of a single client.check() call. */
+export interface CheckResult {
+    verdict: Verdict;
+    score: Score;
+    findings: Finding[];
+    repair_guidance: string[];
+    audit_token: string;
+    protocol_version: string;
+    model?: string;
+    meta?: Record<string, unknown>;
+}
+/** The result of a client.withGuardrails() call. */
+export interface GuardrailsResult {
+    /** The final compliant text. */
+    text: string;
+    /** Number of LLM attempts made (1 = passed on first try). */
+    attempts: number;
+    /** The final CheckResult (always RELEASE). */
+    final_check: CheckResult;
+    /** All CheckResults from every attempt, in order. */
+    check_results: CheckResult[];
+    /** Audit token from the final RELEASE check. */
+    audit_token: string;
+}
+/** Options for constructing a PilcrowClient. */
+export interface PilcrowClientOptions {
+    apiKey: string;
+    workspaceId: string;
+    /** Override the API base URL. Defaults to https://pilcrow.entrustai.co */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000 (30s). */
+    timeoutMs?: number;
+}
+/** Options for client.check(). */
+export interface CheckOptions {
+    protocolVersion?: string;
+    model?: string;
+}
+/** Options for client.withGuardrails(). */
+export interface WithGuardrailsOptions {
+    /** The async LLM callable — any function that takes a string and returns a string. */
+    llmCallable: (prompt: string) => Promise<string>;
+    /** The original prompt to send to the LLM. */
+    prompt: string;
+    /** Maximum retry attempts. Defaults to 3. */
+    maxRetries?: number;
+    protocolVersion?: string;
+    model?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AACxD,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3C,oDAAoD;AACpD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,WAAW,EAAE,WAAW,CAAC;IACzB,qDAAqD;IACrD,aAAa,EAAE,WAAW,EAAE,CAAC;IAC7B,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kCAAkC;AAClC,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,qBAAqB;IACpC,sFAAsF;IACtF,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,6 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// The Pilcrow™ Node.js SDK — Type Definitions
+// © 2026 ENTRUST AI (entrustai.co). All rights reserved.
+// ─────────────────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,8CAA8C;AAC9C,yDAAyD;AACzD,gFAAgF"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@entrustai/pilcrow",
+  "version": "1.0.0",
+  "description": "Official Node.js / TypeScript SDK for The Pilcrow™ — Deterministic AI Governance Linter by ENTRUST AI.",
+  "author": "ENTRUST AI <contact@entrustai.co> (https://entrustai.co)",
+  "license": "MIT",
+  "homepage": "https://entrustai.co",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/entrustai/pilcrow-node"
+  },
+  "keywords": [
+    "pilcrow",
+    "entrust-ai",
+    "ai-governance",
+    "compliance",
+    "linter",
+    "llm",
+    "openai",
+    "anthropic",
+    "guardrails",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}