algorithm-nexus 0.2.1__tar.gz → 0.2.2__tar.gz

algorithm_nexus-0.2.2/.agents/skills/add-nexus-package/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: add-nexus-package
+description:
+  Step-by-step guidance for contributing a new algorithm stack python package to
+  Algorithm Nexus. It ensures all configuration files are properly created,
+  validates the structure of the required nexus package, and helps classify and
+  add the algorithm stack package as a dependency. Use when users want to create
+  a Nexus package for their python library or add their python library to
+  algorithm nexus.
+---
+
+# Adding an Algorithm Stack Package to Algorithm Nexus
+
+## Prerequisites
+
+To add an algorithm stack package to Algorithm Nexus the below package level
+information is required:
+
+- `package_name` (string, required): Name of the Nexus package to be added as
+  per the
+  [prerequisites](../../../docs/contributing/add_new_nexus_package.md#prerequisites)
+  in the _Contributing a python algorithm package to Algorithm Nexus_.
+- `package_url` (string, required): URL of the python package repository on
+  GitHub.
+- `package_version` (string, required): GitHub release version of the python
+  package to be added to the dependencies.
+- `is vllm and optional dependency`: The python package can be installed without
+  vLLM in the dependencies, or with vLLM via an optional dependency group.
+
+If this information is not available stop.
+
+It is optional to include models information in the package. However, for a
+model to be included, the following information is required:
+
+- `huggingface_id` (string, required): Hugging Face model repository identifier.
+- `name` (string, required): Name of the model to be used as folder name.
+- `owner` (string, optional): GitHub username of model owner
+- `requires_vllm` (boolean, required): Whether the model uses vLLM for serving
+- `vllm_plugins` (string, required): If the model uses vLLM it might also
+  require a set of vlLM plugins.
+    - `general` (string, optional): name of the general plugin required for
+      loading the model with vLLM
+    - `io_processors` (list of strings, optional): list of io processor plugins
+      that the model supports for pre/post processing with vLLM
+
+If a model has been specified to be added and the above information is not
+available, stop.
+
+## Steps
+
+Follow the below steps to create the Nexus Package:
+
+1. **Inspect the Algorithm Stack Package Source**: Inspect the code to extract
+   information about the package.
+2. **Identify the Nexus Variant**: Identify which nexus variant should the
+   python package be added to.
+3. **Create Nexus Package Structure**: Create the necessary Nexus package folder
+   structure and populate config files.
+4. **Validate the Nexus Package**: Run `nexus validate package` to check structure.
+5. **Add Algorithm Stack Package as an Algorithm Nexus Dependency**: Use
+   `uv add` with correct variant classification.
+6. **Write Report**: Write a report of the changes made and any errors
+   encountered.
+
+## 1. Inspect the Algorithm Stack Package Source
+
+If the python package repository is not checked out locally, clone the
+repository to a temporary location.
+
+Inspect the source code to identify:
+
+- Available models and their Hugging Face ID.
+    - No two models can have the same Hugging Face ID. If that's the case, stop.
+    - Extract the model name from the Hugging Face ID, i.e. model-name in
+      "org/model-name".
+- Whether the package requires vLLM or not, and if it does whether vLLM is a
+  mandatory or optional requirement.
+- The GitHub release version of the python package to be installed.
+    - If no specific GitHub release version is provided by the user, inspect the
+      repository to identify the latest GitHub release.
+    - If no GitHub release is available, stop and inform the user that a GitHub
+      release is required.
+
+## 2. Identify the Nexus Variant
+
+Using the prerequisite information you can infer the distribution variant the
+algorithm stack package should be added to by following the instructions in the
+[_Variant Association Rules_ section](../../../docs/design/dependency-resolution.md#4-variant-association-rules)
+of the dependency resolution design document.
+
+No algorithm stack package can be added to the `product` variant.
+
+## 3. Create Nexus Package Structure
+
+Using the prerequisite information create the Nexus package structure as
+outlined in the
+[_Create a Nexus package for your algorithm_ section](../../../docs/contributing/add_new_nexus_package.md#step-3-create-a-nexus-package-for-your-algorithm)
+of the _Contributing a python algorithm package to Algorithm Nexus_ document. If
+models are to be included, follow the instructions in
+[_Describe the Models in Your Algorithm Package_ section](../../../docs/contributing/add_new_nexus_package.md#describe-the-models-in-your-algorithm-package)
+of the _Contributing a python algorithm package to Algorithm Nexus_ documentat.
+
+## 4. Validate the Nexus Package
+
+```bash
+uv run nexus validate package packages/<package-name>
+```
+
+If the validation is successful, the tool will print a success message
+`Validation Successful`. Continue to the next step.
+
+If the validation is not successful, it will print `Validation Failed` followed
+by a list of the errors.
+
+There are two main reasons for a failure:
+
+1. A file is missing from the package or models directory.
+2. A Pydantic failure indicating the schema for the package or one of the model
+   configuration files is not correct.
+
+For pydantic failures, iterate on the validation until the failures are
+resolved. If a failure is related to a missing file, check the instructions in
+step 2 to identify and add the missing file, and run the validation again.
+
+## 5. Add Algorithm Stack Package as an Algorithm Nexus Dependency
+
+For each variant the algorithm stack package was identified as belonging to in
+step 1, follow the instructions in
+[`Step 2: Add your algorithm package to the Algorithm Nexus dependencies`](../../../docs/contributing/add_new_nexus_package.md#step-2-add-your-algorithm-package-to-the-algorithm-nexus-dependencies).
+
+In case of failure with uv when adding the algorithm stack package to a variant:
+
+- Report the error with some suggested fixes.
+- Do not attempt changing the dependencies of the project to fix the errors.
+- Skip this variant and continue to the next variant if any.
+
+## 6. Write Report
+
+Generate a report of the changes and unresolved issues following the
+[New Nexus Package PR template](../../../.github/PULL_REQUEST_TEMPLATE/new_nexus_package.md).
+Only add a summary of the changes, without including the rationale behind the
+changes. Save the report as a markdown in a file.

algorithm_nexus-0.2.2/.agents/skills/update-lock-file/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: update-lock-file
+description: >
+    Use when the user wants to update the project lock file and requirements
+    files. Syncs uv.lock with origin/main, regenerates lock, and exports all
+    requirement files, then commits the result.
+---
+
+# Update Lock File and Requirements Files
+
+Follow these steps in order to update the project lock file and requirement
+files.
+
+## 1. Verify the Branch is Up-to-Date with origin/main
+
+Run the following command to check how many commits the current branch is behind
+`origin/main`:
+
+```bash
+git fetch origin main && git rev-list --count HEAD..origin/main
+```
+
+- If the count is **0**, the branch is up-to-date. Continue to Step 2.
+- If the count is **greater than 0**, the branch is behind. Inform the user and
+  ask whether they would like you to rebase the current branch on top of
+  `origin/main`. Wait for their response before proceeding.
+    - If the user says **yes**, run:
+
+        ```bash
+        git rebase origin/main
+        ```
+
+        If the rebase exits with a non-zero status, stop and report the error to
+        the user — do not attempt to resolve conflicts automatically.
+
+    - If the user says **no**, stop here and let the user update the branch
+      before retrying.
+
+## 2. Perform the Dependency Update
+
+Run the following commands **in order**, one at a time. Stop and report any
+failure before proceeding to the next command.
+
+```bash
+git restore --source origin/main -- uv.lock
+```
+
+```bash
+uv lock
+```
+
+```bash
+uv run pre-commit run uv-export -a
+```
+
+## 3. Commit the Updated Files
+
+Stage and commit the lock file and all three requirements files:
+
+```bash
+git add uv.lock requirements-candidate.txt requirements-ecosystem.txt requirements-product.txt
+git commit -m "chore(dependencies): Updated lock file and requirement files"
+```
+
+If there are no files to be committed it means the project dependencies are
+already up-to date, inform the user and stop. Otherwise, commit the changes and
+confirm to the user that the commit was created successfully.

algorithm_nexus-0.2.2/.copywrite.hcl

@@ -0,0 +1,35 @@
+schema_version = 1
+
+project {
+  license        = "Apache-2.0"
+  copyright_year = 2026
+
+  header_ignore = [
+    # Ignore generated files
+    "**/*.md",
+    "**/*.json",
+    "**/*.yaml",
+    "**/*.yml",
+    "**/*.toml",
+    "**/*.txt",
+    "**/*.lock",
+
+    # Ignore directories
+    ".venv/**",
+    ".tox/**",
+    "**/__pycache__/**",
+    "*.egg-info/**",
+    "dist/**",
+    "build/**",
+    ".pytest_cache/**",
+    ".ruff_cache/**",
+    ".mypy_cache/**",
+
+    # Ignore specific files
+    "LICENSE",
+    ".gitignore",
+    ".secrets.baseline",
+    ".pre-commit-config.yaml",
+    ".copywrite.hcl",
+  ]
+}

algorithm_nexus-0.2.2/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "bug: "
+labels: bug
+assignees: ""
+---
+
+## Issue Description
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+## Expected behaviour
+
+A clear and concise description of what you expected to happen.
+
+## Screenshots/Logs
+
+If applicable, add screenshots and logs to help explain your problem.
+
+## Python/system info
+
+Please include the output of:
+
+```terminaloutput
+python --version
+Your OS
+```
+
+## Additional context
+
+Add any other context about the problem here.

algorithm_nexus-0.2.2/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: "feat: "
+labels: enhancement
+assignees: ""
+---
+
+## Description
+
+A clear and concise description of the feature you'd like to see implemented.
+
+## Motivation
+
+Explain why this feature would be useful. What problem does it solve?
+
+## Proposed Solution
+
+Describe the solution you'd like to see implemented.
+
+## Alternatives Considered
+
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+
+Add any other context, screenshots, or examples about the feature request here.
+
+## Implementation Notes
+
+If you have ideas about how this could be implemented, please share them here.

algorithm_nexus-0.2.2/.github/PULL_REQUEST_TEMPLATE/new_nexus_package.md

@@ -0,0 +1,25 @@
+---
+name: New Nexus Package
+about: Submit a new Nexus package to Algorithm Nexus
+title: "feat(package): Add [package-name] Nexus package"
+labels: "nexus-package"
+---
+
+## Description
+
+<!-- Briefly describe the PR -->
+
+## Additional Information
+
+<!-- Add any additional context, notes, or special considerations for reviewers -->
+
+## I need help with this PR
+
+<!-- If you are unable to pass the dependencies resolution (i.e., you have tried to
+fix it yourself, and still it does not work), describe your issue by providing the
+uv logs and any other information that could help the maintainers addressing your
+specific problem.-->
+
+## Related Issues
+
+<!-- Link any related issues, e.g., Closes #123 -->

algorithm_nexus-0.2.2/.github/dco.yml

@@ -0,0 +1,4 @@
+# This enables DCO bot for you, please take a look https://github.com/probot/dco
+# for more details.
+require:
+  members: false

algorithm_nexus-0.2.2/.gitignore

@@ -0,0 +1,76 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# UV package manager
+.uv/
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.hypothesis/
+coverage.xml
+*.cover
+
+# Type checking
+.mypy_cache/
+.pytype/
+.pyre/
+
+# Linting
+.ruff_cache/
+
+# Pre-commit
+.pre-commit-cache/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environment variables
+.env
+.env.local
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+*.bak
+*.orig
+
+# Website build output
+site/
+.cache/
+.gh-pages/
+
+# Node.js
+node_modules/
+package-lock.json

algorithm_nexus-0.2.2/.markdownlint-cli2.yaml

@@ -0,0 +1,45 @@
+# Markdownlint-cli2 configuration
+# See https://github.com/DavidAnson/markdownlint-cli2
+
+# Markdownlint configuration
+config:
+  # Default state for all rules
+  default: true
+
+  # MD001/heading-increment - Heading levels should only increment by one level at a time
+  MD001: false
+
+  # MD024/no-duplicate-heading - Multiple headings with the same content
+  MD024:
+    siblings_only: true
+
+  # MD007/ul-indent - Unordered list indentation
+  MD007:
+    indent: 4
+
+  # MD013/line-length - Line length
+  MD013:
+    line_length: 120
+    heading_line_length: 120
+    code_block_line_length: 120
+    code_blocks: false
+    tables: false
+    headings: true
+    strict: false
+    stern: false
+
+  # MD033/no-inline-html - Inline HTML
+  MD033:
+    allowed_elements:
+      - br
+      - details
+      - summary
+      - img
+      - a
+      - sup
+
+  # MD041/first-line-heading - First line in file should be a top level heading
+  MD041: false
+
+  # MD046/code-block-style - Code block style
+  MD046: false

algorithm_nexus-0.2.2/.pre-commit-config.yaml

@@ -0,0 +1,95 @@
+# Pre-commit hooks configuration
+# See https://pre-commit.com for more information
+
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+default_stages: [pre-commit]
+
+repos:
+  # detect-secrets - Detect secrets in code
+  - repo: https://github.com/ibm/detect-secrets
+    rev: 0.13.1+ibm.64.dss
+    hooks:
+      - id: detect-secrets
+        args: [--baseline, .secrets.baseline, --use-all-plugins, --fail-on-unaudited]
+
+  # Ruff - Python linter and formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Conventional commits
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args:
+          - --no-color
+          - --verbose
+
+  # Codespell - Check for common misspellings
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        additional_dependencies: ["tomli"]
+        args: ["--toml", "pyproject.toml"]
+
+  # UV lock check
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.11.26
+    hooks:
+      - id: uv-lock
+      - id: uv-export
+        alias: "uv-export-ecosystem"
+        args: ["--frozen", "--no-emit-project", "--no-default-groups", "--no-header", "--extra=ecosystem", "--output-file=requirements-ecosystem.txt"]
+      - id: uv-export
+        alias: "uv-export-candidate"
+        args: ["--frozen", "--no-emit-project", "--no-default-groups", "--no-header", "--extra=candidate", "--output-file=requirements-candidate.txt"]
+      - id: uv-export
+        alias: "uv-export-product"
+        args: ["--frozen", "--no-emit-project", "--no-default-groups", "--no-header", "--extra=product", "--output-file=requirements-product.txt"]
+
+  # Copywrite - License header management
+  - repo: https://github.com/hashicorp/copywrite
+    rev: v0.25.3
+    hooks:
+      - id: add-headers
+
+  # Markdownlint - Markdown linting
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.23.0
+    hooks:
+      - id: markdownlint-cli2
+
+  # Yamlfmt - YAML formatting
+  - repo: https://github.com/google/yamlfmt
+    rev: v0.21.0
+    hooks:
+      - id: yamlfmt
+
+  # Tombi - TOML formatting
+  - repo: https://github.com/tombi-toml/tombi-pre-commit
+    rev: v1.2.0
+    hooks:
+      - id: tombi-format
+        args: ["--offline"]
+
+  # Standard pre-commit hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-json
+      - id: mixed-line-ending

algorithm_nexus-0.2.2/.prettierrc.toml

@@ -0,0 +1,4 @@
+# Prettier configuration
+tabWidth = 4
+useTabs = false
+proseWrap = "always"

algorithm_nexus-0.2.2/.python-version

@@ -0,0 +1 @@
+3.12

algorithm_nexus-0.2.2/.secrets.baseline

@@ -0,0 +1,96 @@
+{
+  "exclude": {
+    "files": "^.secrets$|^.secrets.baseline$",
+    "lines": null
+  },
+  "generated_at": "2026-07-16T22:04:38Z",
+  "plugins_used": [
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "base64_limit": 4.5,
+      "name": "Base64HighEntropyString"
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "BoxDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "ghe_instance": "github.ibm.com",
+      "name": "GheDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "hex_limit": 3,
+      "name": "HexHighEntropyString"
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "keyword_exclude": null,
+      "name": "KeywordDetector"
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "results": {
+    "requirements-ecosystem.txt": [
+      {
+        "hashed_secret": "07c7e5dca0db66092ee9e80cdb352d4f58a3d38a",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 666,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ]
+  },
+  "version": "0.13.1+ibm.64.dss",
+  "word_list": {
+    "file": null,
+    "hash": null
+  }
+}

algorithm_nexus-0.2.2/.yamlfmt

@@ -0,0 +1,14 @@
+# yamlfmt configuration
+# See https://github.com/google/yamlfmt
+
+formatter:
+  type: basic
+  indent: 2
+  include_document_start: false
+  line_ending: lf
+  retain_line_breaks: true
+  max_line_length: 120
+  scan_folded_as_literal: false
+  indentless_arrays: false
+  drop_merge_tag: false
+  pad_line_comments: 2