Skip to content

Commit 5446d6d

Browse files
guimachiavelliguimachiavelli
committed
WIP: /chats reference review
1 parent 2c11e0e commit 5446d6d

File tree

2 files changed

+224
-233
lines changed

2 files changed

+224
-233
lines changed

‎learn/ai_powered_search/chat_tooling_reference.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
title: Chat tooling reference
3+
description: An exhaustive reference of special chat tools supported by Meilisearch
4+
---
5+
6+
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.
7+
8+
<Note>
9+
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.
10+
</Note>
11+
12+
## Meilisearch chat tools
13+
14+
For the best user experience, configure all following tools.
15+
16+
2. **Handle progress updates** by displaying search status to users during streaming
17+
3. **Append conversation messages** as requested to maintain context for future requests
18+
4. **Display source documents** to users for transparency and verification
19+
5. **Use the `call_id`** to associate progress updates with their corresponding source results
20+
21+
### `_meiliSearchProgress`
22+
23+
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.
24+
25+
**Purpose**: Provides transparency about search operations and reduces perceived latency by showing users what's happening behind the scenes.
26+
27+
**Arguments**:
28+
29+
- `call_id`: Unique identifier to track the search operation
30+
- `function_name`: Name of the internal function being executed (e.g., "_meiliSearchInIndex")
31+
- `function_parameters`: JSON-encoded string containing search parameters like `q` (query) and `index_uid`
32+
33+
**Example Response**:
34+
35+
```json
36+
{
37+
"function": {
38+
"name": "_meiliSearchProgress",
39+
"arguments": "{\"call_id\":\"89939d1f-6857-477c-8ae2-838c7a504e6a\",\"function_name\":\"_meiliSearchInIndex\",\"function_parameters\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}"
40+
}
41+
}
42+
```
43+
44+
### `_meiliAppendConversationMessage`
45+
46+
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.
47+
48+
**Purpose**: Maintains conversation context for better response quality in subsequent requests by preserving tool calls and results.
49+
50+
**Arguments**:
51+
52+
- `role`: Message author role ("user" or "assistant")
53+
- `content`: Message content (for tool results)
54+
- `tool_calls`: Array of tool calls made by the assistant
55+
- `tool_call_id`: ID of the tool call this message responds to
56+
57+
**Example Response**:
58+
59+
```json
60+
{
61+
"function": {
62+
"name": "_meiliAppendConversationMessage",
63+
"arguments": "{\"role\":\"assistant\",\"tool_calls\":[{\"id\":\"call_ijAdM42bixq9lAF4SiPwkq2b\",\"type\":\"function\",\"function\":{\"name\":\"_meiliSearchInIndex\",\"arguments\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}}]}"
64+
}
65+
}
66+
```
67+
68+
### `_meiliSearchSources`
69+
70+
This tool provides the source documents that were used by the LLM to generate responses, enabling transparency and allowing users to verify information sources.
71+
72+
**Purpose**: Shows users which documents were used to generate responses, improving trust and enabling source verification.
73+
74+
**Arguments**:
75+
76+
- `call_id`: Matches the `call_id` from `_meiliSearchProgress` to associate queries with results
77+
- `documents`: JSON object containing the source documents with only displayed attributes
78+
79+
**Example Response**:
80+
81+
```json
82+
{
83+
"function": {
84+
"name": "_meiliSearchSources",
85+
"arguments": "{\"call_id\":\"abc123\",\"documents\":[{\"id\":197302,\"title\":\"The Sacred Science\",\"overview\":\"Diabetes. Prostate cancer...\",\"genres\":[\"Documentary\",\"Adventure\",\"Drama\"]}]}"
86+
}
87+
}
88+
```
89+
90+
### Sample OpenAI tool declaration
91+
92+
Include these tools in your request's `tools` array to enable enhanced functionality:
93+
94+
<CodeGroup>
95+
96+
```json
97+
{
98+
…
99+
"tools": [
100+
{
101+
"type": "function",
102+
"function": {
103+
"name": "_meiliSearchProgress",
104+
"description": "Provides information about the current Meilisearch search operation",
105+
"parameters": {
106+
"type": "object",
107+
"properties": {
108+
"call_id": {
109+
"type": "string",
110+
"description": "The call ID to track the sources of the search"
111+
},
112+
"function_name": {
113+
"type": "string",
114+
"description": "The name of the function we are executing"
115+
},
116+
"function_parameters": {
117+
"type": "string",
118+
"description": "The parameters of the function we are executing, encoded in JSON"
119+
}
120+
},
121+
"required": ["call_id", "function_name", "function_parameters"],
122+
"additionalProperties": false
123+
},
124+
"strict": true
125+
}
126+
},
127+
{
128+
"type": "function",
129+
"function": {
130+
"name": "_meiliAppendConversationMessage",
131+
"description": "Append a new message to the conversation based on what happened internally",
132+
"parameters": {
133+
"type": "object",
134+
"properties": {
135+
"role": {
136+
"type": "string",
137+
"description": "The role of the messages author, either `role` or `assistant`"
138+
},
139+
"content": {
140+
"type": "string",
141+
"description": "The contents of the `assistant` or `tool` message. Required unless `tool_calls` is specified."
142+
},
143+
"tool_calls": {
144+
"type": ["array", "null"],
145+
"description": "The tool calls generated by the model, such as function calls",
146+
"items": {
147+
"type": "object",
148+
"properties": {
149+
"function": {
150+
"type": "object",
151+
"description": "The function that the model called",
152+
"properties": {
153+
"name": {
154+
"type": "string",
155+
"description": "The name of the function to call"
156+
},
157+
"arguments": {
158+
"type": "string",
159+
"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."
160+
}
161+
}
162+
},
163+
"id": {
164+
"type": "string",
165+
"description": "The ID of the tool call"
166+
},
167+
"type": {
168+
"type": "string",
169+
"description": "The type of the tool. Currently, only function is supported"
170+
}
171+
}
172+
}
173+
},
174+
"tool_call_id": {
175+
"type": ["string", "null"],
176+
"description": "Tool call that this message is responding to"
177+
}
178+
},
179+
"required": ["role", "content", "tool_calls", "tool_call_id"],
180+
"additionalProperties": false
181+
},
182+
"strict": true
183+
}
184+
},
185+
{
186+
"type": "function",
187+
"function": {
188+
"name": "_meiliSearchSources",
189+
"description": "Provides sources of the search",
190+
"parameters": {
191+
"type": "object",
192+
"properties": {
193+
"call_id": {
194+
"type": "string",
195+
"description": "The call ID to track the original search associated to those sources"
196+
},
197+
"documents": {
198+
"type": "object",
199+
"description": "The documents associated with the search (call_id). Only the displayed attributes of the documents are returned"
200+
}
201+
},
202+
"required": ["call_id", "documents"],
203+
"additionalProperties": false
204+
},
205+
"strict": true
206+
}
207+
}
208+
]
209+
}
210+
```
211+
212+
</CodeGroup>

0 commit comments

Comments
 (0)