CHECKPOINT: Brainy 2.0 API refactor - pre-fixes state

Current state: - Unified augmentation system to BrainyAugmentation interface - Changed methods to specific noun/verb naming (addNoun, getNoun, etc) - Made old methods private - Combined getNouns into single unified method - Neural API exists and is complete - Triple Intelligence uses correct Brainy operators (not MongoDB) Issues identified: - Documentation incorrectly shows MongoDB operators (code is correct) - Need to ensure all features are properly exposed - Need to verify nothing was lost in simplification This commit serves as a rollback point before applying fixes.
2025-08-25 09:52:32 -07:00 · 2025-08-25 09:52:32 -07:00 · 26c7d61185
commit 26c7d61185
279 changed files with 177945 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,275 @@
+# 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
+
+```bash
+# Clone your fork
+git clone https://github.com/your-username/brainy.git
+cd brainy
+
+# Install dependencies
+npm install
+
+# Build the project
+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:
+```bash
+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
+
+```bash
+# 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
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { BrainyData } from '../src'
+
+describe('Feature Name', () => {
+  it('should do something specific', async () => {
+    const brain = new BrainyData()
+    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:
+
+```typescript
+import { BrainyAugmentation } from '../types'
+
+export class MyAugmentation extends BrainyAugmentation {
+  name = 'MyAugmentation'
+  
+  async onInit(brain: BrainyData): Promise<void> {
+    // Initialize augmentation
+  }
+  
+  async onAdd(item: any, brain: BrainyData): Promise<any> {
+    // Process before adding
+    return item
+  }
+  
+  async onSearch(query: any, results: any[], brain: BrainyData): 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:
+
+```typescript
+/**
+ * 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:
+
+```typescript
+// examples/feature-name.ts
+import { BrainyData } from 'brainy'
+
+async function exampleUsage() {
+  const brain = new BrainyData()
+  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! 🧠