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

``bash
npm install res-profiles
`

Quick Start

`typescript
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

$3

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

$3

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

$3

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

$3

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

$3

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

$3

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

CLI Tools

$3

`bash
npm run dev # Demo evaluation with sample data
`

$3

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

$3

`bash
npm run validate # Validate all profiles against schemas
`

$3

`bash
npm run calibrate # Calibrate constants against test data
`

Development

$3

- Node.js 18+
- TypeScript 5.3+

$3

`bash
npm install
npm run build
npm test
`

$3

`
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