[Advanced]: Prompt code rabbit on how to review src/hiero_sdk_python/query

[exploreriii]

🧠 Advanced Contributors

This issue is intended for contributors who are already very familiar with the
Hiero Python SDK codebase and its architectural patterns.

You should feel comfortable:

• navigating multiple modules across src/
• understanding and modifying core SDK abstractions
• reasoning about API design and backwards compatibility
• updating or extending tests, examples, and documentation as needed
• making changes that may affect public-facing behavior

New developers should start with
Good First Issues or Intermediate Issues first.

🐞 Problem Description

We can prompt code rabbit with tailored instructions when reviewing query files.

💡 Proposed / Expected Solution

We should prompt it

🧠 Implementation & Design Notes

Edit .coderabbit.yaml

Similar to the other prompts, add a prompt for
src/hiero_sdk_python/query

Explain to how provide high-quality reviews for query transactions and classes

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem and design goals described above
• Maintain backwards compatibility unless explicitly approved otherwise
• Follow existing architectural and coding conventions
• Include comprehensive tests covering new and existing behavior
• Update relevant examples and documentation
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context, Links, or Prior Art

Optional.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• [Intermediate]: Create a Prompt to Code Rabbit to Explain to it how to review /docs #1236
• [Advanced]: Prompt code rabbit on how to review tests/unit and tests/integration #1193
• [Advanced]: Prompt Coderabbit on how to review /examples #1180

🔗 Related PRs

#1137 - feat: create new .github/ISSUE_TEMPLATE/05_intermediate_issue.yml [merged]
#1174 - ci: coderabbit yaml [merged]
#1189 - feat: Add custom CodeRabbit instructions for examples [merged]
#1231 - chore: enhance unit and integration test review instructions [merged]

👤 Suggested Assignees

• exploreriii
• AntonioCeppellini
• Adityarya11
• MonaaEid

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Add CodeRabbit review instructions for the query module (src/hiero_sdk_python/query/**/*) to provide automated guidance when reviewing query class implementations and changes.

Observations

The Hiero Python SDK uses CodeRabbit for automated code review with path-specific instructions defined in .coderabbit.yaml. The file currently contains three instruction sets (examples, unit tests, integration tests) that follow a consistent format: role statement, numbered priorities with actionable checks, and a philosophy section.

The query module implements a Template Method pattern where all query classes inherit from a base Query(_Executable) class and must implement three abstract methods:

• _make_request() for building protobuf requests
• _get_method() for gRPC method selection
• _get_query_response() for response extraction

Queries have unique characteristics including cost-querying capabilities, retry logic, and protobuf-to-domain object conversion patterns.

Assumptions

Assumption 1: Instruction Block Format

Options Considered:

• Follow the established format with role statement, numbered priorities, and philosophy section
• Create a new simplified format specific to queries
• Use a checklist-style format without narrative structure

Chosen Option: 1

Rationale: Consistency with existing prompts ensures CodeRabbit can apply the same parsing logic and developers can understand the structure easily. The established format has proven effective for examples, unit tests, and integration tests.

Assumption 2: Scope and Length

Options Considered:

• Create comprehensive 80-120 line instruction block matching existing prompts
• Create minimal 20-30 line instruction with only critical checks
• Create extensive 200+ line instruction covering all edge cases

Chosen Option: 1

Rationale: The 80-120 line range matches existing prompts in scope and ensures adequate coverage without overwhelming the reviewer or CodeRabbit. It balances comprehensiveness with maintainability.

Assumption 3: Priority Organization

Options Considered:

• Five priorities covering Template Method, cost queries, retry logic, protobuf conversion, and API design
• Three priorities covering only the most critical patterns
• Seven priorities with granular separation of each concern

Chosen Option: 1

Rationale: Five priorities provide comprehensive coverage of query-specific patterns while maintaining alignment with the structure of existing prompts. This grouping naturally separates concerns: core implementation, unique features, error handling, serialization, and compatibility.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Add Query Module Review Instructions

