code/README_HF.md

# EvoRM: Evolutionary Rule Mining for Knowledge Graph Entity Alignment

This repository contains the implementation and experimental results of **EvoRM**, a neuro-symbolic reasoning framework for knowledge graph entity alignment, integrated into the **AdaCoAgentEA** (ICDE 2025) framework.

## Paper

EvoRM: Neuro-Symbolic Evolutionary Rule Mining for Knowledge Graph Reasoning  
*Submitted to TKDE*

## Overview

EvoRM enhances LLM-based entity alignment through 4 key components:

1. **RuleEncoding** - Symbolic rule extraction from LLM reasoning traces
2. **HypergraphStorage** - Weighted hypergraph for rule organization and retrieval
3. **TwoStageInferenceController** - Two-stage inference with Mlight/Mheavy separation
4. **RuleMaintenance** - Dynamic rule pruning and evolution

## Key Features

- **MLP Gate (gϕ)**: Lightweight MLP for survival pair gating (Section III-E)
- **Mlight/Mheavy Separation**: Rationale elicitation separated from decision-making (Section III-C)
- **Entity Embeddings**: 1024-dim feature hashing for cosine similarity (Section III-D)
- **SemanticEquiv/SemanticConflict**: LLM identifies semantically equivalent/conflicting attribute values
- **5 Ablation Modes**: w/o Stage-1, w/o Maintenance, w/o MLP Gate, w/o Hypergraph, w/o Mlight

## Results

### RQ1: Main Experiment (ICEWS-WIKI)

| Method | Hits@1 | Precision | Recall | F1 |
|--------|--------|-----------|--------|-----|
| AdaCoAgentEA (Baseline) | 0.9003 | 0.9235 | 0.9003 | 0.9117 |
| AdaCoAgentEA + EvoRM | **0.9508** | **0.99** | **0.9508** | **0.97** |

### RQ3: Ablation Study

| Configuration | Hits@1 | Precision | Recall |
|---------------|--------|-----------|--------|
| Full System (EvoRM) | 0.9267 | 0.9929 | 0.9267 |
| w/o Stage-1 (Symbolic) | 0.95 | 0.9965 | 0.95 |
| w/o Maintenance | 0.9433 | 0.993 | 0.9433 |
| w/o MLP Gate | TBD | TBD | TBD |
| w/o Hypergraph | TBD | TBD | TBD |
| w/o Mlight | TBD | TBD | TBD |

### RQ5: Cold-Start Scaling

| N_warmup | Hits@1 | Tokens/Pair | Rules |
|----------|--------|-------------|-------|
| 100 | 0.97 | 858.1 | - |
| 200 | 0.935 | 881.1 | - |
| 500 | 0.936 | 884.9 | - |
| 1000 | 0.938 | 877.9 | - |

## Code Structure

```
AdaCoAgentEA/
├── evorm_plugin.py          # Core EvoRM framework (1599 lines)
├── evorm_mlight.py          # Mlight/Mheavy two-step pipeline (608 lines)
├── evorm_entity_embedding.py # Entity embeddings + feature hashing (285 lines)
├── evorm_config.py          # Centralized hyperparameter config (195 lines)
├── evorm_mlp_gate.py        # MLP Gate for survival pair gating (351 lines)
├── baselines/               # All baseline implementations
│   ├── evorm_wrappers/      # EvoRM wrappers for baselines
│   │   ├── chat_ea.py       # ChatEA + EvoRM
│   │   ├── zero_cot.py      # ZeroCoT + EvoRM
│   │   ├── self_consistency.py # Self-Consistency + EvoRM
│   │   ├── cohard.py        # Collaboration-Hard + EvoRM
│   │   ├── matchgpt.py      # MatchGPT/Anymatch + EvoRM
│   │   └── lela_el.py       # LELA/Schema Matching + EvoRM
│   └── original/            # Original baseline source code
├── Area2/                   # AdaCoAgentEA core
│   ├── LLM1_label_selector.py       # AdaCoAgentEA + EvoRM
│   └── LLM1_label_selector_baseline.py # AdaCoAgentEA baseline
├── experiments/             # Experiment scripts
│   ├── run_comprehensive.py # RQ1-RQ5 comprehensive experiments
│   ├── run_ablation_v2.py   # 6-mode ablation study
│   └── run_baselines_v2.py  # Baseline comparison
└── results/                 # All experiment results (JSON)
```

## Baselines

| Task | Baselines | EvoRM-Enhanced |
|------|-----------|----------------|
| Entity Alignment (EA) | ChatEA, ZeroCoT, Self-Consistency, CoHard, AdaCoAgentEA | ✅ All |
| Entity Resolution (ER) | MatchGPT (4 backends), Anymatch | ✅ All |
| Entity Linking (EL) | LELA (4 datasets) | ✅ All |
| Schema Matching (SM) | LLM-DP, ReMatch, Matchmaker | ✅ All |

## Usage

```bash
# Run ablation study
python experiments/run_ablation_v2.py

# Run baseline comparison
python experiments/run_baselines_v2.py

# Run comprehensive experiments
python experiments/run_comprehensive.py --dataset icews_wiki --all
```

## Citation

```bibtex
@article{evorm2025,
  title={EvoRM: Neuro-Symbolic Evolutionary Rule Mining for Knowledge Graph Reasoning},
  journal={IEEE Transactions on Knowledge and Data Engineering},
  year={2025}
}
```

## License

This project is for research purposes only.