Merge pull request #391 from jupyter-naas/385-refactor-update-readmemd

feat: refactor docs

Author: jravenel

.cursorrules

@@ -0,0 +1,171 @@
+# Contributing
+
+Thank you for your interest in contributing to ABI! This document outlines the process and best practices for contributing to the project.
+
+## Code of Conduct
+
+We are committed to providing a welcoming and inclusive experience for everyone. Please read our Code of Conduct before participating in our community.
+
+## Getting Started
+
+1. **Fork the repository** or clone locally
+2. **Set up environment variables** by copying `.env.example` to `.env` and adding your credentials
+3. **Run the project** using `make`
+
+## Development Workflow
+
+1. Pick an issue to work on on [GitHub](https://github.com/jupyter-naas/abi/issues)
+
+2. Create a new branch for your feature or bugfix:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+3. Make your changes following the project's [coding standards](#coding-standards)
+
+4. Add tests for your changes
+
+5. Ensure all tests pass:
+   ```bash
+   make test
+   ```
+
+6. Update documentation as needed
+
+7. Commit your changes with clear, descriptive commit messages:
+   ```bash
+   git commit -m "Add feature: description of the changes"
+   ```
+
+8. Push your branch to your fork and [submit a pull request](#pull-request-process)
+
+## Project Structure
+
+ABI follows a modular architecture:
+
+```
+src/
+├── core/           # Core system modules
+│   └── modules/    # Core functionality organized by domain
+├── custom/         # Custom modules for specific use cases
+│   └── modules/    # Custom functionality organized by domain
+└── marketplace/    # Marketplace for modules to be used in the engine
+```
+
+Each module can contain:
+- `assistants/`: LLM agent configurations
+- `workflows/`: Business logic implementations
+- `pipelines/`: Data transformation processes
+- `integrations/`: Service connectors
+- `models/`: Data models and schemas
+- `ontologies/`: Semantic data definitions
+- `tests/`: Module-specific tests
+
+## Coding Standards
+
+### General Guidelines
+
+1. **Follow functional programming principles**
+   - Use pure functions when possible
+   - Minimize side effects
+   - Use immutable data structures
+   - Leverage higher-order functions and function composition
+
+2. **Keep functions focused and small**
+   - Each function should do one thing well
+   - Aim for functions that are less than 25 lines
+
+3. **Use descriptive names**
+   - Use meaningful variable and function names
+   - Follow `snake_case` for functions and variables
+   - Follow `PascalCase` for classes
+
+4. **Document your code**
+   - Add docstrings to all functions and classes
+   - Include parameter and return value descriptions
+   - Provide usage examples for public APIs
+
+5. **Error handling**
+   - Use appropriate exception types
+   - Provide helpful error messages
+   - Handle errors at appropriate levels
+
+## Module Development
+
+When developing new modules, follow these guidelines:
+
+### Creating Integrations
+
+Integrations connect ABI to external services:
+
+1. Create a configuration class
+2. Implement the Integration interface
+3. Provide methods for API interactions
+4. Expose as tools via `as_tools()`
+5. Include comprehensive error handling
+
+### Developing Workflows
+
+Workflows implement business logic:
+
+1. Define parameters using `WorkflowParameters`
+2. Implement the `run()` method
+3. Expose as tools via `as_tools()`
+4. Add API endpoints via `as_api()`
+5. Follow the single responsibility principle
+
+### Building Pipelines
+
+Pipelines transform data into semantic triples:
+
+1. Use integrations for data fetching
+2. Transform data into semantic graphs
+3. Store results in the ontology store
+4. Ensure idempotent operations
+5. Handle large datasets efficiently
+
+### Implementing Assistants
+
+Assistants provide LLM agent interfaces:
+
+1. Define metadata (name, description, etc.)
+2. Create a system prompt
+3. Configure appropriate tools
+4. Set up memory and shared state
+5. Implement the `create_agent()` function
+
+## Testing
+
+All contributions should include appropriate tests:
+
+1. **Unit tests** for individual functions and classes
+2. **Integration tests** for workflows and pipelines
+3. **End-to-end tests** for complete features
+
+Use `unittest` for writing tests and run them with:
+
+```bash
+make test
+```
+
+## Documentation
+
+Good documentation is essential:
+
+1. **Code comments** for complex logic
+2. **Docstrings** for all public functions and classes
+3. **README.md** files for modules
+4. **Examples** showing how to use your feature
+5. **Update existing docs** affected by your changes
+
+## Pull Request Process
+
+1. **Submit your PR** against the `main` branch
+2. **Fill out the PR template** with a description of changes
+3. **Link related issues** using keywords like "Fixes #123"
+4. **Ensure CI passes** including tests and linting
+5. **Request reviews** from maintainers
+6. **Address feedback** promptly
+7. **Squash commits** before merging if requested
+
+We aim to review PRs within 1-2 business days. Thank you for contributing to ABI!