Neurosymbolic-LLM

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #llm #android #deep-learning #windows #cli #kubernetes #pytorch #mcp #ios #open-source

Neurosymbolic-LLM

(★ 15)

Integrating neurosymbolic representations into LLMs for interpretability, steering, and running symbolic algorithms

Neurosymbolic-LLM Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Neurosymbolic LLM

![Model Diagram](https://raw.githubusercontent.com/vdhanraj/Neurosymbolic-LLM/main/drawio_diagram.png)

This repository implements the method described in the following paper:  [https://aclanthology.org/2025.emnlp-main.1556](https://aclanthology.org/2025.emnlp-main.1556)

## Setup

1. **Get the dataset**  
   You can either:
   - Clone the symbolic math dataset repository:  
     [https://github.com/vdhanraj/Symbolic-Math-Dataset](https://github.com/vdhanraj/Symbolic-Math-Dataset)  
   - Or use randomly generated prompts.

2. **Download LLaMA 3.1 8B Instruct**  
   Download from:  
   [https://www.llama.com/llama-downloads/](https://www.llama.com/llama-downloads/)  
   Make sure to record the path where the following files are saved:
   ```
   consolidated.00.pth
   tokenizer.model
   ```
   (Default: `~/.llama/checkpoints/Llama3.1-8B-Instruct/`)

Model files can also be downloaded via huggingface-cli:
   ```
   huggingface-cli login
   huggingface-cli download meta-llama/Llama-3.1-8B-Instruct --include "original/*" --local-dir ~/.llama/checkpoints/Llama3.1-8B-Instruct
   ```

4. **Install dependencies**
   ```bash
   conda env create -f environment.yml
   ```

or

```bash
   pip install -r requirements.txt
   ```

---

## Step 1: Initial Training (Data Generation)

After obtaining the dataset and base LLM, run the following command to generate training data (hidden states and VSA descriptions):

```bash
python ~/Neurosymbolic-LLM/Programs/train_encoders_and_decoders.py --run_name your_run_name --generate_data 1 \
    --training_data_df_path "path/to/your/training/data.csv" \
    --val_data_df_path "path/to/your/validation/data.csv" \
    --testing_data_df_path "path/to/your/testing/data.csv"
```

If you are using randomly generated datasets, **omit** the `*_data_df_path` arguments.

This step:
- Prompts the LLM with questions from the dataset
- Records hidden states at various layers
- Saves vector symbolic architecture (VSA) representations of the problem
- Stores all data in `Programs/gathered_data_{run_name}/`

---

## Step 2: Train Encoders and Decoders

Now use the gathered data to train the encoder and decoder networks:

```bash
python ~/Neurosymbolic-LLM/Programs/train_encoders_and_decoders.py --run_name your_run_name --generate_data 0 \
    --training_data_df_path "path/to/your/training/data.csv" \
    --val_data_df_path "path/to/your/validation/data.csv" \
    --testing_data_df_path "path/to/your/testing/data.csv"
```

This step:
- Trains encoders to generate VSA vectors from prompts
- Trains decoders to reconstruct the LLM hidden state from VSAs
- Saves models to:
  - `Programs/models/encoders_{run_name}.pth`
  - `Programs/models/decoders_{run_name}.pth`

---

## Step 3: Fine-Tune Decoder in Context of LLM

This fine-tunes the decoder while freezing the base LLM and encoder. It optimizes decoder output via token-level cross-entropy loss.

```bash
python ~/Neurosymbolic-LLM/Programs/fine_tune_decoders.py --run_name your_run_name --test_baseline 1 \
    --encoder_path ~/Neurosymbolic-LLM/Programs/models/your_encoder.pth \
    --decoder_path ~/Neurosymbolic-LLM/Programs/models/your_decoder.pth \
    --training_data_df_path "path/to/your/training/data.csv" \
    --val_data_df_path "path/to/your/validation/data.csv" \
    --testing_data_df_path "path/to/your/testing/data.csv"
```

This will:
- Fine-tune decoder to integrate symbolic solutions with LLM reasoning
- Evaluate performance on validation and test sets
- Also run baseline evaluation on the original LLM (with `--test_baseline 1`)

---

## Optional: Compare with Other Methods

You can compare your neurosymbolic method against LoRA and Chain-of-Thought (CoT) baselines.

**LoRA Baseline:**
```bash
python ~/Neurosymbolic-LLM/Programs/fine_tune_decoders.py --run_name your_lora_run_name --lora_baseline 1 \
    --encoder_path ~/Neurosymbolic-LLM/Programs/models/your_encoder.pth \
    --decoder_path ~/Neurosymbolic-LLM/Programs/models/your_decoder.pth \
    --training_data_df_path "path/to/your/training/data.csv" \
    --val_data_df_path "path/to/your/validation/data.csv" \
    --testing_data_df_path "path/to/your/testing/data.csv"
```

**CoT Baseline:**
```bash
python ~/Neurosymbolic-LLM/Programs/fine_tune_decoders.py --run_name your_cot_run_name --cot 1 \
    --encoder_path ~/Neurosymbolic-LLM/Programs/models/your_encoder.pth \
    --decoder_path ~/Neurosymbolic-LLM/Programs/models/your_decoder.pth \
    --training_data_df_path "path/to/your/training/data.csv" \
    --val_data_df_path "path/to/your/validation/data.csv" \
    --testing_data_df_path "path/to/your/testing/data.csv"
```

---

## Output

All runs are logged to [Weights & Biases](https://wandb.ai) by default.  
To disable W&B logging, pass `--log_wandb False`.

---

## Huggingface Model Weights

The model weights needed to reproduce the paper results can be found at [https://huggingface.co/vdhanraj/neurosymbolic-llm](https://huggingface.co/vdhanraj/neurosymbolic-llm).

## License

This project is licensed under the GNU General Public License v3.0. See the [LICENSE](./LICENSE) file for details.

## Citation

If you use this code or build on this work, please cite:

```bibtex
@inproceedings{dhanraj-eliasmith-2025-improving,
  author    = {Varun Dhanraj and Chris Eliasmith},
  title     = {Improving Rule-based Reasoning in {LLM}s using Neurosymbolic Representations},
  booktitle = {Proceedings of the 2025 Conference on Empirical Methods in Natural Language Processing},
  year      = {2025},
  month     = {November},
  address   = {Suzhou, China},
  publisher = {Association for Computational Linguistics},
  pages     = {30577--30596},
  url       = {https://aclanthology.org/2025.emnlp-main.1556},
  doi       = {10.18653/v1/2025.emnlp-main.1556}
}
```

Neurosymbolic-LLM

Neurosymbolic-LLM Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Neurosymbolic-LLM

Neurosymbolic-LLM Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README