SDK & CLI reference

The whole surface, on one page. Both SDKs write the same open trail format, so trails are portable and cross-verifiable.

Python — looptail

import looptail

client = looptail.init(
    app="support-agent",       # required; trail file is .looptail/<app>.jsonl
    api_key=None,              # optional; enables hosted sync (private beta)
    trail_dir=None,            # default: LOOPTAIL_TRAIL_DIR or ./.looptail
    endpoint=None,             # hosted ingest override
    key_path=None,             # default: ~/.looptail/signing-key
)

• @looptail.trail — decorate a sync or async function; every call is recorded (name, args, result or error, duration). Exceptions re-raise.
• looptail.event(kind, body, ref=None) → str — record any loop event; kinds: observe · evaluate · issue · improve · approve · outcome.
• looptail.outcome(event_id, **signals) → str — link a signal (csat, resolved, …) back to an earlier event.
• looptail.last_event_id() → str | None — id of the most recent event.
• looptail.verify_trail(app=None, trail_dir=None) → dict — {ok, count, errors, key_changes}.

TypeScript — @looptail/sdk

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

const lt = new Looptail({
  app: 'support-agent',        // required
  apiKey: undefined,           // optional; or LOOPTAIL_API_KEY
  trailDir: undefined,         // default: LOOPTAIL_TRAIL_DIR or ./.looptail
  endpoint: undefined,         // hosted ingest override
  keyPath: undefined,          // default: ~/.looptail/signing-key
});

• lt.trail(fn) — wrap a sync or async function; returns the same signature.
• lt.event(kind, body, ref?) → string · lt.outcome(eventId, signals) → string
• lt.lastEventId — id of the most recent event, or null.
• lt.verify() → { ok, count, errors, keyChanges }
• lt.flush() → Promise<void> — drain the hosted-sync queue before exit.
• Chain primitives are exported too: verifyChain, eventHash, canonical, SigningKey, TrailStore.

CLI — @looptail/cli

npx @looptail/cli verify [--app <name>] [--trail-dir <dir>] [--since 24h] [--json]
npx @looptail/cli export [--app <name>] [--trail-dir <dir>] [--out <file.zip>]

• --app — defaults to the only trail in the directory.
• --since 30m | 24h | 30d — count events in the window. The full chain is always verified; integrity is global.
• --json — machine-readable result.
• export — writes a dated, self-verifying evidence pack: the full chain, a manifest (head hash, writer keys, SHA-256), and recipient-runnable verification instructions. Refuses to export a broken chain.
• Exit codes: 0 ok · 1 verification failed · 2 usage error.

Environment & files

Semantics that both SDKs guarantee: the local trail is written before any network call; sync is best-effort and never raises into your app; records are never edited in place.