output-grade

import { grade } from 'output-grade';

// Basic grading -- only the output text is required
const report = grade('The capital of France is Paris.');
console.log(report.score);    // 0.0 - 1.0 composite score
console.log(report.pass);     // true if score >= 0.7
console.log(report.summary);  // human-readable summary

// Context-aware grading with prompt, schema, and format
const report = grade('{"title":"Guide","body":"..."}', {
  prompt: 'Write a JSON guide about quantum computing',
  schema: { type: 'object', required: ['title', 'body'], properties: {
    title: { type: 'string' },
    body: { type: 'string' },
  }},
  format: 'json',
  passThreshold: 0.8,
});

console.log(report.dimensions);  // per-dimension score breakdown
console.log(report.signals);     // array of diagnostic signals

import { grade } from 'output-grade';

const report = grade(output, options);

interface GradeReport {
  score: number;              // Composite quality score, 0.0 to 1.0
  pass: boolean;              // Whether score >= passThreshold
  passThreshold: number;      // The threshold used
  dimensions: DimensionScores; // Per-dimension 0-1 scores
  signals: Signal[];          // All detected signals, ordered by severity
  summary: string;            // Human-readable summary (1-3 sentences)
  meta: GradeMeta;            // Duration, weights, detected format, etc.
}

import { createGrader } from 'output-grade';

const grader = createGrader({
  weights: { 'structural-validity': 0.30, 'content-coherence': 0.20 },
  passThreshold: 0.8,
});

const report = grader.grade(output, { prompt: 'Explain X', format: 'json' });

interface DimensionResult {
  score: number;    // 0.0 to 1.0
  signals: Signal[]; // Signals detected for this dimension
}

import { scoreStructuralValidity } from 'output-grade';

const result = scoreStructuralValidity('{"key": "value"}', 'json');
// result.score === 1.0

import { scoreTruncationRisk } from 'output-grade';

const result = scoreTruncationRisk('Here are 5 items:\n1. First\n2. Second');
// result.score < 1.0 (incomplete list detected)

import { scoreRefusalDetection } from 'output-grade';

const result = scoreRefusalDetection("I can't help with that.");
// result.score === 0.0 (full refusal)

import { scoreContentCoherence } from 'output-grade';

const result = scoreContentCoherence('This is a well-written paragraph.');
// result.score close to 1.0

import { scoreHallucinationRisk } from 'output-grade';

const result = scoreHallucinationRisk('I think probably this might be correct.');
// result.score < 1.0 (hedging detected)

import { scoreSchemaCompleteness } from 'output-grade';

const result = scoreSchemaCompleteness(
  '{"title":"Guide"}',
  { type: 'object', required: ['title', 'body'], properties: {
    title: { type: 'string' },
    body: { type: 'string' },
  }},
);
// result.score < 1.0 (missing required field "body")

import { scoreRelevance } from 'output-grade';

const result = scoreRelevance(
  'Quantum computing uses qubits...',
  'Explain quantum computing',
);
// result.score reflects keyword overlap and structural alignment

import { scoreFormatCompliance } from 'output-grade';

const result = scoreFormatCompliance('{"key":"value"}', 'json');
// result.score === 1.0

import { tokenize } from 'output-grade';

tokenize('Hello World, this is a Test.');
// ['hello', 'world', 'this', 'is', 'a', 'test']

import { splitSentences } from 'output-grade';

splitSentences('Hello world. This is great! Is it?');
// ['Hello world.', 'This is great!', 'Is it?']

import { computeNgrams } from 'output-grade';

const freq = computeNgrams(['the', 'quick', 'brown', 'fox'], 3);
// Map { 'the quick brown' => 1, 'quick brown fox' => 1 }

import { repetitionRatio } from 'output-grade';

repetitionRatio(['a', 'b', 'c', 'a', 'b', 'c'], 3);
// > 0 (repetition detected)

import { detectFormat } from 'output-grade';

detectFormat('{"key": "value"}');  // 'json'
detectFormat('# Hello\nText');     // 'markdown'
detectFormat('<root></root>');     // 'xml'
detectFormat('Plain text.');       // 'text'

import { checkBracketBalance } from 'output-grade';

checkBracketBalance('{ [ ] }');
// { curly: 0, square: 0, round: 0, angle: 0, maxDepth: 2 }

checkBracketBalance('{ [');
// { curly: 1, square: 1, round: 0, angle: 0, maxDepth: 2 }

import { lenientJsonParse } from 'output-grade';

lenientJsonParse('```json\n{"key": "value"}\n```');
// { success: true, value: { key: 'value' }, lenient: true }

lenientJsonParse('not json');
// { success: false, error: '...' }

import { extractUrls } from 'output-grade';

