diffbot-python 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

diffbot/__init__.py

@@ -2,14 +2,38 @@
 diffbot - Python client library for the Diffbot APIs.
 """
 
+import warnings as _warnings
 from importlib.metadata import PackageNotFoundError, version as _version
 
-try:
-    __version__ = _version("diffbot-python")
-except PackageNotFoundError:  # not installed (e.g. running from a source tree)
-    __version__ = "0.0.0"
+def _installed_version(dist: str):
+    try:
+        return _version(dist)
+    except PackageNotFoundError:
+        return None
+
+
+# The distribution was renamed from diffbot-python to diffbot. The final
+# diffbot-python release ships this same code (see legacy/diffbot-python), so
+# fall back to its version when that's what is installed.
+_legacy_version = _installed_version("diffbot-python")
+# "0.0.0" when not installed (e.g. running from a source tree).
+__version__ = _installed_version("diffbot") or _legacy_version or "0.0.0"
+
+# Both distributions ship this module, so a diffbot-python install (alone, or
+# left over next to diffbot) should migrate. FutureWarning, unlike
+# DeprecationWarning, is shown by default wherever the import happens.
+if _legacy_version is not None:
+    _warnings.warn(
+        "diffbot-python has been renamed to diffbot and will receive no further "
+        "updates. Run `pip uninstall diffbot-python && pip install "
+        "--force-reinstall diffbot` and replace diffbot-python with diffbot in "
+        "your requirements.",
+        FutureWarning,
+        stacklevel=2,
+    )
 
 from ._auth import resolve_token
+from .ask import json_schema_format
 from .client import Diffbot, DiffbotAsync
 from .crawl import CrawlEvent, CrawlEventType
 from .errors import (
@@ -26,6 +50,7 @@ __all__ = [
     "Diffbot",
     "DiffbotAsync",
     "resolve_token",
+    "json_schema_format",
     "CrawlEvent",
     "CrawlEventType",
     "Ontology",

diffbot/ask.py

@@ -1,15 +1,75 @@
 """Diffbot LLM RAG API: stream a chat completion."""
 
 import json
-from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Iterator, List
+import re
+from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Iterator, List, Optional
+
+from .errors import ValidationError
 
 if TYPE_CHECKING:
     from .client import Diffbot, DiffbotAsync
 
+MODEL = "diffbot-small-xl"
+
+#: `response_format` types accepted by the Diffbot LLM endpoint.
+RESPONSE_FORMAT_TYPES = ("text", "json_object", "json_schema")
+
+# The RAG loop may prefix its final answer with a think block, and the model
+# occasionally wraps JSON in a markdown fence despite being told not to.
+_THINK_BLOCK = re.compile(r"<think>.*?</think>", re.DOTALL)
+_JSON_FENCE = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE)
+
+
+def json_schema_format(schema: Dict[str, Any], *, name: str = "response") -> Dict[str, Any]:
+    """Build a ``response_format`` value that constrains output to ``schema``.
+
+    The endpoint requires the schema nested under ``json_schema.schema``; passing
+    it anywhere else is ignored server-side without an error, so prefer this
+    helper over hand-building the dict.
+
+    Example:
+        >>> json_schema_format({"type": "object", "properties": {"city": {"type": "string"}}})
+        {'type': 'json_schema', 'json_schema': {'name': 'response', 'schema': {...}}}
+    """
+    if not isinstance(schema, dict):
+        raise ValidationError("schema must be a JSON Schema dict")
+    return {"type": "json_schema", "json_schema": {"name": name, "schema": schema}}
+
 
-def _build_payload(client: Any, messages: List[Dict[str, str]]) -> tuple:
+def _validate_response_format(response_format: Optional[Dict[str, Any]]) -> None:
+    """Reject shapes the endpoint would accept but silently not enforce."""
+    if response_format is None:
+        return
+    if not isinstance(response_format, dict):
+        raise ValidationError("response_format must be a dict")
+
+    fmt_type = response_format.get("type", "text")
+    if fmt_type not in RESPONSE_FORMAT_TYPES:
+        raise ValidationError(
+            f"response_format type must be one of {', '.join(RESPONSE_FORMAT_TYPES)}; got {fmt_type!r}"
+        )
+
+    if fmt_type == "json_schema":
+        json_schema = response_format.get("json_schema")
+        if not isinstance(json_schema, dict) or "schema" not in json_schema:
+            raise ValidationError(
+                'response_format {"type": "json_schema"} requires the schema nested as '
+                '{"json_schema": {"schema": {...}}}. Without it the server returns 200 and '
+                "ignores the constraint. Use diffbot.json_schema_format(schema) to build it."
+            )
+
+
+def _build_payload(
+    client: Any,
+    messages: List[Dict[str, str]],
+    *,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> tuple:
+    _validate_response_format(response_format)
     headers = {"Authorization": f"Bearer {client.token}"}
-    payload = {"model": "diffbot-small-xl", "messages": messages, "stream": True}
+    payload: Dict[str, Any] = {"model": MODEL, "messages": messages, "stream": True}
+    if response_format is not None:
+        payload["response_format"] = response_format
     return headers, payload
 
 
@@ -24,9 +84,68 @@ def _parse_chunk(line: str):
     return None
 
 
-def ask(client: "Diffbot", messages: List[Dict[str, str]]) -> Iterator[str]:
-    headers = {"Authorization": f"Bearer {client.token}"}
-    payload = {"model": "diffbot-small-xl", "messages": messages, "stream": True}
+def _extract_json(text: str) -> Any:
+    """Parse the model's final answer as JSON, tolerating think blocks and fences."""
+    cleaned = _THINK_BLOCK.sub("", text).strip()
+    cleaned = _JSON_FENCE.sub("", cleaned).strip()
+
+    try:
+        return json.loads(cleaned)
+    except json.JSONDecodeError:
+        pass
+
+    # Fall back to the outermost object or array span in the response.
+    spans = []
+    for opener, closer in (("{", "}"), ("[", "]")):
+        start, end = cleaned.find(opener), cleaned.rfind(closer)
+        if start != -1 and end > start:
+            spans.append((start, cleaned[start : end + 1]))
+    for _, span in sorted(spans):
+        try:
+            return json.loads(span)
+        except json.JSONDecodeError:
+            continue
+
+    raise ValidationError(f"could not parse JSON from the model response: {text[:200]!r}")
+
+
+#: Schema used when the caller wants JSON but has no shape in mind. This goes
+#: through the json_schema path rather than {"type": "json_object"} on purpose:
+#: json_object applies no server-side grammar, so the RAG loop's internal
+#: <functioncall> JSON satisfies it and gets returned as the final answer. That
+#: is reproducible whenever the request carries a system message.
+ANY_OBJECT_SCHEMA = {"type": "object"}
+
+
+def _resolve_format(
+    schema: Optional[Dict[str, Any]],
+    response_format: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    if schema is not None and response_format is not None:
+        raise ValidationError("pass either schema or response_format, not both")
+    if response_format is not None:
+        return response_format
+    return json_schema_format(schema if schema is not None else ANY_OBJECT_SCHEMA)
+
+
+def _check_tool_call_leak(parsed: Any) -> Any:
+    """Catch the internal tool call surfacing as the answer (see ANY_OBJECT_SCHEMA)."""
+    if isinstance(parsed, dict) and parsed.get("name") == "functioncall" and "arguments" in parsed:
+        raise ValidationError(
+            "the model returned its internal tool call instead of an answer; this happens with "
+            'response_format {"type": "json_object"} because the server applies no grammar to it. '
+            "Pass a schema instead."
+        )
+    return parsed
+
+
+def ask(
+    client: "Diffbot",
+    messages: List[Dict[str, str]],
+    *,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> Iterator[str]:
+    headers, payload = _build_payload(client, messages, response_format=response_format)
     with client._http.stream("POST", client.llm_url, headers=headers, json=payload) as response:
         client._raise_for_status(response)
         for line in response.iter_lines():
@@ -36,9 +155,13 @@ def ask(client: "Diffbot", messages: List[Dict[str, str]]) -> Iterator[str]:
                     yield content
 
 
-async def ask_async(client: "DiffbotAsync", messages: List[Dict[str, str]]) -> AsyncIterator[str]:
-    headers = {"Authorization": f"Bearer {client.token}"}
-    payload = {"model": "diffbot-small-xl", "messages": messages, "stream": True}
+async def ask_async(
+    client: "DiffbotAsync",
+    messages: List[Dict[str, str]],
+    *,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> AsyncIterator[str]:
+    headers, payload = _build_payload(client, messages, response_format=response_format)
     async with client._http.stream("POST", client.llm_url, headers=headers, json=payload) as response:
         client._raise_for_status(response)
         async for line in response.aiter_lines():
@@ -46,3 +169,27 @@ async def ask_async(client: "DiffbotAsync", messages: List[Dict[str, str]]) -> A
                 content = _parse_chunk(line)
                 if content:
                     yield content
+
+
+def ask_json(
+    client: "Diffbot",
+    messages: List[Dict[str, str]],
+    schema: Optional[Dict[str, Any]] = None,
+    *,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> Any:
+    fmt = _resolve_format(schema, response_format)
+    text = "".join(ask(client, messages, response_format=fmt))
+    return _check_tool_call_leak(_extract_json(text))
+
+
+async def ask_json_async(
+    client: "DiffbotAsync",
+    messages: List[Dict[str, str]],
+    schema: Optional[Dict[str, Any]] = None,
+    *,
+    response_format: Optional[Dict[str, Any]] = None,
+) -> Any:
+    fmt = _resolve_format(schema, response_format)
+    chunks = [chunk async for chunk in ask_async(client, messages, response_format=fmt)]
+    return _check_tool_call_leak(_extract_json("".join(chunks)))

diffbot/cli/__init__.py

@@ -11,7 +11,15 @@ from rich.markdown import Markdown
 from rich.progress import Progress, SpinnerColumn, TextColumn
 from datetime import datetime
 
-from diffbot import CrawlEventType, AuthError, ExtractionError, APIError
+from diffbot import (
+    __version__,
+    CrawlEventType,
+    AuthError,
+    ExtractionError,
+    APIError,
+    ValidationError,
+    json_schema_format,
+)
 
 from ._common import get_client
 
@@ -28,6 +36,7 @@ def print_markdown(text):
 
 
 @click.group()
+@click.version_option(__version__, "-V", "--version", prog_name="db")
 def main():
     """
     Diffbot 🤖 Structure the world's knowledge.
@@ -85,10 +94,29 @@ def extract(url, output, fmt, api):
 @click.argument("prompt")
 @click.option("-o", "--output", type=click.Path(), help="Write output to file instead of stdout")
 @click.option("--json", "as_json", is_flag=True, help="Output from LLM as JSON")
-def ask(prompt: str, output: str = None, as_json: bool = False):
+@click.option(
+    "--schema",
+    "schema_path",
+    type=click.Path(exists=True, dir_okay=False),
+    help="JSON Schema file constraining the output (implies --json)",
+)
+def ask(prompt: str, output: str = None, as_json: bool = False, schema_path: str = None):
     """Ask a question to the Diffbot LLM"""
     db = get_client()
     stdin_content = sys.stdin.read() if not sys.stdin.isatty() else None
+
+    response_format = None
+    if schema_path:
+        as_json = True
+        try:
+            with open(schema_path) as f:
+                response_format = json_schema_format(json.load(f))
+        except json.JSONDecodeError as e:
+            click.echo(f"Error: {schema_path} is not valid JSON: {e}", err=True)
+            raise click.Abort()
+
+    # Without --schema, response_format stays None and ask_json picks its own
+    # permissive default; --json alone must not become {"type": "json_object"}.
     interactive_mode = is_interactive and not output and not as_json
 
     messages = [
@@ -99,9 +127,6 @@ def ask(prompt: str, output: str = None, as_json: bool = False):
         {"role": "user", "content": prompt},
     ]
 
-    if as_json:
-        messages[1]["content"] += "\nReturn the output as a JSON object. Do not include any other text outside of the JSON object."
-
     if stdin_content:
         messages[1]["content"] = f"<input>{stdin_content}</input>\n" + messages[1]["content"]
 
@@ -136,17 +161,20 @@ def ask(prompt: str, output: str = None, as_json: bool = False):
         else:
             response = ""
             if output:
-                for chunk in db.ask(messages):
-                    response += chunk
+                if as_json:
+                    response = json.dumps(
+                        db.ask_json(messages, response_format=response_format), indent=2
+                    )
+                else:
+                    for chunk in db.ask(messages):
+                        response += chunk
                 with open(output, "w") as f:
                     f.write(response)
                 click.echo(f"Output written to {output}")
             elif as_json:
-                buffer = ""
-                for chunk in db.ask(messages):
-                    buffer += chunk
-                buffer = buffer[buffer.find("{") : buffer.rfind("}") + 1]
-                sys.stdout.write(buffer)
+                sys.stdout.write(
+                    json.dumps(db.ask_json(messages, response_format=response_format), indent=2)
+                )
             else:
                 for chunk in db.ask(messages):
                     sys.stdout.write(chunk)
@@ -155,6 +183,9 @@ def ask(prompt: str, output: str = None, as_json: bool = False):
     except AuthError:
         click.echo("Error: Invalid or unauthorized API token.", err=True)
         raise click.Abort()
+    except ValidationError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
     except APIError as e:
         click.echo(f"API error {e.status_code}: {e.message or e.body}", err=True)
         raise click.Abort()

diffbot/client.py

@@ -9,7 +9,12 @@ import httpx
 from . import __version__
 from .errors import APIError, AuthError, RateLimitError, ValidationError
 from .extract import extract as _extract, extract_async as _extract_async
-from .ask import ask as _ask, ask_async as _ask_async
+from .ask import (
+    ask as _ask,
+    ask_async as _ask_async,
+    ask_json as _ask_json,
+    ask_json_async as _ask_json_async,
+)
 from .crawl import (
     CrawlEvent,
     crawl as _crawl,
@@ -22,6 +27,8 @@ from .crawl import (
     crawl_list_jobs_async as _crawl_list_jobs_async,
 )
 from .kg import (
+    KG_DQL_ENDPOINT,
+    KG_ONTOLOGY_ENDPOINT,
     dql as _dql,
     dql_async as _dql_async,
     dql_fetch_ontology as _dql_fetch_ontology,
@@ -67,6 +74,8 @@ class Diffbot:
         crawler_url: str = CRAWL_BASE,
         web_search_url: str = WEB_SEARCH_BASE,
         nlp_url: str = NLP_BASE,
+        dql_url: str = KG_DQL_ENDPOINT,
+        ontology_url: str = KG_ONTOLOGY_ENDPOINT,
         transport: Optional[httpx.BaseTransport] = None,
     ):
         if not token:
@@ -77,6 +86,8 @@ class Diffbot:
         self.crawler_url = crawler_url
         self.web_search_url = web_search_url
         self.nlp_url = nlp_url
+        self.dql_url = dql_url
+        self.ontology_url = ontology_url
         self._http = httpx.Client(
             timeout=timeout,
             headers={"User-Agent": f"diffbot-python/{__version__}"},
@@ -112,9 +123,32 @@ class Diffbot:
         """Extract structured content from a URL. Returns the raw Diffbot API response."""
         return _extract(self, url, api=api, fmt=fmt)
 
-    def ask(self, messages: List[Dict[str, str]]) -> Iterator[str]:
-        """Stream a response from the Diffbot LLM RAG API."""
-        yield from _ask(self, messages)
+    def ask(
+        self,
+        messages: List[Dict[str, str]],
+        *,
+        response_format: Optional[Dict[str, Any]] = None,
+    ) -> Iterator[str]:
+        """Stream a response from the Diffbot LLM RAG API.
+
+        Pass ``response_format`` to constrain the output, e.g.
+        ``{"type": "json_object"}`` or ``diffbot.json_schema_format(schema)``.
+        """
+        yield from _ask(self, messages, response_format=response_format)
+
+    def ask_json(
+        self,
+        messages: List[Dict[str, str]],
+        schema: Optional[Dict[str, Any]] = None,
+        *,
+        response_format: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Ask the Diffbot LLM and return the answer parsed as JSON.
+
+        With ``schema`` (a JSON Schema dict) the model is constrained to it by
+        grammar; without one it falls back to unconstrained JSON output.
+        """
+        return _ask_json(self, messages, schema, response_format=response_format)
 
     def crawl(self, site: str, **kwargs: Any) -> Iterator[CrawlEvent]:
         """Start a crawl job."""
@@ -194,6 +228,8 @@ class DiffbotAsync:
         crawler_url: str = CRAWL_BASE,
         web_search_url: str = WEB_SEARCH_BASE,
         nlp_url: str = NLP_BASE,
+        dql_url: str = KG_DQL_ENDPOINT,
+        ontology_url: str = KG_ONTOLOGY_ENDPOINT,
         transport: Optional[httpx.AsyncBaseTransport] = None,
     ):
         if not token:
@@ -204,6 +240,8 @@ class DiffbotAsync:
         self.crawler_url = crawler_url
         self.web_search_url = web_search_url
         self.nlp_url = nlp_url
+        self.dql_url = dql_url
+        self.ontology_url = ontology_url
         self._http = httpx.AsyncClient(
             timeout=timeout,
             headers={"User-Agent": f"diffbot-python/{__version__}"},
@@ -239,11 +277,34 @@ class DiffbotAsync:
         """Extract structured content from a URL. Returns the raw Diffbot API response."""
         return await _extract_async(self, url, api=api, fmt=fmt)
 
-    async def ask(self, messages: List[Dict[str, str]]) -> AsyncIterator[str]:
-        """Stream a response from the Diffbot LLM RAG API."""
-        async for chunk in _ask_async(self, messages):
+    async def ask(
+        self,
+        messages: List[Dict[str, str]],
+        *,
+        response_format: Optional[Dict[str, Any]] = None,
+    ) -> AsyncIterator[str]:
+        """Stream a response from the Diffbot LLM RAG API.
+
+        Pass ``response_format`` to constrain the output, e.g.
+        ``{"type": "json_object"}`` or ``diffbot.json_schema_format(schema)``.
+        """
+        async for chunk in _ask_async(self, messages, response_format=response_format):
             yield chunk
 
+    async def ask_json(
+        self,
+        messages: List[Dict[str, str]],
+        schema: Optional[Dict[str, Any]] = None,
+        *,
+        response_format: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """Ask the Diffbot LLM and return the answer parsed as JSON.
+
+        With ``schema`` (a JSON Schema dict) the model is constrained to it by
+        grammar; without one it falls back to unconstrained JSON output.
+        """
+        return await _ask_json_async(self, messages, schema, response_format=response_format)
+
     async def crawl(self, site: str, **kwargs: Any) -> AsyncIterator[CrawlEvent]:
         """Start a crawl job. Pass watch=True to poll until completion and yield URL_PROCESSED events."""
         async for event in _crawl_async(self, site, **kwargs):

diffbot/kg.py

@@ -51,7 +51,7 @@ def dql(
     raw: bool = False,
 ) -> Union[Dict[str, Any], bytes]:
     params = _build_dql_params(client, query, size, from_, format, filter, exportspec, extra)
-    response = client._http.get(KG_DQL_ENDPOINT, params=params)
+    response = client._http.get(client.dql_url, params=params)
     client._raise_for_status(response)
     return response.content if raw else response.json()
 
@@ -69,7 +69,7 @@ async def dql_async(
     raw: bool = False,
 ) -> Union[Dict[str, Any], bytes]:
     params = _build_dql_params(client, query, size, from_, format, filter, exportspec, extra)
-    response = await client._http.get(KG_DQL_ENDPOINT, params=params)
+    response = await client._http.get(client.dql_url, params=params)
     client._raise_for_status(response)
     return response.content if raw else response.json()
 
@@ -104,7 +104,7 @@ async def dql_parallel_async(
 
 
 def dql_refresh_ontology(client: "Diffbot", dest: pathlib.Path) -> None:
-    response = client._http.get(KG_ONTOLOGY_ENDPOINT)
+    response = client._http.get(client.ontology_url)
     client._raise_for_status(response)
     dest.parent.mkdir(parents=True, exist_ok=True)
     dest.write_bytes(response.content)
@@ -116,13 +116,13 @@ def dql_fetch_ontology(client: "Diffbot") -> Ontology:
     Performs no caching — the caller decides whether and where to hold onto the
     result. Use :func:`dql_refresh_ontology` instead to persist raw bytes to disk.
     """
-    response = client._http.get(KG_ONTOLOGY_ENDPOINT)
+    response = client._http.get(client.ontology_url)
     client._raise_for_status(response)
     return Ontology.from_json(response.content)
 
 
 async def dql_fetch_ontology_async(client: "DiffbotAsync") -> Ontology:
     """Async variant of :func:`dql_fetch_ontology`."""
-    response = await client._http.get(KG_ONTOLOGY_ENDPOINT)
+    response = await client._http.get(client.ontology_url)
     client._raise_for_status(response)
     return Ontology.from_json(response.content)

diffbot_python-0.3.0.dist-info/METADATA

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: diffbot-python
+Version: 0.3.0
+Summary: ⚠️ LEGACY — renamed to diffbot. Final release, no further updates: pip install diffbot
+Project-URL: Homepage, https://pypi.org/project/diffbot/
+Project-URL: Repository, https://github.com/diffbot/diffbot-python
+Author-email: Jerome Choo <jerome@diffbot.com>, Mike Tung <miket@diffbot.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 7 - Inactive
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# ⚠️ LEGACY PACKAGE — `diffbot-python` is now `diffbot` ⚠️
+
+> ## 🛑 Do not install `diffbot-python`. Install [`diffbot`](https://pypi.org/project/diffbot/) instead:
+>
+> ```bash
+> pip uninstall diffbot-python
+> pip install diffbot
+> ```
+>
+> **This is the final release of `diffbot-python` (0.3.0). It will never be updated again**:
+> no bug fixes, no new Diffbot API features, no security fixes.
+
+---
+
+The Diffbot Python library and `db` CLI now live at
+**[diffbot](https://pypi.org/project/diffbot/)**. The import name is unchanged
+(`import diffbot`), so no code changes are needed.
+
+This release contains the same code as `diffbot` 3.0.0 so existing installs keep
+working, but it prints a warning on every import until you migrate.
+
+## Migrating
+
+1. Replace `diffbot-python` with `diffbot` in your `requirements.txt`, `pyproject.toml`, etc.
+2. Uninstall the old package **before** installing the new one:
+
+   ```bash
+   pip uninstall diffbot-python
+   pip install diffbot
+   ```
+
+   Both packages provide the same `diffbot` module, so uninstalling
+   `diffbot-python` after `diffbot` is installed deletes files that `diffbot`
+   needs. If that happened, run `pip install --force-reinstall diffbot`.
+
+Source and issues: <https://github.com/diffbot/diffbot-python>.

{diffbot_python-0.2.1.dist-info → diffbot_python-0.3.0.dist-info}/RECORD

@@ -1,22 +1,22 @@
-diffbot/__init__.py,sha256=OUDi3bVvKowQAQB4m8I4t761ct4pC-3de461qPI4Zok,827
+diffbot/__init__.py,sha256=LAZr0P760URw34JXMIcN-2fTMIELq_-IUd1gj8KgVfI,1875
 diffbot/_auth.py,sha256=dzNMWqIjtG3YtRBb_EKpPRiBxvZgogxvoE0ABLvzfOk,1251
-diffbot/ask.py,sha256=iNv613j4CoIfdDTOE-pl9KUkjqI-2AxGDMR1prm3DGM,1853
-diffbot/client.py,sha256=G6vYUEDEaIqjJXcIRxAjwS_cvaXvM7KdQFVMIedkgUY,11315
+diffbot/ask.py,sha256=taLISU0BUHzi9SwESZmgDST8PUHoLGJnI02aHngljQM,7411
+diffbot/client.py,sha256=k3orUmOv1RG_xHInyEt0bS0CIYyTOBW56ZDEMgvX8nc,13379
 diffbot/crawl.py,sha256=iYMFmf7HKrbefJrGg14VnlfiBFLOE_Z1pfO4Rn_cDXc,8893
 diffbot/errors.py,sha256=5-AceX5MyNVUhe9pvR_4rnQQmBhvLfwWmrRl7dRZUSg,1576
 diffbot/extract.py,sha256=R9SVxaOi4FjHOQIX5ho_75OwaJ7VdX-mdAoV_UY-lrM,1452
-diffbot/kg.py,sha256=my-5vR4Vbe3LHzBDYVHLHo99KTtyiRXCT5625glsrlQ,3930
+diffbot/kg.py,sha256=WPvy3B_ywdoM0uEmAgN7-3uOvf4aC4l2mjS2v_tWPN4,3925
 diffbot/nlp.py,sha256=lZJW4MkjhVklIEM2OBfhc8LvresXTy7RsuImPteYsOA,1153
 diffbot/ontology.py,sha256=GWD5m2rz7ECWY6RrO1TeN3kk3DYTgmEHz6gFKASMvAU,6283
 diffbot/web_search.py,sha256=RSaEK0pdAdLgtilc500Mf2MNmJ1DmiYYmIlBQBWvOpE,1356
-diffbot/cli/__init__.py,sha256=UVGD3uevKTHmqEdbDhhR2PzO6-3i0xu8d7D_94jLLRo,16488
+diffbot/cli/__init__.py,sha256=uCngMioFdxTSeUrBxPrxepVqqwllAjXVr8W-zThcYaE,17435
 diffbot/cli/__main__.py,sha256=5BjNuyet8AY-POwoF5rGt722rHQ7tJ0Vf0UFUfzzi-I,58
 diffbot/cli/_common.py,sha256=_s8WRukzSX3krjJW6HJmT7_3hEjNyv1i_y45tm81b2A,654
 diffbot/cli/dql.py,sha256=iIMaGysMWTScnbAHAdWei2iVUJpMV5lA1pk1E9uQg4s,11439
 diffbot/cli/entities.py,sha256=tsHKexF0b6NnsoUEZJUS2rJidTIE8lt6xrcSenPbwtY,5630
 diffbot/cli/ontology.py,sha256=cLuRQ0KTsOJnFCXdG_zIX9J1ODK8ThPznWVDDEpO1pg,2055
-diffbot_python-0.2.1.dist-info/METADATA,sha256=xNpRnsnbGtPxU-zUAPwozdiHprTBS82zjUD87BMO36U,7402
-diffbot_python-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-diffbot_python-0.2.1.dist-info/entry_points.txt,sha256=FCxJhrbl7VNEsTK7zl7qYvXID7gQ1_wxhiw5_Vllb_M,40
-diffbot_python-0.2.1.dist-info/licenses/LICENSE,sha256=UZlamI1XGeiG0Mit8dsHssNhOuMGKfmNOp5qpf1533w,1063
-diffbot_python-0.2.1.dist-info/RECORD,,
+diffbot_python-0.3.0.dist-info/METADATA,sha256=ryJb4Ai_rjjbtmngp1o6cYnennDxK3dJWsokcKZ7-U0,1985
+diffbot_python-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+diffbot_python-0.3.0.dist-info/entry_points.txt,sha256=FCxJhrbl7VNEsTK7zl7qYvXID7gQ1_wxhiw5_Vllb_M,40
+diffbot_python-0.3.0.dist-info/licenses/LICENSE,sha256=UZlamI1XGeiG0Mit8dsHssNhOuMGKfmNOp5qpf1533w,1063
+diffbot_python-0.3.0.dist-info/RECORD,,

diffbot_python-0.2.1.dist-info/METADATA

@@ -1,266 +0,0 @@
-Metadata-Version: 2.4
-Name: diffbot-python
-Version: 0.2.1
-Summary: Python client library for Diffbot APIs
-Project-URL: Homepage, https://github.com/diffbot/diffbot-python
-Project-URL: Documentation, https://github.com/diffbot/diffbot-python#readme
-Project-URL: Repository, https://github.com/diffbot/diffbot-python
-Project-URL: Issues, https://github.com/diffbot/diffbot-python/issues
-Author-email: Jerome Choo <jerome@diffbot.com>, Mike Tung <miket@diffbot.com>
-License-Expression: MIT
-License-File: LICENSE
-Keywords: api-client,crawler,diffbot,extract,knowledge-graph,llm,nlp,web-scraping
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-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 :: Internet :: WWW/HTTP
-Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Text Processing :: Markup :: HTML
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Requires-Dist: click>=8.1.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: rich>=13.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# Diffbot Python Library
-
-Python client library for [Diffbot](https://www.diffbot.com) APIs.
-
-
-## Installation
-
-```bash
-python3 -m pip install diffbot-python
-```
-
-Or, for local development:
-
-```bash
-pip install -e ".[dev]"
-```
-
-## Usage
-
-### Authentication
-
-The CLI and the library can share a single credential. The token always has to be
-passed to the client explicitly, but `resolve_token()` gives you the same lookup the
-CLI uses, in this order:
-
-1. An explicit token passed to `resolve_token(token)`.
-2. The `DIFFBOT_API_TOKEN` environment variable.
-3. A `DIFFBOT_API_TOKEN=...` line in `~/.diffbot/credentials`.
-
-Set it once and it works for both the CLI and your scripts. Either export it:
-
-```bash
-export DIFFBOT_API_TOKEN=<TOKEN>
-```
-
-…or write it to the shared credentials file (handy for keeping it out of your shell environment):
-
-```bash
-mkdir -p ~/.diffbot
-printf 'DIFFBOT_API_TOKEN=%s\n' '<TOKEN>' > ~/.diffbot/credentials
-chmod 600 ~/.diffbot/credentials
-```
-
-With either in place, resolve the token and pass it to the client:
-
-```python
-from diffbot import Diffbot, resolve_token
-
-db = Diffbot(token=resolve_token())  # from env var or ~/.diffbot/credentials
-data = db.extract("https://www.example.com")
-```
-
-### Extract structured content
-```python
-from diffbot import Diffbot
-
-db = Diffbot(token="YOUR_TOKEN")
-data = db.extract("https://www.example.com")
-```
-
-### Ask Diffbot LLM
-```python
-from diffbot import Diffbot
-
-db = Diffbot(token="YOUR_TOKEN")
-for chunk in db.ask([{"role": "user", "content": "What's the capital of France?"}]):
-    print(chunk, end="")
-```
-
-### Crawl a site for structured content
-```python
-from diffbot import Diffbot
-
-db = Diffbot(token="YOUR_TOKEN")
-for event in db.crawl("https://www.example.com", hops=1):
-    print(event)
-```
-
-### Query the Knowledge Graph
-```python
-from diffbot import Diffbot
-
-db = Diffbot(token="YOUR_TOKEN")
-results = db.dql('type:Organization name:"Diffbot"')
-```
-
-### Web Search
-```python
-from diffbot import Diffbot
-
-db = Diffbot(token="YOUR_TOKEN")
-results = db.web_search("diffbot knowledge graph")
-for r in results["search_results"]:
-    print(r["score"], r["title"], r["pageUrl"])
-    print(r["content"])
-```
-
-### Entities (NLP)
-```python
-from diffbot import Diffbot
-
-db = Diffbot(token="YOUR_TOKEN")
-result = db.entities("Apple CEO Tim Cook announced record quarterly earnings.")
-for entity in result["entities"]:
-    print(entity["name"], entity.get("type"), entity.get("id"))
-print("sentiment:", result.get("sentiment"))
-```
-
-## Async Usage
-
-### Extract structured content
-```python
-import asyncio
-from diffbot import DiffbotAsync
-
-async def main():
-    async with DiffbotAsync(token="YOUR_TOKEN") as db:
-        data = await db.extract("https://www.example.com")
-        print(data)
-
-asyncio.run(main())
-```
-
-### Ask Diffbot LLM
-```python
-import asyncio
-from diffbot import DiffbotAsync
-
-async def main():
-    async with DiffbotAsync(token="YOUR_TOKEN") as db:
-        async for chunk in db.ask([{"role": "user", "content": "What's the capital of France?"}]):
-            print(chunk, end="")
-
-asyncio.run(main())
-```
-
-### Crawl a site for structured content
-```python
-import asyncio
-from diffbot import DiffbotAsync
-
-async def main():
-    async with DiffbotAsync(token="YOUR_TOKEN") as db:
-        async for event in db.crawl("https://www.example.com", hops=1):
-            print(event)
-
-asyncio.run(main())
-```
-
-### Query the Knowledge Graph
-```python
-import asyncio
-from diffbot import DiffbotAsync
-
-async def main():
-    async with DiffbotAsync(token="YOUR_TOKEN") as db:
-        results = await db.dql('type:Organization name:"Diffbot"')
-        print(results)
-
-asyncio.run(main())
-```
-
-### Web Search
-```python
-import asyncio
-from diffbot import DiffbotAsync
-
-async def main():
-    async with DiffbotAsync(token="YOUR_TOKEN") as db:
-        results = await db.web_search("diffbot knowledge graph")
-        for r in results["search_results"]:
-            print(r["score"], r["title"], r["pageUrl"])
-            print(r["content"])
-
-asyncio.run(main())
-```
-
-### Entities (NLP)
-```python
-import asyncio
-from diffbot import DiffbotAsync
-
-async def main():
-    async with DiffbotAsync(token="YOUR_TOKEN") as db:
-        result = await db.entities("Apple CEO Tim Cook announced record quarterly earnings.")
-        for entity in result["entities"]:
-            print(entity["name"], entity.get("type"), entity.get("id"))
-        print("sentiment:", result.get("sentiment"))
-
-asyncio.run(main())
-```
-
-## CLI
-
-This library also includes a CLI exposed as the `db` command.
-
-To make `db` available from anywhere, install it as an isolated tool with [uv](https://docs.astral.sh/uv/):
-
-```bash
-uv tool install .
-```
-
-This drops a `db` executable into `~/.local/bin` (ensure it is on your `PATH`). Use `--force` to reinstall or upgrade after changes, or `--editable` to have source edits take effect immediately. Alternatively, a plain `pip install .` (or `pip install -e .`) also installs the `db` entry point into the active environment.
-
-```bash
-export DIFFBOT_API_TOKEN=your-token-here
-
-db extract https://www.example.com
-db ask "What's the capital of France?"
-db crawl https://www.example.com --hops 1
-db crawl-list-jobs
-db crawl-delete-job crawl-1234567890
-db web-search "diffbot knowledge graph"
-db web-search "diffbot knowledge graph" -n 5 -f json
-db entities "Apple CEO Tim Cook announced record quarterly earnings."
-db entities "Apple CEO Tim Cook announced record quarterly earnings." -f dql
-```
-
-## Tests
-
-Run the mock test suite:
-```bash
-python -m pytest
-```
-
-Run live integration tests against the real API (requires a valid token).
-The token is resolved the same way as everywhere else — the `DIFFBOT_API_TOKEN`
-environment variable or `~/.diffbot/credentials`:
-```bash
-DIFFBOT_API_TOKEN=your_token python -m pytest -m live
-```