feat!: add workflows namespace sub-package extras

[Nelson-PROIA]

Summary

• Add workflows and workflows-mistralai optional dependencies to pyproject.toml
• Document the PEP 420 namespace sub-package pattern in README

Changes

pyproject.toml:

[project.optional-dependencies]
workflows = ["mistralai-workflows>=2.0.0"]
workflows-mistralai = ["mistralai-workflows[mistralai]>=2.0.0"]

This enables the install matrix from the PEP 420 integration plan:

Command	Result
pip install mistralai	Client only
pip install mistralai[workflows]	Client + workflows core
pip install mistralai[workflows-mistralai]	Client + workflows + mistralai plugin

Plugin extras use flat naming to chain dependencies (mistralai[workflows-X] → mistralai-workflows[X]), since nested pip extras are not valid syntax.

README.md: Added "Namespace Sub-packages" section documenting the pattern.

TODO: Rename mistralai plugin

The current workflows plugin is named mistralai (mistralai-workflows[mistralai]), which means the full install path is mistralai[workflows-mistralai]. This is confusing — a plugin called mistralai inside the mistralai namespace. It should be renamed to something descriptive (e.g. platform, api, core). Once renamed, the extra here needs to be updated accordingly. Waiting on workflows team decision.

Validation

Built wheels from both repos and verified the PEP 420 namespace merge in a clean venv:

# Build wheels
cd client-python && uv build         # → dist/mistralai-2.0.0a1-py3-none-any.whl
cd dashboard/workflow_sdk && uv build # → dist/mistralai_workflows-2.0.0b3-*.whl

# Install into clean venv
python3.12 -m venv /tmp/test-ns
source /tmp/test-ns/bin/activate
pip install dist/mistralai-2.0.0a1-py3-none-any.whl
pip install dist/mistralai_workflows-*.whl

# Verify both imports resolve under shared namespace
python -c "from mistralai.client import Mistral; print('client OK')"        # ✓
python -c "from mistralai.workflows import workflow; print('workflows OK')"  # ✓

Both packages install under site-packages/mistralai/ with no __init__.py at the namespace level — Python merges client/ and workflows/ automatically.

Known issue

mistralai pins opentelemetry-semantic-conventions>=0.59b0,<0.60. mistralai-workflows transitively pulls in opentelemetry-semantic-conventions==0.60b1, which violates the client's <0.60 upper bound. Fix: widen the client's upper bound to <0.61. This dependency is generated by Speakeasy, so it needs to be updated in the next SDK generation or overridden manually (the file is in .genignore).

[Nelson-PROIA]

CI fails because uv sync --all-extras resolves mistralai-workflows>=2.0.0 from PyPI. Published versions (<=2.0.0b3) pin opentelemetry-semantic-conventions<=0.58b0, conflicting with this repo's >=0.59b0,<0.60. Unblocked once the updated mistralai-workflows with compatible otel deps is published.

[louis-sanna-dev]

Very nice.

I'm blocking the merge since we need before merging:

• to update the workflow package to respect the target structure mistralai/workflows
• to solve those otel issues

[louis-sanna-dev]

@Nelson-PROIA [remark] ah I finally understand how we solve the nested nested problem. very nice.

The only issue that we will need to update this list every time workflows adds an extra, which is a bit painful.

Maybe we could document the "raw install"

pip install "mistralai-workflows[mistralai,my-provider]" # plugins directly

Also I wonder if we should add uv example, the entire ecosystem is moving to uv.