docs(api): updates to API spec

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 33
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-4ec783072dd7f57c6e021a746df7650fb8d7a164d8ec25c7d5cab06c33bc114f.yml
-openapi_spec_hash: ceab065d515f3681b0c33137da308968
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-ea6ec4b34f6b7fdecc564f59b2e31482eee05830bf8dc1f389461b158de1548e.yml
+openapi_spec_hash: ea89c1faed473908be2740efe6da255f
 config_hash: 886645f89dc98f04b8931eaf02854e5f

src/writerai/resources/files.py

@@ -6,7 +6,7 @@
 
 import httpx
 
-from ..types import file_list_params, file_retry_params
+from ..types import file_list_params, file_retry_params, file_upload_params
 from .._types import Body, Omit, Query, Headers, NotGiven, FileTypes, SequenceNotStr, omit, not_given
 from .._utils import maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -274,6 +274,7 @@ def upload(
         content: FileTypes,
         content_disposition: str,
         content_type: str,
+        graph_id: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -287,6 +288,13 @@ def upload(
         DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, and XLSX.
 
         Args:
+          graph_id: The unique identifier of the Knowledge Graph to associate the uploaded file
+              with.
+
+              Note: The response from the upload endpoint does not include the `graphId`
+              field, but the association will be visible when you retrieve the file using the
+              file retrieval endpoint.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -303,7 +311,11 @@ def upload(
         return self._post(
             "/v1/files",
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform({"graph_id": graph_id}, file_upload_params.FileUploadParams),
             ),
             binary_request=content,
             cast_to=File,
@@ -550,6 +562,7 @@ async def upload(
         content: FileTypes,
         content_disposition: str,
         content_type: str,
+        graph_id: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
@@ -563,6 +576,13 @@ async def upload(
         DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, and XLSX.
 
         Args:
+          graph_id: The unique identifier of the Knowledge Graph to associate the uploaded file
+              with.
+
+              Note: The response from the upload endpoint does not include the `graphId`
+              field, but the association will be visible when you retrieve the file using the
+              file retrieval endpoint.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -579,7 +599,11 @@ async def upload(
         return await self._post(
             "/v1/files",
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform({"graph_id": graph_id}, file_upload_params.FileUploadParams),
             ),
             binary_request=content,
             cast_to=File,

src/writerai/resources/vision.py

@@ -57,8 +57,10 @@ def analyze(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> VisionResponse:
-        """
-        Submit images and a prompt to generate an analysis of the images.
+        """Submit images and documents with a prompt to generate an analysis.
+
+        Supports JPG,
+        PNG, PDF, and TXT files up to 7MB each.
 
         Args:
           model: The model to use for image analysis.
@@ -125,8 +127,10 @@ async def analyze(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> VisionResponse:
-        """
-        Submit images and a prompt to generate an analysis of the images.
+        """Submit images and documents with a prompt to generate an analysis.
+
+        Supports JPG,
+        PNG, PDF, and TXT files up to 7MB each.
 
         Args:
           model: The model to use for image analysis.

src/writerai/types/file.py

@@ -16,7 +16,13 @@ class File(BaseModel):
     """The timestamp when the file was uploaded."""
 
     graph_ids: List[str]
-    """A list of Knowledge Graph IDs that the file is associated with."""
+    """A list of Knowledge Graph IDs that the file is associated with.
+
+    If you provided a `graphId` during upload, the file is associated with that
+    Knowledge Graph. However, the `graph_ids` field in the upload response is an
+    empty list. The association will be visible in the `graph_ids` list when you
+    retrieve the file using the file retrieval endpoint.
+    """
 
     name: str
     """The name of the file."""

src/writerai/types/file_upload_params.py

@@ -16,3 +16,13 @@ class FileUploadParams(TypedDict, total=False):
     content_disposition: Required[Annotated[str, PropertyInfo(alias="Content-Disposition")]]
 
     content_type: Required[Annotated[str, PropertyInfo(alias="Content-Type")]]
+
+    graph_id: Annotated[str, PropertyInfo(alias="graphId")]
+    """
+    The unique identifier of the Knowledge Graph to associate the uploaded file
+    with.
+
+    Note: The response from the upload endpoint does not include the `graphId`
+    field, but the association will be visible when you retrieve the file using the
+    file retrieval endpoint.
+    """

src/writerai/types/shared/tool_param.py

@@ -203,10 +203,11 @@ class TranslationTool(BaseModel):
 
 class VisionToolFunctionVariable(BaseModel):
     file_id: str
-    """The File ID of the image to analyze.
+    """The File ID of the file to analyze.
 
     The file must be uploaded to the Writer platform before you use it with the
-    Vision tool. The maximum allowed file size is 7MB.
+    Vision tool. Supported file types: JPG, PNG, PDF, TXT. The maximum allowed file
+    size is 7MB.
     """
 
     name: str
@@ -228,7 +229,10 @@ class VisionToolFunction(BaseModel):
 
 class VisionTool(BaseModel):
     function: VisionToolFunction
-    """A tool that uses Palmyra Vision to analyze images."""
+    """A tool that uses Palmyra Vision to analyze images and documents.
+
+    Supports JPG, PNG, PDF, and TXT files up to 7MB each.
+    """
 
     type: Literal["vision"]
     """The type of tool."""

src/writerai/types/shared_params/tool_param.py

@@ -204,10 +204,11 @@ class TranslationTool(TypedDict, total=False):
 
 class VisionToolFunctionVariable(TypedDict, total=False):
     file_id: Required[str]
-    """The File ID of the image to analyze.
+    """The File ID of the file to analyze.
 
     The file must be uploaded to the Writer platform before you use it with the
-    Vision tool. The maximum allowed file size is 7MB.
+    Vision tool. Supported file types: JPG, PNG, PDF, TXT. The maximum allowed file
+    size is 7MB.
     """
 
     name: Required[str]
@@ -229,7 +230,10 @@ class VisionToolFunction(TypedDict, total=False):
 
 class VisionTool(TypedDict, total=False):
     function: Required[VisionToolFunction]
-    """A tool that uses Palmyra Vision to analyze images."""
+    """A tool that uses Palmyra Vision to analyze images and documents.
+
+    Supports JPG, PNG, PDF, and TXT files up to 7MB each.
+    """
 
     type: Required[Literal["vision"]]
     """The type of tool."""

src/writerai/types/vision_analyze_params.py

@@ -25,10 +25,10 @@ class VisionAnalyzeParams(TypedDict, total=False):
 
 class Variable(TypedDict, total=False):
     file_id: Required[str]
-    """The File ID of the image to analyze.
+    """The File ID of the file to analyze.
 
     The file must be uploaded to the Writer platform before it can be used in a
-    vision request.
+    vision request. Supported file types: JPG, PNG, PDF, TXT (max 7MB each).
     """
 
     name: Required[str]

tests/api_resources/test_files.py

@@ -239,6 +239,17 @@ def test_method_upload(self, client: Writer) -> None:
         )
         assert_matches_type(File, file, path=["response"])
 
+    @pytest.mark.skip(reason="requests with binary data not yet supported in test environment")
+    @parametrize
+    def test_method_upload_with_all_params(self, client: Writer) -> None:
+        file = client.files.upload(
+            content=b"raw file contents",
+            content_disposition="Content-Disposition",
+            content_type="Content-Type",
+            graph_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+        )
+        assert_matches_type(File, file, path=["response"])
+
     @pytest.mark.skip(reason="requests with binary data not yet supported in test environment")
     @parametrize
     def test_raw_response_upload(self, client: Writer) -> None:
@@ -484,6 +495,17 @@ async def test_method_upload(self, async_client: AsyncWriter) -> None:
         )
         assert_matches_type(File, file, path=["response"])
 
+    @pytest.mark.skip(reason="requests with binary data not yet supported in test environment")
+    @parametrize
+    async def test_method_upload_with_all_params(self, async_client: AsyncWriter) -> None:
+        file = await async_client.files.upload(
+            content=b"raw file contents",
+            content_disposition="Content-Disposition",
+            content_type="Content-Type",
+            graph_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
+        )
+        assert_matches_type(File, file, path=["response"])
+
     @pytest.mark.skip(reason="requests with binary data not yet supported in test environment")
     @parametrize
     async def test_raw_response_upload(self, async_client: AsyncWriter) -> None: