Elex Ran Features

For non-feature searches (params, counters, keywords), use the appropriate search flag directly.

🎯 Flag Selection Guide (Choose by User Intent)

Feature Lookups (Acronym/FAJ/CXC)

Search Queries (Not Feature Lookup)

🔀 Quick Flag Decision

User Query
    │
    ├─ Is it a FEATURE lookup (acronym/FAJ/CXC)?
    │     │
    │     ├─ Wants KPIs? → --markdown-with-kpis
    │     ├─ Wants parameters? → --full-chain
    │     ├─ Wants cmedit? → --cmedit
    │     ├─ Wants dependencies? → --deps
    │     ├─ Wants activation plan? → --activation-script
    │     └─ Wants JSON? → --json
    │
    ├─ Is it a PARAMETER search?
    │     ├─ Fuzzy → --params <name>
    │     ├─ Exact → --params-exact <name>
    │     ├─ By MO class → --params-mo <class>
    │     └─ Full chain → --param-chain <name>
    │
    ├─ Is it a COUNTER search?
    │     ├─ Basic → --counters <name>
    │     ├─ With KPIs → --counters <name> --counters-with-kpi
    │     └─ Full chain → --counter-chain <name>
    │
    ├─ Is it a KEYWORD search? → --keyword "expr"
    │
    └─ Is it MO CLASS exploration? → --mo-class <class>

💬 Common Questions → Flag Mapping

Quick Reference

Main scripts: search.py, deps.py, validate.py, compare.py, cmedit_generator.py

CLI Commands

Basic Searches

# Feature lookups - choose flag based on user's need
python3 scripts/ops/search.py IFLB --full-chain           # Params with emoji flags
python3 scripts/ops/search.py MSM --markdown-with-kpis    # Full markdown + KPIs
python3 scripts/ops/search.py IFLB --kpis                 # Just KPIs
python3 scripts/ops/search.py --faj "121 3009" --deps     # Dependencies
python3 scripts/ops/search.py --cxc CXC4011808 --cmedit   # Generate cmedit

# Parameter/counter search (no feature flag needed)
python3 scripts/ops/search.py --params sleepMode
python3 scripts/ops/search.py --counters pmMimoSleep --counters-with-kpi
python3 scripts/ops/search.py --counter-chain pmRrcConnEstabSucc
python3 scripts/ops/search.py --mo-class EUtranCellFDD

# Boolean keyword search
python3 scripts/ops/search.py --keyword "MIMO AND sleep"
python3 scripts/ops/search.py --keyword "handover OR mobility"

Schema v2.0.0 Flags

Dependency & Cross-Reference

# Feature dependencies
python3 scripts/deps.py IFLB
python3 scripts/deps.py --activation-order IFLB DUAC MSM

# Validation
python3 scripts/validate.py IFLB DUAC MSM
python3 scripts/validate.py --json IFLB DUAC

# Comparison
python3 scripts/compare.py IFLB DUAC MSM
python3 scripts/compare.py IFLB DUAC --deps --params

# Visualization
python3 scripts/visualize_deps.py IFLB
python3 scripts/visualize_deps.py IFLB --dot > deps.dot
python3 scripts/visualize_deps.py IFLB --mermaid

cmedit Generation

python3 scripts/cmedit_generator.py IFLB
python3 scripts/cmedit_generator.py IFLB --format markdown
python3 scripts/cmedit_generator.py IFLB --format script
python3 scripts/cmedit_generator.py IFLB --site "PARIS_01"

NPM Scripts

# Semantic search
npm run search:semantic "MIMO sleep mode optimization"
npm run similar:feature FAJ_121_3094

# Swarm management
npm run swarm:start
npm run swarm:stop

# Dashboard & testing
npm run ran:dashboard
npm run test:generate
npm run test:self-healing
npm run test:integration

# Embeddings
npm run generate:embeddings
npm run generate:hyperbolic

Index System (Unified v2.0.0)

Available Indexes

Performance Targets (Validated)

Building Indexes

