brainy/CONTRIBUTING.md

Contributing to Brainy

Thank you for your interest in contributing to Brainy! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct:

• Be respectful and inclusive
• Welcome newcomers and help them get started
• Focus on constructive criticism
• Respect differing viewpoints and experiences

How to Contribute

Reporting Issues

Before creating an issue, please check existing issues to avoid duplicates.

When creating an issue, include:

• Clear, descriptive title
• Detailed description of the problem
• Steps to reproduce
• Expected vs actual behavior
• System information (OS, Node version, Brainy version)
• Code examples if applicable

Suggesting Features

Feature requests are welcome! Please provide:

• Clear use case
• Proposed API/interface
• Examples of how it would work
• Any potential challenges or considerations

Pull Requests

Before Starting

1. Check existing issues and PRs
2. Open an issue to discuss significant changes
3. Fork the repository
4. Create a feature branch from main

Development Setup

Quick Setup (Recommended):

# Clone your fork
git clone https://github.com/your-username/brainy.git
cd brainy

# Run setup script (installs all dependencies including Rust)
./scripts/setup-dev.sh

Manual Setup:

# Clone your fork
git clone https://github.com/your-username/brainy.git
cd brainy

# Install system dependencies (Ubuntu/Debian)
sudo apt-get install -y build-essential pkg-config libssl-dev

# Install Rust (for WASM embedding engine)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup target add wasm32-unknown-unknown
cargo install wasm-pack

# Install Node.js dependencies
npm install

# Build Candle WASM embedding engine
npm run build:candle

# Build TypeScript
npm run build

# Run tests
npm test

Making Changes

1. Follow the code style

   • TypeScript for all source code
   • Clear variable and function names
   • Comments for complex logic
   • JSDoc for public APIs

2. Write tests

   • Add tests for new features
   • Update tests for changes
   • Ensure all tests pass

3. Update documentation

   • Update README if needed
   • Add/update API documentation
   • Include examples

Commit Guidelines

Follow conventional commits format:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• perf: Performance improvements
• test: Test changes
• chore: Build/tooling changes

Examples:

feat(triple): add graph traversal depth limit
fix(storage): handle concurrent write conflicts
docs(api): update search method documentation

Submitting PR

1. Push to your fork
2. Create PR against main branch
3. Fill out PR template
4. Ensure CI checks pass
5. Wait for review

Testing

Running Tests

# Run all tests
npm test

# Run specific test file
npm test tests/core.test.ts

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

Writing Tests

import { describe, it, expect } from 'vitest'
import { Brainy } from '../src'

describe('Feature Name', () => {
  it('should do something specific', async () => {
    const brain = new Brainy()
    await brain.init()
    
    // Test implementation
    const result = await brain.search("test")
    
    expect(result).toBeDefined()
    expect(result.length).toBeGreaterThan(0)
  })
})

Architecture Guidelines

Adding New Features

1. Check existing functionality

   • Review ARCHITECTURE.md
   • Check if similar features exist
   • Consider if it should be an augmentation

2. Design considerations

   • Maintain backward compatibility
   • Consider performance impact
   • Think about all storage adapters
   • Plan for extensibility

3. Implementation checklist

   • Core functionality
   • Tests (unit and integration)
   • Documentation
   • TypeScript types
   • Examples
   • Performance benchmarks (if applicable)

Creating Augmentations

Augmentations extend Brainy's functionality:

import { BrainyAugmentation } from '../types'

export class MyAugmentation extends BrainyAugmentation {
  name = 'MyAugmentation'
  
  async onInit(brain: Brainy): Promise<void> {
    // Initialize augmentation
  }
  
  async onAdd(item: any, brain: Brainy): Promise<any> {
    // Process before adding
    return item
  }
  
  async onSearch(query: any, results: any[], brain: Brainy): Promise<any[]> {
    // Process search results
    return results
  }
}

Performance Considerations

• Use batch operations where possible
• Implement caching strategically
• Consider memory usage
• Profile performance impacts
• Add benchmarks for critical paths

Documentation

API Documentation

Use JSDoc for all public APIs:

/**
 * Searches for similar items using vector similarity
 * @param query - Search query (text or vector)
 * @param options - Search options
 * @returns Array of search results with scores
 * @example
 * ```typescript
 * const results = await brain.search("machine learning", { limit: 10 })
 * ```
 */
async search(query: string | Vector, options?: SearchOptions): Promise<SearchResult[]> {
  // Implementation
}

Examples

Add examples for new features:

// examples/feature-name.ts
import { Brainy } from 'brainy'

async function exampleUsage() {
  const brain = new Brainy()
  await brain.init()
  
  // Show feature usage
  // Include comments explaining what's happening
  // Handle errors appropriately
}

exampleUsage().catch(console.error)

Release Process

1. Version bump: Follow semantic versioning
2. Update CHANGELOG: Document all changes
3. Run tests: Ensure all tests pass
4. Build: Generate distribution files
5. Tag: Create git tag for version
6. Publish: Release to npm

Getting Help

• Discord: Join our community
• Issues: Ask questions on GitHub
• Discussions: Share ideas and get feedback

Recognition

Contributors will be recognized in:

• CHANGELOG.md for their contributions
• README.md contributors section
• GitHub contributors page

Thank you for contributing to Brainy! 🧠