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-321826aa393f6f2c2e2ccc8b20795157f8b55908a96b4c28d90272f306ee3ff4.yml
-openapi_spec_hash: ccf23a9557962bab6ed52a94a25ecf1c
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-3f87c8deb39e443022f2e04252994a6c9d25473872503edf9eec00d874576b2d.yml
+openapi_spec_hash: 5de52bf1d78e00b13a04f6e9ce2f2fb5
 config_hash: 7a38bab086b53b43d2a719cb4d883264

src/writerai/resources/graphs.py

@@ -360,6 +360,7 @@ def question(
         *,
         graph_ids: SequenceNotStr[str],
         question: str,
+        query_config: graph_question_params.QueryConfig | NotGiven = NOT_GIVEN,
         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.
@@ -377,6 +378,9 @@ def question(
 
           question: The question to answer using the Knowledge Graph.
 
+          query_config: Configuration options for Knowledge Graph queries, including search parameters
+              and citation settings.
+
           stream: Determines whether the model's output should be streamed. If true, the output is
               generated and sent incrementally, which can be useful for real-time
               applications.
@@ -400,6 +404,7 @@ def question(
         graph_ids: SequenceNotStr[str],
         question: str,
         stream: Literal[True],
+        query_config: graph_question_params.QueryConfig | 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.
@@ -420,6 +425,9 @@ def question(
               generated and sent incrementally, which can be useful for real-time
               applications.
 
+          query_config: Configuration options for Knowledge Graph queries, including search parameters
+              and citation settings.
+
           subqueries: Specify whether to include subqueries.
 
           extra_headers: Send extra headers
@@ -439,6 +447,7 @@ def question(
         graph_ids: SequenceNotStr[str],
         question: str,
         stream: bool,
+        query_config: graph_question_params.QueryConfig | 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.
@@ -459,6 +468,9 @@ def question(
               generated and sent incrementally, which can be useful for real-time
               applications.
 
+          query_config: Configuration options for Knowledge Graph queries, including search parameters
+              and citation settings.
+
           subqueries: Specify whether to include subqueries.
 
           extra_headers: Send extra headers
@@ -477,6 +489,7 @@ def question(
         *,
         graph_ids: SequenceNotStr[str],
         question: str,
+        query_config: graph_question_params.QueryConfig | NotGiven = NOT_GIVEN,
         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.
@@ -492,6 +505,7 @@ def question(
                 {
                     "graph_ids": graph_ids,
                     "question": question,
+                    "query_config": query_config,
                     "stream": stream,
                     "subqueries": subqueries,
                 },
@@ -867,6 +881,7 @@ async def question(
         *,
         graph_ids: SequenceNotStr[str],
         question: str,
+        query_config: graph_question_params.QueryConfig | NotGiven = NOT_GIVEN,
         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.
@@ -884,6 +899,9 @@ async def question(
 
           question: The question to answer using the Knowledge Graph.
 
+          query_config: Configuration options for Knowledge Graph queries, including search parameters
+              and citation settings.
+
           stream: Determines whether the model's output should be streamed. If true, the output is
               generated and sent incrementally, which can be useful for real-time
               applications.
@@ -907,6 +925,7 @@ async def question(
         graph_ids: SequenceNotStr[str],
         question: str,
         stream: Literal[True],
+        query_config: graph_question_params.QueryConfig | 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.
@@ -927,6 +946,9 @@ async def question(
               generated and sent incrementally, which can be useful for real-time
               applications.
 
+          query_config: Configuration options for Knowledge Graph queries, including search parameters
+              and citation settings.
+
           subqueries: Specify whether to include subqueries.
 
           extra_headers: Send extra headers
@@ -946,6 +968,7 @@ async def question(
         graph_ids: SequenceNotStr[str],
         question: str,
         stream: bool,
+        query_config: graph_question_params.QueryConfig | 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.
@@ -966,6 +989,9 @@ async def question(
               generated and sent incrementally, which can be useful for real-time
               applications.
 
+          query_config: Configuration options for Knowledge Graph queries, including search parameters
+              and citation settings.
+
           subqueries: Specify whether to include subqueries.
 
           extra_headers: Send extra headers
@@ -984,6 +1010,7 @@ async def question(
         *,
         graph_ids: SequenceNotStr[str],
         question: str,
+        query_config: graph_question_params.QueryConfig | NotGiven = NOT_GIVEN,
         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.
@@ -999,6 +1026,7 @@ async def question(
                 {
                     "graph_ids": graph_ids,
                     "question": question,
+                    "query_config": query_config,
                     "stream": stream,
                     "subqueries": subqueries,
                 },

src/writerai/types/graph_question_params.py

@@ -7,7 +7,7 @@
 
 from .._types import SequenceNotStr
 
-__all__ = ["GraphQuestionParamsBase", "GraphQuestionParamsNonStreaming", "GraphQuestionParamsStreaming"]
+__all__ = ["GraphQuestionParamsBase", "QueryConfig", "GraphQuestionParamsNonStreaming", "GraphQuestionParamsStreaming"]
 
 
 class GraphQuestionParamsBase(TypedDict, total=False):
@@ -17,10 +17,83 @@ class GraphQuestionParamsBase(TypedDict, total=False):
     question: Required[str]
     """The question to answer using the Knowledge Graph."""
 
+    query_config: QueryConfig
+    """
+    Configuration options for Knowledge Graph queries, including search parameters
+    and citation settings.
+    """
+
     subqueries: bool
     """Specify whether to include subqueries."""
 
 
+class QueryConfig(TypedDict, total=False):
+    grounding_level: float
+    """
+    Level of grounding required for responses, controlling how closely answers must
+    be tied to source material. Set lower for grounded outputs, higher for
+    creativity. Higher values (closer to 1.0) allow more creative interpretation,
+    while lower values (closer to 0.0) stick more closely to source material. Range:
+    0.0-1.0, Default: 0.0.
+    """
+
+    inline_citations: bool
+    """
+    Whether to include inline citations in the response, showing which Knowledge
+    Graph sources were used. Default: false.
+    """
+
+    keyword_threshold: float
+    """Threshold for keyword-based matching when searching Knowledge Graph content.
+
+    Set higher for stricter relevance, lower for broader range. Higher values
+    (closer to 1.0) require stronger keyword matches, while lower values (closer to
+    0.0) allow more lenient matching. Range: 0.0-1.0, Default: 0.7.
+    """
+
+    max_snippets: int
+    """Maximum number of text snippets to retrieve from the Knowledge Graph for
+    context.
+
+    Works in concert with `search_weight` to control best matches vs broader
+    coverage. While technically supports 1-60, values below 5 may return no results
+    due to RAG implementation. Recommended range: 5-25. Due to RAG system behavior,
+    you may see more snippets than requested. Range: 1-60, Default: 30.
+    """
+
+    max_subquestions: int
+    """Maximum number of subquestions to generate when processing complex queries.
+
+    Set higher to improve detail, set lower to reduce response time. Range: 1-10,
+    Default: 6.
+    """
+
+    max_tokens: int
+    """Maximum number of tokens the model can generate in the response.
+
+    This controls the length of the AI's answer. Set higher for longer answers, set
+    lower for shorter, faster answers. Range: 100-8000, Default: 4000.
+    """
+
+    search_weight: int
+    """Weight given to search results when ranking and selecting relevant information.
+
+    Higher values (closer to 100) prioritize keyword-based matching, while lower
+    values (closer to 0) prioritize semantic similarity matching. Use higher values
+    for exact keyword searches, lower values for conceptual similarity searches.
+    Range: 0-100, Default: 50.
+    """
+
+    semantic_threshold: float
+    """
+    Threshold for semantic similarity matching when searching Knowledge Graph
+    content. Set higher for stricter relevance, lower for broader range. Higher
+    values (closer to 1.0) require stronger semantic similarity, while lower values
+    (closer to 0.0) allow more lenient semantic matching. Range: 0.0-1.0, Default:
+    0.7.
+    """
+
+
 class GraphQuestionParamsNonStreaming(GraphQuestionParamsBase, total=False):
     stream: Literal[False]
     """Determines whether the model's output should be streamed.

src/writerai/types/question.py

@@ -2,20 +2,77 @@
 
 from typing import List, Optional
 
+from pydantic import Field as FieldInfo
+
 from .._models import BaseModel
 from .shared.source import Source
 
-__all__ = ["Question", "Subquery"]
+__all__ = ["Question", "References", "ReferencesFile", "ReferencesWeb", "Subquery"]
+
+
+class ReferencesFile(BaseModel):
+    file_id: str = FieldInfo(alias="fileId")
+    """The unique identifier of the file in your Writer account."""
+
+    score: float
+    """
+    Internal score used during the retrieval process for ranking and selecting
+    relevant snippets.
+    """
+
+    text: str
+    """
+    The exact text snippet from the source document that was used to support the
+    response.
+    """
+
+    cite: Optional[str] = None
+    """
+    Unique citation ID that appears in inline citations within the response text
+    (null if not cited).
+    """
+
+    page: Optional[int] = None
+    """Page number where this snippet was found in the source document."""
+
+
+class ReferencesWeb(BaseModel):
+    score: float
+    """
+    Internal score used during the retrieval process for ranking and selecting
+    relevant snippets.
+    """
+
+    text: str
+    """
+    The exact text snippet from the web source that was used to support the
+    response.
+    """
+
+    title: str
+    """The title of the web page where this content was found."""
+
+    url: str
+    """The URL of the web page where this content was found."""
+
+
+class References(BaseModel):
+    files: Optional[List[ReferencesFile]] = None
+    """Array of file-based references from uploaded documents in the Knowledge Graph."""
+
+    web: Optional[List[ReferencesWeb]] = None
+    """Array of web-based references from online sources accessed during the query."""
 
 
 class Subquery(BaseModel):
     answer: str
-    """The answer to the subquery."""
+    """The answer to the subquery based on Knowledge Graph content."""
 
     query: str
-    """The subquery that was asked."""
+    """The subquery that was generated to help answer the main question."""
 
     sources: List[Optional[Source]]
+    """Array of source snippets that were used to answer this subquery."""
 
 
 class Question(BaseModel):
@@ -27,4 +84,10 @@ class Question(BaseModel):
 
     sources: List[Optional[Source]]
 
+    references: Optional[References] = None
+    """
+    Detailed source information organized by reference type, providing comprehensive
+    metadata about the sources used to generate the response.
+    """
+
     subqueries: Optional[List[Optional[Subquery]]] = None

src/writerai/types/shared/graph_data.py

@@ -11,12 +11,13 @@
 
 class Subquery(BaseModel):
     answer: str
-    """The answer to the subquery."""
+    """The answer to the subquery based on Knowledge Graph content."""
 
     query: str
-    """The subquery that was asked."""
+    """The subquery that was generated to help answer the main question."""
 
     sources: List[Optional[Source]]
+    """Array of source snippets that were used to answer this subquery."""
 
 
 class GraphData(BaseModel):

src/writerai/types/shared/source.py

@@ -7,7 +7,10 @@
 
 class Source(BaseModel):
     file_id: str
-    """The unique identifier of the file."""
+    """The unique identifier of the file in your Writer account."""
 
     snippet: str
-    """A snippet of text from the source file."""
+    """
+    The exact text snippet from the source document that was used to support the
+    response.
+    """