# Rebuild all from Excel (ALL_25Q3.xlsx)
python3 scripts/ops/build_unified_index.py /path/to/ALL_25Q3.xlsx -v --link-kpi

# Extract Excel to CSVs (if needed)
python3 scripts/extract_excel_to_csv.py /path/to/ALL_25Q3.xlsx

# Build KPI index from MnM CSV
python3 scripts/build_kpi_index.py /path/to/formulo.csv -v

# Build docs/ran indexes + embeddings
python3 scripts/ops/build_docs_ran_indexes.py --dimensions 384

# Rebuild feature indexes from markdown
python3 scripts/ops/build_index.py

# Audit index integrity
python3 scripts/ops/audit.py --strict

Pattern System

Confidence Gates (3-Tier Automation)

Pattern Store API

import { RANPatternStore } from './pattern-store';
const store = new RANPatternStore();

// Search patterns
const patterns = await store.searchSimilarPatterns("MIMO sleep not activating", 0.7);
const gate = store.getConfidenceGate(patterns[0].confidence); // "auto" | "approve" | "simulate"

// Update confidence after application
await store.updateConfidence(patternId, {
  cell_id: 'CELL_001',
  kpi_before: 50,
  kpi_after: 200,
  improvement_pct: 300,
  success: true
});

// Statistics
const stats = store.getStats();
// { total, auto, high, medium, experimental }

Pattern Lifecycle

1. Detection: HNSW vector search for similar symptoms
2. Gate Decision: Auto/Approve/Simulate based on confidence
3. Application: Execute with rollback safety (⚠️ ENM stub)
4. Monitoring: Track KPI improvements for 5 min (⚠️ Random data)
5. Learning: Update confidence via EWC++ (🚧 Not implemented)

Status: Pattern storage ⚠️ in-memory only (patterns/ folder empty), rollback 🚧 stub, KPI monitoring ⚠️ mock data

HNSW Integration (O(log n) Semantic Search)

Architecture Overview

Query → QueryProcessor → QueryEmbedder → HNSW Index → HybridReRanker → Results
         (RAN domain)    (MiniLM ONNX)   (O(log n))   (5 signals)

Key Components:

• hnsw/hnsw-index.ts - Core HNSW algorithm with 6-layer graph
• hnsw/query-embedder.ts - Real MiniLM embeddings via @xenova/transformers
• hnsw/query-processor.ts - RAN acronym expansion, intent detection
• hnsw/re-ranker.ts - Hybrid scoring (semantic + BM25 + exact + hyperbolic + recency)
• hnsw/multi-index.ts - Unified search across all data types

Configuration (ADR-002/ADR-030/ADR-021) - Updated 2026-01-28

WASM Acceleration (ADR-021)

For production deployments requiring <5ms p50 latency, enable WASM acceleration:

# Option 1: Environment variable
export HNSW_WASM_PATH=/path/to/hnsw_wasm.js
npm run search:semantic "MIMO sleep mode"

# Option 2: Build WASM module
npm run build:wasm
export HNSW_WASM_PATH=./pkg/hnsw/hnsw_wasm.js

Performance with WASM:

// Enable WASM programmatically
import { HNSWIndex, loadWasmModule, isWasmAvailable } from './hnsw';

const hnsw = new HNSWIndex({ useWasm: true });
await hnsw.initializeWasm();

console.log('WASM enabled:', hnsw.isWasmEnabled()); // true if WASM loaded

Performance Results (Validated 2026-01-28)

Recall Fix Details (2026-01-28):

• Added graph refinement step for datasets <2000 nodes
• Uses brute-force neighbor selection during construction
• Ensures every node connects to its true M0 closest neighbors
• Result: 100% recall achieved (was 18.8% before fix)

Multi-Index Embeddings (17,951 vectors)

Hybrid Re-Ranking (5 Signals)

Score = 0.5·Semantic + 0.2·BM25 + 0.2·Exact + 0.05·Hyperbolic + 0.05·Recency

RAN Query Processor

Example: "IFLB" → "Inter-Frequency Load Balancing" with NR/LTE tech filter

TypeScript Integration