Add a new path instruction block to .coderabbit.yaml that provides CodeRabbit with guidance for reviewing query implementations, following the established format and style of existing prompts while focusing on query-specific architectural patterns.

Task 1: Create Query Module Path Instruction Block

Add a new entry to the path_instructions section in .coderabbit.yaml for path pattern src/hiero_sdk_python/query/**/*

• Position the new instruction block after the existing three instruction blocks (examples, unit tests, integration tests) in the path_instructions array
• Begin with the role statement: "You are acting as a senior maintainer of the Hedera query module..." (matching the tone and structure of existing prompts)
• Follow the established format: role statement, 5 numbered PRIORITIES with bullet-pointed checks, and a closing PHILOSOPHY section
• Ensure the instruction is 80-120 lines to match the scope of existing prompts

Task 2: Write Priority 1 - Template Method Implementation

Create Priority 1 focusing on the three required abstract methods all queries must implement

• Open with "PRIORITY 1: Verify correct implementation of the Template Method pattern"
• Include specific checks for _make_request(): validates required fields exist (e.g., if not self.account_id), calls _make_request_header() for header generation, constructs protobuf using .CopyFrom(), and wraps result in query_pb2.Query
• Include specific checks for _get_method(): returns _Method object with correct query_func pointing to appropriate gRPC channel method (e.g., channel.crypto.cryptoGetBalance)
• Include specific checks for _get_query_response(): extracts correct response field matching the query type (e.g., response.cryptogetAccountBalance for account balance queries)
• Add assertion-style language: "Assert that field names match protobuf definitions" and "Assert that all required abstract methods are implemented"

Task 3: Write Priority 2 - Cost Query and Response Type Handling

Create Priority 2 addressing the cost-querying capability unique to queries

• Open with "PRIORITY 2: Validate cost query functionality and response type management"
• Check that queries correctly handle ResponseType.COST_ANSWER for cost estimation versus ResponseType.ANSWER_ONLY for actual execution
• Verify get_cost(client) works correctly by ensuring _make_request_header() sets the appropriate response type based on whether payment is provided
• Assert that payment requirement logic correctly determines if the query needs explicit payment (non-free queries must handle payment properly)
• Include checks for cost query examples if documentation changes are part of the review

Task 4: Write Priority 3 - Retry Logic and Error Mapping

Create Priority 3 covering sophisticated error handling mechanisms

• Open with "PRIORITY 3: Ensure correct retry logic and error handling patterns"
• Verify _should_retry() returns appropriate _ExecutionState enum values (RETRY, FINISHED, ERROR) based on status codes
• Check that _map_status_error() returns correct error types: PrecheckError for precheck code failures, ReceiptStatusError for receipt status failures in transaction queries
• For transaction-related queries (TransactionGetReceiptQuery, TransactionRecordQuery), assert that retryable status sets include appropriate codes: BUSY, UNKNOWN, RECEIPT_NOT_FOUND, RECORD_NOT_FOUND, PLATFORM_NOT_ACTIVE
• Verify that streaming queries implement exponential backoff with sensible defaults (e.g., max_attempts=10, max_backoff=8.0 for TopicMessageQuery)

Task 5: Write Priority 4 - Protobuf and Domain Object Conversion

Create Priority 4 focusing on serialization and deserialization correctness

• Open with "PRIORITY 4: Validate protobuf construction and domain object conversion"
• Assert that protobuf message construction follows the pattern: validate inputs → build header → create message → copy fields using .CopyFrom() → wrap in query_pb2.Query
• Verify domain object conversion uses _from_proto() methods with proper field validation (check required fields exist before processing)
• Check that gRPC method selection matches the query type and uses the correct service stub (e.g., channel.crypto for crypto queries, channel.consensus for consensus queries)
• Ensure error handling wraps operations in try-except blocks with appropriate debug logging

Task 6: Write Priority 5 - API Design and Backwards Compatibility

Create Priority 5 addressing public API surface and compatibility concerns

