@looptail/sdk

@looptail/sdk

Record every AI decision as a signed, append-only trail. Every loop leaves a tail.

npm install @looptail/sdk

import { Looptail } from '@looptail/sdk';

const lt = new Looptail({ app: 'support-agent' });

export const handleTicket = lt.trail(async (ticket) => {
  // ...
});

// report an outcome signal when you learn how it went
lt.outcome(lt.lastEventId!, { csat: 5 });

Every call becomes a hash-chained, Ed25519-signed loop event appended to .looptail/support-agent.jsonl. Nothing is edited in place; any modification, deletion, or reorder of past records is detectable:

npx @looptail/cli verify --app support-agent

✔ 2 loop events
✔ chain intact · signatures valid

Or in code: lt.verify().

The whole loop, in TypeScript

import { Looptail, instrumentAnthropic, loadRubric, judgeFromSpec, run, cluster } from '@looptail/sdk';
import Anthropic from '@anthropic-ai/sdk';

const lt = new Looptail({ app: 'support-agent' });

// Observe — every provider call becomes a signed observe event
const anthropic = instrumentAnthropic(new Anthropic(), lt);

// Understand — score recorded events against your rubric, cluster failures
const judge = await judgeFromSpec('anthropic:claude-opus-4-8'); // or openai:<model>
await run(loadRubric('rubrics/refund-policy.json'), lt, judge);
cluster(lt);

The whole loop — Observe, Understand, and Improve (propose / replay / canary / approve) — is at full parity with the Python SDK: same rubric prompt, judge schema, and event shapes, so a JS verdict, a Python verdict, and a hosted verdict all agree. The provider SDKs (@anthropic-ai/sdk, openai) are optional peer deps, only needed when you build a judge or proposer. From the terminal: npx @looptail/cli evals run / issues cluster / improve.

How it works

• Zero runtime dependencies — signing uses Node's built-in Ed25519.
• A signing key is created on first use at ~/.looptail/signing-key (override with LOOPTAIL_SIGNING_KEY, hex seed).
• Events follow the open trail format — spec/trail-format.md — and are verifiable by any implementation, including the Python SDK's.
• The local trail is the source of truth. With an API key (apiKey option or LOOPTAIL_API_KEY), events also sync to the hosted Tail (private beta); sync is best-effort and never blocks or crashes your app.

Read the trust model in the spec before relying on local trails as evidence: self-signed trails are tamper-evident; hosted anchoring (v0.2) makes them stronger.

Docs: looptail.ai/docs · License: Apache-2.0