Skip to content

Analyzer Architecture (alnoms.core.analyzer)

The Analyzer is the central orchestrator of the Alnoms Performance Intelligence Engine. It coordinates dynamic profiling, static AST analysis, empirical scaling tests, and prescriptive remediation into a single deterministic governance pipeline.

🧩 1. The Intelligence Layers

The Analyzer unifies four independent intelligence layers to provide a 360-degree view of system performance:

  1. Dynamic Profiling: Identifies the empirical bottlenecks in developer-defined functions.
  2. Static Intent Analysis: Scans the Abstract Syntax Tree (AST) to detect structural anti-patterns.
  3. Empirical Scaling Tests: Optional doubling tests that provide mathematical proof of complexity.
  4. Prescriptive Remediation: Maps bottlenecks to "Sovereign" data structures for actionable cures.

🔄 2. The Execution Pipeline

The Analyzer executes a stateless, side-effect-free pipeline to produce a unified governance report.

  1. Script Execution: Loads the target script in an isolated namespace to prevent global state pollution.
  2. Dynamic Profiling: Extracts the top 5 slowest functions using cProfile to identify real-world bottlenecks.
  3. Static AST Analysis: Identifies patterns (e.g., membership tests) and calculates Loop Depth (\(O(N^d)\)).
  4. Empirical Scaling Test: (Optional) Executes doubling tests (\(N, 2N, 4N\)) to verify asymptotic behavior.
  5. Decision Engine: Synthesizes metadata to recommend the most efficient DSA model.
  6. Fixer Integration: Generates "Before/After" remediation snippets.
  7. Governance Report: Compiles all data into a deterministic final output.

⚙️ 3. Internal Mechanics

3.1 Loop Depth Logic

The Analyzer computes complexity by recursively descending into nested loops while ignoring comprehensions (which are optimized at the C-level). It pinpoints the loop closest to the detected pattern to estimate Static Complexity: $\(O(N^{\text{depth}})\)$

3.2 The Doubling Test (Empirical Truth)

When deep=True is enabled, the Analyzer moves beyond static estimates. It performs repeated trials with increasing input sizes to calculate the Scaling Ratio. This is the "empirical truth" that validates whether a theoretical \(O(N^2)\) pattern is actually causing a quadratic slowdown in the current environment.

3.3 Prescriptive Remediation

Unlike traditional profilers that offer vague advice, the Analyzer's Fixer integration is prescriptive. It provides: * The Cure: The specific implementation from alnoms.dsa. * The Impact: Estimated performance gain (e.g., \(100\times - 1000\times\)). * The Proof: A complexity shift explanation (e.g., \(O(N^2) \rightarrow O(N)\)).

🧭 4. Design Principles

The Analyzer is built on the Arprax Lab standard for industrial-grade software:

  • Determinism: No randomness. The same code on the same hardware produces the same diagnostic.
  • Transparency: Every performance claim is backed by observable measurements.
  • Minimal Cognitive Tax: Fixes are designed to be "drop-in" ready, reducing the burden on the developer.
  • Governance Over Profiling: The end goal is not just to see where time is spent, but to enforce a performance standard that prevents silent failures at scale.

🧪 5. Example Output

Given a script with a membership test inside a nested loop, the Analyzer produces: * Static Intent: Membership test inside loop. * Loop Depth: 2. * Empirical Ratio: ~4.0 (Quadratic). * Verdict: ⚠️ WARNING: Function operates at \(O(N^2)\). * Remediation: Replace list-lookup with SeparateChainingHashST.

👉 Next Step: Explore how the Decision Engine selects the perfect data structure for your specific bottleneck.