import { HNSWIndex, createIndexFromFile } from './hnsw/hnsw-index';
import { QueryEmbedder } from './hnsw/query-embedder';
import { RANQueryProcessor } from './hnsw/query-processor';
import { HybridReRanker } from './hnsw/re-ranker';
import { MultiIndexSearch } from './hnsw/multi-index';

// Load pre-built HNSW index (instant)
const hnsw = await loadIndex('./data/hnsw-index.json');

// Or build from embeddings
const hnsw = await createIndexFromFile('./references/embeddings.json');

// Search with O(log n) complexity
const results = hnsw.search(queryEmbedding, 10, 50);
// Returns in ~0.09ms: [{ id, score }, ...]

// Multi-index search across all data types
const multiIndex = new MultiIndexSearch();
const results = await multiIndex.searchAll('MIMO sleep mode', {
  indexes: ['features', 'params', 'counters'],
  tech: 'nr',
  topK: 10
});

// Real semantic embeddings (not hash-based)
const embedder = new QueryEmbedder();
const embedding = await embedder.embed('load balancing mobility');
// Returns 384D MiniLM vector in ~3ms (cached: <1ms)

// RAN-aware query processing
const processor = new RANQueryProcessor();
const processed = processor.process('What is IFLB for 5G?');
// { expanded: 'Inter-Frequency Load Balancing', tech: 'NR', intent: 'LOOKUP' }

// Hybrid re-ranking with 5 signals
const reranker = new HybridReRanker();
const reranked = reranker.rerank(candidates, query, { tech: 'nr' });

CLI Usage

# Standard HNSW search (O(log n))
npm run search:semantic "MIMO sleep mode optimization"

# Multi-index search with technology filter
npm run search:semantic "sleep mode" --index all --tech nr

# Search specific indexes
npm run search:semantic "admission control" --index params --tech lte

# Benchmark HNSW vs brute-force
npm run search:semantic "MIMO" --benchmark 20

# Generate embeddings for all indexes
npm run generate:embeddings:all

9 RAN Agents & Swarm

Agent Roster

Swarm Commands

# Initialize topology
npx @claude-flow/cli@latest swarm init --topology hierarchical-mesh --max-agents 9 --strategy specialized

# Manage swarm
npm run swarm:start
npm run swarm:stop
npx @claude-flow/cli@latest swarm status

# Monitoring
npm run ran:dashboard
npx @claude-flow/cli@latest agent list --metrics
npx @claude-flow/cli@latest agent logs 4g-lte-agent --tail 50

Routing & Consensus

import { RANSwarmCoordinator } from './swarm/coordinator';
import { ConsensusEngine } from './swarm/consensus';

// Route issue to agents
const routing = await coordinator.routeIssue({
  symptom: 'MIMO sleep mode not activating',
  cellId: 'CELL_12345',
  kpi: { pmMimoSleepTime: 50 }
});
// Returns: { primaryAgent, backupAgents, matchedPatterns, confidence, action }

// Byzantine consensus (2/3 agreement)
const result = await consensus.reachConsensus(proposal, agents);
// Returns: { consensus, agreement, confidence, votes }

Architecture

Search Strategy (Waterfall)

Query → 1. O(1) Exact Match (acronym/FAJ/CXC)
     → 2. O(n) Text Search (Boolean keywords)
     → 3. O(log n) Semantic (HNSW vector similarity)

File Structure

