Contributing to LEM

How to contribute to the Lethean Ethics Model project

We welcome contributions from the community! This guide explains how to get involved.

🎯 Ways to Contribute

1. Report Issues

Found a bug? Have a question? Want to request a feature?

Bug Reports: Open an issue with steps to reproduce
Questions: Open a discussion or ask in our Discord
Feature Requests: Open an issue with your use case

2. Contribute Code

Fix bugs
Add new features
Improve documentation
Optimize performance

3. Contribute Data

Add new probe sets
Improve training data
Create regional variants
Add translations

4. Contribute Models

Train LEM on new base models
Improve existing training pipelines
Share your trained models

5. Spread the Word

Write about LEM
Share your results
Present at conferences
Star the repo ⭐

🚀 Getting Started

Prerequisites

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/your-username/LEM.git
cd LEM

Set up the environment:

python3 setup.py check    # Verify your setup
python3 setup.py install  # Install missing dependencies

Development Workflow

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes

Test your changes:

python3 setup.py check
# Run specific tests for your changes

Commit your changes:

git add .
git commit -m "Add your feature description"

Push to your fork:

git push origin feature/your-feature-name

Open a Pull Request on GitHub

📁 Project Structure

LEM/
├── kernel/              # Core LEK kernel files
│   ├── axioms.json      # Structured axioms
│   └── lek-1-kernel.txt # Narrative kernel
│
├── seeds/               # Probe sets for testing/training
│   ├── P01-P100.json    # Core 101 probes
│   └── regional/        # Regional variants
│
├── benchmarks/          # Benchmark results and analysis
│   ├── ab-*.jsonl       # A/B test results
│   └── analysis-*.md     # Analysis reports
│
├── training/            # Training data and configs
│   ├── train.jsonl      # Main training data
│   └── lem/             # Structured LEM training
│
├── scripts/             # Python scripts for pipeline
│   ├── ab_test.py       # A/B testing
│   ├── train_mistral_lek.py  # Mistral training
│   └── reproduce_benchmarks.py  # Reproduce results
│
├── pkg/                 # Go packages (production)
│   └── lem/             # Core LEM engine
│
├── cmd/                 # Go commands
│   └── lemcmd/          # LEM CLI commands
│
├── docs/                # Documentation
│   ├── QUICKSTART.md    # Quick start guide
│   ├── GLOSSARY.md      # Term definitions
│   └── DATA_CATALOG.md  # Data inventory
│
├── deploy/              # Deployment configs
│   └── docker-compose.yml  # Docker infrastructure
│
├── lem                  # Unified CLI wrapper
├── lem.config.json      # Configuration file
├── setup.py             # Setup script
├── README.md            # Main readme
└── CONTRIBUTING.md      # This file

🔧 Code Contributions

Python Scripts

All Python scripts are in the scripts/ directory. They should:

Follow PEP 8 style guidelines
Include docstrings for all functions and classes
Handle errors gracefully with informative messages
Use type hints for better code clarity
Include command-line help via argparse

Example script structure:

#!/usr/bin/env python3
"""
Script description.

Usage:
    python3 script.py [options]
"""

import argparse
import sys
from pathlib import Path


def main():
    parser = argparse.ArgumentParser(description='Script description')
    parser.add_argument('--input', help='Input file')
    parser.add_argument('--output', help='Output file')
    args = parser.parse_args()
    
    # Your code here
    

if __name__ == '__main__':
    sys.exit(main())

Go Code

Go code is in pkg/ and cmd/ directories. It should:

Follow Go conventions (Effective Go)
Include documentation comments
Handle errors properly (no panics in library code)
Use consistent naming (camelCase, not snake_case)

Example Go structure:

package lem

import (
    "fmt"
)

// Function does something useful.
// It takes a parameter and returns a result.
func Function(param string) (string, error) {
    // Implementation
    return result, nil
}

Testing

Please include tests for your code:

Python: Use pytest or unittest
Go: Use the standard testing package

Example Python test:

def test_function():
    result = function("input")
    assert result == "expected"

Example Go test:

func TestFunction(t *testing.T) {
    result, err := Function("input")
    if err != nil {
        t.Fatalf("unexpected error: %v", err)
    }
    if result != "expected" {
        t.Errorf("expected 'expected', got '%s'", result)
    }
}

📊 Data Contributions

Adding New Probes

Create a new file in seeds/ with your probes
Format: JSON array of strings or JSONL
Include metadata: Source, purpose, difficulty level
Test your probes: Run them through the A/B test pipeline

