feat(sdk): collapse @distributed + deploy_distributed_managed (fixes one-covenant/basilica-backend#660)

[epappas]

Summary

Collapses three distributed-training deploy paths into ONE canonical surface, per the SDK API simplification plan (docs/plans/SDK-API-SIMPLIFICATION-PLAN.md on basilica-backend main).

• DistributedTraining becomes itself context-manager-able (__enter__ / __exit__ / __aenter__ / __aexit__).
• BasilicaClient.deploy_distributed[_managed][_async] emit DeprecationWarning on direct calls; the @basilica.distributed decorator path stays silent via an internal _emit_deprecation=False flag.
• Version bumped 0.29.4 -> 0.29.5 (API-surface change).
• New unit-test file test_distributed_canonical_surface.py pins every acceptance criterion.

After this PR, users write ONE thing:

@basilica.distributed(...)
def train(): ...

# Fire-and-forget
train()

# OR -- mid-run orchestration
with train() as training:
    training.scale(target=3)
    training.wait_until_target_world(timeout=300)
    print(training.bench)

Same handle, same semantics, no second factory to learn.

Why

Three names for the same operation taxed every new user. The decorator hid the Training handle (no .scale() / .bench mid-run), so anyone who wanted orchestration switched to deploy_distributed_managed -- a different name, different shape, same outcome. Collapsing the surface makes the decorator the canonical entry-point and keeps the same auto-cleanup contract whether you write with train() or call it bare.

Cross-repo references

• Tracking issue: one-covenant/basilica-backend#660 (this PR's merge auto-closes it via the fixes keyword in the title).
• Plan doc: docs/plans/SDK-API-SIMPLIFICATION-PLAN.md on basilica-backend main (SDK-S1 row in the wave map).
• Part of basilica-backend issue 419 follow-on work (cross-ref only -- no auto-close).

Implementation

crates/basilica-sdk-python/python/basilica/distributed.py

Added sync + async context-manager protocol to DistributedTraining. Best-effort delete() on scope exit, swallows delete-time exceptions so we never mask a caller-side exception that's already propagating. DistributedTrainingManaged is unchanged (still re-exported for type-annotation back-compat).

crates/basilica-sdk-python/python/basilica/__init__.py

Added _emit_deprecation: bool = True to deploy_distributed and deploy_distributed_async. Body-level warnings.warn(..., DeprecationWarning, stacklevel=2) when set. deploy_distributed_managed[_async] emit their own warning at entry and pass _emit_deprecation=False to the underlying deploy call (no double-warn).

crates/basilica-sdk-python/python/basilica/decorators.py

DistributedFunction.deploy() passes _emit_deprecation=False to client.deploy_distributed(...). The user opted into the canonical surface by using the decorator -- they should not see a warning that points at the surface they're already on.

crates/basilica-sdk-python/tests/test_distributed_canonical_surface.py

14 new tests pinning every ticket acceptance criterion. Pre-fix run: 12/14 fail (proving the anti-pattern exists). Post-fix run: 14/14 pass.

Version bump

• crates/basilica-sdk-python/Cargo.toml: 0.29.4 -> 0.29.5
• crates/basilica-sdk-python/pyproject.toml: 0.29.4 -> 0.29.5
• Cargo.lock: regenerated via cargo update -p basilica-sdk-python
• CHANGELOG.md: ## [0.29.5] - 2026-05-18 entry with Added + Deprecated sections.

Test plan

• New tests: 14/14 pass (test_distributed_canonical_surface.py)
• Full SDK test suite: 171 passed (the pre-existing httpx-missing skip on test_dns_propagation_e2e.py is unrelated)
• cargo fmt --all -- --check clean
• cargo clippy -p basilica-sdk --all-targets --all-features -- -D warnings clean
• Version consistency check (Cargo.toml vs pyproject.toml): both 0.29.5
• Runtime verification deferred -- the changes are SDK-internal API-shape (context-manager protocol + warnings); no operator / autoscaler / CRD surface touched. Runtime behaviour for an existing decorator user is byte-identical (Training is still returned; existing .scale()/.delete()/.bench paths still work). Existing example scripts 20/21/22 continue to function; they will migrate in SDK-S5 (separate ticket).

Migration for callers

• client.deploy_distributed_managed(...) as t: -> @basilica.distributed(...) + with train() as t:
• client.deploy_distributed(...) + manual .delete() -> same decorator + with block (auto-cleanup) OR continue calling and silence the warning (still works for two minor versions).
• Type annotations against DistributedTrainingManaged keep working -- the class is unchanged and still re-exported.

What is NOT in this PR

• command= parameter on @basilica.distributed (SDK-S3, separate ticket).
• source: Union[str, Path] deprecation in favor of Callable-only (SDK-S4).
• bench: bool + lazy training.bench: BenchResult | None collapse (SDK-S2).
• Example file migration to the new surface (SDK-S5).
• Removal of deprecated methods (SDK-S7, next major bump).

[coderabbitai]

Warning

Rate limit exceeded

@epappas has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 58 minutes and 26 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ddd98a21-f47a-4f23-8b81-9018527cba1c

📥 Commits

Reviewing files that changed from the base of the PR and between 6dff16f and d638e2f.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• crates/basilica-sdk-python/CHANGELOG.md
• crates/basilica-sdk-python/Cargo.toml
• crates/basilica-sdk-python/pyproject.toml
• crates/basilica-sdk-python/python/basilica/__init__.py
• crates/basilica-sdk-python/python/basilica/decorators.py
• crates/basilica-sdk-python/python/basilica/distributed.py
• crates/basilica-sdk-python/tests/test_distributed_canonical_surface.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sdk-660-collapse-distributed-surface

---

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 and usage tips.}