A neural network for modeling reflective thought sequences and predicting introspective metrics in Self-Reflective AI systems.

RefNet is a transformer-based model that processes sequences of SRAI (Self-Reflective AI) function tokens and predicts:

• Valence: Emotional tone of thoughts
• SMD: Semantic Metric Distance
• Quality: Thought quality assessment
• Next Action: Predicted next cognitive action (consolidate, recall, reframe, evaluate_alignment)

• Model: Transformer encoder with positional encoding
• Input: Sequences of 256-dimensional embeddings
• Output: Multi-task predictions with weighted loss functions
• Configuration: 256 dimensions, 8 attention heads, 6 transformer layers

# Clone the repository
git clone https://github.com/nbursa/refnet.git
cd refnet

# Install dependencies
pip install -e .

# Train with default configuration (recommended)
PYTHONPATH=src python src/refnet/training/train.py

# Train with custom config
PYTHONPATH=src python src/refnet/training/train.py --config configs/refnet_base.yaml

# Alternative: module execution
python -m refnet.training.train --config configs/refnet_base.yaml

The model uses YAML configuration files. Key parameters in configs/refnet_base.yaml:

model:
  d_model: 256          # Embedding dimension
  n_heads: 8            # Attention heads
  n_layers: 6           # Transformer layers
  dropout: 0.1          # Dropout rate

optim:
  lr: 0.0003           # Learning rate
  epochs: 20           # Training epochs
  weight_decay: 0.01   # Weight decay

loss:
  lambda_valence: 1.0   # Valence loss weight
  lambda_smd: 1.0       # SMD loss weight
  lambda_quality: 0.5   # Quality loss weight
  lambda_action: 0.5   # Action loss weight

The model expects JSONL files with the following structure:

{
  "episode_id": "ep-00000",
  "tokens": [
    {
      "token_name": "reflect",
      "embed": [0.94, -1.95, ...],  // 256-dim vector
      "metrics": {"valence": -0.52, "smd": 0.28},
      "edges": []
    }
  ],
  "targets": {
    "valence": 0.064,
    "smd": 0.398,
    "quality": 1,
    "next_action": "consolidate"
  }
}

Use the evaluation script to assess model performance:

# Evaluate trained model
PYTHONPATH=src python scripts/evaluate.py models/refnet_best.pth configs/refnet_base.yaml data/samples/val.jsonl

# Evaluate edge-aware model
PYTHONPATH=src python scripts/evaluate.py models/refnet_best.pth configs/refnet_edge.yaml data/samples/val.jsonl

Evaluation Metrics:

• Action Accuracy: Classification accuracy for next actions
• Action F1 (macro): Balanced F1-score across all action classes
• Valence MAE: Mean Absolute Error for valence predictions
• SMD MAE: Mean Absolute Error for SMD predictions
• Quality Accuracy: Binary classification accuracy (threshold 0.5)
• Quality AUC: ROC-AUC for quality discrimination

Example output:

Evaluation Results:
  Action Accuracy: 0.275
  Action F1 (macro): 0.108
  Valence MAE: 0.442
  SMD MAE: 0.164
  Quality Accuracy: 0.500
  Quality AUC: 0.527
  Total Samples: 120

Test overfitting capability on small data:

# Standard sanity check
PYTHONPATH=src python scripts/sanity_check.py

# Edge-aware sanity check
PYTHONPATH=src python scripts/sanity_check.py --edge

This trains on 50 samples and should achieve near-zero loss if the model architecture is working correctly.

import torch
from refnet.models.refnet import RefNet

# Load trained model
model = RefNet(d_model=256, n_heads=8, n_layers=6, dropout=0.1)
model.load_state_dict(torch.load("models/refnet_trained.pth"))
model.eval()

# Make predictions
with torch.no_grad():
    outputs = model(input_tensor)
    valence = outputs["valence"]
    smd = outputs["smd"]
    quality = outputs["quality"]
    next_action = outputs["next_action"]

Best Checkpoint Saving: Automatically saves the best model based on validation loss:

• models/refnet_best.pth - Best performing model during training
• models/refnet_trained.pth - Final epoch model

Training Stability:

• Gradient clipping (max_norm=1.0) for stable training
• Deterministic training with seed control
• Proper padding masking for variable-length sequences

Training Output:

epoch 1 train={'L': 2.81, 'Lv': 1.63, 'Ls': 0.11, 'Lq': 0.36, 'La': 0.70} val={'L': 1.82, 'Lv': 0.74, 'Ls': 0.02, 'Lq': 0.36, 'La': 0.70}
...
Best model saved to models/refnet_best.pth (val_loss=1.1107)
Final model saved to models/refnet_trained.pth

Where:

• L: Total combined loss
• Lv: Valence loss component
• Ls: SMD loss component
• Lq: Quality loss component
• La: Action loss component

refnet/
├── src/refnet/
│   ├── models/
│   │   └── refnet.py          # Model architecture
│   ├── data/
│   │   ├── dataset.py         # Data loading
│   │   ├── constants.py       # Action vocabulary & constants
│   │   └── schema.md          # Data schema
│   └── training/
│       └── train.py           # Training script
├── configs/
│   └── refnet_base.yaml       # Default configuration
├── data/samples/              # Training data (ignored by git)
├── models/                   # Saved models (ignored by git)
├── docs/
│   ├── design.md              # Design documentation
│   ├── api.md                 # API reference
│   ├── data_format.md         # Data format specification
│   ├── training.md            # Training guide
│   └── examples.md            # Usage examples
├── experiments/               # Experiment notes
├── scripts/
│   ├── generate_synthetic_data.py
│   ├── evaluate.py            # Model evaluation
│   └── sanity_check.py        # Overfitting test
└── pyproject.toml             # Project dependencies

• PyTorch >= 2.0.0
• PyYAML >= 6.0.0
• scikit-learn >= 1.0.0 (for evaluation metrics)
• numpy >= 1.21.0

• Code & Scripts: Apache-2.0 - Free to use, modify, distribute
• Documentation: CC BY 4.0 - Free to use with attribution
• Model Weights: OpenRAIL-M - Research use only, commercial use requires separate license
• Examples & Tutorials: Apache-2.0 - Free to use and modify

For commercial licensing of model weights, contact: [email protected]

Development Dependencies:

• pytest (testing)
• black (code formatting)
• flake8 (linting)
• mypy (type checking)

# Install in development mode
pip install -e .

# Run training
python src/refnet/training/train.py

python scripts/generate_synthetic_data.py

See experiments/ directory for:

• EXP-09: Self model drift analysis
• EXP-10: Hallucination guard implementation

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

See LICENSE file for details.

• Design documentation: docs/design.md
• Data schema: src/refnet/data/schema.md

If you use RefNet in your research, please cite:

Nenad Bursać (2025).
RefNet: Neural Architecture for Structured Reflection in Cognitive AI Systems.
Zenodo. https://doi.org/10.5281/zenodo.17953624