Cantara/similarity-connector

Connector Similarity Calculator Skill

Guidance for working with ConnectorSimilarityCalculator in the lib-electronic-components library.

---

For metadata-driven similarity architecture, see /similarity-metadata:

• SpecImportance levels (CRITICAL, HIGH, MEDIUM, LOW, OPTIONAL)
• ToleranceRule types (exactMatch, percentageTolerance, minimumRequired, etc.)
• SimilarityProfile contexts (DESIGN_PHASE, REPLACEMENT, COST_OPTIMIZATION, etc.)
• Calculator integration patterns and gotchas

---

Overview

The ConnectorSimilarityCalculator compares connectors based on:

• Family - Connector type/series (must match)
• Pin count - Number of contacts (must match for high similarity)
• Pitch - Contact spacing
• Mounting type - Through-hole vs SMD
• Series compatibility - Within TE, Molex, etc.

Applicable Types

ComponentType.CONNECTOR
ComponentType.CONNECTOR_MOLEX
ComponentType.CONNECTOR_TE
ComponentType.CONNECTOR_JST
ComponentType.CONNECTOR_HIROSE
ComponentType.CONNECTOR_AMPHENOL
ComponentType.CONNECTOR_HARWIN
// Any type starting with "CONNECTOR_"

Returns false for null type.

Similarity Thresholds

HIGH_SIMILARITY = 0.9;   // Same series, same pin count
MEDIUM_SIMILARITY = 0.5; // Compatible but different
LOW_SIMILARITY = 0.3;    // Different pin counts

Key Rules

Family Must Match

Different connector families always return 0.0:

// Different families = incompatible
calculator.calculateSimilarity("TE-connector", "Molex-connector", registry);
// Returns 0.0

Pin Count Rules

// Same pin count required for high similarity
calculator.calculateSimilarity("10-pin", "10-pin-variant", registry);
// Returns HIGH

// Different pin counts = LOW
calculator.calculateSimilarity("10-pin", "20-pin", registry);
// Returns 0.3

TE Connectivity Connectors

Part Number Format

1-292161-0
│ │      │
│ │      └── Configuration/variant
│ └─────────  Series number
└───────────  Prefix

// Same TE series
calculator.calculateSimilarity("1-292161-0", "1-292161-2", registry);
// Returns 0.9 (same series)

Würth Headers (WR-PHD)

// Compatible header variants
calculator.calculateSimilarity("61300411121", "61300411021", registry);
// Returns 0.9 if same pin count

Similarity Building Blocks

When connectors aren't direct variants, similarity is built from:

• Same pin count: +0.2
• Same pitch: +0.2
• Same mounting type: +0.1

// Compatible characteristics
// Same pin count (+0.2) + Same pitch (+0.2) + Same mount (+0.1) = 0.5

Connector Handlers

The calculator uses specialized handlers:

• TEConnectorHandler
• MolexConnectorHandler
• JSTConnectorHandler
• etc.

These extract:

• getPinCount(mpn) - Number of contacts
• getPitch(mpn) - Contact spacing (mm)
• getMountingType(mpn) - THT/SMD
• getFamily() - Connector family name
• getVariant(mpn) - Specific variant
• areCompatible(mpn1, mpn2) - Direct compatibility check

Test Examples

// Same TE connector
calculator.calculateSimilarity("1-292161-0", "1-292161-0", registry);
// Returns 1.0

// Same TE series, different variant
calculator.calculateSimilarity("1-292161-0", "1-292161-2", registry);
// Returns 0.9

// Different families
calculator.calculateSimilarity("TE-part", "Molex-part", registry);
// Returns 0.0

// Null handling
calculator.calculateSimilarity(null, "1-292161-0", registry);
// Returns 0.0

---

Learnings & Quirks

TE Part Numbers

• Format often: X-XXXXXX-X or XXXXXXXX
• Series number is key to compatibility
• Last digits often indicate configuration

Molex Part Numbers

• Often 10+ digits
• Series embedded in part number
• Configuration codes vary by series

Metadata-Driven Implementation (January 2026)

Status: ✅ Converted (pre-existing)

The ConnectorSimilarityCalculator uses a metadata-driven approach with ConnectorHandler integration.

Specs Compared

| Spec | Importance | Tolerance Rule | Description | |------|-----------|----------------|-------------| | pinCount | CRITICAL | exactMatch | Number of pins (MUST match) | | pitch | CRITICAL | exactMatch | Pin spacing (2.54mm, 1.27mm, etc.) | | family | HIGH | exactMatch | Connector series/family | | mountingType | HIGH | exactMatch | THT, SMD, Press-fit |

Implementation Pattern

// Different families return 0.0 immediately
if (!handler1.getFamily().equals(handler2.getFamily())) {
    return 0.0;
}

// Extract specs using ConnectorHandler
int pinCount1 = handler1.getPinCount(mpn1);
int pinCount2 = handler2.getPinCount(mpn2);
double pitch1 = handler1.getPitch(mpn1);
double pitch2 = handler2.getPitch(mpn2);

// Weighted spec scoring
// pinCount: CRITICAL (1.0 weight)
// pitch: CRITICAL (1.0 weight)
// family: HIGH (0.7 weight)
// mountingType: HIGH (0.7 weight)

Key Feature: Handler-Based Extraction

Unlike other calculators that use regex patterns, ConnectorSimilarityCalculator uses ConnectorHandler implementations for accurate spec extraction.

Why more accurate: Connectors have complex MPN formats that vary by manufacturer. Using handlers ensures correct extraction of pin count and pitch.

---

Pin Count Extraction

• Critical for compatibility
• Different manufacturers encode differently
• Some require handler-specific logic

Pitch Variations

• 2.54mm (0.1") - Standard through-hole
• 2.00mm - Common header pitch
• 1.27mm (0.05") - Fine pitch
• 0.5mm - FPC connectors

Mounting Types

• THT (Through-Hole Technology)
• SMT/SMD (Surface Mount)
• Press-fit
• Wire-to-board

<!-- Add new learnings above this line -->