elex-ran-features

name: elex-ran-features description: > Ericsson LTE/NR RAN feature knowledge base. Query by acronym (IFLB, DUAC, MSM), FAJ/CXC codes, parameter names, counter patterns, or Boolean keywords. Returns feature descriptions, parameters, counters, KPIs, engineering guidelines, activation procedures, and dependencies. Supports cmedit command generation, dependency visualization, feature validation, and deployment scripts.

Ericsson RAN Features Skill

Simplified knowledge base for Ericsson Radio Access Network features.

⚠️ CRITICAL: Default Output Format

For feature lookups by acronym/FAJ/CXC, NEVER use bare commands like search.py EPLA - this only shows summary counts.

Choose flag based on user's need:

• Need parameter emoji flags (🔐⚠️❌🔒)? → --full-chain
• Need KPI correlation? → --markdown-with-kpis
• Need cmedit commands? → --cmedit or --markdown
• Need activation planning? → --activation-script
• Need dependency info? → --deps

Parameter emoji flags (shown with --full-chain):

• 🔐 Lock Required - Parameter requires cell/object lock to change
• ⚠️ Deprecated - Parameter is deprecated
• ❌ Obsolete - Parameter is obsolete
• 🔒 ReadOnly - Parameter is read-only

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.