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]

I choose to quietly ignore this until it's at least 5x the recommended maximum.

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.

jazairi

A few non-blocking comments and questions, mostly to improve my own understanding. The code is

jazairi · 2026-07-06T16:27:57Z

+                                                                   'threshold (0.0-1.0)'
+      argument :semantic_short_query_max_tokens, Integer, required: false, default_value: nil,
+                                                          description: 'INTERNAL USE ONLY: Semantic query short ' \
+                                                                       'query max tokens'


Is there a range we should specify for max tokens?

We don't really know yet, but will hopefully learn over time based on measurements with the NDCG work.

This value works together with semantic_drop_boost_threshold.

Short queries (this value) don't drop any noise. Long queries drop noise based on the value of semantic_drop_boost_threshold.

It all hurts my brain.

jazairi · 2026-07-06T16:51:23Z

                                           description: 'Filter by subject terms. Use the `contentType` aggregation ' \
                                                        'for a list of possible values. Multiple values are ANDed.'
+
+      # Internal semantic query tuning parameters (not documented publicly). Must start with `INTERNAL USE ONLY` to be


Beyond the scope of this PR: do we have docs on what these parameters are and how to tune them?

This is the closest to useful docs we have on this.

https://github.com/MITLibraries/timdex-semantic-builder/blob/main/lambdas/tokenizer_handler.py#L16-L28

jazairi · 2026-07-06T16:52:26Z

    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,


I choose to quietly ignore this until it's at least 5x the recommended maximum.

jazairi · 2026-07-06T16:54:07Z

+
+  test 'includes semantic options in lambda payload' do
+    query_text = 'test query'
+    mock_response = {


Non-blocking: it seems like we reuse this response a lot. It might make sense to refactor it to a helper method for readability.

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

jazairi self-assigned this Jul 6, 2026

jazairi approved these changes Jul 6, 2026

View reviewed changes

JPrevost merged commit f39dcd8 into main Jul 6, 2026
3 checks passed

JPrevost deleted the use-619 branch July 6, 2026 17:25

		@@ -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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

qltysh Bot Jun 25, 2026

Choose a reason for hiding this comment

Uh oh!

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!

jazairi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

qltysh Bot commented Jun 25, 2026 •

edited

Loading