Add an examples/ directory demonstrating downstream-SDK integration via the extension API

[splch]

Background

ionq-core is the low-level client that higher-level SDKs (qiskit-ionq, cirq-ionq, pennylane-ionq) build on, through the extension API — a ClientExtension bundle plus the EventHook / AsyncEventHook protocols passed to IonQClient(extension=...). It's documented in ionq_core/extensions.py, but there's no runnable example and no examples/ directory.

What to build

A top-level examples/ directory with a sync and an async example that act as a downstream SDK wrapping ionq-core, run against the free simulator (sign up: https://identity.ionq.com/create-account).

• downstream_integration.py (sync): build an IonQClient(extension=...) that sets a user_agent_token, default_headers, an EventHook (logging), and an error_mapper (wrap APIError / RateLimitError into an SDK-defined type); then submit a Bell state, wait_for_job, and print the probabilities.
• downstream_integration_async.py: the same flow with an AsyncEventHook and the asyncio endpoint variants.

Definition of done

• examples/ with both scripts and a README.md (setup: pip install ionq-core, export IONQ_API_KEY=...), linked from the top-level README.md.
• Sync example exercises user_agent_token, default_headers, an EventHook, and the error_mapper; async example uses AsyncEventHook + asyncio variants.
• Uses only public API (ionq_core.__all__); SPDX header on each file (AGENTS.md).
• uv run ruff check, uv run ruff format --check, and uv run ty check examples/ pass. (Needn't run in CI — no API key — but must lint and type-check.)

Notes

httpx-only; auth prefix is apiKey, not Bearer; no new runtime deps. References: extension API docs, ionq_core/extensions.py, ionq_core/ionq_client.py, and the Bell-state quickstart in README.md.

[jyesh310]

Hi is there any reference docs for this ?

[lukedev45]

Hi @splch, I have cerated a draft PR for this issue. I will request a review for when it is ready.

[yanziwei]

Status refresh for PR #64: #64

The PR is open, non-draft, mergeable, and the Snyk check is green. I re-ran the requested local validation today:

• uv run ruff check
• uv run ruff format --check
• uv run ty check examples/
• uv run python -m compileall -q examples

All passed. The PR remains focused on the issue scope: sync and async downstream SDK integration examples using only public API, with ClientExtension, user-agent token, default headers, sync/async event hooks, error mapping, setup docs, README link, SPDX headers, and AI assistance disclosure.

[RafsanNeloy]

I'd appreciate it if you could review #79

[splch]

unitaryHACK26 result: this bounty goes to @lukedev45 via #67 - congratulations, and thanks for the only submission that demonstrates the error_mapper end-to-end! Please contact the unitaryHACK organizers (hack@unitary.foundation) so they can update your payout total. Thanks to everyone who competed; every submission received individual review feedback on its PR. #67 merges once CI completes; closing this issue per the organizers.