Add docs for structured outputs - tools (#262)

* add docs for structured outputs - tools * Update fern/pages/v2/text-generation/tools/tool-use.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * Update fern/pages/text-generation/structured-outputs-json.mdx Co-authored-by: Michael <[email protected]> Signed-off-by: Meor Amer <[email protected]> * updates post-review * fix markdown * change slug Signed-off-by: Michael <[email protected]> * fixes Signed-off-by: Michael <[email protected]> * Update 2024-11-25-structured-outputs-tools.mdx Signed-off-by: Michael <[email protected]> * fix links * rename files * revert url change * Update structured-outputs-json.mdx Signed-off-by: Michael <[email protected]> * update slug to remove 'JSON' * Add redirects for structured outputs pages (#269) Co-authored-by: Max Shkutnyk <[email protected]> --------- Signed-off-by: Meor Amer <[email protected]> Signed-off-by: Michael <[email protected]> Co-authored-by: Michael <[email protected]> Co-authored-by: Michael <[email protected]> Co-authored-by: Max Shkutnyk <[email protected]> Co-authored-by: Max Shkutnyk <[email protected]>
cohere-ai · Nov 29, 2024 · 169412f · 169412f
1 parent 7ebcd53
commit 169412f
Show file tree

Hide file tree

Showing 11 changed files with 360 additions and 166 deletions.
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -574,6 +574,12 @@ redirects:
   - source: /docs/usage-guidelines
     destination: /docs/usage-policy
     permanent: true
+  - source: /docs/structured-outputs-json
+    destination: /docs/structured-outputs
+    permanent: true
+  - source: /v1/docs/structured-outputs-json
+    destination: /v1/docs/structured-outputs
+    permanent: true
   - source: /v2/v2/:slug* 
     destination: /v2/:slug*
     permanent: true

diff --git a/fern/pages/changelog/2024-11-27-structured-outputs-tools.mdx b/fern/pages/changelog/2024-11-27-structured-outputs-tools.mdx
@@ -0,0 +1,16 @@
+---
+title: "Structured Outputs support for tool use"
+slug: "changelog/structured-outputs-tools"
+createdAt: "Wed Nov 27 2024"
+hidden: false
+description: >-
+  Structured Outputs now supports both JSON and tool use scenarios.
+---
+
+Today, we're pleased to announce that we have added Structured Outputs support for tool use in the Chat API.
+
+In addition to supporting Structured Outputs with JSON generation via the `response_format` parameter, Structured Outputs will be available with Tools as well via the `strict_tools` parameter.
+
+Setting `strict_tools` to `true` ensures that tool calls will follow the  provided tool schema exactly. This means the tool calls are guaranteed to adhere to the tool names, parameter names, parameter data types, and required parameters, without the risk of hallucinations.
+
+See the [Structured Outputs documentation](https://docs.cohere.com/v2/docs/structured-outputs#structured-outputs-tools) to learn more.
diff --git a/...xt-generation/structured-outputs-json.mdx → ...es/text-generation/structured-outputs.mdx b/...xt-generation/structured-outputs-json.mdx → ...es/text-generation/structured-outputs.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Structured Generations (JSON)"
-slug: "docs/structured-outputs-json"
+title: "Structured Outputs"
+slug: "docs/structured-outputs"
 
 hidden: false
 
@@ -12,15 +12,38 @@ createdAt: "Thu Jun 06 2024 05:37:56 GMT+0000 (Coordinated Universal Time)"
 updatedAt: "Tue Jun 11 2024 02:43:00 GMT+0000 (Coordinated Universal Time)"
 ---
 
-Cohere models such as [Command R](/docs/command-r) and [Command R+](/docs/command-r-plus) are great at producing structured outputs in formats such as JSON.
+## Overview
 
-## Why generate JSON Objects using an LLM?
+Structured Outputs is a feature for forcing the LLM's output to follow a specified format 100% of the time. This increases the reliability of LLM in enterprise applications where downstream applications expect the LLM output to be correctly formatted. By forcing the model to follow a structured schema, hallucinated fields and entries in structured data can be reliably eliminated.
 
-JSON is a lightweight format that is easy for humans to read and write and is also easy for machines to parse. By generating JSON objects, you can structure and organize the model's responses in a way that can be used in downstream applications. This is particularly useful when you want to extract specific information from the responses, perform data analysis, or integrate the responses into your applications seamlessly.
+Compatible models:
+- Command R 08 2024
+- Command R
+- Command R+ 08 2024
+- Command R+
 
-## How to use the `response_format` parameter
+## How to Use Structured Outputs
 
-When making an API request, you can specify the `response_format` parameter to indicate that you want the response in a JSON object format.
+There are two ways to use Structured Outputs
+- **Structured Outputs (JSON)**. This is primarily used in text generation use cases.
+- **Structured Outputs (Tools)**. This is primarily used in tool use and agents use cases via function calling.
+
+<Note title="API Compatibility"> 
+Structured Outputs with Tools are only supported in [Chat API V2](https://docs.cohere.com/reference/chat#request.body.strict_tools) via the `strict_tools` parameter. This parameter is not supported in Chat API V1.
+</Note>
+
+### Structured Outputs (JSON)
+
+Here, you can call the Chat API to generate Structured Outputs in JSON format. JSON is a lightweight format that is easy for humans to read and write and is also easy for machines to parse. 
+
+This is particularly useful in text generation use cases, for example, when you want to extract specific information from the responses, perform data analysis, or integrate the responses into your applications seamlessly.
+
+There are two ways of specifying the JSON output:
+- JSON mode
+- JSON Schema mode
+
+#### JSON mode
+In JSON mode, when making an API request, you can specify the `response_format` parameter to indicate that you want the response in a JSON object format.
 
 ```python PYTHON
 import cohere
@@ -35,22 +58,34 @@ res = co.chat(
 print(res.text)
 ```
 
-By setting the `response_format` type to `"json_object"` in the Chat API, the output of the model is guaranteed to be a valid JSON object. 
+By setting the `response_format` type to `"json_object"` in the Chat API, the output of the model is guaranteed to be a valid JSON object.
 
-<Note title="Important">
+```
+# Example response
+
+{
+  "name": "Emma Johnson",
+  "age": 32
+}
+
+```
+
+<Info title="Important"> 
 When using  `{ "type": "json_object" }` your `message` should always explicitly instruct the model to generate a JSON (eg: _"Generate a JSON ..."_) . Otherwise the model may end up getting stuck generating an infinite stream of characters and eventually run out of context length.
-</Note>
+</Info>
 
-<Note title="Note">
-This feature is currently not supported in RAG and tool use scenarios.
+<Note title="Experimental"> 
+This feature is currently not supported in RAG mode.
 </Note>
 
-## Specifying a schema (beta)
+#### JSON Schema mode
+In JSON Schema mode, you can optionally define a schema as part of the `response_format`  parameter. A [JSON Schema](https://json-schema.org/specification) is a way to describe the structure of the JSON object you want the LLM to generate. 
 
-The `response_format` parameter also allows you to define a schema for the generated JSON object. A [JSON Schema](https://json-schema.org/specification) is a way to describe the structure of the JSON object you want the LLM to generate. This is optional, but it gives you more control over the response format. 
+This forces the LLM to stick to this schema, thus giving you greater control over the output.
 
 For example, let's say you want the LLM to generate a JSON object with specific keys for a book, such as "title," "author," and "publication_year." Your API request might look like this:
 
+
 ```python PYTHON
 import cohere
 co = cohere.Client(api_key="YOUR API KEY")
@@ -77,9 +112,33 @@ print(res.text)
 
 In this schema, we defined three keys ("title," "author," "publication_year") and their expected data types ("string" and "number"). The LLM will generate a JSON object that adheres to this structure.
 
-<Note title="Important">
-Specifying a `schema` adds even more latency, proportional to the complexity of the schema. This parameter is in **beta**, and will continue seeing performance improvements.
-</Note>
+```
+# Example response
+
+{
+  "title": "The Great Gatsby",
+  "author": "F. Scott Fitzgerald",
+  "publication_year": 1925
+}
+
+```
+
+<Info title="Important"> 
+Note: Each schema provided will incur a latency overhead required for processing the schema. This is only applicable for the first few requests.
+</Info>
+
+## Specifying a schema
+
+### Generating nested objects
+
+The model can be configured to output objects with up to 5 levels of nesting. When a `schema` is specified, there are no limitations on the levels of nesting.
+
+### Schema constraints
+
+When constructing a `schema` keep the following constraints in mind:
+
+- The `type` in the top level schema must be `object`
+- Every object in the schema must have at least one `required` field specified
 
 ### Unsupported schema features
 
@@ -88,7 +147,7 @@ We do not support the entirety of the [JSON Schema specification](https://json-s
 - [Schema Composition](https://json-schema.org/understanding-json-schema/reference/combining#schema-composition) (`anyOf`, `allOf`, `oneOf` and `not`)
 - [Numeric Ranges](https://json-schema.org/understanding-json-schema/reference/numeric#range) (`maximum` and  `minimum`)
 - [Array Length Ranges](https://json-schema.org/understanding-json-schema/reference/array#length) (`minItems` and `maxItems`) 
-- String limitations: 
+- String limitations:
   - [String Length](https://json-schema.org/understanding-json-schema/reference/string#length) (`maxLength` and `minLength`)
   - The following are not supported in [Regular Expressions](https://json-schema.org/understanding-json-schema/reference/string#regexp)
     - `^`
@@ -100,3 +159,6 @@ We do not support the entirety of the [JSON Schema specification](https://json-s
     - `uuid`
     - `date`
     - `time`
+- Others:
+    - `uniqueItems`
+    - `additionalProperties`
diff --git a/fern/pages/tutorials/build-things-with-cohere/text-generation-tutorial.mdx b/fern/pages/tutorials/build-things-with-cohere/text-generation-tutorial.mdx
@@ -251,7 +251,7 @@ print(json_object)
 
 Further reading:
 
-- [Documentation on Structured Generations (JSON)](/docs/structured-outputs-json)
+- [Documentation on Structured Outputs](/docs/structured-outputs)
 
 ## Streaming responses
 

diff --git a/...es/v2/text-generation/prompt-engineering/prompt-library/book-an-appointment.mdx b/...es/v2/text-generation/prompt-engineering/prompt-library/book-an-appointment.mdx
@@ -87,4 +87,4 @@ response = co.chat(model="command-r-plus-08-2024",
 print(response.message.content[0].text)
 ````
 
-Also check out the [structured output generation feature](v2/docs/structured-outputs-json) which guarantees that output of the model will be a valid JSON object.
+Also check out the [Structured Outputs feature](v2/docs/structured-outputs) which guarantees that output of the model will be a valid JSON object.
diff --git a/fern/pages/v2/text-generation/structured-outputs-json.mdx b/fern/pages/v2/text-generation/structured-outputs-json.mdx