Skip to content

Commit fe26f83

Browse files
stainless-app[bot]stainless-app[bot]
committed
docs(api): updates to API spec
1 parent 279d7df commit fe26f83

9 files changed

Lines changed: 176 additions & 50 deletions

File tree

‎.stats.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
configured_endpoints: 32
2-
openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-994b51f2c7c776c2cd3d4e3c6900cc6291da87296cea27921ec709a459a41034.yml
3-
openapi_spec_hash: 1fdc6bb31a5464cebb4c579370764907
2+
openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/writerai%2Fwriter-d4a152368a86404e58ce6fdf8966223006e5b4a15dbda4a3bb46ee331d57781d.yml
3+
openapi_spec_hash: e951797c0506d6c69e0e2578d3dcf2db
44
config_hash: c0c9f57ab19252f82cf765939edc61de

‎src/writerai/resources/completions.py‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -66,8 +66,10 @@ def create(
6666
extra_body: Body | None = None,
6767
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
6868
) -> Completion:
69-
"""
70-
Text generation
69+
"""Generate text completions using the specified model and prompt.
70+
71+
This endpoint is
72+
useful for text generation tasks that don't require conversational context.
7173
7274
Args:
7375
model: The [ID of the model](https://dev.writer.com/home/models) to use for generating
@@ -129,8 +131,10 @@ def create(
129131
extra_body: Body | None = None,
130132
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
131133
) -> Stream[CompletionChunk]:
132-
"""
133-
Text generation
134+
"""Generate text completions using the specified model and prompt.
135+
136+
This endpoint is
137+
useful for text generation tasks that don't require conversational context.
134138
135139
Args:
136140
model: The [ID of the model](https://dev.writer.com/home/models) to use for generating
@@ -192,8 +196,10 @@ def create(
192196
extra_body: Body | None = None,
193197
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
194198
) -> Completion | Stream[CompletionChunk]:
195-
"""
196-
Text generation
199+
"""Generate text completions using the specified model and prompt.
200+
201+
This endpoint is
202+
useful for text generation tasks that don't require conversational context.
197203
198204
Args:
199205
model: The [ID of the model](https://dev.writer.com/home/models) to use for generating
@@ -322,8 +328,10 @@ async def create(
322328
extra_body: Body | None = None,
323329
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
324330
) -> Completion:
325-
"""
326-
Text generation
331+
"""Generate text completions using the specified model and prompt.
332+
333+
This endpoint is
334+
useful for text generation tasks that don't require conversational context.
327335
328336
Args:
329337
model: The [ID of the model](https://dev.writer.com/home/models) to use for generating
@@ -385,8 +393,10 @@ async def create(
385393
extra_body: Body | None = None,
386394
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
387395
) -> AsyncStream[CompletionChunk]:
388-
"""
389-
Text generation
396+
"""Generate text completions using the specified model and prompt.
397+
398+
This endpoint is
399+
useful for text generation tasks that don't require conversational context.
390400
391401
Args:
392402
model: The [ID of the model](https://dev.writer.com/home/models) to use for generating
@@ -448,8 +458,10 @@ async def create(
448458
extra_body: Body | None = None,
449459
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
450460
) -> Completion | AsyncStream[CompletionChunk]:
451-
"""
452-
Text generation
461+
"""Generate text completions using the specified model and prompt.
462+
463+
This endpoint is
464+
useful for text generation tasks that don't require conversational context.
453465
454466
Args:
455467
model: The [ID of the model](https://dev.writer.com/home/models) to use for generating

‎src/writerai/resources/files.py‎

Lines changed: 42 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,8 @@ def retrieve(
6767
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
6868
) -> File:
6969
"""
70-
Retrieve file
70+
Retrieve detailed information about a specific file, including its metadata,
71+
status, and associated graphs.
7172
7273
Args:
7374
extra_headers: Send extra headers
@@ -105,12 +106,12 @@ def list(
105106
extra_body: Body | None = None,
106107
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
107108
) -> SyncCursorPage[File]:
108-
"""List files
109+
"""
110+
Retrieve a paginated list of files with optional filtering by status, graph
111+
association, and file type.
109112
110113
Args:
111-
after: The ID of the last object in the previous page.
112-
113-
This parameter instructs the API
114+
after: The ID of the last object in the previous page. This parameter instructs the API
114115
to return the next page of results.
115116
116117
before: The ID of the first object in the previous page. This parameter instructs the
@@ -173,8 +174,9 @@ def delete(
173174
extra_body: Body | None = None,
174175
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
175176
) -> FileDeleteResponse:
176-
"""
177-
Delete file
177+
"""Permanently delete a file from the system.
178+
179+
This action cannot be undone.
178180
179181
Args:
180182
extra_headers: Send extra headers
@@ -206,8 +208,10 @@ def download(
206208
extra_body: Body | None = None,
207209
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
208210
) -> BinaryAPIResponse:
209-
"""
210-
Download file
211+
"""Download the binary content of a file.
212+
213+
The response will contain the file data
214+
in the appropriate MIME type.
211215
212216
Args:
213217
extra_headers: Send extra headers
@@ -240,8 +244,10 @@ def retry(
240244
extra_body: Body | None = None,
241245
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
242246
) -> FileRetryResponse:
243-
"""
244-
Retry failed files
247+
"""Retry processing of files that previously failed to process.
248+
249+
This will
250+
re-attempt the processing of the specified files.
245251
246252
Args:
247253
file_ids: The unique identifier of the files to retry.
@@ -276,8 +282,10 @@ def upload(
276282
extra_body: Body | None = None,
277283
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
278284
) -> File:
279-
"""
280-
Upload file
285+
"""Upload a new file to the system.
286+
287+
Supports various file formats including PDF,
288+
DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, and XLSX.
281289
282290
Args:
283291
extra_headers: Send extra headers
@@ -335,7 +343,8 @@ async def retrieve(
335343
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
336344
) -> File:
337345
"""
338-
Retrieve file
346+
Retrieve detailed information about a specific file, including its metadata,
347+
status, and associated graphs.
339348
340349
Args:
341350
extra_headers: Send extra headers
@@ -373,12 +382,12 @@ def list(
373382
extra_body: Body | None = None,
374383
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
375384
) -> AsyncPaginator[File, AsyncCursorPage[File]]:
376-
"""List files
385+
"""
386+
Retrieve a paginated list of files with optional filtering by status, graph
387+
association, and file type.
377388
378389
Args:
379-
after: The ID of the last object in the previous page.
380-
381-
This parameter instructs the API
390+
after: The ID of the last object in the previous page. This parameter instructs the API
382391
to return the next page of results.
383392
384393
before: The ID of the first object in the previous page. This parameter instructs the
@@ -441,8 +450,9 @@ async def delete(
441450
extra_body: Body | None = None,
442451
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
443452
) -> FileDeleteResponse:
444-
"""
445-
Delete file
453+
"""Permanently delete a file from the system.
454+
455+
This action cannot be undone.
446456
447457
Args:
448458
extra_headers: Send extra headers
@@ -474,8 +484,10 @@ async def download(
474484
extra_body: Body | None = None,
475485
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
476486
) -> AsyncBinaryAPIResponse:
477-
"""
478-
Download file
487+
"""Download the binary content of a file.
488+
489+
The response will contain the file data
490+
in the appropriate MIME type.
479491
480492
Args:
481493
extra_headers: Send extra headers
@@ -508,8 +520,10 @@ async def retry(
508520
extra_body: Body | None = None,
509521
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
510522
) -> FileRetryResponse:
511-
"""
512-
Retry failed files
523+
"""Retry processing of files that previously failed to process.
524+
525+
This will
526+
re-attempt the processing of the specified files.
513527
514528
Args:
515529
file_ids: The unique identifier of the files to retry.
@@ -544,8 +558,10 @@ async def upload(
544558
extra_body: Body | None = None,
545559
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
546560
) -> File:
547-
"""
548-
Upload file
561+
"""Upload a new file to the system.
562+
563+
Supports various file formats including PDF,
564+
DOC, DOCX, PPT, PPTX, JPG, PNG, EML, HTML, SRT, CSV, XLS, and XLSX.
549565
550566
Args:
551567
extra_headers: Send extra headers

‎src/writerai/resources/models.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,10 @@ def list(
4949
extra_body: Body | None = None,
5050
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
5151
) -> ModelListResponse:
52-
"""List models"""
52+
"""
53+
Retrieve a list of available models that can be used for text generation, chat
54+
completions, and other AI tasks.
55+
"""
5356
return self._get(
5457
"/v1/models",
5558
options=make_request_options(
@@ -89,7 +92,10 @@ async def list(
8992
extra_body: Body | None = None,
9093
timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
9194
) -> ModelListResponse:
92-
"""List models"""
95+
"""
96+
Retrieve a list of available models that can be used for text generation, chat
97+
completions, and other AI tasks.
98+
"""
9399
return await self._get(
94100
"/v1/models",
95101
options=make_request_options(

‎src/writerai/types/chat_chat_params.py‎

Lines changed: 44 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
__all__ = [
1515
"ChatChatParamsBase",
1616
"Message",
17+
"MessageContentUnionMember1",
18+
"MessageContentUnionMember1TextFragment",
19+
"MessageContentUnionMember1ImageFragment",
20+
"MessageContentUnionMember1ImageFragmentImageURL",
1721
"ResponseFormat",
1822
"StreamOptions",
1923
"ToolChoice",
@@ -116,6 +120,35 @@ class ChatChatParamsBase(TypedDict, total=False):
116120
"""
117121

118122

123+
class MessageContentUnionMember1TextFragment(TypedDict, total=False):
124+
text: Required[str]
125+
"""The actual text content of the message fragment."""
126+
127+
type: Required[Literal["text"]]
128+
"""The type of content fragment. Must be `text` for text fragments."""
129+
130+
131+
class MessageContentUnionMember1ImageFragmentImageURL(TypedDict, total=False):
132+
url: Required[str]
133+
"""The URL pointing to the image file.
134+
135+
Supports common image formats like JPEG, PNG, GIF, etc.
136+
"""
137+
138+
139+
class MessageContentUnionMember1ImageFragment(TypedDict, total=False):
140+
image_url: Required[MessageContentUnionMember1ImageFragmentImageURL]
141+
"""The image URL object containing the location of the image."""
142+
143+
type: Required[Literal["image_url"]]
144+
"""The type of content fragment. Must be `image_url` for image fragments."""
145+
146+
147+
MessageContentUnionMember1: TypeAlias = Union[
148+
MessageContentUnionMember1TextFragment, MessageContentUnionMember1ImageFragment
149+
]
150+
151+
119152
class Message(TypedDict, total=False):
120153
role: Required[Literal["user", "assistant", "system", "tool"]]
121154
"""The role of the chat message.
@@ -126,11 +159,21 @@ class Message(TypedDict, total=False):
126159
`tool`.
127160
"""
128161

129-
content: Optional[str]
162+
content: Union[str, Iterable[MessageContentUnionMember1], None]
163+
"""The content of the message.
164+
165+
Can be either a string (for text-only messages) or an array of content fragments
166+
(for mixed text and image messages).
167+
"""
130168

131169
graph_data: Optional[GraphData]
132170

133171
name: Optional[str]
172+
"""An optional name for the message sender.
173+
174+
Useful for identifying different users, personas, or tools in multi-participant
175+
conversations.
176+
"""
134177

135178
refusal: Optional[str]
136179

‎src/writerai/types/chat_completion_message.py‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
from .shared.tool_call import ToolCall
88
from .shared.graph_data import GraphData
99

10-
__all__ = ["ChatCompletionMessage", "LlmData", "TranslationData"]
10+
__all__ = ["ChatCompletionMessage", "LlmData", "TranslationData", "WebSearchData", "WebSearchDataSource"]
1111

1212

1313
class LlmData(BaseModel):
@@ -29,6 +29,16 @@ class TranslationData(BaseModel):
2929
"""The language code of the target text."""
3030

3131

32+
class WebSearchDataSource(BaseModel):
33+
raw_content: Optional[str] = None
34+
35+
url: Optional[str] = None
36+
37+
38+
class WebSearchData(BaseModel):
39+
sources: List[WebSearchDataSource]
40+
41+
3242
class ChatCompletionMessage(BaseModel):
3343
content: str
3444
"""The text content produced by the model.
@@ -49,3 +59,5 @@ class ChatCompletionMessage(BaseModel):
4959
tool_calls: Optional[List[ToolCall]] = None
5060

5161
translation_data: Optional[TranslationData] = None
62+
63+
web_search_data: Optional[WebSearchData] = None

0 commit comments

Comments
 (0)