SEER: Spectral Entropy Encoding of Roles for Context-Aware Attention-Based Design Pattern Detection

TL;DR

SEER reframes code as context-sensitive sequences by introducing spectral-entropy role encoding and time-weighted calling context, enabling explicit role understanding within design patterns while remaining compatible with Transformer encoders. The approach yields consistent gains on PyDesignNet across all 23 GoF patterns, improves macro-F1 to 0.9320 and accuracy to 0.9398, and reduces false positives by about 20%, with interpretable symbol-level attributions. Its language-agnostic preprocessing and cross-language portability offer practical benefits for applying design-pattern detection across languages with minimal adaptation. Overall, SEER advances automated pattern detection by marrying principled spectral topology with temporal signal weighting, delivering robust, scalable, and interpretable performance gains.

Abstract

This paper presents SEER, an upgraded version of our prior method Context Is All You Need for detecting Gang of Four (GoF) design patterns from source code. The earlier approach modeled code as attention-ready sequences that blended lightweight structure with behavioral context; however, it lacked explicit role disambiguation within classes and treated call edges uniformly. SEER addresses these limitations with two principled additions: (i) a spectral-entropy role encoder that derives per-member role embeddings from the Laplacian spectrum of each class's interaction graph, and (ii) a time-weighted calling context that assigns empirically calibrated duration priors to method categories (e.g., constructors, getters/setters, static calls, virtual dispatch, cloning). Together, these components sharpen the model's notion of "who does what" and "how much it matters," while remaining portable across languages with minimal adaptation and fully compatible with Transformer-based sequence encoders. Importantly, SEER does not "force" a win by capacity or data; it nudges the classifier, steering attention toward role-consistent and temporally calibrated signals that matter most. We evaluate SEER on PyDesignNet (1,832 files, 35,000 sequences, 23 GoF patterns) and observe consistent gains over our previous system: macro-F1 increases from 92.47% to 93.20% and accuracy from 92.52% to 93.98%, with macro-precision 93.98% and macro-recall 92.52%. Beyond aggregate metrics, SEER reduces false positives by nearly 20%, a decisive improvement that strengthens its robustness and practical reliability. Moreover, SEER yields interpretable, symbol-level attributions aligned with canonical roles, exhibits robustness under small graph perturbations, and shows stable calibration.

Figures (10)

• Figure 1: Examples of tokens extracted from a generated sequence from our previous research, each encapsulating a behavioral aspect—depicting the interaction between two objects—and a structural/architectural aspect conveyed through dedicated symbols.
• Figure 2: Examples of tokens extracted from a generated sequence from our previous research, each encapsulating a behavioral aspect—depicting the interaction between two objects—and a structural/architectural aspect conveyed through dedicated symbols.
• Figure 3: Overview of the SEER architecture for attention-based design pattern detection. The pipeline begins with the data collection and preprocessing layer, where source code is transformed into token sequences and enriched with role encodings derived from Laplacian spectral entropy. A dual-path embedding strategy is employed: the standard transformer path processes token sequences with positional encodings, while the customized enriching path encodes spectral entropy and temporal values using circular embeddings.
• Figure 4: Vertex-colored member-level graph of the Auth class from the PyDesignNet dataset houichimePyDesignNetDataset2024, where nodes represent individual class members—constructors (blue), public methods (green), private methods (orange), and attributes (pink)—and edges denote structural relationships, labeled as either intra-class method calls or method-to-attribute accesses. This encoding preserves both the structural topology and semantic roles of members for subsequent spectral analysis in the SEER framework.
• Figure 5: Overview of six structurally similar classes from the PyDesignNet houichimePyDesignNetDataset2024 dataset—AuthManager, InMemoryCache, UserController, AppLogger, UserRepository, and PaymentService—showing their corresponding normalized Laplacian spectra. Despite originating from the same project and exhibiting comparable member layouts, the spectral profiles differ, highlighting the discriminative power of the SEER role encoding in capturing subtle structural variations.

Theorems & Definitions (3)

• Theorem 1
• Theorem 2: Weyl's Inequality strangLectureNotesLinear
• Theorem 3