Added examples and revamped the API desc

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

@@ -28,7 +28,7 @@ export class ConfigsController {
   @ApiOperation({
     summary: 'List configs',
     description:
-      'Lists the currently available configs, including the default and user-defined configurations',
+      'Lists the currently available configs, including the default and user-defined configurations.',
   })
   @Get()
   findAll() {
@@ -44,7 +44,7 @@ export class ConfigsController {
   @ApiOperation({
     summary: 'Get a config',
     description:
-      'Retrieves a config instance, providing basic information about the config',
+      'Retrieves a config instance, providing basic information about the config.',
   })
   @ApiParam({
     name: 'name',
@@ -64,7 +64,7 @@ export class ConfigsController {
   })
   @ApiOperation({
     summary: 'Configure a model',
-    description: "Updates a config by it's group and key",
+    description: "Updates a specific configuration setting by its group and key.",
     parameters: [
       {
         in: 'path',

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

@@ -25,7 +25,7 @@ export class EnginesController {
   @ApiOperation({
     summary: 'List available engines',
     description:
-      'Lists the currently available engines, including local and remote engines',
+      'Lists the currently available engines, including local and remote engines.',
   })
   @Get()
   findAll() {
@@ -41,7 +41,7 @@ export class EnginesController {
   @ApiOperation({
     summary: 'Get an engine',
     description:
-      'Retrieves an engine instance, providing basic information about the engine',
+      'Retrieves an engine instance, providing basic information about the engine.',
   })
   @ApiParam({
     name: 'name',

cortex-js/src/infrastructure/dtos/configs/config-update.dto.ts

@@ -4,7 +4,7 @@ import { IsOptional, IsString } from 'class-validator';
 export class ConfigUpdateDto {
   @ApiProperty({
     example: 'apiKey',
-    description: 'The configuration key.',
+    description: 'The configuration API key.',
   })
   @IsString()
   @IsOptional()
@@ -14,7 +14,7 @@ export class ConfigUpdateDto {
   @ApiProperty({
     type: String,
     example: 'sk-xxxxxx',
-    description: 'The value of the configuration.',
+    description: 'The value of the configuration API key.',
   })
   @IsString()
   @IsOptional()
@@ -23,7 +23,7 @@ export class ConfigUpdateDto {
   @ApiProperty({
     type: String,
     example: 'openai',
-    description: 'The configuration name.',
+    description: 'The name of the configuration.',
   })
   @IsString()
   @IsOptional()

cortex-js/src/infrastructure/dtos/embeddings/embeddings-request.dto.ts

@@ -3,19 +3,22 @@ import { ApiProperty } from '@nestjs/swagger';
 
 export class CreateEmbeddingsDto {
   @ApiProperty({
+    example: 'llama3',
     description: 'The name of the embedding model to be used.',
     type: String,
   })
   model: string;
 
   @ApiProperty({
+    example: ['Hello World'],
     description:
       'The text or token array(s) to be embedded. This can be a single string, an array of strings, or an array of token arrays to embed multiple inputs in one request.',
     type: [String],
   })
   input: string | string[];
 
   @ApiProperty({
+    example: 'float',
     description:
       'Specifies the format for the embeddings. Supported formats include `float` and `int`. This field is optional.',
     type: String,
@@ -24,6 +27,7 @@ export class CreateEmbeddingsDto {
   encoding_format?: string;
 
   @ApiProperty({
+    example: 3,
     description:
       'Defines the number of dimensions for the output embeddings. This feature is supported by certain models only. This field is optional.',
     type: Number,

cortex-js/src/infrastructure/dtos/engines/engines.dto.ts

@@ -7,7 +7,7 @@ export class EngineDto implements Partial<Extension> {
     type: String,
     example: 'cortex.llamacpp',
     description:
-      'The name of the engine, which can be referenced in the API endpoints.',
+      'The name of the engine that you want to retrieve.',
   })
   @IsString()
   name: string;

cortex-js/src/infrastructure/dtos/messages/create-message.dto.ts

@@ -4,32 +4,54 @@ import { Message, MessageContent } from '@/domain/models/message.interface';
 
 export class CreateMessageDto implements Partial<Message> {
   @ApiProperty({
+    example: 'thread_456',
     description: 'The ID of the thread to which the message will be posted.',
   })
   @IsString()
   thread_id: string;
 
-  @ApiProperty({ description: "The assistant's unique identifier." })
+  @ApiProperty({
+    example: 'assistant_789',
+    description: "The assistant's unique identifier.",
+  })
   @IsString()
   assistant_id?: string;
 
-  @ApiProperty({ description: 'The sources of the messages.' })
+  @ApiProperty({
+    example: 'user',
+    description: 'The sources of the messages.',
+  })
   role: 'user' | 'assistant';
 
-  @ApiProperty({ description: 'The content of the messages.' })
+  @ApiProperty({
+    example: [
+      {
+        type: 'text',
+        data: 'Hello, how can I help you today?'
+      }
+    ],
+    description: 'The content of the messages.',
+  })
   @IsArray()
   content: MessageContent[];
 
-  @ApiProperty({ description: 'Current status of the message.' })
+  @ApiProperty({
+    example: 'in_progress',
+    description: 'Current status of the message.',
+  })
   status: 'in_progress' | 'incomplete' | 'completed';
 
   @ApiProperty({
-    description:
-      'Optional dictionary for additional unstructured message information.',
+    example: { urgency: 'high', tags: ['customer_support'] },
+    description: 'Optional dictionary for additional unstructured message information.',
   })
   metadata?: Record<string, unknown>;
 
-  @ApiProperty({ description: 'Type of the message.' })
+  @ApiProperty({
+    example: 'text',
+    description: 'Type of the message.',
+  })
   @IsString()
   type?: string;
 }
+

cortex-js/src/infrastructure/dtos/threads/create-message.dto.ts

@@ -2,13 +2,15 @@ import { ApiProperty } from '@nestjs/swagger';
 
 export class CreateMessageDto {
   @ApiProperty({
+    example: 'user',
     description: `The role of the entity that is creating the message. Allowed values include:
       - user: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
       - assistant: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.`,
   })
   role: 'user' | 'assistant';
 
   @ApiProperty({
+    example: 'Tell me a joke',
     description: 'The text contents of the message.',
   })
   content: string;

cortex-js/src/infrastructure/dtos/threads/create-thread-assistant.dto.ts

@@ -8,66 +8,117 @@ import type {
 
 export class CreateThreadAssistantDto implements Assistant {
   @ApiProperty({
+    example: 'thread_123',
     description: 'The unique identifier of the assistant.',
     type: 'string',
   })
   @IsString()
   id: string;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 'https://example.com/avatar.png',
+    description: 'URL of the assistant\'s avatar image.',
+    type: 'string',
+  })
   @IsOptional()
   @IsString()
   avatar?: string;
 
-  @ApiProperty({ description: 'The name of the assistant.' })
+  @ApiProperty({
+    example: 'Virtual Helper',
+    description: 'The name of the assistant.',
+    type: 'string',
+  })
   @IsString()
   name: string;
 
-  @ApiProperty({ description: "The model's unique identifier and settings." })
+  @ApiProperty({
+    example: 'llama3',
+    description: 'The model\'s unique identifier and settings.',
+    type: 'string',
+  })
   @IsString()
   model: string;
 
-  @ApiProperty({ description: "The assistant's specific instructions." })
+  @ApiProperty({
+    example: 'Assist with customer queries and provide information based on the company database.',
+    description: 'The assistant\'s specific instructions.',
+    type: 'string',
+  })
   @IsString()
   instructions: string;
 
   @ApiProperty({
-    description: "The thread's tool(Knowledge Retrieval) configurations.",
+    example: [{ name: 'Knowledge Retrieval', settings: { source: 'internal', endpoint: 'https://api.example.com/knowledge' } }],
+    description: 'The thread\'s tool(Knowledge Retrieval) configurations.',
+    type: 'array',
   })
   @IsOptional()
   @IsArray()
   tools: any;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 'This assistant helps with customer support by retrieving relevant information.',
+    description: 'The description of the assistant.',
+    type: 'string',
+  })
   @IsString()
   @IsOptional()
   description: string | null;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: { department: 'support', version: '1.0' },
+    description: 'Additional metadata for the assistant.',
+    type: 'object',
+  })
   @IsOptional()
   metadata: Record<string, unknown> | null;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 'assistant',
+    description: 'The object type, always "assistant".',
+    type: 'string',
+  })
   object: 'assistant';
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 0.7,
+    description: 'Sampling temperature for the assistant.',
+    type: 'number',
+  })
   @IsNumber()
   @IsOptional()
   temperature?: number | null;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 0.9,
+    description: 'Top-p sampling value for the assistant.',
+    type: 'number',
+  })
   @IsNumber()
   @IsOptional()
   top_p?: number | null;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 1622470423,
+    description: 'Timestamp of when the assistant was created.',
+    type: 'number',
+  })
   created_at: number;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: { format: 'json' },
+    description: 'The response format option for the assistant.',
+    type: 'object',
+  })
   @IsOptional()
   response_format?: AssistantResponseFormatOption;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: { resources: ['database1', 'database2'] },
+    description: 'Tool resources for the assistant.',
+    type: 'object',
+  })
   @IsOptional()
   tool_resources?: AssistantToolResources;
-}
+}

cortex-js/src/infrastructure/dtos/threads/delete-message.dto.ts

@@ -1,12 +1,22 @@
 import { ApiProperty } from '@nestjs/swagger';
 
 export default class DeleteMessageDto {
-  @ApiProperty()
+  @ApiProperty({
+    example: 'message_123',
+    description: 'The identifier of the message that was deleted.',
+  })
   id: string;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: 'message',
+    description: "Type of the object, indicating it's a message.",
+    default: 'message',
+  })
   object: string;
 
-  @ApiProperty()
+  @ApiProperty({
+    example: true,
+    description: 'Indicates whether the message was successfully deleted.',
+  })
   deleted: boolean;
 }