SEG-52: add v2 async helpers (submit_async, run_async, AsyncJob)

[shrey-rajvanshi]

Summary

Adds v2 async support to the Python SDK — submit-and-poll for any heimdall `/v2/{slug}` model — so callers can stop wrapping their own request/poll loops around `requests.post`.

```python
import segmind

One-shot: submit + poll until COMPLETED

result = segmind.run_async("seedance-1-pro", prompt="A sunset", timeout=300)

Or split for finer control (parallelism, request_id tracking)

job = segmind.submit_async("seedance-1-pro", prompt="A sunset")
print(job.request_id)
result = job.wait(timeout=300)
```

Defaults: `interval=1.0s`, `timeout=600s`. Override per call for very slow models (Veo, Seedance video) or use webhooks (SEG-93) instead.

What's in

• New module `segmind/v2.py` — `AsyncJob`, `InferenceFailed`, `InferenceTimeout`, internal `submit()` / `run()` / `_v2_base()`.
• `SegmindClient.submit_async()` and `.run_async()` methods on the existing client.
• Module-level `segmind.submit_async()` / `segmind.run_async()` resolving through the lazy default client.
• 11 respx-mocked unit tests covering submit, wait, polling progression, FAILED, TIMEOUT, one-shot, staging URL derivation, and module-level exports.

What's deliberately NOT in

• Polling-hints consumption — SEG-243 was cancelled; this is a plain client. Caller tunes `timeout`/`interval` per call.
• Async/await variant (`httpx.AsyncClient`) — separate ticket if/when wanted; the SDK is otherwise sync.
• Webhook helpers — SEG-93 is the heimdall side; SDK webhook surface is a different concern.

Design notes

• Exception names skip the `Error` suffix (`InferenceFailed`/`InferenceTimeout`). Reads naturally in caller code; per-file `# ruff: noqa: N818`.
• `_v2_base()` derives the v2 prefix from `client.base_url` — callers using `api-latest.segmind.com/v1` for staging automatically get the matching `/v2` host with no extra config.
• Loud-fail on a 2xx submit missing `request_id` / `status_url` / `response_url` instead of polling forever on a missing URL. Server contract is to always return all three.
• `FAILED` path fetches the full result body (not just the status one) so the exception carries metrics + request_id alongside the error string.

Smoke

• 11 / 11 unit tests pass via `pytest tests/test_v2.py`.
• `ruff check` clean.
• `black --check` clean.
• Live one-shot vs `api-latest.segmind.com/v2/mock-inference` (sleep=1, credits=1e-6) returned `COMPLETED` with `inference_time=1.013s`.
• Live timeout path (`sleep=5, timeout=1`) raised `InferenceTimeout` cleanly with the expected request_id in the message.

Tickets

