langchain-nestdaddy 0.1.0__tar.gz

langchain_nestdaddy-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,32 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest tests/unit_tests --disable-socket --allow-unix-socket -q
+
+  integration:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[test]"
+      - run: pytest -m integration tests/integration_tests -q
+        env:
+          NESTDADDY_API_KEY: ${{ secrets.NESTDADDY_API_KEY }}

langchain_nestdaddy-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env

langchain_nestdaddy-0.1.0/LICENSE

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

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: langchain-nestdaddy
+Version: 0.1.0
+Summary: LangChain integration for NestDaddy: give your AI today's internet. Live web search, real-time news and page reading.
+Project-URL: Homepage, https://nestdaddy.com/mcp
+Project-URL: Documentation, https://github.com/nestdaddy/langchain-nestdaddy#readme
+Project-URL: Source, https://github.com/nestdaddy/langchain-nestdaddy
+Project-URL: API reference, https://nestdaddy.com/apis
+Author-email: NestDaddy <hello@nestdaddy.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,langchain,nestdaddy,news,rag,search,web search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0.0,>=0.25.0
+Requires-Dist: langchain-core<2.0.0,>=0.3.15
+Requires-Dist: pydantic<3.0,>=2.7
+Provides-Extra: test
+Requires-Dist: langchain-tests>=0.3.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-socket>=0.7; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-nestdaddy
+
+**Give your AI today's internet.** Live web search, real-time breaking news from around the world and full page
+reading for LangChain agents and RAG pipelines, from [NestDaddy](https://nestdaddy.com)'s own index.
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-nestdaddy)](https://pypi.org/project/langchain-nestdaddy/)
+[![tests](https://github.com/nestdaddy/langchain-nestdaddy/actions/workflows/tests.yml/badge.svg)](https://github.com/nestdaddy/langchain-nestdaddy/actions/workflows/tests.yml)
+
+```bash
+pip install -U langchain-nestdaddy
+export NESTDADDY_API_KEY="your-key"   # free trial key: https://nestdaddy.com/mcp
+```
+
+| Class | What it does |
+|---|---|
+| `NestDaddySearch` | Web search on NestDaddy's own index (title, url, snippet, domain) |
+| `NestDaddyNewsSearch` | Real-time news by key words, optional country and time window |
+| `NestDaddyReadPage` | Clean main text of any page or article, no menus or ads |
+| `NestDaddyNewsRetriever` | News as LangChain `Document`s for RAG, optionally with the full article text |
+
+## Give an agent live search and news
+
+```python
+from langchain.agents import create_agent
+from langchain_nestdaddy import NestDaddyNewsSearch, NestDaddyReadPage, NestDaddySearch
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=[NestDaddySearch(max_results=5), NestDaddyNewsSearch(days=7), NestDaddyReadPage()],
+    system_prompt="Use news search for anything recent, web search for everything else. "
+                  "Read a page in full before you explain its details.",
+)
+
+result = agent.invoke({"messages": [{"role": "user", "content": "What did the Fed decide this week?"}]})
+print(result["messages"][-1].content)
+```
+
+Any chat model that supports tool calling works the same way.
+
+## Use the tools directly
+
+```python
+from langchain_nestdaddy import NestDaddyNewsSearch, NestDaddySearch, NestDaddyReadPage
+
+NestDaddySearch(max_results=3).invoke({"query": "model context protocol"})
+# {'query': 'model context protocol', 'count': 3, 'results': [{'title': ..., 'url': ..., 'snippet': ...}]}
+
+NestDaddyNewsSearch().invoke({"query": "interest rates", "country": "US", "days": 7})
+# {'query': 'interest rates', 'count': 10, 'total': ..., 'results': [{'title': ..., 'source_domain': ...,
+#   'published_timestamp': ..., 'summary': ...}]}
+
+NestDaddyReadPage(max_chars=8000).invoke({"url": "https://example.com/some-article"})
+# {'title': ..., 'final_url': ..., 'text': ...}
+```
+
+Local news works in the local language: `NestDaddyNewsSearch().invoke({"query": "banjir Jakarta", "country": "ID"})`.
+
+## RAG over today's news
+
+```python
+from langchain_nestdaddy import NestDaddyNewsRetriever
+
+retriever = NestDaddyNewsRetriever(k=5, days=3, full_text=True)
+docs = retriever.invoke("chip export rules")
+
+for d in docs:
+    print(d.metadata["title"], d.metadata["url"], d.metadata["published_timestamp"])
+    print(d.page_content[:300])
+```
+
+With `full_text=True` each article is read in full (one extra API call per article). If an article cannot be
+read, its summary is kept so you still get `k` documents.
+
+## Async
+
+Every tool and the retriever support `ainvoke`; the retriever reads full articles in parallel.
+
+```python
+docs = await NestDaddyNewsRetriever(k=5, full_text=True).ainvoke("AI regulation")
+```
+
+## Errors
+
+API errors raise `NestDaddyAPIError` with the HTTP status and a hint (a bad key points to the dashboard, a plan
+limit to the plans page). Your key is stored as a `SecretStr` and never printed.
+
+## Prefer MCP?
+
+The same tools are available as a remote MCP server for Claude, Cursor, VS Code and n8n:
+`https://mcp.nestdaddy.com/mcp`. Setup: [nestdaddy.com/mcp](https://nestdaddy.com/mcp).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest tests/unit_tests --disable-socket --allow-unix-socket   # offline
+NESTDADDY_API_KEY=... pytest -m integration tests/integration_tests
+```
+
+MIT licensed.

langchain_nestdaddy-0.1.0/README.md

@@ -0,0 +1,100 @@
+# langchain-nestdaddy
+
+**Give your AI today's internet.** Live web search, real-time breaking news from around the world and full page
+reading for LangChain agents and RAG pipelines, from [NestDaddy](https://nestdaddy.com)'s own index.
+
+[![PyPI](https://img.shields.io/pypi/v/langchain-nestdaddy)](https://pypi.org/project/langchain-nestdaddy/)
+[![tests](https://github.com/nestdaddy/langchain-nestdaddy/actions/workflows/tests.yml/badge.svg)](https://github.com/nestdaddy/langchain-nestdaddy/actions/workflows/tests.yml)
+
+```bash
+pip install -U langchain-nestdaddy
+export NESTDADDY_API_KEY="your-key"   # free trial key: https://nestdaddy.com/mcp
+```
+
+| Class | What it does |
+|---|---|
+| `NestDaddySearch` | Web search on NestDaddy's own index (title, url, snippet, domain) |
+| `NestDaddyNewsSearch` | Real-time news by key words, optional country and time window |
+| `NestDaddyReadPage` | Clean main text of any page or article, no menus or ads |
+| `NestDaddyNewsRetriever` | News as LangChain `Document`s for RAG, optionally with the full article text |
+
+## Give an agent live search and news
+
+```python
+from langchain.agents import create_agent
+from langchain_nestdaddy import NestDaddyNewsSearch, NestDaddyReadPage, NestDaddySearch
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=[NestDaddySearch(max_results=5), NestDaddyNewsSearch(days=7), NestDaddyReadPage()],
+    system_prompt="Use news search for anything recent, web search for everything else. "
+                  "Read a page in full before you explain its details.",
+)
+
+result = agent.invoke({"messages": [{"role": "user", "content": "What did the Fed decide this week?"}]})
+print(result["messages"][-1].content)
+```
+
+Any chat model that supports tool calling works the same way.
+
+## Use the tools directly
+
+```python
+from langchain_nestdaddy import NestDaddyNewsSearch, NestDaddySearch, NestDaddyReadPage
+
+NestDaddySearch(max_results=3).invoke({"query": "model context protocol"})
+# {'query': 'model context protocol', 'count': 3, 'results': [{'title': ..., 'url': ..., 'snippet': ...}]}
+
+NestDaddyNewsSearch().invoke({"query": "interest rates", "country": "US", "days": 7})
+# {'query': 'interest rates', 'count': 10, 'total': ..., 'results': [{'title': ..., 'source_domain': ...,
+#   'published_timestamp': ..., 'summary': ...}]}
+
+NestDaddyReadPage(max_chars=8000).invoke({"url": "https://example.com/some-article"})
+# {'title': ..., 'final_url': ..., 'text': ...}
+```
+
+Local news works in the local language: `NestDaddyNewsSearch().invoke({"query": "banjir Jakarta", "country": "ID"})`.
+
+## RAG over today's news
+
+```python
+from langchain_nestdaddy import NestDaddyNewsRetriever
+
+retriever = NestDaddyNewsRetriever(k=5, days=3, full_text=True)
+docs = retriever.invoke("chip export rules")
+
+for d in docs:
+    print(d.metadata["title"], d.metadata["url"], d.metadata["published_timestamp"])
+    print(d.page_content[:300])
+```
+
+With `full_text=True` each article is read in full (one extra API call per article). If an article cannot be
+read, its summary is kept so you still get `k` documents.
+
+## Async
+
+Every tool and the retriever support `ainvoke`; the retriever reads full articles in parallel.
+
+```python
+docs = await NestDaddyNewsRetriever(k=5, full_text=True).ainvoke("AI regulation")
+```
+
+## Errors
+
+API errors raise `NestDaddyAPIError` with the HTTP status and a hint (a bad key points to the dashboard, a plan
+limit to the plans page). Your key is stored as a `SecretStr` and never printed.
+
+## Prefer MCP?
+
+The same tools are available as a remote MCP server for Claude, Cursor, VS Code and n8n:
+`https://mcp.nestdaddy.com/mcp`. Setup: [nestdaddy.com/mcp](https://nestdaddy.com/mcp).
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest tests/unit_tests --disable-socket --allow-unix-socket   # offline
+NESTDADDY_API_KEY=... pytest -m integration tests/integration_tests
+```
+
+MIT licensed.

langchain_nestdaddy-0.1.0/langchain_nestdaddy/__init__.py

@@ -0,0 +1,26 @@
+"""LangChain integration for NestDaddy: give your AI today's internet.
+
+Live web search, real-time breaking news from around the world and full page reading, from NestDaddy's own
+index. Get a key at https://nestdaddy.com/mcp and set ``NESTDADDY_API_KEY``.
+"""
+
+from importlib import metadata
+
+from langchain_nestdaddy._client import NestDaddyAPIError, NestDaddyAPIWrapper
+from langchain_nestdaddy.retrievers import NestDaddyNewsRetriever
+from langchain_nestdaddy.tools import NestDaddyNewsSearch, NestDaddyReadPage, NestDaddySearch
+
+try:
+    __version__ = metadata.version(__package__ or "langchain_nestdaddy")
+except metadata.PackageNotFoundError:
+    __version__ = ""
+
+__all__ = [
+    "NestDaddyAPIError",
+    "NestDaddyAPIWrapper",
+    "NestDaddyNewsRetriever",
+    "NestDaddyNewsSearch",
+    "NestDaddyReadPage",
+    "NestDaddySearch",
+    "__version__",
+]

langchain_nestdaddy-0.1.0/langchain_nestdaddy/_client.py

@@ -0,0 +1,89 @@
+"""Small HTTP client for the NestDaddy REST API, shared by the tools and the retriever."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+DEFAULT_BASE_URL = "https://nestdaddy.com"
+USER_AGENT = "langchain-nestdaddy/0.1.0"
+
+
+class NestDaddyAPIError(RuntimeError):
+    """Raised when the NestDaddy API answers with an error (bad key, plan limit, bad input)."""
+
+    def __init__(self, status_code: int, error: str, message: str) -> None:
+        self.status_code = status_code
+        self.error = error
+        hint = ""
+        if status_code in (401, 403):
+            hint = " Check your key at https://nestdaddy.com/dashboard"
+        elif status_code == 429:
+            hint = " You reached your plan's limit: https://nestdaddy.com/mcp"
+        super().__init__(f"NestDaddy API error {status_code} ({error}): {message}.{hint}")
+
+
+class NestDaddyAPIWrapper(BaseModel):
+    """Calls the NestDaddy API with your key.
+
+    The key is read from ``api_key`` or the ``NESTDADDY_API_KEY`` environment variable.
+    Get one at https://nestdaddy.com/mcp (free trial).
+    """
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    api_key: Optional[SecretStr] = Field(default=None)
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = 30.0
+    transport: Optional[Any] = Field(default=None, exclude=True, repr=False)
+    """Optional httpx transport (used by tests). Leave unset in normal use."""
+
+    @model_validator(mode="after")
+    def _resolve_key(self) -> "NestDaddyAPIWrapper":
+        if self.api_key is None:
+            env = os.environ.get("NESTDADDY_API_KEY", "").strip()
+            if env:
+                self.api_key = SecretStr(env)
+        if self.api_key is None or not self.api_key.get_secret_value():
+            raise ValueError(
+                "NestDaddy API key not found. Pass api_key=... or set NESTDADDY_API_KEY. "
+                "Get a key at https://nestdaddy.com/mcp"
+            )
+        return self
+
+    # ------------------------------------------------------------------ internals
+    def _headers(self) -> Dict[str, str]:
+        assert self.api_key is not None
+        return {
+            "X-API-Key": self.api_key.get_secret_value(),
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+
+    @staticmethod
+    def _clean(params: Dict[str, Any]) -> Dict[str, Any]:
+        return {k: v for k, v in params.items() if v not in (None, "")}
+
+    @staticmethod
+    def _parse(response: httpx.Response) -> Dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError:
+            raise NestDaddyAPIError(response.status_code, "invalid_response",
+                                    "the API did not return JSON") from None
+        if response.status_code != 200:
+            raise NestDaddyAPIError(response.status_code, str(data.get("error") or "error"),
+                                    str(data.get("message") or data.get("error") or response.reason_phrase))
+        return data
+
+    def get(self, path: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        with httpx.Client(base_url=self.base_url, timeout=self.timeout, transport=self.transport) as client:
+            return self._parse(client.get(path, params=self._clean(params), headers=self._headers()))
+
+    async def aget(self, path: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        async with httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout,
+                                     transport=self.transport) as client:
+            return self._parse(await client.get(path, params=self._clean(params), headers=self._headers()))

langchain_nestdaddy-0.1.0/langchain_nestdaddy/retrievers.py

@@ -0,0 +1,108 @@
+"""NestDaddy news retriever: real-time news as LangChain Documents, optionally with the full article text."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, List, Optional
+
+from langchain_core.callbacks import AsyncCallbackManagerForRetrieverRun, CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import Field, model_validator
+
+from langchain_nestdaddy._client import NestDaddyAPIError, NestDaddyAPIWrapper
+
+META_FIELDS = ("title", "url", "source_domain", "published_timestamp", "country")
+
+
+class NestDaddyNewsRetriever(BaseRetriever):
+    """Retrieve real-time news from around the world for a query.
+
+    Each article becomes a ``Document``: the summary (or, with ``full_text=True``, the article text) is the
+    ``page_content``; title, url, source, publish time and country are in ``metadata``.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-nestdaddy
+            export NESTDADDY_API_KEY="your-key"
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_nestdaddy import NestDaddyNewsRetriever
+
+            retriever = NestDaddyNewsRetriever(k=5, days=7, full_text=True)
+
+    Usage:
+        .. code-block:: python
+
+            docs = retriever.invoke("chip export rules")
+    """
+
+    api_wrapper: NestDaddyAPIWrapper
+    k: int = Field(default=5, ge=1, le=50)
+    """How many articles to return."""
+    days: int = Field(default=30, ge=1, le=120)
+    """Only news from the last N days."""
+    country: Optional[str] = None
+    """Optional two-letter country code, e.g. US, GB, IN, SG, ID."""
+    full_text: bool = False
+    """Read each article in full (one extra API call per article) instead of using its summary."""
+    max_chars: int = Field(default=6000, ge=500, le=30000)
+    """Characters kept from each full article."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _build_wrapper(cls, values: Any) -> Any:
+        if isinstance(values, dict) and "api_wrapper" not in values:
+            kwargs = {k: values.pop(k) for k in ("api_key", "base_url") if k in values}
+            values["api_wrapper"] = NestDaddyAPIWrapper(**kwargs)
+        return values
+
+    # ------------------------------------------------------------------ helpers
+    def _params(self, query: str) -> Dict[str, Any]:
+        return {"q": query, "days": self.days, "limit": self.k,
+                "country": self.country.upper() if self.country else None}
+
+    @staticmethod
+    def _to_doc(item: Dict[str, Any], text: Optional[str] = None) -> Document:
+        content = text or item.get("summary") or item.get("description") or item.get("title") or ""
+        meta = {f: item[f] for f in META_FIELDS if item.get(f) not in (None, "")}
+        meta["full_text"] = bool(text)
+        return Document(page_content=content, metadata=meta)
+
+    def _items(self, data: Dict[str, Any]) -> List[Dict[str, Any]]:
+        return [r for r in data.get("results") or [] if isinstance(r, dict) and r.get("url")][: self.k]
+
+    def _read(self, url: str) -> Optional[str]:
+        try:
+            page = self.api_wrapper.get("/api/v1/extract", {"url": url, "max_chars": self.max_chars})
+        except NestDaddyAPIError:
+            return None          # keep the summary when one article cannot be read
+        text = page.get("text") or ""
+        return text if len(text) > 200 else None
+
+    async def _aread(self, url: str) -> Optional[str]:
+        try:
+            page = await self.api_wrapper.aget("/api/v1/extract", {"url": url, "max_chars": self.max_chars})
+        except NestDaddyAPIError:
+            return None
+        text = page.get("text") or ""
+        return text if len(text) > 200 else None
+
+    # ------------------------------------------------------------------ BaseRetriever
+    def _get_relevant_documents(self, query: str, *,
+                                run_manager: CallbackManagerForRetrieverRun) -> List[Document]:
+        items = self._items(self.api_wrapper.get("/api/v1/news/search", self._params(query)))
+        texts = [self._read(i["url"]) if self.full_text else None for i in items]
+        return [self._to_doc(i, t) for i, t in zip(items, texts)]
+
+    async def _aget_relevant_documents(self, query: str, *,
+                                       run_manager: AsyncCallbackManagerForRetrieverRun) -> List[Document]:
+        items = self._items(await self.api_wrapper.aget("/api/v1/news/search", self._params(query)))
+        if self.full_text:
+            texts = await asyncio.gather(*(self._aread(i["url"]) for i in items))
+        else:
+            texts = [None] * len(items)
+        return [self._to_doc(i, t) for i, t in zip(items, texts)]

langchain_nestdaddy-0.1.0/langchain_nestdaddy/tools.py

@@ -0,0 +1,221 @@
+"""NestDaddy tools for LangChain agents: web search, real-time news search and full page reading."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple, Type
+
+from langchain_core.callbacks import AsyncCallbackManagerForToolRun, CallbackManagerForToolRun
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, model_validator
+
+from langchain_nestdaddy._client import NestDaddyAPIWrapper
+
+SNIPPET_CHARS = 400
+NEWS_FIELDS = ("title", "url", "source_domain", "published_timestamp", "summary", "description", "country")
+WEB_FIELDS = ("title", "url", "snippet", "domain", "type")
+
+
+def _pick(item: Dict[str, Any], fields: Tuple[str, ...]) -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    for f in fields:
+        v = item.get(f)
+        if v in (None, "", [], {}):
+            continue
+        if isinstance(v, str) and len(v) > SNIPPET_CHARS:
+            v = v[:SNIPPET_CHARS].rstrip() + "..."
+        out[f] = v
+    return out
+
+
+class _NestDaddyTool(BaseTool):
+    """Shared setup: every tool owns an API wrapper, built from ``api_key`` or ``NESTDADDY_API_KEY``."""
+
+    api_wrapper: NestDaddyAPIWrapper
+
+    @model_validator(mode="before")
+    @classmethod
+    def _build_wrapper(cls, values: Any) -> Any:
+        if isinstance(values, dict) and "api_wrapper" not in values:
+            kwargs = {k: values.pop(k) for k in ("api_key", "base_url") if k in values}
+            values["api_wrapper"] = NestDaddyAPIWrapper(**kwargs)
+        return values
+
+
+# ---------------------------------------------------------------------------------------------- web search
+class NestDaddySearchInput(BaseModel):
+    query: str = Field(description="Short key words to search the web for, not a whole sentence.")
+    max_results: Optional[int] = Field(default=None, ge=1, le=50,
+                                       description="How many results to return (1-50).")
+
+
+class NestDaddySearch(_NestDaddyTool):
+    """Search the web with NestDaddy's own index.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-nestdaddy
+            export NESTDADDY_API_KEY="your-key"
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_nestdaddy import NestDaddySearch
+
+            tool = NestDaddySearch(max_results=5)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"query": "model context protocol"})
+    """
+
+    name: str = "nestdaddy_search"
+    description: str = (
+        "Search the web with NestDaddy's own index. Returns the title, url, snippet and domain of each page. "
+        "For time-sensitive questions fresh news articles are mixed in. Use short key words. "
+        "Call nestdaddy_read_page on a url when the snippet is not enough."
+    )
+    args_schema: Type[BaseModel] = NestDaddySearchInput
+    max_results: int = 10
+
+    def _params(self, query: str, max_results: Optional[int]) -> Dict[str, Any]:
+        return {"q": query, "limit": max_results or self.max_results}
+
+    @staticmethod
+    def _format(data: Dict[str, Any]) -> Dict[str, Any]:
+        results = [_pick(r, WEB_FIELDS) for r in data.get("results") or [] if isinstance(r, dict)]
+        return {"query": data.get("query"), "count": len(results), "results": results}
+
+    def _run(self, query: str, max_results: Optional[int] = None,
+             run_manager: Optional[CallbackManagerForToolRun] = None) -> Dict[str, Any]:
+        return self._format(self.api_wrapper.get("/api/v1/search", self._params(query, max_results)))
+
+    async def _arun(self, query: str, max_results: Optional[int] = None,
+                    run_manager: Optional[AsyncCallbackManagerForToolRun] = None) -> Dict[str, Any]:
+        return self._format(await self.api_wrapper.aget("/api/v1/search", self._params(query, max_results)))
+
+
+# ---------------------------------------------------------------------------------------------- news search
+class NestDaddyNewsSearchInput(BaseModel):
+    query: str = Field(description="Key words a headline would use, in the local language for local news.")
+    country: Optional[str] = Field(default=None, min_length=2, max_length=2,
+                                   description="Optional two-letter country code, e.g. US, GB, IN, SG, ID.")
+    days: Optional[int] = Field(default=None, ge=1, le=120, description="Only news from the last N days (1-120).")
+    max_results: Optional[int] = Field(default=None, ge=1, le=50,
+                                       description="How many articles to return (1-50).")
+
+
+class NestDaddyNewsSearch(_NestDaddyTool):
+    """Search real-time news from around the world by key words, newest and best match first.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-nestdaddy
+            export NESTDADDY_API_KEY="your-key"
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_nestdaddy import NestDaddyNewsSearch
+
+            tool = NestDaddyNewsSearch(days=7, max_results=5)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"query": "interest rates", "country": "US"})
+    """
+
+    name: str = "nestdaddy_news_search"
+    description: str = (
+        "Search real-time breaking news from around the world by key words: title, url, source, publish time and "
+        "summary of each article, newest and best match first. The best tool for questions about recent events, "
+        "people, companies and places. Optional country (two-letter code) and days (1-120)."
+    )
+    args_schema: Type[BaseModel] = NestDaddyNewsSearchInput
+    max_results: int = 10
+    days: int = 30
+
+    def _params(self, query: str, country: Optional[str], days: Optional[int],
+                max_results: Optional[int]) -> Dict[str, Any]:
+        return {"q": query, "country": country.upper() if country else None, "days": days or self.days,
+                "limit": max_results or self.max_results}
+
+    @staticmethod
+    def _format(data: Dict[str, Any]) -> Dict[str, Any]:
+        results = [_pick(r, NEWS_FIELDS) for r in data.get("results") or [] if isinstance(r, dict)]
+        return {"query": data.get("query"), "count": len(results), "total": data.get("total"), "results": results}
+
+    def _run(self, query: str, country: Optional[str] = None, days: Optional[int] = None,
+             max_results: Optional[int] = None,
+             run_manager: Optional[CallbackManagerForToolRun] = None) -> Dict[str, Any]:
+        return self._format(self.api_wrapper.get("/api/v1/news/search",
+                                                 self._params(query, country, days, max_results)))
+
+    async def _arun(self, query: str, country: Optional[str] = None, days: Optional[int] = None,
+                    max_results: Optional[int] = None,
+                    run_manager: Optional[AsyncCallbackManagerForToolRun] = None) -> Dict[str, Any]:
+        return self._format(await self.api_wrapper.aget("/api/v1/news/search",
+                                                        self._params(query, country, days, max_results)))
+
+
+# ---------------------------------------------------------------------------------------------- read page
+class NestDaddyReadPageInput(BaseModel):
+    url: str = Field(description="The full http(s) url of the page or article to read.")
+    max_chars: Optional[int] = Field(default=None, ge=500, le=30000,
+                                     description="Maximum characters of text to return (500-30000).")
+
+
+class NestDaddyReadPage(_NestDaddyTool):
+    """Read the clean main text of any web page or news article (no menus, no ads).
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-nestdaddy
+            export NESTDADDY_API_KEY="your-key"
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_nestdaddy import NestDaddyReadPage
+
+            tool = NestDaddyReadPage(max_chars=8000)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"url": "https://en.wikipedia.org/wiki/Model_Context_Protocol"})
+    """
+
+    name: str = "nestdaddy_read_page"
+    description: str = (
+        "Read the full readable text of one web page or news article: title, author, date and main text, "
+        "without menus or ads. Use it after a search when you need the details behind a result."
+    )
+    args_schema: Type[BaseModel] = NestDaddyReadPageInput
+    max_chars: int = 8000
+
+    @staticmethod
+    def _format(data: Dict[str, Any]) -> Dict[str, Any]:
+        keep = ("title", "final_url", "author", "published", "text", "truncated", "length")
+        return {k: data[k] for k in keep if data.get(k) not in (None, "")}
+
+    def _run(self, url: str, max_chars: Optional[int] = None,
+             run_manager: Optional[CallbackManagerForToolRun] = None) -> Dict[str, Any]:
+        return self._format(self.api_wrapper.get("/api/v1/extract",
+                                                 {"url": url, "max_chars": max_chars or self.max_chars}))
+
+    async def _arun(self, url: str, max_chars: Optional[int] = None,
+                    run_manager: Optional[AsyncCallbackManagerForToolRun] = None) -> Dict[str, Any]:
+        return self._format(await self.api_wrapper.aget("/api/v1/extract",
+                                                        {"url": url, "max_chars": max_chars or self.max_chars}))
+
+
+__all__: List[str] = [
+    "NestDaddySearch", "NestDaddySearchInput",
+    "NestDaddyNewsSearch", "NestDaddyNewsSearchInput",
+    "NestDaddyReadPage", "NestDaddyReadPageInput",
+]

langchain_nestdaddy-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-nestdaddy"
+version = "0.1.0"
+description = "LangChain integration for NestDaddy: give your AI today's internet. Live web search, real-time news and page reading."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "NestDaddy", email = "hello@nestdaddy.com" }]
+keywords = ["langchain", "search", "news", "web search", "rag", "agents", "nestdaddy"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "langchain-core>=0.3.15,<2.0.0",
+    "httpx>=0.25.0,<1.0.0",
+    "pydantic>=2.7,<3.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-socket>=0.7",
+    "langchain-tests>=0.3.0",
+]
+
+[project.urls]
+Homepage = "https://nestdaddy.com/mcp"
+Documentation = "https://github.com/nestdaddy/langchain-nestdaddy#readme"
+Source = "https://github.com/nestdaddy/langchain-nestdaddy"
+"API reference" = "https://nestdaddy.com/apis"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_nestdaddy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["integration: calls the live NestDaddy API (needs NESTDADDY_API_KEY)"]
+addopts = "-m 'not integration'"

langchain_nestdaddy-0.1.0/tests/integration_tests/test_live.py

@@ -0,0 +1,32 @@
+"""Live tests against the real NestDaddy API. Run with: NESTDADDY_API_KEY=... pytest -m integration"""
+
+import os
+
+import pytest
+
+from langchain_nestdaddy import NestDaddyNewsRetriever, NestDaddyNewsSearch, NestDaddyReadPage, NestDaddySearch
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(not os.environ.get("NESTDADDY_API_KEY"), reason="NESTDADDY_API_KEY not set"),
+]
+
+
+def test_live_web_search() -> None:
+    out = NestDaddySearch(max_results=3).invoke({"query": "model context protocol"})
+    assert out["count"] >= 1 and out["results"][0]["url"].startswith("http")
+
+
+def test_live_news_search() -> None:
+    out = NestDaddyNewsSearch(max_results=3, days=7).invoke({"query": "AI"})
+    assert out["count"] >= 1 and out["results"][0]["title"]
+
+
+def test_live_read_page() -> None:
+    out = NestDaddyReadPage(max_chars=1000).invoke({"url": "https://en.wikipedia.org/wiki/Web_search_engine"})
+    assert len(out.get("text", "")) > 200
+
+
+def test_live_retriever() -> None:
+    docs = NestDaddyNewsRetriever(k=2, days=7).invoke("AI")
+    assert docs and docs[0].metadata["url"].startswith("http")

langchain_nestdaddy-0.1.0/tests/unit_tests/test_behaviour.py

@@ -0,0 +1,138 @@
+"""Behaviour tests with a fake NestDaddy API (httpx.MockTransport), sync and async."""
+
+import json
+from typing import Any, Dict, List
+
+import httpx
+import pytest
+
+from langchain_nestdaddy import (
+    NestDaddyAPIError,
+    NestDaddyAPIWrapper,
+    NestDaddyNewsRetriever,
+    NestDaddyNewsSearch,
+    NestDaddyReadPage,
+    NestDaddySearch,
+)
+
+LONG = "Full article text. " * 40
+
+
+def fake_api(seen: List[httpx.Request]) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        if request.headers.get("X-API-Key") != "test-key":
+            return httpx.Response(401, json={"error": "Invalid API key", "message": "The key is not valid"})
+        path, q = request.url.path, dict(request.url.params)
+        if path == "/api/v1/search":
+            return httpx.Response(200, json={"query": q["q"], "results": [
+                {"title": "MCP spec", "url": "https://modelcontextprotocol.io", "snippet": "x" * 900,
+                 "domain": "modelcontextprotocol.io", "type": "web", "internal_score": 9}]})
+        if path == "/api/v1/news/search":
+            return httpx.Response(200, json={"query": q["q"], "total": 2, "results": [
+                {"title": "Fed holds rates", "url": "https://news.example/a", "source_domain": "news.example",
+                 "published_timestamp": "2026-11-13T10:00:00Z", "summary": "The Fed held rates.", "country": "US"},
+                {"title": "Markets rise", "url": "https://news.example/b", "source_domain": "news.example",
+                 "published_timestamp": "2026-11-13T09:00:00Z", "summary": "Stocks rose.", "country": "US"}]})
+        if path == "/api/v1/extract":
+            if q["url"].endswith("/b"):
+                return httpx.Response(422, json={"error": "Unreadable", "message": "No article text"})
+            return httpx.Response(200, json={"title": "Fed holds rates", "final_url": q["url"],
+                                             "text": LONG, "length": len(LONG), "truncated": False})
+        return httpx.Response(404, json={"error": "Not found", "message": path})
+    return httpx.MockTransport(handler)
+
+
+def wrapper(seen: List[httpx.Request], key: str = "test-key") -> NestDaddyAPIWrapper:
+    return NestDaddyAPIWrapper(api_key=key, transport=fake_api(seen))
+
+
+def test_missing_key_is_a_clear_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("NESTDADDY_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="NESTDADDY_API_KEY"):
+        NestDaddySearch()
+
+
+def test_key_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("NESTDADDY_API_KEY", "env-key")
+    assert NestDaddySearch().api_wrapper.api_key.get_secret_value() == "env-key"
+
+
+def test_key_is_not_printed() -> None:
+    w = NestDaddyAPIWrapper(api_key="secret-value")
+    assert "secret-value" not in repr(w) and "secret-value" not in str(w.model_dump())
+
+
+def test_web_search_trims_and_picks_fields() -> None:
+    seen: List[httpx.Request] = []
+    out = NestDaddySearch(api_wrapper=wrapper(seen), max_results=3).invoke({"query": "mcp"})
+    assert seen[0].url.params["limit"] == "3" and seen[0].url.params["q"] == "mcp"
+    r = out["results"][0]
+    assert set(r) == {"title", "url", "snippet", "domain", "type"}   # internal fields dropped
+    assert len(r["snippet"]) <= 403
+
+
+def test_news_search_params_and_output() -> None:
+    seen: List[httpx.Request] = []
+    out = NestDaddyNewsSearch(api_wrapper=wrapper(seen), days=7).invoke(
+        {"query": "fed", "country": "us", "max_results": 2})
+    p = seen[0].url.params
+    assert (p["country"], p["days"], p["limit"]) == ("US", "7", "2")
+    assert out["count"] == 2 and out["total"] == 2 and out["results"][0]["source_domain"] == "news.example"
+
+
+def test_optional_params_are_not_sent() -> None:
+    seen: List[httpx.Request] = []
+    NestDaddyNewsSearch(api_wrapper=wrapper(seen)).invoke({"query": "fed"})
+    assert "country" not in seen[0].url.params
+
+
+def test_read_page() -> None:
+    seen: List[httpx.Request] = []
+    out = NestDaddyReadPage(api_wrapper=wrapper(seen), max_chars=2000).invoke({"url": "https://news.example/a"})
+    assert seen[0].url.params["max_chars"] == "2000" and out["text"].startswith("Full article text")
+
+
+def test_api_error_is_raised_with_hint() -> None:
+    seen: List[httpx.Request] = []
+    with pytest.raises(NestDaddyAPIError, match="dashboard") as e:
+        wrapper(seen, key="wrong").get("/api/v1/search", {"q": "x"})
+    assert e.value.status_code == 401
+
+
+def test_tool_as_agent_tool_message() -> None:
+    """Tools called by an agent return a ToolMessage whose content is the JSON result."""
+    seen: List[httpx.Request] = []
+    tool = NestDaddyNewsSearch(api_wrapper=wrapper(seen))
+    msg = tool.invoke({"type": "tool_call", "id": "call_1", "name": tool.name, "args": {"query": "fed"}})
+    assert msg.tool_call_id == "call_1" and "Fed holds rates" in msg.content
+
+
+def test_retriever_summaries() -> None:
+    seen: List[httpx.Request] = []
+    docs = NestDaddyNewsRetriever(api_wrapper=wrapper(seen), k=2).invoke("fed")
+    assert [d.page_content for d in docs] == ["The Fed held rates.", "Stocks rose."]
+    assert docs[0].metadata["url"] == "https://news.example/a" and docs[0].metadata["full_text"] is False
+    assert len(seen) == 1
+
+
+def test_retriever_full_text_keeps_summary_when_unreadable() -> None:
+    seen: List[httpx.Request] = []
+    docs = NestDaddyNewsRetriever(api_wrapper=wrapper(seen), k=2, full_text=True).invoke("fed")
+    assert docs[0].page_content.startswith("Full article text") and docs[0].metadata["full_text"] is True
+    assert docs[1].page_content == "Stocks rose." and docs[1].metadata["full_text"] is False
+    assert len(seen) == 3
+
+
+async def test_async_tool_and_retriever() -> None:
+    seen: List[httpx.Request] = []
+    out = await NestDaddySearch(api_wrapper=wrapper(seen)).ainvoke({"query": "mcp"})
+    assert out["count"] == 1
+    docs = await NestDaddyNewsRetriever(api_wrapper=wrapper(seen), k=2, full_text=True).ainvoke("fed")
+    assert docs[0].metadata["full_text"] is True and len(docs) == 2
+
+
+def test_output_is_json_serialisable() -> None:
+    seen: List[httpx.Request] = []
+    out: Dict[str, Any] = NestDaddyNewsSearch(api_wrapper=wrapper(seen)).invoke({"query": "fed"})
+    json.dumps(out)

langchain_nestdaddy-0.1.0/tests/unit_tests/test_standard.py

@@ -0,0 +1,53 @@
+"""LangChain standard unit tests for the NestDaddy tools (no network)."""
+
+from typing import Type
+
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_nestdaddy import NestDaddyNewsSearch, NestDaddyReadPage, NestDaddySearch
+
+
+class TestNestDaddySearchUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> Type[NestDaddySearch]:
+        return NestDaddySearch
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"api_key": "test-key", "max_results": 3}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"query": "model context protocol"}
+
+    @property
+    def init_from_env_params(self) -> tuple:
+        return ({"NESTDADDY_API_KEY": "env-key"}, {}, {})
+
+
+class TestNestDaddyNewsSearchUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> Type[NestDaddyNewsSearch]:
+        return NestDaddyNewsSearch
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"api_key": "test-key"}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"query": "interest rates", "country": "US", "days": 7}
+
+
+class TestNestDaddyReadPageUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> Type[NestDaddyReadPage]:
+        return NestDaddyReadPage
+
+    @property
+    def tool_constructor_params(self) -> dict:
+        return {"api_key": "test-key"}
+
+    @property
+    def tool_invoke_params_example(self) -> dict:
+        return {"url": "https://example.com/article"}