@knowledge-stack/ksapi 1.13.0 → 1.14.0

package/src/apis/ChunksApi.ts

@@ -16,18 +16,24 @@
 import * as runtime from '../runtime';
 import type {
   ChunkResponse,
+  ChunkSearchRequest,
   CreateChunkRequest,
   HTTPValidationError,
+  ScoredChunkResponse,
   UpdateChunkContentRequest,
   UpdateChunkMetadataRequest,
 } from '../models/index';
 import {
     ChunkResponseFromJSON,
     ChunkResponseToJSON,
+    ChunkSearchRequestFromJSON,
+    ChunkSearchRequestToJSON,
     CreateChunkRequestFromJSON,
     CreateChunkRequestToJSON,
     HTTPValidationErrorFromJSON,
     HTTPValidationErrorToJSON,
+    ScoredChunkResponseFromJSON,
+    ScoredChunkResponseToJSON,
     UpdateChunkContentRequestFromJSON,
     UpdateChunkContentRequestToJSON,
     UpdateChunkMetadataRequestFromJSON,
@@ -49,6 +55,11 @@ export interface GetChunkRequest {
     ksUat?: string;
 }
 
+export interface SearchChunksRequest {
+    chunkSearchRequest: ChunkSearchRequest;
+    ksUat?: string;
+}
+
 export interface UpdateChunkContentOperationRequest {
     chunkId: string;
     updateChunkContentRequest: UpdateChunkContentRequest;
@@ -119,6 +130,23 @@ export interface ChunksApiInterface {
      */
     getChunk(requestParameters: GetChunkRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<ChunkResponse>;
 
+    /**
+     * Semantic search over chunks using vector similarity.  Combines pgvector cosine similarity with path-based authorization and optional metadata filters. Uses a two-session design to avoid holding a DB connection during the external embedding API call.
+     * @summary Search Chunks Handler
+     * @param {ChunkSearchRequest} chunkSearchRequest 
+     * @param {string} [ksUat] 
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof ChunksApiInterface
+     */
+    searchChunksRaw(requestParameters: SearchChunksRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Array<ScoredChunkResponse>>>;
+
+    /**
+     * Semantic search over chunks using vector similarity.  Combines pgvector cosine similarity with path-based authorization and optional metadata filters. Uses a two-session design to avoid holding a DB connection during the external embedding API call.
+     * Search Chunks Handler
+     */
+    searchChunks(requestParameters: SearchChunksRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Array<ScoredChunkResponse>>;
+
     /**
      * Update chunk content by creating a new content row.  The old content row is preserved (not deleted). If the new content matches an existing content hash, it will be deduplicated.
      * @summary Update Chunk Content Handler
@@ -280,6 +308,47 @@ export class ChunksApi extends runtime.BaseAPI implements ChunksApiInterface {
         return await response.value();
     }
 
+    /**
+     * Semantic search over chunks using vector similarity.  Combines pgvector cosine similarity with path-based authorization and optional metadata filters. Uses a two-session design to avoid holding a DB connection during the external embedding API call.
+     * Search Chunks Handler
+     */
+    async searchChunksRaw(requestParameters: SearchChunksRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<Array<ScoredChunkResponse>>> {
+        if (requestParameters['chunkSearchRequest'] == null) {
+            throw new runtime.RequiredError(
+                'chunkSearchRequest',
+                'Required parameter "chunkSearchRequest" was null or undefined when calling searchChunks().'
+            );
+        }
+
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        headerParameters['Content-Type'] = 'application/json';
+
+
+        let urlPath = `/v1/chunks/search`;
+
+        const response = await this.request({
+            path: urlPath,
+            method: 'POST',
+            headers: headerParameters,
+            query: queryParameters,
+            body: ChunkSearchRequestToJSON(requestParameters['chunkSearchRequest']),
+        }, initOverrides);
+
+        return new runtime.JSONApiResponse(response, (jsonValue) => jsonValue.map(ScoredChunkResponseFromJSON));
+    }
+
+    /**
+     * Semantic search over chunks using vector similarity.  Combines pgvector cosine similarity with path-based authorization and optional metadata filters. Uses a two-session design to avoid holding a DB connection during the external embedding API call.
+     * Search Chunks Handler
+     */
+    async searchChunks(requestParameters: SearchChunksRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<Array<ScoredChunkResponse>> {
+        const response = await this.searchChunksRaw(requestParameters, initOverrides);
+        return await response.value();
+    }
+
     /**
      * Update chunk content by creating a new content row.  The old content row is preserved (not deleted). If the new content matches an existing content hash, it will be deduplicated.
      * Update Chunk Content Handler

package/src/models/ChunkSearchRequest.ts

@@ -0,0 +1,160 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * The version of the OpenAPI document: 0.1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+import type { EmbeddingModel } from './EmbeddingModel';
+import {
+    EmbeddingModelFromJSON,
+    EmbeddingModelFromJSONTyped,
+    EmbeddingModelToJSON,
+    EmbeddingModelToJSONTyped,
+} from './EmbeddingModel';
+import type { ChunkType } from './ChunkType';
+import {
+    ChunkTypeFromJSON,
+    ChunkTypeFromJSONTyped,
+    ChunkTypeToJSON,
+    ChunkTypeToJSONTyped,
+} from './ChunkType';
+
+/**
+ * Request body for semantic chunk search.
+ * @export
+ * @interface ChunkSearchRequest
+ */
+export interface ChunkSearchRequest {
+    /**
+     * Search query text
+     * @type {string}
+     * @memberof ChunkSearchRequest
+     */
+    query: string;
+    /**
+     * Embedding model to use
+     * @type {EmbeddingModel}
+     * @memberof ChunkSearchRequest
+     */
+    model?: EmbeddingModel;
+    /**
+     * Path part IDs to search within (non-CHUNK types). Defaults to tenant's /KS_ROOT/shared.
+     * @type {Array<string>}
+     * @memberof ChunkSearchRequest
+     */
+    parentPathIds?: Array<string>;
+    /**
+     * Filter by chunk type (TEXT, TABLE, IMAGE, UNKNOWN)
+     * @type {ChunkType}
+     * @memberof ChunkSearchRequest
+     */
+    chunkType?: ChunkType;
+    /**
+     * Only chunks updated after this timestamp
+     * @type {Date}
+     * @memberof ChunkSearchRequest
+     */
+    updatedAt?: Date;
+    /**
+     * Number of results (1-50)
+     * @type {number}
+     * @memberof ChunkSearchRequest
+     */
+    topK?: number;
+    /**
+     * Minimum similarity score
+     * @type {number}
+     * @memberof ChunkSearchRequest
+     */
+    scoreThreshold?: number;
+}
+
+
+
+/**
+ * Check if a given object implements the ChunkSearchRequest interface.
+ */
+export function instanceOfChunkSearchRequest(value: object): value is ChunkSearchRequest {
+    if (!('query' in value) || value['query'] === undefined) return false;
+    return true;
+}
+
+export function ChunkSearchRequestFromJSON(json: any): ChunkSearchRequest {
+    return ChunkSearchRequestFromJSONTyped(json, false);
+}
+
+export function ChunkSearchRequestFromJSONTyped(json: any, ignoreDiscriminator: boolean): ChunkSearchRequest {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'query': json['query'],
+        'model': json['model'] == null ? undefined : EmbeddingModelFromJSON(json['model']),
+        'parentPathIds': json['parent_path_ids'] == null ? undefined : json['parent_path_ids'],
+        'chunkType': json['chunk_type'] == null ? undefined : ChunkTypeFromJSON(json['chunk_type']),
+        'updatedAt': json['updated_at'] == null ? undefined : (new Date(json['updated_at'])),
+        'topK': json['top_k'] == null ? undefined : json['top_k'],
+        'scoreThreshold': json['score_threshold'] == null ? undefined : json['score_threshold'],
+    };
+}
+
+export function ChunkSearchRequestToJSON(json: any): ChunkSearchRequest {
+    return ChunkSearchRequestToJSONTyped(json, false);
+}
+
+export function ChunkSearchRequestToJSONTyped(value?: ChunkSearchRequest | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'query': value['query'],
+        'model': EmbeddingModelToJSON(value['model']),
+        'parent_path_ids': value['parentPathIds'],
+        'chunk_type': ChunkTypeToJSON(value['chunkType']),
+        'updated_at': value['updatedAt'] == null ? value['updatedAt'] : value['updatedAt'].toISOString(),
+        'top_k': value['topK'],
+        'score_threshold': value['scoreThreshold'],
+    };
+}
+
+export const ChunkSearchRequestPropertyValidationAttributesMap: {
+    [property: string]: {
+        maxLength?: number,
+        minLength?: number,
+        pattern?: string,
+        maximum?: number,
+        exclusiveMaximum?: boolean,
+        minimum?: number,
+        exclusiveMinimum?: boolean,
+        multipleOf?: number,
+        maxItems?: number,
+        minItems?: number,
+        uniqueItems?: boolean
+    }
+} = {
+    query: {
+        minLength: 1,
+    },
+    topK: {
+        maximum: 50,
+        exclusiveMaximum: false,
+        minimum: 1,
+        exclusiveMinimum: false,
+    },
+}
+
+export const ChunkSearchRequestAdditionalPropertiesValidationAttributes: { maxProperties?: number, minProperties?: number } = {
+}
+

package/src/models/EmbeddingModel.ts

@@ -0,0 +1,52 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * The version of the OpenAPI document: 0.1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+/**
+ * Supported embedding models.
+ * @export
+ */
+export const EmbeddingModel = {
+    TextEmbedding3Small: 'text-embedding-3-small'
+} as const;
+export type EmbeddingModel = typeof EmbeddingModel[keyof typeof EmbeddingModel];
+
+
+export function instanceOfEmbeddingModel(value: any): boolean {
+    for (const key in EmbeddingModel) {
+        if (Object.prototype.hasOwnProperty.call(EmbeddingModel, key)) {
+            if (EmbeddingModel[key as keyof typeof EmbeddingModel] === value) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+export function EmbeddingModelFromJSON(json: any): EmbeddingModel {
+    return EmbeddingModelFromJSONTyped(json, false);
+}
+
+export function EmbeddingModelFromJSONTyped(json: any, ignoreDiscriminator: boolean): EmbeddingModel {
+    return json as EmbeddingModel;
+}
+
+export function EmbeddingModelToJSON(value?: EmbeddingModel | null): any {
+    return value as any;
+}
+
+export function EmbeddingModelToJSONTyped(value: any, ignoreDiscriminator: boolean): EmbeddingModel {
+    return value as EmbeddingModel;
+}
+

package/src/models/ScoredChunkResponse.ts

@@ -0,0 +1,215 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Knowledge Stack API
+ * Knowledge Stack backend API for authentication and knowledge management
+ *
+ * The version of the OpenAPI document: 0.1.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+import type { ChunkMetadataOutput } from './ChunkMetadataOutput';
+import {
+    ChunkMetadataOutputFromJSON,
+    ChunkMetadataOutputFromJSONTyped,
+    ChunkMetadataOutputToJSON,
+    ChunkMetadataOutputToJSONTyped,
+} from './ChunkMetadataOutput';
+import type { ChunkType } from './ChunkType';
+import {
+    ChunkTypeFromJSON,
+    ChunkTypeFromJSONTyped,
+    ChunkTypeToJSON,
+    ChunkTypeToJSONTyped,
+} from './ChunkType';
+
+/**
+ * Chunk response with similarity score.
+ * @export
+ * @interface ScoredChunkResponse
+ */
+export interface ScoredChunkResponse {
+    /**
+     * Chunk ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    id: string;
+    /**
+     * PathPart ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    pathPartId: string;
+    /**
+     * ChunkContent ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    contentId: string;
+    /**
+     * Chunk text content
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    content: string;
+    /**
+     * Type of chunk content
+     * @type {ChunkType}
+     * @memberof ScoredChunkResponse
+     */
+    chunkType: ChunkType;
+    /**
+     * Chunk metadata
+     * @type {ChunkMetadataOutput}
+     * @memberof ScoredChunkResponse
+     */
+    chunkMetadata: ChunkMetadataOutput;
+    /**
+     * Parent PathPart ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    parentId: string;
+    /**
+     * Previous sibling PathPart ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    prevSiblingPathId?: string;
+    /**
+     * Next sibling PathPart ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    nextSiblingId?: string;
+    /**
+     * Full materialized path from root
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    materializedPath: string;
+    /**
+     * Tenant ID
+     * @type {string}
+     * @memberof ScoredChunkResponse
+     */
+    tenantId: string;
+    /**
+     * Creation timestamp
+     * @type {Date}
+     * @memberof ScoredChunkResponse
+     */
+    createdAt: Date;
+    /**
+     * Last update timestamp
+     * @type {Date}
+     * @memberof ScoredChunkResponse
+     */
+    updatedAt: Date;
+    /**
+     * Cosine similarity score (1 - cosine_distance)
+     * @type {number}
+     * @memberof ScoredChunkResponse
+     */
+    score: number;
+}
+
+
+
+/**
+ * Check if a given object implements the ScoredChunkResponse interface.
+ */
+export function instanceOfScoredChunkResponse(value: object): value is ScoredChunkResponse {
+    if (!('id' in value) || value['id'] === undefined) return false;
+    if (!('pathPartId' in value) || value['pathPartId'] === undefined) return false;
+    if (!('contentId' in value) || value['contentId'] === undefined) return false;
+    if (!('content' in value) || value['content'] === undefined) return false;
+    if (!('chunkType' in value) || value['chunkType'] === undefined) return false;
+    if (!('chunkMetadata' in value) || value['chunkMetadata'] === undefined) return false;
+    if (!('parentId' in value) || value['parentId'] === undefined) return false;
+    if (!('materializedPath' in value) || value['materializedPath'] === undefined) return false;
+    if (!('tenantId' in value) || value['tenantId'] === undefined) return false;
+    if (!('createdAt' in value) || value['createdAt'] === undefined) return false;
+    if (!('updatedAt' in value) || value['updatedAt'] === undefined) return false;
+    if (!('score' in value) || value['score'] === undefined) return false;
+    return true;
+}
+
+export function ScoredChunkResponseFromJSON(json: any): ScoredChunkResponse {
+    return ScoredChunkResponseFromJSONTyped(json, false);
+}
+
+export function ScoredChunkResponseFromJSONTyped(json: any, ignoreDiscriminator: boolean): ScoredChunkResponse {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'id': json['id'],
+        'pathPartId': json['path_part_id'],
+        'contentId': json['content_id'],
+        'content': json['content'],
+        'chunkType': ChunkTypeFromJSON(json['chunk_type']),
+        'chunkMetadata': ChunkMetadataOutputFromJSON(json['chunk_metadata']),
+        'parentId': json['parent_id'],
+        'prevSiblingPathId': json['prev_sibling_path_id'] == null ? undefined : json['prev_sibling_path_id'],
+        'nextSiblingId': json['next_sibling_id'] == null ? undefined : json['next_sibling_id'],
+        'materializedPath': json['materialized_path'],
+        'tenantId': json['tenant_id'],
+        'createdAt': (new Date(json['created_at'])),
+        'updatedAt': (new Date(json['updated_at'])),
+        'score': json['score'],
+    };
+}
+
+export function ScoredChunkResponseToJSON(json: any): ScoredChunkResponse {
+    return ScoredChunkResponseToJSONTyped(json, false);
+}
+
+export function ScoredChunkResponseToJSONTyped(value?: ScoredChunkResponse | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'id': value['id'],
+        'path_part_id': value['pathPartId'],
+        'content_id': value['contentId'],
+        'content': value['content'],
+        'chunk_type': ChunkTypeToJSON(value['chunkType']),
+        'chunk_metadata': ChunkMetadataOutputToJSON(value['chunkMetadata']),
+        'parent_id': value['parentId'],
+        'prev_sibling_path_id': value['prevSiblingPathId'],
+        'next_sibling_id': value['nextSiblingId'],
+        'materialized_path': value['materializedPath'],
+        'tenant_id': value['tenantId'],
+        'created_at': value['createdAt'].toISOString(),
+        'updated_at': value['updatedAt'].toISOString(),
+        'score': value['score'],
+    };
+}
+
+export const ScoredChunkResponsePropertyValidationAttributesMap: {
+    [property: string]: {
+        maxLength?: number,
+        minLength?: number,
+        pattern?: string,
+        maximum?: number,
+        exclusiveMaximum?: boolean,
+        minimum?: number,
+        exclusiveMinimum?: boolean,
+        multipleOf?: number,
+        maxItems?: number,
+        minItems?: number,
+        uniqueItems?: boolean
+    }
+} = {
+}
+

package/src/models/index.ts

@@ -4,6 +4,7 @@ export * from './ChunkLineageResponse';
 export * from './ChunkMetadataInput';
 export * from './ChunkMetadataOutput';
 export * from './ChunkResponse';
+export * from './ChunkSearchRequest';
 export * from './ChunkType';
 export * from './CreateChunkLineageRequest';
 export * from './CreateChunkRequest';
@@ -23,6 +24,7 @@ export * from './DocumentType';
 export * from './DocumentVersionResponse';
 export * from './EmailSentResponse';
 export * from './EmailVerificationRequest';
+export * from './EmbeddingModel';
 export * from './FolderDocumentResponse';
 export * from './FolderResponse';
 export * from './HTTPValidationError';
@@ -59,6 +61,7 @@ export * from './PermissionResponse';
 export * from './Polygon';
 export * from './PolygonReference';
 export * from './RootResponse';
+export * from './ScoredChunkResponse';
 export * from './SectionResponse';
 export * from './SignInRequest';
 export * from './TagPathPartRequest';