• Open with "PRIORITY 5: Maintain backwards compatibility and consistent API design"
• Verify that public method signatures remain unchanged unless explicitly approved for breaking changes
• Check that fluent API patterns (.set_*() methods) follow established query conventions and return self for chaining
• Assert that new query parameters have sensible defaults that don't break existing code
• Ensure changes to response mapping maintain the same public object structure
• AVOID introducing new abstractions or patterns that diverge from existing query implementations

Task 7: Write Philosophy Section

Add closing PHILOSOPHY section explaining the design principles behind query implementations

• Title the section "PHILOSOPHY:" (matching existing prompt format)
• Emphasize that queries use the Template Method pattern to ensure consistency across all query types while allowing customization through three focused abstract methods
• Explain that queries prioritize network efficiency through cost estimation (COST_ANSWER) and intelligent retry logic with exponential backoff
• Note that the separation of concerns (request building, gRPC method selection, response extraction) enables maintainability and makes query behavior predictable
• State that backwards compatibility is critical because queries form the read-path for user applications and breaking changes affect all SDK consumers
• Conclude with: "Simplicity and alignment with existing patterns should guide any new query implementations. When in doubt, extend the existing template rather than creating new abstractions."

🤖 Prompt for AI agents

This phase adds a new CodeRabbit path instruction block to `.coderabbit.yaml`
for the query module following the established format. The goal is to provide
automated review guidance for query implementations.

Locate the `path_instructions` section in `.coderabbit.yaml` and add a new entry
after the existing three instruction blocks with path pattern
`src/hiero_sdk_python/query/**/*`

Structure the instruction block with:
- Role statement: "You are acting as a senior maintainer of the Hedera query
module..."
- 5 numbered PRIORITIES with bullet-pointed checks
- Closing PHILOSOPHY section
- Total length: 80-120 lines

PRIORITY 1 - Template Method Implementation:
- Title: "Verify correct implementation of the Template Method pattern"
- Check `_make_request()`: validates required fields, calls
`_make_request_header()`, constructs protobuf with `.CopyFrom()`, wraps in
`query_pb2.Query`
- Check `_get_method()`: returns `_Method` object with correct `query_func` for
gRPC channel method
- Check `_get_query_response()`: extracts correct response field matching query
type
- Use assertion-style language: "Assert that field names match protobuf
definitions"

PRIORITY 2 - Cost Query and Response Type Handling:
- Title: "Validate cost query functionality and response type management"
- Check handling of `ResponseType.COST_ANSWER` vs `ResponseType.ANSWER_ONLY`
- Verify `get_cost(client)` and `_make_request_header()` response type logic
- Assert payment requirement logic for non-free queries
- Check cost query documentation examples

PRIORITY 3 - Retry Logic and Error Mapping:
- Title: "Ensure correct retry logic and error handling patterns"
- Verify `_should_retry()` returns correct `_ExecutionState` enum values
- Check `_map_status_error()` returns `PrecheckError` or `ReceiptStatusError`
appropriately
- Assert transaction queries include retryable statuses: `BUSY`, `UNKNOWN`,
`RECEIPT_NOT_FOUND`, `RECORD_NOT_FOUND`, `PLATFORM_NOT_ACTIVE`
- Verify streaming queries use exponential backoff (e.g., max_attempts=10,
max_backoff=8.0)

PRIORITY 4 - Protobuf and Domain Object Conversion:
- Title: "Validate protobuf construction and domain object conversion"
- Assert protobuf pattern: validate inputs → build header → create message →
`.CopyFrom()` → wrap in `query_pb2.Query`
- Verify `_from_proto()` methods with field validation
- Check gRPC method selection matches service stub (e.g., `channel.crypto`,
`channel.consensus`)
- Ensure try-except blocks with debug logging

PRIORITY 5 - API Design and Backwards Compatibility:
- Title: "Maintain backwards compatibility and consistent API design"
- Verify public method signatures remain unchanged
- Check fluent API patterns (`.set_*()` methods return `self`)
- Assert new parameters have sensible defaults
- Ensure response mapping maintains public object structure
- AVOID new abstractions diverging from existing patterns

