Expose GraphQL tuning parameters

[jazairi]

Why these changes are being introduced:

Semantic tuning arguments are accepted at runtime, but are intentionally hidden from GraphQL
introspection by custom visibility behavior in the schema. This creates a mismatch for downstream
clients that validate against
introspection-derived schema artifacts, including
graphql-client.

It was decided in ADR 8 to expose these arguments.

Relevant ticket(s):

• USE-680

How this addresses that need:

This adds a Tuning Parameters Input Type that
exposes the semantic tuning arguments and validates acceptable input ranges, as specified in the ADR.

Side effects of this change:

We no longer use the GraphQL::Schema::Visibility module. This should be fine, as it was only needed to call the visible? method that hid internal
arguments.

Developer

• All new ENV is documented in README
• All new ENV has been added to Heroku Pipeline, Staging and Prod
• ANDI or Wave has been run in accordance to
  our guide and
  all issues introduced by these changes have been resolved or opened as new
  issues (link to those issues in the Pull Request details above)
• Stakeholder approval has been confirmed (or is not needed)

Code Reviewer

• The commit message is clear and follows our guidelines
  (not just this pull request message)
• There are appropriate tests covering any new functionality
• The documentation has been updated or is unnecessary
• The changes have been verified
• New dependencies are appropriate or there were no changes

Requires database migrations?

NO

Includes new or updated dependencies?

NO

[qltysh]

❌ 4 blocking issues (6 total)

Tool	Category	Rule	Count
rubocop	Lint	Assignment Branch Condition size for search is too high. [<7, 17, 0> 18.38/17]	2	❌
rubocop	Lint	Avoid parameter lists longer than 5 parameters. [20/5]	1	❌
rubocop	Lint	Cyclomatic complexity for validate\_and\_build\_semantic\_options is too high. [8/7]	1	❌
qlty	Structure	Function with many parameters (count = 20): search	1
qlty	Structure	Function with high complexity (count = 10): validate_and_build_semantic_options	1

[qltysh]

Found 2 issues:

1. Function with many parameters (count = 20): search [qlty:function-parameters]


2. Avoid parameter lists longer than 5 parameters. [20/5] [rubocop:Metrics/ParameterLists]

[Copilot]

Pull request overview

This PR updates TIMDEX’s public GraphQL schema to explicitly expose semantic-search tuning parameters (per ADR 8), removing the prior approach of hiding “internal” arguments from introspection so downstream clients can rely on introspection-derived schema artifacts.

Changes:

• Replaces the previously hidden semantic tuning arguments with a new tuningParametersInput input object argument on search.
• Adds runtime validation for tuning parameter ranges and returns GraphQL execution errors for invalid values.
• Updates/extends controller tests to assert introspection visibility and validate accept/reject behaviors.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
test/controllers/graphql_controller_test.rb	Updates introspection expectations and adds tests for valid/invalid tuning parameter inputs.
app/graphql/types/tuning_parameters_input_type.rb	Introduces a new GraphQL input object to expose tuning parameters in the public schema.
app/graphql/types/query_type.rb	Adds tuningParametersInput to search and validates/constructs semantic_options from it.
app/graphql/timdex_schema.rb	Removes schema visibility customization now that internal-only arguments are no longer used/hidden.

Suppressed comments (2)

app/graphql/types/query_type.rb:225

• This validation error message doesn’t indicate that the field is nested under tuningParametersInput, which can be confusing for clients. Consider prefixing the field name with the input object path.

        unless threshold.between?(0.0, 1.0)
          raise GraphQL::ExecutionError, "dropBoostThreshold must be between 0.0 and 1.0, got #{threshold}"
        end

app/graphql/types/query_type.rb:235

• This validation error message doesn’t indicate that the field is nested under tuningParametersInput, which can be confusing for clients. Consider prefixing the field name with the input object path.

        unless tokens.positive?
          raise GraphQL::ExecutionError,
                "shortQueryMaxTokens must be greater than 0, got #{tokens}"
        end

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[qltysh]

Found 3 issues:

1. Function with high complexity (count = 10): validate_and_build_semantic_options [qlty:function-complexity]


2. Assignment Branch Condition size for validate_and_build_semantic_options is too high. [<7, 19, 7> 21.42/17] [rubocop:Metrics/AbcSize]


3. Cyclomatic complexity for validate_and_build_semantic_options is too high. [8/7] [rubocop:Metrics/CyclomaticComplexity]