Documentation

On this page: browser, command line, GitHub Action, what the scores mean, rules, MCP, privacy, limits.

First run in the browser

1. Open Evaluate. An example question and source text are already filled in and Demo mode is on.
2. Press Run evaluation. You get one PASS and two FAILs with reasons. Demo results are labelled because no AI model is called.
3. Open a card, click a score to read what it means, and read the suggested fixes.
4. Switch to Live, choose a provider, paste your key, list the models to compare and run again. Use a judge model from a different family than the candidate when you can.
5. Edit the rules under Guardrails, export results, and download a trustllm.yaml to run the same check in CI.

Command line

Needs Node 20 or newer. No install step: the repository ships a bundled CLI.

git clone https://github.com/Professional50coder/trustllm && cd trustllm
node dist/cli.cjs init trustllm.yaml      # writes an example config
node dist/cli.cjs run trustllm.yaml --json report.json --md report.md
echo $?                                    # 0 pass, 1 gate failed, 2 error

# live mode: keys come from the environment, never from the file
OPENAI_API_KEY=... node dist/cli.cjs run trustllm.yaml

GitHub Action

- uses: actions/checkout@v4
- uses: Professional50coder/trustllm@main
  with:
    config: trustllm.yaml
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

The job fails when the gate fails and a Markdown report is written to the job summary.

Add comment: true (and permissions: pull-requests: write on the job) to post the report on the pull request.

MCP server and agents

Agents can call the gate as a tool. Start the server with node dist/cli.cjs mcp (stdio). Tools: evaluate, list_packs, list_rule_types. A summary for agents is at /llms.txt. The server speaks a minimal subset of the protocol and has been tested at the message level, not with every client.

Packs, approvals and sharing

• Packs: on Guardrails, start from support bot, strict RAG, structured output, safety first, or warnings-only. In the CLI: init --pack support-bot.
• Approve anyway: on a failed answer, record a human override with a reason. The failure stays in the report; the gate outcome becomes “released with human approval”.
• Copy share link: the whole report is packed into the link after the #, which browsers never send to a server. Anyone with the link sees the report; do not share it for confidential content.

What the scores mean

Grounding

Of the factual statements in the answer, how many are backed by the context passage you provided. Higher is better. 100% means every statement can be traced to your source text. Needs a context passage. Without one this signal is not measured.

Unsupported claims

The share of statements the context does not support or that contradict it. This is how this tool counts likely hallucinations. Lower is better. A statement can be unsupported and still true; the point is that you cannot show it from your source. Offline demo scoring compares words and numbers only; the live judge reads meaning.

Consistency

The model answers the same question again several times. If its facts change between answers, it is probably guessing (the SelfCheckGPT idea). Higher is better. Low values flag instability even when the first answer sounds fine. Only available when the tool generates the answer and draws 2 or more samples.

Toxicity

Whether the answer contains insults, hate, harassment or threats: none, mild, clear or severe. None is the goal. The offline demo uses a short word list and misses implicit or sarcastic toxicity. The live judge is better but not perfect.

Expressed confidence

How certain the wording sounds ("definitely" versus "maybe"). It describes tone, not correctness. Not a quality score. Confident wording together with unsupported claims is the risky combination. Based on hedge and booster words only.

Overall

A convenience number mixing the signals above. The PASS/FAIL decision does not use it; it comes from your guardrail rules. Use it to sort results, not to decide releases. Weights (grounding 40, unsupported 30, consistency 30, toxicity 20, renormalised for missing signals) are not calibrated against human judgement.

Guardrail rules

Exact rules give the same answer every time. Scored rules depend on the judge, so keep them as warnings (blocking: false) until you trust them on your own data. A rule that cannot run (for example grounding without a source text) is shown as skipped and never counts as a pass.

guardrails:
  - { id: no-pii, type: no_pii }
  - { id: grounded, type: min_grounding, value: 80 }
  - { id: consistent, type: min_consistency, value: 70, blocking: false }

Privacy and keys

• Your key lives in the page's memory and is sent only with the evaluation request. It is never written to browser storage, history, exports or logs, and it disappears on reload.
• The server forwards your prompt, source text and key to the provider you chose and returns the result. It stores nothing and has no database.
• The server only connects to known provider endpoints (OpenAI, Anthropic, OpenRouter, Groq, Together, Mistral, DeepSeek). Custom endpoints are available in the CLI only.
• Rules, saved runs and preferences are kept in this browser's local storage. Clear them from History.
• Do not paste confidential text into a deployment you do not control. Run the app yourself for sensitive data.

Limits

• Grounding is relative to the source you supply, not to the truth.
• Demo scoring compares words and numbers. It misses paraphrase and implicit toxicity.
• LLM judges can be wrong, favour long answers and favour their own model family.
• The web app limits one request to 5 cases, 4 models and 60 model calls.
• Measured agreement with labelled examples and its limits are in docs/evaluation.md.