API: added the endpoint responses

Author: irfanpena

cortex-js/src/infrastructure/controllers/assistants.controller.ts

@@ -20,7 +20,7 @@ export class AssistantsController {
     description: 'Creates a new assistant.',
   })
   @ApiCreatedResponse({
-    description: 'Assistant created successfully.',
+    description: 'The assistant has been successfully created.',
   })
   @Post()
   create(@Body() createAssistantDto: CreateAssistantDto) {
@@ -32,7 +32,7 @@ export class AssistantsController {
     description: 'Retrieves all the available assistants along with their settings.',
   })
   @ApiOkResponse({
-    description: 'Return an array of assistants',
+    description: 'Ok',
     type: [AssistantEntity],
   })
   @Get()
@@ -45,7 +45,7 @@ export class AssistantsController {
     description: "Retrieves a specific assistant defined by an assistant's `id`.",
   })
   @ApiOkResponse({
-    description: 'Return an assistant object',
+    description: 'Ok',
     type: AssistantEntity,
   })
   @ApiParam({ name: 'id', required: true, description: "The unique identifier of the assistant." })
@@ -59,7 +59,7 @@ export class AssistantsController {
     description: "Deletes a specific assistant defined by an assistant's `id`.",
   })
   @ApiOkResponse({
-    description: 'Successfully deleted the assistant.',
+    description: 'The assistant has been successfully deleted.',
   })
   @ApiParam({ name: 'id', required: true, description: "The unique identifier of the assistant." })
   @Delete(':id')

cortex-js/src/infrastructure/controllers/chat.controller.ts

@@ -1,4 +1,4 @@
-import { Body, Controller, Post, Headers, Res } from '@nestjs/common';
+import { Body, Controller, Post, Headers, Res, HttpCode } from '@nestjs/common';
 import { CreateChatCompletionDto } from '@/infrastructure/dtos/chat/create-chat-completion.dto';
 import { ChatUsecases } from '@/usecases/chat/chat.usecases';
 import { Response } from 'express';
@@ -8,8 +8,13 @@ import {
   ApiOperation,
   ApiTags,
   getSchemaPath,
+  ApiResponse
 } from '@nestjs/swagger';
 import { ChatStreamEvent } from '@/domain/abstracts/oai.abstract';
+import {
+  ChatCompletionChunkedResponse,
+  ChatCompletionResponse,
+} from '../dtos/chat/chat-completion-response.dto';
 
 @ApiTags('Inference')
 @Controller('chat')
