Tools Workflows

Tools Overview #

The plugin’s Tools workflow is the analysis feature area inside Davix H2I. In the loaded source files, it is documented as a Tools analysis flow and is exposed in the admin modal as the Tools tab, with a REST endpoint at POST /davix-h2i/v1/tools/analyze. The Tools flow is part of the same WordPress-admin media workflow model as Image and H2I, but unlike those generate flows, it does not replace attachments or create new Media Library files. Instead, it analyzes selected attachments and returns parsed results from the upstream tools API.

The Tools tab supports selecting:

• hash
• similarity

The plugin overview and behavior docs consistently describe Tools as an analysis workflow, not a rendering or media-generation workflow.

Hash Analysis #

The Tools workflow supports hash analysis through the hash object in the request payload. The loaded documentation confirms that the allowed hash types are:

• phash
• md5
• sha1
• sha256

The behavior docs explain that the request handler reads hash.type, validates it against that allowlist, and only builds a valid tools set from supported values. If no valid tools are selected after validation, the request is treated as invalid.

That means hash analysis is available only through those four documented hash modes. The loaded files do not document additional hash algorithms beyond those four.

Similarity Analysis #

The Tools workflow also supports similarity analysis through the similarity object in the request payload. The documented supported similarity modes are:

• pairs
• tofirst

The request handler validates similarity.mode against that allowlist and reads similarity.threshold only when it falls within the accepted threshold range. If the threshold is outside the supported range, it is cleared or ignored rather than treated as valid threshold input.

The user-facing docs also make one workflow rule explicit: if similarity is selected, at least two images are required. Otherwise the request fails.

Tool Modes and Inputs #

The Tools workflow is driven by selected attachments and tool configuration values. The documented request inputs are:

• ids — required array of attachment IDs
• hash object
• similarity object

The behavior docs describe the Tools analyze flow like this:

• trigger: POST /davix-h2i/v1/tools/analyze
• permission checks run first
• the handler reads ids, hash, and similarity
• it validates the tool selection
• it builds a multipart payload
• it sends the request to the tools service
• it returns parsed upstream results
• it performs no attachment replacement or output persistence

That means the Tools workflow depends on selected existing media items. It is not documented as accepting arbitrary text input or standalone uploaded files outside the attachment-selection workflow.

[Image placeholder — Tools tab showing tool selection options for Hash and Similarity]

Threshold and Validation Rules #

The loaded source files define clear validation rules for the Tools workflow.

Required Attachment IDs #

ids must be present and non-empty. If no usable IDs are provided, the request fails with davix_h2i_missing_ids.

Hash Validation #

hash.type must be one of:

• phash
• md5
• sha1
• sha256

Similarity Mode Validation #

similarity.mode must be one of:

• pairs
• tofirst

Similarity Threshold Validation #

The supported threshold range is:

• 0 to 64

Values outside that range are cleared or ignored and are not treated as valid threshold input.

Minimum Image Count for Similarity #

If similarity is selected, the workflow requires at least two images. The user guide states this directly, and the behavior docs confirm the enforcement in the request handler.

At Least One Valid Tool Is Required #

The behavior docs also confirm that the handler enforces at least one selected valid tool. If no valid tool survives validation, the request fails as an invalid request.

Understanding Tools Results #

The user-facing docs describe the Tools response behavior simply: the endpoint returns results containing the parsed response body from the upstream tools API.

The developer and behavior references confirm the exact success shape:

{
  "results": "<decoded upstream JSON body>"
}

In other words, the plugin does not remap the upstream tools result into a new WordPress-specific result schema. It parses the upstream JSON body and returns it under the results key.

That is the key thing users should understand about Tools results:

• the plugin validates the request
• sends it upstream
• parses the upstream JSON response
• returns that parsed structure inside results
• does not create attachments or downloadable media output in the Tools flow

The appendix also identifies includes/views/tools-results.php as the template used for tools output rendering in the admin UI, confirming that the plugin has a dedicated results display surface for this workflow.

[Image placeholder — Tools results modal showing returned analysis results]

Permission and Attachment Checks #

The Tools workflow uses the same shared REST permission model as Image and H2I. The behavior docs confirm these checks:

• nonce header: x_wp_nonce
• nonce action: wp_rest
• capability requirement: upload_files
• per-attachment permission check: edit_post for every selected ID

That means a Tools request is only valid when the user is authenticated in WordPress admin and has both:

• general permission to use the feature routes
• edit permission for each attachment included in the request

No Media Replacement or Saved Output #

A major difference between Tools and the Image and H2I generate workflows is that Tools does not persist output to the Media Library. The behavior docs explicitly state:

• response parsing returns {'results': <decoded-body>}
• no local file or attachment replacement is performed in the Tools flow

This means Tools is an analysis-only workflow. It does not:

• replace the selected attachment
• create a new attachment
• download or sideload generated files into WordPress media storage

Common Tools Workflow Errors #

The behavior docs document the main top-level error types for Tools requests.

davix_h2i_missing_ids #

Returned when the request does not include a usable non-empty ids array.

davix_h2i_forbidden_attachment #

Returned when the current user cannot edit one or more of the selected attachments.

davix_h2i_missing_file #

Returned when a selected attachment’s source file cannot be found on disk. The developer reference includes missing source files among the top-level WP_Error cases for Tools analyze.

davix_h2i_invalid_request #

Returned for invalid tool selections or invalid request composition, including cases where no valid tools remain after validation.

Transport and Upstream Errors #

The Tools flow can also return top-level request errors for transport or upstream HTTP failures, including:

• davix_h2i_transport_error
• davix_h2i_upstream_error

Unlike bulk Image and bulk H2I generate flows, the Tools docs describe errors as top-level WP_Error cases for validation, transport, and upstream failures.

End-to-End Tools Workflow Summary #

The fully documented Tools workflow is:

1. Open the Tools tab in the Davix H2I modal.
2. Select one or more attachments to analyze.
3. Choose hash, similarity, or both.
4. If using hash, choose one supported hash type.
5. If using similarity, choose a supported mode and optional threshold within 0..64, and ensure at least two images are selected.
6. Run the analysis request through /davix-h2i/v1/tools/analyze.
7. Review the returned results data in the Tools results interface.