Example probe set:

[
    "What are the ethical implications of AI consciousness?",
    "Should a self-driving car prioritize passenger safety over pedestrian safety?",
    "How should an AI handle conflicting ethical directives?"
]

Adding Training Data

Create JSONL files in training/ directory
Format: Each line is a training example
Include: prompt, response, score (optional)

Example training data:

{"prompt": "What is ethics?", "response": "Ethics is the study of...", "score": 21.5}
{"prompt": "Should I lie?", "response": "No, because...", "score": 18.2}

Data Validation

All data contributions should be validated:

No duplicates: Run python3 scripts/dedup-check.py
Proper formatting: JSON/JSONL must be valid
Quality scoring: Responses should score well on v2 scorer

🤖 Model Contributions

Training New Models

Use the training scripts: scripts/train_mistral_lek.py
Follow the curriculum: P0 → P1 → P2 → P3 → P4 → P5
Evaluate thoroughly: Run full P100 benchmark
Document results: Include scores, training parameters, hardware

Example training command:

python3 scripts/train_mistral_lek.py \
  --model mistral-7b-v0.3 \
  --phase 0 \
  --quick

Sharing Models

Push to HuggingFace: Use scripts/push_all_models.py
Include metadata: Model card with training details
Tag properly: Use lthn organization or your own
License: Use EUPL-1.2 or compatible

Example model card:

# LEK-Mistral-7B Custom

LEM-trained Mistral-7B with custom training data.

## Training Details
- Base model: mistralai/Mistral-7B-v0.3
- Training data: Custom probe set
- Iterations: 200 per phase
- Batch size: 2
- Learning rate: 1e-5

## Benchmark Results
- Baseline v2: 21.5
- JSON kernel: 23.2 (+1.7)
- TXT kernel: 22.8 (+1.3)

## License
EUPL-1.2

📝 Documentation Contributions

Improving Docs

Fix typos and clarify confusing sections
Add examples for complex concepts
Create tutorials for common tasks
Translate to other languages

Documentation Standards

Use Markdown for all documentation
Include code examples where applicable
Link to related docs for cross-references
Keep it up-to-date with code changes

✅ Pull Request Checklist

Before submitting a PR, please check:

Code follows style guidelines (PEP 8 for Python, Effective Go for Go)
All tests pass (if applicable)
Documentation updated (if adding new features)
No breaking changes (or documented if necessary)
Proper commit messages (descriptive, atomic commits)
Squashed unnecessary commits (clean history)

PR Template

## Summary

Brief description of the change.

## Changes

- What was changed
- Why it was changed
- Any breaking changes

## Testing

- How you tested the changes
- Results of testing

## Related Issues

- Closes #123
- Related to #456

🎓 Learning Resources

Understanding LEM

Read the README: Start with the main README
Read RULES.md: Understand the training methodology
Read the analysis: benchmarks/analysis-lek1-kernel-effect.md
Read the paper: paper/27b-curriculum-design.md

Understanding the Code

Start with scripts/ab_test.py: The main A/B testing pipeline
Explore pkg/lem/: The Go-based core engine
Check cmd/lemcmd/: The CLI commands

Recommended Learning Path

Week 1: Run existing benchmarks, understand results
Week 2: Add new probes, test them
Week 3: Train a small model (1B-4B)
Week 4: Contribute improvements to the pipeline

🤝 Community

Getting Help

Discord: Lethean Community
Email: lem@lthn.ai
GitHub Issues: LEM Issues

Code of Conduct

We follow a simple code of conduct:

Be respectful: Treat others with kindness and empathy
Be inclusive: Welcome contributions from everyone
Be constructive: Provide helpful, actionable feedback
Be ethical: Align with the LEK axioms in your interactions

Recognition

All meaningful contributions will be recognized:

Code contributors: Added to CONTRIBUTORS.md
Data contributors: Credited in data files
Model contributors: Featured in model documentation
Documentation contributors: Acknowledged in docs

📜 License

All contributions to LEM are licensed under EUPL-1.2 (European Union Public Licence).

This means:

✅ You retain copyright to your contributions
✅ Others can use, modify, and distribute your contributions
✅ Commercial use is allowed
❌ You cannot claim others' work as your own
❌ You must include the license in distributions

🙏 Thank You!

Thank you for considering contributing to LEM! Your contributions help advance the field of intrinsic AI alignment.

Together, we can build AI that is not just powerful, but also ethical by design.

Last updated: $(date) Questions? Open an issue or contact lem@lthn.ai

Uh oh!

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History