Contributing to @falai/agent

First off, thank you for considering contributing to @falai/agent! 🎉

It's people like you that make @falai/agent such a great tool for building AI agents.

Code of Conduct
How Can I Contribute?
Getting Started
Development Workflow
Style Guidelines
Commit Guidelines
Pull Request Process

Code of Conduct

This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. We pledge to make participation in our project a harassment-free experience for everyone.

Our Standards

Positive behavior includes:

Using welcoming and inclusive language
Being respectful of differing viewpoints
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members

Unacceptable behavior includes:

Harassment, trolling, or insulting/derogatory comments
Public or private harassment
Publishing others' private information without permission
Other conduct which could reasonably be considered inappropriate

Tool System Overview

@falai/agent features a unified Tool interface that supports both simple return values and complex ToolResult patterns:

Unified Tool Interface

interface Tool<TContext = unknown, TData = unknown, TResult = unknown> {
  id: string;
  name?: string;
  description?: string;
  parameters?: unknown;
  handler: (
    context: ToolContext<TContext, TData>,
    args?: Record<string, unknown>
  ) => Promise<TResult | ToolResult<TResult, TContext, TData>> | TResult | ToolResult<TResult, TContext, TData>;
}

Tool Creation Methods

agent.addTool() - Direct addition to agent scope
agent.tool.register() - Registry for ID-based reference
agent.tool.create() - Create without adding to scope
Pattern helpers - createDataEnrichment(), createValidation(), etc.

Return Value Flexibility

// Simple return value
handler: async () => "Simple result"

// Complex ToolResult object
handler: async () => ({
  data: "Result data",
  success: true,
  contextUpdate: { lastAction: "completed" }
})

How Can I Contribute?

🐛 Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

When submitting a bug report, include:

A clear and descriptive title
Steps to reproduce the behavior
Expected vs actual behavior
Code samples or test cases
Your environment (Node/Bun version, OS, TypeScript version)
Screenshots if applicable

Template:

**Description**
A clear description of the bug.

**To Reproduce**

1. Create an agent with '...'
2. Call method '...'
3. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**

- Node/Bun version:
- TypeScript version:
- @falai/agent version:
- OS:

**Additional Context**
Any other relevant information.

💡 Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues.

When suggesting an enhancement, include:

A clear and descriptive title
The current behavior vs proposed behavior
Why this enhancement would be useful
Examples of how it would work
Potential implementation approach (optional)

📝 Documentation Improvements

Documentation is crucial! Feel free to:

Fix typos or unclear wording
Add examples
Improve API documentation
Create tutorials or guides
Translate documentation

🔨 Code Contributions

Want to add a feature or fix a bug? Great!

Getting Started

Prerequisites

Node.js 18+ or Bun 1.0+
Git
TypeScript knowledge
Familiarity with AI/LLM concepts (helpful but not required)

Fork & Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/falai.git
cd falai

# Add upstream remote
git remote add upstream https://github.com/falai-dev/agent.git

Install Dependencies

# Using bun (recommended)
bun install

# Or using npm
npm install

Set Up Development Environment

# Create .env file
echo "GEMINI_API_KEY=your_test_key_here" > .env

# Build the project
bun run build

# Run type checking
bun typecheck

# Run linting
bun lint

Development Workflow

1. Create a Branch

# Update your main branch
git checkout main
git pull upstream main

# Create a feature branch
git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation only
refactor/ - Code refactoring
test/ - Adding tests
chore/ - Maintenance tasks

2. Make Your Changes

Project Structure

src/
├── types/          # Type definitions
├── core/           # Core classes (Agent, Route, etc.)
├── providers/      # AI provider implementations
├── utils/          # Utility functions
├── constants/      # Constants
└── index.ts        # Public exports

Key Principles

DRY - Don't Repeat Yourself
Modular - Keep code organized and reusable
Type-Safe - Use TypeScript properly
Tested - Add tests for new features
Documented - Update docs for public APIs

