langchain-keenable 0.1.0__tar.gz

langchain_keenable-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+# Publishes langchain-keenable to PyPI via Trusted Publishing (OIDC) — no API
+# tokens or passwords. Runs when a GitHub Release is published. The release tag
+# must match the version in pyproject.toml (e.g. tag v0.1.0 -> version 0.1.0).
+#
+# One-time setup on PyPI (see PUBLISH.md): register a Trusted Publisher /
+# pending publisher for project `langchain-keenable` pointing at this repo,
+# workflow `publish.yml`, environment `pypi`.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/langchain-keenable
+    permissions:
+      id-token: write # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

langchain_keenable-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.benchmarks/
+dist/
+.red_team_scratch/
+red_team_report.*
+.env
+.env.*
+!.env.example

langchain_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.

langchain_keenable-0.1.0/Makefile

@@ -0,0 +1,27 @@
+.PHONY: all format lint test integration_test typing help
+
+all: help
+
+test:
+	uv run --group test python -m pytest tests/unit_tests -q
+
+integration_test:
+	uv run --group test python -m pytest tests/integration_tests -q
+
+lint:
+	uv run --group lint python -m ruff check .
+	uv run --group lint python -m ruff format --check .
+
+format:
+	uv run --group lint python -m ruff format .
+	uv run --group lint python -m ruff check --fix .
+
+typing:
+	uv run --group typing python -m mypy langchain_keenable
+
+help:
+	@echo 'test             - run unit + standard unit tests'
+	@echo 'integration_test - run live integration/standard tests'
+	@echo 'lint             - run ruff check + format --check'
+	@echo 'format           - apply ruff format + fixes'
+	@echo 'typing           - run mypy'

