Skip to main content

langchain-kaer

langchain-kaer connects LangChain agents and chains to the Kaer Search API. It provides KaerSearch, a tool a model can call to search the web, and KaerSearchRetriever, which returns search results as LangChain documents. Both send one POST /v1/search request per query and work with sync and async code.

Install

pip install -U langchain-kaer

Get an API key

  1. Sign up at api.kaer.ai.
  2. Create a key in the dashboard and tick the search scope.
  3. Add credit. Search opens after your account's first top-up; adding a card in Billing first gives you free web searches. See Search pricing for the price per query on each lane.
export KAER_API_KEY="kaer_live_..."

You can also pass the key in code: KaerSearch(kaer_api_key="...").

Use the search tool

from langchain_kaer import KaerSearch

tool = KaerSearch(max_results=5)

tool.invoke({"query": "latest results on perovskite solar cells"})

The tool returns the query, the lane that served it and a list of results. Each result has a title, url and snippet, plus published_date when it is known and the page's main text on the deep lane.

Give the tool to an agent

The agent and chain examples below also need LangChain and a model package:

pip install -U langchain langchain-anthropic
from langchain.agents import create_agent
from langchain_kaer import KaerSearch

agent = create_agent(
    model="anthropic:claude-sonnet-5-5",
    tools=[KaerSearch(max_results=5)],
)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "What changed in the EU AI Act this month?"}
        ]
    }
)
print(result["messages"][-1].content)

When a model calls the tool, the ToolMessage content holds compact results for the model to read. Its artifact holds the full API response, including kaer.request_id and kaer.cost_usd, so your code can log what each search cost.

What the model can set

Argument Type Description
query string What to search for, 1 to 512 characters. Required.
lane string web, fast, deep or auto. Optional.
include_domains list of strings Only return results from these host names or their subdomains. Optional.
exclude_domains list of strings Never return results from these host names. Optional.

Settings you fix when you create the tool

Setting Default Description
max_results 5 Results per query, 1 to 25.
lane "auto" The lane used when the model does not choose one.
allow_model_lane True Set False to always use lane, which keeps the price per query fixed.
include_domains None Default host names to search within.
exclude_domains None Default host names to leave out.
kaer_api_key KAER_API_KEY Your key.
timeout 60 Seconds to wait for a response.

Choose a lane

Lane What it does Timeout
web Searches Kaer's own index. Fastest and cheapest. 6 s
fast Races Kaer's index against the live web. 12 s
deep Runs every lane and re-ranks the results. Each result carries the page's main text, up to 4,000 characters, when the page could be read. 40 s
auto Kaer picks a lane for each query. You pay for the lane that served it. 40 s

A search that fails or times out is not charged.

Use the retriever

KaerSearchRetriever returns a list of Document objects. On the deep lane, page_content is the page's main text; on the other lanes it is the result snippet. metadata holds title, url, snippet, source, published_date and served_lane.

from langchain_kaer import KaerSearchRetriever

retriever = KaerSearchRetriever(k=5, lane="deep")

docs = retriever.invoke("How do heat pumps work in cold climates?")
for doc in docs:
    print(doc.metadata["title"], doc.metadata["url"])

Pass k at call time to change how many documents come back: retriever.invoke(query, k=3).

Use the retriever in a chain

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain.chat_models import init_chat_model
from langchain_kaer import KaerSearchRetriever

retriever = KaerSearchRetriever(k=5, lane="deep")
llm = init_chat_model("anthropic:claude-sonnet-5-5")

prompt = ChatPromptTemplate.from_template(
    "Answer from the sources and cite their URLs.\n\n"
    "Sources:\n{context}\n\nQuestion: {question}"
)


def format_docs(docs):
    return "\n\n".join(f"{d.metadata['url']}\n{d.page_content}" for d in docs)


chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

print(chain.invoke("How do heat pumps work in cold climates?"))

Call the API directly

KaerSearchAPIWrapper sends the request and returns the API's JSON response. It accepts every request field the API documents, including offset and page for paging on the web and fast lanes, and fields to choose which result keys come back.

from langchain_kaer import KaerSearchAPIWrapper

search = KaerSearchAPIWrapper()
data = search.search(
    "solar panel efficiency records", lane="fast", num_results=10, offset=10
)
print(data["served_lane"], data["kaer"]["cost_usd"])

Use await search.asearch(...) in async code. To send requests through your own httpx client, for a proxy or retries, pass client= or async_client=.

Handle errors

KaerSearchAPIWrapper raises KaerAPIError, with the HTTP status_code, the API's error code, its message, the request_id and retry_after when the API sent one. The tool catches these errors and returns them to the model as an error ToolMessage, so an agent can recover. The retriever raises them.

Status Code What to do
401 invalid_api_key Check the key, or create a new one.
402 insufficient_credits Add credit.
403 tier_required Search opens after your account's first top-up.
403 insufficient_scope Add the search scope to the key.
429 rate_limit_exceeded Wait for retry_after seconds, then retry.
504 search_timeout Retry, or use a faster lane.

The full list is in the error reference.

Development

make test               # unit tests, no network
make integration_tests  # live tests, needs KAER_API_KEY
make lint

Set KAER_BASE_URL to send requests to another base URL, for example a proxy in front of the API.

Licence

MIT. See LICENSE.

Metadata

Release files for langchain-kaer 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for langchain-kaer 0.1.0
File Size Uploaded Provenance Actions
langchain_kaer-0.1.0.tar.gz 15.0 kB With provenance Details for langchain_kaer-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for langchain-kaer 0.1.0
File Interpreter ABI Platform Actions
langchain_kaer-0.1.0-py3-none-any.whl Python 3 none any Details for langchain_kaer-0.1.0-py3-none-any.whl

Total release size: 28.2 kB

Release files / langchain_kaer-0.1.0.tar.gz

Download URL langchain_kaer-0.1.0.tar.gz
Size 15.0 kB
Tags Source
SHA-256 checksum
How to use checksums
4c18a1f8d222f4e14b91cf87e31119a4e2176451b7f3710eb156a9a45df80c40
BLAKE2b-256 checksum
How to use checksums
682ea0aa92224885144e13b7c4244112372b35a3473587627f5f9b8f2c83b851
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / langchain_kaer-0.1.0-py3-none-any.whl

Download URL langchain_kaer-0.1.0-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6488349b04ba4be9077ac3dd88005b57bb449ba759db960acb9d33f991486451
BLAKE2b-256 checksum
How to use checksums
737e907e2d0f0ce3213d1bc316f0050eb5757e80545068059d89ddea0f01805c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for langchain-kaer 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for langchain_kaer-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page