Query Sense

A powerful semantic search module that finds semantically similar documents using AI.

Installation

npm install query-sense

Usage

Quick Start

import { semanticSearch } from 'query-sense';

const results = await semanticSearch("kitten", [
  "Cats are quiet animals",
  "Dogs are loyal pets",
  "Python is used for backend development",
  "JavaScript runs in the browser",
  "Machine learning finds patterns in data"
]);

console.log(results);
// {
//   results: [
//     { document: "Cats are quiet animals", score: 0.68 },
//     { document: "Dogs are loyal pets", score: 0.50 },
//     ...
//   ],
//   query: "kitten"
// }

Using the QuerySense Class

import QuerySense from 'query-sense';

const qs = new QuerySense();

const results = await qs.search({
  query: "kitten",
  documents: [
    "Cats are quiet animals",
    "Dogs are loyal pets",
    "Python is used for backend development"
  ],
  topK: 3,        // Optional: limit results
  threshold: 0.5  // Optional: minimum similarity score
});

Configuration Options

const qs = new QuerySense({
  apiUrl: "https://your-custom-api.com/search", // Optional: custom API endpoint
  timeout: 10000 // Optional: request timeout in ms (default: 30000)
});

API Reference

semanticSearch(query, documents, options?)

Convenience function for quick semantic search.

Parameters:

• query (string): The search query
• documents (string[]): Array of documents to search through
• options (object, optional):
  • topK (number): Maximum number of results to return
  • threshold (number): Minimum similarity score (0-1)
  • apiUrl (string): Custom API URL
  • timeout (number): Request timeout in ms

Returns: Promise<SemanticSearchResponse>

QuerySense Class

constructor(config?)

Creates a new QuerySense client.

Config Options:

• apiUrl (string): Custom API URL
• timeout (number): Request timeout in ms

search(options)

Performs a semantic search.

Options:

• query (string, required): The search query
• documents (string[], required): Documents to search
• topK (number, optional): Limit results count
• threshold (number, optional): Minimum score threshold

Types

interface SearchResult {
  document: string;
  score: number;
}

interface SemanticSearchResponse {
  results: SearchResult[];
  query: string;
}

Error Handling

import { semanticSearch, QuerySenseError } from 'query-sense';

try {
  const results = await semanticSearch("query", documents);
} catch (error) {
  if (error instanceof QuerySenseError) {
    console.error("Search failed:", error.message);
    console.error("Status code:", error.statusCode);
  }
}

License

MIT