docs(api): updates to API spec (#223)

Author: stainless-app[bot]

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 30
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-57a138ff1e8940e627dd0108eb14c25bbeacd70e5f1106f8abd796cba6c51882.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-50d65469557b50b46f15db6f5da3b81ed5c1f551e5eab64ded93e46eafaa3696.yml

src/writerai/resources/chat.py

@@ -115,9 +115,11 @@ def chat(
               automatically choose the best tool, `none` disables tool calling. You can also
               pass a specific previously defined function.
 
-          tools: An array of tools described to the model using JSON schema that the model can
-              use to generate responses. You can define your own functions or use the built-in
-              `graph` or `llm` tools.
+          tools: An array containing tool definitions for tools that the model can use to
+              generate responses. The tool definitions use JSON schema. You can define your
+              own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+              that you can only use one built-in tool type in the array (only one of `graph`,
+              `llm`, or `vision`).
 
           top_p: Sets the threshold for "nucleus sampling," a technique to focus the model's
               token generation on the most likely subset of tokens. Only tokens with
@@ -198,9 +200,11 @@ def chat(
               automatically choose the best tool, `none` disables tool calling. You can also
               pass a specific previously defined function.
 
-          tools: An array of tools described to the model using JSON schema that the model can
-              use to generate responses. You can define your own functions or use the built-in
-              `graph` or `llm` tools.
+          tools: An array containing tool definitions for tools that the model can use to
+              generate responses. The tool definitions use JSON schema. You can define your
+              own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+              that you can only use one built-in tool type in the array (only one of `graph`,
+              `llm`, or `vision`).
 
           top_p: Sets the threshold for "nucleus sampling," a technique to focus the model's
               token generation on the most likely subset of tokens. Only tokens with
@@ -281,9 +285,11 @@ def chat(
               automatically choose the best tool, `none` disables tool calling. You can also
               pass a specific previously defined function.
 
-          tools: An array of tools described to the model using JSON schema that the model can
-              use to generate responses. You can define your own functions or use the built-in
-              `graph` or `llm` tools.
+          tools: An array containing tool definitions for tools that the model can use to
+              generate responses. The tool definitions use JSON schema. You can define your
+              own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+              that you can only use one built-in tool type in the array (only one of `graph`,
+              `llm`, or `vision`).
 
           top_p: Sets the threshold for "nucleus sampling," a technique to focus the model's
               token generation on the most likely subset of tokens. Only tokens with
@@ -435,9 +441,11 @@ async def chat(
               automatically choose the best tool, `none` disables tool calling. You can also
               pass a specific previously defined function.
 
-          tools: An array of tools described to the model using JSON schema that the model can
-              use to generate responses. You can define your own functions or use the built-in
-              `graph` or `llm` tools.
+          tools: An array containing tool definitions for tools that the model can use to
+              generate responses. The tool definitions use JSON schema. You can define your
+              own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+              that you can only use one built-in tool type in the array (only one of `graph`,
+              `llm`, or `vision`).
 
           top_p: Sets the threshold for "nucleus sampling," a technique to focus the model's
               token generation on the most likely subset of tokens. Only tokens with
@@ -518,9 +526,11 @@ async def chat(
               automatically choose the best tool, `none` disables tool calling. You can also
               pass a specific previously defined function.
 
-          tools: An array of tools described to the model using JSON schema that the model can
-              use to generate responses. You can define your own functions or use the built-in
-              `graph` or `llm` tools.
+          tools: An array containing tool definitions for tools that the model can use to
+              generate responses. The tool definitions use JSON schema. You can define your
+              own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+              that you can only use one built-in tool type in the array (only one of `graph`,
+              `llm`, or `vision`).
 
           top_p: Sets the threshold for "nucleus sampling," a technique to focus the model's
               token generation on the most likely subset of tokens. Only tokens with
@@ -601,9 +611,11 @@ async def chat(
               automatically choose the best tool, `none` disables tool calling. You can also
               pass a specific previously defined function.
 
-          tools: An array of tools described to the model using JSON schema that the model can
-              use to generate responses. You can define your own functions or use the built-in
-              `graph` or `llm` tools.
+          tools: An array containing tool definitions for tools that the model can use to
+              generate responses. The tool definitions use JSON schema. You can define your
+              own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+              that you can only use one built-in tool type in the array (only one of `graph`,
+              `llm`, or `vision`).
 
           top_p: Sets the threshold for "nucleus sampling," a technique to focus the model's
               token generation on the most likely subset of tokens. Only tokens with

src/writerai/types/chat_chat_params.py

@@ -77,9 +77,11 @@ class ChatChatParamsBase(TypedDict, total=False):
 
     tools: Iterable[ToolParam]
     """
-    An array of tools described to the model using JSON schema that the model can
-    use to generate responses. You can define your own functions or use the built-in
-    `graph` or `llm` tools.
+    An array containing tool definitions for tools that the model can use to
+    generate responses. The tool definitions use JSON schema. You can define your
+    own functions or use one of the built-in `graph`, `llm`, or `vision` tools. Note
+    that you can only use one built-in tool type in the array (only one of `graph`,
+    `llm`, or `vision`).
     """
 
     top_p: float

src/writerai/types/shared/tool_param.py

@@ -7,7 +7,17 @@
 from ..._models import BaseModel
 from .function_definition import FunctionDefinition
 
-__all__ = ["ToolParam", "FunctionTool", "GraphTool", "GraphToolFunction", "LlmTool", "LlmToolFunction"]
+__all__ = [
+    "ToolParam",
+    "FunctionTool",
+    "GraphTool",
+    "GraphToolFunction",
+    "LlmTool",
+    "LlmToolFunction",
+    "VisionTool",
+    "VisionToolFunction",
+    "VisionToolFunctionVariable",
+]
 
 
 class FunctionTool(BaseModel):
@@ -53,4 +63,39 @@ class LlmTool(BaseModel):
     """The type of tool."""
 
 
-ToolParam: TypeAlias = Annotated[Union[FunctionTool, GraphTool, LlmTool], PropertyInfo(discriminator="type")]
+class VisionToolFunctionVariable(BaseModel):
+    file_id: str
+    """The File ID of the image to be analyzed.
+
+    The file must be uploaded to the Writer platform before you use it with the
+    Vision tool.
+    """
+
+    name: str
+    """The name of the file variable.
+
+    You must reference this name in the `message.content` field of the request to
+    the chat completions endpoint. Use double curly braces (`{{}}`) to reference the
+    file. For example,
+    `Describe the difference between the image {{image_1}} and the image {{image_2}}`.
+    """
+
+
+class VisionToolFunction(BaseModel):
+    model: str
+    """The model to be used for image analysis. Must be `palmyra-vision`."""
+
+    variables: List[VisionToolFunctionVariable]
+
+
+class VisionTool(BaseModel):
+    function: VisionToolFunction
+    """A tool that uses Palmyra Vision to analyze images."""
+
+    type: Literal["vision"]
+    """The type of tool."""
+
+
+ToolParam: TypeAlias = Annotated[
+    Union[FunctionTool, GraphTool, LlmTool, VisionTool], PropertyInfo(discriminator="type")
+]

src/writerai/types/shared_params/tool_param.py

@@ -2,12 +2,22 @@
 
 from __future__ import annotations
 
-from typing import List, Union
+from typing import List, Union, Iterable
 from typing_extensions import Literal, Required, TypeAlias, TypedDict
 
 from .function_definition import FunctionDefinition
 
-__all__ = ["ToolParam", "FunctionTool", "GraphTool", "GraphToolFunction", "LlmTool", "LlmToolFunction"]
+__all__ = [
+    "ToolParam",
+    "FunctionTool",
+    "GraphTool",
+    "GraphToolFunction",
+    "LlmTool",
+    "LlmToolFunction",
+    "VisionTool",
+    "VisionToolFunction",
+    "VisionToolFunctionVariable",
+]
 
 
 class FunctionTool(TypedDict, total=False):
@@ -53,4 +63,37 @@ class LlmTool(TypedDict, total=False):
     """The type of tool."""
 
 
-ToolParam: TypeAlias = Union[FunctionTool, GraphTool, LlmTool]
+class VisionToolFunctionVariable(TypedDict, total=False):
+    file_id: Required[str]
+    """The File ID of the image to be analyzed.
+
+    The file must be uploaded to the Writer platform before you use it with the
+    Vision tool.
+    """
+
+    name: Required[str]
+    """The name of the file variable.
+
+    You must reference this name in the `message.content` field of the request to
+    the chat completions endpoint. Use double curly braces (`{{}}`) to reference the
+    file. For example,
+    `Describe the difference between the image {{image_1}} and the image {{image_2}}`.
+    """
+
+
+class VisionToolFunction(TypedDict, total=False):
+    model: Required[str]
+    """The model to be used for image analysis. Must be `palmyra-vision`."""
+
+    variables: Required[Iterable[VisionToolFunctionVariable]]
+
+
+class VisionTool(TypedDict, total=False):
+    function: Required[VisionToolFunction]
+    """A tool that uses Palmyra Vision to analyze images."""
+
+    type: Required[Literal["vision"]]
+    """The type of tool."""
+
+
+ToolParam: TypeAlias = Union[FunctionTool, GraphTool, LlmTool, VisionTool]