.claude/skills/elex-ran-features/
├── SKILL.md (this file)
├── pattern-store.ts (687 lines, ⚠️ in-memory only)
├── rag-adapter.ts (572 lines, ✅)
├── skill-interface.ts (617 lines, ✅)
├── agentdb-adapter.ts (~500 lines, ⚠️ embedding stub)
├── automation-engine.ts (218 lines, 🚧 stub methods)
├── ruvector-adapter.ts (168 lines, 🚧 minimal stub)
├── references/ (44.8MB total, ✅)
│   ├── features.json (593 features)
│   ├── lookup.json (O(1) indexes)
│   ├── param_index.json (8,001 params)
│   ├── counter_index.json (5,202 counters)
│   ├── event_index.json (1,074 events)
│   ├── alarm_index.json (278 alarms)
│   ├── kpi_index.json (3,434 KPIs, 5,361 counters)
│   ├── embeddings.json (⚠️ hash-based)
│   └── hyperbolic_embeddings.json (⚠️ hash-based)
├── scripts/ (21 Python files, ✅)
│   ├── search.py (unified CLI)
│   ├── deps.py, validate.py, compare.py
│   ├── build_unified_index.py
│   ├── build_kpi_index.py
│   ├── generate_embeddings.py (⚠️ hash-based)
│   └── audit.py
├── swarm/ (812 lines total, ✅)
│   ├── coordinator.ts (374 lines, 🚧 drift not impl)
│   ├── consensus.ts (293 lines, ✅)
│   ├── start.ts, stop.ts
├── agents/ (14 YAML files, ✅)
├── dashboard/ (ran-dashboard.ts, 14K, ✅)
├── monitoring/
│   ├── metrics-collector.ts (314 lines, 🚧 no export)
│   ├── alerts.ts (321 lines, 🚧 not connected)
├── testing/ (8 files, ✅)
│   ├── test-generator.ts, test-runner.ts
├── hooks/
│   ├── ran-learning-handler.ts (119 lines, 🚧 no EWC++)
├── patterns/ (⚠️ only README.md, 0 patterns)
└── cli/ (3 TS files, ✅)

Operations

Dashboard

npm run ran:dashboard

Features: Real-time agent health, swarm metrics, pattern confidence distribution, event log

Keyboard Controls: q exit, r refresh, h help, ↑/↓ navigate, Enter details, s sort, e export JSON

Modes: --mode performance (latency breakdown), --mode patterns (analytics), --mode topology (agent mesh)

Export: --export metrics.json, --format prometheus, --stream --interval 5s

Testing

# Generate test cases
npm run test:generate
npm run test:generate -- --category energy-saving

# Run tests
npm run test:self-healing
npm run test:self-healing -- --coverage
npm run test:integration

# Output: 247 tests, 94.7% pass rate

Test Categories: Functional (92 tests), Performance (80), Self-Healing (62), Integration (13)

Quick Start

# 1. Install dependencies
npm install
pip install sentence-transformers

# 2. Build indexes (if needed)
python3 scripts/ops/build_unified_index.py /path/to/ALL_25Q3.xlsx -v --link-kpi
python3 scripts/build_kpi_index.py /path/to/formulo.csv -v

# 3. Generate embeddings (⚠️ currently hash-based)
npm run generate:embeddings
npm run generate:hyperbolic

# 4. Initialize swarm
npx @claude-flow/cli@latest swarm init --topology hierarchical-mesh --max-agents 9

# 5. Start agents
npm run swarm:start

# 6. Launch dashboard
npm run ran:dashboard

# 7. Search features (choose flag based on need)
python3 scripts/ops/search.py IFLB --full-chain            # Full details + params
python3 scripts/ops/search.py MSM --markdown-with-kpis     # Markdown + KPIs
python3 scripts/ops/search.py IFLB --kpis                  # Just KPIs
python3 scripts/ops/search.py --params sleepMode           # Parameter search
npm run search:semantic "MIMO sleep optimization"

Reference Tables

Categories (14 total)

• Carrier Aggregation, Radio Resource Management, NR/5G, Transport & Connectivity
• MIMO & Antenna, Mobility & Handover, Energy Saving, Coverage & Capacity
• Voice & IMS, QoS & Scheduling, Security, SON, Testing & Optimization, Multi-RAT

Key Files

ADRs

• ADR-002: HNSW configuration (M=24, efConstruction=200)
• ADR-030: RAN vector search with HNSW
• ADR-031: RAN pattern learning with confidence-based automation
• ADR-032: RAN agents swarm with Byzantine consensus

See docs/adr/ for full decision records.

Known Gaps & Status

Legend: ✅ Production | ⚠️ Partial | 🚧 Stub

Recent Improvements (HNSW Implementation)

See HNSW_IMPLEMENTATION_PLAN.md for full implementation details.