Skip to content

Commit 653bc8c

Browse files
author
stlc-bot
committed
feat(answers): add live web research with fast and ultra modes (#954)
Stainless-Generated-From: 09ae3a2
1 parent 85ac787 commit 653bc8c

7 files changed

Lines changed: 328 additions & 1 deletion

File tree

‎.stats.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
configured_endpoints: 47
1+
configured_endpoints: 48

‎api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Types:
1616

1717
```python
1818
from context.dev.types import (
19+
WebAnswersResponse,
1920
WebExtractResponse,
2021
WebExtractCompetitorsResponse,
2122
WebExtractFontsResponse,
@@ -32,6 +33,7 @@ from context.dev.types import (
3233

3334
Methods:
3435

36+
- <code title="post /web/answers">client.web.<a href="./src/context/dev/resources/web.py">answers</a>(\*\*<a href="src/context/dev/types/web_answers_params.py">params</a>) -> <a href="./src/context/dev/types/web_answers_response.py">WebAnswersResponse</a></code>
3537
- <code title="post /web/extract">client.web.<a href="./src/context/dev/resources/web.py">extract</a>(\*\*<a href="src/context/dev/types/web_extract_params.py">params</a>) -> <a href="./src/context/dev/types/web_extract_response.py">WebExtractResponse</a></code>
3638
- <code title="get /web/competitors">client.web.<a href="./src/context/dev/resources/web.py">extract_competitors</a>(\*\*<a href="src/context/dev/types/web_extract_competitors_params.py">params</a>) -> <a href="./src/context/dev/types/web_extract_competitors_response.py">WebExtractCompetitorsResponse</a></code>
3739
- <code title="get /web/fonts">client.web.<a href="./src/context/dev/resources/web.py">extract_fonts</a>(\*\*<a href="src/context/dev/types/web_extract_fonts_params.py">params</a>) -> <a href="./src/context/dev/types/web_extract_fonts_response.py">WebExtractFontsResponse</a></code>

‎src/context/dev/resources/web.py‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
from ..types import (
1111
web_search_params,
12+
web_answers_params,
1213
web_extract_params,
1314
web_screenshot_params,
1415
web_web_crawl_md_params,
@@ -32,6 +33,7 @@
3233
)
3334
from .._base_client import make_request_options
3435
from ..types.web_search_response import WebSearchResponse
36+
from ..types.web_answers_response import WebAnswersResponse
3537
from ..types.web_extract_response import WebExtractResponse
3638
from ..types.web_screenshot_response import WebScreenshotResponse
3739
from ..types.web_web_crawl_md_response import WebWebCrawlMdResponse
@@ -66,6 +68,73 @@ def with_streaming_response(self) -> WebResourceWithStreamingResponse:
6668
"""
6769
return WebResourceWithStreamingResponse(self)
6870

71+
def answers(
72+
self,
73+
*,
74+
task: str,
75+
json_format: Dict[str, object] | Omit = omit,
76+
mode: Literal["fast", "ultra"] | Omit = omit,
77+
tags: SequenceNotStr[str] | Omit = omit,
78+
timeout_ms: int | Omit = omit,
79+
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
80+
# The extra values given here take precedence over values defined on the client or passed to this method.
81+
extra_headers: Headers | None = None,
82+
extra_query: Query | None = None,
83+
extra_body: Body | None = None,
84+
timeout: float | httpx.Timeout | None | NotGiven = not_given,
85+
) -> WebAnswersResponse:
86+
"""
87+
Researches the live web and returns a sourced answer in your requested JSON
88+
shape. Select fast for a smaller research budget at 10 credits or ultra for
89+
deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to
90+
30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline.
91+
92+
Args:
93+
task: What to research and answer, in plain language. Naming a domain in the task (for
94+
example "pricing on context.dev") makes the agent read that site before it
95+
searches.
96+
97+
json_format: An example object with placeholder values (for example {"pricing_page_url": "",
98+
"plans": [{"name": "", "price": 0}]}). Object keys and value types are
99+
preserved; unknown values may be null. Empty arrays accept any JSON items.
100+
Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters.
101+
102+
mode: Research level: fast uses a smaller model and research budget for 10 credits;
103+
ultra uses deeper reasoning and research for 100 credits. Defaults to ultra.
104+
Only successful requests consume credits.
105+
106+
tags: Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
107+
108+
timeout_ms: Optional timeout in milliseconds for the request. If the request takes longer
109+
than this value, it will be aborted with a 408 status code. Maximum allowed
110+
value is 300000ms (5 minutes).
111+
112+
extra_headers: Send extra headers
113+
114+
extra_query: Add additional query parameters to the request
115+
116+
extra_body: Add additional JSON properties to the request
117+
118+
timeout: Override the client-level default timeout for this request, in seconds
119+
"""
120+
return self._post(
121+
"/web/answers",
122+
body=maybe_transform(
123+
{
124+
"task": task,
125+
"json_format": json_format,
126+
"mode": mode,
127+
"tags": tags,
128+
"timeout_ms": timeout_ms,
129+
},
130+
web_answers_params.WebAnswersParams,
131+
),
132+
options=make_request_options(
133+
extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
134+
),
135+
cast_to=WebAnswersResponse,
136+
)
137+
69138
def extract(
70139
self,
71140
*,
@@ -2321,6 +2390,73 @@ def with_streaming_response(self) -> AsyncWebResourceWithStreamingResponse:
23212390
"""
23222391
return AsyncWebResourceWithStreamingResponse(self)
23232392

2393+
async def answers(
2394+
self,
2395+
*,
2396+
task: str,
2397+
json_format: Dict[str, object] | Omit = omit,
2398+
mode: Literal["fast", "ultra"] | Omit = omit,
2399+
tags: SequenceNotStr[str] | Omit = omit,
2400+
timeout_ms: int | Omit = omit,
2401+
# Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
2402+
# The extra values given here take precedence over values defined on the client or passed to this method.
2403+
extra_headers: Headers | None = None,
2404+
extra_query: Query | None = None,
2405+
extra_body: Body | None = None,
2406+
timeout: float | httpx.Timeout | None | NotGiven = not_given,
2407+
) -> WebAnswersResponse:
2408+
"""
2409+
Researches the live web and returns a sourced answer in your requested JSON
2410+
shape. Select fast for a smaller research budget at 10 credits or ultra for
2411+
deeper reasoning at 100 credits. Defaults to ultra. Fast research is limited to
2412+
30 seconds and ultra to 50 seconds; timeoutMS can shorten either deadline.
2413+
2414+
Args:
2415+
task: What to research and answer, in plain language. Naming a domain in the task (for
2416+
example "pricing on context.dev") makes the agent read that site before it
2417+
searches.
2418+
2419+
json_format: An example object with placeholder values (for example {"pricing_page_url": "",
2420+
"plans": [{"name": "", "price": 0}]}). Object keys and value types are
2421+
preserved; unknown values may be null. Empty arrays accept any JSON items.
2422+
Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters.
2423+
2424+
mode: Research level: fast uses a smaller model and research budget for 10 credits;
2425+
ultra uses deeper reasoning and research for 100 credits. Defaults to ultra.
2426+
Only successful requests consume credits.
2427+
2428+
tags: Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters.
2429+
2430+
timeout_ms: Optional timeout in milliseconds for the request. If the request takes longer
2431+
than this value, it will be aborted with a 408 status code. Maximum allowed
2432+
value is 300000ms (5 minutes).
2433+
2434+
extra_headers: Send extra headers
2435+
2436+
extra_query: Add additional query parameters to the request
2437+
2438+
extra_body: Add additional JSON properties to the request
2439+
2440+
timeout: Override the client-level default timeout for this request, in seconds
2441+
"""
2442+
return await self._post(
2443+
"/web/answers",
2444+
body=await async_maybe_transform(
2445+
{
2446+
"task": task,
2447+
"json_format": json_format,
2448+
"mode": mode,
2449+
"tags": tags,
2450+
"timeout_ms": timeout_ms,
2451+
},
2452+
web_answers_params.WebAnswersParams,
2453+
),
2454+
options=make_request_options(
2455+
extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
2456+
),
2457+
cast_to=WebAnswersResponse,
2458+
)
2459+
23242460
async def extract(
23252461
self,
23262462
*,
@@ -4560,6 +4696,9 @@ class WebResourceWithRawResponse:
45604696
def __init__(self, web: WebResource) -> None:
45614697
self._web = web
45624698

4699+
self.answers = to_raw_response_wrapper(
4700+
web.answers,
4701+
)
45634702
self.extract = to_raw_response_wrapper(
45644703
web.extract,
45654704
)
@@ -4599,6 +4738,9 @@ class AsyncWebResourceWithRawResponse:
45994738
def __init__(self, web: AsyncWebResource) -> None:
46004739
self._web = web
46014740

4741+
self.answers = async_to_raw_response_wrapper(
4742+
web.answers,
4743+
)
46024744
self.extract = async_to_raw_response_wrapper(
46034745
web.extract,
46044746
)
@@ -4638,6 +4780,9 @@ class WebResourceWithStreamingResponse:
46384780
def __init__(self, web: WebResource) -> None:
46394781
self._web = web
46404782

4783+
self.answers = to_streamed_response_wrapper(
4784+
web.answers,
4785+
)
46414786
self.extract = to_streamed_response_wrapper(
46424787
web.extract,
46434788
)
@@ -4677,6 +4822,9 @@ class AsyncWebResourceWithStreamingResponse:
46774822
def __init__(self, web: AsyncWebResource) -> None:
46784823
self._web = web
46794824

4825+
self.answers = async_to_streamed_response_wrapper(
4826+
web.answers,
4827+
)
46804828
self.extract = async_to_streamed_response_wrapper(
46814829
web.extract,
46824830
)

‎src/context/dev/types/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
from .web_search_params import WebSearchParams as WebSearchParams
1515
from .news_search_params import NewsSearchParams as NewsSearchParams
1616
from .retry_config_param import RetryConfigParam as RetryConfigParam
17+
from .web_answers_params import WebAnswersParams as WebAnswersParams
1718
from .web_extract_params import WebExtractParams as WebExtractParams
1819
from .batch_list_response import BatchListResponse as BatchListResponse
1920
from .batch_submit_params import BatchSubmitParams as BatchSubmitParams
@@ -24,6 +25,7 @@
2425
from .monitor_run_response import MonitorRunResponse as MonitorRunResponse
2526
from .news_search_response import NewsSearchResponse as NewsSearchResponse
2627
from .person_enrich_params import PersonEnrichParams as PersonEnrichParams
28+
from .web_answers_response import WebAnswersResponse as WebAnswersResponse
2729
from .web_extract_response import WebExtractResponse as WebExtractResponse
2830
from .batch_cancel_response import BatchCancelResponse as BatchCancelResponse
2931
from .batch_delete_response import BatchDeleteResponse as BatchDeleteResponse

‎src/context/dev/types/web_answers_params.py‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2+
3+
from __future__ import annotations
4+
5+
from typing import Dict
6+
from typing_extensions import Literal, Required, Annotated, TypedDict
7+
8+
from .._types import SequenceNotStr
9+
from .._utils import PropertyInfo
10+
11+
__all__ = ["WebAnswersParams"]
12+
13+
14+
class WebAnswersParams(TypedDict, total=False):
15+
task: Required[str]
16+
"""What to research and answer, in plain language.
17+
18+
Naming a domain in the task (for example "pricing on context.dev") makes the
19+
agent read that site before it searches.
20+
"""
21+
22+
json_format: Dict[str, object]
23+
"""
24+
An example object with placeholder values (for example {"pricing_page_url": "",
25+
"plans": [{"name": "", "price": 0}]}). Object keys and value types are
26+
preserved; unknown values may be null. Empty arrays accept any JSON items.
27+
Defaults to {"result": ""}. Maximum 8 levels, 500 values, and 16000 characters.
28+
"""
29+
30+
mode: Literal["fast", "ultra"]
31+
"""
32+
Research level: fast uses a smaller model and research budget for 10 credits;
33+
ultra uses deeper reasoning and research for 100 credits. Defaults to ultra.
34+
Only successful requests consume credits.
35+
"""
36+
37+
tags: SequenceNotStr[str]
38+
"""Optional tags for tracking usage. Up to 20 tags, each 1 to 50 characters."""
39+
40+
timeout_ms: Annotated[int, PropertyInfo(alias="timeoutMS")]
41+
"""Optional timeout in milliseconds for the request.
42+
43+
If the request takes longer than this value, it will be aborted with a 408
44+
status code. Maximum allowed value is 300000ms (5 minutes).
45+
"""

‎src/context/dev/types/web_answers_response.py‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
2+
3+
from typing import Dict, List, Optional
4+
5+
from .._models import BaseModel
6+
7+
__all__ = ["WebAnswersResponse", "KeyMetadata"]
8+
9+
10+
class KeyMetadata(BaseModel):
11+
"""Credit usage, included whenever a valid API key is provided."""
12+
13+
credits_consumed: int
14+
"""Credits used by this request."""
15+
16+
credits_remaining: int
17+
"""Credits remaining for your organization."""
18+
19+
20+
class WebAnswersResponse(BaseModel):
21+
json_content: Dict[str, object]
22+
"""The answer, in the shape requested by json_format."""
23+
24+
sources: List[str]
25+
"""URLs that supplied search results or readable page content, in first-seen order.
26+
27+
Unreadable pages are excluded.
28+
"""
29+
30+
key_metadata: Optional[KeyMetadata] = None
31+
"""Credit usage, included whenever a valid API key is provided."""

0 commit comments

Comments
 (0)