@@ -21,6 +26,12 @@ export class ChatController {
     description:
       "Creates a model response for the given chat conversation. The API limits stop words to a maximum of 4. If more are specified, only the first four will be accepted. [Equivalent to OpenAI's create chat completion](https://platform.openai.com/docs/api-reference/chat/create).",
   })
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: ChatCompletionChunkedResponse,
+  })
   @Post('completions')
   async create(
     @Headers() headers: Record<string, string>,

cortex-js/src/infrastructure/controllers/models.controller.ts

@@ -11,6 +11,9 @@ import {
 import { ModelsUsecases } from '@/usecases/models/models.usecases';
 import { CreateModelDto } from '@/infrastructure/dtos/models/create-model.dto';
 import { UpdateModelDto } from '@/infrastructure/dtos/models/update-model.dto';
+import { ModelDto } from '@/infrastructure/dtos/models/model-successfully-created.dto';
+import { ListModelsResponseDto } from '@/infrastructure/dtos/models/list-model-response.dto';
+import { DeleteModelResponseDto } from '@/infrastructure/dtos/models/delete-model.dto';
 import {
   ApiCreatedResponse,
   ApiOkResponse,
@@ -28,11 +31,6 @@ export class ModelsController {
   constructor(private readonly modelsUsecases: ModelsUsecases) {}
 
   @ApiOperation({ summary: 'Create model', description: "Creates a model `.json` instance file manually." })
-  @HttpCode(200)
-  @ApiResponse({
-    status: 200,
-    description: 'The model has been successfully created.'
-  })
   @Post()
   create(@Body() createModelDto: CreateModelDto) {
     return this.modelsUsecases.create(createModelDto);
@@ -74,12 +72,24 @@ export class ModelsController {
     return this.modelsUsecases.downloadModel(modelId);
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: ListModelsResponseDto,
+  })
   @ApiOperation({ summary: 'List models', description: "Lists the currently available models, and provides basic information about each one such as the owner and availability. [Equivalent to OpenAI's list model](https://platform.openai.com/docs/api-reference/models/list)." })
   @Get()
   findAll() {
     return this.modelsUsecases.findAll();
   }
 
+  @HttpCode(200)
+  @ApiResponse({
+    status: 200,
+    description: 'Ok',
+    type: ModelDto,
+  })
   @ApiOperation({ summary: 'Get model', description: "Retrieves a model instance, providing basic information about the model such as the owner and permissions. [Equivalent to OpenAI's list model](https://platform.openai.com/docs/api-reference/models/retrieve)." })
   @ApiParam({ name: 'id', required: true, description: "The unique identifier of the model." })
   @Get(':id')
@@ -93,7 +103,7 @@ export class ModelsController {
     description: 'The model has been successfully updated.',
     type: UpdateModelDto,
   })
-  @ApiOperation({ summary: 'Update model', description: "Updates a model instance defined by a mode;'s `id`." })
+  @ApiOperation({ summary: 'Update model', description: "Updates a model instance defined by a model's `id`." })
   @ApiParam({ name: 'id', required: true, description: "The unique identifier of the model." })
   @Patch(':id')
   update(@Param('id') id: string, @Body() updateModelDto: UpdateModelDto) {
@@ -102,7 +112,8 @@ export class ModelsController {
 
   @ApiResponse({
     status: 200,
-    description: 'The model has been successfully deleted.'
+    description: 'The model has been successfully deleted.',
+    type: DeleteModelResponseDto,
   })
   @ApiOperation({ summary: 'Delete model', description: "Deletes a model. [Equivalent to OpenAI's delete model](https://platform.openai.com/docs/api-reference/models/delete)." })
   @ApiParam({ name: 'id', required: true, description: "The unique identifier of the model." })

cortex-js/src/infrastructure/dtos/chat/chat-completion-response.dto.ts

@@ -0,0 +1,127 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+class Usage {
+  @ApiProperty({
+    type: Number,
+    description: 'Number of tokens in the generated completion.',
+  })
+  completion_tokens: number;
+
+  @ApiProperty({ type: Number, description: 'Number of tokens in the prompt.' })
+  prompt_tokens: number;
+
+  @ApiProperty({
+    type: Number,
+    description:
+      'Total number of tokens used in the request (prompt + completion).',
+  })
+  total_tokens: number;
+}
+
+class Choice {
+  @ApiProperty({ type: String, description: 'The text of the completion.' })
+  text: string;
+
+  @ApiProperty({ type: Number, description: 'Index of the choice.' })
+  index: number;
+
+  @ApiProperty({
+    type: String,
+    description: 'Reason for finishing the completion.',
+  })
+  finish_reason: string;
+}
+
+export class ChatCompletionResponse {
+  @ApiProperty({
+    type: String,
+    description: 'A unique identifier for the chat completion.',
+  })
+  id: string;
+
+  @ApiProperty({
+    type: [Choice],
+    description: 'A list of chat completion choices.',
+  })
+  choices: Choice[];
+
+  @ApiProperty({
+    type: Number,
+    description:
+      'The Unix timestamp (in seconds) of when the chat completion was created.',
+  })
+  created: number;
+
+  @ApiProperty({
+    type: String,
+    description: 'The model used for the chat completion.',
+  })
+  model: string;
+
+  @ApiProperty({
+    type: String,
+    description:
+      'The system fingerprint representing the backend configuration.',
+  })
+  system_fingerprint: string;
+
+  @ApiProperty({
+    type: String,
+    description: 'The object type, which is always chat.completion.',
+  })
+  object: string;
+
+  @ApiProperty({
+    type: Usage,
+    description: 'Usage statistics for the completion request.',
+  })
+  usage: Usage;
+}
+
+export class ChatCompletionChunkedResponse {
+  @ApiProperty({
+    type: String,
+    description:
+      'A unique identifier for the chat completion. Each chunk has the same ID.',
+  })
+  id: string;
+
+  @ApiProperty({
+    type: [Choice],
+    description: 'A list of chat completion choices.',
+  })
+  choices: Choice[];
+
+  @ApiProperty({
+    type: Number,
+    description:
+      'The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.',
+  })
+  created: number;
+
+  @ApiProperty({
+    type: String,
+    description: 'The model used to generate the completion.',
+  })
+  model: string;
+
+  @ApiProperty({
+    type: String,
+    description:
+      'The system fingerprint representing the backend configuration.',
+  })
+  system_fingerprint: string;
+
+  @ApiProperty({
+    type: String,
+    description: 'The object type, which is always chat.completion.chunk.',
+  })
+  object: string;
+
+  @ApiProperty({
+    type: Usage,
+    required: false,
+    description: 'Usage statistics for the completion request.',
+  })
+  usage?: Usage;
+}

cortex-js/src/infrastructure/dtos/models/delete-model.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class DeleteModelResponseDto {
+    @ApiProperty({
+        example: 'mistral-ins-7b-q4',
+        description: 'The identifier of the model that was deleted.'
+    })
+    id: string;
+
+    @ApiProperty({
+        example: 'model',
+        description: 'Type of the object, indicating it\'s a model.',
+        default: 'model'
+    })
+    object: string;
+
+    @ApiProperty({
+        example: true,
+        description: 'Indicates whether the model was successfully deleted.'
+    })
+    deleted: boolean;
+}

cortex-js/src/infrastructure/dtos/models/list-model-response.dto.ts

@@ -0,0 +1,10 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { ModelDto } from './model-successfully-created.dto'; // Import the ModelDto class
+
+export class ListModelsResponseDto {
+    @ApiProperty({ example: 'list', enum: ['list'] })
+    object: string;
+
+    @ApiProperty({ type: [ModelDto], description: 'List of models' })
+    data: ModelDto[];
+}

cortex-js/src/infrastructure/dtos/models/model-successfully-created.dto.ts

@@ -0,0 +1,66 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ModelDto {
+    @ApiProperty({ example: 'https://huggingface.co/janhq/trinity-v1.2-GGUF/resolve/main/trinity-v1.2.Q4_K_M.gguf', description: 'URL to the source of the model.' })
+    source_url: string;
+
+    @ApiProperty({ example: 'trinity-v1.2-7b', description: 'Unique identifier used in chat-completions model_name, matches folder name.' })
+    id: string;
+
+    @ApiProperty({ example: 'model' })
+    object: string;
+
+    @ApiProperty({ example: 'Trinity-v1.2 7B Q4', description: 'Name of the model.' })
+    name: string;
+
+    @ApiProperty({ default: '1.0', description: 'The version number of the model.' })
+    version: string;
+
+    @ApiProperty({ example: 'Trinity is an experimental model merge using the Slerp method. Recommended for daily assistance purposes.', description: 'Description of the model.' })
+    description: string;
+
+    @ApiProperty({ example: 'gguf', description: 'State format of the model, distinct from the engine.' })
+    format: string;
+
+    @ApiProperty({ description: 'Context length.', example: 4096 })
+    ctx_len: number;
+
+    @ApiProperty({ example: 'system\n{system_message}\nuser\n{prompt}\nassistant' })
+    prompt_template: string;
+
+    @ApiProperty({ example: 0.7 })
+    temperature: number;
+
+    @ApiProperty({ example: 0.95 })
+    top_p: number;
+
+    @ApiProperty({ example: true })
+    stream: boolean;
+
+    @ApiProperty({ example: 4096 })
+    max_tokens: number;
+
+    @ApiProperty({ type: [String], example: [] })
+    stop: string[];
+
+    @ApiProperty({ example: 0 })
+    frequency_penalty: number;
+
+    @ApiProperty({ example: 0 })
+    presence_penalty: number;
+
+    @ApiProperty({ example: 'Jan' })
+    author: string;
+
+    @ApiProperty({ type: [String], example: ['7B', 'Merged', 'Featured'] })
+    tags: string[];
+
+    @ApiProperty({ example: 4370000000 })
+    size: number;
+
+    @ApiProperty({ example: 'https://raw.githubusercontent.com/janhq/jan/main/models/trinity-v1.2-7b/cover.png' })
+    cover: string;
+
+    @ApiProperty({ example: 'nitro' })
+    engine: string;
+}