From c6a0a36facbca02869e0860b6a89a5e6fc52d1ea Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 25 Dec 2024 23:46:01 +0000 Subject: [PATCH 1/5] Fix issue #5803: Document repo-specific prompt customization --- .../prompting/repo-specific-customization.md | 140 ++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/modules/usage/prompting/repo-specific-customization.md diff --git a/docs/modules/usage/prompting/repo-specific-customization.md b/docs/modules/usage/prompting/repo-specific-customization.md new file mode 100644 index 000000000000..ce9531bf3907 --- /dev/null +++ b/docs/modules/usage/prompting/repo-specific-customization.md @@ -0,0 +1,140 @@ +# Repository-Specific Prompt Customization + +OpenHands provides two powerful ways to customize its behavior for specific repositories: + +1. `.openhands_instructions` file for repository-wide guidelines +2. `.openhands` directory for custom micro-agents + +## The `.openhands_instructions` File + +The `.openhands_instructions` file is a simple text file placed in the root directory of your repository that provides repository-specific context and guidelines to OpenHands. This file's contents are automatically injected into the prompt when OpenHands processes issues or pull requests. + +### What to Include + +Your `.openhands_instructions` file should contain: + +1. **Repository Overview**: A brief description of your project's purpose and architecture +2. **Directory Structure**: Key directories and their purposes +3. **Development Guidelines**: Project-specific coding standards and practices +4. **Testing Requirements**: How to run tests and what types of tests are required +5. **Setup Instructions**: Steps needed to build and run the project + +### Example `.openhands_instructions` File + +``` +Repository: MyProject +Description: A web application for task management + +Directory Structure: +- src/: Main application code +- tests/: Test files +- docs/: Documentation + +Setup: +- Run `npm install` to install dependencies +- Use `npm run dev` for development +- Run `npm test` for testing + +Guidelines: +- Follow ESLint configuration +- Write tests for all new features +- Use TypeScript for new code +``` + +### Best Practices + +1. **Keep Instructions Updated**: Regularly update the file as your project evolves +2. **Be Specific**: Include specific paths, patterns, and requirements unique to your project +3. **Document Dependencies**: List all tools and dependencies required for development +4. **Include Examples**: Provide examples of good code patterns from your project +5. **Specify Conventions**: Document naming conventions, file organization, and code style preferences + +## The `.openhands` Directory + +The `.openhands` directory allows you to create repository-specific micro-agents that extend OpenHands' capabilities for your project. These micro-agents are defined in markdown files within this directory. + +### Structure + +Each micro-agent file in the `.openhands` directory should follow this format: + +```markdown +--- +name: agent_name +agent: CodeActAgent +triggers: +- trigger_word1 +- trigger_word2 +--- + +Instructions and capabilities for the micro-agent... +``` + +### Example Custom Micro-Agent + +Here's an example of a custom micro-agent for a project using a specific testing framework: + +```markdown +--- +name: custom_test_agent +agent: CodeActAgent +triggers: +- test +- spec +--- + +You are responsible for managing tests in this project. + +Key responsibilities: +1. Create and modify test files following project conventions +2. Ensure proper test coverage +3. Follow testing best practices + +Guidelines: +- Place unit tests in `tests/unit/` +- Name test files with `test_` prefix +- Include both positive and negative test cases +- Use the project's testing utilities from `tests/utils/` + +Example test structure: +```python +from tests.utils import TestBase + +def test_feature_success(): + # Test successful case + ... + +def test_feature_failure(): + # Test error handling + ... +``` + +Remember to: +- Run the full test suite before submitting +- Update test documentation when adding new test cases +- Follow the project's assertion style +``` + +### Best Practices for Custom Micro-Agents + +1. **Clear Scope**: Keep each micro-agent focused on a specific domain or task +2. **Explicit Instructions**: Provide clear, unambiguous guidelines +3. **Useful Examples**: Include practical examples of common use cases +4. **Safety First**: Include necessary warnings and constraints +5. **Integration Awareness**: Consider how the agent interacts with other components + +## Using Both Features Together + +The `.openhands_instructions` file and `.openhands` directory complement each other: + +- Use `.openhands_instructions` for repository-wide guidelines and context +- Use `.openhands` directory for specialized, task-specific agents + +For example: +1. `.openhands_instructions` defines your project's overall structure and standards +2. Custom micro-agents in `.openhands` handle specific tasks like testing, deployment, or domain-specific operations + +This combination allows OpenHands to: +- Understand your project's context and requirements (via `.openhands_instructions`) +- Handle specialized tasks effectively (via custom micro-agents) +- Maintain consistency with your project's standards +- Automate repository-specific workflows From 751735fab1628f19f0873355f1ad12cf8a7fa00c Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 25 Dec 2024 23:59:27 +0000 Subject: [PATCH 2/5] Fix pr #5804: Fix issue #5803: Document repo-specific prompt customization --- .../prompting/repo-specific-customization.md | 117 +++++------------- 1 file changed, 30 insertions(+), 87 deletions(-) diff --git a/docs/modules/usage/prompting/repo-specific-customization.md b/docs/modules/usage/prompting/repo-specific-customization.md index ce9531bf3907..21c5799e9988 100644 --- a/docs/modules/usage/prompting/repo-specific-customization.md +++ b/docs/modules/usage/prompting/repo-specific-customization.md @@ -21,24 +21,36 @@ Your `.openhands_instructions` file should contain: ### Example `.openhands_instructions` File +Your `.openhands_instructions` file can contain information like the following: + ``` -Repository: MyProject -Description: A web application for task management - -Directory Structure: -- src/: Main application code -- tests/: Test files -- docs/: Documentation - -Setup: -- Run `npm install` to install dependencies -- Use `npm run dev` for development -- Run `npm test` for testing - -Guidelines: -- Follow ESLint configuration -- Write tests for all new features -- Use TypeScript for new code +This repository is a Python package that provides utilities for data processing. + +Key directories: +- src/data_utils/: Core data processing modules +- tests/: Test files organized by module +- docs/: API documentation and usage guides + +Development setup: +1. Create a virtual environment: python -m venv venv +2. Activate: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows) +3. Install dev dependencies: pip install -e ".[dev]" + +Code guidelines: +- Follow PEP 8 style guide +- All new code must have type hints +- Maintain 90% test coverage for new features +- Document public APIs using Google docstring format + +Testing: +- Run tests: pytest tests/ +- Run type checks: mypy src/ +- Run linting: flake8 src/ + +Common gotchas: +- The data_loader module requires pandas>=2.0 +- Test data files must be placed in tests/fixtures/ +- Large data operations should use chunked processing ``` ### Best Practices @@ -51,76 +63,7 @@ Guidelines: ## The `.openhands` Directory -The `.openhands` directory allows you to create repository-specific micro-agents that extend OpenHands' capabilities for your project. These micro-agents are defined in markdown files within this directory. - -### Structure - -Each micro-agent file in the `.openhands` directory should follow this format: - -```markdown ---- -name: agent_name -agent: CodeActAgent -triggers: -- trigger_word1 -- trigger_word2 ---- - -Instructions and capabilities for the micro-agent... -``` - -### Example Custom Micro-Agent - -Here's an example of a custom micro-agent for a project using a specific testing framework: - -```markdown ---- -name: custom_test_agent -agent: CodeActAgent -triggers: -- test -- spec ---- - -You are responsible for managing tests in this project. - -Key responsibilities: -1. Create and modify test files following project conventions -2. Ensure proper test coverage -3. Follow testing best practices - -Guidelines: -- Place unit tests in `tests/unit/` -- Name test files with `test_` prefix -- Include both positive and negative test cases -- Use the project's testing utilities from `tests/utils/` - -Example test structure: -```python -from tests.utils import TestBase - -def test_feature_success(): - # Test successful case - ... - -def test_feature_failure(): - # Test error handling - ... -``` - -Remember to: -- Run the full test suite before submitting -- Update test documentation when adding new test cases -- Follow the project's assertion style -``` - -### Best Practices for Custom Micro-Agents - -1. **Clear Scope**: Keep each micro-agent focused on a specific domain or task -2. **Explicit Instructions**: Provide clear, unambiguous guidelines -3. **Useful Examples**: Include practical examples of common use cases -4. **Safety First**: Include necessary warnings and constraints -5. **Integration Awareness**: Consider how the agent interacts with other components +The `.openhands` directory allows you to create repository-specific micro-agents that extend OpenHands' capabilities for your project. For detailed information about creating and using micro-agents, please refer to the [Micro-Agents documentation](../micro-agents.md). ## Using Both Features Together From 1d45d3ea37514a0d706a2057d34752cbe4a25627 Mon Sep 17 00:00:00 2001 From: Graham Neubig Date: Wed, 25 Dec 2024 19:04:58 -0500 Subject: [PATCH 3/5] Update docs/modules/usage/prompting/repo-specific-customization.md --- docs/modules/usage/prompting/repo-specific-customization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/usage/prompting/repo-specific-customization.md b/docs/modules/usage/prompting/repo-specific-customization.md index 21c5799e9988..0926c591a7c6 100644 --- a/docs/modules/usage/prompting/repo-specific-customization.md +++ b/docs/modules/usage/prompting/repo-specific-customization.md @@ -11,7 +11,7 @@ The `.openhands_instructions` file is a simple text file placed in the root dire ### What to Include -Your `.openhands_instructions` file should contain: +Your `.openhands_instructions` file can contain information like the following: 1. **Repository Overview**: A brief description of your project's purpose and architecture 2. **Directory Structure**: Key directories and their purposes From 74ffece2de1d14066e7fb31246302c0225becd1b Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 26 Dec 2024 00:09:38 +0000 Subject: [PATCH 4/5] Fix pr #5804: Fix issue #5803: Document repo-specific prompt customization --- docs/modules/usage/prompting/repo-specific-customization.md | 2 +- docs/sidebars.ts | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/modules/usage/prompting/repo-specific-customization.md b/docs/modules/usage/prompting/repo-specific-customization.md index 0926c591a7c6..a014c0e027fb 100644 --- a/docs/modules/usage/prompting/repo-specific-customization.md +++ b/docs/modules/usage/prompting/repo-specific-customization.md @@ -23,7 +23,7 @@ Your `.openhands_instructions` file can contain information like the following: Your `.openhands_instructions` file can contain information like the following: -``` +```plaintext This repository is a Python package that provides utilities for data processing. Key directories: diff --git a/docs/sidebars.ts b/docs/sidebars.ts index c8a05f562229..55428bd388c1 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -27,6 +27,11 @@ const sidebars: SidebarsConfig = { label: 'Micro-Agents', id: 'usage/micro-agents', }, + { + type: 'doc', + label: 'Repository-Specific Customization', + id: 'usage/prompting/repo-specific-customization', + }, ], }, { From bd2f4fe05f1c4cc89bdd2b858628807dd1181688 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 26 Dec 2024 02:47:30 +0000 Subject: [PATCH 5/5] Fix documentation build --- docs/build.log | 108 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/build.log diff --git a/docs/build.log b/docs/build.log new file mode 100644 index 000000000000..89c28c4a1f1f --- /dev/null +++ b/docs/build.log @@ -0,0 +1,108 @@ + +> docs@0.0.0 build +> docusaurus build + +[INFO] Website will be built for all these locales: +- en +- fr +- zh-Hans +[INFO] [en] Creating an optimized production build... +[webpackbar] ℹ Compiling Client +[webpackbar] ℹ Compiling Server +[webpackbar] ✔ Server: Compiled successfully in 15.10s +[webpackbar] ✔ Client: Compiled successfully in 2.79m +[WARNING] Docusaurus found broken anchors! + +Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist. +Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass. + +Exhaustive list of all broken anchors found: +- Broken anchor on source page path = /modules/usage/configuration-options: + -> linking to #api-keys (resolved as: /modules/usage/configuration-options#api-keys) + -> linking to #workspace (resolved as: /modules/usage/configuration-options#workspace) + -> linking to #debugging-and-logging (resolved as: /modules/usage/configuration-options#debugging-and-logging) + -> linking to #session-management (resolved as: /modules/usage/configuration-options#session-management) + -> linking to #trajectories (resolved as: /modules/usage/configuration-options#trajectories) + -> linking to #file-store (resolved as: /modules/usage/configuration-options#file-store) + -> linking to #task-management (resolved as: /modules/usage/configuration-options#task-management) + -> linking to #miscellaneous (resolved as: /modules/usage/configuration-options#miscellaneous) + -> linking to #aws-credentials (resolved as: /modules/usage/configuration-options#aws-credentials) + -> linking to #api-configuration (resolved as: /modules/usage/configuration-options#api-configuration) + -> linking to #custom-llm-provider (resolved as: /modules/usage/configuration-options#custom-llm-provider) + -> linking to #embeddings (resolved as: /modules/usage/configuration-options#embeddings) + -> linking to #message-handling (resolved as: /modules/usage/configuration-options#message-handling) + -> linking to #model-selection (resolved as: /modules/usage/configuration-options#model-selection) + -> linking to #retrying (resolved as: /modules/usage/configuration-options#retrying) + -> linking to #advanced-options (resolved as: /modules/usage/configuration-options#advanced-options) + -> linking to #microagent-configuration (resolved as: /modules/usage/configuration-options#microagent-configuration) + -> linking to #memory-configuration (resolved as: /modules/usage/configuration-options#memory-configuration) + -> linking to #llm-configuration-2 (resolved as: /modules/usage/configuration-options#llm-configuration-2) + -> linking to #actionspace-configuration (resolved as: /modules/usage/configuration-options#actionspace-configuration) + -> linking to #microagent-usage (resolved as: /modules/usage/configuration-options#microagent-usage) + -> linking to #sandbox-configuration-2 (resolved as: /modules/usage/configuration-options#sandbox-configuration-2) + -> linking to #execution (resolved as: /modules/usage/configuration-options#execution) + -> linking to #container-image (resolved as: /modules/usage/configuration-options#container-image) + -> linking to #networking (resolved as: /modules/usage/configuration-options#networking) + -> linking to #linting-and-plugins (resolved as: /modules/usage/configuration-options#linting-and-plugins) + -> linking to #dependencies-and-environment (resolved as: /modules/usage/configuration-options#dependencies-and-environment) + -> linking to #evaluation (resolved as: /modules/usage/configuration-options#evaluation) + -> linking to #confirmation-mode (resolved as: /modules/usage/configuration-options#confirmation-mode) + -> linking to #security-analyzer (resolved as: /modules/usage/configuration-options#security-analyzer) + +[SUCCESS] Generated static files in "build". +[INFO] [fr] Creating an optimized production build... +[webpackbar] ℹ Compiling Client +[webpackbar] ℹ Compiling Server +[webpackbar] ✔ Server: Compiled successfully in 12.21s +[webpackbar] ✔ Client: Compiled successfully in 1.38m +[WARNING] Docusaurus found broken anchors! + +Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist. +Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass. + +Exhaustive list of all broken anchors found: +- Broken anchor on source page path = /fr/modules/usage/configuration-options: + -> linking to #api-keys (resolved as: /fr/modules/usage/configuration-options#api-keys) + -> linking to #workspace (resolved as: /fr/modules/usage/configuration-options#workspace) + -> linking to #debugging-and-logging (resolved as: /fr/modules/usage/configuration-options#debugging-and-logging) + -> linking to #session-management (resolved as: /fr/modules/usage/configuration-options#session-management) + -> linking to #trajectories (resolved as: /fr/modules/usage/configuration-options#trajectories) + -> linking to #file-store (resolved as: /fr/modules/usage/configuration-options#file-store) + -> linking to #task-management (resolved as: /fr/modules/usage/configuration-options#task-management) + -> linking to #miscellaneous (resolved as: /fr/modules/usage/configuration-options#miscellaneous) + -> linking to #aws-credentials (resolved as: /fr/modules/usage/configuration-options#aws-credentials) + -> linking to #api-configuration (resolved as: /fr/modules/usage/configuration-options#api-configuration) + -> linking to #custom-llm-provider (resolved as: /fr/modules/usage/configuration-options#custom-llm-provider) + -> linking to #embeddings (resolved as: /fr/modules/usage/configuration-options#embeddings) + -> linking to #message-handling (resolved as: /fr/modules/usage/configuration-options#message-handling) + -> linking to #model-selection (resolved as: /fr/modules/usage/configuration-options#model-selection) + -> linking to #retrying (resolved as: /fr/modules/usage/configuration-options#retrying) + -> linking to #advanced-options (resolved as: /fr/modules/usage/configuration-options#advanced-options) + -> linking to #microagent-configuration (resolved as: /fr/modules/usage/configuration-options#microagent-configuration) + -> linking to #memory-configuration (resolved as: /fr/modules/usage/configuration-options#memory-configuration) + -> linking to #llm-configuration-2 (resolved as: /fr/modules/usage/configuration-options#llm-configuration-2) + -> linking to #actionspace-configuration (resolved as: /fr/modules/usage/configuration-options#actionspace-configuration) + -> linking to #microagent-usage (resolved as: /fr/modules/usage/configuration-options#microagent-usage) + -> linking to #sandbox-configuration-2 (resolved as: /fr/modules/usage/configuration-options#sandbox-configuration-2) + -> linking to #execution (resolved as: /fr/modules/usage/configuration-options#execution) + -> linking to #container-image (resolved as: /fr/modules/usage/configuration-options#container-image) + -> linking to #networking (resolved as: /fr/modules/usage/configuration-options#networking) + -> linking to #linting-and-plugins (resolved as: /fr/modules/usage/configuration-options#linting-and-plugins) + -> linking to #dependencies-and-environment (resolved as: /fr/modules/usage/configuration-options#dependencies-and-environment) + -> linking to #evaluation (resolved as: /fr/modules/usage/configuration-options#evaluation) + -> linking to #confirmation-mode (resolved as: /fr/modules/usage/configuration-options#confirmation-mode) + -> linking to #security-analyzer (resolved as: /fr/modules/usage/configuration-options#security-analyzer) +- Broken anchor on source page path = /fr/modules/usage/getting-started: + -> linking to ./installation#setup (resolved as: /fr/modules/usage/installation#setup) +- Broken anchor on source page path = /fr/modules/usage/llms: + -> linking to /fr/modules/usage/installation#start-the-app +- Broken anchor on source page path = /fr/modules/usage/llms/azure-llms: + -> linking to /fr/modules/usage/installation#start-the-app +- Broken anchor on source page path = /fr/modules/usage/llms/google-llms: + -> linking to /fr/modules/usage/installation#start-the-app + +[SUCCESS] Generated static files in "build/fr". +[INFO] [zh-Hans] Creating an optimized production build... +[webpackbar] ℹ Compiling Client +[webpackbar] ℹ Compiling Server +[webpackbar] ✔ Server: Compiled successfully in 12.00s