From f5a092190b226a6723718d7680aa689f1d2b64bc Mon Sep 17 00:00:00 2001 From: Ashish Patel Date: Sat, 11 Oct 2025 10:52:30 +0530 Subject: [PATCH] Add/update CONTRIBUTION.md and add LICENSE (MIT) --- CONTRIBUTION.md | 190 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 142 insertions(+), 48 deletions(-) diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md index 363d8a7..f119211 100644 --- a/CONTRIBUTION.md +++ b/CONTRIBUTION.md @@ -1,76 +1,170 @@ # Contributing to 500-AI-Agents-Projects -Thank you for your interest in contributing to 500-AI-Agents-Projects! This project is a collection of AI agent projects and examples; contributions from the community are welcome. This document explains how to contribute, what we expect, and the process for submitting changes. +Welcome — this repository collects 500 AI agent projects, templates, demos, and integrations. Thank you for helping grow a practical, reproducible, and responsible catalog of agent work. This document is tuned to the AI-agent focus of the project: reproducibility, model/data hygiene, evaluation, and safety. -## Table of Contents +Quick summary +- Add small, runnable, well-documented agent examples and templates. +- Prefer reproducible demos and small checkpoints or external download scripts. +- Follow the folder schema and metadata so projects are discoverable and automatable. +- Pay attention to license, data provenance, and ethical/safety notes. -- How to contribute -- Code style and standards -- Branching and commits -- Issues -- Pull requests -- Tests -- Review and merge process -- Reporting security issues -- Code of conduct +--- -## How to contribute +## What to contribute +- New agent projects (single- or multi-agent; code, notebooks, or demos). +- Templates/boilerplates for agent types (reactive, planning-based, learning agents, RL, LLM-based, etc.). +- Integrations (environments, simulators, observability / logging tools). +- Shared tooling (evaluation harnesses, metrics, benchmark suites, dataset loaders). +- Docs, reproducible experiments, visualization utilities, or lightweight datasets (or links to them). -There are several ways to contribute: +If your contribution is large (new category, many projects, major refactor) please open an issue first to coordinate placement and naming. -- Open an issue to report bugs, request features, or propose new project ideas. -- Submit a pull request (PR) with improvements, bug fixes, documentation updates, or new projects. -- Help review open PRs and provide constructive feedback. +--- -Before submitting substantial changes (like new project additions), please open an issue first to discuss the idea with maintainers. +## Project folder requirements (must-have) +Each agent project added must include the following at the top level of its folder: -## Code style and standards +- README.md — concise description, intended use-case, quick start with exact commands, expected output, and runtime (CPU/GPU/time). +- LICENSE or a note referencing repository root LICENSE (see root LICENSE). +- requirements.txt, pyproject.toml, or environment.yml (pin critical dependency versions). +- One or more runnable examples (script or notebook) that reproduce the core behavior. + - Provide minimal example(s) that run in <10 minutes on a modest machine where possible. +- tests/ or a smoke-test script with instructions to run them. +- metadata.yaml or metadata.json (see example below). +- small models / datasets should be included only if tiny. Prefer external hosting (Hugging Face, S3, Google Drive) with a download script. -- Follow consistent formatting. Where appropriate, add or update linting configuration files (e.g., .prettierrc, .eslintrc) so automatic formatting is used. -- Write clear, concise code with comments where necessary. -- Keep project-level READMEs up to date. Each project folder should include a README.md describing purpose, setup, usage, and license. +Example metadata schema (recommended) +```yaml +title: quick-chatbot-agent +author: Your Name +language: python +tags: + - llm + - agent + - rl +license: MIT +datasets: + - name: example-dialogs + url: https://... +entrypoint: run_demo.py +requirements: requirements.txt +``` -## Branching and commits +--- -- Fork the repository and create a feature branch off main. Name branches as feature/short-description or fix/short-description. -- Keep changes focused and small; one logical change per PR makes review easier. -- Use descriptive commit messages. Prefer the format: +## Naming & layout conventions +- Folder names: lowercase, hyphen-separated (e.g., multi-agent-pursuit). +- Place one logical project per folder. +- Keep demos and notebooks near the code: demo.ipynb and run_demo.py in the project root. +- Avoid committing large binaries. Use .gitattributes or .gitignore to keep repository clean. - type: short description +--- - Where type is one of: feat, fix, docs, style, refactor, test, chore +## Reproducibility & experiments +- Include seed values, environment variables, and exact dependency versions. +- Provide a minimal run command and expected output sample. +- For stochastic experiments, include evaluation scripts and deterministic seeds or checkpoints. +- If results require large compute or private data, include a small reproducible “toy” example that demonstrates the same pipeline on tiny inputs. -Example: "feat: add sample multi-agent example" +--- -## Issues +## Models, datasets & large files policy +- Don’t add large datasets or model checkpoints directly. Instead: + - Provide a download script (download.sh / download.py) that fetches artifacts from a stable host (Hugging Face, S3, Zenodo). + - Document the expected location/path after download. +- Clearly state dataset licenses, attribution, and any usage restrictions. +- When linking to external model weights provide their license and any fine-tuning provenance. -- Search existing issues before opening a new one to avoid duplicates. -- Use clear titles and provide steps to reproduce if reporting bugs. Include environment details and relevant logs or errors. -- For feature requests, explain the motivation and suggested behavior. +--- -## Pull requests +## Code style, documentation & tests +- Python: follow PEP 8, add a linter config (.flake8, pyproject.toml with [tool.black] or similar). +- JS/TS: provide ESLint/Prettier configs where relevant. +- Document complex algorithms with short docstrings and references. +- Add unit or integration tests when possible. Include a lightweight smoke test that CI can run quickly. -- Link related issues in the PR description using "Fixes #" when appropriate. -- Describe what the PR does, why it is needed, and any tradeoffs. -- Update or add tests and documentation as needed. -- Keep PRs draft if you want feedback before finalizing. +--- -## Tests +## Evaluation & metrics +- Include an evaluation script that produces metrics (accuracy, reward, latency). +- State measurement conditions (hardware, seeds). +- Where applicable, include latency and memory cost alongside performance metrics. -- Where applicable, include automated tests for new features or bug fixes. -- Describe test steps in the PR if automated tests are not available. +--- -## Review and merge process +## CI / GitHub Actions recommendations +- If adding workflows, put them under .github/workflows and ensure expensive jobs are optional or use small inputs. +- Recommended checks: lint, unit tests, smoke demos. Heavy training jobs should be omitted or gated/opt-in. -- Maintainers will review PRs and may request changes. Address review comments and push follow-up commits. -- Once approved, a maintainer will merge the PR. We use a non-fast-forward merge strategy to preserve PR history when appropriate. +--- -## Reporting security issues +## PR process and checklist +Before opening a PR: +- [ ] Fork and create a branch: feat/ or fix/ +- [ ] Update README and metadata +- [ ] Include tests or a smoke-test demonstration +- [ ] Ensure no secrets or private data are included +- [ ] Confirm license compatibility for added assets -If you discover a security vulnerability, please do NOT open a public issue. Instead, contact the repository owner directly or use GitHub's private security advisory feature. +PR description should include: +- What changed and why +- How to run the example(s) and tests +- Links to related issues or external artifacts (datasets, model hosts) -## Code of conduct +Suggested minimal PR template (add to .github/PULL_REQUEST_TEMPLATE.md if helpful): +```markdown +## Summary +Short description of change -By participating in this project, you agree to follow a respectful and inclusive code of conduct. Be constructive and courteous in issues and reviews. +## How to run +1. pip install -r requirements.txt +2. python run_demo.py ---- \ No newline at end of file +## Checklist +- [ ] README updated +- [ ] metadata.yaml added/updated +- [ ] smoke test included +``` + +--- + +## Security, secrets & responsible disclosure +- Never commit secrets, private keys, or API tokens. +- If you discover a security vulnerability, do not open a public issue. Contact maintainers privately (see repository contact info) or use GitHub's private security advisory. + +--- + +## Ethics, fairness & safety +AI agents can amplify harms. When contributing: +- Include an explicit "Ethical considerations" or "Safety notes" section in the README if the agent interacts with people, makes decisions, or processes personal data. +- State potential biases, failure modes, and appropriate usage guidance. +- Avoid shipping models trained on clearly disallowed data (private or scraped personal content without consent). +- Prefer human-in-the-loop defaults for high-risk demos and clearly mark such demos as not production-ready. + +--- + +## Licensing and attribution +- Respect upstream licenses for models, code, and datasets. Include attribution and license text where required. +- If the project uses third-party models/datasets, list their license and link to the source. + +--- + +## Communication & review +- Maintainers will review PRs and may request changes. Please reply to review comments and push updates. +- For large or disruptive changes, maintainers may ask for staged PRs to ease review. + +--- + +## Contributor support & contact +If you need early feedback: +- Open an issue describing your planned contribution with the following: summary, folder name, and minimal example of what you plan to add. +- For urgent or private matters, use the contact method listed in the repository (owner profile / repo settings). + +--- + +## Code of Conduct +By contributing, you agree to the project's Code of Conduct. Be respectful, constructive, and collaborative. + +--- + +Thank you for contributing to 500-AI-Agents-Projects — your examples, templates, and tools make the agent community stronger and more reproducible.