From 14f733fe7a1757c8c5062f9337dd59c19e4fd08e Mon Sep 17 00:00:00 2001 From: trentfowlercohere <141260477+trentfowlercohere@users.noreply.github.com> Date: Tue, 26 Nov 2024 08:17:41 -0700 Subject: [PATCH 01/10] Bad slug, missing link. (#265) Co-authored-by: Trent Fowler --- fern/pages/models/aya.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/fern/pages/models/aya.mdx b/fern/pages/models/aya.mdx index f529be3e..5a98186c 100644 --- a/fern/pages/models/aya.mdx +++ b/fern/pages/models/aya.mdx @@ -1,6 +1,6 @@ --- title: Aya Family of Models -slug: aya/tools +slug: "docs/aya" hidden: false description: >- Understand Cohere for AI's groundbreaking multilingual Aya models, which aim to bring many more languages into generative AI. @@ -66,7 +66,7 @@ Espero que esta historia te sea útil para ilustrar vocabulario sencillo en espa Finally, you can directly download the raw models for research purposes because Cohere For AI has released [Aya Expanse 8B](https://huggingface.co/CohereForAI/aya-expanse-8b) and [Aya Expanse 32B](https://huggingface.co/CohereForAI/aya-expanse-32b) as open-weight models, through HuggingFace. What’s more, the massively multilingual instruction data used for development of these models has been [made available](https://huggingface.co/datasets/CohereForAI/aya_collection) for download as well. ## Find More -We hope you’ve found this as fascinating as we do! If you want to see more substantial projects you can check out these notebooks (source): +We hope you’ve found this as fascinating as we do! If you want to see more substantial projects you can check out these notebooks ([source](https://huggingface.co/CohereForAI/aya-expanse-32b)): - [Multilingual Writing Assistant](https://colab.research.google.com/drive/1SRLWQ0HdYN_NbRMVVUHTDXb-LSMZWF60) - [AyaMCooking](https://colab.research.google.com/drive/1-cnn4LXYoZ4ARBpnsjQM3sU7egOL_fLB?usp=sharing) From affc0c4a127244fb5158e25683ece14a0053376e Mon Sep 17 00:00:00 2001 From: Max Shkutnyk Date: Tue, 26 Nov 2024 18:05:55 +0200 Subject: [PATCH 02/10] Add python code samples check (#258) * Add script to check code snipepts format * update action name * add broken code snippet for testing * clean up * Switch to using poetry * Test pipeline fails * Test pipeline not fails on correct change * Test pipeline not fails on correct change * cleaup * cleaup * Update step to install poetry in pipeline --------- Co-authored-by: Max Shkutnyk --- .github/scripts/check_python_code_snippets.py | 86 +++++++++++++++ .../workflows/check-python-code-snippets.yml | 39 +++++++ poetry.lock | 100 +++++++++++++++++- pyproject.toml | 1 + 4 files changed, 224 insertions(+), 2 deletions(-) create mode 100755 .github/scripts/check_python_code_snippets.py create mode 100644 .github/workflows/check-python-code-snippets.yml diff --git a/.github/scripts/check_python_code_snippets.py b/.github/scripts/check_python_code_snippets.py new file mode 100755 index 00000000..ecd519bc --- /dev/null +++ b/.github/scripts/check_python_code_snippets.py @@ -0,0 +1,86 @@ +import os +import re +from pathlib import Path +import black + +DEFAULT_LINE_LENGTH = 70 +BASE_DIR = Path(__file__).resolve().parent +MDX_DIR = BASE_DIR / "../../fern/pages" +FILE_PATTERN = re.compile(r"\.mdx$") + + +def find_files_by_pattern(directory, pattern): + """ + Finds all files in the given directory that match the provided regex pattern. + """ + directory = Path(directory).resolve() + if not directory.is_dir(): + raise ValueError(f"Provided directory {directory} is not valid.") + return [f for f in directory.rglob('*') if f.is_file() and pattern.search(f.name)] + + +def format_python_snippets_in_mdx(file_path, line_length=DEFAULT_LINE_LENGTH): + """ + Formats Python code snippets inside MDX files using Black. + """ + black_mode = black.FileMode(line_length=line_length) + code_block_pattern = re.compile(r"```python\n(.*?)\n```", re.DOTALL) + + with open(file_path, 'r', encoding='utf-8') as file: + original_content = file.read() + + def format_with_black(match): + code = match.group(1) + formatted_code = black.format_str(code, mode=black_mode) + return f"```python\n{formatted_code.strip()}\n```" + + new_content = code_block_pattern.sub(format_with_black, original_content) + + with open(file_path, 'w', encoding='utf-8') as file: + file.write(new_content) + + return original_content, new_content + + +def process_mdx_files(directory, file_pattern, line_length=DEFAULT_LINE_LENGTH, check_changes=False): + """ + Processes all MDX files in the directory, formatting Python code snippets. + + Args: + directory (Path or str): Path to the directory containing MDX files. + file_pattern (re.Pattern): Regex pattern to match MDX files. + line_length (int): Line length to use for Black formatting. + check_changes (bool): If True, raises an exception if changes are detected. + """ + matching_files = find_files_by_pattern(directory, file_pattern) + files_changed = [] + + for file_path in matching_files: + original_content, new_content = format_python_snippets_in_mdx(file_path, line_length) + + if original_content != new_content: + files_changed.append(file_path) + + if check_changes and files_changed: + raise RuntimeError( + f"The following files were modified during the run:\n" + + "\n".join(str(file) for file in files_changed) + ) + + +if __name__ == "__main__": + import sys + + path = sys.argv[1] if len(sys.argv) > 1 else MDX_DIR + line_length = int(sys.argv[2]) if len(sys.argv) > 2 else DEFAULT_LINE_LENGTH + check_changes = os.getenv("CI") == "true" # Set to True in CI pipeline + + if Path(path).is_dir(): + process_mdx_files(path, FILE_PATTERN, line_length, check_changes) + elif Path(path).is_file(): + if FILE_PATTERN.search(path): + process_mdx_files(Path(path).parent, FILE_PATTERN, line_length, check_changes) + else: + print("The specified file does not match the MDX pattern.") + else: + print("Provided path is not valid.") diff --git a/.github/workflows/check-python-code-snippets.yml b/.github/workflows/check-python-code-snippets.yml new file mode 100644 index 00000000..d02620dc --- /dev/null +++ b/.github/workflows/check-python-code-snippets.yml @@ -0,0 +1,39 @@ +name: check-python-code-snippets + +on: + pull_request: + branches: + - main + paths: + - 'fern/pages/**/*.mdx' + - 'fern/pages/**/**/*.mdx' + +jobs: + run: + runs-on: ubuntu-latest + permissions: write-all + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.11' + + - name: Install Poetry + shell: bash + run: | + pipx install poetry + + - name: Install Project Dependencies with Poetry + shell: bash + run: | + poetry install + + - name: Run Python MDX Snippet Formatter + shell: bash + env: + CI: true + run: poetry run python .github/scripts/check_python_code_snippets.py fern/pages diff --git a/poetry.lock b/poetry.lock index c1215525..48492ac1 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 1.6.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.8.4 and should not be changed by hand. [[package]] name = "annotated-types" @@ -31,6 +31,50 @@ doc = ["Sphinx (>=7.4,<8.0)", "packaging", "sphinx-autodoc-typehints (>=1.2.0)", test = ["anyio[trio]", "coverage[toml] (>=7)", "exceptiongroup (>=1.2.0)", "hypothesis (>=4.0)", "psutil (>=5.9)", "pytest (>=7.0)", "pytest-mock (>=3.6.1)", "trustme", "truststore (>=0.9.1)", "uvloop (>=0.21.0b1)"] trio = ["trio (>=0.26.1)"] +[[package]] +name = "black" +version = "24.10.0" +description = "The uncompromising code formatter." +optional = false +python-versions = ">=3.9" +files = [ + {file = "black-24.10.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e6668650ea4b685440857138e5fe40cde4d652633b1bdffc62933d0db4ed9812"}, + {file = "black-24.10.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:1c536fcf674217e87b8cc3657b81809d3c085d7bf3ef262ead700da345bfa6ea"}, + {file = "black-24.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:649fff99a20bd06c6f727d2a27f401331dc0cc861fb69cde910fe95b01b5928f"}, + {file = "black-24.10.0-cp310-cp310-win_amd64.whl", hash = "sha256:fe4d6476887de70546212c99ac9bd803d90b42fc4767f058a0baa895013fbb3e"}, + {file = "black-24.10.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:5a2221696a8224e335c28816a9d331a6c2ae15a2ee34ec857dcf3e45dbfa99ad"}, + {file = "black-24.10.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:f9da3333530dbcecc1be13e69c250ed8dfa67f43c4005fb537bb426e19200d50"}, + {file = "black-24.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4007b1393d902b48b36958a216c20c4482f601569d19ed1df294a496eb366392"}, + {file = "black-24.10.0-cp311-cp311-win_amd64.whl", hash = "sha256:394d4ddc64782e51153eadcaaca95144ac4c35e27ef9b0a42e121ae7e57a9175"}, + {file = "black-24.10.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b5e39e0fae001df40f95bd8cc36b9165c5e2ea88900167bddf258bacef9bbdc3"}, + {file = "black-24.10.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d37d422772111794b26757c5b55a3eade028aa3fde43121ab7b673d050949d65"}, + {file = "black-24.10.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:14b3502784f09ce2443830e3133dacf2c0110d45191ed470ecb04d0f5f6fcb0f"}, + {file = "black-24.10.0-cp312-cp312-win_amd64.whl", hash = "sha256:30d2c30dc5139211dda799758559d1b049f7f14c580c409d6ad925b74a4208a8"}, + {file = "black-24.10.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:1cbacacb19e922a1d75ef2b6ccaefcd6e93a2c05ede32f06a21386a04cedb981"}, + {file = "black-24.10.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:1f93102e0c5bb3907451063e08b9876dbeac810e7da5a8bfb7aeb5a9ef89066b"}, + {file = "black-24.10.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ddacb691cdcdf77b96f549cf9591701d8db36b2f19519373d60d31746068dbf2"}, + {file = "black-24.10.0-cp313-cp313-win_amd64.whl", hash = "sha256:680359d932801c76d2e9c9068d05c6b107f2584b2a5b88831c83962eb9984c1b"}, + {file = "black-24.10.0-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:17374989640fbca88b6a448129cd1745c5eb8d9547b464f281b251dd00155ccd"}, + {file = "black-24.10.0-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:63f626344343083322233f175aaf372d326de8436f5928c042639a4afbbf1d3f"}, + {file = "black-24.10.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ccfa1d0cb6200857f1923b602f978386a3a2758a65b52e0950299ea014be6800"}, + {file = "black-24.10.0-cp39-cp39-win_amd64.whl", hash = "sha256:2cd9c95431d94adc56600710f8813ee27eea544dd118d45896bb734e9d7a0dc7"}, + {file = "black-24.10.0-py3-none-any.whl", hash = "sha256:3bb2b7a1f7b685f85b11fed1ef10f8a9148bceb49853e47a294a3dd963c1dd7d"}, + {file = "black-24.10.0.tar.gz", hash = "sha256:846ea64c97afe3bc677b761787993be4991810ecc7a4a937816dd6bddedc4875"}, +] + +[package.dependencies] +click = ">=8.0.0" +mypy-extensions = ">=0.4.3" +packaging = ">=22.0" +pathspec = ">=0.9.0" +platformdirs = ">=2" + +[package.extras] +colorama = ["colorama (>=0.4.3)"] +d = ["aiohttp (>=3.10)"] +jupyter = ["ipython (>=7.8.0)", "tokenize-rt (>=3.2.0)"] +uvloop = ["uvloop (>=0.15.2)"] + [[package]] name = "certifi" version = "2024.8.30" @@ -156,6 +200,20 @@ files = [ {file = "charset_normalizer-3.4.0.tar.gz", hash = "sha256:223217c3d4f82c3ac5e29032b3f1c2eb0fb591b72161f86d93f5719079dae93e"}, ] +[[package]] +name = "click" +version = "8.1.7" +description = "Composable command line interface toolkit" +optional = false +python-versions = ">=3.7" +files = [ + {file = "click-8.1.7-py3-none-any.whl", hash = "sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28"}, + {file = "click-8.1.7.tar.gz", hash = "sha256:ca9853ad459e787e2192211578cc907e7594e294c7ccc834310722b41b9ca6de"}, +] + +[package.dependencies] +colorama = {version = "*", markers = "platform_system == \"Windows\""} + [[package]] name = "cohere" version = "5.11.1" @@ -410,6 +468,17 @@ files = [ [package.extras] all = ["flake8 (>=7.1.1)", "mypy (>=1.11.2)", "pytest (>=8.3.2)", "ruff (>=0.6.2)"] +[[package]] +name = "mypy-extensions" +version = "1.0.0" +description = "Type system extensions for programs checked with the mypy type checker." +optional = false +python-versions = ">=3.5" +files = [ + {file = "mypy_extensions-1.0.0-py3-none-any.whl", hash = "sha256:4392f6c0eb8a5668a69e23d168ffa70f0be9ccfd32b5cc2d26a34ae5b844552d"}, + {file = "mypy_extensions-1.0.0.tar.gz", hash = "sha256:75dbf8955dc00442a438fc4d0666508a9a97b6bd41aa2f0ffe9d2f2725af0782"}, +] + [[package]] name = "packaging" version = "24.1" @@ -435,6 +504,33 @@ files = [ [package.extras] dev = ["jinja2"] +[[package]] +name = "pathspec" +version = "0.12.1" +description = "Utility library for gitignore style pattern matching of file paths." +optional = false +python-versions = ">=3.8" +files = [ + {file = "pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08"}, + {file = "pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712"}, +] + +[[package]] +name = "platformdirs" +version = "4.3.6" +description = "A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`." +optional = false +python-versions = ">=3.8" +files = [ + {file = "platformdirs-4.3.6-py3-none-any.whl", hash = "sha256:73e575e1408ab8103900836b97580d5307456908a03e92031bab39e4554cc3fb"}, + {file = "platformdirs-4.3.6.tar.gz", hash = "sha256:357fb2acbc885b0419afd3ce3ed34564c13c9b95c89360cd9563f73aa5e2b907"}, +] + +[package.extras] +docs = ["furo (>=2024.8.6)", "proselint (>=0.14)", "sphinx (>=8.0.2)", "sphinx-autodoc-typehints (>=2.4)"] +test = ["appdirs (==1.4.4)", "covdefaults (>=2.3)", "pytest (>=8.3.2)", "pytest-cov (>=5)", "pytest-mock (>=3.14)"] +type = ["mypy (>=1.11.2)"] + [[package]] name = "pydantic" version = "2.9.2" @@ -835,4 +931,4 @@ zstd = ["zstandard (>=0.18.0)"] [metadata] lock-version = "2.0" python-versions = "^3.11" -content-hash = "22bcef10734d2ef9157537b9c3d2a6c2d00bfb46de0e7f537d970aa4c38d6951" +content-hash = "9f3e32193f943b04cabbcb26f2412fffadea02a184bdcee11907d419da4ce40e" diff --git a/pyproject.toml b/pyproject.toml index 1d95e93d..99b75d3a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,6 +8,7 @@ readme = "README.md" [tool.poetry.dependencies] python = "^3.11" cohere = "^5.11.1" +black = "^24.10.0" [build-system] From eb807b26f28a828622951752eda8a7939cb56dca Mon Sep 17 00:00:00 2001 From: platform-endpoints Date: Wed, 27 Nov 2024 00:17:38 +0000 Subject: [PATCH 03/10] Add spec changes Co-authored-by: Abdullah Elkady --- cohere-openapi.yaml | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/cohere-openapi.yaml b/cohere-openapi.yaml index c900a77f..1c1c5b79 100644 --- a/cohere-openapi.yaml +++ b/cohere-openapi.yaml @@ -5962,6 +5962,15 @@ paths: A list of available tools (functions) that the model may suggest invoking before producing a text response. When `tools` is passed (without `tool_results`), the `text` content in the response will be empty and the `tool_calls` field in the response will be populated with a list of tool calls that need to be made. If no calls need to be made, the `tool_calls` array will be empty. + strict_tools: + x-fern-audiences: + - public + x-fern-availability: beta + type: boolean + description: | + When set to `true`, tool calls in the Assistant message will be forced to follow the tool definition strictly. Learn more in the [Strict Tools guide](https://docs.cohere.com/docs/structured-outputs-json#structured-outputs-tools). + + **Note**: The first few requests with a new set of tools will take longer to process. documents: type: array items: @@ -6037,7 +6046,7 @@ paths: minimum: 0 maximum: 500 description: | - Ensures that only the top `k` most likely tokens are considered for generation at each step. When `k` is set to `0`, k-sampling is disabled. + Ensures that only the top `k` most likely tokens are considered for generation at each step. When `k` is set to `0`, k-sampling is disabled. Defaults to `0`, min value of `0`, max value of `500`. p: type: number From 7fec48635af6062d0883731ca9b4e5ceeb67c3a4 Mon Sep 17 00:00:00 2001 From: platform-endpoints Date: Wed, 27 Nov 2024 14:15:18 +0000 Subject: [PATCH 04/10] Add spec changes Co-authored-by: billytrend-cohere <144115527+billytrend-cohere@users.noreply.github.com> --- cohere-openapi.yaml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/cohere-openapi.yaml b/cohere-openapi.yaml index 1c1c5b79..646bc4ea 100644 --- a/cohere-openapi.yaml +++ b/cohere-openapi.yaml @@ -5946,6 +5946,8 @@ paths: - model properties: model: + x-fern-audiences: + - public type: string description: The name of a compatible [Cohere model](https://docs.cohere.com/v2/docs/models) (such as @@ -5953,8 +5955,12 @@ paths: [fine-tuned](https://docs.cohere.com/v2/docs/chat-fine-tuning) model. messages: + x-fern-audiences: + - public $ref: "#/components/schemas/ChatMessages" tools: + x-fern-audiences: + - public type: array items: $ref: "#/components/schemas/ToolV2" @@ -5972,6 +5978,8 @@ paths: **Note**: The first few requests with a new set of tools will take longer to process. documents: + x-fern-audiences: + - public type: array items: oneOf: @@ -5980,10 +5988,16 @@ paths: description: | A list of relevant documents that the model can cite to generate a more accurate reply. Each document is either a string or document object with content and metadata. citation_options: + x-fern-audiences: + - public $ref: "#/components/schemas/CitationOptions" response_format: + x-fern-audiences: + - public $ref: "#/components/schemas/ResponseFormatV2" safety_mode: + x-fern-audiences: + - public enum: - CONTEXTUAL - STRICT @@ -5996,18 +6010,24 @@ paths: **Note**: This parameter is only compatible with models [Command R 08-2024](https://docs.cohere.com/v2/docs/command-r#august-2024-release), [Command R+ 08-2024](https://docs.cohere.com/v2/docs/command-r-plus#august-2024-release) and newer. max_tokens: + x-fern-audiences: + - public type: integer description: | The maximum number of tokens the model will generate as part of the response. **Note**: Setting a low value may result in incomplete generations. stop_sequences: + x-fern-audiences: + - public type: array items: type: string description: | A list of up to 5 strings that the model will use to stop generation. If the model generates a string that matches any of the strings in the list, it will stop generating tokens and return the generated text up to that point not including the stop sequence. temperature: + x-fern-audiences: + - public type: number format: float minimum: 0 @@ -6019,6 +6039,8 @@ paths: Randomness can be further maximized by increasing the value of the `p` parameter. seed: + x-fern-audiences: + - public type: integer minimum: 0 maximum: 18446744073709552000 @@ -6028,18 +6050,24 @@ paths: seed and parameters should return the same result. However, determinism cannot be totally guaranteed. frequency_penalty: + x-fern-audiences: + - public type: number format: float description: | Defaults to `0.0`, min value of `0.0`, max value of `1.0`. Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation. presence_penalty: + x-fern-audiences: + - public type: number format: float description: | Defaults to `0.0`, min value of `0.0`, max value of `1.0`. Used to reduce repetitiveness of generated tokens. Similar to `frequency_penalty`, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies. k: + x-fern-audiences: + - public type: number format: float default: 0 @@ -6049,6 +6077,8 @@ paths: Ensures that only the top `k` most likely tokens are considered for generation at each step. When `k` is set to `0`, k-sampling is disabled. Defaults to `0`, min value of `0`, max value of `500`. p: + x-fern-audiences: + - public type: number format: float default: 0.75 @@ -6058,6 +6088,8 @@ paths: Ensures that only the most likely tokens, with total probability mass of `p`, are considered for generation at each step. If both `k` and `p` are enabled, `p` acts after `k`. Defaults to `0.75`. min value of `0.01`, max value of `0.99`. logprobs: + x-fern-audiences: + - public type: boolean description: | Defaults to `false`. When set to `true`, the log probabilities of the generated tokens will be included in the response. From 9595a64515172fe99dd9191067494f289e38e0ba Mon Sep 17 00:00:00 2001 From: Max Shkutnyk Date: Wed, 27 Nov 2024 20:04:53 +0200 Subject: [PATCH 05/10] Fix reported issue with chained redirects (#270) Co-authored-by: Max Shkutnyk --- fern/pages/v2/fine-tuning/fine-tuning-with-the-python-sdk.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/pages/v2/fine-tuning/fine-tuning-with-the-python-sdk.mdx b/fern/pages/v2/fine-tuning/fine-tuning-with-the-python-sdk.mdx index 8aec259f..57cde519 100644 --- a/fern/pages/v2/fine-tuning/fine-tuning-with-the-python-sdk.mdx +++ b/fern/pages/v2/fine-tuning/fine-tuning-with-the-python-sdk.mdx @@ -56,5 +56,5 @@ finetuned_model = co.finetuning.create_finetuned_model( ## Fine-tuning results -When the fine-tune model is ready you will receive an email notification. You can explore the evaluation metrics using the Dashboard and try out your model using one of our APIs on the [Playground](https://dashboard.cohere.com/playground/). +When the fine-tune model is ready you will receive an email notification. You can explore the evaluation metrics using the Dashboard and try out your model using one of our APIs on the [Playground](https://dashboard.cohere.com/welcome/login?redirect_uri=/playground/chat). From 15e40ae99b74541973677f27812921f30b3b9ae7 Mon Sep 17 00:00:00 2001 From: platform-endpoints Date: Wed, 27 Nov 2024 19:19:11 +0000 Subject: [PATCH 06/10] Add spec changes Co-authored-by: billytrend-cohere <144115527+billytrend-cohere@users.noreply.github.com> --- cohere-openapi.yaml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/cohere-openapi.yaml b/cohere-openapi.yaml index 646bc4ea..01b77d64 100644 --- a/cohere-openapi.yaml +++ b/cohere-openapi.yaml @@ -5945,6 +5945,18 @@ paths: - messages - model properties: + stream: + description: | + Defaults to `false`. + + When `true`, the response will be a SSE stream of events. The final event will contain the complete response, and will have an `event_type` of `"stream-end"`. + + Streaming is beneficial for user interfaces that render the contents of the response piece by piece, as it gets generated. + + Compatible Deployments: Cohere Platform, Azure, AWS Sagemaker/Bedrock, Private Deployments + type: boolean + x-fern-audiences: + - public model: x-fern-audiences: - public From 7ebcd53b1a6efad2c3dff5e83dacdec996899f81 Mon Sep 17 00:00:00 2001 From: platform-endpoints Date: Wed, 27 Nov 2024 21:55:54 +0000 Subject: [PATCH 07/10] Add spec changes Co-authored-by: Max Shkutnyk --- cohere-openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cohere-openapi.yaml b/cohere-openapi.yaml index 01b77d64..c2ee6275 100644 --- a/cohere-openapi.yaml +++ b/cohere-openapi.yaml @@ -15258,7 +15258,7 @@ paths: items: $ref: "#/components/schemas/EmbeddingType" description: |- - Specifies the types of embeddings you want to get back. Not required and default is None, which returns the Embed Floats response type. Can be one or more of the following types. + Specifies the types of embeddings you want to get back. Can be one or more of the following types. * `"float"`: Use this when you want to get back the default float embeddings. Valid for all models. * `"int8"`: Use this when you want to get back signed int8 embeddings. Valid for only v3 models. From 169412fcdfb214f977ccdcc5201fe3d7346582cc Mon Sep 17 00:00:00 2001 From: Meor Amer <92068895+mrmer1@users.noreply.github.com> Date: Fri, 29 Nov 2024 16:04:02 +0800 Subject: [PATCH 08/10] 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 Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/changelog/2024-11-25-structured-outputs-tools.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/v2/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * Update fern/pages/text-generation/structured-outputs-json.mdx Co-authored-by: Michael Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> * updates post-review * fix markdown * change slug Signed-off-by: Michael * fixes Signed-off-by: Michael * Update 2024-11-25-structured-outputs-tools.mdx Signed-off-by: Michael * fix links * rename files * revert url change * Update structured-outputs-json.mdx Signed-off-by: Michael * update slug to remove 'JSON' * Add redirects for structured outputs pages (#269) Co-authored-by: Max Shkutnyk --------- Signed-off-by: Meor Amer <92068895+mrmer1@users.noreply.github.com> Signed-off-by: Michael Co-authored-by: Michael Co-authored-by: Michael Co-authored-by: Max Shkutnyk Co-authored-by: Max Shkutnyk --- fern/docs.yml | 6 + .../2024-11-27-structured-outputs-tools.mdx | 16 ++ ...utputs-json.mdx => structured-outputs.mdx} | 98 ++++++-- .../text-generation-tutorial.mdx | 2 +- .../prompt-library/book-an-appointment.mdx | 2 +- .../structured-outputs-json.mdx | 141 ----------- .../v2/text-generation/structured-outputs.mdx | 238 ++++++++++++++++++ .../v2/text-generation/tools/tool-use.mdx | 13 + .../text-generation-tutorial.mdx | 2 +- fern/v1.yml | 4 +- fern/v2.yml | 4 +- 11 files changed, 360 insertions(+), 166 deletions(-) create mode 100644 fern/pages/changelog/2024-11-27-structured-outputs-tools.mdx rename fern/pages/text-generation/{structured-outputs-json.mdx => structured-outputs.mdx} (50%) delete mode 100644 fern/pages/v2/text-generation/structured-outputs-json.mdx create mode 100644 fern/pages/v2/text-generation/structured-outputs.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 2a6fe328..06c036b9 100644 --- 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 new file mode 100644 index 00000000..a08ce9c6 --- /dev/null +++ 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/fern/pages/text-generation/structured-outputs-json.mdx b/fern/pages/text-generation/structured-outputs.mdx similarity index 50% rename from fern/pages/text-generation/structured-outputs-json.mdx rename to fern/pages/text-generation/structured-outputs.mdx index 90ac5088..bab8d112 100644 --- a/fern/pages/text-generation/structured-outputs-json.mdx +++ b/fern/pages/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. + + +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. + + +### 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. - +``` +# Example response + +{ + "name": "Emma Johnson", + "age": 32 +} + +``` + + 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. - + - -This feature is currently not supported in RAG and tool use scenarios. + +This feature is currently not supported in RAG mode. -## 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. - -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. - +``` +# Example response + +{ + "title": "The Great Gatsby", + "author": "F. Scott Fitzgerald", + "publication_year": 1925 +} + +``` + + +Note: Each schema provided will incur a latency overhead required for processing the schema. This is only applicable for the first few requests. + + +## 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 index c23640d9..a3339038 100644 --- 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/fern/pages/v2/text-generation/prompt-engineering/prompt-library/book-an-appointment.mdx b/fern/pages/v2/text-generation/prompt-engineering/prompt-library/book-an-appointment.mdx index 18b13fca..be828e46 100644 --- a/fern/pages/v2/text-generation/prompt-engineering/prompt-library/book-an-appointment.mdx +++ b/fern/pages/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 deleted file mode 100644 index 5c53cdbb..00000000 --- a/fern/pages/v2/text-generation/structured-outputs-json.mdx +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: "Structured Generations (JSON)" -slug: "v2/docs/structured-outputs-json" - -hidden: false - -description: "This page describes how to get Cohere models to create outputs in a certain format, such as JSON." -image: "../../../assets/images/f1cc130-cohere_meta_image.jpg" -keywords: "Cohere, language models, structured outputs" - -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](https://docs.cohere.com/docs/command-r) and [Command R+](https://docs.cohere.com/docs/command-r-plus) are great at producing structured outputs in formats such as JSON. - -## Why generate JSON Objects using an LLM? - -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. - -## How to use the `response_format` parameter - -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 -import cohere - -co = cohere.ClientV2(api_key="YOUR API KEY") - -res = co.chat( - model="command-r-plus-08-2024", - messages=[ - { - "role": "user", - "content": "Generate a JSON describing a person, with the fields 'name' and 'age'", - } - ], - response_format={"type": "json_object"}, -) - -print(res.message.content[0].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. - -``` -# Example response - -{ - "name": "Emma Johnson", - "age": 32 -} - -``` - - - 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. - - -## Specifying a schema (beta) - -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. - -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 -import cohere - -co = cohere.ClientV2(api_key="YOUR API KEY") - -res = co.chat( - model="command-r-plus-08-2024", - messages=[ - { - "role": "user", - "content": "Generate a JSON describing a book, with the fields 'title' and 'author' and 'publication_year'", - } - ], - response_format={ - "type": "json_object", - "schema": { - "type": "object", - "required": ["title", "author", "publication_year"], - "properties": { - "title": {"type": "string"}, - "author": {"type": "string"}, - "publication_year": {"type": "integer"}, - }, - }, - }, -) - -print(res.message.content[0].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. - -``` -# Example response - -{ - "title": "The Great Gatsby", - "author": "F. Scott Fitzgerald", - "publication_year": 1925 -} - -``` - - -Specifying a `json_schema` adds even more latency, proportional to the complexity of the schema. This parameter is in **beta**, and will continue seeing performance improvements. - - -### Generating nested objects - -By setting `response_format={ "type": "json_object" }`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 - -We do not support the entirety of the [JSON Schema specification](https://json-schema.org/specification). Below is a list of some unsupported features: - -- [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 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) - - `^` - - `$` - - `?=` - - `?!` - - The following [formats](https://json-schema.org/understanding-json-schema/reference/string#format) are the only supported ones - - `date-time` - - `uuid` - - `date` - - `time` diff --git a/fern/pages/v2/text-generation/structured-outputs.mdx b/fern/pages/v2/text-generation/structured-outputs.mdx new file mode 100644 index 00000000..2865aaa3 --- /dev/null +++ b/fern/pages/v2/text-generation/structured-outputs.mdx @@ -0,0 +1,238 @@ +--- +title: "Structured Outputs" +slug: "v2/docs/structured-outputs" + +hidden: false + +description: "This page describes how to get Cohere models to create outputs in a certain format, such as JSON." +image: "../../../assets/images/f1cc130-cohere_meta_image.jpg" +keywords: "Cohere, language models, structured outputs" + +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)" +--- + + +## Overview + +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. + +Compatible models: +- Command R 08 2024 +- Command R +- Command R+ 08 2024 +- Command R+ + +## How to Use Structured Outputs + +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. + + +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. + + +### 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 +co = cohere.ClientV2(api_key="YOUR API KEY") + +res = co.chat( + model="command-r-plus-08-2024", + messages=[ + { + "role": "user", + "content": "Generate a JSON describing a person, with the fields 'name' and 'age'", + } + ], + response_format={"type": "json_object"}, +) + +print(res.message.content[0].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. + +``` +# Example response + +{ + "name": "Emma Johnson", + "age": 32 +} + +``` + + +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. + + + +This feature is currently not supported in RAG mode. + + +#### 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. + +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.ClientV2(api_key="YOUR API KEY") + +res = co.chat( + model="command-r-plus-08-2024", + messages=[ + { + "role": "user", + "content": "Generate a JSON describing a book, with the fields 'title' and 'author' and 'publication_year'", + } + ], + response_format={ + "type": "json_object", + "schema": { + "type": "object", + "properties": { + "title": {"type": "string"}, + "author": {"type": "string"}, + "publication_year": {"type": "integer"}, + }, + "required": ["title", "author", "publication_year"], + }, + }, +) + +print(res.message.content[0].text) +``` + +In this schema, we defined three keys ("title," "author," "publication_year") and their expected data types ("string" and "integer"). The LLM will generate a JSON object that adheres to this structure. + +``` +# Example response + +{ + "title": "The Great Gatsby", + "author": "F. Scott Fitzgerald", + "publication_year": 1925 +} + +``` + + +Note: Each schema provided (in both JSON and Tools modes) will incur a latency overhead required for processing the schema. This is only applicable for the first few requests. + + +### Structured Outputs (Tools) +When you use the Chat API with `tools`, setting the `strict_tools` parameter to `true` will enforce that every generated tool call follows the specified tool schema. + + +`strict_tools` is currently an experimental parameter. We’ll be iterating on this feature and are looking for feedback. Share your experience with us in the `#api-discussions` channel on [discord](https://discord.gg/co-mmunity) or via [email](mailto:support@cohere.com). + + +With `strict_tools` enabled, the API will ensure that the tool names and tool parameters are generated according to the tool definitions. This eliminates tool name and parameter hallucinations, ensures that each parameter matches the specified data type, and that all required parameters are included in the model response. + +Additionally, this results in faster development. You don’t need to spend a lot of time prompt engineering the model to avoid hallucinations. + +In the example below, we create a tool that can retrieve weather data for a given location. The tool is called`get_weather` which contains a parameter called `location`. We then invoke the Chat API with `strict_tools` set to `true` to ensure that the generated tool calls always include the correct function and parameter names. + +When the `strict_tools` parameter is set to `true`, you can define a maximum of 200 fields across all tools being passed to an API call. + +```python PYTHON {24} +tools = [ + { + "type": "function", + "function": { + "name": "get_weather", + "description" : "Gets the weather of a given location", + "parameters": { + "type": "object", + "properties": { + "location": { + "type" : "string", + "description": "The location to get weather." + } + }, + "required": ["location"] + } + } + }, +] + +response = co.chat(model="command-r-plus-08-2024", + messages=[{"role": "user", "content": "What's the weather in Toronto?"}], + tools=tools, + strict_tools=True) + +print(response.message.tool_calls) +``` + + + +When `strict_tools` is enabled, tool definitions that have optional parameters must specify at least one `required` parameter as well. Tools with only optional parameters are not supported in this mode. + + +### When to Use Structured Outputs (JSON) vs. Structured Outputs (Tools) + +Structured Outputs (JSON) are ideal for text generation use cases where you want to format the model's responses to users in a specific way. + +For example, when building a travel planner application, you might want the LLM to generate itineraries in a specific JSON format, allowing the application to use the output in the other parts of the application. + +Structured Outputs (Tools) are ideal for function calling, tool use or agents use cases where you need the model to interact with external data or services. For instance, you can grant the model access to functions that interact with databases or other APIs. + +In summary, opt for: +- Structured Outputs (JSON) when you need the model's response to follow a specific structure. +- Structured Outputs (Tools) when you need the model to interact with external data or services. + + +## 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 + +We do not support the entirety of the [JSON Schema specification](https://json-schema.org/specification). Below is a list of some unsupported features: + +- [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 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) + - `^` + - `$` + - `?=` + - `?!` + - The following [formats](https://json-schema.org/understanding-json-schema/reference/string#format) are the only supported ones + - `date-time` + - `uuid` + - `date` + - `time` +- Others: + - `uniqueItems` + - `additionalProperties` diff --git a/fern/pages/v2/text-generation/tools/tool-use.mdx b/fern/pages/v2/text-generation/tools/tool-use.mdx index 677fe699..1b7b8798 100644 --- a/fern/pages/v2/text-generation/tools/tool-use.mdx +++ b/fern/pages/v2/text-generation/tools/tool-use.mdx @@ -362,6 +362,19 @@ Start: 177 | End: 204 | Text: 'Laptop: $1,000, 15 in stock' Start: 207 | End: 232 | Text: 'Tablet: $300, 25 in stock' ``` +## Structured Outputs (Tools) + +Setting the `strict_tools` parameter to True will enforce each tool call to follow the specified tool schema. To learn more about this feature, visit the [Structured Outputs documentation](https://docs.cohere.com/v2/docs/structured-outputs). + +Note that `strict_tools` is currently an experimental feature. + +```python PYTHON {4} +response = co.chat(model="command-r-plus-08-2024", + messages=messages, + tools=tools, + strict_tools=True) +``` + ## How to Get Good Answers With Tool Use To get good answers with tool use, make sure that the tool name and description as well as the names and descriptions for each parameter are descriptive. If you're not getting the model to recommend your tool correctly, iterate on those descriptions and names to help the model understand the tool better. diff --git a/fern/pages/v2/tutorials/build-things-with-cohere/text-generation-tutorial.mdx b/fern/pages/v2/tutorials/build-things-with-cohere/text-generation-tutorial.mdx index 7188767e..f9abc454 100644 --- a/fern/pages/v2/tutorials/build-things-with-cohere/text-generation-tutorial.mdx +++ b/fern/pages/v2/tutorials/build-things-with-cohere/text-generation-tutorial.mdx @@ -268,7 +268,7 @@ print(json_object) ``` Further reading: -- [Documentation on Structured Generations (JSON)](https://docs.cohere.com/docs/structured-outputs-json) +- [Documentation on Structured Outputs](https://docs.cohere.com/docs/structured-outputs) ## Streaming responses diff --git a/fern/v1.yml b/fern/v1.yml index e87e4d28..c038684f 100644 --- a/fern/v1.yml +++ b/fern/v1.yml @@ -65,8 +65,8 @@ navigation: path: pages/text-generation/chat-api.mdx - page: Streaming Responses path: pages/text-generation/streaming.mdx - - page: Structured Generations (JSON) - path: pages/text-generation/structured-outputs-json.mdx + - page: Structured Outputs + path: pages/text-generation/structured-outputs.mdx - page: Predictable Outputs path: pages/text-generation/predictable-outputs.mdx - page: Advanced Generation Parameters diff --git a/fern/v2.yml b/fern/v2.yml index 95bf54f0..ceb9bea1 100644 --- a/fern/v2.yml +++ b/fern/v2.yml @@ -65,8 +65,8 @@ navigation: path: pages/v2/text-generation/chat-api.mdx - page: Streaming Responses path: pages/v2/text-generation/streaming.mdx - - page: Structured Generations (JSON) - path: pages/v2/text-generation/structured-outputs-json.mdx + - page: Structured Outputs + path: pages/v2/text-generation/structured-outputs.mdx - page: Predictable Outputs path: pages/v2/text-generation/predictable-outputs.mdx - page: Advanced Generation Parameters From 1ce914b31deebc6e6755f16f9d9d2fd9f3a35e21 Mon Sep 17 00:00:00 2001 From: platform-endpoints Date: Fri, 29 Nov 2024 14:51:55 +0000 Subject: [PATCH 09/10] Add spec changes Co-authored-by: billytrend-cohere <144115527+billytrend-cohere@users.noreply.github.com> --- cohere-openapi.yaml | 76 +++++++++++++-------------------------------- 1 file changed, 21 insertions(+), 55 deletions(-) diff --git a/cohere-openapi.yaml b/cohere-openapi.yaml index c2ee6275..dffe695e 100644 --- a/cohere-openapi.yaml +++ b/cohere-openapi.yaml @@ -7888,11 +7888,7 @@ paths: $ref: "#/components/schemas/GenerateStreamedResponse" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -11560,11 +11556,7 @@ paths: embeddings_by_type: "#/components/schemas/EmbedByTypeResponse" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -15150,11 +15142,7 @@ paths: $ref: "#/components/schemas/EmbedByTypeResponse" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -15436,11 +15424,7 @@ paths: $ref: "#/components/schemas/CreateEmbedJobResponse" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -15585,11 +15569,7 @@ paths: $ref: "#/components/schemas/ListEmbedJobResponse" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -15735,11 +15715,7 @@ paths: $ref: "#/components/schemas/EmbedJob" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning message for potentially incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -15870,11 +15846,7 @@ paths: description: OK headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -18362,11 +18334,7 @@ paths: description: OK headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" content: application/json: schema: @@ -18664,11 +18632,7 @@ paths: description: OK headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" content: application/json: schema: @@ -18926,11 +18890,7 @@ paths: description: OK headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" content: application/json: schema: @@ -19983,11 +19943,7 @@ paths: $ref: "#/components/schemas/GetModelResponse" headers: X-API-Warning: - schema: - type: string - x-fern-audiences: - - public - description: Warning description for incorrect usage of the API + $ref: "#/components/headers/ApiWarning" "400": $ref: "#/components/responses/BadRequest" "401": @@ -27596,3 +27552,13 @@ components: properties: data: type: string + headers: + ApiWarning: + description: The name of the project that is making the request. + x-fern-audiences: + - public + schema: + type: string + required: false + example: Parameter xyz is deprecated, for more information please refer to + https://docs.cohere.com/versioning-reference From 960fbc36b138c061b4cb6443fefecffab8de89ad Mon Sep 17 00:00:00 2001 From: fern <126544928+fern-bot@users.noreply.github.com> Date: Fri, 29 Nov 2024 08:24:11 -0700 Subject: [PATCH 10/10] Update package.json to upgrade Fern (#272) Signed-off-by: fern <126544928+fern-bot@users.noreply.github.com> --- package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/package.json b/package.json index efb368db..540b073e 100644 --- a/package.json +++ b/package.json @@ -19,8 +19,8 @@ }, "dependencies": { "cohere-ai": "^7.14.0", - "fern-api": "^0.41.16", + "fern-api": "^0.45.1", "gray-matter": "^4.0.3", "react": "^18.3.1" } -} \ No newline at end of file +}