Skip to content

ClassID Usage Guide

This guide demonstrates how to use the ClassID → Model Pool mapping functionality in verdikta-common.

Overview

The ClassMap system provides a curated mapping from ClassIDs to AI model pools, enabling:

  • Deterministic validation of Query Manifests with automatic truncation
  • Strict model pinning to ensure reproducible results
  • Resource limits to prevent abuse and ensure fair usage
  • Provider abstraction across OpenAI, Anthropic, Ollama, and Hyperbolic

Quick Start

const { classMap } = require('@verdikta/common');

// Check if a ClassID is available
const cls = classMap.getClass(128);
if (cls && cls.status === 'ACTIVE') {
  console.log(`Using ${cls.name} with ${cls.models.length} models`);
}

// Validate a query manifest
const result = classMap.validateQueryAgainstClass(queryManifest, 128);
if (result.ok) {
  // Use result.effectiveManifest for execution
  console.log('Validation passed with', result.issues.length, 'adjustments');
}

API Reference

Core Functions

getClass(classId: number|bigint): ClassSpec|undefined

Returns the complete specification for a ClassID, or undefined if not found.

const cls = classMap.getClass(128);
if (cls) {
  console.log(`Class: ${cls.name}`);
  console.log(`Status: ${cls.status}`);
  console.log(`Models: ${cls.models.length}`);
  console.log(`Max outcomes: ${cls.limits.max_outcomes}`);
}

listClasses(filter?: {status?, provider?}): ClassListItem[]

Lists available classes with optional filtering.

// Get all active classes
const activeClasses = classMap.listClasses({ status: 'ACTIVE' });

// Get classes supporting OpenAI models
const openaiClasses = classMap.listClasses({ provider: 'openai' });

// Get active classes supporting Ollama
const localActive = classMap.listClasses({ 
  status: 'ACTIVE', 
  provider: 'ollama' 
});

isTracked(classId: number|bigint): boolean

Checks if a ClassID is in the curated range (< 2^56).

console.log(classMap.isTracked(128));        // true
console.log(classMap.isTracked(2n ** 60n));  // false (reserved)

isReserved(classId: number|bigint): boolean

Checks if a ClassID is in the experimental range (>= 2^56).

console.log(classMap.isReserved(128));        // false
console.log(classMap.isReserved(2n ** 60n));  // true

validateQueryAgainstClass(manifest: any, classId: number|bigint): ValidationResult

Validates and truncates a Query Manifest against a ClassID's limits.

const result = classMap.validateQueryAgainstClass(queryManifest, 128);

if (!result.ok) {
  console.error('Validation failed:', result.issues);
  return;
}

// Use the effective manifest (with truncations applied)
const manifestToExecute = result.effectiveManifest;

// Check for warnings
result.issues.forEach(issue => {
  if (issue.code === 'OUTCOMES_TRUNCATED') {
    console.warn('Some outcomes were truncated');
  }
});

Available Classes (v1)

ClassID Name Status Providers Models
128 OpenAI & Anthropic Core ACTIVE openai, anthropic gpt-5, gpt-5-mini, claude-sonnet-4
129 Open-Source Local (Ollama) ACTIVE ollama llama3.1:8b, llava:7b, deepseek-r1:8b, qwen3:8b
130 OSS via Hyperbolic API EMPTY (reserved) (none)

Resource Limits

All current classes share these limits:

  • Max outcomes: 20 evaluation outcomes
  • Max panel size: 5 unique models per panel
  • Max iterations: 3 panel cycles
  • Max no_counts: 2 per-model inner loop counts
  • Max evidence payload: 40 MB total across all files
  • Max supporting files: 10 files total
  • Max single file: 20 MB per individual file

Validation and Truncation

The validation system applies deterministic truncation to ensure manifests fit within class limits:

1. Outcomes Truncation

// Input: 25 outcomes
// Output: First 20 outcomes kept
// Issue: OUTCOMES_TRUNCATED

2. Model Deduplication and Panel Size

// Input: 7 models with 2 duplicates
// Output: 5 unique models (duplicates removed, then truncated)
// Issues: DUPLICATE_MODELS_REMOVED, PANEL_SIZE_TRUNCATED (if needed)

3. Iteration Limits

// Input: no_counts=10, iterations=5
// Output: no_counts=2, iterations=3
// Issues: NO_COUNTS_CLAMPED, ITERATIONS_CLAMPED

