langchain-youdotcom 0.3.1

An integration package connecting You.com and LangChain

langchain-youdotcom

LangChain partner package for You.com search, content extraction, research, and finance research APIs.

Installation | Credentials | Tools | Retriever | API Wrapper | Resources

Installation

pip install -U langchain-youdotcom

Credentials

Get an API key at you.com/platform/api-keys, then set it as an environment variable:

export YDC_API_KEY="your-api-key"

Or pass it directly when instantiating any component:

from langchain_youdotcom import YouSearchTool, YouAPIWrapper

tool = YouSearchTool(api_wrapper=YouAPIWrapper(ydc_api_key="your-api-key"))

Tools

YouSearchTool

Search the web with up to date results. Supports geographic filtering, freshness controls, and optional live-crawling for full page content. Great for monitoring mentions, pulling recent news, or feeding live data into agent workflows.

Instantiation parameters (set on YouAPIWrapper):

Parameter	Type	Default	Description
count	int | None	None	Max results per section, 1-100
country	str | None	None	Two-letter country code to focus results geographically
freshness	str | None	None	Filter by recency: day, week, month, or year
language	str | None	None	BCP-47 language code for results
livecrawl	str | None	None	Fetch full page content: web, news, or all
livecrawl_formats	str | None	None	Format for livecrawled content: html or markdown
offset	int | None	None	Pagination offset, 0-9
safesearch	str | None	None	Content filter: off, moderate, or strict
k	int | None	None	Max documents to return

Invocation args:

• query (required, str): The search query.

from langchain_youdotcom import YouSearchTool, YouAPIWrapper

tool = YouSearchTool(
    api_wrapper=YouAPIWrapper(
        count=5,
        country="US",
        freshness="week",
        livecrawl="web",
        livecrawl_formats="markdown",
    ),
)

# invoke directly
result = tool.invoke("latest AI news")
print(result)

Using with an agent:

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

from langchain_youdotcom import YouSearchTool

tools = [YouSearchTool()]
agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)

response = agent.invoke(
    {"messages": [{"role": "user", "content": "what happened in AI today?"}]}
)

YouContentsTool

Extract clean, structured content from one or more web pages. Returns page text as markdown or HTML, plus metadata like JSON-LD, OpenGraph, and Twitter Cards. Useful for scraping product pages, pulling article text, or extracting structured data from any URL.

Instantiation parameters (set on YouAPIWrapper):

No tool-level configuration. All parameters are passed at invocation time.

Invocation args:

• urls (required, list[str]): URLs to fetch content from.

Content format and timeout are configured when calling the wrapper directly (see YouAPIWrapper).

Parameter	Type	Default	Description
urls	list[str]	—	URLs to extract content from (required)
formats	list[str] | None	["markdown", "metadata"]	Output formats: markdown, html, and/or metadata
crawl_timeout	float | None	None	Per-URL crawl timeout in seconds

from langchain_youdotcom import YouContentsTool

tool = YouContentsTool()
result = tool.invoke({"urls": ["https://example.com"]})
print(result)

YouResearchTool

Get a comprehensive, cited answer to a complex question. The Research API searches the web, reads multiple sources, and synthesizes a detailed markdown response with inline numbered citations. Perfect for competitive analysis, market research, technical due diligence, or any question that needs more than a simple search result.

Instantiation parameters (set on YouAPIWrapper):

Parameter	Type	Default	Description
research_effort	str | None	None	Controls depth and speed (see levels below)

Research effort levels:

Level	Description
lite	Quick answers for straightforward questions
standard	Balanced speed and depth (default)
deep	More time researching and cross-referencing sources
exhaustive	Most thorough option for complex research tasks

Invocation args:

• query (required, str): The research question.

from langchain_youdotcom import YouResearchTool, YouAPIWrapper

# default effort
tool = YouResearchTool()
result = tool.invoke("what are the latest advances in quantum computing")
print(result)

# deep research
tool = YouResearchTool(
    api_wrapper=YouAPIWrapper(research_effort="deep"),
)
result = tool.invoke("compare transformer architectures for long-context tasks")
print(result)

YouFinanceResearchTool

Get a comprehensive, citation-backed answer to a financial question. The Finance Research API works like the Research API but searches a finance-optimized index covering SEC filings, earnings reports, equity prices, macro indicators, and financial news. Ideal for earnings analysis, competitive benchmarking, due diligence, and market research.

Instantiation parameters (set on YouAPIWrapper):

Parameter	Type	Default	Description
research_effort	str | None	None	Controls depth (shared with YouResearchTool; see levels below)

Finance research only accepts deep and exhaustive. Other values raise ValueError.

Level	Description
deep	Multi-source analysis, earnings summaries, competitive benchmarking (default)
exhaustive	Comprehensive research, deep due diligence, full 10-K analysis

Invocation args:

• query (required, str): The financial research question.

from langchain_youdotcom import YouFinanceResearchTool, YouAPIWrapper

tool = YouFinanceResearchTool()
result = tool.invoke("what were NVIDIA's key revenue drivers in FY2025")
print(result)

# exhaustive research for complex due diligence
tool = YouFinanceResearchTool(
    api_wrapper=YouAPIWrapper(research_effort="exhaustive"),
)
result = tool.invoke("compare gross margins of Apple, Microsoft, and Google over the past three fiscal years")
print(result)

Retriever

The simplest way to get You.com search results as LangChain documents. Accepts all search parameters from YouSearchTool.

from langchain_youdotcom import YouRetriever

retriever = YouRetriever()
docs = retriever.invoke("latest AI news")

for doc in docs:
    print(doc.metadata["title"])
    print(doc.page_content[:200])
    print()

With search parameters:

retriever = YouRetriever(
    k=5,
    count=10,
    livecrawl="web",
    livecrawl_formats="markdown",
    country="US",
    freshness="week",
    safesearch="moderate",
)

YouAPIWrapper

Lower-level wrapper that powers the tools and retriever under the hood. Use it directly when you need full control over API calls and response formats.

Search:

from langchain_youdotcom import YouAPIWrapper

wrapper = YouAPIWrapper()

# search -> list[Document]
docs = wrapper.results("latest AI news")

# raw SDK response
raw = wrapper.raw_results("latest AI news")

Contents:

pages = wrapper.contents(
    ["https://example.com"],
    formats=["markdown", "metadata"],
    crawl_timeout=30,
)

Research:

# research -> formatted markdown with sources
text = wrapper.research_text("explain quantum entanglement")

# raw SDK response
raw = wrapper.raw_research("explain quantum entanglement")

Finance Research:

# finance research -> formatted markdown with sources
text = wrapper.finance_text("what drove NVIDIA's revenue growth in FY2025")

# raw response (parsed from JSON)
raw = wrapper.raw_finance("compare AAPL and MSFT gross margins")

Async variants are available for all methods: results_async, raw_results_async, contents_async, research_text_async, raw_research_async, finance_text_async, raw_finance_async.

Resources

• You.com API docs
• Search API reference
• Contents API reference
• Research API reference
• Finance Research API reference
• You.com API keys

Development

uv sync --all-groups
make format            # ruff format + fix
make lint              # ruff check + format diff + mypy
make test              # unit tests
make integration_tests # requires YDC_API_KEY
make check_imports     # verify all modules importable