[codex] Add local metadata for registered topics by lintool · Pull Request #3348 · castorini/anserini

lintool · 2026-07-14T14:40:39Z

Summary

Add local topic metadata and aliases for registered topics.
Refactor Topics into a metadata-backed registry loaded from JSON resources.
Replace Topics.resolve(...) with explicit Topics.load(...) and TopicReader.load(...) entry points.
Keep local-file topic loading explicit: local readable paths use TopicReader.load(file, topicReader), while registry keys use Topics.load(key).
Update callers and tests to use canonical topic keys and remove legacy enum-style topic symbols and wrappers.
Remove unused topic-loading helpers.

Validation

mvn -Dtest=TopicsTest,TopicReaderTest,TopicsRegistryTest test
mvn -Dtest=SearchCollectionTest test
git diff --check

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 968dceaadf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

codecov · 2026-07-14T14:52:13Z

Codecov Report

❌ Patch coverage is 74.38017% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.25%. Comparing base (a071946) to head (7f7c66e).
⚠️ Report is 10 commits behind head on master.

Files with missing lines	Patch %	Lines
...in/java/io/anserini/search/topicreader/Topics.java	70.00%	16 Missing and 8 partials ⚠️
...main/java/io/anserini/search/SearchCollection.java	62.50%	2 Missing and 1 partial ⚠️
...ini/cli/ExtractQueriesAndDocumentsFromTrecRun.java	80.00%	0 Missing and 1 partial ⚠️
src/main/java/io/anserini/cli/TopicsRegistry.java	75.00%	0 Missing and 1 partial ⚠️
...ava/io/anserini/search/SearchFlatDenseVectors.java	75.00%	0 Missing and 1 partial ⚠️
...ava/io/anserini/search/SearchHnswDenseVectors.java	75.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #3348      +/-   ##
============================================
- Coverage     73.40%   72.25%   -1.15%     
- Complexity     1913     1918       +5     
============================================
  Files           206      206              
  Lines         13493    13013     -480     
  Branches       1867     1874       +7     
============================================
- Hits           9904     9403     -501     
- Misses         2843     2854      +11     
- Partials        746      756      +10

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

lintool · 2026-07-14T15:07:23Z

Initial refactor pass by Codex. Will now de-slopify.

lintool · 2026-07-15T08:23:12Z

@codex review

lintool · 2026-07-18T18:02:30Z

Wrapping up reproductions, working fine - ready for review.

# Invocation to run on batch01 on 102, batch02 on 104, and batch03 on tuna:
nohup bin/run.sh io.anserini.reproduce.RunJavaReproductionCommands --config from-document-collection.batch01 --load 32 --max 3 --sleep 60 >& from-document-collection.batch01.log &
nohup bin/run.sh io.anserini.reproduce.RunJavaReproductionCommands --config from-document-collection.batch02 --load 32 --max 3 --sleep 60 >& from-document-collection.batch02.log &
nohup bin/run.sh io.anserini.reproduce.RunJavaReproductionCommands --config from-document-collection.batch03 --load 44 --max 5 --sleep 60 >& from-document-collection.batch03.log &

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7f7c66e186

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

lilyjge

would it make more sense for src/main/resources/topics-and-qrels/_local_metadata_topics.json and src/main/resources/topics-and-qrels/_local_metadata_topics_aliases.json to go in the tools repo? instead of an explicit topic reader class it could be a more vague enum topic type that get's mapped to the appropriate reader class in anserini/pyserini. the path and aliases could definitely be reused across pyserini/anserini as well

lintool · 2026-07-19T00:52:23Z

hi @lilyjge thanks for your review - responses:

would it make more sense for src/main/resources/topics-and-qrels/_local_metadata_topics.json and src/main/resources/topics-and-qrels/_local_metadata_topics_aliases.json to go in the tools repo?

Yupp, the plan is for the metadata files to go in https://github.com/castorini/anserini-tools/tree/master/topics-and-qrels eventually.

I'm currently using src/main/resources/topics-and-qrels/ as a staging area to make sure everything is okay before moving over.

This is to avoid churn, having to repeated touch files in another repo.

instead of an explicit topic reader class it could be a more vague enum topic type that get's mapped to the appropriate reader class in anserini/pyserini. the path and aliases could definitely be reused across pyserini/anserini as well

My current plan is to decouple Anserini/Pyserini and have both read the metadata separately into their own internal classes. This decoupling allows Anserini/Pyserini to advance without inter-dependencies.

