How to use the ClearRun SDK

The ClearRun SDK is the @clearrun/sdk package. score and evaluate score text you already have. chat gets an answer from a model and scores it. verify looks up a past verdict. It does not score anything.

Last updated

Install and score

npm install @clearrun/sdk
import { createKernelClient } from '@clearrun/sdk';

const client = createKernelClient({
  hosted: { apiKey: process.env.CLEARRUN_API_KEY },
});

const scored = await client.score({
  responseText: 'The capital of France is Paris.',
});

console.log(scored.verdict.score, scored.verdict.verdictId);

If you leave out hosted.apiKey, the client reads CLEARRUN_API_KEY, then the key saved by clearrun login. With no key, it throws MissingApiKeyError and makes no call.

Evaluate, chat and look up

const { verdict } = await client.evaluate({
  prompt: 'Where is the Eiffel Tower?',
  responseText: 'The Eiffel Tower is in Berlin.',
});

const chat = await client.chat({ message: 'What is the capital of France?' });
console.log(chat.responseText, chat.verdict.score);

const check = await client.verify({ verdictId: verdict.verdictId });
console.log(check.verified);
  • score calls POST /api/score.
  • evaluate calls POST /api/evaluate.
  • chat calls POST /api/chat. The answer is always in responseText.
  • verify calls GET /api/verify/{verdictId}. It does not send your key.

To look up a verdict without a key, use createVerifyClient() from the SDK, clearrun verify 6e07586d-e028-43d6-bec3-0f4821b22ca0, or curl https://api.clearrun.net/api/verify/6e07586d-e028-43d6-bec3-0f4821b22ca0.

Options and errors

  • baseUrl changes the API address. timeoutMs stops slow requests.
  • API errors throw HostedApiError with status, message, and sometimes code.
  • { forceMock: true } gives local local test scores. They are not signed.

Package readme: packages/sdk/README.md.