Parent: SEG-52 "SDK async" (Phase 1 — Async core).
Cancelled sibling: SEG-243 (server-side polling hints — decided we don't need them; client picks defaults).
Related: SEG-93 (webhooks, for slow models).

[gemini-code-assist]

Code Review

This pull request introduces v2 async inference capabilities to the Segmind Python SDK, adding submit_async and run_async methods alongside an AsyncJob class for polling and retrieving results. The feedback focuses on optimizing the polling loop in AsyncJob.wait to avoid sleeping past the timeout deadline, removing the unused _TERMINAL_STATES constant, and exposing SegmindError at the package level to simplify exception handling and unit tests.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The current polling loop can sleep past the deadline and make an unnecessary HTTP request after the timeout has already expired. Additionally, if the timeout is reached during the sleep, the loop will still perform another status check before raising InferenceTimeout. We can optimize this by checking the deadline at the start of the loop, checking if the remaining time is exceeded before sleeping, and capping the sleep interval to the remaining time.

        deadline = time.monotonic() + timeout
        while True:
            if time.monotonic() >= deadline:
                raise InferenceTimeout(
                    request_id=self.request_id,
                    elapsed_s=timeout,
                )

            status_body = self.status()
            state = status_body.get("status")

            if state == "COMPLETED":
                return self.result()

            if state == "FAILED":
                # /status carries the error for FAILED; pull the full body
                # so the exception caller has metrics + request_id alongside.
                final = self.result()
                err = final.get("error") or status_body.get("error")
                raise InferenceFailed(detail=err, response_body=final)

            remaining = deadline - time.monotonic()
            if remaining <= 0:
                raise InferenceTimeout(
                    request_id=self.request_id,
                    elapsed_s=timeout,
                )
            time.sleep(min(interval, remaining))

[gemini-code-assist]

The constant _TERMINAL_STATES is defined but never used anywhere in the module. It should be removed to keep the codebase clean and maintainable.

[gemini-code-assist]

Exposing SegmindError at the package level (segmind.SegmindError) is highly recommended so that users of the SDK can easily import and catch the base exception class without needing to import from internal modules. This also avoids workarounds in the test suite.

Suggested change

	from segmind.v2 import (
	DEFAULT_POLL_INTERVAL_S,
	DEFAULT_POLL_TIMEOUT_S,
	AsyncJob,
	InferenceFailed,
	InferenceTimeout,
	)
	from segmind.exceptions import SegmindError
	from segmind.v2 import (
	DEFAULT_POLL_INTERVAL_S,
	DEFAULT_POLL_TIMEOUT_S,
	AsyncJob,
	InferenceFailed,
	InferenceTimeout,
	)

[gemini-code-assist]

Add SegmindError to all to explicitly export it as part of the public API.

Suggested change

	"DEFAULT_POLL_INTERVAL_S",
	"DEFAULT_POLL_TIMEOUT_S",
	"AsyncJob",
	"InferenceFailed",
	"InferenceTimeout",
	"DEFAULT_POLL_INTERVAL_S",
	"DEFAULT_POLL_TIMEOUT_S",
	"AsyncJob",
	"InferenceFailed",
	"InferenceTimeout",
	"SegmindError",

[gemini-code-assist]

With SegmindError exposed at the package level, we can simplify this assertion and remove the conditional hasattr check.

Suggested change

	with pytest.raises(segmind.SegmindError if hasattr(segmind, "SegmindError") else Exception):
	with pytest.raises(segmind.SegmindError):

[shrey-rajvanshi]

Self-review pass — pushed 2c34e83

Two cleanups before the tester session reports back. Both are pure simplifications — no public-API surface changes other than one field rename on the failure exception.

1. Removed unused _TERMINAL_STATES

The constant was defined and never referenced; `wait()` checks `state == "COMPLETED"` / `state == "FAILED"` directly. Deleted.

2. FAILED path no longer does an extra HTTP round-trip

Before:
```python
if state == "FAILED":
final = self.result() # extra GET /v2/requests/{id}
err = final.get("error") or status_body.get("error")
raise InferenceFailed(detail=err, response_body=final)
```

After:
```python
if state == "FAILED":
raise InferenceFailed(
detail=status_body.get("error"),
status_body=status_body,
)
```

`/v2/requests/{id}/status` already carries the error string on FAILED (heimdall SEG-97), so the second GET was redundant. Saves one round-trip per failure path.

Trade-off: the exception now carries the status payload (not the full result body). Callers who want server-side metrics on failure can still call `AsyncJob.result()` themselves after catching. The simpler default felt right for a no-over-engineering pass.

Field rename: `InferenceFailed.response_body` → `InferenceFailed.status_body`. The new test enforces this with `assert result_route.called is False` so any regression that re-introduces the extra GET fails the suite.

3. Module docstring polish

Dropped the `SEG-243 cancelled` reference — internal noise for SDK readers. Replaced with product-facing guidance.

Verified

• 11 / 11 tests pass.
• `ruff check` + `black --check` clean.
• Live sanity against api-latest: a bogus slug surfaces as `SegmindError(404, "Model information not found")` at submit time (caught by `raise_for_status`), confirming the FAILED-state path is reachable separately for a queued-then-failed task.

What I considered but did NOT change

• `submit_response` field on `AsyncJob` — keeps forward-compat for new server response keys; cheap to carry.
• `_v2_base()` URL derivation — robust already; cosmetic micro-rewrite not worth the loss of clarity.
• First-poll latency — the loop runs `status()` immediately (no initial sleep), so fast models pay only one poll-interval if the result didn't land within first round-trip.
• `result()` caching — YAGNI; users rarely call it twice.