That is, if Pyserini depends on Anserini enums, then moving metadata to files doesn't shorten the dependency chain... you'd still have to modify Anserini, publish fatjar, and then modify Pyserini.

Under the current plan I'm in the process of implementing, we would just modify the json metadata, and Anserini/Pyserini can read the new info (prebuilt indexes, topics, and qrels) independently. The downside here is that there will be redundant code reading the metadata (in Java and Python), but I think this is a worthwhile tradeoff (to decouple Pyserini from Anserini and shorten the dependency chain).

Happy to discuss...

lilyjge · 2026-07-20T01:01:17Z

this resolves my primary concern: using src/main/resources/topics-and-qrels/ as a staging area to make sure everything is okay before moving over.

yes, I agree with this!
decouple Anserini/Pyserini and have both read the metadata separately into their own internal classes. This decoupling allows Anserini/Pyserini to advance without inter-dependencies.

what I meant about an enum type for the queries is that instead of specifying the anserini reader class, to abstract a level higher so it can be shared across anserini/pyserini, eg reader_class: tsv instead of "reader_class": "io.anserini.search.topicreader.TrecTopicReader" but we can iterate on that

design wise I think this is fine! I will take a pass through the code then

lintool · 2026-07-20T01:42:37Z

eg reader_class: tsv instead of "reader_class": "io.anserini.search.topicreader.TrecTopicReader" but we can iterate on that

Ah, I see.

However, currently, pyserini needs Anserini TopicReaders to read the topics: https://github.com/castorini/pyserini/blob/master/pyserini/search/_base.py#L122

So we need to rethink a bit more...

Yes, let's iterate on this further on another PR?

lilyjge · 2026-07-20T01:59:40Z

+    lookup.put(name, topic);
  }

-  public static <K> SortedMap<K, Map<String, String>> resolve(String[] topicsArray, String topicReader) {


why did we remove this helper method? it was called in multiple places that now have chunks of code

lilyjge · 2026-07-20T02:01:12Z

-        } else {
-          topics.putAll(TopicReader.getTopics(ref));
-        }
+      Path topicsPath = Paths.get(topicsFile);


for future note, the fact that this section has basically the same diff as src/main/java/io/anserini/search/SearchFlatDenseVectors.java makes me think there can be more abstraction to reduce duplication

lilyjge · 2026-07-20T02:12:29Z

@@ -813,47 +795,7 @@ public void testTREC20DL() throws IOException {
    assertEquals("why did the ancient egyptians call their land ke ##met , or black land ?", topics.get(topics.lastKey()).get("title"));
    assertEquals("who is aziz hash ##im", topics.get(1030303).get("title"));

-    topics = TopicReader.getTopics(Topics.TREC2020_DL_UNICOIL);


why did these tests get removed instead of replaced? similarly below

lintool added 2 commits July 14, 2026 10:40

Add local metadata for registered topics

968dcea

Add local topic metadata aliases

d637167

chatgpt-codex-connector Bot reviewed Jul 14, 2026

View reviewed changes

Comment thread src/main/resources/topics-and-qrels/_local_metadata_topics.json Outdated

Refactor topics registry to load from metadata

5ceda03

Refine topic registry loading API

9498aaf

lintool marked this pull request as draft July 14, 2026 19:41

Refine topic registry lookup and callers

7f7c66e

lintool marked this pull request as ready for review July 18, 2026 17:59

lintool requested review from lilyjge, lingwei-gu, nourj98 and sahel-sh July 18, 2026 18:00

chatgpt-codex-connector Bot reviewed Jul 18, 2026

View reviewed changes

Comment thread src/main/resources/topics-and-qrels/_local_metadata_topics.json

lilyjge reviewed Jul 18, 2026

View reviewed changes

lintool requested a review from lilyjge July 20, 2026 00:59

lilyjge reviewed Jul 20, 2026

View reviewed changes

Uh oh!

Conversation

lintool commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

codecov Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

lintool commented Jul 14, 2026

Uh oh!

lintool commented Jul 15, 2026

Uh oh!

lintool commented Jul 18, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

lilyjge left a comment

Choose a reason for hiding this comment

Uh oh!

lintool commented Jul 19, 2026

Uh oh!

lilyjge commented Jul 20, 2026

Uh oh!

lintool commented Jul 20, 2026

Uh oh!

lilyjge Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

lilyjge Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

lilyjge Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lintool commented Jul 14, 2026 •

edited

Loading

codecov Bot commented Jul 14, 2026 •

edited

Loading