feat(benchmarks): add unified benchmark suite

[Globalpropertyguy]

Closes #5.

Summary

• add benchmarks/suite.py with Bell, 3-qubit GHZ, and deterministic random depth-5 circuits
• support --executor local --shots N and repeated --executor flags for comparison runs
• render the CONTRIBUTING.md §5 table columns exactly
• skip executor/circuit failures, log to stderr, and continue the suite
• add parametrized tests plus skip-and-log coverage

Verification

• /tmp/marqov-sdk-venv/bin/python -m ruff check benchmarks/suite.py tests/test_benchmark_suite.py
• focused benchmark-suite tests: 7 passed using explicit lightweight stubs for optional cloud/circuit SDK imports

Local environment note

• Full uv run --extra dev --extra all ... setup remains blocked locally because llvmlite needs cmake, which is not installed on this machine. The failure is in Braket simulator dependency setup before the benchmark tests run.

[ddri]

Thanks for the PR. I see you're a brand new account, making a number of PRs on projects in the unitaryHACK listing (and your Marqov submission were even before the event started!). The concern here would be that AI has done all the work, and there's not been any good-faith effort to really understand the project, make thoughtful decisions, and properly test the solution in context.

To help me understand if that's the case, I'd like to hear your thoughts on this, and talk a little about your experience and approach using the Marqov SDK.

[Globalpropertyguy]

Thanks for raising this directly. I understand the concern, especially given the timing and the fact that this is a new account.

I did use AI assistance while working on this PR, but I do not want to represent it as a black-box "agent submitted this and I have no idea what it does." My intent was to solve the specific benchmark-harness request in #5 in the smallest way that matched the project's existing executor interface and the Section 5 benchmark format in CONTRIBUTING.md.

My understanding of the Marqov SDK in this area is:

• executors share the async BaseExecutor.execute(circuit, shots=...) -> ExecutionResult interface;
• ExecutionResult already normalizes counts, shots, backend, and execution_time_ms, so the benchmark harness should not need provider-specific result parsing;
• the benchmark cases should use Marqov-native circuits rather than external framework circuits, which is why I used bell_state, ghz_state(3), and a deterministic small random circuit;
• repeated --executor flags are intended to compare executor/circuit combinations while keeping the output in the exact table shape from CONTRIBUTING.md;
• the suite should continue on backend/circuit failure because comparing multiple executors should not be invalidated by one unavailable backend.

The main design choice I made was to keep the first version deliberately narrow: local executor support through a simple factory, repeated --executor flags, deterministic cases, top-3 outcome rendering, and stderr skip logging. I avoided adding cloud executor configuration or a broader benchmark framework because that seemed beyond #5 and would be hard to test responsibly without provider credentials.

For testing, I added focused tests around the deterministic parts: top-outcome ordering, table formatting, result-to-row conversion, one-row-per-case execution, and skip/log behavior. Ruff passes for the touched files:

/tmp/marqov-sdk-venv/bin/python -m ruff check benchmarks/suite.py tests/test_benchmark_suite.py

I also want to be clear about what I have not fully verified. A full local install/test run is currently blocked on this machine by the Braket/default-simulator dependency chain: llvmlite fails to build because cmake is not installed. I retried today and hit the same blocker during pip install -e .:

FileNotFoundError: llvmlite needs CMake tools to build.

So I should not overclaim that this has had a clean full-project test pass in my local environment.

On the unitaryHACK timing point: I was looking through listed repos before the event window and opened this before realizing that could create exactly this kind of trust issue. If that makes this inappropriate for event/bounty consideration, I understand. I am happy for this to be reviewed purely as a normal contribution, or to withdraw it if that is the better outcome for the project.

If you think the PR is directionally useful, I am happy to tighten it based on how you expect Marqov benchmarks to be used. For example, I can:

1. keep it local-only as a minimal benchmark harness;
2. add support for configured non-local executors if you point me to the intended pattern;
3. adjust the output/schema to better fit your docs;
4. add more integration-style tests once the expected local dev setup is clear.

I am also happy to walk through any part of the implementation or revise it based on your feedback.