langchain-diffbot 0.1.0__tar.gz

langchain_diffbot-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.benchmarks/
+.ipynb_checkpoints/
+dist/
+build/
+.env
+
+# Claude Code harness runtime artifacts
+**/.claude/scheduled_tasks.lock

langchain_diffbot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diffbot
+
+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_diffbot-0.1.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: langchain-diffbot
+Version: 0.1.0
+Summary: LangChain integration for the Diffbot Knowledge Graph and Extract APIs
+Project-URL: Homepage, https://www.diffbot.com/
+Project-URL: Repository, https://github.com/diffbot/langchain-diffbot
+Project-URL: Issues, https://github.com/diffbot/langchain-diffbot/issues
+Author: Diffbot
+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: diffbot-python>=0.2.1
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: langchain-core<2.0,>=1.0
+Provides-Extra: examples
+Requires-Dist: fastapi<1.0,>=0.115; extra == 'examples'
+Requires-Dist: langchain-anthropic<2.0,>=1.4; extra == 'examples'
+Requires-Dist: langchain<2.0,>=1.3; extra == 'examples'
+Requires-Dist: langsmith<1.0,>=0.1; extra == 'examples'
+Requires-Dist: python-dotenv<2.0,>=1.0; extra == 'examples'
+Requires-Dist: uvicorn[standard]<1.0,>=0.30; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# langchain-diffbot
+
+A thin LangChain integration over the official [`diffbot-python`](https://github.com/diffbot/diffbot-python) SDK. Every Diffbot API gets the closest LangChain primitive:
+
+| Diffbot API | LangChain class(es) |
+| --- | --- |
+| Knowledge Graph (DQL) | `DiffbotKnowledgeGraphRetriever`, `DiffbotKnowledgeGraphTool` |
+| Web Search | `DiffbotWebSearchRetriever`, `DiffbotWebSearchTool` |
+| Extract (Analyze) | `DiffbotExtractTool`, `DiffbotExtractLoader` |
+| NLP entities | `DiffbotEntitiesTool` |
+| Crawl | `DiffbotCrawlLoader` |
+| LLM RAG (`ask`) | `ChatDiffbot` (with native streaming) |
+
+## Installation
+
+```bash
+pip install langchain-diffbot
+```
+
+## Authentication
+
+Get an API token at https://app.diffbot.com/get-started/ and export it:
+
+```bash
+export DIFFBOT_API_TOKEN="..."
+```
+
+Every class also accepts `diffbot_api_token=...` directly, or a pre-built `diffbot.Diffbot` client via `client=...` (see [Bring-your-own-client](#bring-your-own-client) below).
+
+## Quickstart — Knowledge Graph retriever
+
+```python
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+retriever = DiffbotKnowledgeGraphRetriever(k=5)
+docs = retriever.invoke("type:Organization industries:\"Artificial Intelligence\" location.city.name:\"Boston\"")
+for d in docs:
+    print(d.metadata["name"], "—", d.page_content[:120])
+```
+
+The query string is a [DQL (Diffbot Query Language)](https://docs.diffbot.com/reference/dql-quickstart) expression.
+
+## Shaping the output
+
+Diffbot KG entities and web-search results are large. Dumping them straight into an LLM prompt can blow past per-minute input-token limits in a single call. Both retrievers expose three shaping knobs:
+
+```python
+from langchain_core.documents import Document
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+# 1. Project only the top-level fields you care about. Drops everything else
+#    from `metadata`. Recommended for agent / tool-use scenarios.
+retriever = DiffbotKnowledgeGraphRetriever(
+    k=5,
+    fields=["id", "type", "name", "homepageUri", "nbEmployees"],
+)
+
+# 2. Choose which field becomes `page_content`. First non-empty value wins.
+retriever = DiffbotKnowledgeGraphRetriever(
+    content_fields=["summary", "description", "name"],
+)
+
+# 3. For total control, pass a `document_mapper` that turns a raw entity
+#    dict into whatever Document shape you want.
+def mapper(entity: dict) -> Document:
+    return Document(
+        page_content=entity.get("summary", ""),
+        metadata={"id": entity["id"], "name": entity["name"]},
+    )
+
+retriever = DiffbotKnowledgeGraphRetriever(document_mapper=mapper)
+```
+
+`fields` and `content_fields` are ignored when `document_mapper` is set. The same knobs work on `DiffbotWebSearchRetriever`.
+
+## Web search
+
+```python
+from langchain_diffbot import DiffbotWebSearchRetriever
+
+web = DiffbotWebSearchRetriever(k=5, fields=["title", "pageUrl", "score"])
+docs = web.invoke("diffbot knowledge graph llm grounding")
+```
+
+## Extract a URL
+
+```python
+from langchain_diffbot import DiffbotExtractTool, DiffbotExtractLoader
+
+# Single URL
+tool = DiffbotExtractTool()
+page = tool.invoke({"url": "https://www.diffbot.com/products/extract/"})
+
+# Batch — yields one Document per URL, sync or async
+loader = DiffbotExtractLoader(urls=["https://example.com", "https://diffbot.com"])
+for doc in loader.lazy_load():
+    print(doc.metadata["title"], doc.page_content[:200])
+```
+
+`DiffbotExtractTool` returns a structured `{"error": ..., "errorCode": ...}` dict when Diffbot reports an extraction failure (200 with `errorCode`), so agents can react and try another URL instead of catching an exception. Auth / rate-limit errors propagate as `diffbot.errors.AuthError` / `RateLimitError`.
+
+## ChatDiffbot
+
+```python
+from langchain_core.messages import HumanMessage
+from langchain_diffbot import ChatDiffbot
+
+llm = ChatDiffbot()
+
+for chunk in llm.stream([HumanMessage(content="What is the Diffbot Knowledge Graph?")]):
+    print(chunk.content, end="", flush=True)
+```
+
+`_stream` / `_astream` are native — no thread-pool fallback. `.invoke()` aggregates the stream into a single message.
+
+## Using a retriever in a chain
+
+The retrievers are standard `BaseRetriever`s, so they slot into LCEL like any other:
+
+```python
+from langchain_anthropic import ChatAnthropic
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnablePassthrough
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+retriever = DiffbotKnowledgeGraphRetriever(
+    k=5,
+    fields=["id", "name", "homepageUri", "nbEmployees", "industries"],
+)
+
+prompt = ChatPromptTemplate.from_template(
+    "Answer using only this Diffbot KG context:\n\n{context}\n\nQuestion: {question}"
+)
+
+
+def _format(docs):
+    return "\n---\n".join(
+        f"{d.metadata.get('name')} (id={d.metadata.get('id')}): {d.page_content}"
+        for d in docs
+    )
+
+
+chain = (
+    {"context": retriever | _format, "question": RunnablePassthrough()}
+    | prompt
+    | ChatAnthropic(model="claude-sonnet-4-6")
+    | StrOutputParser()
+)
+
+chain.invoke('type:Organization location.city.name:"Boston" industries:"Biotech"')
+```
+
+## Bring-your-own-client
+
+Every class accepts a pre-built `diffbot.Diffbot` (or `diffbot.DiffbotAsync`) via `client` / `async_client`. The package uses it as-is and **does not close it** — you own the lifecycle. This is the escape hatch for anything the SDK supports that's not re-exposed as a field (custom URLs, `transport=`, shared connection pools, custom headers).
+
+```python
+from diffbot import Diffbot
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+# One client shared across many retriever calls (no per-call httpx pool churn)
+shared = Diffbot(token="...", timeout=60.0)
+retriever = DiffbotKnowledgeGraphRetriever(client=shared, k=5)
+```
+
+## Examples
+
+The [`examples/`](./examples) folder has runnable demos:
+
+- [`examples/quickstart/`](./examples/quickstart) — full tour: every public class, output shaping, async, and a multi-tool research agent.
+- [`examples/company_research/`](./examples/company_research) — the same multi-tool agent as a one-shot CLI: `cd examples && python -m company_research "your question"`. The agent combines KG search + web search + URL extract.
+
+Both need `langchain` + `langchain-anthropic` on top of the base package — install the extra:
+
+```bash
+pip install "langchain-diffbot[examples]"
+```
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest tests/unit_tests
+```
+
+## Releasing
+
+Tokens are stored in macOS Keychain so the Makefile can pull them automatically — no plaintext on disk, no shell-history leaks. First-time setup:
+
+```bash
+make set-token-testpypi    # prompts; input is hidden as you paste
+make set-token-pypi        # same, for real PyPI
+```
+
+Both targets read with `bash read -rsp` (hidden input), overwrite any existing entry, and never put the token in `make` output or shell history. Re-run either one any time you rotate a token.
+
+Then the release flow per version:
+
+```bash
+# 1. Bump the version (edits pyproject.toml in place via `uv version --bump`)
+make bump-patch    # 0.1.0 → 0.1.1
+# or: make bump-minor   # 0.1.0 → 0.2.0
+# or: make bump-major   # 0.1.0 → 1.0.0
+
+# 2. Publish to TestPyPI and verify installable
+make release-test
+make verify-release-test
+
+# 3. Publish to real PyPI (prompts for the version to confirm)
+make release
+make verify-release
+```
+
+`make release-test` and `make release` will refuse to publish if the current `pyproject.toml` version is already on the target index — so the workflow is "bump → release-test → verify → release → verify".
+
+To rotate: revoke the old token at https://pypi.org/manage/account/token/ (or the TestPyPI equivalent), then run `make set-token-pypi` / `make set-token-testpypi` again — it overwrites the existing Keychain entry without prompting.
+
+Integration tests hit the live Diffbot API and require `DIFFBOT_API_TOKEN`:
+
+```bash
+uv run pytest tests/integration_tests
+```

langchain_diffbot-0.1.0/README.md

@@ -0,0 +1,223 @@
+# langchain-diffbot
+
+A thin LangChain integration over the official [`diffbot-python`](https://github.com/diffbot/diffbot-python) SDK. Every Diffbot API gets the closest LangChain primitive:
+
+| Diffbot API | LangChain class(es) |
+| --- | --- |
+| Knowledge Graph (DQL) | `DiffbotKnowledgeGraphRetriever`, `DiffbotKnowledgeGraphTool` |
+| Web Search | `DiffbotWebSearchRetriever`, `DiffbotWebSearchTool` |
+| Extract (Analyze) | `DiffbotExtractTool`, `DiffbotExtractLoader` |
+| NLP entities | `DiffbotEntitiesTool` |
+| Crawl | `DiffbotCrawlLoader` |
+| LLM RAG (`ask`) | `ChatDiffbot` (with native streaming) |
+
+## Installation
+
+```bash
+pip install langchain-diffbot
+```
+
+## Authentication
+
+Get an API token at https://app.diffbot.com/get-started/ and export it:
+
+```bash
+export DIFFBOT_API_TOKEN="..."
+```
+
+Every class also accepts `diffbot_api_token=...` directly, or a pre-built `diffbot.Diffbot` client via `client=...` (see [Bring-your-own-client](#bring-your-own-client) below).
+
+## Quickstart — Knowledge Graph retriever
+
+```python
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+retriever = DiffbotKnowledgeGraphRetriever(k=5)
+docs = retriever.invoke("type:Organization industries:\"Artificial Intelligence\" location.city.name:\"Boston\"")
+for d in docs:
+    print(d.metadata["name"], "—", d.page_content[:120])
+```
+
+The query string is a [DQL (Diffbot Query Language)](https://docs.diffbot.com/reference/dql-quickstart) expression.
+
+## Shaping the output
+
+Diffbot KG entities and web-search results are large. Dumping them straight into an LLM prompt can blow past per-minute input-token limits in a single call. Both retrievers expose three shaping knobs:
+
+```python
+from langchain_core.documents import Document
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+# 1. Project only the top-level fields you care about. Drops everything else
+#    from `metadata`. Recommended for agent / tool-use scenarios.
+retriever = DiffbotKnowledgeGraphRetriever(
+    k=5,
+    fields=["id", "type", "name", "homepageUri", "nbEmployees"],
+)
+
+# 2. Choose which field becomes `page_content`. First non-empty value wins.
+retriever = DiffbotKnowledgeGraphRetriever(
+    content_fields=["summary", "description", "name"],
+)
+
+# 3. For total control, pass a `document_mapper` that turns a raw entity
+#    dict into whatever Document shape you want.
+def mapper(entity: dict) -> Document:
+    return Document(
+        page_content=entity.get("summary", ""),
+        metadata={"id": entity["id"], "name": entity["name"]},
+    )
+
+retriever = DiffbotKnowledgeGraphRetriever(document_mapper=mapper)
+```
+
+`fields` and `content_fields` are ignored when `document_mapper` is set. The same knobs work on `DiffbotWebSearchRetriever`.
+
+## Web search
+
+```python
+from langchain_diffbot import DiffbotWebSearchRetriever
+
+web = DiffbotWebSearchRetriever(k=5, fields=["title", "pageUrl", "score"])
+docs = web.invoke("diffbot knowledge graph llm grounding")
+```
+
+## Extract a URL
+
+```python
+from langchain_diffbot import DiffbotExtractTool, DiffbotExtractLoader
+
+# Single URL
+tool = DiffbotExtractTool()
+page = tool.invoke({"url": "https://www.diffbot.com/products/extract/"})
+
+# Batch — yields one Document per URL, sync or async
+loader = DiffbotExtractLoader(urls=["https://example.com", "https://diffbot.com"])
+for doc in loader.lazy_load():
+    print(doc.metadata["title"], doc.page_content[:200])
+```
+
+`DiffbotExtractTool` returns a structured `{"error": ..., "errorCode": ...}` dict when Diffbot reports an extraction failure (200 with `errorCode`), so agents can react and try another URL instead of catching an exception. Auth / rate-limit errors propagate as `diffbot.errors.AuthError` / `RateLimitError`.
+
+## ChatDiffbot
+
+```python
+from langchain_core.messages import HumanMessage
+from langchain_diffbot import ChatDiffbot
+
+llm = ChatDiffbot()
+
+for chunk in llm.stream([HumanMessage(content="What is the Diffbot Knowledge Graph?")]):
+    print(chunk.content, end="", flush=True)
+```
+
+`_stream` / `_astream` are native — no thread-pool fallback. `.invoke()` aggregates the stream into a single message.
+
+## Using a retriever in a chain
+
+The retrievers are standard `BaseRetriever`s, so they slot into LCEL like any other:
+
+```python
+from langchain_anthropic import ChatAnthropic
+from langchain_core.output_parsers import StrOutputParser
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.runnables import RunnablePassthrough
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+retriever = DiffbotKnowledgeGraphRetriever(
+    k=5,
+    fields=["id", "name", "homepageUri", "nbEmployees", "industries"],
+)
+
+prompt = ChatPromptTemplate.from_template(
+    "Answer using only this Diffbot KG context:\n\n{context}\n\nQuestion: {question}"
+)
+
+
+def _format(docs):
+    return "\n---\n".join(
+        f"{d.metadata.get('name')} (id={d.metadata.get('id')}): {d.page_content}"
+        for d in docs
+    )
+
+
+chain = (
+    {"context": retriever | _format, "question": RunnablePassthrough()}
+    | prompt
+    | ChatAnthropic(model="claude-sonnet-4-6")
+    | StrOutputParser()
+)
+
+chain.invoke('type:Organization location.city.name:"Boston" industries:"Biotech"')
+```
+
+## Bring-your-own-client
+
+Every class accepts a pre-built `diffbot.Diffbot` (or `diffbot.DiffbotAsync`) via `client` / `async_client`. The package uses it as-is and **does not close it** — you own the lifecycle. This is the escape hatch for anything the SDK supports that's not re-exposed as a field (custom URLs, `transport=`, shared connection pools, custom headers).
+
+```python
+from diffbot import Diffbot
+from langchain_diffbot import DiffbotKnowledgeGraphRetriever
+
+# One client shared across many retriever calls (no per-call httpx pool churn)
+shared = Diffbot(token="...", timeout=60.0)
+retriever = DiffbotKnowledgeGraphRetriever(client=shared, k=5)
+```
+
+## Examples
+
+The [`examples/`](./examples) folder has runnable demos:
+
+- [`examples/quickstart/`](./examples/quickstart) — full tour: every public class, output shaping, async, and a multi-tool research agent.
+- [`examples/company_research/`](./examples/company_research) — the same multi-tool agent as a one-shot CLI: `cd examples && python -m company_research "your question"`. The agent combines KG search + web search + URL extract.
+
+Both need `langchain` + `langchain-anthropic` on top of the base package — install the extra:
+
+```bash
+pip install "langchain-diffbot[examples]"
+```
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pytest tests/unit_tests
+```
+
+## Releasing
+
+Tokens are stored in macOS Keychain so the Makefile can pull them automatically — no plaintext on disk, no shell-history leaks. First-time setup:
+
+```bash
+make set-token-testpypi    # prompts; input is hidden as you paste
+make set-token-pypi        # same, for real PyPI
+```
+
+Both targets read with `bash read -rsp` (hidden input), overwrite any existing entry, and never put the token in `make` output or shell history. Re-run either one any time you rotate a token.
+
+Then the release flow per version:
+
+```bash
+# 1. Bump the version (edits pyproject.toml in place via `uv version --bump`)
+make bump-patch    # 0.1.0 → 0.1.1
+# or: make bump-minor   # 0.1.0 → 0.2.0
+# or: make bump-major   # 0.1.0 → 1.0.0
+
+# 2. Publish to TestPyPI and verify installable
+make release-test
+make verify-release-test
+
+# 3. Publish to real PyPI (prompts for the version to confirm)
+make release
+make verify-release
+```
+
+`make release-test` and `make release` will refuse to publish if the current `pyproject.toml` version is already on the target index — so the workflow is "bump → release-test → verify → release → verify".
+
+To rotate: revoke the old token at https://pypi.org/manage/account/token/ (or the TestPyPI equivalent), then run `make set-token-pypi` / `make set-token-testpypi` again — it overwrites the existing Keychain entry without prompting.
+
+Integration tests hit the live Diffbot API and require `DIFFBOT_API_TOKEN`:
+
+```bash
+uv run pytest tests/integration_tests
+```

langchain_diffbot-0.1.0/langchain_diffbot/__init__.py

@@ -0,0 +1,39 @@
+"""LangChain integration for Diffbot.
+
+Thin layer over the official `diffbot-python` SDK. Every public class accepts
+either a `diffbot_api_token` (or `DIFFBOT_API_TOKEN` env var) or a pre-built
+`diffbot.Diffbot` / `diffbot.DiffbotAsync` client via the `client` /
+`async_client` fields — anything the SDK can do, you can do via these classes.
+"""
+
+from langchain_diffbot.chat_models import ChatDiffbot
+from langchain_diffbot.document_loaders import (
+    DiffbotCrawlLoader,
+    DiffbotExtractLoader,
+)
+from langchain_diffbot.retrievers import (
+    DiffbotKnowledgeGraphRetriever,
+    DiffbotWebSearchRetriever,
+)
+from langchain_diffbot.tools import (
+    DiffbotDQLProbeTool,
+    DiffbotEntitiesTool,
+    DiffbotExtractTool,
+    DiffbotKnowledgeGraphTool,
+    DiffbotOntologyTool,
+    DiffbotWebSearchTool,
+)
+
+__all__ = [
+    "ChatDiffbot",
+    "DiffbotCrawlLoader",
+    "DiffbotDQLProbeTool",
+    "DiffbotEntitiesTool",
+    "DiffbotExtractLoader",
+    "DiffbotExtractTool",
+    "DiffbotKnowledgeGraphRetriever",
+    "DiffbotKnowledgeGraphTool",
+    "DiffbotOntologyTool",
+    "DiffbotWebSearchRetriever",
+    "DiffbotWebSearchTool",
+]

langchain_diffbot-0.1.0/langchain_diffbot/_base.py

@@ -0,0 +1,110 @@
+"""Shared base for langchain-diffbot components.
+
+Every public class in this package inherits from `_BaseDiffbotComponent`. The
+mixin holds the token / timeout / optional pre-built SDK clients and exposes
+two context managers (`_sync_db`, `_async_db`) that the components use to
+acquire a `diffbot.Diffbot` / `diffbot.DiffbotAsync` for a single call.
+
+Bring-your-own-client: if the user supplies `client=...` or
+`async_client=...`, we use it as-is and **do not close it** — the user owns
+the lifecycle. Otherwise we construct a fresh SDK client per call and close
+it on exit (same per-call lifecycle as the previous hand-rolled httpx
+wrapper).
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Iterator
+from contextlib import asynccontextmanager, contextmanager
+
+from diffbot import Diffbot, DiffbotAsync
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+
+class _BaseDiffbotComponent(BaseModel):
+    """Mixin holding token, timeout, and optional pre-built SDK clients.
+
+    Concrete classes inherit from this *and* a LangChain base
+    (`BaseRetriever`, `BaseTool`, `BaseDocumentLoader`, `BaseChatModel`).
+    Both are Pydantic models, so their fields merge.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    diffbot_api_token: SecretStr | None = Field(default=None)
+    """Diffbot API token. Falls back to `DIFFBOT_API_TOKEN`.
+
+    Not required when both `client` and `async_client` are supplied.
+    """
+
+    timeout: float = 30.0
+    """HTTP timeout (seconds) for SDK clients we construct ourselves.
+
+    Ignored when `client` / `async_client` are supplied.
+    """
+
+    client: Diffbot | None = Field(default=None, exclude=True, repr=False)
+    """Optional pre-built sync SDK client.
+
+    If set, we use it as-is and do not close it.
+    """
+
+    async_client: DiffbotAsync | None = Field(default=None, exclude=True, repr=False)
+    """Optional pre-built async SDK client.
+
+    If set, we use it as-is and do not close it.
+    """
+
+    @model_validator(mode="after")
+    def _resolve_token(self) -> _BaseDiffbotComponent:
+        # If the user gave us a client (for either side), we can't be sure
+        # they'll use the other side — but token resolution shouldn't block
+        # construction in that case. Defer the missing-token error to call time.
+        if self.client is not None or self.async_client is not None:
+            return self
+        if (
+            self.diffbot_api_token is None
+            or not self.diffbot_api_token.get_secret_value()
+        ):
+            env_token = os.environ.get("DIFFBOT_API_TOKEN", "")
+            if not env_token:
+                msg = (
+                    "A Diffbot API token is required. Pass `diffbot_api_token=...`, "
+                    "set the `DIFFBOT_API_TOKEN` environment variable, or supply a "
+                    "pre-built `client` / `async_client`."
+                )
+                raise ValueError(msg)
+            self.diffbot_api_token = SecretStr(env_token)
+        return self
+
+    def _token(self) -> str:
+        if (
+            self.diffbot_api_token is None
+            or not self.diffbot_api_token.get_secret_value()
+        ):
+            msg = (
+                "A Diffbot API token is required for this call. Pass "
+                "`diffbot_api_token=...`, set `DIFFBOT_API_TOKEN`, or supply a "
+                "pre-built client."
+            )
+            raise ValueError(msg)
+        return self.diffbot_api_token.get_secret_value()
+
+    @contextmanager
+    def _sync_db(self) -> Iterator[Diffbot]:
+        """Yield a `Diffbot` for one call. Closes only clients we constructed."""
+        if self.client is not None:
+            yield self.client
+            return
+        with Diffbot(token=self._token(), timeout=self.timeout) as db:
+            yield db
+
+    @asynccontextmanager
+    async def _async_db(self) -> AsyncIterator[DiffbotAsync]:
+        """Yield a `DiffbotAsync` for one call. Closes only clients we constructed."""
+        if self.async_client is not None:
+            yield self.async_client
+            return
+        async with DiffbotAsync(token=self._token(), timeout=self.timeout) as db:
+            yield db