CONTRIBUTING.md

Contributing to FlowLLM

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

Development Setup

1. Prerequisites

   • Node.js 18 or higher
   • npm 9 or higher
   • Git

2. Clone the repository

   git clone https://github.com/flowllm/flowllm.git
   cd flowllm

3. Install dependencies

   npm install

4. Build all packages

   npm run build

5. Run tests

   npm test

Project Structure

flowllm/
├── packages/
│   ├── core/          # Core agent framework
│   ├── providers/     # LLM provider implementations
│   ├── mcp/           # MCP integration
│   └── flowllm/       # Main SDK package
├── examples/          # Usage examples
├── docs/             # Documentation
└── tests/            # Integration tests

Development Workflow

1. Create a feature branch

   git checkout -b feature/your-feature-name

2. Make your changes

   • Write code following the existing style
   • Add tests for new functionality
   • Update documentation as needed

3. Run tests and linting

   npm test
   npm run lint

4. Commit your changes

   git commit -m "feat: add new feature"

   Follow Conventional Commits:

   • feat: New feature
   • fix: Bug fix
   • docs: Documentation changes
   • test: Test additions or changes
   • refactor: Code refactoring
   • chore: Maintenance tasks

5. Push and create a pull request

   git push origin feature/your-feature-name

Coding Guidelines

TypeScript

• Use TypeScript for all code
• Enable strict mode
• Provide type annotations for public APIs
• Avoid any types when possible

Code Style

• Use 2 spaces for indentation
• Use single quotes for strings
• Add semicolons
• Follow existing patterns in the codebase

Testing

• Write unit tests for all new functionality
• Aim for 80%+ code coverage
• Use descriptive test names
• Test both success and error cases

Documentation

• Add JSDoc comments for public APIs
• Update README files when adding features
• Provide examples for new functionality
• Keep documentation clear and concise

Adding a New Provider

To add support for a new LLM provider:

1. Create a new file in packages/providers/src/
2. Implement the LLMProvider interface
3. Add cost tracking and token counting
4. Write tests
5. Export from packages/providers/src/index.ts
6. Update documentation

Example:

export class NewProvider implements LLMProvider {
  public readonly name = 'new-provider';
  
  async chat(messages: Message[], config: LLMConfig): Promise<LLMResponse> {
    // Implementation
  }
  
  async *stream(messages: Message[], config: LLMConfig): AsyncIterable<StreamChunk> {
    // Implementation
  }
  
  countTokens(text: string, model: string): number {
    // Implementation
  }
  
  getMaxTokens(model: string): number {
    // Implementation
  }
  
  getCostPerToken(model: string): { prompt: number; completion: number } {
    // Implementation
  }
}

Pull Request Process

1. Ensure all tests pass
2. Update documentation
3. Add examples if applicable
4. Request review from maintainers
5. Address feedback
6. Once approved, your PR will be merged

Code Review Guidelines

When reviewing PRs, consider:

• Correctness: Does the code work as intended?
• Tests: Are there adequate tests?
• Documentation: Is the code well-documented?
• Style: Does it follow project conventions?
• Performance: Are there any performance concerns?
• Security: Are there any security issues?

Getting Help

• Documentation: Check docs/README.md
• Examples: See examples/
• Issues: Browse GitHub Issues
• Discussions: Join GitHub Discussions

License

By contributing to FlowLLM, you agree that your contributions will be licensed under the MIT License.