docs: add assistants api reference

docs/docs/specs/engineering/assistants.md

@@ -40,6 +40,10 @@ In Jan, assistants are `primary` entities with the following capabilities:
 
 ## `assistant.json`
 
+- Each `assistant` folder contains an `assistant.json` file, which is a representation of an assistant.
+- `assistant.json` contains metadata and model parameter overrides
+- There are no required fields.
+
 ```js
 {
   "id": "asst_abc123",                // Defaults to foldername

docs/openapi/jan.yaml

@@ -476,6 +476,74 @@ paths:
         - lang: "curl"
           source: |
             curl http://localhost:1337/v1/threads/{thread_id}
+  ### ASSISTANTS
+  /assistants/:
+    get:
+      operationId: listAssistants
+      tags:
+        - Assistants
+      summary: List assistants
+      description: |
+        Return a list of assistants. <a href = "https://platform.openai.com/docs/api-reference/assistants/listAssistants"> Equivalent to OpenAI's list assistants. </a>
+      responses:
+        "200":
+          description: 
+          content:
+            application/json:
+              schema:
+                $ref: "specs/assistants.yaml#/components/schemas/ListAssistantsResponse"
+    post:
+      operationId: createAssistant
+      tags:
+        - Assistants
+      summary: Create assistant
+      description: |
+        Create an assistant with a model and instructions. <a href = "https://platform.openai.com/docs/api-reference/assistants/createAssistant"> Equivalent to OpenAI's create assistants. </a>
+      responses:
+        "200":
+          description:
+          content:
+            application/json:
+              schema:
+                $ref: "specs/assistants.yaml#/components/schemas/CreateAssistantResponse"
+
+  /assistants/{assistant_id}:
+    get:
+      operationId: getAssistant
+      tags:
+        - Assistants
+      summary: Retrieve assistant
+      description: |
+        Retrieves an assistant. <a href = "https://platform.openai.com/docs/api-reference/assistants/getAssistant"> Equivalent to OpenAI's retrieve assistants. </a> 
+      responses:
+        "200":
+          description:
+          content:
+            application/json:
+              schema:
+                $ref: "specs/assistants.yaml#/components/schemas/RetrieveAssistantResponse"
+
+    post:
+      operationId: modifyAssistant
+      tags:
+        - Assistants
+      summary: Modify assistant
+      description: |
+        Modifies an assistant. <a href = "https://platform.openai.com/docs/api-reference/assistants/modifyAssistant"> Equivalent to OpenAI's modify assistant. </a>
+    delete:
+      operationId: deleteAssistant
+      tags:
+        - Assistants
+      summary: Delete assistant
+      description: |
+        Delete an assistant. <a href = "https://platform.openai.com/docs/api-reference/assistants/deleteAssistant"> Equivalent to OpenAI's delete assistant. </a>
+      responses:
+        "200":
+          description:
+          content:
+            application/json:
+              schema:
+                $ref: "specs/assistants.yaml#/components/schemas/ModifyAssistantResponse"
 
   ### MESSAGES
   /threads/{thread_id}/messages:
@@ -709,6 +777,19 @@ x-webhooks:
           application/json:
             schema:
               $ref: 'specs/models.yaml#/components/schemas/ModelObject'
+  AssistantObject:
+    post:
+      summary: The assistant object
+      description: |
+        Build assistants that can call models and use tools to perform tasks. <a  href = "https://platform.openai.com/docs/api-reference/assistants"> Equivalent to OpenAI's assistants object. </a>
+      operationId: AssistantObjects
+      tags:
+        - Assistants
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: 'specs/assistants.yaml#/components/schemas/AssistantObject'
   MessageObject:
     post:
       summary: The message object

docs/openapi/specs/assistants.yaml

@@ -0,0 +1,78 @@
+components:
+  schemas:
+    AssistantObject:
+      type: object
+      properties:
+        id:
+          type: string
+          description: "The identifier of the assistant."
+          example: "asst_abc123"
+        object:
+          type: string
+          description: "Type of the object, indicating it's an assistant."
+          default: "assistant"
+        version:
+          type: integer
+          description: "Version number of the assistant."
+          example: 1
+        created_at:
+          type: integer
+          format: int64
+          description: "Unix timestamp representing the creation time of the assistant."
+          example: 1698984975
+        name:
+          type: string
+          description: "Name of the assistant."
+          example: "Math Tutor"
+        description:
+          type: string
+          description: "Description of the assistant. Can be null."
+          example: null
+        avatar:
+          type: string
+          description: "URL of the assistant's avatar. Jan-specific property."
+          example: "https://pic.png"
+        models:
+          type: array
+          description: "List of models associated with the assistant. Jan-specific property."
+          items:
+            type: object
+            properties:
+              model_id:
+                type: string
+                example: model_0  
+        instructions:
+          type: string
+          description: "A system prompt for the assistant"
+          example: Be concise
+        events:
+          type: object
+          description: "Event subscription settings for the assistant."
+          properties:
+            in:
+              type: array
+              items:
+                type: string
+            out:
+              type: array
+              items:
+                type: string
+          # If there are specific event types, they can be detailed here
+        metadata:
+          type: object
+          description: "Metadata associated with the assistant."
+
+    ListAssistantsResponse:
+      type: object
+
+    CreateAssistantResponse:
+      type: object
+
+    RetrieveAssistantResponse:
+      type: object
+
+    ModifyAssistantResponse:
+      type: object
+
+    DeleteAssistantResponse:
+      type: object