Adds semantic query tuning parameters by JPrevost · Pull Request #971 · MITLibraries/timdex

JPrevost · 2026-06-25T19:18:07Z

Why are these changes being introduced:

We want to be able to tune the semantic query parameters for better results.

Relevant ticket(s):

https://mitlibraries.atlassian.net/browse/USE-619

How does this address that need:

Introduces new semantic query tuning parameters to the GraphQL API.
Ensures those parameters are not documented publicly by prefixing them with INTERNAL USE ONLY in the description and skipping them in introspection queries.

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

Why are these changes being introduced: * We want to be able to tune the semantic query parameters for better results. Relevant ticket(s): * https://mitlibraries.atlassian.net/browse/USE-619 How does this address that need: * Introduces new semantic query tuning parameters to the GraphQL API. * Ensures those parameters are not documented publicly by prefixing them with `INTERNAL USE ONLY` in the description and skipping them in introspection queries.

qltysh · 2026-06-25T19:19:58Z

❌ 9 blocking issues (14 total)

Tool	Category	Rule	Count
rubocop	Lint	Assignment Branch Condition size for `search` is too high. [<7, 16, 0> 17.46/17]	3	❌
rubocop	Lint	Avoid parameter lists longer than 5 parameters. [22/5]	2	❌
rubocop	Lint	Method has too many lines. [14/10]	2	❌
rubocop	Lint	Cyclomatic complexity for `visible?` is too high. [10/7]	1	❌
rubocop	Lint	Perceived complexity for `visible?` is too high. [10/8]	1	❌
qlty	Structure	Function with high complexity (count = 6): visible?	3
qlty	Structure	Function with many parameters (count = 22): search	2

qltysh · 2026-06-25T19:20:00Z

    def search(searchterm:, citation:, contributors:, funding_information:, geodistance:, geobox:, identifiers:,
               locations:, subjects:, title:, index:, source:, from:, boolean_type:, fulltext:, per_page: 20,
-               query_mode: 'keyword', use_global_scoring: false, **filters)
+               query_mode: 'keyword', use_global_scoring: false, semantic_must_boost_threshold: nil,


Found 2 issues:

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

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

qltysh · 2026-06-25T19:20:00Z

@@ -4,12 +4,13 @@ class Opensearch
  MAX_SIZE = 200

  def search(from, params, client, highlight: false, index: nil, fulltext: false, query_mode: 'keyword',


Found 2 issues:

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

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

Copilot

Pull request overview

This PR adds internal semantic query tuning knobs to the GraphQL search API and threads them through to the semantic-query Lambda payload, while attempting to hide these knobs from public schema introspection.

Changes:

Add semantic_* tuning arguments to GraphQL search and pass them through to OpenSearch query building.
Extend Opensearch, HybridQueryBuilder, and SemanticQueryBuilder to accept and forward semantic_options.
Add schema-level visibility logic intended to hide “INTERNAL USE ONLY” arguments from introspection.

Reviewed changes

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

Show a summary per file

File	Description
app/models/semantic_query_builder.rb	Accepts semantic tuning options and conditionally adds them to the Lambda invocation payload.
app/models/opensearch.rb	Stores semantic options and passes them only for semantic/hybrid query modes.
app/models/hybrid_query_builder.rb	Forwards semantic options into `SemanticQueryBuilder`.
app/graphql/types/query_type.rb	Adds internal GraphQL arguments and constructs the `semantic_options` hash passed to `Opensearch`.
app/graphql/timdex_schema.rb	Adds visibility hook intended to hide INTERNAL USE ONLY members during introspection.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

qltysh · 2026-07-01T13:43:40Z

+      return false if is_introspection
+    end
+
+    super


Found 3 issues:

1. Function with high complexity (count = 6): visible? [qlty:function-complexity]

2. Cyclomatic complexity for visible? is too high. [10/7] [rubocop:Metrics/CyclomaticComplexity]

3. Perceived complexity for visible? is too high. [10/8] [rubocop:Metrics/PerceivedComplexity]

qltysh · 2026-07-01T13:43:40Z

+      builder.build(@params, fulltext: @fulltext, semantic_options: @semantic_options || {})
+    else
+      builder.build(@params, fulltext: @fulltext)
+    end


Function with high complexity (count = 5): query [qlty:function-complexity]

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

JPrevost requested a review from Copilot June 25, 2026 19:18

Copilot started reviewing on behalf of JPrevost June 25, 2026 19:19 View session

qltysh Bot reviewed Jun 25, 2026

View reviewed changes

mitlib temporarily deployed to timdex-api-p-use-619-dises3whb June 25, 2026 19:20 Inactive

Copilot AI reviewed Jun 25, 2026

View reviewed changes

Comment thread app/models/semantic_query_builder.rb Outdated

Comment thread app/models/opensearch.rb Outdated

Comment thread app/graphql/timdex_schema.rb Outdated

Comment thread app/graphql/types/query_type.rb Outdated

Comment thread app/models/semantic_query_builder.rb

Address automated code review suggestions

cd4b0b5

JPrevost requested a review from Copilot July 1, 2026 13:43

Copilot started reviewing on behalf of JPrevost July 1, 2026 13:43 View session

qltysh Bot reviewed Jul 1, 2026

View reviewed changes

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread app/graphql/timdex_schema.rb

Comment thread app/graphql/types/query_type.rb

Comment thread app/graphql/timdex_schema.rb

Add tests to confirm fields are hidden

d208728

JPrevost requested review from jazairi and matt-bernhardt July 1, 2026 19:09

		@@ -4,12 +4,13 @@ class Opensearch
		MAX_SIZE = 200

		def search(from, params, client, highlight: false, index: nil, fulltext: false, query_mode: 'keyword',

Uh oh!

Conversation

JPrevost commented Jun 25, 2026

Developer

Code Reviewer

Requires database migrations?

Includes new or updated dependencies?

Uh oh!

qltysh Bot commented Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ 9 blocking issues (14 total)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qltysh Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

qltysh Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qltysh Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

qltysh Bot Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

qltysh Bot commented Jun 25, 2026 •

edited

Loading