Added examples and revamped the API desc (#823)

irfanpena · web-flow · commit b2d9d5f31a5c · 2024-07-05T14:02:44.000+07:00
diff --git a/README.md b/README.md
@@ -28,9 +28,13 @@ Cortex currently supports 3 inference engines:
 ### Prerequisites
 Ensure that your system meets the following requirements to run Cortex:
 - **Dependencies**:
-  - **Node.js**: version 18 and above is required to run the installation.
+  - **Node.js**: Version 18 and above is required to run the installation.
   - **NPM**: Needed to manage packages.
   - **CPU Instruction Sets**: Available for download from the [Cortex GitHub Releases](https://github.com/janhq/cortex/releases) page.
+  - **OpenMPI**: Required for Linux. Install by using the following command:
+    ```bash
+    sudo apt install openmpi-bin libopenmpi-dev
+    ```
 - **OS**:
   - MacOSX 13.6 or higher.
   - Windows 10 or higher.
diff --git a/cortex-js/README.md b/cortex-js/README.md
@@ -28,9 +28,13 @@ Cortex currently supports 3 inference engines:
 ### Prerequisites
 Ensure that your system meets the following requirements to run Cortex:
 - **Dependencies**:
-  - **Node.js**: version 18 and above is required to run the installation.
+  - **Node.js**: Version 18 and above is required to run the installation.
   - **NPM**: Needed to manage packages.
   - **CPU Instruction Sets**: Available for download from the [Cortex GitHub Releases](https://github.com/janhq/cortex/releases) page.
+  - **OpenMPI**: Required for Linux. Install by using the following command:
+    ```bash
+    sudo apt install openmpi-bin libopenmpi-dev
+    ```
 - **OS**:
   - MacOSX 13.6 or higher.
   - Windows 10 or higher.
diff --git a/cortex-js/src/app.ts b/cortex-js/src/app.ts
@@ -30,12 +30,12 @@ export const getApp = async () => {
   const config = new DocumentBuilder()
     .setTitle('Cortex API')
     .setDescription(
-      'Cortex API provides a command-line interface (CLI) for seamless interaction with large language models (LLMs). It is fully compatible with the [OpenAI API](https://platform.openai.com/docs/api-reference) and enables straightforward command execution and management of LLM interactions.',
+      'Cortex API provides a command-line interface (CLI) for seamless interaction with Large Language Models (LLMs). It is fully compatible with the [OpenAI API](https://platform.openai.com/docs/api-reference) and enables straightforward command execution and management of LLM interactions.',
     )
     .setVersion('1.0')
     .addTag(
       'Inference',
-      'This endpoint initiates interaction with a Language Learning Model (LLM).',
+      'This endpoint initiates interaction with a Large Language Models (LLM).',
     )
     .addTag(
       'Assistants',
diff --git a/cortex-js/src/infrastructure/controllers/configs.controller.ts b/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',
diff --git a/cortex-js/src/infrastructure/controllers/engines.controller.ts b/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',
diff --git a/cortex-js/src/infrastructure/dtos/configs/config-update.dto.ts b/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()
diff --git a/cortex-js/src/infrastructure/dtos/embeddings/embeddings-request.dto.ts b/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,
diff --git a/cortex-js/src/infrastructure/dtos/engines/engines.dto.ts b/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;
diff --git a/cortex-js/src/infrastructure/dtos/messages/create-message.dto.ts b/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;
 }
+
diff --git a/cortex-js/src/infrastructure/dtos/threads/create-message.dto.ts b/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;
diff --git a/cortex-js/src/infrastructure/dtos/threads/create-thread-assistant.dto.ts b/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;
-}
+}
diff --git a/cortex-js/src/infrastructure/dtos/threads/delete-message.dto.ts b/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;
 }
