knowledge-ask/components/types.ts

A frontend nuxt library to call the knowledge-hub API.

import { Ref, UnwrapRef } from "vue";
import {
    AsyncDataExecuteOptions,
    AsyncDataRequestStatus,
} from "nuxt3/dist/app/composables/asyncData";

/**
 * An embedding of 384 parameters where each parameter is between 0 and 1.
 */
export type Embedding = number[];

/**
 * Represents an item in a bilingual glossary.
 *
 * @property {string} name_fr - The name of the item in French.
 * @property {string} name_en - The name of the item in English.
 * @property {string} definition_fr - The definition of the item in French.
 * @property {string} definition_en - The definition of the item in English.
 * @property {string} source - The source or reference for the glossary item.
 */
export type GlossaryItem = {
    name_fr: string;
    name_en: string;
    definition_fr: string;
    definition_en: string;
    source: string;
};

/**
 * Represents a document with vector embeddings.
 *
 * @property {string} id - A unique uuid identifier for the document.
 * @property {string} content - The textual content of the document.
 * @property {GlossaryItem} embedding_metadata - Additional metadata or information representing an item in the bilingual glossary.
 * @property {Embedding} embedding - The vector embedding associated with the document content.
 */
export type VectorDocument = {
    id: string;
    content: string;
    embedding_metadata: GlossaryItem;
    embedding: Embedding;
};

/**
 * Represents the request data for a similarity search operation.
 *
 * @property {number} defaultMaxItems - The default maximum number of items to be retrieved in the response.
 * @property {string} query - The query string for the similarity search.
 * @property {string} knowledgeHubURL - The base URL (e.g. https://www.knowledgehub.confiance.ai) of the knowledge hub api where the search operation is performed.
 */
export type SimilaritySearchRequest = {
    maxItems: number;
    query: string;
    knowledgeHubURL: string;
};

/**
 * Represents the response data for a similarity search operation.
 *
 * @property {Ref<UnwrapRef<number>>} maxItems - The maximum number of items requested in the search results, wrapped as a ref.
 * @property {Ref<Array<VectorDocument>>} data - The search results data, which is an array of `VectorDocument`, wrapped as a ref.
 * @property {string} query - The query string that was used for the similarity search in the vector database.
 * @property {Ref<boolean>} pending - A ref indicating if the search operation is currently in progress.
 * @property {(opts?: AsyncDataExecuteOptions) => Promise<void>} refresh - A method to refresh the search results. Takes an optional parameter of type `AsyncDataExecuteOptions`. Read the documentation of Nuxt useFetch to no more about it.
 * @property {Ref<any | null>} error - A ref containing any errors that occurred during the search operation, or null if no errors.
 * @property {Ref<AsyncDataRequestStatus>} status - A ref indicating the current status of the search request.
 */
export type SimilaritySearchResponse = {
    maxItems: Ref<UnwrapRef<number>>;
    data: Ref<Array<VectorDocument> | null>;
    query: string;
    pending: Ref<boolean>;
    refresh: (opts?: AsyncDataExecuteOptions) => Promise<void>;
    error: Ref<any | null>;
    status: Ref<AsyncDataRequestStatus>;
};