LearnNewsExamplesServices
Frontmatter
titleExtract score weights as constants
authorMahita07
stateMerged
createdAtOct 17, 2025, 6:13 PM
updatedAtOct 27, 2025, 12:05 PM
closedAtOct 27, 2025, 12:05 PM
mergedAtOct 27, 2025, 12:05 PM
branchesdev ← knowledge-query-endpoint
urlhttps://github.com/neomjs/neo/pull/7533
Merged
Mahita07
Mahita07 commented on Oct 17, 2025, 6:13 PM

Please make sure to read the Contributing Guidelines:

https://github.com/neomjs/neo/blob/dev/CONTRIBUTING.md

What kind of change does this PR introduce? (check at least one)

  • Bugfix
  • Feature
  • Code style update
  • Refactor
  • Build-related changes
  • Other, please describe:

Does this PR introduce a breaking change? (check one)

  • Yes
  • No

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

  • It's submitted to the dev branch, not the main branch
  • When resolving a specific issue, it's referenced in the PR's title (e.g. fix #xxx[,#xxx], where "xxx" is the issue number)

If adding a new feature, the PR's description includes:

  • A convincing reason for adding this feature (to avoid wasting your time, it's best to open a suggestion issue first and wait for approval before working on it)

Other information:

Description of the scoring logic used for knowledge query endpoint:

  1. Base Score: The initial ranking from the vector search (ChromaDB) is used as a starting point.
  2. Keyword Matching: It heavily boosts files where keywords from the query appear in important places like the file path, file name, or class name. This adds a layer of traditional keyword search on top of the semantic vector search.
  3. Content Type Boosts: guide files get a significant boost, indicating a preference for explanatory documentation over raw source code. blog posts get a smaller boost.
  4. Penalties: ticket and release files are penalized (in "all" searches) to prevent them from cluttering the results when you're likely looking for implementation details or guides.
  5. Convention Boosts: It boosts Base.mjs files, as these are often foundational classes in the framework.
  6. Inheritance Boost: It cleverly boosts the scores of parent classes in the inheritance chain of a result, acknowledging that context is often inherited.
  7. Proximity Boost: It gives a final small boost to files that are in the same directory as other top-ranked files, assuming that related files are often located together.

In short, the algorithm is a multi-faceted approach that combines semantic search with a series of project-specific rules to fine-tune the relevance of the results.

Mahita07
Mahita07 commented on Oct 17, 2025, 6:13 PM

@tobiu Could you please review this PR ?

tobiu
tobiu commented on Oct 24, 2025, 11:09 AM

Input from Gemini:

Hi @Mahita07, thank you for your work on this. The scoring algorithm logic and the introduction of the SCORE_WEIGHTS constant to remove magic numbers are excellent improvements.

However, this PR is based on an architecture we have recently deprecated. We have moved from standalone Express servers to a formal MCP server architecture using STDIO as the transport layer. The correct, active implementation for this service is in ai/mcp/server/knowledge-base/services/QueryService.mjs.

We would love to get this merged, but it needs to be refactored to fit the new architecture. Here is the plan:

  1. Remove New/Modified Files: Please remove the new server files (ai/mcp/server/knowledge/index.mjs and ai/mcp/server/knowledge/query.mjs) and revert the change to package.json (the ai:server-knowledge-mcp script is for the deprecated server).
  2. Move the SCORE_WEIGHTS: Please add your SCORE_WEIGHTS constant to the existing configuration file at ai/mcp/server/knowledge-base/config.mjs.
  3. Refactor QueryService.mjs: Please modify the existing ai/mcp/server/knowledge-base/services/QueryService.mjs to import the SCORE_WEIGHTS from the config file and use them in the scoring algorithm instead of the current hardcoded numbers.

This will integrate your valuable scoring improvements into our new, correct server architecture. I know this is a significant change from your original PR, and I apologize for the architectural shift not being clearer. Please let me know if you have any questions about this refactoring.

Thanks again for your great work on the scoring logic!

Mahita07
Mahita07 commented on Oct 25, 2025, 7:33 PM

@tobiu could you please review this PR ? Have modified it to extract score weights as constants and use them in query service.

tobiu
tobiu commented on Oct 27, 2025, 11:59 AM

Input from Gemini:

✦ Hi @Mahita07, thank you so much for your diligence in refactoring this PR! You've correctly moved the logic into the new architecture, and extracting the magic numbers into constants is a fantastic improvement for maintainability. We really appreciate the effort you've put into this.

We are approving and merging this PR.

As a small point of feedback for the future (and this is a nuance you wouldn't have known), our config files follow a convention of having a single default export with all properties inside it using camelCase. We're going to handle this minor cleanup in a follow-up ticket (#7673) ourselves, so no action is needed from you.

Excellent contribution to Hacktoberfest, and we hope to see more from you!