Skip to content

Commit f5a0921

Browse files
ashishpatel26ashishpatel26
committed
Add/update CONTRIBUTION.md and add LICENSE (MIT)
1 parent b9a11ac commit f5a0921

File tree

1 file changed

+158
-64
lines changed

1 file changed

+158
-64
lines changed

‎CONTRIBUTION.md‎

Lines changed: 158 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,170 @@
11
# Contributing to 500-AI-Agents-Projects
22

3-
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.
3+
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.
4+
5+
Quick summary
6+
- Add small, runnable, well-documented agent examples and templates.
7+
- Prefer reproducible demos and small checkpoints or external download scripts.
8+
- Follow the folder schema and metadata so projects are discoverable and automatable.
9+
- Pay attention to license, data provenance, and ethical/safety notes.
10+
11+
---
12+
13+
## What to contribute
14+
- New agent projects (single- or multi-agent; code, notebooks, or demos).
15+
- Templates/boilerplates for agent types (reactive, planning-based, learning agents, RL, LLM-based, etc.).
16+
- Integrations (environments, simulators, observability / logging tools).
17+
- Shared tooling (evaluation harnesses, metrics, benchmark suites, dataset loaders).
18+
- Docs, reproducible experiments, visualization utilities, or lightweight datasets (or links to them).
19+
20+
If your contribution is large (new category, many projects, major refactor) please open an issue first to coordinate placement and naming.
21+
22+
---
23+
24+
## Project folder requirements (must-have)
25+
Each agent project added must include the following at the top level of its folder:
26+
27+
- README.md — concise description, intended use-case, quick start with exact commands, expected output, and runtime (CPU/GPU/time).
28+
- LICENSE or a note referencing repository root LICENSE (see root LICENSE).
29+
- requirements.txt, pyproject.toml, or environment.yml (pin critical dependency versions).
30+
- One or more runnable examples (script or notebook) that reproduce the core behavior.
31+
- Provide minimal example(s) that run in <10 minutes on a modest machine where possible.
32+
- tests/ or a smoke-test script with instructions to run them.
33+
- metadata.yaml or metadata.json (see example below).
34+
- small models / datasets should be included only if tiny. Prefer external hosting (Hugging Face, S3, Google Drive) with a download script.
35+
36+
Example metadata schema (recommended)
37+
```yaml
38+
title: quick-chatbot-agent
39+
author: Your Name <[email protected]>
40+
language: python
41+
tags:
42+
- llm
43+
- agent
44+
- rl
45+
license: MIT
46+
datasets:
47+
- name: example-dialogs
48+
url: https://...
49+
entrypoint: run_demo.py
50+
requirements: requirements.txt
51+
```
52+
53+
---
54+
55+
## Naming & layout conventions
56+
- Folder names: lowercase, hyphen-separated (e.g., multi-agent-pursuit).
57+
- Place one logical project per folder.
58+
- Keep demos and notebooks near the code: demo.ipynb and run_demo.py in the project root.
59+
- Avoid committing large binaries. Use .gitattributes or .gitignore to keep repository clean.
60+
61+
---
62+
63+
## Reproducibility & experiments
64+
- Include seed values, environment variables, and exact dependency versions.
65+
- Provide a minimal run command and expected output sample.
66+
- For stochastic experiments, include evaluation scripts and deterministic seeds or checkpoints.
67+
- If results require large compute or private data, include a small reproducible “toy” example that demonstrates the same pipeline on tiny inputs.
68+
69+
---
70+
71+
## Models, datasets & large files policy
72+
- Don’t add large datasets or model checkpoints directly. Instead:
73+
- Provide a download script (download.sh / download.py) that fetches artifacts from a stable host (Hugging Face, S3, Zenodo).
74+
- Document the expected location/path after download.
75+
- Clearly state dataset licenses, attribution, and any usage restrictions.
76+
- When linking to external model weights provide their license and any fine-tuning provenance.
77+
78+
---
79+
80+
## Code style, documentation & tests
81+
- Python: follow PEP 8, add a linter config (.flake8, pyproject.toml with [tool.black] or similar).
82+
- JS/TS: provide ESLint/Prettier configs where relevant.
83+
- Document complex algorithms with short docstrings and references.
84+
- Add unit or integration tests when possible. Include a lightweight smoke test that CI can run quickly.
85+
86+
---
87+
88+
## Evaluation & metrics
89+
- Include an evaluation script that produces metrics (accuracy, reward, latency).
90+
- State measurement conditions (hardware, seeds).
91+
- Where applicable, include latency and memory cost alongside performance metrics.
92+
93+
---
94+
95+
## CI / GitHub Actions recommendations
96+
- If adding workflows, put them under .github/workflows and ensure expensive jobs are optional or use small inputs.
97+
- Recommended checks: lint, unit tests, smoke demos. Heavy training jobs should be omitted or gated/opt-in.
98+
99+
---
100+
101+
## PR process and checklist
102+
Before opening a PR:
103+
- [ ] Fork and create a branch: feat/<short-desc> or fix/<short-desc>
104+
- [ ] Update README and metadata
105+
- [ ] Include tests or a smoke-test demonstration
106+
- [ ] Ensure no secrets or private data are included
107+
- [ ] Confirm license compatibility for added assets
108+
109+
PR description should include:
110+
- What changed and why
111+
- How to run the example(s) and tests
112+
- Links to related issues or external artifacts (datasets, model hosts)
113+
114+
Suggested minimal PR template (add to .github/PULL_REQUEST_TEMPLATE.md if helpful):
115+
```markdown
116+
## Summary
117+
Short description of change
118+
119+
## How to run
120+
1. pip install -r requirements.txt
121+
2. python run_demo.py
122+
123+
## Checklist
124+
- [ ] README updated
125+
- [ ] metadata.yaml added/updated
126+
- [ ] smoke test included
127+
```
128+
129+
---
130+
131+
## Security, secrets & responsible disclosure
132+
- Never commit secrets, private keys, or API tokens.
133+
- 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.
134+
135+
---
136+
137+
## Ethics, fairness & safety
138+
AI agents can amplify harms. When contributing:
139+
- Include an explicit "Ethical considerations" or "Safety notes" section in the README if the agent interacts with people, makes decisions, or processes personal data.
140+
- State potential biases, failure modes, and appropriate usage guidance.
141+
- Avoid shipping models trained on clearly disallowed data (private or scraped personal content without consent).
142+
- Prefer human-in-the-loop defaults for high-risk demos and clearly mark such demos as not production-ready.
4143
5-
## Table of Contents
144+
---
6145
7-
- How to contribute
8-
- Code style and standards
9-
- Branching and commits
10-
- Issues
11-
- Pull requests
12-
- Tests
13-
- Review and merge process
14-
- Reporting security issues
15-
- Code of conduct
146+
## Licensing and attribution
147+
- Respect upstream licenses for models, code, and datasets. Include attribution and license text where required.
148+
- If the project uses third-party models/datasets, list their license and link to the source.
16149
17-
## How to contribute
150+
---
18151
19-
There are several ways to contribute:
152+
## Communication & review
153+
- Maintainers will review PRs and may request changes. Please reply to review comments and push updates.
154+
- For large or disruptive changes, maintainers may ask for staged PRs to ease review.
20155
21-
- Open an issue to report bugs, request features, or propose new project ideas.
22-
- Submit a pull request (PR) with improvements, bug fixes, documentation updates, or new projects.
23-
- Help review open PRs and provide constructive feedback.
156+
---
24157
25-
Before submitting substantial changes (like new project additions), please open an issue first to discuss the idea with maintainers.
158+
## Contributor support & contact
159+
If you need early feedback:
160+
- Open an issue describing your planned contribution with the following: summary, folder name, and minimal example of what you plan to add.
161+
- For urgent or private matters, use the contact method listed in the repository (owner profile / repo settings).
26162
27-
## Code style and standards
163+
---
28164
29-
- Follow consistent formatting. Where appropriate, add or update linting configuration files (e.g., .prettierrc, .eslintrc) so automatic formatting is used.
30-
- Write clear, concise code with comments where necessary.
31-
- Keep project-level READMEs up to date. Each project folder should include a README.md describing purpose, setup, usage, and license.
165+
## Code of Conduct
166+
By contributing, you agree to the project's Code of Conduct. Be respectful, constructive, and collaborative.
32167
33-
## Branching and commits
168+
---
34169
35-
- Fork the repository and create a feature branch off main. Name branches as feature/short-description or fix/short-description.
36-
- Keep changes focused and small; one logical change per PR makes review easier.
37-
- Use descriptive commit messages. Prefer the format:
38-
39-
type: short description
40-
41-
Where type is one of: feat, fix, docs, style, refactor, test, chore
42-
43-
Example: "feat: add sample multi-agent example"
44-
45-
## Issues
46-
47-
- Search existing issues before opening a new one to avoid duplicates.
48-
- Use clear titles and provide steps to reproduce if reporting bugs. Include environment details and relevant logs or errors.
49-
- For feature requests, explain the motivation and suggested behavior.
50-
51-
## Pull requests
52-
53-
- Link related issues in the PR description using "Fixes #<issue-number>" when appropriate.
54-
- Describe what the PR does, why it is needed, and any tradeoffs.
55-
- Update or add tests and documentation as needed.
56-
- Keep PRs draft if you want feedback before finalizing.
57-
58-
## Tests
59-
60-
- Where applicable, include automated tests for new features or bug fixes.
61-
- Describe test steps in the PR if automated tests are not available.
62-
63-
## Review and merge process
64-
65-
- Maintainers will review PRs and may request changes. Address review comments and push follow-up commits.
66-
- Once approved, a maintainer will merge the PR. We use a non-fast-forward merge strategy to preserve PR history when appropriate.
67-
68-
## Reporting security issues
69-
70-
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.
71-
72-
## Code of conduct
73-
74-
By participating in this project, you agree to follow a respectful and inclusive code of conduct. Be constructive and courteous in issues and reviews.
75-
76-
---
170+
Thank you for contributing to 500-AI-Agents-Projects — your examples, templates, and tools make the agent community stronger and more reproducible.

0 commit comments

Comments
 (0)