From 53bbfc5bce13ee0fe43da553c7511cdb090b5bed Mon Sep 17 00:00:00 2001
From: 0xSage <n@pragmatic.vc>
Date: Fri, 24 Nov 2023 16:55:15 +0800
Subject: [PATCH] docs: chats

---
 docs/docs/specs/chats.md    | 26 ++++++++++++++++++++------
 docs/docs/specs/messages.md |  2 +-
 docs/docs/specs/models.md   |  2 +-
 docs/docs/specs/threads.md  |  2 +-
 4 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/docs/docs/specs/chats.md b/docs/docs/specs/chats.md
index c6e9c1681..c119cc45d 100644
--- a/docs/docs/specs/chats.md
+++ b/docs/docs/specs/chats.md
@@ -2,15 +2,29 @@
 title: Chats
 ---
 
-:::warning
+:::caution
 
-This page is still under construction, and should be read as a scratchpad
+This is currently under development.
 
 :::
 
-Chats are essentially inference requests to a model
+## Overview
 
-> OpenAI Equivalent: https://platform.openai.com/docs/api-reference/chat
+In Jan, `chats` are LLM responses in the form of OpenAI compatible `chat completion objects`.
 
-- This should reference Nitro ChatCompletion API page to reduce duplication. 
-- We are fine with adding Jan API for this but it makes sense to use Nitro as reference as Nitro is default inference engine for Jan in this release
\ No newline at end of file
+- Models take a list of messages and return a model-generated response as output.
+- An [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) compatible endpoint at `localhost:3000/v1/chats`.
+
+## Folder Structure
+
+Chats are stateless, thus are not saved in `janroot`. Any content and relevant metadata from calling this endpoint is extracted and persisted through [Messages](/specs/messages).
+
+## API Reference
+
+Jan's Chat API is compatible with [OpenAI's Chat API](https://platform.openai.com/docs/api-reference/chat).
+
+See [Jan Chat API](https://jan.ai/api-reference/#tag/Chat-Completion)
+
+## Implementation
+
+Under the hood, the `/chat` endpoint simply reroutes an existing endpoint from [Nitro server](https://nitro.jan.ai). Nitro is a lightweight & local inference server, written in C++ and embedded into the Jan app. See [Nitro documentation](https://nitro.jan.ai/docs).
diff --git a/docs/docs/specs/messages.md b/docs/docs/specs/messages.md
index 07d4f08a8..ba3158cdf 100644
--- a/docs/docs/specs/messages.md
+++ b/docs/docs/specs/messages.md
@@ -86,4 +86,4 @@ Here's an example `message` response from an assistant.
 
 Jan's `messages` API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally.
 
-See [Jan Messages API](https://jan.ai/api-reference#tag/Messages)
+See [Jan Messages API](https://jan.ai/api-reference#tag/Messages).
diff --git a/docs/docs/specs/models.md b/docs/docs/specs/models.md
index ceb6b7cf0..d396c10d1 100644
--- a/docs/docs/specs/models.md
+++ b/docs/docs/specs/models.md
@@ -86,7 +86,7 @@ Here's a standard example `model.json` for a GGUF model.
 
 Jan's Model API is compatible with [OpenAI's Models API](https://platform.openai.com/docs/api-reference/models), with additional methods for managing and running models locally.
 
-See [Jan Models API](https://jan.ai/api-reference#tag/Models)
+See [Jan Models API](https://jan.ai/api-reference#tag/Models).
 
 ## Importing Models
 
diff --git a/docs/docs/specs/threads.md b/docs/docs/specs/threads.md
index 44253b21c..b75afd84b 100644
--- a/docs/docs/specs/threads.md
+++ b/docs/docs/specs/threads.md
@@ -62,4 +62,4 @@ Here's a standard example `thread.json` for a conversation between the user and
 
 Jan's Threads API is compatible with [OpenAI's Threads API](https://platform.openai.com/docs/api-reference/threads), with additional methods for managing threads locally.
 
-See [Jan Threads API](https://jan.ai/api-reference#tag/Threads)
+See [Jan Threads API](https://jan.ai/api-reference#tag/Threads).