extractUrls('Visit https://example.com/page for info.');
// [{ url: 'https://example.com/page', start: 6, end: 31, suspicious: true, reason: 'example domain' }]

import { extractDates } from 'output-grade';

extractDates('Released 2024-01-15. Event on February 30, 2024.');
// [
//   { date: '2024-01-15', start: 9, end: 19, valid: true },
//   { date: 'February 30, 2024', start: 30, end: 47, valid: false, reason: 'impossible date' }
// ]

import { removeStopwords } from 'output-grade';

removeStopwords(['the', 'quick', 'brown', 'fox', 'is', 'a', 'test']);
// ['quick', 'brown', 'fox', 'test']

interface PatternEntry {
  pattern: RegExp;
  category: string;
  severity: 'info' | 'warning' | 'critical';
  label: string;
}

import { redistributeWeights, DEFAULT_WEIGHTS } from 'output-grade';

const weights = redistributeWeights(DEFAULT_WEIGHTS, ['schema-completeness', 'relevance']);
// schema-completeness: 0, relevance: 0, others scaled up proportionally

const report = grade(output, {
  weights: {
    'structural-validity': 0.30,
    'hallucination-risk': 0.25,
    'content-coherence': 0.20,
    'truncation-risk': 0.10,
    'refusal-detection': 0.10,
    'relevance': 0.05,
  },
});

const report = grade(output, { passThreshold: 0.85 });

const report = grade(output, {
  criticalFloors: {
    'structural-validity': { threshold: 0.3, ceiling: 0.4 },
    'refusal-detection': { threshold: 0.5, ceiling: 0.3 },
  },
});

const report = grade(output, {
  customPatterns: {
    hedging: [/\bsupposedly\b/i, /\ballegedly\b/i],
    refusal: [/\bwe do not support\b/i],
    preamble: [/^Note:\s*/i],
  },
});

const report = grade(output, {
  prompt: 'Explain the React useEffect hook',
  stopwords: ['react', 'hook', 'component'],
});

import { createGrader } from 'output-grade';

const jsonGrader = createGrader({
  weights: {
    'schema-completeness': 0.30,
    'structural-validity': 0.30,
    'content-coherence': 0.10,
    'hallucination-risk': 0.10,
    'truncation-risk': 0.10,
    'refusal-detection': 0.05,
    'relevance': 0.03,
    'format-compliance': 0.02,
  },
  passThreshold: 0.8,
});

const report = jsonGrader.grade(apiResponse, {
  schema: { type: 'object', required: ['id', 'name', 'status'] },
  format: 'json',
});

if (!report.pass) {
  console.error('Quality check failed:', report.summary);
  // retry or escalate
}

import { createGrader } from 'output-grade';

const grader = createGrader();

// Check only for refusal
const refusal = grader.detectRefusal(output);
if (refusal.score < 0.5) {
  console.warn('Model refused:', refusal.signals);
}

// Check only for truncation
const truncation = grader.detectTruncation(output);
if (truncation.score < 0.3) {
  console.warn('Output appears truncated');
}

import { grade } from 'output-grade';

function qualityGate(output: string, prompt: string): boolean {
  const report = grade(output, { prompt, passThreshold: 0.75 });

  if (!report.pass) {
    const criticals = report.signals.filter(s => s.severity === 'critical');
    console.warn(`Quality gate failed (${report.score.toFixed(2)}):`, criticals);
    return false;
  }

  return true;
}

import { createGrader } from 'output-grade';

const grader = createGrader({ passThreshold: 0.7 });
const outputs: string[] = loadOutputs();

const results = outputs.map(output => grader.grade(output));
const passRate = results.filter(r => r.pass).length / results.length;
const avgScore = results.reduce((sum, r) => sum + r.score, 0) / results.length;

console.log(`Pass rate: ${(passRate * 100).toFixed(1)}%`);
console.log(`Avg score: ${avgScore.toFixed(3)}`);

import { grade } from 'output-grade';

const report = grade(output, { prompt, format: 'json' });

// Signals are ordered: critical first, then warning, then info
for (const signal of report.signals) {
  const loc = signal.location
    ? ` [chars ${signal.location.start}-${signal.location.end}]`
    : '';
  console.log(`[${signal.severity.toUpperCase()}] ${signal.dimension}: ${signal.message}${loc}`);
}

import type {
  GradeReport,
  GradeOptions,
  GraderConfig,
  Grader,
  DimensionId,
  DimensionResult,
  DimensionScores,
  Signal,
  SignalLocation,
  Severity,
  OutputFormat,
  DetectedFormat,
  GradeMeta,
  JsonSchema,
  CustomPatterns,
  CriticalFloorConfig,
  BracketBalance,
  JsonParseResult,
  UrlLocation,
  DateLocation,
  PatternEntry,
} from 'output-grade';