langchain_keenable-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: langchain-keenable
+Version: 0.1.0
+Summary: An integration package connecting Keenable web search and LangChain
+Project-URL: Homepage, https://keenable.ai
+Project-URL: Documentation, https://docs.keenable.ai
+Project-URL: Repository, https://github.com/keenableai/langchain-keenable
+Project-URL: Source Code, https://github.com/keenableai/langchain-keenable
+Author-email: Keenable <hello@keenable.ai>
+License: MIT
+License-File: LICENSE
+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.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: <4.0,>=3.10
+Requires-Dist: langchain-core<2.0,>=0.3
+Requires-Dist: requests<3.0,>=2.32
+Description-Content-Type: text/markdown
+
+# langchain-keenable
+
+This package contains the LangChain integration with [Keenable](https://keenable.ai), a web search
+and page-fetch API built for AI agents.
+
+## Installation
+
+```bash
+pip install -U langchain-keenable
+```
+
+Optionally set a `KEENABLE_API_KEY` environment variable to use the authenticated endpoints. Without a
+key, both search and fetch transparently fall back to their keyless public endpoints.
+
+```bash
+export KEENABLE_API_KEY="your-api-key"  # optional; create one at https://keenable.ai/console
+```
+
+The API endpoint defaults to `https://api.keenable.ai` and can be overridden (e.g. for staging) with the
+`KEENABLE_API_URL` environment variable. It must be an `https://` URL.
+
+## Tools
+
+### `KeenableSearch`
+
+Queries the Keenable search API and returns a list of result dictionaries. All filters are
+**per-invocation**, so an agent can vary them per query:
+
+```python
+from langchain_keenable import KeenableSearch
+
+# Works with no key (keyless public endpoint) or with KEENABLE_API_KEY set.
+tool = KeenableSearch()
+
+results = tool.invoke({
+    "query": "typescript best practices",
+    "site": "github.com",          # optional: restrict to a domain
+    "published_after": "2026-01-01",  # optional: YYYY-MM-DD date filters
+    # "published_before" / "acquired_after" / "acquired_before" also supported
+    # "mode": "realtime",          # optional per-call override (needs an org key)
+})
+for result in results:
+    print(result["title"], result["url"])
+```
+
+`mode` defaults to `"pro"` (deeper retrieval); use `"realtime"` for latency-sensitive cases such as
+voice agents. It can be set as a class default and overridden per call. `realtime` requires an org key.
+
+### `KeenableFetch`
+
+Fetches a page via Keenable and returns its main content as markdown — pair it with `KeenableSearch` so
+an agent can read the pages it discovers:
+
+```python
+from langchain_keenable import KeenableFetch
+
+tool = KeenableFetch()
+page = tool.invoke({"url": "https://example.com/article"})
+print(page["title"], page["content"])
+```
+
+## Error handling
+
+Both tools set `handle_tool_error = True`: rate limits (429), auth (401) and credit (402) errors, network
+timeouts and malformed responses are surfaced to the agent as an error **string** (carrying the backend's
+message) rather than raising and crashing the agent loop.
+
+## Async
+
+Both tools implement `_arun`, so `await tool.ainvoke({...})` works (the request runs in a worker thread).
+
+The tools can be bound to any LangChain chat model that supports tool calling and used within an agent.

langchain_keenable-0.1.0/PUBLISH.md

@@ -0,0 +1,85 @@
+# Publishing `langchain-keenable` to PyPI
+
+This package publishes to PyPI via **Trusted Publishing (OIDC)** — GitHub Actions
+mints a short-lived identity token and PyPI trusts it, so **no API tokens or
+passwords are stored anywhere**. The workflow is
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml); it runs when a
+GitHub **Release** is published.
+
+## One-time setup (do this once, by a PyPI account owner)
+
+The PyPI account needs a **verified email** and **2FA enabled** first
+(https://pypi.org/manage/account/). Then:
+
+1. Go to **https://pypi.org/manage/account/publishing/** ("Publishing" →
+   "Add a new pending publisher"). A *pending* publisher lets you wire this up
+   **before the project exists** — the first release creates the project.
+2. Fill in exactly:
+   - **PyPI Project Name:** `langchain-keenable`
+   - **Owner:** `keenableai`
+   - **Repository name:** `langchain-keenable`
+   - **Workflow name:** `publish.yml`
+   - **Environment name:** `pypi`
+3. Save. (Values must match the workflow exactly, including the environment name
+   `pypi` — a mismatch is the #1 reason publishing silently fails with
+   "not a trusted publisher".)
+4. *(Recommended)* In this GitHub repo → **Settings → Environments → New
+   environment → `pypi`**, and optionally add required reviewers so a release
+   needs a human approval before it publishes.
+
+That's it — no secrets to add to GitHub.
+
+## Cutting a release
+
+1. Bump `version` in `pyproject.toml` (PyPI never lets you re-upload the same
+   version). Commit + push to `main`.
+2. Tag and create a GitHub Release:
+   ```bash
+   git tag v0.1.0           # tag must match pyproject version
+   git push origin v0.1.0
+   gh release create v0.1.0 --title "v0.1.0" --notes "Initial release"
+   ```
+   (Or use the GitHub UI: Releases → Draft a new release.)
+3. The **Publish to PyPI** workflow runs: build → `twine check` → publish via
+   OIDC. Watch it under the repo's **Actions** tab. On success the package is
+   live at https://pypi.org/project/langchain-keenable/.
+4. After the first successful publish you can tighten the PyPI publisher to be
+   project-scoped (it already is, by project name).
+
+You can also trigger a (re)publish manually from **Actions → Publish to PyPI →
+Run workflow** (`workflow_dispatch`) — useful once a tag/release already exists.
+
+## Pre-release checks (run locally first)
+
+```bash
+rm -rf dist && uv build
+uvx twine check dist/*
+uv run --group test pytest tests/unit_tests   # 59 passing, offline
+```
+
+## Troubleshooting ("we tried and it was silent")
+
+- **No verification email on signup:** check Spam; resend from
+  https://pypi.org/manage/account/ → Account emails; the link expires — request a
+  fresh one. Corporate mail (`@keenable.ai`) may filter it; try a personal email
+  and add the work address later.
+- **2FA not enabled:** you cannot create tokens *or* publish without it. Enable a
+  TOTP app under account settings.
+- **Workflow runs but PyPI rejects with "not a trusted publisher":** the pending
+  publisher fields don't match — most often the **environment name** (`pypi`) or
+  the **workflow filename** (`publish.yml`). Re-check step 2 above.
+- **`Missing id-token: write`:** the `publish` job must keep
+  `permissions: id-token: write` (it does). Don't remove it.
+- **Re-uploading the same version:** PyPI refuses silently-looking 400s — bump
+  the version; you can't overwrite `0.1.0` once published.
+
+## Manual fallback (token, only if Actions is unavailable)
+
+Trusted Publishing is preferred. If you must publish from a laptop:
+```bash
+rm -rf dist && uv build
+UV_PUBLISH_TOKEN=pypi-XXXX uv publish     # account- or project-scoped token; user is __token__
+```
+Create the token at https://pypi.org/manage/account/token/ (first one is
+account-scoped because the project doesn't exist yet; switch to a
+project-scoped token after the first publish). Prefer the OIDC workflow above.

