Metadata-Version: 2.5
Name: langchain-nestdaddy
Version: 0.1.1
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: 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 :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
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.
