Skip to content

Decision Engine (alnoms.core.decision_engine)

The Decision Engine is the "Logic Center" of the Alnoms framework. Its role is to map detected performance anti-patterns to their mathematically optimal remedies. In the OSS tier, this engine is strictly deterministic and rule-based, ensuring that performance governance is reproducible and transparent.

🧭 1. Philosophy: Deterministic Governance

Unlike modern "AI-driven" tools that rely on heuristics or black-box models, the Alnoms Decision Engine operates on a single principle: No Guesses.

  • Zero Telemetry: No data is sent to external servers for "learning."
  • Fully Deterministic: The same input pattern always yields the same recommendation.
  • Non-Adaptive: The engine uses stable, non-heuristic rules to ensure that performance audits can be replicated across different environments.

🔄 2. The Decision Logic

The engine sits between the Analyzer and the Fixers. It processes raw pattern data and developer "intent" to select an algorithm from the sovereign alnoms.dsa registry.

2.1 The Rule Map

For standard performance traps, the engine uses a direct 1-to-1 mapping to identify the recommended remedy:

Detected Pattern Recommended Remedy Technical Objective
inefficient_membership separate_chaining_hash_st Reduce \(O(N)\) lookup to \(O(1)\)
redundant_sort merge_sort Enforce stable \(O(N \log N)\) sorting
inplace_concat list_concat Avoid \(O(N^2)\) memory reallocation
expensive_calls memoization Eliminate redundant computation via caching

2.2 Intent-Aware Nested Loops

Nested loops are a primary source of "Silent Traps." The Decision Engine uses AST-derived Heuristic Intent to refine its choice:

  • Membership Intent: If the inner loop is checking existence, it suggests a Hash Table.
  • DFS Intent: If the structure suggests traversal, it suggests specialized Graph models.
  • Generic Intent: If the logic is opaque, it defaults to Pruning strategies.

⚙️ 3. Internal Mechanics

3.1 Metadata Normalization

The engine maintains strict naming conventions to satisfy governance requirements. It automatically normalizes PascalCase identifiers (e.g., MergeSort) into the canonical snake_case (e.g., merge_sort) used by the OSS-tier registries. This ensures consistency across the Alnoms ecosystem.

3.2 The Metadata Registry

Every decision made by the engine is backed by a metadata lookup. This provides the Analyzer with: * Complexity Shift: A mathematical proof of improvement (e.g., \(O(N^2) \rightarrow O(N)\)). * Implementation Path: The exact module path for the remediation code. * Access Tier: Verification that the remedy is available in the Open Source tier.

🧪 4. Example: The Decision Flow

  1. Input: Analyzer detects nested_loops with an inner in check (Intent: membership).
  2. Mapping: Engine queries the nested_loop_rules dictionary for the membership key.
  3. Selection: Returns separate_chaining_hash_st.
  4. Enrichment: decide_metadata() retrieves the complexity proof and the Python import path.
  5. Output: A prescriptive recommendation: "Use separate_chaining_hash_st to reduce complexity."

🧭 5. Design Principles

  • Reproducibility: A developer in Nacogdoches and a researcher in Tokyo will receive the exact same fix for the same code bottleneck.
  • Sovereign Mapping: Every recommended algorithm is pulled from the alnoms.dsa library, ensuring the fix follows our "Minimal Cognitive Tax" standard.
  • Separation of Concerns: The engine does not perform the fix; it only provides the "Prescription" based on the "Diagnosis" provided by the Analyzer.

👉 Next Step: Learn how the Profiler generates the empirical timing data that validates these decisions.