langchain_keenable-0.1.0/README.md

@@ -0,0 +1,72 @@
+# langchain-keenable
+
+This package contains the LangChain integration with [Keenable](https://keenable.ai), a web search
+and page-fetch API built for AI agents.
+
+## Installation
+
+```bash
+pip install -U langchain-keenable
+```
+
+Optionally set a `KEENABLE_API_KEY` environment variable to use the authenticated endpoints. Without a
+key, both search and fetch transparently fall back to their keyless public endpoints.
+
+```bash
+export KEENABLE_API_KEY="your-api-key"  # optional; create one at https://keenable.ai/console
+```
+
+The API endpoint defaults to `https://api.keenable.ai` and can be overridden (e.g. for staging) with the
+`KEENABLE_API_URL` environment variable. It must be an `https://` URL.
+
+## Tools
+
+### `KeenableSearch`
+
+Queries the Keenable search API and returns a list of result dictionaries. All filters are
+**per-invocation**, so an agent can vary them per query:
+
+```python
+from langchain_keenable import KeenableSearch
+
+# Works with no key (keyless public endpoint) or with KEENABLE_API_KEY set.
+tool = KeenableSearch()
+
+results = tool.invoke({
+    "query": "typescript best practices",
+    "site": "github.com",          # optional: restrict to a domain
+    "published_after": "2026-01-01",  # optional: YYYY-MM-DD date filters
+    # "published_before" / "acquired_after" / "acquired_before" also supported
+    # "mode": "realtime",          # optional per-call override (needs an org key)
+})
+for result in results:
+    print(result["title"], result["url"])
+```
+
+`mode` defaults to `"pro"` (deeper retrieval); use `"realtime"` for latency-sensitive cases such as
+voice agents. It can be set as a class default and overridden per call. `realtime` requires an org key.
+
+### `KeenableFetch`
+
+Fetches a page via Keenable and returns its main content as markdown — pair it with `KeenableSearch` so
+an agent can read the pages it discovers:
+
+```python
+from langchain_keenable import KeenableFetch
+
+tool = KeenableFetch()
+page = tool.invoke({"url": "https://example.com/article"})
+print(page["title"], page["content"])
+```
+
+## Error handling
+
+Both tools set `handle_tool_error = True`: rate limits (429), auth (401) and credit (402) errors, network
+timeouts and malformed responses are surfaced to the agent as an error **string** (carrying the backend's
+message) rather than raising and crashing the agent loop.
+
+## Async
+
+Both tools implement `_arun`, so `await tool.ainvoke({...})` works (the request runs in a worker thread).
+
+The tools can be bound to any LangChain chat model that supports tool calling and used within an agent.

langchain_keenable-0.1.0/langchain_keenable/__init__.py

@@ -0,0 +1,15 @@
+"""LangChain integration for the Keenable web search API."""
+
+from langchain_keenable.tools import (
+    KeenableFetch,
+    KeenableFetchInput,
+    KeenableSearch,
+    KeenableSearchInput,
+)
+
+__all__ = [
+    "KeenableFetch",
+    "KeenableFetchInput",
+    "KeenableSearch",
+    "KeenableSearchInput",
+]