v1.15.1: /chat route docs review

docs.json

@@ -165,7 +165,6 @@
                 "group": "AI-powered search",
                 "pages": [
                   "learn/ai_powered_search/getting_started_with_ai_search",
-                  "learn/ai_powered_search/conversational_search_with_chat",
                   "learn/ai_powered_search/configure_rest_embedder",
                   "learn/ai_powered_search/document_template_best_practices",
                   "learn/ai_powered_search/image_search_with_user_provided_embeddings",
@@ -175,6 +174,14 @@
                   "learn/ai_powered_search/difference_full_text_ai_search"
                 ]
               },
+              {
+                "group": "Conversational search",
+                "pages": [
+                  "learn/chat/getting_started_with_chat",
+                  "learn/chat/chat_tooling_reference",
+                  "learn/chat/conversational_search"
+                ]
+              },
               {
                 "group": "Self-hosted",
                 "pages": [
@@ -945,6 +952,14 @@
     {
       "source": "/guides/deployment/gcp",
       "destination": "/guides/running_production"
+    },
+    {
+      "source": "/guides/ai/getting_started_with_chat",
+      "destination": "/learn/chat/getting_started_with_chat"
+    },
+    {
+      "source": "learn/ai_powered_search/conversational_search_with_chat",
+      "destination": "learn/chat/conversational_search"
     }
   ]
 }

learn/chat/chat_tooling_reference.md

