Enhance vector search API reference documentation #226
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
- Add detailed parameter descriptions for VectorSearchParams - Include multiple practical examples showing different use cases - Document parameter constraints and valid ranges - Update return value description to match current interface Co-Authored-By: jhaynie@agentuity.com <jhaynie@gmail.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 5879967 | Commit Preview URL | Jul 08 2025, 05:16 AM |
WalkthroughThe documentation for the Changes
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
content/SDKs/javascript/api-reference.mdx (2)
229-230: Return-value description incompleteThe bullet list omits the
similarityproperty that’s referenced later in examples. Suggest:-Returns a Promise that resolves to an array of search results, each containing an ID, key, metadata, and similarity score. +Returns a Promise that resolves to an array of search results. +Each result object has: +`id` (string) • `key` (string) • `metadata` (object | null) • `similarity` (number 0-1).
234-252: Code-snippet polish: avoidconstshadowing & show metadata-only hackUsing
const resultsthree times in the same block shadows the identifier; some bundlers flag this. Also, including an example of a metadata-only search (single-space query) would help users.-// Basic search with query only -const results = await context.vector.search('product-descriptions', { +// Basic search with query only +let results = await context.vector.search('product-descriptions', { query: 'comfortable office chair' }); -// Search with limit and similarity threshold -const results = await context.vector.search('product-descriptions', { +// Search with limit and similarity threshold +results = await context.vector.search('product-descriptions', { query: 'comfortable office chair', limit: 5, similarity: 0.7 }); -// Search with metadata filtering -const results = await context.vector.search('product-descriptions', { +// Metadata-only search (use single space as query) +results = await context.vector.search('product-descriptions', { + query: ' ', + metadata: { category: 'furniture', inStock: true } +}); + +// Combined search with metadata filtering +results = await context.vector.search('product-descriptions', { query: 'comfortable office chair', limit: 10, similarity: 0.6, metadata: { category: 'furniture', inStock: true } });
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
content/SDKs/javascript/api-reference.mdx(1 hunks)
🧰 Additional context used
🧠 Learnings (2)
📓 Common learnings
Learnt from: afterrburn
PR: agentuity/docs#208
File: agent-docs/src/agents/doc-qa/retriever.ts:46-51
Timestamp: 2025-06-28T15:55:43.334Z
Learning: In Agentuity vector search API, the query parameter cannot be an empty string as it would throw an error. When performing metadata-only searches (like retrieving all chunks for a specific document path), a single space ' ' can be used as a workaround since the API requires a non-empty query string.
content/SDKs/javascript/api-reference.mdx (1)
Learnt from: afterrburn
PR: agentuity/docs#208
File: agent-docs/src/agents/doc-qa/retriever.ts:46-51
Timestamp: 2025-06-28T15:55:43.334Z
Learning: In Agentuity vector search API, the query parameter cannot be an empty string as it would throw an error. When performing metadata-only searches (like retrieving all chunks for a specific document path), a single space ' ' can be used as a workaround since the API requires a non-empty query string.
🪛 LanguageTool
content/SDKs/javascript/api-reference.mdx
[grammar] ~222-~222: “Text” is a singular noun. It appears that the verb form is incorrect.
Context: ... - query (string, required): The text query to search for. This will be converted t...
(PCT_SINGULAR_NOUN_PLURAL_VERB_AGREEMENT)
[uncategorized] ~225-~225: You might be missing the article “the” here.
Context: ...ied key-value pairs will be included in results. Must be a valid JSON object. ##### Re...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Workers Builds: docs
Comment on lines
+221
to
226
| - `params`: Search parameters object with the following properties: | ||
| - `query` (string, required): The text query to search for. This will be converted to embeddings and used to find semantically similar documents. | ||
| - `limit` (number, optional): Maximum number of search results to return. Must be a positive integer. If not specified, the server default will be used. | ||
| - `similarity` (number, optional): Minimum similarity threshold for results (0.0-1.0). Only vectors with similarity scores greater than or equal to this value will be returned. 1.0 means exact match, 0.0 means no similarity requirement. | ||
| - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. Must be a valid JSON object. | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Mention non-empty query requirement & tighten grammar
- The backend rejects an empty string for
query(see learning from Agentuity PR QA Agent Interface #208). Add an explicit note or throw ifquery.trim().length === 0. - Minor grammar tweaks:
• "query… This will be converted to embeddings"
• "metadata… will be included in the results."
- - `query` (string, required): The text query to search for. This will be converted to embeddings and used to find semantically similar documents.
+ - `query` (string, required): The text query to search for (must be **non-empty**; use a single space `" "` for metadata-only searches). This query is converted to embeddings and used to find semantically similar documents.
...
- - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. Must be a valid JSON object.
+ - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in **the** results. Must be a valid JSON object.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - `params`: Search parameters object with the following properties: | |
| - `query` (string, required): The text query to search for. This will be converted to embeddings and used to find semantically similar documents. | |
| - `limit` (number, optional): Maximum number of search results to return. Must be a positive integer. If not specified, the server default will be used. | |
| - `similarity` (number, optional): Minimum similarity threshold for results (0.0-1.0). Only vectors with similarity scores greater than or equal to this value will be returned. 1.0 means exact match, 0.0 means no similarity requirement. | |
| - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. Must be a valid JSON object. | |
| - `params`: Search parameters object with the following properties: | |
| - `query` (string, required): The text query to search for (must be **non-empty**; use a single space `" "` for metadata-only searches). This query is converted to embeddings and used to find semantically similar documents. | |
| - `limit` (number, optional): Maximum number of search results to return. Must be a positive integer. If not specified, the server default will be used. | |
| - `similarity` (number, optional): Minimum similarity threshold for results (0.0-1.0). Only vectors with similarity scores greater than or equal to this value will be returned. 1.0 means exact match, 0.0 means no similarity requirement. | |
| - `metadata` (object, optional): Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in **the** results. Must be a valid JSON object. |
🧰 Tools
🪛 LanguageTool
[grammar] ~222-~222: “Text” is a singular noun. It appears that the verb form is incorrect.
Context: ... - query (string, required): The text query to search for. This will be converted t...
(PCT_SINGULAR_NOUN_PLURAL_VERB_AGREEMENT)
[uncategorized] ~225-~225: You might be missing the article “the” here.
Context: ...ied key-value pairs will be included in results. Must be a valid JSON object. ##### Re...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
🤖 Prompt for AI Agents
In content/SDKs/javascript/api-reference.mdx around lines 221 to 226, update the
description of the `query` parameter to explicitly state that it must be a
non-empty string and that empty or whitespace-only strings are rejected by the
backend. Also, adjust the grammar by changing "This will be converted" to "This
text will be converted" for `query`, and add "the" before "results" in the
`metadata` description to improve clarity.
jhaynie
approved these changes
Jul 8, 2025
5 tasks
This was referenced Aug 19, 2025
Merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR description is being written. Please check back in a minute.
Devin Session: https://app.devin.ai/sessions/ccf549fb2a724912bd58325cdfde68b7
Summary by CodeRabbit
context.vector.searchmethod, including detailed parameter descriptions and updated return value information.