Das TypeScript-SDK (sdk/typescript, Paketname @ledger/sdk) ist die Referenzimplementierung — vollständige Parität, einschließlich Auto-Instrumentierung für Anthropic- und OpenAI-Clients.
Noch nicht auf npm veröffentlicht. Binden Sie sdk/typescript vorerst als Vendor-Verzeichnis in Ihr Projekt ein — kopieren Sie das Verzeichnis hinein oder referenzieren Sie es als lokale/git-Abhängigkeit:
npm install <path-to-repo>/sdk/typescript
import { init } from "@ledger/sdk";
const ledger = init({
endpoint: process.env.LEDGER_ENDPOINT ?? "http://127.0.0.1:4010",
ingestKey: process.env.LEDGER_INGEST_KEY ?? "",
agentId: "urn:agent:research-assistant",
onError: (e) => console.error("[ledger]", e),
});
const t0 = new Date();
// ... die Arbeit erledigen ...
const t1 = new Date();
ledger.record({
action_type: "llm_call",
provider: "anthropic",
model: "claude-fable-5",
started_at: t0,
ended_at: t1,
status: "success",
usage: { tokens_in: 420, tokens_out: 180 },
payloads: [
{ kind: "prompt", content: "Summarize the policy for the client memo." },
{ kind: "response", content: "The policy provides that…" },
],
trigger: { type: "human", subject: "person@example.com" },
});
await ledger.flush();
await ledger.shutdown();
shutdown() führt einen Best-Effort-Abschluss-Flush mit einer harten Deadline durch (Standard 2 s) — rufen Sie es vor dem Prozessende auf, damit gepufferte Events nicht verloren gehen.
Für Anthropic oder OpenAI können Sie manuelle record()-Aufrufe ganz überspringen — wickeln Sie den Client einmal ein, und jeder folgende Aufruf wird automatisch erfasst, einschließlich Streaming:
import { init } from "@ledger/sdk";
import Anthropic from "@anthropic-ai/sdk";
const ledger = init({
endpoint: process.env.LEDGER_ENDPOINT ?? "http://127.0.0.1:4010",
ingestKey: process.env.LEDGER_INGEST_KEY ?? "",
agentId: "urn:agent:research-assistant",
});
ledger.setTrigger({ type: "human", subject: "person@example.com" });
const anthropic = ledger.instrumentAnthropic(new Anthropic());
// ab hier unveränderter Anwendungscode — keine Ledger-Referenzen nötig
const res = await anthropic.messages.create({
model: "claude-fable-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Draft the client memo." }],
});
instrumentOpenAI(client) funktioniert genauso für OpenAIs Client. Beide sind duck-typed Wrapper — keine Provider-SDK-Abhängigkeiten innerhalb von @ledger/sdk selbst.
const { spanId } = ledger.record({ action_type: "search", /* ... */ });
ledger.within(spanId, async () => {
// alles, was hier erfasst wird, setzt parent_ref standardmäßig auf spanId
const anthropic = ledger.instrumentAnthropic(client);
await anthropic.messages.create(/* ... */);
});
Übergeben Sie parentRef explizit bei einem record()-Aufruf, um den ambienten Parent zu überschreiben.
const { blob_id } = await ledger.uploadBlob(fileBuffer, "application/pdf");
ledger.record({
action_type: "data_read",
payloads: [{ kind: "artifact", blob_ref: blob_id }],
// ...
});
Wenn Sie bereits eine OTel-Pipeline betreiben, binden Sie den Ledger als Exporter oder Span-Prozessor ein, statt manuell zu instrumentieren:
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
provider.addSpanProcessor(ledger.otelSpanProcessor());
// oder: new BatchSpanProcessor(ledger.otelExporter())
Jede gen_ai.*-Span wird zu einem Ledger-Event; andere Spans laufen unverändert durch.