@@ -0,0 +1,225 @@
+---
+title: Chat tooling reference
+description: An exhaustive reference of special chat tools supported by Meilisearch
+---
+
+When creating your conversational search agent, you may be able to extend the model's capabilities with a number of tools. This page lists Meilisearch-specific tools that may improve user experience.
+
+<Note>
+This is an experimental feature. Use the Meilisearch Cloud UI or the experimental features endpoint to activate it:
+
+```sh
+curl \
+  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "chatCompletions": true
+  }'
+```
+</Note>
+
+## Meilisearch chat tools
+
+For the best user experience, configure all following tools.
+
+1. **Handle progress updates** by displaying search status to users during streaming
+2. **Append conversation messages** as requested to maintain context for future requests
+3. **Display source documents** to users for transparency and verification
+4. **Use `call_id`** to associate progress updates with their corresponding source results
+
+<Note>
+These special tools are handled internally by Meilisearch and are not forwarded to the LLM provider. They serve as a communication mechanism between Meilisearch and your application to provide enhanced user experience features.
+</Note>
+
+### `_meiliSearchProgress`
+
+This tool reports real-time progress of internal search operations. When declared, Meilisearch will call this function whenever search operations are performed in the background.
+
+**Purpose**: Provides transparency about search operations and reduces perceived latency by showing users what's happening behind the scenes.
+
+**Arguments**:
+
+- `call_id`: Unique identifier to track the search operation
+- `function_name`: Name of the internal function being executed (e.g., "_meiliSearchInIndex")
+- `function_parameters`: JSON-encoded string containing search parameters like `q` (query) and `index_uid`
+
+**Example Response**:
+
+```json
+{
+  "function": {
+    "name": "_meiliSearchProgress",
+    "arguments": "{\"call_id\":\"89939d1f-6857-477c-8ae2-838c7a504e6a\",\"function_name\":\"_meiliSearchInIndex\",\"function_parameters\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}"
+  }
+}
+```
+
+### `_meiliAppendConversationMessage`
+
+Since the `/chats/{workspace}/chat/completions` endpoint is stateless, this tool helps maintain conversation context by requesting the client to append internal messages to the conversation history.
+
+**Purpose**: Maintains conversation context for better response quality in subsequent requests by preserving tool calls and results.
+
+**Arguments**:
+
+- `role`: Message author role ("user" or "assistant")
+- `content`: Message content (for tool results)
+- `tool_calls`: Array of tool calls made by the assistant
+- `tool_call_id`: ID of the tool call this message responds to
+
+**Example Response**:
+
+```json
+{
+  "function": {
+    "name": "_meiliAppendConversationMessage",
+    "arguments": "{\"role\":\"assistant\",\"tool_calls\":[{\"id\":\"call_ijAdM42bixq9lAF4SiPwkq2b\",\"type\":\"function\",\"function\":{\"name\":\"_meiliSearchInIndex\",\"arguments\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}}]}"
+  }
+}
+```
+
+### `_meiliSearchSources`
+
+This tool provides the source documents that were used by the LLM to generate responses, enabling transparency and allowing users to verify information sources.
+
+**Purpose**: Shows users which documents were used to generate responses, improving trust and enabling source verification.
+
+**Arguments**:
+
+- `call_id`: Matches the `call_id` from `_meiliSearchProgress` to associate queries with results
+- `documents`: JSON object containing the source documents with only displayed attributes
+
+**Example Response**:
+
+```json
+{
+  "function": {
+    "name": "_meiliSearchSources",
+    "arguments": "{\"call_id\":\"abc123\",\"documents\":[{\"id\":197302,\"title\":\"The Sacred Science\",\"overview\":\"Diabetes. Prostate cancer...\",\"genres\":[\"Documentary\",\"Adventure\",\"Drama\"]}]}"
+  }
+}
+```
+
+### Sample OpenAI tool declaration
+
+Include these tools in your request's `tools` array to enable enhanced functionality:
+
+<CodeGroup>
+
+```json
+{
+  …
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "_meiliSearchProgress",
+        "description": "Provides information about the current Meilisearch search operation",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "call_id": {
+              "type": "string",
+              "description": "The call ID to track the sources of the search"
+            },
+            "function_name": {
+              "type": "string",
+              "description": "The name of the function we are executing"
+            },
+            "function_parameters": {
+              "type": "string",
+              "description": "The parameters of the function we are executing, encoded in JSON"
+            }
+          },
+          "required": ["call_id", "function_name", "function_parameters"],
+          "additionalProperties": false
+        },
+        "strict": true
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "_meiliAppendConversationMessage",
+        "description": "Append a new message to the conversation based on what happened internally",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "role": {
+              "type": "string",
+              "description": "The role of the messages author, either `role` or `assistant`"
+            },
+            "content": {
+              "type": "string",
+              "description": "The contents of the `assistant` or `tool` message. Required unless `tool_calls` is specified."
+            },
+            "tool_calls": {
+              "type": ["array", "null"],
+              "description": "The tool calls generated by the model, such as function calls",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "function": {
+                    "type": "object",
+                    "description": "The function that the model called",
+                    "properties": {
+                      "name": {
+                        "type": "string",
+                        "description": "The name of the function to call"
+                      },
+                      "arguments": {
+                        "type": "string",
+                        "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function."
+                      }
+                    }
+                  },
+                  "id": {
+                    "type": "string",
+                    "description": "The ID of the tool call"
+                  },
+                  "type": {
+                    "type": "string",
+                    "description": "The type of the tool. Currently, only function is supported"
+                  }
+                }
+              }
+            },
+            "tool_call_id": {
+              "type": ["string", "null"],
+              "description": "Tool call that this message is responding to"
+            }
+          },
+          "required": ["role", "content", "tool_calls", "tool_call_id"],
+          "additionalProperties": false
+        },
+        "strict": true
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "_meiliSearchSources",
+        "description": "Provides sources of the search",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "call_id": {
+              "type": "string",
+              "description": "The call ID to track the original search associated to those sources"
+            },
+            "documents": {
+              "type": "object",
+              "description": "The documents associated with the search (call_id). Only the displayed attributes of the documents are returned"
+            }
+          },
+          "required": ["call_id", "documents"],
+          "additionalProperties": false
+        },
+        "strict": true
+      }
+    }
+  ]
+}
+```
+
+</CodeGroup>

learn/ai_powered_search/conversational_search_with_chat.mdx → learn/chat/conversational_search.mdx

@@ -1,18 +1,28 @@
 ---
-title: Conversational search with chat
+title: Conversational search
 sidebarTitle: Conversational search
 description: Learn how to implement AI-powered conversational search using Meilisearch's chat feature
 ---
 
 Meilisearch's chat completions feature enables AI-powered conversational search, allowing users to ask questions in natural language and receive direct answers based on your indexed content. This feature transforms the traditional search experience into an interactive dialogue.
 
