docs(api): updates to API spec

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 29
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-710e8a17bc916b755685592b3831e6732f3ba02904f970084aef0ac86fd79ed5.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-9f17b2629bd54f56bc3e48ec710b11e2ba84302725f8da9e9ed390bbed5d3b5b.yml

src/writerai/resources/graphs.py

@@ -66,23 +66,24 @@ def with_streaming_response(self) -> GraphsResourceWithStreamingResponse:
     def create(
         self,
         *,
-        name: str,
         description: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
         # 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,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> GraphCreateResponse:
-        """Create graph
+        """
+        Create graph
 
         Args:
-          name: The name of the graph.
-
-        This can be at most 255 characters.
+          description: A description of the graph (max 255 characters). Omitting this field leaves the
+              description unchanged.
 
-          description: A description of the graph. This can be at most 255 characters.
+          name: The name of the graph (max 255 characters). Omitting this field leaves the name
+              unchanged.
 
           extra_headers: Send extra headers
 
@@ -96,8 +97,8 @@ def create(
             "/v1/graphs",
             body=maybe_transform(
                 {
-                    "name": name,
                     "description": description,
+                    "name": name,
                 },
                 graph_create_params.GraphCreateParams,
             ),
@@ -144,23 +145,24 @@ def update(
         self,
         graph_id: str,
         *,
-        name: str,
         description: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
         # 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,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> GraphUpdateResponse:
-        """Update graph
+        """
+        Update the name and description of a Knowledge Graph.
 
         Args:
-          name: The name of the graph.
-
-        This can be at most 255 characters.
+          description: A description of the graph (max 255 characters). Omitting this field leaves the
+              description unchanged.
 
-          description: A description of the graph. This can be at most 255 characters.
+          name: The name of the graph (max 255 characters). Omitting this field leaves the name
+              unchanged.
 
           extra_headers: Send extra headers
 
@@ -176,8 +178,8 @@ def update(
             f"/v1/graphs/{graph_id}",
             body=maybe_transform(
                 {
-                    "name": name,
                     "description": description,
+                    "name": name,
                 },
                 graph_update_params.GraphUpdateParams,
             ),
@@ -528,23 +530,24 @@ def with_streaming_response(self) -> AsyncGraphsResourceWithStreamingResponse:
     async def create(
         self,
         *,
-        name: str,
         description: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
         # 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,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> GraphCreateResponse:
-        """Create graph
+        """
+        Create graph
 
         Args:
-          name: The name of the graph.
-
-        This can be at most 255 characters.
+          description: A description of the graph (max 255 characters). Omitting this field leaves the
+              description unchanged.
 
-          description: A description of the graph. This can be at most 255 characters.
+          name: The name of the graph (max 255 characters). Omitting this field leaves the name
+              unchanged.
 
           extra_headers: Send extra headers
 
@@ -558,8 +561,8 @@ async def create(
             "/v1/graphs",
             body=await async_maybe_transform(
                 {
-                    "name": name,
                     "description": description,
+                    "name": name,
                 },
                 graph_create_params.GraphCreateParams,
             ),
@@ -606,23 +609,24 @@ async def update(
         self,
         graph_id: str,
         *,
-        name: str,
         description: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
         # 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,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> GraphUpdateResponse:
-        """Update graph
+        """
+        Update the name and description of a Knowledge Graph.
 
         Args:
-          name: The name of the graph.
-
-        This can be at most 255 characters.
+          description: A description of the graph (max 255 characters). Omitting this field leaves the
+              description unchanged.
 
-          description: A description of the graph. This can be at most 255 characters.
+          name: The name of the graph (max 255 characters). Omitting this field leaves the name
+              unchanged.
 
           extra_headers: Send extra headers
 
@@ -638,8 +642,8 @@ async def update(
             f"/v1/graphs/{graph_id}",
             body=await async_maybe_transform(
                 {
-                    "name": name,
                     "description": description,
+                    "name": name,
                 },
                 graph_update_params.GraphUpdateParams,
             ),

src/writerai/types/graph_create_params.py

@@ -2,14 +2,20 @@
 
 from __future__ import annotations
 
-from typing_extensions import Required, TypedDict
+from typing_extensions import TypedDict
 
 __all__ = ["GraphCreateParams"]
 
 
 class GraphCreateParams(TypedDict, total=False):
-    name: Required[str]
-    """The name of the graph. This can be at most 255 characters."""
-
     description: str
-    """A description of the graph. This can be at most 255 characters."""
+    """A description of the graph (max 255 characters).
+
+    Omitting this field leaves the description unchanged.
+    """
+
+    name: str
+    """The name of the graph (max 255 characters).
+
+    Omitting this field leaves the name unchanged.
+    """

src/writerai/types/graph_update_params.py

@@ -2,14 +2,20 @@
 
 from __future__ import annotations
 
-from typing_extensions import Required, TypedDict
+from typing_extensions import TypedDict
 
 __all__ = ["GraphUpdateParams"]
 
 
 class GraphUpdateParams(TypedDict, total=False):
-    name: Required[str]
-    """The name of the graph. This can be at most 255 characters."""
-
     description: str
-    """A description of the graph. This can be at most 255 characters."""
+    """A description of the graph (max 255 characters).
+
+    Omitting this field leaves the description unchanged.
+    """
+
+    name: str
+    """The name of the graph (max 255 characters).
+
+    Omitting this field leaves the name unchanged.
+    """

src/writerai/types/question.py

@@ -15,7 +15,7 @@ class Subquery(BaseModel):
     query: str
     """The subquery that was asked."""
 
-    sources: List[Source]
+    sources: List[Optional[Source]]
 
 
 class Question(BaseModel):
@@ -25,6 +25,6 @@ class Question(BaseModel):
     question: str
     """The question that was asked."""
 
-    sources: List[Source]
+    sources: List[Optional[Source]]
 
-    subqueries: Optional[List[Subquery]] = None
+    subqueries: Optional[List[Optional[Subquery]]] = None

src/writerai/types/shared/graph_data.py

@@ -16,12 +16,12 @@ class Subquery(BaseModel):
     query: str
     """The subquery that was asked."""
 
-    sources: List[Source]
+    sources: List[Optional[Source]]
 
 
 class GraphData(BaseModel):
-    sources: Optional[List[Source]] = None
+    sources: Optional[List[Optional[Source]]] = None
 
     status: Optional[Literal["processing", "finished"]] = None
 
-    subqueries: Optional[List[Subquery]] = None
+    subqueries: Optional[List[Optional[Subquery]]] = None

src/writerai/types/shared_params/graph_data.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Iterable
+from typing import Iterable, Optional
 from typing_extensions import Literal, Required, TypedDict
 
 from .source import Source
@@ -17,12 +17,12 @@ class Subquery(TypedDict, total=False):
     query: Required[str]
     """The subquery that was asked."""
 
-    sources: Required[Iterable[Source]]
+    sources: Required[Iterable[Optional[Source]]]
 
 
 class GraphData(TypedDict, total=False):
-    sources: Iterable[Source]
+    sources: Iterable[Optional[Source]]
 
-    status: Literal["processing", "finished"]
+    status: Optional[Literal["processing", "finished"]]
 
-    subqueries: Iterable[Subquery]
+    subqueries: Iterable[Optional[Subquery]]