PHILOSOPHY section:
- Title: "PHILOSOPHY:"
- Emphasize Template Method pattern ensures consistency
- Explain network efficiency through cost estimation and retry logic
- Note separation of concerns enables maintainability
- State backwards compatibility is critical for read-path applications
- Conclude: "Simplicity and alignment with existing patterns should guide any
new query implementations. When in doubt, extend the existing template rather
than creating new abstractions."

---

🚀 Next Steps

🤖 All AI agent prompts combined

This phase adds a new CodeRabbit path instruction block to `.coderabbit.yaml`
for the query module following the established format. The goal is to provide
automated review guidance for query implementations.

Locate the `path_instructions` section in `.coderabbit.yaml` and add a new entry
after the existing three instruction blocks with path pattern
`src/hiero_sdk_python/query/**/*`

Structure the instruction block with:
- Role statement: "You are acting as a senior maintainer of the Hedera query
module..."
- 5 numbered PRIORITIES with bullet-pointed checks
- Closing PHILOSOPHY section
- Total length: 80-120 lines

PRIORITY 1 - Template Method Implementation:
- Title: "Verify correct implementation of the Template Method pattern"
- Check `_make_request()`: validates required fields, calls
`_make_request_header()`, constructs protobuf with `.CopyFrom()`, wraps in
`query_pb2.Query`
- Check `_get_method()`: returns `_Method` object with correct `query_func` for
gRPC channel method
- Check `_get_query_response()`: extracts correct response field matching query
type
- Use assertion-style language: "Assert that field names match protobuf
definitions"

PRIORITY 2 - Cost Query and Response Type Handling:
- Title: "Validate cost query functionality and response type management"
- Check handling of `ResponseType.COST_ANSWER` vs `ResponseType.ANSWER_ONLY`
- Verify `get_cost(client)` and `_make_request_header()` response type logic
- Assert payment requirement logic for non-free queries
- Check cost query documentation examples

PRIORITY 3 - Retry Logic and Error Mapping:
- Title: "Ensure correct retry logic and error handling patterns"
- Verify `_should_retry()` returns correct `_ExecutionState` enum values
- Check `_map_status_error()` returns `PrecheckError` or `ReceiptStatusError`
appropriately
- Assert transaction queries include retryable statuses: `BUSY`, `UNKNOWN`,
`RECEIPT_NOT_FOUND`, `RECORD_NOT_FOUND`, `PLATFORM_NOT_ACTIVE`
- Verify streaming queries use exponential backoff (e.g., max_attempts=10,
max_backoff=8.0)

PRIORITY 4 - Protobuf and Domain Object Conversion:
- Title: "Validate protobuf construction and domain object conversion"
- Assert protobuf pattern: validate inputs → build header → create message →
`.CopyFrom()` → wrap in `query_pb2.Query`
- Verify `_from_proto()` methods with field validation
- Check gRPC method selection matches service stub (e.g., `channel.crypto`,
`channel.consensus`)
- Ensure try-except blocks with debug logging

PRIORITY 5 - API Design and Backwards Compatibility:
- Title: "Maintain backwards compatibility and consistent API design"
- Verify public method signatures remain unchanged
- Check fluent API patterns (`.set_*()` methods return `self`)
- Assert new parameters have sensible defaults
- Ensure response mapping maintains public object structure
- AVOID new abstractions diverging from existing patterns

PHILOSOPHY section:
- Title: "PHILOSOPHY:"
- Emphasize Template Method pattern ensures consistency
- Explain network efficiency through cost estimation and retry logic
- Note separation of concerns enables maintainability
- State backwards compatibility is critical for read-path applications
- Conclude: "Simplicity and alignment with existing patterns should guide any
new query implementations. When in doubt, extend the existing template rather
than creating new abstractions."

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[github-actions]

@coderabbitai plan

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[github-actions]

Hi @manishdait 👋

This issue has been assigned but no pull request has been created yet.
Are you still planning on working on it?

From the Python SDK Team