-<Warning>
-The chat completions feature is experimental and must be enabled through [experimental features](/reference/api/experimental_features). API specifications may change in future releases.
-</Warning>
+<Note>
+This is an experimental feature. Use the Meilisearch Cloud UI or the experimental features endpoint to activate it:
+
+```sh
+curl \
+  -X PATCH 'MEILISEARCH_URL/experimental-features/' \
+  -H 'Content-Type: application/json' \
+  --data-binary '{
+    "chatCompletions": true
+  }'
+```
+</Note>
 
 ## What is conversational search?
 
-Conversational search allows users to:
+Conversational search interfaces allow users to:
+
 - Ask questions in natural language instead of using keywords
 - Receive direct answers rather than just document links
 - Maintain context across multiple questions
@@ -23,53 +33,50 @@ This approach bridges the gap between traditional search and modern AI experienc
 ## How chat completions differs from traditional search
 
 ### Traditional search workflow
+
 1. User enters keywords
 2. Meilisearch returns matching documents
 3. User reviews results to find answers
 
 ### Conversational search workflow
+
 1. User asks a question in natural language
 2. Meilisearch retrieves relevant documents
 3. AI generates a direct answer based on those documents
 4. User can ask follow-up questions
 
-## RAG implementation simplified
-
-The chat completions feature implements a complete Retrieval Augmented Generation (RAG) pipeline in a single API endpoint. Traditional RAG implementations require:
-
-- Multiple LLM calls for query optimization
-- Separate vector database for semantic search
-- Custom reranking solutions
-- Complex pipeline management
-
-Meilisearch's chat completions consolidates these into one streamlined process:
-
-1. **Query understanding**: Automatically transforms questions into optimal search parameters
-2. **Hybrid retrieval**: Combines keyword and semantic search for superior relevance
-3. **Answer generation**: Uses your chosen LLM to generate responses
-4. **Context management**: Maintains conversation history automatically
-
 ## When to use chat completions vs traditional search
 
 ### Use conversational search when:
+
 - Users need direct answers to specific questions
 - Content is informational (documentation, knowledge bases, FAQs)
 - Users benefit from follow-up questions
 - Natural language interaction improves user experience
 
 ### Use traditional search when:
+
 - Users need to browse multiple options
 - Results require comparison (e-commerce products, listings)
 - Exact matching is critical
 - Response time is paramount
 
-## Alternative: Model Context Protocol integration
+## Use chat completions to implement RAG pipelines
+
+The chat completions feature implements a complete Retrieval Augmented Generation (RAG) pipeline in a single API endpoint. Meilisearch's chat completions consolidates RAG creation into one streamlined process:
+
+1. **Query understanding**: automatically transforms questions into search parameters
+2. **Hybrid retrieval**: combines keyword and semantic search for better relevancy
+3. **Answer generation**: uses your chosen LLM to generate responses
+4. **Context management**: maintains conversation history by constantly pushing the full conversation to the dedicated tool
+
+### Alternative: MCP integration
 
 When integrating Meilisearch with AI assistants and automation tools, consider using [Meilisearch's Model Context Protocol (MCP) server](/guides/ai/mcp). MCP enables standardized tool integration across various AI platforms and applications.
 
 ## Architecture overview
 
-The chat completions feature operates through workspaces, which are isolated configurations for different use cases or tenants. Each workspace can:
+Chat completions operate through workspaces, which are isolated configurations for different use cases. Each workspace can:
 
 - Use different LLM sources (openAi, azureOpenAi, mistral, gemini, vLlm)
 - Apply custom prompts
@@ -97,13 +104,12 @@ The chat completions feature operates through workspaces, which are isolated con
 
 The chat completions feature integrates with Meilisearch's existing security model:
 
-- **API key permissions**: Chat only accesses indexes visible to the provided API key
-- **Tenant tokens**: Support for multi-tenant applications
-- **LLM credentials**: Stored securely in workspace settings
-- **Content isolation**: Responses based only on indexed content
+- **API key permissions**: chat only accesses indexes visible to the provided API key
+- **Tenant tokens**: support for multi-tenant applications
+- **LLM credentials**: stored securely in workspace settings
+- **Content isolation**: responses based only on indexed content
 
 ## Next steps
 
-- [Get started with chat completions implementation](/guides/ai/getting_started_with_chat)
+- [Get started with chat completions implementation](/learn/chat/getting_started_with_chat)
 - [Explore the chat completions API reference](/reference/api/chats)
-- [Learn about experimental features](/reference/api/experimental_features)