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

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 30
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-50d65469557b50b46f15db6f5da3b81ed5c1f551e5eab64ded93e46eafaa3696.yml
-openapi_spec_hash: 5e65cdf348fa909363010cd2fb5866c5
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-d15316b8a3a086ae9ec8eea0d436b0885262df9bcf23b9587ad059e50357c220.yml
+openapi_spec_hash: 4f81a4f4840438f80eff345e76ead962
 config_hash: b3310cd2944d74a3599e847847226a42

src/writerai/resources/graphs.py

@@ -358,8 +358,8 @@ def question(
         *,
         graph_ids: List[str],
         question: str,
-        stream: Literal[False],
-        subqueries: bool,
+        stream: Literal[False] | NotGiven = NOT_GIVEN,
+        subqueries: bool | 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,
@@ -398,7 +398,7 @@ def question(
         graph_ids: List[str],
         question: str,
         stream: Literal[True],
-        subqueries: bool,
+        subqueries: bool | 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,
@@ -437,7 +437,7 @@ def question(
         graph_ids: List[str],
         question: str,
         stream: bool,
-        subqueries: bool,
+        subqueries: bool | 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,
@@ -469,14 +469,14 @@ def question(
         """
         ...
 
-    @required_args(["graph_ids", "question", "stream", "subqueries"])
+    @required_args(["graph_ids", "question"], ["graph_ids", "question", "stream"])
     def question(
         self,
         *,
         graph_ids: List[str],
         question: str,
-        stream: Literal[False] | Literal[True],
-        subqueries: bool,
+        stream: Literal[False] | Literal[True] | NotGiven = NOT_GIVEN,
+        subqueries: bool | 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,
@@ -857,8 +857,8 @@ async def question(
         *,
         graph_ids: List[str],
         question: str,
-        stream: Literal[False],
-        subqueries: bool,
+        stream: Literal[False] | NotGiven = NOT_GIVEN,
+        subqueries: bool | 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,
@@ -897,7 +897,7 @@ async def question(
         graph_ids: List[str],
         question: str,
         stream: Literal[True],
-        subqueries: bool,
+        subqueries: bool | 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,
@@ -936,7 +936,7 @@ async def question(
         graph_ids: List[str],
         question: str,
         stream: bool,
-        subqueries: bool,
+        subqueries: bool | 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,
@@ -968,14 +968,14 @@ async def question(
         """
         ...
 
-    @required_args(["graph_ids", "question", "stream", "subqueries"])
+    @required_args(["graph_ids", "question"], ["graph_ids", "question", "stream"])
     async def question(
         self,
         *,
         graph_ids: List[str],
         question: str,
-        stream: Literal[False] | Literal[True],
-        subqueries: bool,
+        stream: Literal[False] | Literal[True] | NotGiven = NOT_GIVEN,
+        subqueries: bool | 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,

src/writerai/types/chat_chat_params.py

@@ -95,6 +95,12 @@ class ChatChatParamsBase(TypedDict, total=False):
 
 class Message(TypedDict, total=False):
     role: Required[Literal["user", "assistant", "system", "tool"]]
+    """The role of the chat message.
+
+    You can provide a system prompt by setting the role to `system`, or specify that
+    a message is the result of a [tool call](/api-guides/tool-calling) by setting
+    the role to `tool`.
+    """
 
     content: Optional[str]
 

src/writerai/types/graph_question_params.py

@@ -15,12 +15,12 @@ class GraphQuestionParamsBase(TypedDict, total=False):
     question: Required[str]
     """The question to be answered using the Knowledge Graph."""
 
-    subqueries: Required[bool]
+    subqueries: bool
     """Specify whether to include subqueries."""
 
 
 class GraphQuestionParamsNonStreaming(GraphQuestionParamsBase, total=False):
-    stream: Required[Literal[False]]
+    stream: Literal[False]
     """Determines whether the model's output should be streamed.
 
     If true, the output is generated and sent incrementally, which can be useful for

tests/api_resources/test_graphs.py

@@ -261,6 +261,14 @@ def test_path_params_add_file_to_graph(self, client: Writer) -> None:
 
     @parametrize
     def test_method_question_overload_1(self, client: Writer) -> None:
+        graph = client.graphs.question(
+            graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
+            question="question",
+        )
+        assert_matches_type(Question, graph, path=["response"])
+
+    @parametrize
+    def test_method_question_with_all_params_overload_1(self, client: Writer) -> None:
         graph = client.graphs.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
@@ -274,8 +282,6 @@ def test_raw_response_question_overload_1(self, client: Writer) -> None:
         response = client.graphs.with_raw_response.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
-            stream=False,
-            subqueries=True,
         )
 
         assert response.is_closed is True
@@ -288,8 +294,6 @@ def test_streaming_response_question_overload_1(self, client: Writer) -> None:
         with client.graphs.with_streaming_response.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
-            stream=False,
-            subqueries=True,
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -301,6 +305,15 @@ def test_streaming_response_question_overload_1(self, client: Writer) -> None:
 
     @parametrize
     def test_method_question_overload_2(self, client: Writer) -> None:
+        graph_stream = client.graphs.question(
+            graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
+            question="question",
+            stream=True,
+        )
+        graph_stream.response.close()
+
+    @parametrize
+    def test_method_question_with_all_params_overload_2(self, client: Writer) -> None:
         graph_stream = client.graphs.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
@@ -315,7 +328,6 @@ def test_raw_response_question_overload_2(self, client: Writer) -> None:
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
             stream=True,
-            subqueries=True,
         )
 
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -328,7 +340,6 @@ def test_streaming_response_question_overload_2(self, client: Writer) -> None:
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
             stream=True,
-            subqueries=True,
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -625,6 +636,14 @@ async def test_path_params_add_file_to_graph(self, async_client: AsyncWriter) ->
 
     @parametrize
     async def test_method_question_overload_1(self, async_client: AsyncWriter) -> None:
+        graph = await async_client.graphs.question(
+            graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
+            question="question",
+        )
+        assert_matches_type(Question, graph, path=["response"])
+
+    @parametrize
+    async def test_method_question_with_all_params_overload_1(self, async_client: AsyncWriter) -> None:
         graph = await async_client.graphs.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
@@ -638,8 +657,6 @@ async def test_raw_response_question_overload_1(self, async_client: AsyncWriter)
         response = await async_client.graphs.with_raw_response.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
-            stream=False,
-            subqueries=True,
         )
 
         assert response.is_closed is True
@@ -652,8 +669,6 @@ async def test_streaming_response_question_overload_1(self, async_client: AsyncW
         async with async_client.graphs.with_streaming_response.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
-            stream=False,
-            subqueries=True,
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -665,6 +680,15 @@ async def test_streaming_response_question_overload_1(self, async_client: AsyncW
 
     @parametrize
     async def test_method_question_overload_2(self, async_client: AsyncWriter) -> None:
+        graph_stream = await async_client.graphs.question(
+            graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
+            question="question",
+            stream=True,
+        )
+        await graph_stream.response.aclose()
+
+    @parametrize
+    async def test_method_question_with_all_params_overload_2(self, async_client: AsyncWriter) -> None:
         graph_stream = await async_client.graphs.question(
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
@@ -679,7 +703,6 @@ async def test_raw_response_question_overload_2(self, async_client: AsyncWriter)
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
             stream=True,
-            subqueries=True,
         )
 
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -692,7 +715,6 @@ async def test_streaming_response_question_overload_2(self, async_client: AsyncW
             graph_ids=["182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"],
             question="question",
             stream=True,
-            subqueries=True,
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"