3. Write Tests

# Run tests (when implemented)
bun test

# Run tests in watch mode
bun test --watch

Test Guidelines:

Unit tests for individual functions
Integration tests for features
Add tests before fixing bugs
Aim for >80% coverage

4. Check Your Code

# Type checking
bun typecheck

# Linting
bun lint

# Fix linting issues automatically
bun lint:fix

# Build to ensure no errors
bun run build

5. Commit Your Changes

Follow Conventional Commits:

git add .
git commit -m "feat: add support for routes"

Commit types:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
style: - Code style changes (formatting, etc.)
refactor: - Code refactoring
test: - Adding or updating tests
chore: - Maintenance tasks

Examples:

git commit -m "feat: add retry logic to AI provider"
git commit -m "fix: resolve route reference memory leak"
git commit -m "docs: update API reference for Agent class"
git commit -m "refactor: simplify prompt builder logic"

6. Push and Create PR

# Push your branch
git push origin feature/your-feature-name

# Create a Pull Request on GitHub

Style Guidelines

TypeScript Style

// ✅ Good
interface UserContext {
  userId: string;
  userName: string;
}

const agent = new Agent<UserContext>({
  name: "SupportBot",
  provider: provider,
});

// ❌ Bad
interface user_context {
  user_id: string;
  user_name: string;
}

const agent = new Agent<any>({
  name: "SupportBot",
  provider: provider,
});

Code Style

Use TypeScript - No any types unless absolutely necessary
camelCase for variables and functions
PascalCase for classes and interfaces
UPPER_SNAKE_CASE for constants
Explicit return types for public APIs
JSDoc comments for public methods
No console.log in production code (use proper logging)

File Organization

/**
 * Brief description of the file
 */

// Imports - group by: external, internal types, internal code
import { ExternalLib } from "external-lib";
import type { MyType } from "@types/mytype";
import { MyClass } from "@core/MyClass";

// Constants
const DEFAULT_VALUE = 10;

// Types (if not in types/)
interface LocalType {
  // ...
}

// Main code
export class MyClass {
  // ...
}

Documentation Style

/**
 * Creates a new agent with the specified configuration.
 *
 * @example
 * ```typescript
 * const agent = new Agent({
 *   name: "MyBot",
 *   provider: provider,
 * });
 * ```
 *
 * @param options - Configuration options for the agent
 * @returns A new Agent instance
 */
export class Agent<TContext = unknown> {
  constructor(options: AgentOptions<TContext>) {
    // ...
  }
}

Commit Guidelines

Commit Message Format

<type>(<scope>): <subject>

<body>

<footer>

Example:

feat(agent): add support for custom AI providers

- Implement AiProvider interface
- Add OpenAI provider example
- Update documentation

Closes #123

Scopes

agent - Agent core
route - Route/Journey DSL
tools - Tool system
types - Type definitions
providers - AI providers
docs - Documentation
examples - Example files

Pull Request Process

Before Submitting

Code compiles without errors (bun run build)
All tests pass (bun test)
Linting passes (bun lint)
Type checking passes (bun typecheck)
Documentation updated (if needed)
Examples added (if new feature)
CHANGELOG updated (for significant changes)

PR Template

## Description

Brief description of changes.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?

Describe the tests you ran.

## Checklist

- [ ] My code follows the style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

## Related Issues

Closes #(issue number)

Review Process

Automated Checks - CI must pass
Code Review - At least one maintainer approval required
Testing - Reviewers may test your changes
Discussion - Address feedback and questions
Merge - Once approved, maintainers will merge

Questions?

💬 Open a Discussion
🐛 Report an Issue
📧 Email: (if you want to add your email)

Recognition

Contributors will be:

Listed in our README
Mentioned in release notes
Part of our growing community! 🎉

Thank you for contributing to @falai/agent!

Made with ❤️ for the community

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History