You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Parallel Python library provides convenient access to the Parallel REST API from any Python 3.8+
6
6
application. The library includes type definitions for all request params and response fields,
7
7
and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
8
+
It is strongly encouraged to use the asynchronous client for best performance.
8
9
9
10
It is generated with [Stainless](https://www.stainless.com/).
10
11
11
12
## Documentation
12
13
13
-
The REST API documentation can be found on [docs.parallel.ai](https://docs.parallel.ai). The full API of this library can be found in [api.md](api.md).
14
+
The REST API documentation can be found on our [docs](https://docs.parallel.ai).
15
+
The full API of this Python library can be found in [api.md](api.md).
14
16
15
17
## Installation
16
18
@@ -34,11 +36,12 @@ client = Parallel(
34
36
api_key=os.environ.get("PARALLEL_API_KEY"), # This is the default and can be omitted
35
37
)
36
38
37
-
task_run= client.task_run.create(
39
+
run_result= client.task_run.execute(
38
40
input="France (2023)",
39
-
processor="processor",
41
+
processor="core",
42
+
output="GDP"
40
43
)
41
-
print(task_run.run_id)
44
+
print(run_result.output)
42
45
```
43
46
44
47
While you can provide an `api_key` keyword argument,
@@ -61,33 +64,133 @@ client = AsyncParallel(
61
64
62
65
63
66
asyncdefmain() -> None:
64
-
task_run=await client.task_run.create(
67
+
run_result=await client.task_run.execute(
65
68
input="France (2023)",
66
-
processor="processor",
69
+
processor="core",
70
+
output="GDP"
67
71
)
68
-
print(task_run.run_id)
72
+
print(run_result.output)
69
73
70
74
71
-
asyncio.run(main())
75
+
if__name__=="__main__":
76
+
asyncio.run(main())
72
77
```
73
78
74
-
Functionality between the synchronous and asynchronous clients is otherwise identical.
79
+
To get the best performance out of Parallel's API, we recommend
80
+
using the asynchronous client, especially for executing multiple Task Runs concurrently.
81
+
Functionality between the synchronous and asynchronous clients is identical.
75
82
76
-
## Using types
83
+
## Convenience methods
77
84
78
-
Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also provide helper methods for things like:
85
+
### Execute
79
86
80
-
- Serializing back into JSON, `model.to_json()`
81
-
- Converting to a dictionary, `model.to_dict()`
87
+
The `execute` method provides a single call which combines creating a task run,
88
+
polling until it is completed, and parsing structured outputs (if specified).
82
89
83
-
Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
90
+
If an output type which inherits from `BaseModel` is
91
+
specified in the call to `.execute()`, the response content will be parsed into an
92
+
instance of the provided output type. The parsed output can be accessed via the
93
+
`parsed` property on the output field of the response.
84
94
85
-
## Nested params
95
+
```python
96
+
import os
97
+
import asyncio
98
+
from parallel import AsyncParallel
99
+
from pydantic import BaseModel
86
100
87
-
Nested parameters are dictionaries, typed using `TypedDict`, for example:
101
+
client = AsyncParallel()
102
+
103
+
classSampleOutputStructure(BaseModel):
104
+
output: str
105
+
106
+
asyncdefmain() -> None:
107
+
# with pydantic
108
+
run_result =await client.task_run.execute(
109
+
input="France (2023)",
110
+
processor="core",
111
+
output=SampleOutputStructure,
112
+
)
113
+
# parsed output of type SampleOutputStructure
114
+
print(run_result.output.parsed)
115
+
# without pydantic
116
+
run_result =await client.task_run.execute(
117
+
input="France (2023)",
118
+
processor="core",
119
+
output="GDP"
120
+
)
121
+
print(run_result.output)
122
+
123
+
124
+
if__name__=="__main__":
125
+
asyncio.run(main())
126
+
```
127
+
128
+
The async client allows creating several task runs without blocking.
129
+
To create multiple task runs in one go, call execute and then gather the results at the end.
130
+
131
+
```python
132
+
import asyncio
133
+
import os
134
+
135
+
from parallel import AsyncParallel
136
+
from pydantic import BaseModel, Field
137
+
from typing import List
138
+
139
+
classCountryInput(BaseModel):
140
+
country: str= Field(
141
+
description="Name of the country to research. Must be a recognized "
142
+
"sovereign nation (e.g., 'France', 'Japan')."
143
+
)
144
+
year: int= Field(
145
+
description="Year for which to retrieve data. Must be 2000 or later. "
146
+
"Use most recent full-year estimates if year is current."
147
+
)
148
+
149
+
classCountryOutput(BaseModel):
150
+
gdp: str= Field(
151
+
description="GDP in USD for the year, formatted like '$3.1 trillion (2023)'."
152
+
)
153
+
top_exports: List[str] = Field(
154
+
description="Top 3 exported goods/services by value. Use credible sources."
155
+
)
156
+
top_imports: List[str] = Field(
157
+
description="Top 3 imported goods/services by value. Use credible sources."
When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `parallel.APIConnectionError` is raised.
@@ -144,9 +254,10 @@ from parallel import Parallel
task_run = response.parse() # get the object that `task_run.create()` would have returned
270
-
print(task_run.run_id)
383
+
task_run = response.parse() # get the object that `task_run.execute()` would have returned
384
+
print(task_run.output)
271
385
```
272
386
273
387
These methods return an [`APIResponse`](https://github.com/shapleyai/parallel-sdk-python/tree/main/src/parallel/_response.py) object.
@@ -281,9 +395,10 @@ The above interface eagerly reads the full response body when you make the reque
281
395
To stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods.
282
396
283
397
```python
284
-
with client.task_run.with_streaming_response.create(
398
+
with client.task_run.with_streaming_response.execute(
0 commit comments