soulforge-framework/CONTRIBUTING.md

A TypeScript framework for building digital beings with persistent memory, emotions, and identity. Create AI companions that grow, learn, and form genuine relationships.

# Contributing to SoulForge Framework

Thank you for your interest in contributing to SoulForge! This document outlines the process for contributing to this project.

## 🌟 Ways to Contribute

- 🐛 Report bugs and issues
- 💡 Suggest new features or improvements
- 📝 Improve documentation
- 🧪 Add tests and examples
- 💻 Submit code improvements
- 🎨 Create new personality templates
- 🎮 Build example applications

## 🚀 Getting Started

1. **Fork the repository**
2. **Clone your fork:**
   ```bash
   git clone https://github.com/yourusername/soulforge-framework.git
   cd soulforge-framework
   ```

3. **Install dependencies:**
   ```bash
   npm install
   ```

4. **Build the project:**
   ```bash
   npm run build
   ```

5. **Run tests:**
   ```bash
   npm test
   ```

## 🛠️ Development Guidelines

### Code Style
- Use TypeScript with strict typing
- Follow the existing code structure and patterns
- Include comprehensive JSDoc comments
- Use descriptive variable and function names
- Follow the fluent API pattern for configuration

### Framework Philosophy
- Focus on creating "entities" not just chatbots
- Emphasize psychological realism and cognitive science principles
- Build systems that evolve and adapt over time
- Prioritize emotional intelligence and empathy

### Core Systems to Maintain
1. **Soul** - Main entity class with fluent API
2. **MemorySystem** - Episodic, semantic, and emotional memory
3. **MoodEngine** - Dynamic emotions with internal monologue
4. **PersonalitySystem** - Big Five traits, MBTI, psychological archetypes

## 📝 Pull Request Process

1. **Create a feature branch:**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes:**
   - Write clean, well-documented code
   - Add tests for new functionality
   - Update documentation as needed

3. **Test your changes:**
   ```bash
   npm run build
   npm test
   npm run demo:chat  # Test with examples
   ```

4. **Commit your changes:**
   ```bash
   git commit -m "feat: add your feature description"
   ```

5. **Push to your fork:**
   ```bash
   git push origin feature/your-feature-name
   ```

6. **Create a Pull Request:**
   - Provide a clear description of changes
   - Reference any related issues
   - Include screenshots for UI changes

## 🧪 Testing Guidelines

- Test personality consistency across interactions
- Verify memory recall across time periods
- Test emotional response appropriateness
- Ensure personality adaptation works gradually
- Validate multi-user conversation handling

## 📚 Documentation

When adding new features:
- Update the README.md if needed
- Add JSDoc comments to all public methods
- Create examples demonstrating usage
- Update type definitions

## 🐛 Bug Reports

Please include:
- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Environment details (Node.js version, OS)
- Code examples if applicable

## 💡 Feature Requests

When suggesting features:
- Explain the use case and benefits
- Consider how it fits with the framework philosophy
- Propose the API design if relevant
- Discuss potential implementation approaches

## 🏷️ Commit Message Convention

Use conventional commits:
- `feat:` - New features
- `fix:` - Bug fixes
- `docs:` - Documentation changes
- `style:` - Code style changes
- `refactor:` - Code refactoring
- `test:` - Adding tests
- `chore:` - Maintenance tasks

## 📋 Code of Conduct

- Be respectful and inclusive
- Focus on constructive feedback
- Help newcomers learn and contribute
- Celebrate diverse perspectives and approaches

## 🎯 Areas for Contribution

### High Priority
- Additional personality templates
- More sophisticated memory consolidation algorithms
- Enhanced emotional intelligence capabilities
- Performance optimizations
- Mobile SDK development

### Examples and Applications
- Healthcare and therapy applications
- Educational tutoring systems
- Gaming and entertainment NPCs
- Creative writing assistants
- Customer service bots

### Documentation
- Video tutorials
- API reference improvements
- Best practices guides
- Deployment examples

Thank you for helping make SoulForge better! 🌟