keenable 0.1.0__tar.gz

keenable-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+uv.lock
+package-lock.json
+.DS_Store

keenable-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keenable
+
+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.

keenable-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: keenable
+Version: 0.1.0
+Summary: Official Python SDK for the Keenable web search API, built for AI agents
+Project-URL: Homepage, https://keenable.ai
+Project-URL: Documentation, https://github.com/keenableai/keenable-sdk#readme
+Project-URL: Repository, https://github.com/keenableai/keenable-sdk
+Project-URL: Issues, https://github.com/keenableai/keenable-sdk/issues
+Author-email: Keenable <support@keenable.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,grounding,keenable,llm,rag,search,web-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# keenable
+
+Official Python SDK for [Keenable](https://keenable.ai), a web search API built
+for AI agents: ranked results that come back with the page text already
+extracted, plus a fetch endpoint that returns any URL as clean markdown.
+
+**Keyless by default.** Every call works with no account and no key. An optional
+`KEENABLE_API_KEY` only lifts the hourly rate limit.
+
+```bash
+pip install keenable
+```
+
+## Search
+
+```python
+from keenable import Keenable
+
+keenable = Keenable()  # or Keenable("keen_...") / set KEENABLE_API_KEY
+
+results = keenable.search("how wafer scale chips avoid the memory bottleneck")
+
+for result in results:
+    print(result.title, result.url)
+    print(result.snippet)
+```
+
+Results carry the page text in `snippet`. (`description` is the page's meta
+description and is empty for most pages, so build prompts from `snippet`.)
+
+Filters are optional and combine freely:
+
+```python
+results = keenable.search(
+    "post-training quantization results",
+    site="arxiv.org",
+    published_after="2026-01-01",
+    snippet_max_length=500,
+)
+```
+
+| Argument | What it does |
+|---|---|
+| `site` | Restrict to one domain, e.g. `"arxiv.org"` |
+| `published_after` / `published_before` | Filter by publication date (`YYYY-MM-DD`) |
+| `acquired_after` / `acquired_before` | Filter by when Keenable indexed the page |
+| `snippet_max_length` | Cap the page text returned per result |
+| `mode` | Search mode; `"pro"` (default) does deeper retrieval |
+
+## Ground a model in one line
+
+`to_context()` renders the result set as a numbered, citable block you can drop
+straight into a prompt:
+
+```python
+context = keenable.search("cerebras inference benchmarks").to_context()
+
+prompt = f"Answer using only these sources, citing them by number.\n\n{context}\n\nQuestion: ..."
+```
+
+It emits `[1] Title (url)` headers followed by the page text, adds results whole
+until the character budget is reached (`max_chars=12000` by default), and never
+truncates a source mid-sentence.
+
+## Read a full page
+
+```python
+page = keenable.fetch("https://cerebras.ai/chip")
+print(page.title)
+print(page.content)  # markdown, boilerplate stripped
+```
+
+## Tool calling
+
+The SDK ships OpenAI-compatible tool definitions, so any inference API that
+speaks that schema can call Keenable directly:
+
+```python
+from keenable import Keenable, TOOLS, run_tool_call
+
+keenable = Keenable()
+response = client.chat.completions.create(model=..., messages=messages, tools=TOOLS)
+
+for call in response.choices[0].message.tool_calls or []:
+    messages.append(
+        {
+            "role": "tool",
+            "tool_call_id": call.id,
+            "content": run_tool_call(
+                keenable, call.function.name, call.function.arguments
+            ),
+        }
+    )
+```
+
+`TOOLS` exposes `keenable_search` and `keenable_fetch`; `run_tool_call` executes
+whichever the model picked and returns text ready for the `tool` message.
+
+## Async
+
+`AsyncKeenable` mirrors the sync client:
+
+```python
+import asyncio
+from keenable import AsyncKeenable
+
+
+async def main():
+    async with AsyncKeenable() as keenable:
+        results = await keenable.search("wafer scale engine")
+        print(results.to_context())
+
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors subclass `KeenableError`:
+
+| Exception | When |
+|---|---|
+| `KeenableRateLimitError` | HTTP 429. Set `KEENABLE_API_KEY` to lift the keyless cap |
+| `KeenableAuthError` | HTTP 401/403, the key was rejected |
+| `KeenableAPIError` | Any other non-2xx response; carries `status_code` |
+| `KeenableConnectionError` | The API could not be reached |
+| `KeenableInvalidRequestError` | Bad arguments; no request was sent |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `KEENABLE_API_KEY` | unset | Lifts the hourly rate limit. Create one at [keenable.ai/console](https://keenable.ai/console) |
+| `KEENABLE_API_URL` | `https://api.keenable.ai` | Override the API base URL |
+
+## License
+
+MIT

keenable-0.1.0/README.md

@@ -0,0 +1,138 @@
+# keenable
+
+Official Python SDK for [Keenable](https://keenable.ai), a web search API built
+for AI agents: ranked results that come back with the page text already
+extracted, plus a fetch endpoint that returns any URL as clean markdown.
+
+**Keyless by default.** Every call works with no account and no key. An optional
+`KEENABLE_API_KEY` only lifts the hourly rate limit.
+
+```bash
+pip install keenable
+```
+
+## Search
+
+```python
+from keenable import Keenable
+
+keenable = Keenable()  # or Keenable("keen_...") / set KEENABLE_API_KEY
+
+results = keenable.search("how wafer scale chips avoid the memory bottleneck")
+
+for result in results:
+    print(result.title, result.url)
+    print(result.snippet)
+```
+
+Results carry the page text in `snippet`. (`description` is the page's meta
+description and is empty for most pages, so build prompts from `snippet`.)
+
+Filters are optional and combine freely:
+
+```python
+results = keenable.search(
+    "post-training quantization results",
+    site="arxiv.org",
+    published_after="2026-01-01",
+    snippet_max_length=500,
+)
+```
+
+| Argument | What it does |
+|---|---|
+| `site` | Restrict to one domain, e.g. `"arxiv.org"` |
+| `published_after` / `published_before` | Filter by publication date (`YYYY-MM-DD`) |
+| `acquired_after` / `acquired_before` | Filter by when Keenable indexed the page |
+| `snippet_max_length` | Cap the page text returned per result |
+| `mode` | Search mode; `"pro"` (default) does deeper retrieval |
+
+## Ground a model in one line
+
+`to_context()` renders the result set as a numbered, citable block you can drop
+straight into a prompt:
+
+```python
+context = keenable.search("cerebras inference benchmarks").to_context()
+
+prompt = f"Answer using only these sources, citing them by number.\n\n{context}\n\nQuestion: ..."
+```
+
+It emits `[1] Title (url)` headers followed by the page text, adds results whole
+until the character budget is reached (`max_chars=12000` by default), and never
+truncates a source mid-sentence.
+
+## Read a full page
+
+```python
+page = keenable.fetch("https://cerebras.ai/chip")
+print(page.title)
+print(page.content)  # markdown, boilerplate stripped
+```
+
+## Tool calling
+
+The SDK ships OpenAI-compatible tool definitions, so any inference API that
+speaks that schema can call Keenable directly:
+
+```python
+from keenable import Keenable, TOOLS, run_tool_call
+
+keenable = Keenable()
+response = client.chat.completions.create(model=..., messages=messages, tools=TOOLS)
+
+for call in response.choices[0].message.tool_calls or []:
+    messages.append(
+        {
+            "role": "tool",
+            "tool_call_id": call.id,
+            "content": run_tool_call(
+                keenable, call.function.name, call.function.arguments
+            ),
+        }
+    )
+```
+
+`TOOLS` exposes `keenable_search` and `keenable_fetch`; `run_tool_call` executes
+whichever the model picked and returns text ready for the `tool` message.
+
+## Async
+
+`AsyncKeenable` mirrors the sync client:
+
+```python
+import asyncio
+from keenable import AsyncKeenable
+
+
+async def main():
+    async with AsyncKeenable() as keenable:
+        results = await keenable.search("wafer scale engine")
+        print(results.to_context())
+
+
+asyncio.run(main())
+```
+
+## Errors
+
+All errors subclass `KeenableError`:
+
+| Exception | When |
+|---|---|
+| `KeenableRateLimitError` | HTTP 429. Set `KEENABLE_API_KEY` to lift the keyless cap |
+| `KeenableAuthError` | HTTP 401/403, the key was rejected |
+| `KeenableAPIError` | Any other non-2xx response; carries `status_code` |
+| `KeenableConnectionError` | The API could not be reached |
+| `KeenableInvalidRequestError` | Bad arguments; no request was sent |
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `KEENABLE_API_KEY` | unset | Lifts the hourly rate limit. Create one at [keenable.ai/console](https://keenable.ai/console) |
+| `KEENABLE_API_URL` | `https://api.keenable.ai` | Override the API base URL |
+
+## License
+
+MIT

keenable-0.1.0/keenable/__init__.py

@@ -0,0 +1,44 @@
+"""Keenable: web search and page fetch for AI agents.
+
+Keyless by default. ``Keenable()`` works with no account; an API key only lifts
+the hourly rate limit.
+
+    from keenable import Keenable
+
+    keenable = Keenable()
+    results = keenable.search("fastest inference providers 2026")
+    context = results.to_context()
+"""
+
+from .client import DEFAULT_BASE_URL, AsyncKeenable, Keenable
+from .errors import (
+    KeenableAPIError,
+    KeenableAuthError,
+    KeenableConnectionError,
+    KeenableError,
+    KeenableInvalidRequestError,
+    KeenableRateLimitError,
+)
+from .models import Page, SearchResponse, SearchResult
+from .tools import FETCH_TOOL, SEARCH_TOOL, TOOLS, run_tool_call
+
+__all__ = [
+    "AsyncKeenable",
+    "DEFAULT_BASE_URL",
+    "FETCH_TOOL",
+    "Keenable",
+    "KeenableAPIError",
+    "KeenableAuthError",
+    "KeenableConnectionError",
+    "KeenableError",
+    "KeenableInvalidRequestError",
+    "KeenableRateLimitError",
+    "Page",
+    "SEARCH_TOOL",
+    "SearchResponse",
+    "SearchResult",
+    "TOOLS",
+    "run_tool_call",
+]
+
+__version__ = "0.1.0"