diff --git a/CONTRIBUTING_GUIDELINES.md b/CONTRIBUTING_GUIDELINES.md new file mode 100644 index 0000000..5b2670a --- /dev/null +++ b/CONTRIBUTING_GUIDELINES.md @@ -0,0 +1,91 @@ +# 🤝 Contributing Guide + +Welcome to contribute to the AgentScope Sample Agents project! Please follow this guide to ensure efficient collaboration. + + +--- + +# 📁 Directory Structure Requirements +All examples must be organized by functionality. The structure follows the root README.md layout: +```bash +agentscope-samples/ +├── browser_use/ # Browser automation examples +│ ├── agent_browser/ # Pure Python browser agent +│ └── browser_use_fullstack_runtime/ # Full-stack runtime version +├── deep_research/ # Deep research examples +│ ├── agent_deep_research/ +│ └── qwen_langgraph_search_fullstack_runtime/ +├── games/ +│ └── game_werewolves/ # Werewolf game +├── conversational_agents/ # Conversational applications +│ ├── chatbot/ +│ └── multiagent_conversation/ +├── functionality/ # Functional examples +│ ├── long_term_memory_mem0/ +│ └── stream_printing_messages/ +└── CONTRIBUTING_GUIDELINES.md +``` + + +--- + +# 📥 Submitting a Pull Request (PR) + +### 1. **Directory Placement** +- **Location**: + Choose an existing subdirectory (e.g., `browser_use/`、`games/`), or create a new one (update the **Example List** table in the root `README.md`) +- **File Naming**: + - Example files: `feature_description.py`(如 `chatbot_multi_turn.py`) + - Test files: `test_feature_description.py` + +### 2. **Write a Detailed README** +- **Subdirectory `README.md`**: + Include the following to ensure reproducibility: + ```markdown + ## Example Name (e.g., Multi-turn Chatbot) + + ### 📌 Description + Demonstrates the implementation of multi-turn conversations. + + ### 📦 Dependencies + ```bash + pip install -r requirements.txt + ``` + +### 🚀 Run Command +```bash +python chatbot_multi_turn.py +``` + + +- **Root `README.md`**: +Update the **Example List** table with links to new examples. + +### 3. **Dependency Management** +- **Each Subdirectory Requires `requirements.txt`**: +List only dependencies needed for that example: + +```txt +openai==0.27.0 +pandas==2.0.0 +``` + +### 4. **Code Formatting** +- **Install `pre-commit`**: +```bash +pip install pre-commit +pre-commit install +pre-commit run --all-files +# Fix any formatting errors (e.g., indentation, line length) +``` + + +### PR Checklist +- [ ] Example placed in the correct subdirectory (e.g., `browser_use/`、`games/`) +- [ ] Subdirectory includes `README.md` and `requirements.txt` +- [ ] Code formatted with `pre-commit` +- [ ] New test cases cover core functionality +- [ ] Root `README.md` updated with the new example +- [ ] PR title is clear (e.g., `Add multi-turn chatbot example`) + +--- diff --git a/README.md b/README.md index 673cdb5..13de567 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ It includes **context management** and **secure sandboxing**, and can be used wi ## 📌 Example List -| Category | Example Folder | Uses AgentScope | Uses Runtime | Description | +| Category | Example Folder | Uses AgentScope | Use AgentScope Runtime | Description | | ----------------------- |-------------------------------------------------------| --------------- | ------------ |--------------------------------------------------| | **Browser Use** | browser_use/agent_browser | ✅ | ❌ | Command-line browser automation using AgentScope | | | browser_use/browser_use_fullstack_runtime | ✅ | ✅ | Full-stack browser automation with UI & sandbox | @@ -121,7 +121,7 @@ If you: Please: 1. Read the sample-specific `README.md`. -2. File a [GitHub Issue](https://github.com/agentscope-ai/agentscope-samples/issues). +2. File a [GitHub Issue](https://github.com/agentscope-ai/agentscope-samples/blob/main/issues). 3. Join the community discussions. ------ @@ -135,13 +135,13 @@ We welcome contributions such as: - Documentation improvements - Code contributions -See the [Contributing Guidelines](https://github.com/agentscope-ai/agentscope-samples/CONTRIBUTING.md) for details. +See the [Contributing Guidelines](https://github.com/agentscope-ai/agentscope-samples/blob/main/CONTRIBUTING_GUIDELINES.md) for details. ------ ## 📄 License -This project is licensed under the **Apache 2.0 License** – see the [LICENSE](https://github.com/agentscope-ai/agentscope-samples/LICENSE) file for details. +This project is licensed under the **Apache 2.0 License** – see the [LICENSE](https://github.com/agentscope-ai/agentscope-samples/blob/main/LICENSE) file for details. ------ diff --git a/functionality/__init__.py b/functionality/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/games/__init__.py b/games/__init__.py deleted file mode 100644 index e69de29..0000000