langchain-diffbot 0.1.0__py3-none-any.whl

langchain_diffbot/tools.py

@@ -0,0 +1,435 @@
+"""Diffbot tools — agent-callable wrappers around individual SDK methods.
+
+Each tool is a thin BaseTool around one `diffbot` method. Args schemas mirror
+the SDK signatures one-for-one so agents calling these tools see the same
+shape as a direct SDK call.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from diffbot import Ontology
+from diffbot.errors import ExtractionError
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForToolRun,
+    CallbackManagerForToolRun,
+)
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr
+
+from langchain_diffbot._base import _BaseDiffbotComponent
+
+
+class _DiffbotExtractInput(BaseModel):
+    url: str = Field(description="URL to extract structured content from.")
+    api: str = Field(
+        default="analyze",
+        description=(
+            "Diffbot extract API to call. Defaults to `analyze` "
+            "(auto-detects content type)."
+        ),
+    )
+    fmt: str = Field(
+        default="markdown",
+        description="Output format. `markdown` uses Diffbot's LLM-optimized mode.",
+    )
+
+
+class DiffbotExtractTool(_BaseDiffbotComponent, BaseTool):
+    """Tool that extracts structured content from a URL via Diffbot's analyze API.
+
+    Returns a small dict so the agent doesn't have to wade through the full
+    raw response. On extraction failure (a 200 response with an `errorCode`
+    body) returns a structured error dict instead of raising, so the agent
+    can react. Auth / rate-limit errors propagate as exceptions — those are
+    infra problems, not per-call signals.
+    """
+
+    name: str = "diffbot_extract"
+    description: str = (
+        "Extract structured content (title, text, type, resolved URL) from a "
+        "single web page. Use for reading the contents of a known URL."
+    )
+    args_schema: type[BaseModel] = _DiffbotExtractInput
+
+    @staticmethod
+    def _shape_response(raw: dict[str, Any]) -> dict[str, Any]:
+        objects = raw.get("objects") or []
+        first = objects[0] if objects else {}
+        return {
+            "content": first.get("text") or raw.get("markdown") or "",
+            "title": first.get("title") or raw.get("title"),
+            "pageUrl": first.get("pageUrl") or raw.get("url"),
+            "resolvedPageUrl": first.get("resolvedPageUrl"),
+            "type": first.get("type") or raw.get("type"),
+        }
+
+    def _run(
+        self,
+        url: str,
+        api: str = "analyze",
+        fmt: str = "markdown",
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        try:
+            with self._sync_db() as db:
+                raw = db.extract(url, api=api, fmt=fmt)
+        except ExtractionError as e:
+            return {"error": str(e), "errorCode": e.error_code}
+        return self._shape_response(raw)
+
+    async def _arun(
+        self,
+        url: str,
+        api: str = "analyze",
+        fmt: str = "markdown",
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        try:
+            async with self._async_db() as db:
+                raw = await db.extract(url, api=api, fmt=fmt)
+        except ExtractionError as e:
+            return {"error": str(e), "errorCode": e.error_code}
+        return self._shape_response(raw)
+
+
+class _DiffbotWebSearchInput(BaseModel):
+    text: str = Field(description="Natural-language search query.")
+    num_results: int | None = Field(
+        default=None, description="Max results to return. Server default if unset."
+    )
+    max_tokens: int | None = Field(
+        default=None, description="Optional total content-token cap."
+    )
+
+
+class DiffbotWebSearchTool(_BaseDiffbotComponent, BaseTool):
+    """Tool that performs a Diffbot web search and returns the raw result list.
+
+    Use this when the agent needs the search results as-is (with score, title,
+    pageUrl, content). For LangChain `Document` output use
+    `DiffbotWebSearchRetriever` instead.
+    """
+
+    name: str = "diffbot_web_search"
+    description: str = (
+        "Search the web via Diffbot. Returns a list of results, each with "
+        "title, pageUrl, score, and content."
+    )
+    args_schema: type[BaseModel] = _DiffbotWebSearchInput
+
+    def _run(
+        self,
+        text: str,
+        num_results: int | None = None,
+        max_tokens: int | None = None,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> list[dict[str, Any]]:
+        with self._sync_db() as db:
+            body = db.web_search(text, num_results=num_results, max_tokens=max_tokens)
+        return body.get("search_results", [])
+
+    async def _arun(
+        self,
+        text: str,
+        num_results: int | None = None,
+        max_tokens: int | None = None,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> list[dict[str, Any]]:
+        async with self._async_db() as db:
+            body = await db.web_search(
+                text, num_results=num_results, max_tokens=max_tokens
+            )
+        return body.get("search_results", [])
+
+
+class _DiffbotEntitiesInput(BaseModel):
+    text: str = Field(description="Text to extract entities and sentiment from.")
+    lang: str = Field(default="auto", description="Language hint (`auto` to detect).")
+
+
+class DiffbotEntitiesTool(_BaseDiffbotComponent, BaseTool):
+    """Tool that identifies entities and sentiment in text via Diffbot NLP.
+
+    Returns the SDK response dict as-is — it's small (entity list + sentiment).
+    Entity IDs in the response can be looked up in the KG via
+    `DiffbotKnowledgeGraphTool` or `DiffbotKnowledgeGraphRetriever` using
+    `id:or("id1","id2",...)`.
+    """
+
+    name: str = "diffbot_entities"
+    description: str = (
+        "Identify entities (people, organizations, places, ...) and sentiment "
+        "in a piece of text. Returns entity IDs that can be looked up in the "
+        "Diffbot Knowledge Graph."
+    )
+    args_schema: type[BaseModel] = _DiffbotEntitiesInput
+
+    def _run(
+        self,
+        text: str,
+        lang: str = "auto",
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        with self._sync_db() as db:
+            return db.entities(text, lang=lang)
+
+    async def _arun(
+        self,
+        text: str,
+        lang: str = "auto",
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        async with self._async_db() as db:
+            return await db.entities(text, lang=lang)
+
+
+class _DiffbotDQLInput(BaseModel):
+    query: str = Field(
+        description='DQL query, e.g. `type:Organization name:"Diffbot"`.'
+    )
+    size: int = Field(default=10, description="Max results.")
+    from_: int = Field(default=0, description="Result offset.")
+    filter: str | None = Field(
+        default=None, description="Optional DQL filter expression."
+    )
+
+
+class DiffbotKnowledgeGraphTool(_BaseDiffbotComponent, BaseTool):
+    """Tool that runs a DQL query against the Diffbot Knowledge Graph.
+
+    Returns the raw response dict (with `data`, `hits`, etc.). For LangChain
+    `Document` output use `DiffbotKnowledgeGraphRetriever` instead.
+
+    Best for agents that have been instructed in DQL syntax.
+    """
+
+    name: str = "diffbot_knowledge_graph"
+    description: str = (
+        "Query the Diffbot Knowledge Graph with a DQL expression "
+        '(e.g. `type:Organization location.city.name:"Boston"`). '
+        "Returns the raw response — use only if you know DQL syntax."
+    )
+    args_schema: type[BaseModel] = _DiffbotDQLInput
+
+    def _run(
+        self,
+        query: str,
+        size: int = 10,
+        from_: int = 0,
+        filter: str | None = None,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        with self._sync_db() as db:
+            body = db.dql(query, size=size, from_=from_, filter=filter)
+        if not isinstance(body, dict):
+            msg = "Unexpected non-JSON DQL response."
+            raise TypeError(msg)
+        return body
+
+    async def _arun(
+        self,
+        query: str,
+        size: int = 10,
+        from_: int = 0,
+        filter: str | None = None,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        async with self._async_db() as db:
+            body = await db.dql(query, size=size, from_=from_, filter=filter)
+        if not isinstance(body, dict):
+            msg = "Unexpected non-JSON DQL response."
+            raise TypeError(msg)
+        return body
+
+
+_OntologyOp = Literal[
+    "types", "composites", "enums", "taxonomies", "fields", "taxonomy", "enum", "search"
+]
+
+
+def _ontology_lookup(
+    ont: Ontology, op: str, name: str | None, search: str | None
+) -> list[str] | dict[str, str]:
+    """Run one ontology navigation op, returning a list or a recoverable error dict.
+
+    `KeyError` (unknown type/taxonomy/enum) and missing-argument `ValueError`s are
+    returned as `{"error": ...}` so the agent can correct itself and retry rather
+    than the tool call raising.
+    """
+    try:
+        if op == "types":
+            return ont.types()
+        if op == "composites":
+            return ont.composites()
+        if op == "enums":
+            return ont.enums()
+        if op == "taxonomies":
+            return ont.taxonomies()
+        if op == "fields":
+            if not name:
+                msg = "op='fields' requires `name` (the entity type or composite)."
+                raise ValueError(msg)
+            fields = ont.fields_for(name)
+            return [
+                Ontology.format_field(n, m)
+                for n, m in Ontology.filter_fields(fields, search)
+            ]
+        if op == "taxonomy":
+            if not name:
+                msg = "op='taxonomy' requires `name` (the taxonomy)."
+                raise ValueError(msg)
+            return ont.taxonomy_values(name, search)
+        if op == "enum":
+            if not name:
+                msg = "op='enum' requires `name` (the enum)."
+                raise ValueError(msg)
+            return ont.enum_values(name)
+        if op == "search":
+            if not name:
+                msg = "op='search' requires `name` (the regex to match)."
+                raise ValueError(msg)
+            return ont.find_named(name)
+        msg = f"Unknown op {op!r}."
+        raise ValueError(msg)
+    except (KeyError, ValueError) as exc:
+        return {
+            "error": str(exc).strip('"'),
+            "hint": (
+                "Valid ops: types, composites, enums, taxonomies, fields, "
+                "taxonomy, enum, search. List names first (e.g. op='types') "
+                "before drilling into fields/taxonomy/enum."
+            ),
+        }
+
+
+class _DiffbotOntologyInput(BaseModel):
+    op: _OntologyOp = Field(
+        description=(
+            "Which part of the ontology to inspect: `types`/`composites`/`enums`/"
+            "`taxonomies` list names; `fields` lists the fields of a type or "
+            "composite; `taxonomy`/`enum` list a named taxonomy's/enum's values; "
+            "`search` matches any name anywhere in the ontology by regex."
+        )
+    )
+    name: str | None = Field(
+        default=None,
+        description=(
+            "Target name for `fields` (a type/composite), `taxonomy`, or `enum`; "
+            "the regex pattern for `search`. Unused by the list ops."
+        ),
+    )
+    search: str | None = Field(
+        default=None,
+        description=(
+            "Optional case-insensitive regex to filter `fields` or `taxonomy` results."
+        ),
+    )
+
+
+class DiffbotOntologyTool(_BaseDiffbotComponent, BaseTool):
+    """Tool that navigates the Diffbot Knowledge Graph ontology.
+
+    Lets an agent discover real entity types, field paths, taxonomy values, and
+    enum values *before* writing a DQL query — so it constructs valid queries
+    instead of guessing field names. The ontology is fetched once over HTTP via
+    `Diffbot.dql_fetch_ontology()` and cached in memory on the tool instance for
+    the rest of its lifetime (pass `refresh=True` in a call to re-fetch).
+    """
+
+    name: str = "diffbot_ontology"
+    description: str = (
+        "Inspect the Diffbot Knowledge Graph schema to build valid DQL. Ops: "
+        "`types`/`composites`/`enums`/`taxonomies` (list names), `fields` "
+        "(fields of a type/composite — pass `name`), `taxonomy`/`enum` (values "
+        "of a named taxonomy/enum — pass `name`), `search` (regex over all "
+        "names — pass the pattern as `name`). Look fields up here before "
+        "writing a DQL query."
+    )
+    args_schema: type[BaseModel] = _DiffbotOntologyInput
+
+    _ontology: Ontology | None = PrivateAttr(default=None)
+
+    def _run(
+        self,
+        op: str,
+        name: str | None = None,
+        search: str | None = None,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> list[str] | dict[str, str]:
+        if self._ontology is None:
+            with self._sync_db() as db:
+                self._ontology = db.dql_fetch_ontology()
+        return _ontology_lookup(self._ontology, op, name, search)
+
+    async def _arun(
+        self,
+        op: str,
+        name: str | None = None,
+        search: str | None = None,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> list[str] | dict[str, str]:
+        if self._ontology is None:
+            async with self._async_db() as db:
+                self._ontology = await db.dql_fetch_ontology()
+        return _ontology_lookup(self._ontology, op, name, search)
+
+
+class _DiffbotDQLProbeInput(BaseModel):
+    queries: list[str] = Field(
+        description=(
+            "DQL query variants to probe. Each is run with size=0 (hit count only)."
+        )
+    )
+    workers: int = Field(default=8, description="Max concurrent requests.")
+
+
+class DiffbotDQLProbeTool(_BaseDiffbotComponent, BaseTool):
+    """Tool that probes DQL query variants in parallel, returning hit counts only.
+
+    Each query runs with `size=0`, so the response carries the match count but no
+    entity data — cheap and fast. Use it to check a query's selectivity (too
+    broad? too narrow?) and compare variants before committing to a full
+    `diffbot_knowledge_graph` query. Backed by `Diffbot.dql_parallel()`.
+    """
+
+    name: str = "diffbot_dql_probe"
+    description: str = (
+        "Probe one or more DQL query variants in parallel and get the hit count "
+        "for each (size=0, no entity data). Use to validate that a query is "
+        "well-shaped — not matching zero results or millions — before running it."
+    )
+    args_schema: type[BaseModel] = _DiffbotDQLProbeInput
+
+    @staticmethod
+    def _shape(queries: list[str], results: list[Any]) -> list[dict[str, Any]]:
+        return [
+            {
+                "query": q,
+                "hits": r.get("hits") if isinstance(r, dict) else None,
+            }
+            for q, r in zip(queries, results, strict=False)
+        ]
+
+    def _run(
+        self,
+        queries: list[str],
+        workers: int = 8,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> list[dict[str, Any]]:
+        reqs = [{"query": q, "size": 0} for q in queries]
+        with self._sync_db() as db:
+            results = db.dql_parallel(reqs, workers=workers)
+        return self._shape(queries, results)
+
+    async def _arun(
+        self,
+        queries: list[str],
+        workers: int = 8,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> list[dict[str, Any]]:
+        reqs = [{"query": q, "size": 0} for q in queries]
+        async with self._async_db() as db:
+            results = await db.dql_parallel(reqs, workers=workers)
+        return self._shape(queries, results)

langchain_diffbot-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+langchain_diffbot/__init__.py,sha256=buggsYKg8Jeb0svJV4PgUKSuvK4CuTXVP1j9HEhSHX0,1139
+langchain_diffbot/_base.py,sha256=eKJ6tZXSkbijTIL0Sal01w0IGSmBtcgo7r0O3CYCZ28,4233
+langchain_diffbot/chat_models.py,sha256=hxwSoOHT27NgAbVQdLh6z93DS_PzCvqmPfGt3H3w3wc,4193
+langchain_diffbot/document_loaders.py,sha256=L7bE69gwnIPn7cqC3oeccuxMe6f3Lz6n7ovdq5H_BBA,5252
+langchain_diffbot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_diffbot/retrievers.py,sha256=flW6CVfJUANGOgNbEdEc0zEsiRBwLICthlXBnbzRLPg,9903
+langchain_diffbot/tools.py,sha256=9jrie3sHjDMYh3f_hYg448w2M_tn7tvpaqm_wHXrRT0,15782
+langchain_diffbot-0.1.0.dist-info/METADATA,sha256=298LPyP0yGBLFaooTZgphjEWZNuzK7T7hwt-8KLA2xU,9440
+langchain_diffbot-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+langchain_diffbot-0.1.0.dist-info/licenses/LICENSE,sha256=ctCt1arYbBpFK3id9IIqaBMAaU3gwnWTmnbzw4bVDSo,1064
+langchain_diffbot-0.1.0.dist-info/RECORD,,