res-profiles

RES vehicle profiles, engine coefficients, and performance evaluation library.

Purpose

This package provides a comprehensive backend for vehicle performance estimation, including:

• Data: Vehicle profiles, engine-family coefficients, modification ontology, and validation datasets
• Core Library: Performance evaluation, modification normalization, VIN-to-profile matching, and calibration utilities
• CLIs: Tools to generate, validate, and calibrate data

Installation

npm install res-profiles

Quick Start

import { evaluate, normalizeMods, matchVinToProfile, loadProfiles } from 'res-profiles';

// Load vehicle profiles
const profiles = await loadProfiles();

// Match VIN to profile
const { profile } = matchVinToProfile({
  year: 2019,
  make: 'BMW',
  model: 'M340i',
  engine_code: 'B58B30O1',
  drivetrain: 'AWD',
  trans: 'AT8',
  market: 'USDM'
}, profiles);

// Normalize modification text
const mods = normalizeMods('BM3 Stage 2 E30, catless DP, VRSF IC', 'BMW_B58');

// Evaluate performance
const result = evaluate(profile, mods, {
  surface: 'Street',
  tires: 'MaxPerf',
  tempF: 70,
  da_ft: 500
});

console.log(result);
// {
//   whp: 425,
//   zeroTo60: 3.6,
//   quarterET: 12.0,
//   trap: 118,
//   sustainHint: 'IC upgrade improves sustained performance'
// }

Core Functions

evaluate(profile, mods, env)

Calculates performance metrics for a vehicle with modifications:

• Inputs: CarProfile, NormalizedMods, EvaluationEnvironment
• Outputs: Wheel HP, 0-60 time, quarter mile ET, trap speed
• Features: Turbo pressure-ratio modeling, fuel system gains, traction scoring

normalizeMods(freeText, overlay)

Converts free-text modification descriptions to structured format:

• Inputs: Text description, engine family overlay
• Outputs: NormalizedMods object
• Features: Rule-based parsing, schema validation, AI-ready stub

matchVinToProfile(vinDecoded, profiles)

Finds the best matching vehicle profile:

• Inputs: Decoded VIN data, profile array
• Outputs: Matched profile with confidence level
• Features: Engine code primary key, fallback scoring

Data Structure

Vehicle Profiles

Each profile contains:

• Identity: Make, model, year, engine family/code
• Powertrain: Crank HP/TQ, redline, displacement
• Chassis: Weight, drag coefficient, frontal area
• Baselines: Stock performance metrics
• Coefficients: Engine-specific tuning parameters
• Validation: Confidence tier (Bronze/Silver/Gold), source

Confidence Tiers

• Bronze: Generated profiles with estimated parameters
• Silver: Validated against some real-world data
• Gold: Fully validated with comprehensive testing

Model Versioning

Profiles include modelVersion field (e.g., "2025-08-RES-v1") for tracking updates and compatibility.

CLI Tools

Development

npm run dev          # Demo evaluation with sample data

Data Generation

npm run gen:bmw      # Generate BMW profiles 2010-2025

Validation

npm run validate     # Validate all profiles against schemas

Calibration

npm run calibrate    # Calibrate constants against test data

Development

Prerequisites

• Node.js 18+
• TypeScript 5.3+

Setup

npm install
npm run build
npm test

Project Structure

res-profiles/
├─ /src
│  ├─ /types          # Zod schemas + TypeScript types
│  ├─ /constants      # Performance constants & gain tables
│  ├─ /lib            # Core library functions
│  └─ /cli            # Command-line tools
├─ /data              # Seed data & validation sets
├─ /schemas           # JSON Schema definitions
└─ /tests             # Vitest test suite

Performance Model

The evaluation engine uses a physics-based approach:

• Baseline: Crank HP × drivetrain efficiency
• Turbo/SC: Pressure ratio model with efficiency curves
• Fuel System: Ethanol content scaling
• Air Path: Intake, intercooler, and exhaust gains
• Traction: Tire type, surface, and drivetrain effects

Constants (a0-a2, b0-b2, c0-c2) are calibrated against validation data and can be refined using the calibration CLI.

Contributing

1. Follow TypeScript strict mode and ESLint rules
2. Add tests for new functionality
3. Update schemas when modifying data structures
4. Use semantic versioning for releases

License

MIT