CONTRIBUTING.md

Contributing Guidelines

Thank you for considering contributing to AI Agents from Scratch!

Project Philosophy

This repository teaches AI agent fundamentals by building from scratch. Every contribution should support this learning mission.

Core Principles:

• Clarity over cleverness - Code should be easy to understand
• Fundamentals first - No black boxes or magic
• Progressive learning - Each example builds on the previous
• Local-first - No API dependencies

Types of Contributions

Bug Reports

Found something broken? Open an issue with:

• Which example (intro/, react-agent/, etc.)
• What you expected vs. what happened
• Your environment (Node version, OS, model used)
• Steps to reproduce

Documentation Improvements

• Typos and grammar fixes
• Clearer explanations
• Better code comments
• Additional examples in documentation
• Diagrams and visualizations

New Examples

Want to add a new agent pattern? Great! Please:

1. Open an issue first - let's discuss if it fits
2. Follow the existing structure:

• pattern-name/pattern-name.js - Working code
• pattern-name/CODE.md - Detailed code walkthrough
• pattern-name/CONCEPT.md - Why it matters, use cases

3. Keep it simple and well-commented
4. Test thoroughly with at least one model

Code Improvements

• Performance optimizations (with benchmarks)
• Better error handling
• Clearer variable names
• More helpful console output

What We're Not Looking For

• Framework integrations (LangChain, etc.) - this repo teaches what they do
• Cloud API examples - keep it local
• Production features (monitoring, scaling) - this is educational
• Complex abstractions - keep it beginner-friendly

Contribution Process

1. Fork the repository
2. Create a branch: git checkout -b fix/issue-description
3. Make changes and test thoroughly
4. Commit with clear messages: git commit -m "Fix: clarify ReAct loop explanation"
5. Push: git push origin fix/issue-description
6. Open a Pull Request with:

• Clear title
• Description of what changed and why
• Which issue it addresses (if any)

Code Standards

• Use clear, descriptive variable names
• Add comments explaining why, not just what
• Follow existing code style (no linter, just match the patterns)
• Keep examples self-contained (one file when possible)
• Test with Qwen or Llama models before submitting

Documentation Standards

• Use clear, simple language
• Explain concepts before code
• Include diagrams where helpful (ASCII art is fine!)
• Provide real-world use cases
• Link to related examples

Example Structure

new-pattern/
├── new-pattern.js # The working code
├── CODE.md # Line-by-line walkthrough
└── CONCEPT.md # High-level explanation

CODE.md should include:

• Prerequisites
• Step-by-step code breakdown
• How to run it
• Expected output

CONCEPT.md should include:

• What problem it solves
• Why this pattern matters
• Real-world applications
• Simple diagrams

Getting Help

• Not sure if your idea fits? Open an issue to discuss
• Stuck on implementation? Ask in the issue
• Want to pair on something? Reach out!

License

By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).

Recognition

All contributors will be recognized in the README. Thank you for helping others learn!

---

Questions? Open an issue or reach out. Happy to help guide your contribution!