knowledge.ts

Overview

This file defines TypeScript interfaces that specify the structure of request bodies and parameters for various API calls related to knowledge retrieval and management within an application. These interfaces serve as type contracts for requests involving:

Retrieval of test data based on question similarity and knowledge base filters.
Fetching lists of knowledge entries owned by specific users.
Querying lists of knowledge bases with optional filtering and pagination.
Retrieving lists of documents filtered by suffixes and run statuses.

The primary purpose of these interfaces is to ensure type safety and clarity in the data passed to backend services or APIs that handle knowledge-related operations.

Interfaces

1. ITestRetrievalRequestBody

Defines the shape of the request body when performing a test retrieval query based on a question and similarity metrics.

Property	Type	Optional	Description
`question`	`string`	No	The input question string to retrieve relevant knowledge.
`similarity_threshold`	`number`	No	The minimum similarity score required for a retrieved item to be considered relevant.
`vector_similarity_weight`	`number`	No	Weighting factor applied to vector similarity scores when ranking results.
`rerank_id`	`string`	Yes	Optional identifier for reranking the results based on a particular strategy or model.
`top_k`	`number`	Yes	Optional maximum number of top results to return.
`use_kg`	`boolean`	Yes	Optional flag indicating whether to utilize a knowledge graph in retrieval.
`highlight`	`boolean`	Yes	Optional flag to enable highlighting of matched segments in the results.
`kb_id`	`string[]`	Yes	Optional list of knowledge base IDs to restrict the retrieval scope.

Usage Example

const requestBody: ITestRetrievalRequestBody = {
  question: "What is the capital of France?",
  similarity_threshold: 0.7,
  vector_similarity_weight: 0.8,
  top_k: 5,
  use_kg: true,
  highlight: true,
  kb_id: ["kb123", "kb456"],
};

2. IFetchKnowledgeListRequestBody

Defines the structure of the request body used to fetch a list of knowledge entries filtered by owner IDs.

Property	Type	Optional	Description
`owner_ids`	`string[]`	Yes	List of owner/user IDs to filter the knowledge list by ownership.

Usage Example

const requestBody: IFetchKnowledgeListRequestBody = {
  owner_ids: ["user1", "user2"],
};

3. IFetchKnowledgeListRequestParams

Specifies query parameters for fetching a paginated list of knowledge bases with optional filters.

Property	Type	Optional	Description
`kb_id`	`string`	Yes	Filter by a specific knowledge base ID.
`keywords`	`string`	Yes	Keywords to search within the knowledge bases.
`page`	`number`	Yes	Page number for pagination (default depends on the backend).
`page_size`	`number`	Yes	Number of items per page for pagination.

Usage Example

const queryParams: IFetchKnowledgeListRequestParams = {
  kb_id: "kb123",
  keywords: "machine learning",
  page: 2,
  page_size: 10,
};

4. IFetchDocumentListRequestBody

Defines the request body structure for fetching a list of documents filtered by file suffixes and run statuses.

Property	Type	Optional	Description
`suffix`	`string[]`	Yes	Array of file suffixes/extensions to filter documents (e.g., `["pdf", "docx"]`).
`run_status`	`string[]`	Yes	Array of run statuses to filter the documents (e.g., `["completed", "pending"]`).

Usage Example

const requestBody: IFetchDocumentListRequestBody = {
  suffix: ["pdf", "txt"],
  run_status: ["completed"],
};

Implementation Details

The file contains no executable code; it only exports TypeScript interfaces for type validation and development-time safety.
These interfaces are designed to be used in API client modules or service layers that send requests to backend knowledge management or retrieval endpoints.
Optional properties use the ? modifier to indicate they are not mandatory, allowing flexible request construction.
Arrays are used where multiple filter values can be provided, supporting multi-criteria filtering.
The naming conventions follow a consistent I prefix for interfaces and descriptive names reflecting their role in fetching or retrieving knowledge data.

Interaction with Other System Components

These interfaces are likely imported and used in service modules that construct HTTP requests to backend APIs managing knowledge bases, knowledge graphs, or document repositories.
For example, a function that fetches relevant documents based on a user query would use ITestRetrievalRequestBody to ensure the payload adheres to expected structure.
Pagination and filtering interfaces (IFetchKnowledgeListRequestParams) enable integration with UI components that display paginated lists of knowledge bases, supporting keyword search and filtering.
The interfaces help maintain strong typing between front-end or middleware layers and backend API endpoints.

Visual Diagram

classDiagram
    class ITestRetrievalRequestBody {
        +question: string
        +similarity_threshold: number
        +vector_similarity_weight: number
        +rerank_id?: string
        +top_k?: number
        +use_kg?: boolean
        +highlight?: boolean
        +kb_id?: string[]
    }

    class IFetchKnowledgeListRequestBody {
        +owner_ids?: string[]
    }

    class IFetchKnowledgeListRequestParams {
        +kb_id?: string
        +keywords?: string
        +page?: number
        +page_size?: number
    }

    class IFetchDocumentListRequestBody {
        +suffix?: string[]
        +run_status?: string[]
    }

Summary

This file provides essential TypeScript interfaces for structuring requests related to knowledge retrieval and management. By defining these interfaces, the application ensures consistency and type safety across components interacting with backend knowledge services, enabling robust querying, filtering, and retrieval of knowledge bases and documents.