docs: define common MLOps template contract

[Hitesh-XS]

Summary

Defines and documents the shared contract for MLOps templates and extensions so that new AI/ML capabilities follow consistent conventions across the catalog.

This extends the existing docs/MLOPS_CONTRACT.md with explicit guidance for:

• L1/L2/L3 CI profile compatibility
• shared MLOps environment variables
• extension composition and incompatibility rules

It also links the MLOps contract directly from docs/AUTHORING.md so contributors can discover these requirements from the main template-authoring documentation.

Changes

CI profile compatibility

Documented the expected behavior of MLOps templates and extensions across the layered CI model:

• L1: bare MLOps templates must scaffold successfully using a CPU-safe default configuration
• L2: extensions must be validated against their canonical template and generated-project tests must run
• L3: representative multi-extension MLOps stacks are validated through curated profiles rather than testing every possible combination

The contract also specifies that default CI must remain:

• CPU-first
• offline-capable
• free of required cloud credentials
• independent of GPUs/CUDA and external services

Shared environment variables

Added shared configuration conventions for common MLOps concerns, including:

• MODEL_NAME
• MLFLOW_TRACKING_URI

The contract requires stable naming for equivalent settings across templates, safe local defaults where possible, and explicit handling of secrets and extension-specific configuration.

MLFLOW_TRACKING_URI remains the canonical tracking URI for the shared MLflow integration rather than introducing a duplicate generic tracker variable.

Extension composition

Added rules defining when MLOps extensions can safely compose and when incompatibleWith should be used.

The contract now covers:

• template type compatibility
• extension ownership boundaries
• conflicting generated files or runtime providers
• symmetric incompatibleWith declarations
• L2/L3 validation expectations for extension composition

Concrete AI/ML incompatibility pairs remain represented through the existing compatibility guidance and registry metadata rather than being duplicated in the MLOps contract.

Authoring documentation

Updated docs/AUTHORING.md to reference docs/MLOPS_CONTRACT.md directly from the AI/ML authoring section.

Validation

• python scripts/ci/validate-registry.py

  • ✅ registry ok (6 templates, 18 extensions)

• git diff --check

  • ✅ passed

No runtime or generated-template behavior is changed by this PR; the changes define and document the shared contract for future MLOps template and extension work.

Closes#151

Summary by CodeRabbit

• Documentation
  • Expanded MLOps authoring guidance with links to the shared MLOps contract.
  • Documented requirements for CI profile compatibility, environment variables, tracker configuration, extension ownership, incompatibilities, and composition testing.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 6466c1cd-ecc4-4c14-8945-03e3f327cbc1

📥 Commits

Reviewing files that changed from the base of the PR and between 6986f9b and cd3d640.

📒 Files selected for processing (2)

• docs/AUTHORING.md
• docs/MLOPS_CONTRACT.md

---

📝 Walkthrough

Walkthrough

The PR adds MLOps CI profile, environment, tracker, and extension composition requirements to docs/MLOPS_CONTRACT.md. It also links the contract from the AI/ML authoring guidance.

Changes

MLOps contract

Layer / File(s)	Summary
CI and environment contract docs/MLOPS_CONTRACT.md, docs/AUTHORING.md	The contract defines CPU-first offline validation, synthetic or fixture data, active environment checks, secret handling, stable naming, and MLFLOW_TRACKING_URI. The authoring guide links to these requirements.
Extension composition contract docs/MLOPS_CONTRACT.md	The contract defines compatibility, ownership, symmetric incompatibleWith declarations, compatibility-matrix integration, and L2/L3 composition testing.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• docs(mlops): add contributor checklist for first MLOps template PR #121 — Covers overlapping MLOps template contribution requirements.
• Add registry mappings and CI profiles for AI/ML catalog #76 — Relates to the documented AI/ML CI profile and composition requirements.

Possibly related PRs

• Create-Python-App/cpa-templates#163 — Also links MLOPS_CONTRACT.md from docs/AUTHORING.md.

Suggested reviewers:ulises-jeremias, okason97

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the primary change: defining a common MLOps template contract.
Linked Issues check	✅ Passed	The documentation defines the requested MLOps contract areas and references the contract from AUTHORING.md [#151].
Out of Scope Changes check	✅ Passed	All changes are documentation updates that directly support the linked issue and stated objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}