@rankigi/langchain

LangChain (JS/TS) callback handler that adds RANKIGI cryptographic receipts to every LLM, tool, agent, retriever, and LangGraph node.

Compatible with @langchain/core >= 0.3 and LangGraph.

Install

npm install @rankigi/langchain @rankigi/sdk @langchain/core

Setup

First, enroll a connector passport in your RANKIGI dashboard (Agents → New, type "connector"). Copy the credentials into your environment:

RANKIGI_API_KEY=rnk_...
RANKIGI_AGENT_ID=<uuid>
RANKIGI_PASSPORT_ID=<uuid>
RANKIGI_SIGNING_KEY=<base64 ed25519 seed>

Then add the callback to your agent:

import { createRankigiCallback } from "@rankigi/langchain";
import { AgentExecutor } from "langchain/agents";

const executor = new AgentExecutor({
  agent,
  tools,
  callbacks: [createRankigiCallback({ agentTag: "checkout-service-prod" })],
});

Or pass per-invocation:

await executor.invoke(
  { input: "..." },
  { callbacks: [createRankigiCallback({ agentTag: "checkout-service-prod" })] },
);

LangGraph works the same way — pass the callback in the RunnableConfig:

await graph.invoke(state, {
  callbacks: [createRankigiCallback({ agentTag: "research-agent" })],
});

What gets a receipt

| LangChain event | RANKIGI action | |---|---| | handleLLMEnd / handleChatModelStart+End | llm_call | | handleToolEnd | tool_call | | handleAgentAction | agent_action | | handleAgentEnd | agent_finish | | handleChainStart/End (LangGraph nodes + top-level only) | chain_start / chain_end | | handleRetrieverEnd | retrieval | | any *Error callback | *_error with severity: "warn" |

What gets hashed

Prompts, completions, tool inputs, tool outputs, agent reasoning logs, retriever queries, and document contents are SHA-256-hashed locally by the SDK before any network call. Only the hashes plus safe metadata (model name, token counts, latency, run/parent IDs, LangGraph node names) reach RANKIGI.

Safety

Every callback is wrapped in try/catch. SDK or network failures are absorbed silently — the callback never throws into LangChain. The underlying SDK has a durable disk queue that absorbs RANKIGI downtime and retries on the next process boot.

Explicit credentials

If you can't use env vars, pass the credentials directly:

createRankigiCallback({
  apiKey: process.env.RANKIGI_API_KEY!,
  agentId: process.env.RANKIGI_AGENT_ID!,
  passportId: process.env.RANKIGI_PASSPORT_ID!,
  signingPrivateKey: process.env.RANKIGI_SIGNING_KEY!,
  agentTag: "checkout-service-prod",
});

Test injection

For unit tests, pass a mock client:

createRankigiCallback({
  client: { computeHashes: ..., track: async () => {} },
});

Note on method names

The JS LangChain BaseCallbackHandler dispatches by camelCase handle* method names (handleLLMEnd, handleToolEnd, etc.). The on_* snake_case names are the Python SDK convention; in JS the runtime will never call them. This handler exposes the canonical handle* names.

License

MIT