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¶
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¶
- "ClassID not found" → Use
isTracked()
to check if ClassID is in curated range - "Class is EMPTY" → Class is reserved but not yet populated with models
- "Unexpected truncation" → Check class limits with
getClass().limits
- "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
.