align-human

Measure judge-human agreement with TPR/TNR, Cohen's kappa, and bias detection from paired JSONL labels.

809|65|Updated Jul 8, 2025
One-click install
npx skills add https://github.com/agentscope-ai/OpenJudge --skill align-human
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: align-human
Source: https://github.com/agentscope-ai/OpenJudge/tree/main/skills/eval_pipeline/03-align-human
Command: npx skills add https://github.com/agentscope-ai/OpenJudge --skill align-human

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

You have an automatic judge or grader and human-labeled data, but no rigorous way to know whether the judge agrees with humans, where it is biased, or whether it can safely replace human review in production.

Core Features & Use Cases

  • Calibration Statistics: Computes confusion matrix, TPR/TNR/F1 with bootstrap 95% confidence intervals, Cohen's kappa, Gwet's AC1, and directional bias from paired judge verdicts and human labels.
  • Bias Detection: Runs five systematic bias checks covering position bias, verbosity bias, self-enhancement, progress illusion, and label drift, plus per-stratum breakdowns to expose hidden failures on boundary cases.
  • Human-Reduction Roadmap: Produces a 4-phase transition plan (Advisory, Assisted, Auto-gate, Autonomous) gated by kappa thresholds, with disagreement clustering to diagnose root causes.
  • Use Case: You have 200 human-labeled samples and a grader you want to deploy as a CI quality gate. Run the bundled calibration script to get a calibrated/not_calibrated verdict with the exact metrics blocking deployment.

Quick Start

Run the bundled calibration script on my paired judge verdicts and human labels JSONL files and tell me whether my grader is calibrated enough to reduce human review.

Frequently Asked Questions about align-human

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I measure if my LLM judge agrees with human labels?

Pair judge verdicts with human labels by sample id, then compute TPR/TNR, Cohen's kappa, and Gwet's AC1. The bundled calibration.py script accepts paired JSONL files and prints all metrics with bootstrap 95% confidence intervals and a calibration verdict.

What kappa value means a judge can replace human review?

Kappa of 0.8 or higher indicates substantial agreement suitable for auto-gating with borderline review. Kappa between 0.6 and 0.8 supports assisted use with 20% spot-checking, while below 0.6 the judge should remain advisory only.

Why is Cohen's kappa low when judge-human agreement is high?

This is the kappa paradox caused by class imbalance, such as a 90% pass rate. Gwet's AC1 corrects for this; if kappa and AC1 differ by more than 0.15, report both and trust AC1 for imbalanced data.

Does the calibration script require OpenJudge or numpy?

No, calibration.py runs on the Python standard library alone and works with any judge producing pass/fail verdicts. Numpy is optional and only speeds up bootstrap resampling; results are identical without it.

How many human labels do I need to validate a judge?

The calibration gate requires at least 50 total labels with at least 10 per class, otherwise it returns insufficient_evidence. Per-stratum breakdowns also need 10 or more samples per stratum to be reported.

What biases should I check before trusting an LLM judge?

Check five biases: position bias from response ordering, verbosity bias favoring longer responses, self-enhancement when judge and target share a model family, progress illusion where aggregate TPR hides boundary failures, and label drift from changed system outputs.