4. File Limits (Stable Priority)

// Priority order:
// 1. Drop files > 20MB per file
// 2. Keep support files first, then additional files
// 3. Apply count limit (10 files total)
// 4. Apply size limit (40MB total)

Error Handling

Unknown ClassID

const result = classMap.validateQueryAgainstClass(manifest, 999);
// result.ok = false
// result.classKnown = false
// result.issues[0].code = 'UNKNOWN_CLASS'

Empty/Reserved Classes

const result = classMap.validateQueryAgainstClass(manifest, 130);
// result.ok = false
// result.classStatus = 'EMPTY'
// result.issues[0].code = 'CLASS_EMPTY'

Deprecated Classes

// When a class is deprecated:
// result.ok = true (still usable)
// result.classStatus = 'DEPRECATED'
// result.issues includes CLASS_DEPRECATED warning

Best Practices

1. Always Check Class Status

const cls = classMap.getClass(classId);
if (!cls) {
  throw new Error(`Unknown ClassID: ${classId}`);
}
if (cls.status !== 'ACTIVE') {
  console.warn(`ClassID ${classId} is ${cls.status}`);
}

2. Use Effective Manifest

const result = classMap.validateQueryAgainstClass(manifest, classId);
if (result.ok) {
  // Always use the effective manifest, not the original
  return executeQuery(result.effectiveManifest);
}

3. Handle Truncation Gracefully

const hasOutcomesTruncated = result.issues.some(i => 
  i.code === 'OUTCOMES_TRUNCATED'
);
if (hasOutcomesTruncated) {
  console.warn('Some outcomes were truncated to fit class limits');
}

4. Provider Selection

// Find classes supporting specific providers
const openaiClasses = classMap.listClasses({ 
  status: 'ACTIVE',
  provider: 'openai' 
});

if (openaiClasses.length === 0) {
  console.warn('No active classes support OpenAI models');
}

Integration Examples

Arbiter Node Registration

function validateArbitersupportsClass(classId) {
  const cls = classMap.getClass(classId);

  if (!cls) {
    throw new Error(`ClassID ${classId} is not tracked`);
  }

  if (cls.status !== 'ACTIVE') {
    throw new Error(`ClassID ${classId} is ${cls.status}, cannot register`);
  }

  // Check if arbiter supports required providers
  const requiredProviders = [...new Set(cls.models.map(m => m.provider))];
  // ... validate arbiter capabilities

  return true;
}

Client-Side Validation

function preflightValidation(manifest, classId) {
  const result = classMap.validateQueryAgainstClass(manifest, classId);

  if (!result.ok) {
    return { error: result.issues[0].detail };
  }

  const warnings = result.issues.map(issue => ({
    type: issue.code,
    message: issue.detail
  }));

  return {
    effectiveManifest: result.effectiveManifest,
    warnings
  };
}

UI Model Selection

function getAvailableModels(classId) {
  const cls = classMap.getClass(classId);
  if (!cls || cls.status !== 'ACTIVE') {
    return [];
  }

  return cls.models.map(model => ({
    id: `${model.provider}/${model.model}`,
    provider: model.provider,
    name: model.model,
    contextWindow: model.context_window_tokens,
    supportedTypes: model.supported_file_types
  }));
}

Troubleshooting

Common Issues

  1. "ClassID not found" → Use isTracked() to check if ClassID is in curated range
  2. "Class is EMPTY" → Class is reserved but not yet populated with models
  3. "Unexpected truncation" → Check class limits with getClass().limits
  4. "Models not available" → Verify class status is ACTIVE and contains models

Debug Information

function debugClassInfo(classId) {
  console.log('ClassID:', classId);
  console.log('Is tracked:', classMap.isTracked(classId));
  console.log('Is reserved:', classMap.isReserved(classId));

  const cls = classMap.getClass(classId);
  if (cls) {
    console.log('Status:', cls.status);
    console.log('Models:', cls.models.length);
    console.log('Limits:', cls.limits);
  } else {
    console.log('Class not found');
  }
}

Version Information

  • Map Version: Use classMap.getMapVersion() to get current version
  • Compatibility: Follow semantic versioning for breaking changes
  • Updates: New classes and relaxed limits are minor versions

For more examples, see examples/classmap-usage.js.