You need an API key to access the Writer API. Get an API key by following the steps in the API quickstart.We recommend setting the API key as an environment variable in a
.env
file with the name WRITER_API_KEY
.Tool structure
Knowledge Graph chat is a predefined tool supported by Palmyra X4 and later models, to be used with tool calling in the chat endpoint. To use Knowledge Graph chat, add the following object to thetools
array when calling the chat endpoint:
Parameter | Type | Description |
---|---|---|
type | string | The type of tool. Must be graph for Knowledge Graph chat. |
function | object | An object containing the graph_ids , description , subqueries , and query_config parameters |
function.graph_ids | array | An array of strings containing the graph IDs you wish to reference |
function.description | string | A description of the graphs you are referencing. This helps the model understand when to use the Knowledge Graph tool in the chat. If there are multiple graphs, include a description for each, referencing the graph by name. |
function.subqueries | Boolean | A Boolean indicating whether to include the subqueries used by Palmyra in the response. |
function.query_config | object | Configuration options for Knowledge Graph queries. See the Query configuration parameters below. |
Query configuration parameters
Parameter | Type | Range | Default | Description |
---|---|---|---|---|
max_subquestions | integer | 1-10 | 6 | Maximum number of sub-questions to generate when processing complex queries. |
search_weight | integer | 0-100 | 50 | Controls the balance between keyword and semantic search in ranking results. |
grounding_level | number | 0.0-1.0 | 0.0 | Controls how closely responses must match to source material. |
max_snippets | integer | 5-25 (recommended) | 30 | Maximum number of text snippets to retrieve from the Knowledge Graph for context. Works in concert with search_weight to control best matches vs broader coverage. Note: While technically supports 1-60, values below 5 may return no results due to RAG implementation. Recommended range is 5-25. Due to RAG system behavior, you may see more snippets than requested. |
max_tokens | integer | 100-8000 | 4000 | Maximum number of tokens the model can generate in the response. |
keyword_threshold | number | 0.0-1.0 | 0.7 | Threshold for keyword-based matching when searching Knowledge Graph content. |
semantic_threshold | number | 0.0-1.0 | 0.7 | Threshold for semantic similarity matching when searching Knowledge Graph content. Set higher for stricter relevance, lower for broader range. |
inline_citations | Boolean | true/false | false | Whether to include inline citations within the response text. |
You can only pass one prebuilt tool in the
tools
array at a time. However, you can pass multiple custom tools in the same request.Prebuilt tools are:- Knowledge Graph tool
- LLM tool
- Translation tool
- Vision tool
Response format
When a chat completion uses the Knowledge Graph tool, the response from the Knowledge Graph tool is in thegraph_data
object. That object contains the following fields:
Parameter | Type | Description |
---|---|---|
sources | array | An array of objects containing the source file IDs and snippets that helped the model answer the question. |
sources.file_id | string | The ID of the source file. |
sources.snippet | string | A snippet from the source file that helped the model answer the question. |
status | string | The status of the query. |
subqueries | array | An array of objects containing the subqueries used by Palmyra in the response. |
subqueries.query | string | The query used by Palmyra to answer the question. |
subqueries.answer | string | The answer to the question. |
subqueries.sources | array | An array of objects containing the source file IDs and snippets that helped the model answer the question. |
subqueries
parameter is false
, or if the model doesn’t need subqueries to answer the question, this array is be empty.
Usage example
The following example uses a hypothetical product information Knowledge Graph to answer a question about which food products contain both food coloring and chocolate.Create the tools array
First, define thetools
array with the type
set to graph
. The function
object contains the graph_ids
, description
, and subqueries
parameters.
In this example, the subqueries are included in the response. Subqueries can be useful for debugging or for providing additional context to the user about how the model arrived at the answer.
Send the request
Add the tools array to the chat endpoint call along with your array of messages. Settingtool_choice
to auto
allows the model to choose when to use the Knowledge Graph tool, based on the user’s question and the description of the tool.
This example streams the response in real-time as the model generates it.
If you are unfamiliar with the chat completions endpoint or streaming vs. non-streaming responses, learn more in the chat completion guide.
Display Knowledge Graph subqueries and sources
You may want to display thesources
or subqueries
in your UI to assist your user in understanding how the model derived the answer to the question. The following example shows how to display the subqueries as well as the status of the query from the Knowledge Graph.
Customize query behavior
You can fine-tune how your Knowledge Graph searches and retrieves content using thequery_config
parameter. Learn about all available configuration options in the Knowledge Graph query configuration guide.