Skip to content

Releases

keenable (TypeScript) 0.1.5

Choose a tag to compare

@github-actions github-actions released this 13 Nov 15:43
c2ee986
  • search() accepts excludeDomains: 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 (an array, a Set) is sent as an array 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. site is unchanged.
  • The keenable_search tool offers exclude_domains alongside site.
    runToolCall sends the argument as given: only an absent or null value (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, value and reason name it, and
    whose message ends with the API's fix. value and reason are set only
    when the body's error is invalid_filter, undefined otherwise. value
    is 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 (a BigInt) throws
    KeenableInvalidRequestError and sends nothing, in search() and
    runToolCall alike.

The SDK now matches the Python and Go SDKs case for case: all three run the
shared cases in scripts/conformance. Changes marked Behaviour change alter
what an existing call does.

  • Fixed: Page.publishedAt is 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 to SearchResult.publishedAt and
    acquiredAt. A number below 1, past the year 9999 (a millisecond value
    too) or not finite is undefined, as before.

  • Added: Page.truncated (boolean | undefined) and Page.totalChars
    (number | undefined): whether the API cut content at max_chars, and
    the full content's length in code points. undefined when the API leaves
    them out or sends another type. content and toContext() are unchanged.

  • Added: search() accepts mode: "realtime", the fastest response, for
    latency-sensitive agent loops. "pro", deeper retrieval, stays the default.
    The API already took it; the type was "pro" alone.

  • Added: fetch() takes maxChars (cap the content returned; the API
    default is 50000), live (true fetches the page from its source instead
    of the indexed copy) and prompt (an extraction instruction of up to 2000
    characters; content is then only the model's output for it). Its second
    argument is now the exported FetchOptions, which extends RequestOptions,
    so existing calls compile unchanged. An option left unset is not sent,
    live: false is not sent, and an empty prompt is unset.

  • Added: search() takes disableCards: true returns 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. Only true is sent: false, the API
    default, is left out. A value that is not a boolean throws
    KeenableInvalidRequestError and sends nothing. The keenable_search tool
    offers disable_cards as a boolean; runToolCall sends it only as true,
    treats false, null and "" as unset, and rejects any other value.

  • Behaviour change: errors no longer expose docsUrl, billingUrl,
    autoTopUpUrl, payPerRequest or raw, and the message no longer ends with
    Docs: <url>. None of these was in a release. body (the API's message) is
    unchanged.

  • Behaviour change: a 402's message is the SDK's own sentence rather than
    the API's text, which links to billing and checkout pages:
    "Keenable: insufficient credits (402). ..." or, for an x402 or payment_*
    response, "Keenable: payment required (402). This SDK does not pay per
    request ...". It is still a KeenableInsufficientCreditsError, with code,
    fix, requestId and body set, and carries no payment offer.

  • Behaviour change: fetch() refuses more special-purpose addresses, the
    same list in every SDK: 100.64.0.0/10 (carrier-grade NAT, including Alibaba
    Cloud's metadata address), 192.0.0.0/24, 192.0.2.0/24, 198.18.0.0/15,
    198.51.100.0/24, 203.0.113.0/24, and every IPv6 address outside
    2000::/3 or inside 2001::/23, 2001:db8::/32, 2002::/16 or 3fff::/20
    (so fc::1, NAT64 64:ff9b::/96, fec0::/10 and IPv4-compatible
    addresses). It also refuses names under .localhost.

  • Behaviour change: fetch() refuses a URL whose host other parsers read
    differently: https:///host, https:host and https:/host (read as
    https://host/ before), a backslash in the host part, a control character
    anywhere, or a leading or trailing space.

  • Behaviour change: a Retry-After date must be one of the three RFC 9110
    forms with the zone GMT. A date with a numeric zone (+0000) or none at all
    is ignored and the backoff applies, as in Go.

  • Behaviour change: an error body that is JSON but not an object ("oops",
    42, null) no longer becomes the error's detail; the error maps by status
    alone.

  • Behaviour change: a search result's title, url and snippet, and a
    page's title and content, are "" when the API sends something other
    than a string (they were "42", "[object Object]" or "false"). An array
    inside results is skipped like any other non-object.

  • Behaviour change: a fetch you pass that follows a redirect although the
    SDK asks it not to (redirect: "manual") now throws the same, non-retried
    redirect error instead of returning the other host's reply.

  • Behaviour change: a header name that is not an HTTP token, or a value
    with CR, LF or NUL, in defaultHeaders or a call's headers, throws
    KeenableInvalidRequestError before anything is sent, rather than failing as
    a connection error that was retried.

  • Behaviour change: mode: "" sends "pro", and an empty string filter
    (such as site: "") is not sent, as in Go.

  • Behaviour change: baseUrl with a query or fragment is refused (the path
    was appended after it), surrounding whitespace is ignored, localhost. counts
    as localhost, and http://127.1 is refused as in Python and Go. A blank
    KEENABLE_API_URL means the default instead of throwing.

  • Behaviour change: limit.max is set only for an integer from 0 to
    2^53 - 1.

  • Fix: a timeoutMs over 2147483647 (about 24.8 days) timed out at once,
    because a JavaScript timer fires immediately past that. It now waits that
    long.

  • Automatic retries. Connection errors, timeouts, 408, 429 and 5xx are retried
    up to maxRetries times (default 2), unless the API marks the error
    retryable: false. The wait is the API's Retry-After when sent, else
    exponential backoff (0.5 s to 8 s, jittered). A Retry-After over 60 s, such
    as the keyless hourly cap, is thrown at once instead of waited out. Pass
    maxRetries: 0 to turn retries off. Aborting signal cancels a pending
    retry.

  • New KeenableTimeoutError, a KeenableConnectionError subclass, for a
    request that did not answer within timeoutMs.

  • search() and fetch() take timeoutMs, maxRetries and headers for
    that call (the new RequestOptions type); the client takes maxRetries and
    defaultHeaders. X-API-Key can only come from apiKey.

  • SearchResponse.requestId and Page.requestId (body request_id, else the
    X-Request-Id header).

  • Fix: fetch() refused every hostname starting with fc, fd or
    fe8-feb (such as fdic.gov or fcbarcelona.com) as a "private
    address". Only IPv6 literals in those ranges are refused now, and IPv4
    multicast, reserved and broadcast addresses are refused as in Python and Go.

  • Fix: redirects are no longer followed. fetch would have carried the
    X-API-Key header to whatever host a redirect named. A redirect now throws
    KeenableConnectionError.

  • timeoutMs and maxRetries are validated: a non-positive timeout or a
    negative or fractional retry count throws KeenableInvalidRequestError.

  • Fix: a Retry-After header that is not a number or an HTTP date (1.5,
    -1, Jan 1) was read as a date in the past, so the retry came at once. It
    is now ignored, and the backoff applies, as in Python and Go.

  • Fix: a call whose signal is already aborted throws without calling
    fetch, even a custom fetch that ignores the signal.

  • Fix: Page.url falls back to the URL you asked for when the API sends an
    empty one, as in Python and Go.

  • Errors carry the API's agent-ready fields: code, error, fix,
    retryable, retryAfterSeconds (from the body, else the Retry-After
    header), requestId (body, else X-Request-Id), param and limit (a new
    RateLimitInfo type). Each is undefined when the API does not send it.

  • New KeenableInsufficientCreditsError (alias KeenableCreditsError) for HTTP 402. It extends
    KeenableAPIError, so existing handlers keep working.

  • A 403 whose code is target_blocked (the fetched site refused us) is now a
    plain KeenableAPIError labelled "Keenable API error (403)" rather than a
    KeenableAuthError. Without a code, 401/403 behave as before.

  • When the API sends fix, the error message ends with it (". "), as in
    the Go and Python SDKs. A Retry-After header is capped at a year, so an
    oversi...

Read more

keenable (Python) 0.1.5

Choose a tag to compare

@github-actions github-actions released this 13 Nov 15:43
c2ee986

Install from GitHub

pip install https://github.com/keenableai/keenable-sdk/releases/download/python-v0.1.5/keenable-0.1.5-py3-none-any.whl

keenable (Python) 0.1.4

Choose a tag to compare

@github-actions github-actions released this 13 Nov 15:09
66f4f9e
  • search() (sync and async) accepts exclude_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. site is unchanged.
  • The keenable_search tool offers exclude_domains alongside site.
    run_tool_call sends the argument as given: only an absent or null value
    (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, value and reason name it, and
    whose message ends with the API's fix. value and reason are set only
    when the body's error is invalid_filter, None otherwise. value is
    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)
    raises KeenableInvalidRequestError and sends nothing, in search() and
    run_tool_call alike.

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_at is 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 to SearchResult.published_at and
    acquired_at. A number below 1, past the year 9999 (a millisecond value
    too), not finite, or a boolean is None, as before.

  • Added: Page.truncated (bool | None) and Page.total_chars
    (int | None): whether the API cut content at max_chars, and the full
    content's length in code points. None when the API leaves them out or
    sends another type. content and to_context() are unchanged.

  • Added: search() accepts mode="realtime", the fastest response, for
    latency-sensitive agent loops. "pro", deeper retrieval, stays the default.
    The API already took it; the type was Literal["pro"].

  • Added: fetch() takes max_chars (cap the content returned; the API
    default is 50000), live (True fetches the page from its source instead
    of the indexed copy) and prompt (an extraction instruction of up to 2000
    characters; content is then only the model's output for it), on Keenable
    and AsyncKeenable. An option left unset is not sent, live=False is not
    sent, and an empty prompt is unset.

  • Added: search() (sync and async) takes disable_cards: True returns
    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. Only True is sent:
    False, the API default, is left out. Any value that is not a bool raises
    KeenableInvalidRequestError and sends nothing. The keenable_search tool
    offers disable_cards as a boolean; run_tool_call sends it only as
    true, treats false, null and "" as unset, and rejects any other value.

  • Changed: errors no longer have docs_url, billing_url,
    auto_top_up_url, pay_per_request or raw (none was in a release), and
    str(err) no longer ends with Docs: <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 or fix: "Keenable: payment required (402). This SDK does not pay per
    request: ..." for a pay-per-request (x402) or payment_* response, else
    "Keenable: insufficient credits (402). ...". It is still a
    KeenableInsufficientCreditsError, and body, fix, code and
    request_id are 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
    outside 2000::/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 exactly http:// or https:// before the host. The
    ranges are now a fixed list shared with the other SDKs rather than Python's
    ipaddress flags, which differ between Python versions; an IPv4-mapped
    public address (::ffff:8.8.8.8) is now allowed on every version.

  • Changed: a Retry-After date 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
    object message no 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. NaN and Infinity in 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, snippet or content
    that is not a string is "" instead of its str(); a page url that is
    blank or not a string falls back to the URL you fetched.

  • Changed: limit.max is 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_headers or extra_headers raises KeenableInvalidRequestError
    before anything is sent, instead of a connection error that was retried.

  • Changed: a non-string search() query or fetch() URL raises
    KeenableInvalidRequestError (was AttributeError or TypeError), and an
    empty-string search filter is not sent, as in Go.

  • Changed: base_url may not have a query or fragment, surrounding
    whitespace is dropped, http://localhost. counts as localhost, and a blank
    KEENABLE_API_URL means the default.

  • Changed: a timeout over 2,147,483.647 s (about 24.8 days) is treated as
    that long; a larger one raised OverflowError from the socket layer.

  • Automatic retries. Connection errors, timeouts, 408, 429 and 5xx are retried
    up to max_retries times (default 2), unless the API marks the error
    retryable: false. The wait is the API's Retry-After when sent, else
    exponential backoff (0.5 s to 8 s, jittered). A Retry-After over 60 s, such
    as the keyless hourly cap, is raised at once instead of waited out. Pass
    max_retries=0 to turn retries off.

  • New KeenableTimeoutError, a KeenableConnectionError subclass, for a
    request that did not answer within timeout.

  • search() and fetch() take timeout, max_retries and extra_headers
    for that call; the clients take max_retries and default_headers.
    X-API-Key can only come from api_key.

  • SearchResponse.request_id and Page.request_id (body request_id, else
    the X-Request-Id header).

  • Redirects are never followed, even by an httpx.Client you pass with
    follow_redirects=True, so the API key cannot reach another host. A
    redirect raises KeenableConnectionError.

  • With your own client, its timeout now applies unless you pass timeout;
    before, the SDK's 30 s default was ignored silently either way.
    On the client, timeout=None still means no deadline. A per-call timeout
    overrides the client's for that call, and a per-call None (the default)
    keeps the client's. An httpx.Timeout is accepted in both places.

  • timeout and max_retries are validated: a non-positive timeout or a
    negative retry count raises KeenableInvalidRequestError.

  • Fix: a retry budget over 1024 raised OverflowError in 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 message in an error body no longer becomes the
    error's detail, and a blank query in 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 the Retry-After
    header), request_id (body, else X-Request-Id), param and limit (a
    new RateLimitInfo). Each is None when the API does not send it.

  • New KeenableInsufficientCreditsError (alias KeenableCreditsError) for HTTP 402. It subclasses
    KeenableAPIError, so existing handlers keep working.

  • A 403 whose code is target_blocked (the fetched site refused us) is now a
    plain KeenableAPIError labelled "Keenable API error (403)" rather than a
    KeenableAuthError. Without a code, 401/403 behave as before.

  • When the API sends fix, the error message ends with it (". "), as in
    the Go and TypeScript SDKs. A Retry-After header is capped at a year, so an
    oversized value can never break error handling. The same year cap applies to
    a far-future Retry-After date and to the body's retry_after_seconds and
    retryAfter; a body value too large for a double (such as 1e400) is
    dropped and the next source of the delay is used, as in the other SDKs.

  • Er...

Read more

keenable (TypeScript) 0.1.4

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 02 Nov 19:32
17a9c21

search() accepts maxResults (1 to 50) and queryTime. Both are client-only; the tool schema is unchanged. No migration.

keenable (Python) 0.1.3

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 02 Nov 19:31
17a9c21

search() accepts max_results (1 to 50) and query_time. Both are client-only; the tool schema is unchanged. No migration.

keenable (TypeScript) 0.1.3

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 29 Oct 11:48
ee882ee
  • SearchResult.description and Page.description are marked @deprecated. The API no longer fills them: read snippet on search results and content on fetched pages. The fields stay for compatibility; see https://docs.keenable.ai/versioning.

The Python SDK 0.1.2 ships the same change.

keenable (Python) 0.1.2

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 29 Oct 11:42
ee882ee
  • SearchResult.description and Page.description are deprecated. The API no longer fills them: read snippet on search results and content on fetched pages. The fields stay for compatibility; see https://docs.keenable.ai/versioning.

The TypeScript SDK 0.1.3 ships the same change.

keenable (TypeScript) 0.1.2

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 29 Oct 11:43
1ab3bfb

Published to npm on 2026-09-07. This GitHub release was added on 2026-10-29 because the tag was missing.

keenable (TypeScript) 0.1.1

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 15 Aug 11:41

Hardening and internals release. No breaking changes.

Fixed

  • SSRF guard: the client-side fetch precheck missed IPv4-mapped IPv6 addresses, so https://[::ffff:169.254.169.254]/ reached the network, cloud-metadata address included. Note the detail that made this easy to miss: new URL() rewrites the dotted tail into hex (::ffff:a9fe:a9fe), so a check that only knows the dotted spelling never fires. A trailing dot in the host (https://localhost./) is now normalised away too.
  • toContext() stopped at the first over-budget result rather than skipping it and continuing, which could emit [1] then [3] and break the mapping from a model's citations back to results. Now pinned by a test.
  • Non-object tool-call arguments (an array, a number) are rejected as KeenableInvalidRequestError instead of silently becoming "no query".

Added

  • SearchResponse.cited() reports which results toContext() actually rendered, in citation order, so a printed source list cannot number sources the model never saw.
  • Page.toContext(): a fetched page renders as the same numbered, citable block as search results, and the keenable_fetch tool now returns it instead of anonymous markdown.
  • clientSource lets an integration built on this SDK keep its own traffic attribution instead of forking the transport.

Changed

  • toContext() collapses whitespace in snippets. They are raw page text, and their newlines collided with the blank line that separates one source from the next.
  • The package version is injected at build time from package.json, so the User-Agent cannot go stale.
  • Internals: endpoints named once with the keyless /public variant derived, and the search filters declared in one table that the payload builder, the tool schema and the tool dispatcher all read.

Published to npm: https://www.npmjs.com/package/keenable

keenable (TypeScript) 0.1.0

Choose a tag to compare

@ilya-bogin-keenable ilya-bogin-keenable released this 15 Aug 07:37

First release of the Keenable TypeScript SDK.

npm install keenable
import { Keenable } from "keenable";

const keenable = new Keenable();   // keyless; KEENABLE_API_KEY only lifts the rate limit
const results = await keenable.search("fastest inference providers 2026");
console.log(results.toContext());
  • search() with site, publication-date and index-date filters, snippetMaxLength, and an AbortSignal
  • fetch() returning any URL as markdown
  • toContext(), which renders results as a numbered, citable block for a prompt
  • TOOLS + runToolCall(): OpenAI-compatible tool definitions and a dispatcher for tool calling
  • Node 18+, no runtime dependencies, ESM and CJS with types

Published manually to npm: https://www.npmjs.com/package/keenable