Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
142 commits
Select commit Hold shift + click to select a range
f130aff
mask_update
Matvezy Feb 4, 2025
7bf08cb
add Florence-2 object detection cookbook
SkalskiP Feb 5, 2025
54f3840
Merge pull request #135 from roboflow/cookbooks/florence_2_object_det…
SkalskiP Feb 5, 2025
e3ad8bf
:arrow_up: Update mypy requirement
dependabot[bot] Feb 5, 2025
8ee7a60
Merge pull request #139 from roboflow/dependabot/pip/mypy-gte-1.11.2-…
onuralpszr Feb 5, 2025
442be6b
ci(docs): 👷 update docs ci with mkdocs-insiders and use uv
onuralpszr Feb 5, 2025
2f9c3aa
ci(docs): 📦 update mkdocs-material-insiders to version 9.6.2
onuralpszr Feb 5, 2025
908e274
Merge pull request #140 from roboflow/docs/mkdocs-insiders
onuralpszr Feb 5, 2025
fdd862b
Update pip package to have quotes therefore Mac zsh will not globbing…
cnukaus Feb 6, 2025
a5585b0
Merge pull request #143 from cnukaus/develop
SkalskiP Feb 6, 2025
c1bf76b
:arrow_up: Update transformers requirement from <4.48.0 to <4.49.0
dependabot[bot] Feb 7, 2025
d6f0b42
docs: 📝 transformers comment about paligemma2 removed
onuralpszr Feb 7, 2025
cf7ad8a
Merge pull request #151 from roboflow/dependabot/pip/transformers-lt-…
onuralpszr Feb 7, 2025
2115397
docs: 📝 enable comments on documentation pages and add comment secti…
onuralpszr Feb 9, 2025
ad3a96e
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Feb 9, 2025
1e05c9c
Merge pull request #152 from roboflow/docs/style-updates
onuralpszr Feb 9, 2025
c920633
chore: qwen2.5 and paligemma2 notebooks maestro versions are set to l…
onuralpszr Feb 9, 2025
6bae478
- add JSONL docs page
SkalskiP Feb 10, 2025
52b87a4
Merge pull request #156 from roboflow/docs/jsonl_format
SkalskiP Feb 10, 2025
7e66063
set version of maestro to latest
SkalskiP Feb 10, 2025
895f8a9
Merge pull request #157 from roboflow/cookbooks/set_maestro_version_t…
SkalskiP Feb 10, 2025
15e91ca
feat(logging): 🔊 add logging configuration for PyTorch Lightning and …
onuralpszr Feb 4, 2025
c82738a
fix(logging): 🐞 correct logger variable names and set logging levels …
onuralpszr Feb 4, 2025
380f7d5
fix(logging): 🐞 reorder import statement for configure_logging in exa…
onuralpszr Feb 4, 2025
7ae2b98
Merge pull request #128 from roboflow/log/maestro
onuralpszr Feb 10, 2025
f00f512
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Feb 10, 2025
5191104
Merge pull request #158 from roboflow/pre-commit-ci-update-config
onuralpszr Feb 11, 2025
b14f682
initial commit with JSONLDataset refactor and Florence-2 box -> text …
SkalskiP Feb 11, 2025
457c76d
initial implementation of COCO loader
SkalskiP Feb 11, 2025
c172516
improve JSONLDataset and COCODataset API consistency
SkalskiP Feb 11, 2025
bb484a2
roboflow identifier parsing
SkalskiP Feb 11, 2025
0ab5034
plugging in smart dataset loading
SkalskiP Feb 11, 2025
0a1e6ae
small changes
SkalskiP Feb 11, 2025
be1e702
initial COCO integration for Florence-2
SkalskiP Feb 11, 2025
8dd82bf
bring back trust_remote_code=True
SkalskiP Feb 11, 2025
63d3526
Florence-2 training with mAP
SkalskiP Feb 11, 2025
9070624
debug
SkalskiP Feb 11, 2025
5dbb609
debug
SkalskiP Feb 11, 2025
79dd56d
run all validation batches
SkalskiP Feb 11, 2025
1075682
prevent training start when splits are not present
SkalskiP Feb 12, 2025
7ddbe70
Merge branch 'feature/plugin_mean_average_precision' into feature/sma…
SkalskiP Feb 12, 2025
c9810cd
bump `maestro` version from `1.0.0` to `1.1.0rc1`
SkalskiP Feb 12, 2025
258bfad
Update README.md
SkalskiP Feb 12, 2025
bffbee9
Merge pull request #159 from roboflow/feature/smart_dataset_loading
SkalskiP Feb 12, 2025
d6dd21f
add experimental Florence-2 notebook with COCO and mAP support
SkalskiP Feb 12, 2025
cecc78f
Update README.md
SkalskiP Feb 14, 2025
4c0ba5b
:arrow_up: Update mkdocstrings[python] requirement
dependabot[bot] Feb 14, 2025
f509f81
ci: 👷 insider version removed from test doc
onuralpszr Feb 16, 2025
dc66d40
Merge pull request #161 from roboflow/dependabot/pip/mkdocstrings-pyt…
onuralpszr Feb 16, 2025
2db88c4
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Feb 17, 2025
26835d8
Merge pull request #167 from roboflow/pre-commit-ci-update-config
onuralpszr Feb 17, 2025
d3822f0
deps: 📦 update transformers version constraints and qwen support
onuralpszr Feb 17, 2025
90d34aa
docs: 📝 remove installation warning for transformers and update insta…
onuralpszr Feb 17, 2025
f467f35
fix: 🐛 update dataset import with new JSONLDataset
onuralpszr Feb 17, 2025
4c0c9ae
deps: 📦 update version to 1.1.0rc2 in pyproject.toml and installation…
onuralpszr Feb 18, 2025
d3daf16
Merge pull request #169 from roboflow/deps/transformers/qwen
SkalskiP Feb 18, 2025
40bdd19
add `detections_to_suffix_formatter` and `detections_to_prefix_format…
SkalskiP Feb 21, 2025
ea82a89
add mAP support for Qwen2.5-VL
SkalskiP Feb 24, 2025
963394d
fix `image_grid_thw.cpu()`
SkalskiP Feb 24, 2025
e202550
fix during mAP calculation
SkalskiP Feb 24, 2025
46eb547
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Feb 24, 2025
c11659f
Merge pull request #171 from roboflow/pre-commit-ci-update-config
onuralpszr Feb 24, 2025
dc43210
:arrow_up: Update mkdocstrings[python] requirement
dependabot[bot] Feb 24, 2025
33753c0
Merge pull request #172 from roboflow/dependabot/pip/mkdocstrings-pyt…
onuralpszr Feb 24, 2025
1e408d3
Merge pull request #129 from roboflow/qwen_loss_mask_fix
SkalskiP Feb 24, 2025
7ba8c83
logging + processor.tokenizer.padding_side = "left"
SkalskiP Feb 24, 2025
9b105ca
Merge branch 'develop' into feature/qwen_2_5_vl_object_detection_support
SkalskiP Feb 24, 2025
190572e
qwen2.5 train_collate_fn refactor
SkalskiP Feb 24, 2025
f94f3a1
bring back limit_val_batches=1,
SkalskiP Feb 24, 2025
6dbe104
setting use_fast=True for Qwen2.5 image processor
SkalskiP Feb 24, 2025
ef0345c
Qwen2.5-VL detections_to_prefix_formatter updates
SkalskiP Feb 25, 2025
28ab5b3
unify PaliGemma 2, Florence-2 and Qwen2.5-VL logging and checkpoint l…
SkalskiP Feb 25, 2025
ef51c20
bump maestro version from 1.1.0rc2 to 1.1.0rc3
SkalskiP Feb 25, 2025
f130403
Merge pull request #173 from roboflow/feature/qwen_2_5_vl_object_dete…
SkalskiP Feb 25, 2025
edac891
updated Qwen2.5 notebooks - object detection + JSON data extraction
SkalskiP Feb 25, 2025
14496e4
Update README.md
SkalskiP Feb 25, 2025
9710aba
Update README.md
SkalskiP Feb 25, 2025
1168180
custom LoRA config
shataxiDubey Feb 26, 2025
3cc1dae
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Feb 26, 2025
e2ddbfc
lora keys and json error handling
shataxiDubey Feb 26, 2025
86f6aa9
lora keys and json exception handling
shataxiDubey Feb 26, 2025
9dd688b
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Feb 26, 2025
8c17204
lora keys and json exception handling
shataxiDubey Feb 26, 2025
87296d7
lora keys and json exception handling
shataxiDubey Feb 26, 2025
34483e9
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Feb 26, 2025
06c4dea
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Mar 3, 2025
869c0fe
Merge pull request #180 from roboflow/pre-commit-ci-update-config
SkalskiP Mar 6, 2025
28acfaf
added logger.exception and moved exception inside inner function
shataxiDubey Mar 6, 2025
f792eb9
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Mar 6, 2025
f3461f9
minor changes
shataxiDubey Mar 6, 2025
4a9f755
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Mar 6, 2025
e14262e
using maestro logger
shataxiDubey Mar 7, 2025
d5d9888
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Mar 7, 2025
f746db2
dict return type
shataxiDubey Mar 7, 2025
447ab46
dict return type
shataxiDubey Mar 7, 2025
4e87b40
dict return type
shataxiDubey Mar 7, 2025
7e86f8a
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Mar 10, 2025
8f3e6a8
:arrow_up: Update mkdocstrings[python] requirement
dependabot[bot] Mar 10, 2025
55c704f
Merge pull request #182 from roboflow/pre-commit-ci-update-config
SkalskiP Mar 11, 2025
b84cbb3
Merge pull request #175 from shataxiDubey/develop
SkalskiP Mar 11, 2025
e45e66e
Merge pull request #183 from roboflow/dependabot/pip/mkdocstrings-pyt…
onuralpszr Mar 12, 2025
2bbd788
:arrow_up: Update ruff requirement
dependabot[bot] Mar 13, 2025
6ab55bc
Merge pull request #186 from roboflow/dependabot/pip/ruff-gte-0.6.5-a…
onuralpszr Mar 13, 2025
f9f02d9
:arrow_up: Update ruff requirement
dependabot[bot] Mar 14, 2025
a51efc5
Merge pull request #187 from roboflow/dependabot/pip/ruff-gte-0.6.5-a…
onuralpszr Mar 15, 2025
ad72726
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Mar 17, 2025
2e44c75
refactor(mypy): simplify integer type for ruff and mypy
onuralpszr Mar 17, 2025
8e8c812
Merge pull request #188 from roboflow/pre-commit-ci-update-config
onuralpszr Mar 17, 2025
30beed0
:arrow_up: Update pre-commit requirement from <4.2,>=3.8 to >=3.8,<4.3
dependabot[bot] Mar 19, 2025
7562154
Merge pull request #189 from roboflow/dependabot/pip/pre-commit-gte-3…
onuralpszr Mar 19, 2025
7a791f7
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Mar 24, 2025
59d6476
Merge pull request #191 from roboflow/pre-commit-ci-update-config
onuralpszr Mar 24, 2025
b44e7bc
:arrow_up: Update tox requirement
dependabot[bot] Mar 27, 2025
2668805
Merge pull request #193 from roboflow/dependabot/pip/tox-gte-4.18.1-a…
onuralpszr Mar 27, 2025
8a5ed13
:arrow_up: Update mkdocstrings[python] requirement
dependabot[bot] Mar 31, 2025
8a1353d
Merge pull request #195 from roboflow/dependabot/pip/mkdocstrings-pyt…
onuralpszr Apr 1, 2025
c3a4b7a
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Apr 7, 2025
359dcf7
Merge pull request #196 from roboflow/pre-commit-ci-update-config
onuralpszr Apr 7, 2025
ee93c15
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Apr 14, 2025
eb2a745
Merge pull request #199 from roboflow/pre-commit-ci-update-config
onuralpszr Apr 21, 2025
46344cc
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Apr 21, 2025
1ca631b
Merge pull request #200 from roboflow/pre-commit-ci-update-config
onuralpszr Apr 22, 2025
c6a8738
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Apr 28, 2025
1388f9e
Merge pull request #201 from roboflow/pre-commit-ci-update-config
onuralpszr May 4, 2025
ca1b3ba
:arrow_up: Update tox requirement
dependabot[bot] May 13, 2025
275f2f5
:arrow_up: Update mypy requirement
dependabot[bot] May 29, 2025
4a78945
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Jun 2, 2025
682ed06
:arrow_up: Update pytest requirement from ~=8.3.2 to >=8.3.2,<8.5.0
dependabot[bot] Jun 2, 2025
08c096a
Merge pull request #208 from roboflow/dependabot/pip/pytest-gte-8.3.2…
onuralpszr Jun 5, 2025
8af5a5d
Merge pull request #206 from roboflow/dependabot/pip/mypy-gte-1.11.2-…
onuralpszr Jun 5, 2025
752f5ac
Merge pull request #204 from roboflow/dependabot/pip/tox-gte-4.18.1-a…
onuralpszr Jun 5, 2025
7c3746e
Merge pull request #202 from roboflow/pre-commit-ci-update-config
onuralpszr Jun 5, 2025
bc7a7ec
add new theme
capjamesg Jun 17, 2025
cb074bc
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Jun 17, 2025
7c071b0
chore(pre_commit): ⬆ pre_commit autoupdate
pre-commit-ci[bot] Jun 30, 2025
5e36fd2
Merge pull request #209 from roboflow/pre-commit-ci-update-config
onuralpszr Jun 30, 2025
5a2fd14
update theme based on supervision feedback
capjamesg Jul 9, 2025
a23c5a2
update nav bar
capjamesg Jul 9, 2025
0aeae5e
update navigation link
capjamesg Jul 9, 2025
b5218c7
use same stylesheet as supervision
capjamesg Jul 10, 2025
f394fce
Merge pull request #214 from roboflow/new-theme
SkalskiP Jul 10, 2025
216faf7
Pin lightning==2.6.1 to avoid compromised 2.6.2/2.6.3
imbgar-roboflow May 1, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 0 additions & 39 deletions .github/workflows/publish-dev-docs.yml

This file was deleted.

74 changes: 74 additions & 0 deletions .github/workflows/publish-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
name: Build and Publish Docs

on:
push:
branches:
- develop
workflow_dispatch:
release:
types: [published]

# Ensure only one concurrent deployment
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'push' && github.ref}}
cancel-in-progress: true

# Restrict permissions by default
permissions:
contents: write # Required for committing to gh-pages
pages: write # Required for deploying to Pages
pull-requests: write # Required for PR comments

jobs:
doc-deploy:
name: Publish Docs
runs-on: ubuntu-latest
environment:
name: documentation-deployment
url: https://maestro.roboflow.com/
timeout-minutes: 10
strategy:
matrix:
python-version: ["3.10"]
steps:
- name: 📥 Checkout the repository
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
fetch-depth: 0

- name: 🐍 Install uv and set Python ${{ matrix.python-version }}
uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
with:
python-version: ${{ matrix.python-version }}

- name: 🔑 Create GitHub App token (mkdocs)
id: mkdocs_token
uses: actions/create-github-app-token@c1a285145b9d317df6ced56c09f525b5c2b6f755 # v1.11.1
with:
app-id: ${{ secrets.MKDOCS_APP_ID }}
private-key: ${{ secrets.MKDOCS_PEM }}
owner: roboflow
repositories: mkdocs-material-insiders

- name: 🏗️ Install dependencies
run: |
uv pip install -r pyproject.toml --extra docs
uv pip install -e ".[docs]"
# Install mkdocs-material-insiders using the GitHub App token
uv pip install "git+https://roboflow:${{ steps.mkdocs_token.outputs.token }}@github.com/roboflow/mkdocs-material-insiders.git@9.6.2-insiders-4.53.15#egg=mkdocs-material[imaging]"

- name: ⚙️ Configure git for github-actions
run: |
git config --global user.name "github-actions[bot]"
git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"

- name: 🚀 Deploy Development Docs
if: (github.event_name == 'push' && github.ref == 'refs/heads/develop') || github.event_name == 'workflow_dispatch'
run: |
MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} uv run mike deploy --push develop

- name: 🚀 Deploy Release Docs
if: github.event_name == 'release' && github.event.action == 'published'
run: |
latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
MKDOCS_GIT_COMMITTERS_APIKEY=${{ secrets.GITHUB_TOKEN }} uv run mike deploy --push --update-aliases $latest_tag latest
41 changes: 0 additions & 41 deletions .github/workflows/publish-release-docs.yml

This file was deleted.

17 changes: 10 additions & 7 deletions .github/workflows/test-doc.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: 🧪 Maestro Docs Test WorkFlow 📚
name: 🧪 Docs Test WorkFlow 📚

on:
pull_request:
Expand All @@ -22,13 +22,16 @@ jobs:
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
fetch-depth: 0
- name: 🐍 Set up Python
uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0

- name: 🐍 Install uv and set Python ${{ matrix.python-version }}
uses: astral-sh/setup-uv@4db96194c378173c656ce18a155ffc14a9fc4355 # v5.2.2
with:
python-version: '3.10'
python-version: ${{ matrix.python-version }}

- name: 📦 Install Packages
run: pip install -e ".[docs]"
- name: 🏗️ Install dependencies
run: |
uv pip install -r pyproject.toml --extra docs
uv pip install -e ".[docs]"

- name: 🧪 Test Docs Build
run: mkdocs build --verbose
run: uv run mkdocs build --verbose
6 changes: 3 additions & 3 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,21 @@ repos:
- id: mixed-line-ending

- repo: https://github.com/PyCQA/bandit
rev: '1.8.2'
rev: '1.8.5'
hooks:
- id: bandit
args: ["-c", "pyproject.toml"]
additional_dependencies: ["bandit[toml]"]

- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.9.4
rev: v0.12.1
hooks:
- id: ruff
args: [--fix, --exit-non-zero-on-fix]
- id: ruff-format
types_or: [ python, pyi, jupyter]

- repo: https://github.com/pre-commit/mirrors-mypy
rev: 'v1.14.1'
rev: 'v1.16.1'
hooks:
- id: mypy
149 changes: 64 additions & 85 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,115 +1,94 @@
# Contributing to Multimodal Maestro 🛠️
# Contributing to Maestro

Thank you for your interest in contributing to Multimodal Maestro (`MM` for short)!
Thank you for helping to advance Maestro! Your participation is invaluable in evolving our platform—whether you’re squashing bugs, refining documentation, rolling out new features, or even introducing an entirely new model. Every contribution pushes the project forward.

Multimodal Maestro gives you more control over Large Multimodal Models (LMMs) by providing the utilities you need to effectively prompt the models.
## Table of Contents

We are actively improving this library to add more prompting techniques.
1. [How to Contribute](#how-to-contribute)
2. [CLA Signing](#cla-signing)
3. [Google-Style Docstrings and Mandatory Type Hints](#google-style-docstrings-and-mandatory-type-hints)
4. [Reporting Bugs](#reporting-bugs)
5. [Adding a New Model](#adding-a-new-model)
6. [License](#license)

## Contribution Guidelines
## How to Contribute

We welcome contributions to:
Your contributions can be in many forms—whether it’s enhancing existing features, improving documentation, resolving bugs, or proposing new ideas. Here’s a high-level overview to get you started:

1. Add a new feature to the library (guidance below).
2. Improve our documentation and add examples to make it clear how to leverage the Multimodal Maestro library.
3. Report bugs and issues in the project.
4. Submit a request for a new feature.
5. Improve our test coverage.
1. [Fork the Repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo): Click the “Fork” button on our GitHub page to create your own copy.
2. [Clone Locally](https://docs.github.com/en/enterprise-server@3.11/repositories/creating-and-managing-repositories/cloning-a-repository): Download your fork to your local development environment.
3. [Create a Branch](https://docs.github.com/en/desktop/making-changes-in-a-branch/managing-branches-in-github-desktop): Use a descriptive name to create a new branch (e.g., `feature/your-descriptive-name`):
```bash
git checkout -b feature/your-descriptive-name
```
4. Develop Your Changes: Make your updates, ensuring your commit messages clearly describe your modifications.
5. [Commit and Push](https://docs.github.com/en/desktop/making-changes-in-a-branch/committing-and-reviewing-changes-to-your-project-in-github-desktop): Run:
```bash
git add .
git commit -m "A brief description of your changes"
git push -u origin your-descriptive-name
```
6. [Open a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request): Submit your pull request against the main development branch. Please detail your changes and link any related issues.

### Contributing Features ✨
Before merging, check that all tests pass and that your changes adhere to our development and documentation standards.

Before you contribute a new feature, consider submitting an Issue to discuss the feature so the community can weigh in and assist.
## CLA Signing

## How to Contribute Changes
In order to maintain the integrity of our project, every pull request must include a signed Contributor License Agreement (CLA). This confirms that your contributions are properly licensed under our Apache 2.0 License. After opening your pull request, simply add a comment stating:

First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `multimodal-maestro` repository to get started:

![Forking the repository](https://media.roboflow.com/fork.png)

![Creating a repository fork](https://media.roboflow.com/create_fork.png)

Then, run `git clone` to download the project code to your computer.

Move to a new branch using the `git checkout` command:

```bash
git checkout -b <your_branch_name>
```

The name you choose for your branch should describe the change you want to make (i.e. `add-few-shot-prompting`).

Make any changes you want to the project code, then run the following commands to commit your changes:

```bash
git add .
git commit -m "Your commit message"
git push -u origin main
I have read the CLA Document and I sign the CLA.
```

## 🎨 Code quality

### Pre-commit tool

This project utilizes the [pre-commit](https://pre-commit.com/) tool to maintain code quality and consistency. Before submitting a pull request or making any commits, it is important to run the pre-commit tool to ensure that your changes meet the project's guidelines.

Furthermore, we have integrated a pre-commit GitHub Action into our workflow. This means that with every pull request opened, the pre-commit checks will be automatically enforced, streamlining the code review process and ensuring that all contributions adhere to our quality standards.

To run the pre-commit tool, follow these steps:
This step is essential before any merge can occur.

1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project
## Google-Style Docstrings and Mandatory Type Hints

2. Once pre-commit is installed, navigate to the project's root directory.
For clarity and maintainability, any new functions or classes must include [Google-style docstrings](https://google.github.io/styleguide/pyguide.html) and use Python type hints. Type hints are mandatory in all function definitions, ensuring explicit parameter and return type declarations. These docstrings should clearly explain parameters, return types, and provide usage examples when applicable.

3. Run the command `pre-commit run --all-files`. This will execute the pre-commit hooks configured for this project against the modified files. If any issues are found, the pre-commit tool will provide feedback on how to resolve them. Make the necessary changes and re-run the pre-commit command until all issues are resolved.
For example:

4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you.
```python
def sample_function(param1: int, param2: int = 10) -> bool:
"""
Provides a brief description of function behavior.

### Docstrings
Args:
param1 (int): Explanation of the first parameter.
param2 (int): Explanation of the second parameter, defaulting to 10.

All new functions and classes in `multimodal-maestro` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library.
Returns:
bool: True if the operation succeeds, otherwise False.

`multimodal-maestro` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution.

Then, go back to your fork of the `multimodal-maestro` repository, click "Pull Requests", and click "New Pull Request".

![Opening a pull request](https://media.roboflow.com/open_pr.png)

Make sure the `base` branch is `develop` before submitting your PR.

On the next page, review your changes then click "Create pull request":

![Configuring a pull request](https://media.roboflow.com/create_pr_submit.png)

Next, write a description for your pull request, and click "Create pull request" again to submit it for review:

![Submitting a pull request](https://media.roboflow.com/write_pr.png)

When creating new functions, please ensure you have the following:

1. Docstrings for the function and all parameters.
2. Unit tests for the function.
3. Examples in the documentation for the function.
4. Created an entry in our docs to autogenerate the documentation for the function.
5. Please share a Google Colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that Google Colab can be accessed without any issue.

When you submit your Pull Request, you will be asked to sign a Contributor License Agreement (CLA) by the `cla-assistant` GitHub bot. We can only respond to PRs from contributors who have signed the project CLA.
Examples:
>>> sample_function(5, 10)
True
"""
return param1 == param2
```

All pull requests will be reviewed by the maintainers of the project. We will provide feedback and ask for changes if necessary.
Following this pattern helps ensure consistency throughout the codebase.

PRs must pass all tests and linting requirements before they can be merged.
## Reporting Bugs

## 📝 documentation
Bug reports are vital for continued improvement. When reporting an issue, please include a clear, minimal reproducible example that demonstrates the problem. Detailed bug reports assist us in swiftly diagnosing and addressing issues.

The `multimodal-maestro` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.
## Adding a New Model

To run the documentation, install the project requirements with `poetry install dev`. Then, run `mkdocs serve` to start the documentation server.
If you’re contributing a new model to Maestro, please adhere to these guidelines to ensure alignment with our project structure:

You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
- Directory Structure: Create a dedicated folder under the `models/` directory (e.g., `models/your_model/`). Your folder should mirror the structure seen in existing models, including:
- `core.py`: Implements the primary logic of the model.
- `loaders.py`: Manages data ingestion and preprocessing.
- `checkpoints.py`: Handles saving and loading model checkpoints.
- `inference.py`: Contains the functions for running predictions.
- `entrypoint.py`: Provides the integration interface for the model.

## 🧪 tests
- Dependencies: Update the [`pyproject.toml`](https://github.com/roboflow/maestro/blob/develop/pyproject.toml) file with any new dependencies needed by your model.
- Documentation: Add a dedicated page for your model under the `docs/` directory and update the main docs index ([`docs/index.md`](https://github.com/roboflow/maestro/blob/develop/docs/index.md)). For style guidance, refer to pages like [`florence_2.md`](https://github.com/roboflow/maestro/blob/develop/docs/models/florence_2.md), [`paligemma_2.md`](https://github.com/roboflow/maestro/blob/develop/docs/models/paligemma_2.md), or [`qwen_2_5_vl.md`](https://github.com/roboflow/maestro/blob/develop/docs/models/qwen_2_5_vl.md).

[`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.
## License

## 📄 license
By contributing to Maestro, you agree that your contributions will be licensed under the Apache 2.0 License as specified in our [LICENSE](/LICENSE) file.

By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/roboflow/multimodal-maestro/blob/develop/LICENSE.md).
Thank you for your commitment to making Maestro better. We look forward to your pull requests and continued collaboration. Happy coding!
Loading
Loading