Enhance autocomplete and similarity search functionality

- Updated README.md to clarify default algorithm options for similarity search.
- Modified autocomplete response structure in `search.test.ts` and `search-concepts.ts` to reflect changes in suggestion format.
- Improved `AutocompleteOptions` interface to include `domainIds` and updated documentation for deprecated fields.
- Enhanced `SimilarSearchOptions` and `SimilarConcept` interfaces to provide more detailed response handling and options.
- Added tests to ensure correct handling of new options and response structures in autocomplete and similarity search functionalities.

Author: alex-omophub

README.md

@@ -231,6 +231,7 @@ Find concepts similar to a known concept or natural language query:
 
 ```ts
 // Find concepts similar to a known concept
+// `algorithm` defaults to 'semantic'; 'lexical' and 'hybrid' are also available.
 const sim = await client.search.similar({ conceptId: 201826, algorithm: 'hybrid' });
 for (const r of sim.data?.similar_concepts ?? []) {
   console.log(`${r.concept_name} (score: ${r.similarity_score.toFixed(2)})`);

e2e/search.test.ts

@@ -122,8 +122,8 @@ describe('e2e: client.search.autocomplete', () => {
     expect(Array.isArray(data?.suggestions)).toBe(true);
     expect(data?.suggestions.length).toBeGreaterThan(0);
     const first = data?.suggestions[0];
-    expect(typeof first?.suggestion.concept_id).toBe('number');
-    expect(typeof first?.suggestion.concept_name).toBe('string');
+    expect(typeof first?.concept_id).toBe('number');
+    expect(typeof first?.suggestion).toBe('string');
   });
 
   runOrSkip('echoes the query field with vocabulary filter applied', async () => {

examples/__docsnippet_check.ts

@@ -0,0 +1,13 @@
+import { OMOPHub } from '../src/index.js';
+
+const client = new OMOPHub('oh_test');
+
+export async function fromOldDocs(): Promise<void> {
+  const { data } = await client.search.autocomplete('diab', { pageSize: 10 });
+  console.log(data?.query);
+
+  for (const entry of data?.suggestions ?? []) {
+    console.log(entry.suggestion.concept_name);
+    console.log(entry.match_score);
+  }
+}

examples/search-concepts.ts

@@ -100,12 +100,12 @@ async function bulkSemanticSearch(client: OMOPHub): Promise<void> {
 
 async function autocompleteExample(client: OMOPHub): Promise<void> {
   console.log('\n=== Autocomplete ===');
-  // Returns `{ query, suggestions: [{ suggestion: Concept, match_score?, match_type? }] }`.
+  // Returns `{ query, suggestions: [{ suggestion: string, concept_id, ... }] }`.
   const { data, error } = await client.search.autocomplete('hypert', { pageSize: 5 });
   if (error) throw new Error(error.message);
   console.log(`Suggestions for '${data.query}':`);
   for (const s of data.suggestions.slice(0, 5)) {
-    console.log(`  [${s.suggestion.vocabulary_id}] ${s.suggestion.concept_name}`);
+    console.log(`  [${s.vocabulary_id}] ${s.suggestion}`);
   }
 }
 

src/index.ts

@@ -135,6 +135,7 @@ export type {
   SimilarSearchMetadata,
   SimilarSearchOptions,
   SimilarSearchResult,
+  SimilarSourceConcept,
 } from './search/interfaces/index.js';
 export { __version__ } from './version.js';
 export type {

src/search/interfaces/autocomplete-options.ts

@@ -1,6 +1,9 @@
 export interface AutocompleteOptions {
   vocabularyIds?: string[];
+  domainIds?: string[];
+  /** @deprecated Use `domainIds`. */
   domains?: string[];
-  /** Maximum number of suggestions. Default 10 at the API; max 100. */
+  /** Maximum number of suggestions. Default 10 at the API; max 20. */
   pageSize?: number;
+  includeContext?: boolean;
 }

src/search/interfaces/index.ts

@@ -32,4 +32,5 @@ export type {
   SimilarConcept,
   SimilarSearchMetadata,
   SimilarSearchResult,
+  SimilarSourceConcept,
 } from './similar-search-result.js';

src/search/interfaces/search-result.ts

@@ -34,14 +34,20 @@ export interface SearchResult {
   search_metadata?: SearchMetadata;
 }
 
-/**
- * One entry in `AutocompleteResult.suggestions`. The server nests the
- * concept under a `suggestion` field and may add scoring fields alongside.
- */
+/** One concept-name suggestion returned by `GET /search/suggest`. */
 export interface AutocompleteEntry {
-  suggestion: Concept;
-  match_score?: number;
-  match_type?: string;
+  suggestion: string;
+  concept_id: Concept['concept_id'];
+  concept_code: Concept['concept_code'];
+  vocabulary_id: Concept['vocabulary_id'];
+  domain_id: Concept['domain_id'];
+  concept_class_id: Concept['concept_class_id'];
+  standard_concept: Concept['standard_concept'];
+  context?: {
+    vocabulary_id: string;
+    domain_id: string;
+    concept_class_id: string;
+  };
 }
 
 /**

src/search/interfaces/similar-search-options.ts

@@ -1,15 +1,39 @@
 interface SimilarSearchBase {
-  /** `'semantic'`, `'lexical'`, or `'hybrid'` (default). */
+  /** `'semantic'` (the API's default), `'lexical'`, or `'hybrid'`. */
   algorithm?: 'semantic' | 'lexical' | 'hybrid';
-  /** Similarity floor (0–1). Default 0.7 at the API. */
+  /**
+   * Similarity floor (0–1). Default 0.7 at the API. `0` is a valid value and
+   * is honoured — it returns every candidate the retrieval produced.
+   */
   similarityThreshold?: number;
+  /**
+   * Page of the ranked candidate pool, 1-based.
+   *
+   * Every algorithm ranks a bounded pool, so reachable depth is bounded too;
+   * page while `meta.pagination.has_next` is true rather than comparing `page`
+   * to `total_pages`, and check `search_metadata.totals_are_lower_bound`
+   * before treating a total as exact.
+   */
+  page?: number;
   pageSize?: number;
   vocabularyIds?: string[];
   domainIds?: string[];
+  conceptClassIds?: string[];
+  /** `'N'` selects non-standard concepts, which OMOP stores as a null column. */
   standardConcept?: 'S' | 'C' | 'N';
+  /**
+   * Include invalid/deprecated concepts. Defaults to `false`, and is supported
+   * only with `algorithm: 'lexical'` — the embedding index holds valid
+   * concepts only, so the API answers 400 for the other two rather than
+   * ignoring the filter.
+   */
   includeInvalid?: boolean;
+  /** Include `similarity_score` on each concept. Default true. */
   includeScores?: boolean;
+  /** Include an `explanation` on each concept. Default false. */
   includeExplanations?: boolean;
+  /** Exclude the reference concept from its own results. Default true. */
+  excludeSelf?: boolean;
 }
 
 /**

src/search/interfaces/similar-search-result.ts

@@ -1,7 +1,11 @@
 import type { ConceptSummary } from '../../concepts/interfaces/concept.js';
 
 export interface SimilarConcept extends ConceptSummary {
-  similarity_score: number;
+  /**
+   * Absent when the request set `includeScores: false`, which the API honours
+   * by omitting the key rather than zeroing it.
+   */
+  similarity_score?: number;
   domain_id?: string;
   concept_class_id?: string;
   standard_concept?: 'S' | 'C' | 'N' | null;
@@ -10,20 +14,59 @@ export interface SimilarConcept extends ConceptSummary {
     lexical?: number;
     hybrid?: number;
   };
+  /** Present when the request set `includeExplanations: true`. */
   explanation?: string;
+  /**
+   * @deprecated Duplicate of `explanation`, emitted by the API for one release
+   * so clients that read the old name keep working. Read `explanation`.
+   */
+  similarity_explanation?: string;
 }
 
 export interface SimilarSearchMetadata {
   original_query: string;
   algorithm_used: 'semantic' | 'lexical' | 'hybrid';
   similarity_threshold: number;
+  /**
+   * How many concepts cleared `similarity_threshold` inside the bounded
+   * retrieval pool — not how many were evaluated. The pool holds up to 500 and
+   * everything below the threshold is discarded before this is counted.
+   */
   total_candidates: number;
   results_returned: number;
   processing_time_ms: number;
   embedding_latency_ms?: number;
+  /**
+   * True when retrieval hit its candidate bound, so `total_candidates` and the
+   * pagination totals count only what qualified inside the pool that was
+   * searched, rather than across the whole corpus. Treat them as "at least this
+   * many".
+   */
+  totals_are_lower_bound?: boolean;
+  /**
+   * The algorithm that was asked for, when a fallback served the request
+   * instead — `hybrid` degrades to `lexical` if the embedding service is
+   * unavailable. Present only when it differs from `algorithm_used`.
+   */
+  degraded_from?: 'semantic' | 'lexical' | 'hybrid';
+  /** The concept the search started from, when `conceptId` was supplied. */
+  source_concept_id?: number;
+}
+
+/** The reference concept a similarity search started from. */
+export interface SimilarSourceConcept {
+  concept_id: number;
+  concept_name: string;
+  concept_code?: string;
+  vocabulary_id?: string;
+  domain_id?: string;
+  concept_class_id?: string;
+  standard_concept?: 'S' | 'C' | 'N' | null;
 }
 
 export interface SimilarSearchResult {
   similar_concepts: SimilarConcept[];
   search_metadata: SimilarSearchMetadata;
+  /** Returned when the search started from a `conceptId`. */
+  source_concept?: SimilarSourceConcept;
 }