keirolabs-api 1.0.0__tar.gz

keirolabs_api-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keirolabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keirolabs_api-1.0.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: keirolabs-api
+Version: 1.0.0
+Summary: Web search for AI agents. One-line search, prompt-ready web context, and web search for any OpenAI or Anthropic client.
+Author-email: Keirolabs <team@keirolabs.cloud>
+License: MIT
+Project-URL: Homepage, https://keirolabs.cloud
+Project-URL: Documentation, https://platform.keirolabs.cloud/docs
+Project-URL: Source, https://github.com/Keirolabs-API/keirolabs-python
+Keywords: web search,search api,ai agents,llm,rag,tavily alternative,openai,anthropic,tool calling
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# keirolabs-api
+
+Web search for AI agents, in one line. No dependencies.
+
+```bash
+pip install keirolabs-api
+export KEIRO_API_KEY=keiro_...   # free key, 750 credits: https://keirolabs.cloud
+```
+
+```python
+from keirolabs import search
+
+search("latest llama release")
+# [{"title": ..., "url": ..., "snippet": ..., "content": ...}, ...]
+```
+
+## Give any LLM web search
+
+Wrap your OpenAI or Anthropic client. The model searches when it needs to, and you get a normal response back.
+
+```python
+from openai import OpenAI
+from keirolabs import wrap
+
+client = wrap(OpenAI())
+client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "What did Nvidia report this quarter?"}],
+)
+```
+
+```python
+from anthropic import Anthropic
+client = wrap(Anthropic())
+```
+
+Any client with the OpenAI chat completions API should work, such as OpenRouter or Groq (tested on Groq). Your own tools keep working: if the model calls one of them, you get the response back as usual. The model gets up to 3 searches per call (`max_steps`). Sync clients only for now (`OpenAI()`, `Anthropic()`, not the async ones). Streaming calls (`stream=True`) go straight to the model without search.
+
+## Prompt-ready web context
+
+Searches, reads the pages, and returns the passages most likely to answer the question, packed into your token budget.
+
+```python
+from keirolabs import context
+
+prompt = f"""Answer using these sources.
+
+{context("who won the 2022 world cup", max_tokens=1500)}
+
+Question: who won the 2022 world cup?"""
+```
+
+It runs on Keiro deep search, which scores 96.5% on SimpleQA.
+
+## Switching from Tavily
+
+Change one import. The methods and response keys match Tavily's.
+
+```diff
+- from tavily import TavilyClient
++ from keirolabs.compat import TavilyClient
+```
+
+`search`, `get_search_context`, `qna_search` and `extract` are supported. Differences: `score` comes from the result's rank, domain filters are applied after the search (so you can get fewer results than you asked for), and `images` is always empty. A Tavily key is ignored: pass a Keiro key or set `KEIRO_API_KEY`.
+
+## Everything else
+
+```python
+from keirolabs import search, deep, answer, md, tool, run_tool
+
+search("query", mode="lite")      # cheapest: $0.10 per 1,000 on paid plans
+search("query", mode="fast")      # fast live results
+search("query", mode="content")   # full page markdown for each result
+deep("query", budget=2000)        # ranked evidence + confidence
+answer("query")                   # {"answer": ..., "sources": [...]}
+md("https://example.com")         # any page as clean text
+
+tool()               # web_search tool for OpenAI-style APIs
+tool("anthropic")    # ...or Anthropic, "gemini", "json"
+run_tool(args)       # run a model's web_search call, get the tool result text
+```
+
+Use a client object for a different key, base URL or timeout:
+
+```python
+from keirolabs import Keiro
+k = Keiro(api_key="keiro_...", timeout=60)
+k.search("query")
+```
+
+Errors raise `keirolabs.KeiroError` with `.status` (401 bad key, 402 out of credits, 429 rate limited).
+
+Results are lists of dicts. The full API response (credits used, latency) is on `.raw`.
+
+## Pricing
+
+Free: 750 credits at signup. Lite costs 1 credit on free, and $0.10 per 1,000 searches on paid plans. [Pricing](https://keirolabs.cloud/pricing).
+
+MIT license.

keirolabs_api-1.0.0/README.md

@@ -0,0 +1,99 @@
+# keirolabs-api
+
+Web search for AI agents, in one line. No dependencies.
+
+```bash
+pip install keirolabs-api
+export KEIRO_API_KEY=keiro_...   # free key, 750 credits: https://keirolabs.cloud
+```
+
+```python
+from keirolabs import search
+
+search("latest llama release")
+# [{"title": ..., "url": ..., "snippet": ..., "content": ...}, ...]
+```
+
+## Give any LLM web search
+
+Wrap your OpenAI or Anthropic client. The model searches when it needs to, and you get a normal response back.
+
+```python
+from openai import OpenAI
+from keirolabs import wrap
+
+client = wrap(OpenAI())
+client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "What did Nvidia report this quarter?"}],
+)
+```
+
+```python
+from anthropic import Anthropic
+client = wrap(Anthropic())
+```
+
+Any client with the OpenAI chat completions API should work, such as OpenRouter or Groq (tested on Groq). Your own tools keep working: if the model calls one of them, you get the response back as usual. The model gets up to 3 searches per call (`max_steps`). Sync clients only for now (`OpenAI()`, `Anthropic()`, not the async ones). Streaming calls (`stream=True`) go straight to the model without search.
+
+## Prompt-ready web context
+
+Searches, reads the pages, and returns the passages most likely to answer the question, packed into your token budget.
+
+```python
+from keirolabs import context
+
+prompt = f"""Answer using these sources.
+
+{context("who won the 2022 world cup", max_tokens=1500)}
+
+Question: who won the 2022 world cup?"""
+```
+
+It runs on Keiro deep search, which scores 96.5% on SimpleQA.
+
+## Switching from Tavily
+
+Change one import. The methods and response keys match Tavily's.
+
+```diff
+- from tavily import TavilyClient
++ from keirolabs.compat import TavilyClient
+```
+
+`search`, `get_search_context`, `qna_search` and `extract` are supported. Differences: `score` comes from the result's rank, domain filters are applied after the search (so you can get fewer results than you asked for), and `images` is always empty. A Tavily key is ignored: pass a Keiro key or set `KEIRO_API_KEY`.
+
+## Everything else
+
+```python
+from keirolabs import search, deep, answer, md, tool, run_tool
+
+search("query", mode="lite")      # cheapest: $0.10 per 1,000 on paid plans
+search("query", mode="fast")      # fast live results
+search("query", mode="content")   # full page markdown for each result
+deep("query", budget=2000)        # ranked evidence + confidence
+answer("query")                   # {"answer": ..., "sources": [...]}
+md("https://example.com")         # any page as clean text
+
+tool()               # web_search tool for OpenAI-style APIs
+tool("anthropic")    # ...or Anthropic, "gemini", "json"
+run_tool(args)       # run a model's web_search call, get the tool result text
+```
+
+Use a client object for a different key, base URL or timeout:
+
+```python
+from keirolabs import Keiro
+k = Keiro(api_key="keiro_...", timeout=60)
+k.search("query")
+```
+
+Errors raise `keirolabs.KeiroError` with `.status` (401 bad key, 402 out of credits, 429 rate limited).
+
+Results are lists of dicts. The full API response (credits used, latency) is on `.raw`.
+
+## Pricing
+
+Free: 750 credits at signup. Lite costs 1 credit on free, and $0.10 per 1,000 searches on paid plans. [Pricing](https://keirolabs.cloud/pricing).
+
+MIT license.

keirolabs_api-1.0.0/keirolabs/__init__.py

@@ -0,0 +1,23 @@
+"""Keiro: web search for AI agents. https://keirolabs.cloud
+
+    from keirolabs import search, context, wrap
+"""
+from .client import (
+    Keiro,
+    KeiroError,
+    Results,
+    __version__,
+    answer,
+    context,
+    deep,
+    extract,
+    md,
+    search,
+)
+from .tools import run_tool, tool, wrap
+
+__all__ = [
+    "Keiro", "KeiroError", "Results", "__version__",
+    "search", "deep", "answer", "extract", "md", "context",
+    "tool", "run_tool", "wrap",
+]

keirolabs_api-1.0.0/keirolabs/client.py

@@ -0,0 +1,167 @@
+"""Keiro web search API client. Standard library only."""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any, Iterable
+
+__version__ = "1.0.0"
+
+DEFAULT_BASE_URL = "https://api.keirolabs.cloud"
+_SEARCH_PATHS = {"lite": "search/lite", "fast": "search/fast", "content": "search/content"}
+
+
+class KeiroError(Exception):
+    """Raised for any non-2xx response. `status` is the HTTP code (0 = network error)."""
+
+    def __init__(self, message: str, status: int = 0, body: Any = None):
+        super().__init__(f"{message} (HTTP {status})" if status else message)
+        self.status = status
+        self.body = body
+
+
+class Results(list):
+    """A list of result dicts. `.raw` holds the full API response (credits, latency, ...)."""
+
+    raw: dict
+
+
+def _result(r: dict) -> dict:
+    # One shape for every endpoint: title, url, snippet, content.
+    return {
+        "title": r.get("title") or "",
+        "url": r.get("url") or "",
+        "snippet": r.get("snippet") or r.get("excerpt") or "",
+        "content": r.get("markdown_content") or r.get("content") or "",
+    }
+
+
+class Keiro:
+    """Client for api.keirolabs.cloud.
+
+    >>> k = Keiro()                      # reads KEIRO_API_KEY
+    >>> k.search("latest llama release")
+    """
+
+    def __init__(self, api_key: str | None = None, base_url: str | None = None, timeout: float = 120):
+        self.api_key = api_key or os.environ.get("KEIRO_API_KEY")
+        if not self.api_key:
+            raise KeiroError("No API key. Pass api_key=... or set KEIRO_API_KEY (free key: https://keirolabs.cloud)")
+        self.base_url = (base_url or os.environ.get("KEIRO_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+
+    # ── transport ────────────────────────────────────────────────────────────
+    def request(self, path: str, body: dict) -> dict:
+        """POST /api/v2/<path> and return the decoded JSON. Use this for any endpoint or param the helpers don't cover."""
+        req = urllib.request.Request(
+            f"{self.base_url}/api/v2/{path.lstrip('/')}",
+            data=json.dumps({k: v for k, v in body.items() if v is not None}).encode(),
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"keirolabs-python/{__version__}",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return json.loads(r.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode(errors="replace")
+            try:
+                data = json.loads(raw)
+                msg = data.get("message") or data.get("error") or raw
+            except ValueError:
+                data, msg = raw, raw or e.reason
+            raise KeiroError(str(msg), e.code, data) from None
+        except urllib.error.URLError as e:
+            raise KeiroError(f"Network error: {e.reason}") from None
+
+    # ── endpoints ────────────────────────────────────────────────────────────
+    def search(self, query: str, *, mode: str = "lite", max_results: int = 10, **params: Any) -> Results:
+        """Web search. mode: "lite" (cheapest, snippets), "fast", or "content" (full page markdown)."""
+        if mode not in _SEARCH_PATHS:
+            raise ValueError(f"mode must be one of {list(_SEARCH_PATHS)}")
+        data = self.request(_SEARCH_PATHS[mode], {"query": query, "maxResults": max_results, **params})
+        out = Results(_result(r) for r in data.get("results") or [])
+        out.raw = data
+        return out
+
+    def deep(self, query: str, *, budget: int | None = None, content: bool | None = None, **params: Any) -> dict:
+        """Deep search: searches, reads the pages and returns the passages most likely to hold the answer.
+
+        Returns the API response: `evidence` (best passages, packed into `budget` tokens),
+        `results` (ranked pages), `confidence` and `answer_status`.
+        """
+        return self.request("deep", {"query": query, "budget": budget, "content": content, **params})
+
+    def answer(self, query: str, **params: Any) -> dict:
+        """A written answer with sources: {"answer": str, "sources": [url, ...], ...}."""
+        data = self.request("answer", {"query": query, "stream": False, **params})
+        return data.get("data", data)
+
+    def extract(self, urls: str | Iterable[str], **params: Any) -> Results:
+        """Clean content from one or more URLs."""
+        body = {"url": urls} if isinstance(urls, str) else {"urls": list(urls)}
+        data = self.request("extract", {**body, **params})
+        out = Results({**_result(r), "error": r.get("error")} for r in data.get("results") or [])
+        out.raw = data
+        return out
+
+    def md(self, url: str) -> str:
+        """Any URL as clean markdown/text."""
+        res = self.extract(url)
+        if not res or res[0].get("error"):
+            raise KeiroError(f"Could not extract {url}: {res[0].get('error') if res else 'no result'}")
+        return res[0]["content"]
+
+    def context(self, query: str, max_tokens: int = 2000) -> str:
+        """Prompt-ready web context for `query`, at most ~max_tokens. Paste it straight into a prompt."""
+        budget = max(100, min(int(max_tokens), 20000))
+        data = self.deep(query, budget=budget)
+        blocks = [
+            f"[{i}] {e.get('title') or e.get('url')}\n{e.get('url')}\n{(e.get('text') or '').strip()}"
+            for i, e in enumerate(data.get("evidence") or [], 1)
+        ]
+        if not blocks:  # nothing scored as evidence: fall back to the ranked pages
+            blocks = [
+                f"[{i}] {r.get('title')}\n{r.get('url')}\n{(r.get('excerpt') or r.get('snippet') or '').strip()}"
+                for i, r in enumerate(data.get("results") or [], 1)
+            ]
+        return "\n\n".join(blocks)
+
+
+_default: Keiro | None = None
+
+
+def _client() -> Keiro:
+    global _default
+    if _default is None:
+        _default = Keiro()
+    return _default
+
+
+def search(query: str, **kw: Any) -> Results:
+    return _client().search(query, **kw)
+
+
+def deep(query: str, **kw: Any) -> dict:
+    return _client().deep(query, **kw)
+
+
+def answer(query: str, **kw: Any) -> dict:
+    return _client().answer(query, **kw)
+
+
+def extract(urls: str | Iterable[str], **kw: Any) -> Results:
+    return _client().extract(urls, **kw)
+
+
+def md(url: str) -> str:
+    return _client().md(url)
+
+
+def context(query: str, max_tokens: int = 2000) -> str:
+    return _client().context(query, max_tokens)

keirolabs_api-1.0.0/keirolabs/compat.py

@@ -0,0 +1,95 @@
+"""Drop-in replacement for the Tavily Python client.
+
+    - from tavily import TavilyClient
+    + from keirolabs.compat import TavilyClient
+
+Same methods and response shapes, backed by Keiro. Reads KEIRO_API_KEY; a Tavily key ("tvly-...") is ignored.
+"""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Iterable
+from urllib.parse import urlparse
+
+from .client import Keiro
+
+
+def _host(url: str) -> str:
+    h = urlparse(url).netloc.lower()
+    return h[4:] if h.startswith("www.") else h
+
+
+def _match(url: str, domains: Iterable[str]) -> bool:
+    h = _host(url)
+    return any(h == d or h.endswith("." + d) for d in (_host("//" + d.lower()) for d in domains))
+
+
+class TavilyClient:
+    def __init__(self, api_key: str | None = None, **_: Any):
+        self._k = Keiro(api_key=api_key if api_key and api_key.startswith("keiro_") else None)
+
+    def search(
+        self,
+        query: str,
+        search_depth: str = "basic",
+        max_results: int = 5,
+        include_answer: bool | str = False,
+        include_raw_content: bool | str = False,
+        include_domains: Iterable[str] | None = None,
+        exclude_domains: Iterable[str] | None = None,
+        **_: Any,
+    ) -> dict:
+        t0 = time.time()
+        mode = "content" if include_raw_content or search_depth == "advanced" else "lite"
+        # Domain filters are applied to the results, so ask for extra results to filter from.
+        want = max_results * 3 if include_domains or exclude_domains else max_results
+        rows = self._k.search(query, mode=mode, max_results=want)
+        if include_domains:
+            rows = [r for r in rows if _match(r["url"], include_domains)]
+        if exclude_domains:
+            rows = [r for r in rows if not _match(r["url"], exclude_domains)]
+        rows = rows[:max_results]
+        results = [
+            {
+                "title": r["title"],
+                "url": r["url"],
+                "content": r["snippet"] or r["content"][:500],
+                # ponytail: Keiro returns rank, not a relevance score. Rank-derived so sorting by score keeps order.
+                "score": round(1 - i / (len(rows) + 1), 4),
+                "raw_content": r["content"] or None if include_raw_content else None,
+            }
+            for i, r in enumerate(rows)
+        ]
+        answer = self._k.answer(query).get("answer") if include_answer else None
+        return {
+            "query": query,
+            "follow_up_questions": None,
+            "answer": answer,
+            "images": [],
+            "results": results,
+            "response_time": round(time.time() - t0, 2),
+        }
+
+    def get_search_context(self, query: str, max_tokens: int = 4000, **kw: Any) -> str:
+        """JSON string of [{url, content}], like Tavily."""
+        res = self.search(query, **kw)["results"]
+        out, used = [], 0
+        for r in res:
+            used += len(r["content"]) // 4
+            if used > max_tokens:
+                break
+            out.append({"url": r["url"], "content": r["content"]})
+        return json.dumps(out)
+
+    def qna_search(self, query: str, **_: Any) -> str:
+        return self._k.answer(query).get("answer") or ""
+
+    def extract(self, urls: str | Iterable[str], **_: Any) -> dict:
+        t0 = time.time()
+        rows = self._k.extract(urls)
+        return {
+            "results": [{"url": r["url"], "raw_content": r["content"], "images": []} for r in rows if not r.get("error")],
+            "failed_results": [{"url": r["url"], "error": r["error"]} for r in rows if r.get("error")],
+            "response_time": round(time.time() - t0, 2),
+        }

keirolabs_api-1.0.0/keirolabs/tools.py

@@ -0,0 +1,142 @@
+"""Web search as an LLM tool: a schema for every major format, and `wrap()` to add it to any client."""
+from __future__ import annotations
+
+import inspect
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+from .client import Keiro, _client
+
+NAME = "web_search"
+FINAL_NUDGE = "Search limit reached. Answer now using the results above."
+DESCRIPTION = (
+    "Search the web for current information. Use it for anything recent, anything after your "
+    "training cutoff, or anything that needs a source. Results are live: don't add a year to the query "
+    "unless the user gave one. Returns ranked results with title, url and text."
+)
+PARAMETERS = {
+    "type": "object",
+    "properties": {"query": {"type": "string", "description": "What to search for, written like a search engine query."}},
+    # ponytail: no "required". Some providers (Groq) hard-fail the whole request when a model names the
+    # argument differently; run_tool accepts q/search_query/any string instead and tells the model if it's empty.
+}
+
+
+def tool(format: str = "openai") -> dict:
+    """The web_search tool definition.
+
+    format: "openai" (also OpenRouter, Groq, Together, vLLM...), "anthropic", "gemini", or "json" (bare schema).
+    """
+    if format == "openai":
+        return {"type": "function", "function": {"name": NAME, "description": DESCRIPTION, "parameters": PARAMETERS}}
+    if format == "anthropic":
+        return {"name": NAME, "description": DESCRIPTION, "input_schema": PARAMETERS}
+    if format in ("gemini", "json"):
+        return {"name": NAME, "description": DESCRIPTION, "parameters": PARAMETERS}
+    raise ValueError('format must be "openai", "anthropic", "gemini" or "json"')
+
+
+def run_tool(args: dict | str, *, mode: str = "lite", client: Keiro | None = None) -> str:
+    """Run a web_search call from a model and return the text to send back as the tool result."""
+    if isinstance(args, str):
+        args = json.loads(args or "{}")
+    args = args or {}
+    query = args.get("query") or args.get("q") or args.get("search_query") or next((v for v in args.values() if isinstance(v, str)), "")
+    query = query.strip()
+    if not query:
+        return "Error: query is required."
+    k = client or _client()
+    # Models assume their training year; telling them today's date keeps them from searching stale years.
+    head = f"Web results for {query!r}, searched {datetime.now(timezone.utc):%Y-%m-%d} (UTC):\n\n"
+    try:
+        if mode == "deep":
+            return head + (k.context(query, 1500) or "No results.")
+        rows = k.search(query, mode=mode, max_results=8)
+    except Exception as e:  # the model should see the failure, not crash the loop
+        return f"Search failed: {e}"
+    return head + ("\n\n".join(f"{i}. {r['title']}\n{r['url']}\n{r['snippet'] or r['content'][:500]}" for i, r in enumerate(rows, 1)) or "No results.")
+
+
+class _Proxy:
+    """Looks like `target`, except for the attributes in `overrides`."""
+
+    def __init__(self, target: Any, **overrides: Any):
+        self._target, self._overrides = target, overrides
+
+    def __getattr__(self, name: str) -> Any:
+        return self._overrides[name] if name in self._overrides else getattr(self._target, name)
+
+
+def _dump(obj: Any) -> Any:
+    return obj.model_dump(exclude_none=True) if hasattr(obj, "model_dump") else obj
+
+
+def wrap(client: Any, *, mode: str = "lite", max_steps: int = 3, keiro: Keiro | None = None) -> Any:
+    """Give an OpenAI or Anthropic client web search. Every create() call can now search on its own.
+
+    >>> client = wrap(OpenAI())
+    >>> client.chat.completions.create(model="gpt-4.1", messages=[{"role": "user", "content": "news on X today?"}])
+
+    The model decides when to search; searches run here and the final answer comes back as a normal response.
+    Your own tools are left alone: if the model calls one of them, the response is returned to you as usual.
+    mode: "lite" (cheapest) or "deep" (best evidence, 96.5% on SimpleQA).
+    Streaming calls (stream=True) pass through without search.
+    """
+    run = lambda args: run_tool(args, mode=mode, client=keiro)  # noqa: E731
+
+    if hasattr(client, "chat") and hasattr(client.chat, "completions"):
+        orig = client.chat.completions.create
+        if inspect.iscoroutinefunction(orig):
+            # ponytail: sync clients only for now; add an async loop when someone asks.
+            raise TypeError("wrap() supports the sync OpenAI client. Use OpenAI(), not AsyncOpenAI().")
+
+        def create(**kw: Any) -> Any:
+            if kw.get("stream"):
+                return orig(**kw)
+            own = list(kw.pop("tools", None) or [])
+            messages = list(kw.pop("messages"))
+            for step in range(max_steps + 1):
+                # Final round: the tool stays defined (history references it) but calls are off, so the model must answer.
+                last = step == max_steps
+                extra = {"tool_choice": "none"} if last and step else {}
+                resp = orig(messages=messages, tools=own + [tool("openai")], **extra, **kw)
+                msg = resp.choices[0].message
+                calls = msg.tool_calls or []
+                if last or not calls or any(c.function.name != NAME for c in calls):
+                    return resp
+                messages.append(_dump(msg))
+                messages += [{"role": "tool", "tool_call_id": c.id, "content": run(c.function.arguments)} for c in calls]
+                if step + 1 == max_steps:
+                    messages.append({"role": "user", "content": FINAL_NUDGE})
+            return resp
+
+        return _Proxy(client, chat=_Proxy(client.chat, completions=_Proxy(client.chat.completions, create=create)))
+
+    if hasattr(client, "messages") and hasattr(client.messages, "create"):
+        orig = client.messages.create
+        if inspect.iscoroutinefunction(orig):
+            raise TypeError("wrap() supports the sync Anthropic client. Use Anthropic(), not AsyncAnthropic().")
+
+        def create(**kw: Any) -> Any:
+            if kw.get("stream"):
+                return orig(**kw)
+            own = list(kw.pop("tools", None) or [])
+            messages = list(kw.pop("messages"))
+            for step in range(max_steps + 1):
+                last = step == max_steps
+                extra = {"tool_choice": {"type": "none"}} if last and step else {}
+                resp = orig(messages=messages, tools=own + [tool("anthropic")], **extra, **kw)
+                uses = [b for b in resp.content if getattr(b, "type", None) == "tool_use"]
+                if last or resp.stop_reason != "tool_use" or not uses or any(b.name != NAME for b in uses):
+                    return resp
+                messages.append({"role": "assistant", "content": [_dump(b) for b in resp.content]})
+                results = [{"type": "tool_result", "tool_use_id": b.id, "content": run(b.input)} for b in uses]
+                if step + 1 == max_steps:
+                    results.append({"type": "text", "text": FINAL_NUDGE})
+                messages.append({"role": "user", "content": results})
+            return resp
+
+        return _Proxy(client, messages=_Proxy(client.messages, create=create))
+
+    raise TypeError("wrap() takes an OpenAI or Anthropic client (or any OpenAI-compatible client).")

keirolabs_api-1.0.0/keirolabs_api.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: keirolabs-api
+Version: 1.0.0
+Summary: Web search for AI agents. One-line search, prompt-ready web context, and web search for any OpenAI or Anthropic client.
+Author-email: Keirolabs <team@keirolabs.cloud>
+License: MIT
+Project-URL: Homepage, https://keirolabs.cloud
+Project-URL: Documentation, https://platform.keirolabs.cloud/docs
+Project-URL: Source, https://github.com/Keirolabs-API/keirolabs-python
+Keywords: web search,search api,ai agents,llm,rag,tavily alternative,openai,anthropic,tool calling
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# keirolabs-api
+
+Web search for AI agents, in one line. No dependencies.
+
+```bash
+pip install keirolabs-api
+export KEIRO_API_KEY=keiro_...   # free key, 750 credits: https://keirolabs.cloud
+```
+
+```python
+from keirolabs import search
+
+search("latest llama release")
+# [{"title": ..., "url": ..., "snippet": ..., "content": ...}, ...]
+```
+
+## Give any LLM web search
+
+Wrap your OpenAI or Anthropic client. The model searches when it needs to, and you get a normal response back.
+
+```python
+from openai import OpenAI
+from keirolabs import wrap
+
+client = wrap(OpenAI())
+client.chat.completions.create(
+    model="gpt-4.1",
+    messages=[{"role": "user", "content": "What did Nvidia report this quarter?"}],
+)
+```
+
+```python
+from anthropic import Anthropic
+client = wrap(Anthropic())
+```
+
+Any client with the OpenAI chat completions API should work, such as OpenRouter or Groq (tested on Groq). Your own tools keep working: if the model calls one of them, you get the response back as usual. The model gets up to 3 searches per call (`max_steps`). Sync clients only for now (`OpenAI()`, `Anthropic()`, not the async ones). Streaming calls (`stream=True`) go straight to the model without search.
+
+## Prompt-ready web context
+
+Searches, reads the pages, and returns the passages most likely to answer the question, packed into your token budget.
+
+```python
+from keirolabs import context
+
+prompt = f"""Answer using these sources.
+
+{context("who won the 2022 world cup", max_tokens=1500)}
+
+Question: who won the 2022 world cup?"""
+```
+
+It runs on Keiro deep search, which scores 96.5% on SimpleQA.
+
+## Switching from Tavily
+
+Change one import. The methods and response keys match Tavily's.
+
+```diff
+- from tavily import TavilyClient
++ from keirolabs.compat import TavilyClient
+```
+
+`search`, `get_search_context`, `qna_search` and `extract` are supported. Differences: `score` comes from the result's rank, domain filters are applied after the search (so you can get fewer results than you asked for), and `images` is always empty. A Tavily key is ignored: pass a Keiro key or set `KEIRO_API_KEY`.
+
+## Everything else
+
+```python
+from keirolabs import search, deep, answer, md, tool, run_tool
+
+search("query", mode="lite")      # cheapest: $0.10 per 1,000 on paid plans
+search("query", mode="fast")      # fast live results
+search("query", mode="content")   # full page markdown for each result
+deep("query", budget=2000)        # ranked evidence + confidence
+answer("query")                   # {"answer": ..., "sources": [...]}
+md("https://example.com")         # any page as clean text
+
+tool()               # web_search tool for OpenAI-style APIs
+tool("anthropic")    # ...or Anthropic, "gemini", "json"
+run_tool(args)       # run a model's web_search call, get the tool result text
+```
+
+Use a client object for a different key, base URL or timeout:
+
+```python
+from keirolabs import Keiro
+k = Keiro(api_key="keiro_...", timeout=60)
+k.search("query")
+```
+
+Errors raise `keirolabs.KeiroError` with `.status` (401 bad key, 402 out of credits, 429 rate limited).
+
+Results are lists of dicts. The full API response (credits used, latency) is on `.raw`.
+
+## Pricing
+
+Free: 750 credits at signup. Lite costs 1 credit on free, and $0.10 per 1,000 searches on paid plans. [Pricing](https://keirolabs.cloud/pricing).
+
+MIT license.

keirolabs_api-1.0.0/keirolabs_api.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+keirolabs/__init__.py
+keirolabs/client.py
+keirolabs/compat.py
+keirolabs/tools.py
+keirolabs_api.egg-info/PKG-INFO
+keirolabs_api.egg-info/SOURCES.txt
+keirolabs_api.egg-info/dependency_links.txt
+keirolabs_api.egg-info/top_level.txt
+tests/test_keirolabs.py

keirolabs_api-1.0.0/keirolabs_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

keirolabs_api-1.0.0/keirolabs_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+keirolabs

keirolabs_api-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "keirolabs-api"
+version = "1.0.0"
+description = "Web search for AI agents. One-line search, prompt-ready web context, and web search for any OpenAI or Anthropic client."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Keirolabs", email = "team@keirolabs.cloud" }]
+keywords = ["web search", "search api", "ai agents", "llm", "rag", "tavily alternative", "openai", "anthropic", "tool calling"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://keirolabs.cloud"
+Documentation = "https://platform.keirolabs.cloud/docs"
+Source = "https://github.com/Keirolabs-API/keirolabs-python"
+
+[tool.setuptools]
+packages = ["keirolabs"]

keirolabs_api-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

keirolabs_api-1.0.0/tests/test_keirolabs.py

@@ -0,0 +1,168 @@
+"""Offline tests (fake transport, fake LLM clients). Run: python -m unittest discover tests
+Set KEIRO_API_KEY to also run the live smoke test."""
+import json
+import os
+import unittest
+from types import SimpleNamespace as NS
+
+import keirolabs
+import keirolabs.tools
+from keirolabs import Keiro, tool, wrap
+from keirolabs.compat import TavilyClient
+
+LITE = {"results": [
+    {"title": "A", "url": "https://www.a.com/x", "snippet": "sa"},
+    {"title": "B", "url": "https://docs.b.org/y", "snippet": "sb"},
+    {"title": "C", "url": "https://c.net/z", "snippet": "sc"},
+], "creditsCharged": 0.0375}
+DEEP = {"evidence": [{"title": "T", "url": "https://t.com", "text": "evidence text"}], "results": []}
+
+
+class FakeKeiro(Keiro):
+    def __init__(self):
+        super().__init__(api_key="keiro_test")
+        self.calls = []
+
+    def request(self, path, body):
+        self.calls.append((path, body))
+        if path.startswith("search/"):
+            return LITE
+        if path == "deep":
+            return DEEP
+        if path == "answer":
+            return {"data": {"answer": "42", "sources": ["https://t.com"]}}
+        if path == "extract":
+            return {"results": [{"url": body.get("url"), "content": "page text", "error": None}]}
+        raise AssertionError(path)
+
+
+class ClientTests(unittest.TestCase):
+    def test_search_normalizes_and_keeps_raw(self):
+        k = FakeKeiro()
+        r = k.search("q")
+        self.assertEqual(r[0], {"title": "A", "url": "https://www.a.com/x", "snippet": "sa", "content": ""})
+        self.assertEqual(r.raw["creditsCharged"], 0.0375)
+        self.assertEqual(k.calls[0], ("search/lite", {"query": "q", "maxResults": 10}))
+        with self.assertRaises(ValueError):
+            k.search("q", mode="nope")
+
+    def test_context_clamps_budget_and_formats(self):
+        k = FakeKeiro()
+        out = k.context("q", max_tokens=50)
+        self.assertEqual(k.calls[0][1]["budget"], 100)
+        self.assertEqual(out, "[1] T\nhttps://t.com\nevidence text")
+
+    def test_answer_md(self):
+        k = FakeKeiro()
+        self.assertEqual(k.answer("q")["answer"], "42")
+        self.assertEqual(k.calls[0][1]["stream"], False)
+        self.assertEqual(k.md("https://x.com"), "page text")
+
+    def test_missing_key(self):
+        old = os.environ.pop("KEIRO_API_KEY", None)
+        try:
+            with self.assertRaises(keirolabs.KeiroError):
+                Keiro()
+        finally:
+            if old:
+                os.environ["KEIRO_API_KEY"] = old
+
+
+class ToolTests(unittest.TestCase):
+    def test_formats(self):
+        self.assertEqual(tool()["function"]["name"], "web_search")
+        self.assertIn("input_schema", tool("anthropic"))
+        self.assertEqual(keirolabs.run_tool('{"query":""}', client=FakeKeiro()), "Error: query is required.")
+        self.assertIn("https://www.a.com/x", keirolabs.run_tool({"query": "q"}, client=FakeKeiro()))
+
+
+def oa_resp(content=None, calls=None):
+    msg = NS(content=content, tool_calls=calls, model_dump=lambda **_: {"role": "assistant", "tool_calls": "..."})
+    return NS(choices=[NS(message=msg)])
+
+
+class FakeOpenAI:
+    def __init__(self, script):
+        self.script, self.seen = list(script), []
+        self.chat = NS(completions=NS(create=self._create))
+        self.models = "untouched"
+
+    def _create(self, **kw):
+        self.seen.append(kw)
+        return self.script.pop(0)
+
+
+class WrapTests(unittest.TestCase):
+    def test_openai_loop(self):
+        call = NS(id="c1", function=NS(name="web_search", arguments='{"query":"q"}'))
+        fake = FakeOpenAI([oa_resp(calls=[call]), oa_resp(content="done")])
+        c = wrap(fake, keiro=FakeKeiro())
+        r = c.chat.completions.create(model="m", messages=[{"role": "user", "content": "hi"}])
+        self.assertEqual(r.choices[0].message.content, "done")
+        self.assertEqual(c.models, "untouched")
+        second = fake.seen[1]["messages"]
+        self.assertEqual(second[-1]["role"], "tool")
+        self.assertIn("https://www.a.com/x", second[-1]["content"])
+
+    def test_openai_user_tool_passthrough_and_last_step(self):
+        mine = NS(id="c1", function=NS(name="my_tool", arguments="{}"))
+        fake = FakeOpenAI([oa_resp(calls=[mine])])
+        r = wrap(fake, keiro=FakeKeiro()).chat.completions.create(model="m", messages=[], tools=[{"x": 1}])
+        self.assertIs(r.choices[0].message.tool_calls[0], mine)
+        self.assertEqual(len(fake.seen[0]["tools"]), 2)
+        # last round forbids tool calls and the model is nudged to answer
+        call = NS(id="c1", function=NS(name="web_search", arguments='{"query":"q"}'))
+        fake = FakeOpenAI([oa_resp(calls=[call]), oa_resp(content="x")])
+        wrap(fake, max_steps=1, keiro=FakeKeiro()).chat.completions.create(model="m", messages=[])
+        self.assertNotIn("tool_choice", fake.seen[0])
+        self.assertEqual(fake.seen[1]["tool_choice"], "none")
+        self.assertEqual(fake.seen[1]["messages"][-1]["content"], keirolabs.tools.FINAL_NUDGE)
+
+    def test_anthropic_loop(self):
+        use = NS(type="tool_use", id="t1", name="web_search", input={"query": "q"},
+                 model_dump=lambda **_: {"type": "tool_use", "id": "t1"})
+        script = [NS(stop_reason="tool_use", content=[use]), NS(stop_reason="end_turn", content=[NS(type="text", text="ok")])]
+        seen = []
+        fake = NS(messages=NS(create=lambda **kw: (seen.append(kw), script.pop(0))[1]))
+        r = wrap(fake, keiro=FakeKeiro()).messages.create(model="m", max_tokens=10, messages=[{"role": "user", "content": "hi"}])
+        self.assertEqual(r.content[0].text, "ok")
+        self.assertEqual(seen[1]["messages"][-1]["content"][0]["type"], "tool_result")
+
+    def test_rejects_unknown(self):
+        with self.assertRaises(TypeError):
+            wrap(object())
+
+
+class CompatTests(unittest.TestCase):
+    def test_tavily_shape(self):
+        t = TavilyClient.__new__(TavilyClient)
+        t._k = FakeKeiro()
+        r = t.search("q", max_results=2, include_answer=True)
+        self.assertEqual(set(r), {"query", "follow_up_questions", "answer", "images", "results", "response_time"})
+        self.assertEqual(len(r["results"]), 2)
+        self.assertEqual(r["answer"], "42")
+        self.assertGreater(r["results"][0]["score"], r["results"][1]["score"])
+        only = t.search("q", include_domains=["b.org"])["results"]
+        self.assertEqual([x["url"] for x in only], ["https://docs.b.org/y"])
+        none_a = t.search("q", exclude_domains=["a.com"])["results"]
+        self.assertNotIn("https://www.a.com/x", [x["url"] for x in none_a])
+        self.assertEqual(json.loads(t.get_search_context("q"))[0]["url"], "https://www.a.com/x")
+        self.assertEqual(t.extract("https://x.com")["results"][0]["raw_content"], "page text")
+
+
+@unittest.skipUnless(os.environ.get("KEIRO_API_KEY"), "set KEIRO_API_KEY for the live test")
+class LiveTests(unittest.TestCase):
+    def test_live(self):
+        k = Keiro()
+        r = k.search("who won the 2022 world cup")
+        self.assertTrue(r and r[0]["url"].startswith("http"))
+        self.assertIn("http", k.context("who won the 2022 world cup", 300))
+        self.assertTrue(k.answer("capital of france")["answer"])
+        self.assertTrue(k.md("https://example.com"))
+        with self.assertRaises(keirolabs.KeiroError) as e:
+            Keiro(api_key="keiro_bad").search("x")
+        self.assertEqual(e.exception.status, 401)
+
+
+if __name__ == "__main__":
+    unittest.main()