Contributing a python algorithm package to Algorithm Nexus¶

This guide walks you through the process of contributing a algorithm python package, containing, for example, AI models, to Algorithm Nexus.

There are four steps to contribute your algorithm package

1. Setup a local copy of the Algorithm Nexus repository
2. Add your algorithm package to the Algorithm Nexus dependencies
3. Create a Nexus package for your algorithm
4. Commit your changes, push them, and then open a PR with Algorithm Nexus

Prerequisites¶

Before you begin, ensure

• Your algorithm package is publicly available GitHub at <Python-Package-URL>.
• uv is installed on your system.
• You have a fork of the Algorithm Nexus repository checked out locally

Step 1: Setup the Algorithm Nexus repository¶

Run the commands below from the folder where you have checked out your Algorithm Nexus fork.

cd algorithm-nexus
uv sync --group dev --extra cli
uv run pre-commit install

Then, create a new branch to host your changes.

git checkout -b add-<package-name>-package

Step 2: Add your algorithm package to the Algorithm Nexus dependencies¶

1. Determine which variants your package should be added to, by reading Identify The Algorithm Nexus variant for your Package.
2. Add it to each of these variants using uv.
3. Export requirements

For example, if your package should be added to the ecosystem variant run,

uv add <Python-Package-URL> --optional ecosystem --no-sync
uv export --frozen --no-emit-project --no-default-groups \
          --no-header --extra=ecosystem \
          --output-file=requirements-ecosystem.txt

If the uv add step fails, and you are unable to troubleshoot the error, record the error you get and continue on to step 3 and 4.

Then export the requirement file by running:

uv export --frozen --no-emit-project --no-default-groups \
          --no-header --extra=ecosystem \
          --output-file=requirements-ecosystem.txt

Step 3: Create a Nexus package for your algorithm¶

A Nexus package is a directory with some files that contains metadata about your algorithm package. Under packages/ in the root of the Algorithm Nexus repository you checked out, create a folder with your package name

mkdir packages/<package-name>

Then, create the Nexus package configuration file in packages/<package-name>/nexus.yaml with the following content:

package:
    name: <package-name>

Finally, validate the package structure with

uv run nexus validate packages/<package-name>

In case of validation errors, the nexus validate tool will list all the errors. Fix them before moving to the next step.

Step 4: Commit Changes and Open a Pull Request¶

Add the files to be committed

git add packages/<package-name> pyproject.toml uv.lock requirements-ecosystem.txt

Commit your changes and push to your remote fork

git commit -s -m "feat(package): Add <package-name> Nexus Package"
git push origin add-<package-name>-package

Finally, navigate to your fork on GitHub and open a Pull request for the newly pushed branch to be merged with the Algorithm Nexus main branch. Use the New Nexus Package pull request template and fill all the required fields. In case of failures in Step 2, the PR template contains a dedicated section (I Need Help) where you can log the errors recorded while adding your python package to the Algorithm Nexus dependencies.

Optional Steps¶

After completing above you can flesh out your contribution with more information:

1. Describe the models your algorithm package contains
   • This is required to access testing and benchmarking of your model in future
2. Add documentation on how to use your models for inference and fine-tuning
3. Add agent skills for your package

Describe the Models in Your Algorithm Package¶

If your algorithm package contains one or more models, you can add their description to the Nexus package metadata by following the steps below.

For each model (<model-name>) that your package supports:

1. Create a directory under packages/<package-name>/models/<model-name>/

2. Create a model.yaml file with the model configuration:

   model:
       id: organization/model-name # Hugging Face model repository identifier
       owner: github-username # Optional: defaults to package owner if omitted
   

Full details on the model configuration file are available in the Nexus Package Structure Guide.

Model Usage Documentation¶

Optionally, each model in a Nexus package can provide usage documentation in a usage.md file in the model subfolder. This should be populated with usage examples, description of useful parameters, and any other relevant information.

Agent Skills for Nexus Packages¶

Optionally, each Nexus package can provide agent skills for helping the user with using the package and its models. Example agent skills would aid the users with models deployment on different target infrastructure (e.g., bare metal, Kubernetes, etc.) and with building scripts for evaluating the models.

Identify The Algorithm Nexus Variant for your Package¶

If your Python package:

• does not declare vllm as a default dependency
• does not declare vllm as an optional dependency

It belongs to the ecosystem variant only.

If your Python package:

• declares vllm as a default (mandatory) dependency

It belongs to the candidate variant only.

If your Python package:

• declares vllm as an optional dependency

It belongs both to the ecosystem and candidate variant only. In this case, when adding to the candidate variant, users must ensure their package is added with the optional vllm dependency (package-name[vllm-dependency]).

Getting Help¶

If you encounter issues:

1. Check the Nexus Package Structure Guide
2. Review the Dependency Resolution Design Document
3. Search existing issues on GitHub
4. Open a new issue with details about your problem