Development Essentials#

This document will cover how you can set up the AdalFlow codebase and start coding, testing, and documentation.

Set Up#

We mainly use poetry for dependency management and virtual environment setup.

To set up poetry and contribute, please check the following steps:

Clone the Repository:

git clone https://github.com/SylphAI-Inc/AdalFlow
cd AdalFlow

Set Up the AdalFlow Dev Environment: The AdalFlow source code, tests, and dependencies are in the ./adalflow directory. The ./adalflow/pyproject.toml controls the dependencies for the adalflow package. Use Poetry to install the dependencies and set up the virtual environment:
```
cd adalflow
poetry install
poetry shell
```
Test the setup by running the tests at the ./adalflow directory:
```
pytest tests
```
Set Up the Root Dev Environment: At the root directory, we have a pyproject.toml file that controls the dependencies for the root directory.
```
poetry install
poetry shell
```
This will install all relevant dependencies and the files in /use_cases, /tutorials, and /benchmarks will be using the development version of the adalflow package. You should see output similar to the following:
```
- Installing adalflow (0.2.5 /Users/liyin/Documents/test/AdalFlow/adalflow)
```

[Optional] Configure API Keys in the Root Directory: Copy the example environment file and add your API keys:

cp .env.example .env
# example API keys:
# OPENAI_API_KEY=YOUR_API_KEY_IF_YOU_USE_OPENAI
# GROQ_API_KEY=YOUR_API_KEY_IF_YOU_USE_GROQ
# ANTHROPIC_API_KEY=YOUR_API_KEY_IF_YOU_USE_ANTHROPIC
# GOOGLE_API_KEY=YOUR_API_KEY_IF_YOU_USE_GOOGLE
# COHERE_API_KEY=YOUR_API_KEY_IF_YOU_USE_COHERE
# HF_TOKEN=YOUR_API_KEY_IF_YOU_USE_HF

This will be helpful for you to run tutorials, use cases, and benchmarks.

Coding#

Structuring#

It is recommended to check our the structuring in Part 1: Structuring and API Reference to understand the codebase structure.

What to code#

Please check the Part 3: Contributing Steps to see some coding examples and steps to contribute to the codebase.

Code Tips#

Please follow the Google Python Style Guide.
Functions and classes should include standard docstrings and comments. Please refer to documentation contribution guidelines for standard docstrings.

Copilot#

We suggest you use GitHub Copilot to help you write code faster and more efficiently. You can follow this Guide to set it up with your IDE. There are other options like Cursor and Tabnine that you can use as well.

Dependencies#

If you want to add any new dependencies to the package, please include them in your PR description to inform us.
Since we have already set up the testing automatic workflow in GitHub, please also set your new dependencies in ./adalflow/pyproject.toml file [tool.poetry.group.test.dependencies] section to avoid dependency errors in our CI/CD workflow. In order to correctly add the dependency using poetry, please run
```
poetry add --group test <package-name>
```

Testing#

After you update the code, please make sure your code is well tested before making a pull request. There is a ./adalflow/tests folder in the project directory to host your unit testing cases.

You might need to install the testing packages using poetry:

For example:

poetry install # or
poetry add --group test

You should name your test files with the following format: test_<module_name>.py.

Activate the virtual environment from ./adalflow and run the tests:

poetry shell
pytest

To run a specific test file, you can use the following command:

pytest tests/test_components.py

For more details on testing, please refer to the README.md under the ./adalflow/tests directory.

Documentation#

Please refer to the README.md under the ./docs directory for more details on how to contribute to the documentation.