feat(broker): add Core-only Broker Alpha - #67
Merged
Conversation
…eneric runner Tributo needs an optional control-plane integration for internal Redis Streams tasks, lifecycle events, and cooperative cancellation. Redis and KnoVa protocol models must stay in a separately installed provider wheel, so Core only gains a safe, lazily loaded, versioned Broker extension contract. The provider wheel is developed separately (independent tributo-broker-redis repository); this branch carries only the Core side. - Broker SPI: BrokerPlugin, BrokerRuntime, TaskConsumer, EventReporter, CancellationChecker, Message/JobResult identity fields, TaskDisposition, and JSON-safe CancellationSpec; new dataclass fields default so existing constructions keep working. - Lazy discovery: tributo.brokers entry-point group, fail-open discovery with diagnostics, fail-closed explicit resolution, TRIBUTO_PLUGINS filtering, and api_version/broker_id/capabilities contract checks. - Broker Registry and generic BrokerRunner with ACK/RETRY/REJECT, bounded reconnect backoff, DEGRADED/RECONNECTING lifecycle states, and graceful shutdown. - Lazy CLI: broker list/validate/consume mounted through a lazy Click group; importing tributo.cli does not import the broker modules. - Runtime injection: build_runtime_env extra_py_modules/runtime_pip_packages and submit_training_job execution_context plumbing; the default path adds no pip section. - Identity mapping: submit_training_job_with_identity returns run_id, attempt_id, submission_id, and the Ray execution job_id; reconcile resolves the real execution ID when available and retains a compatibility fallback. - Training bridge: worker-side cancellation checker rebuilt from JSON-safe specs (fail-open), _tributo_* keys stripped before strict config validation, cancel state surfaced in report metrics, and Ray Train metrics/history preserved in the lifecycle summary for provider replay. - Docs: STABILITY.md beta entries for the three broker modules and ADR 002 (broker plugin boundary). - Targeted Core suite (broker SPI, discovery, runner, CLI isolation, runtime env, stability inventory, training lifecycle): `pytest -p no:cacheprovider tests/test_broker.py tests/test_broker_cli.py tests/test_runtime_env.py tests/test_stability_inventory.py tests/training/test_job_submitter.py tests/training/test_training_lifecycle.py -q` — 766 passed, 6 skipped. - Full Core non-IT regression: `pytest -p no:cacheprovider tests --ignore=tests/integration -q` — 2867 passed, 40 skipped, 171 deselected. - Core Ray runtime-environment IT: `tests/integration/test_ray_runtime_env.py -m ray_runtime_env` — 1 passed. - Lint: ruff format check and ruff check on the changed files pass, plus pre-commit hooks; git diff --check passes. - Real Redis Stream/Ray provider IT is intentionally excluded from this Core-only commit and is maintained in the independent provider repository. - [x] Unit tests pass - [x] Lint passes for changed Python files (ruff format --check, ruff check, and pre-commit) - [x] Integration tests pass (if applicable) — Core ray-runtime IT passed; real Redis/Ray provider IT lives in the independent provider repository - [x] No internal credentials, URLs, or tokens exposed - [x] New external dependencies reviewed for license compatibility — no new dependencies Signed-off-by: jiangxt2 <jiangxt2@vip.qq.com>
Signed-off-by: jiangxt2 <jiangxt2@vip.qq.com>
Signed-off-by: jiangxt2 <jiangxt2@vip.qq.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR introduces a Core-only, transport-neutral Broker Alpha API so external provider packages can integrate Redis Streams or other brokers without adding transport dependencies or production consume loops to Tributo.
The change:
RayJobSubmissioncontract, deterministicsubmission_idgeneration, ambiguous Ray Jobs submission reconciliation, and status/stop operations keyed bysubmission_id;ray_job_idoptional and populates it only from a real RayJobDetails.job_id;tributo broker listandtributo broker validatecommands without importing broker registries or providers on normal CLI paths; andThis is an Alpha API change. Provider packages own transport connections, consumer groups, acknowledgements, re-delivery and recovery, cancellation watchers, external task/event schemas, production consume runtimes, and terminal-event durability. Core does not add Redis dependencies, provider runtime-environment injection, a generic consume loop, worker-side broker cancellation, or exactly-once guarantees.
Normal Tributo CLI and runtime behavior remain unchanged when no broker provider is selected.
pyproject.tomlanduv.lockare unchanged.Related issues
None.
Additional information
Validation on commit
f0d8e93c2af12db29575b920cd2589ae55ea72d9:uv run --locked --no-sync python scripts/pr-precheck.py --skip-testspassed with the repository's existing non-blocking warnings. The command's CI-parity unit-test matrix passed on Python 3.12 and 3.13, and strict docs and spelling checks passed. The changed-test selection was also exercised once on the same final HEAD and is covered by the passing CI-parity matrix.git diff --check origin/master...HEADpassed.Redis/Ray provider Docker integration tests were not run in this repository. Those healthy-path and transport-recovery tests belong to the independently versioned provider package and are outside this Core-only PR.