diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7cda8b06..2560eb9af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -209,5 +209,147 @@ This command generates a JWT token that will be valid for 10 days. - Check for missing environment variables in the `.env` file. - Use the `docker compose logs` command to view detailed logs for debugging. +## Project Components + +The Julep project consists of several components that work together to provide a robust and scalable platform for building multi-step agent workflows. These components include: + +* **Agents**: The agents are the core components of the Julep project. They are responsible for executing the workflows and interacting with the user. +* **Workflows**: The workflows are the sequences of tasks that are executed by the agents. They are defined using a YAML file and can include multiple tasks and conditional logic. +* **Activities**: The activities are the individual tasks that are executed by the agents. They can include things like sending emails, making API calls, and executing shell commands. +* **Database**: The database is used to store the workflows, agents, and activities. It is also used to store the results of the workflows. + +## How to Contribute + +To contribute to the Julep project, you can follow these steps: + +* **Fork the repository**: Fork the Julep repository on GitHub to create a copy of the code in your own account. +* **Create a new branch**: Create a new branch in your forked repository to make your changes. +* **Make your changes**: Make your changes to the code and commit them to your new branch. +* **Submit a pull request**: Submit a pull request to the Julep repository to have your changes reviewed and merged. + +## Code Style + +The Julep project uses a consistent code style throughout the codebase. This includes: + +* **Indentation**: The code uses 4 spaces for indentation. +* **Line length**: The code uses a maximum line length of 80 characters. +* **Variable naming**: The code uses descriptive variable names that follow the camelCase convention. + +## Testing + +The Julep project uses a comprehensive testing suite to ensure that the code is correct and stable. This includes: + +* **Unit tests**: The code includes unit tests for each component to ensure that it is working correctly. +* **Integration tests**: The code includes integration tests to ensure that the components are working together correctly. +* **End-to-end tests**: The code includes end-to-end tests to ensure that the entire system is working correctly. + +## Project Overview and Architecture + +### Key Components + +1. **agents-api**: The core API service for Julep. +2. **typespec**: API specifications and contracts. +3. **integrations-service**: Handles external integrations. +4. **embedding-service**: Manages text embeddings. +5. **memory-store**: Handles persistent storage. +6. **llm-proxy**: Proxy for language model interactions. +7. **scheduler**: Manages task scheduling. +8. **gateway**: API gateway and routing. +9. **monitoring**: System monitoring and metrics. + +### Technology Stack + +- **FastAPI**: Web framework for building APIs +- **TypeSpec**: API specification language +- **Cozo**: Database system +- **Temporal**: Workflow engine +- **Docker**: Containerization + +### Relationships Between Components + +The `agents-api` serves as the central component, interacting with most other services: +- It uses `typespec` definitions for API contracts. +- Communicates with `integrations-service` for external tool interactions. +- Utilizes `embedding-service` for text processing. +- Stores data in `memory-store`. +- Interacts with language models through `llm-proxy`. +- Uses `scheduler` for task management. +- All API requests pass through the `gateway`. +- `monitoring` observes the entire system. + +## Understanding the Codebase + +To get a comprehensive understanding of Julep, we recommend exploring the codebase in the following order: + +1. **Project Overview** + - Read `README.md` in the root directory + - Explore `docs/` for detailed documentation + +2. **System Architecture** + - Examine `docker-compose.yml` in the root directory + - Review `deploy/` directory for different deployment configurations + +3. **API Specifications** + - Learn about TypeSpec: https://typespec.io/docs/ + - Explore `typespec/` directory: + - Start with `common/` folder + - Review `main.tsp` + - Examine each module sequentially + +4. **Core API Implementation** + - Learn about FastAPI: https://fastapi.tiangolo.com/ + - Explore `agents-api/` directory: + - Review `README.md` for an overview + - Examine `routers/` for API endpoints + - Look into `models/` for data models + +5. **Database and Storage** + - Learn about Cozo: https://docs.cozodb.org/en/latest/tutorial.html + - Review `agents-api/README.md` for database schema + - Explore `agents-api/models/` for database queries + +6. **Workflow Management** + - Learn about Temporal: https://docs.temporal.io/develop/python + - Explore `agents-api/activities/` for individual workflow steps + - Review `agents-api/workflows/task_execution/` for main workflow logic + +7. **Testing** + - Examine `agents-api/tests/` for test cases + +8. **Additional Services** + - Explore other service directories (`integrations-service/`, `embedding-service/`, etc.) to understand their specific roles and implementations + +## Contributing Guidelines + +1. **Set Up Development Environment** + - Clone the repository + - Install Docker and Docker Compose + - Set up necessary API keys and environment variables + +2. **Choose an Area to Contribute** + - Check the issue tracker for open issues + - Look for "good first issue" labels for newcomers + +3. **Make Changes** + - Create a new branch for your changes + - Write clean, well-documented code + - Ensure your changes adhere to the project's coding standards + +4. **Test Your Changes** + - Run existing tests + - Add new tests for new functionality + - Ensure all tests pass before submitting your changes + +5. **Submit a Pull Request** + - Provide a clear description of your changes + - Reference any related issues + - Be prepared to respond to feedback and make adjustments + +6. **Code Review** + - Address any comments or suggestions from reviewers + - Make necessary changes and push updates to your branch + +7. **Merge** + - Once approved, your changes will be merged into the main branch Remember, contributions aren't limited to code. Documentation improvements, bug reports, and feature suggestions are also valuable contributions to the project.