Repository navigation
keenable (Python) 0.1.4
search()(sync and async) acceptsexclude_domains: a list of hosts to
keep out of the results. A host also excludes its subdomains; up to 1,000
distinct hosts. Any iterable of strings is sent as a list of its entries as
given, including[]; a lone string is one host, and""is sent as[""]
so the API rejects it rather than searching unfiltered. The API cleans up
unambiguous entries (scheme,www., case, port, trailing/or dot, query,
#fragment, whitespace; international names become punycode) and rejects
anything else (paths, suffixes such as.com, wildcards, IP addresses,
user@host, invalid hosts) with HTTP 400. If every result is excluded, the
response can be empty.siteis unchanged.- The
keenable_searchtool offersexclude_domainsalongsidesite.
run_tool_callsends the argument as given: only an absent ornullvalue
(or"") is unset, a lone string is wrapped, and any other value goes to the
API, which rejects a malformed one with a 400. - A rejected entry is a 400 whose
param,valueandreasonname it, and
whose message ends with the API'sfix.valueandreasonare set only
when the body'serrorisinvalid_filter,Noneotherwise.valueis
usually the entry as sent; a size cap reports the list's size
("2500 entries"or"more than 1000 distinct hosts") or an over-long
entry's first 64 characters and"...". - A search argument JSON cannot encode (
NaN, bytes, an arbitrary object)
raisesKeenableInvalidRequestErrorand sends nothing, insearch()and
run_tool_callalike.
The Python, TypeScript and Go SDKs now run one shared set of conformance cases
(scripts/conformance/), and these changes make them behave the same.
Behaviour changes are marked Changed.
-
Fixed:
Page.published_atis now set for fetched pages. The API sends a
fetch's publish date as Unix seconds, which the SDK dropped; it is now an
ISO 8601 UTC string to the second, such as"2024-05-01T12:00:00Z", the
form search results use. An ISO 8601 string is still kept as sent, so both
forms work. The same applies toSearchResult.published_atand
acquired_at. A number below 1, past the year 9999 (a millisecond value
too), not finite, or a boolean isNone, as before. -
Added:
Page.truncated(bool | None) andPage.total_chars
(int | None): whether the API cutcontentatmax_chars, and the full
content's length in code points.Nonewhen the API leaves them out or
sends another type.contentandto_context()are unchanged. -
Added:
search()acceptsmode="realtime", the fastest response, for
latency-sensitive agent loops."pro", deeper retrieval, stays the default.
The API already took it; the type wasLiteral["pro"]. -
Added:
fetch()takesmax_chars(cap the content returned; the API
default is 50000),live(Truefetches the page from its source instead
of the indexed copy) andprompt(an extraction instruction of up to 2000
characters;contentis then only the model's output for it), onKeenable
andAsyncKeenable. An option left unset is not sent,live=Falseis not
sent, and an emptypromptis unset. -
Added:
search()(sync and async) takesdisable_cards:Truereturns
ordinary web pages in place of Keenable's cards (results Keenable writes for
prices, exchange rates or company facts, whose URLs expire after one day).
It works in the"pro"and"realtime"modes. OnlyTrueis sent:
False, the API default, is left out. Any value that is not aboolraises
KeenableInvalidRequestErrorand sends nothing. Thekeenable_searchtool
offersdisable_cardsas a boolean;run_tool_callsends it only as
true, treatsfalse,nulland""as unset, and rejects any other value. -
Changed: errors no longer have
docs_url,billing_url,
auto_top_up_url,pay_per_requestorraw(none was in a release), and
str(err)no longer ends withDocs: <url>. The SDK does not expose docs
links, billing or checkout URLs, or x402 payment offers. -
Changed: a 402's message is the SDK's own sentence, without the API's
text orfix: "Keenable: payment required (402). This SDK does not pay per
request: ..." for a pay-per-request (x402) orpayment_*response, else
"Keenable: insufficient credits (402). ...". It is still a
KeenableInsufficientCreditsError, andbody,fix,codeand
request_idare still set. -
Changed:
fetch()refuses more targets before sending:100.64.0.0/10
(carrier-grade NAT, including Alibaba Cloud's metadata address),
192.0.0.0/24,fec0::/10,2002::/16,3fff::/20, any IPv6 address
outside2000::/3, names under.localhost, percent-encoded hosts
(127.0.0.%31), hosts with a soft hyphen or zero-width character, URLs with
a control character or surrounding space, a backslash in the host part, or
anything other than exactlyhttp://orhttps://before the host. The
ranges are now a fixed list shared with the other SDKs rather than Python's
ipaddressflags, which differ between Python versions; an IPv4-mapped
public address (::ffff:8.8.8.8) is now allowed on every version. -
Changed: a
Retry-Afterdate must be an RFC 9110 HTTP date
(IMF-fixdate, RFC 850 or asctime, in GMT). A date with a numeric zone or no
zone is ignored, so the next source of the delay (else backoff) is used. -
Changed: an error body field of the wrong type is ignored: a numeric or
objectmessageno longer becomes the detail (str()of it was shown), and
an error body that is JSON but not an object ("oops",42,null) gives
no detail.NaNandInfinityin a body are not JSON, a leading byte order
mark is ignored, and invalid UTF-8 no longer makes a JSON body unreadable. -
Changed: in results and pages, a
title,url,snippetorcontent
that is not a string is""instead of itsstr(); a pageurlthat is
blank or not a string falls back to the URL you fetched. -
Changed:
limit.maxis set only for a whole number from 0 to 2^53 - 1. -
Changed: an invalid header name, or a header value with CR, LF or NUL, in
default_headersorextra_headersraisesKeenableInvalidRequestError
before anything is sent, instead of a connection error that was retried. -
Changed: a non-string
search()query orfetch()URL raises
KeenableInvalidRequestError(wasAttributeErrororTypeError), and an
empty-string search filter is not sent, as in Go. -
Changed:
base_urlmay not have a query or fragment, surrounding
whitespace is dropped,http://localhost.counts as localhost, and a blank
KEENABLE_API_URLmeans the default. -
Changed: a timeout over 2,147,483.647 s (about 24.8 days) is treated as
that long; a larger one raisedOverflowErrorfrom the socket layer. -
Automatic retries. Connection errors, timeouts, 408, 429 and 5xx are retried
up tomax_retriestimes (default 2), unless the API marks the error
retryable: false. The wait is the API'sRetry-Afterwhen sent, else
exponential backoff (0.5 s to 8 s, jittered). ARetry-Afterover 60 s, such
as the keyless hourly cap, is raised at once instead of waited out. Pass
max_retries=0to turn retries off. -
New
KeenableTimeoutError, aKeenableConnectionErrorsubclass, for a
request that did not answer withintimeout. -
search()andfetch()taketimeout,max_retriesandextra_headers
for that call; the clients takemax_retriesanddefault_headers.
X-API-Keycan only come fromapi_key. -
SearchResponse.request_idandPage.request_id(bodyrequest_id, else
theX-Request-Idheader). -
Redirects are never followed, even by an
httpx.Clientyou pass with
follow_redirects=True, so the API key cannot reach another host. A
redirect raisesKeenableConnectionError. -
With your own
client, its timeout now applies unless you passtimeout;
before, the SDK's 30 s default was ignored silently either way.
On the client,timeout=Nonestill means no deadline. A per-calltimeout
overrides the client's for that call, and a per-callNone(the default)
keeps the client's. Anhttpx.Timeoutis accepted in both places. -
timeoutandmax_retriesare validated: a non-positive timeout or a
negative retry count raisesKeenableInvalidRequestError. -
Fix: a retry budget over 1024 raised
OverflowErrorin the backoff. -
Fix:
fetch()now refuses a loopback or private host spelled as a number
(2130706433,0x7f.0.0.1,0177.0.0.1,127.1) or in fullwidth digits,
as the TypeScript SDK does. -
Fix: a whitespace-only
messagein an error body no longer becomes the
error's detail, and a blankqueryin a response keeps the query you sent. -
Errors carry the API's agent-ready fields:
code,error,fix,
retryable,retry_after_seconds(from the body, else theRetry-After
header),request_id(body, elseX-Request-Id),paramandlimit(a
newRateLimitInfo). Each isNonewhen the API does not send it. -
New
KeenableInsufficientCreditsError(aliasKeenableCreditsError) for HTTP 402. It subclasses
KeenableAPIError, so existing handlers keep working. -
A 403 whose
codeistarget_blocked(the fetched site refused us) is now a
plainKeenableAPIErrorlabelled "Keenable API error (403)" rather than a
KeenableAuthError. Without acode, 401/403 behave as before. -
When the API sends
fix, the error message ends with it (". "), as in
the Go and TypeScript SDKs. ARetry-Afterheader is capped at a year, so an
oversized value can never break error handling. The same year cap applies to
a far-futureRetry-Afterdate and to the body'sretry_after_secondsand
retryAfter; a body value too large for a double (such as1e400) is
dropped and the next source of the delay is used, as in the other SDKs. -
Errors carry the API's
type(error format v1):invalid_request_error,
authentication_error,permission_error,billing_error,
rate_limit_error,target_errororapi_error. An API that does not send
it gets one derived from the status andcode, sotypeis set on every
KeenableAPIErrorfrom a response. A 401/403 whose type istarget_error
is not aKeenableAuthError(astarget_blockedalready was). -
str(err)ends with(code: <code>)and(request_id: <id>)when the API
sends them, the way Stripe's SDKs print the request id.bodyis unchanged,
and so is the message of a response without either field.
A message that already ends in a period no longer gets a second one before
the fix. -
to_context()(search results and fetched pages) drops markdown images and
<img>tags, and resolves relative links against the result's URL (or keeps
just the link text when it cannot). Absolute links are unchanged, and lines
left holding only pipes and dashes are dropped. Themax_charsbudget counts
the cleaned text. Fenced code blocks, inline code andname[i](x)calls are
left alone.snippetandcontentare untouched. -
to_context()(search results and fetched pages) flattens markdown tables:
delimiter rows (|---|:-:|) are dropped, and each row becomes its non-empty
cells joined with " · " and ended with ";" (one is not added when the last
cell already ends in ";"), so rows stay apart once a search snippet's
whitespace is collapsed. A line is a row when it sits under another
row or over a delimiter row, or looks like one on its own (| a | b |), so
prose such as|x| is ...is left alone. A pipe after an odd run of
backslashes (\|) is a literal pipe. A row left with no cells,
such as one that held only avatar images, is dropped. Tables inside fenced
code are left alone, and a pipe inside inline code does not split a cell. -
SearchResponse.to_context()andcited()takemax_snippet_chars(default 2000,
new constantDEFAULT_CONTEXT_MAX_SNIPPET_CHARS): each result's cleaned text
is cut at the last space at or before that many characters and ends in "…",
so one whole-page snippet no longer takes the wholemax_charsbudget. The
budget counts the capped text. PassNonefor the old uncapped behaviour;
a value below 1 also disables the cap (in Go, 0 means the default and a negative value disables it).
Page.to_context()is unchanged. -
The wheel now ships a
py.typedmarker, so mypy and pyright read the SDK's
type hints instead of treatingkeenableas untyped. If you run a strict
type checker, you may see new (correct) errors where your code passed values
the SDK never accepted.