langchain-groundtruth

LangChain tools that look up a company from its website domain: who runs the domain, what its website runs on, whether it is hiring, and how to reach it. Every item in the answer links to the page or record it came from.

pip install -U langchain-groundtruth

Python 3.10+ (the minimum for langchain-core). Works without a key on the free tier (10 calls a day).

Two lines

from langchain_groundtruth import GroundTruthCompanyLookup

print(GroundTruthCompanyLookup().invoke({"domain": "stripe.com"}))

The tools

Both are BaseTool subclasses with pydantic input schemas, sync and async.

Agent example

from langchain.agents import create_agent
from langchain_groundtruth import GroundTruthCompanyContacts, GroundTruthCompanyLookup

agent = create_agent(
    model="openai:gpt-5.5",  # any chat model you have configured
    tools=[GroundTruthCompanyLookup(), GroundTruthCompanyContacts()],
)
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Is stripe.com hiring, and what does its website run on?"}]}
)
print(result["messages"][-1].content)

Key

export GROUNDTRUTH_API_KEY="your-key"

or pass it in: GroundTruthCompanyLookup(api_key="your-key"). Without a key you get 10 calls a day per caller, no sign-up.

A company lookup uses 2 of a key's calls, a contacts lookup 4. A call that fails is not charged. Live prices: https://companyfacts.dev/pricing

Errors

A failed call does not crash the agent. The tools set handle_tool_error, so the message comes back as the tool result (a ToolMessage with status error) and the model can read it and tell the user. That covers a spent free allowance (the message includes where to buy a key), a malformed domain, a site that blocks automated readers, a domain with nothing found, and an upstream source being down.

tool = GroundTruthCompanyLookup()
print(tool.invoke({"domain": "stripe.com"}))
# If the free allowance is used up this prints the explanation and the buy link, it does not raise.

To get exceptions instead, set handle_tool_error=False.

Options

Tests

pip install pytest pytest-asyncio langchain-tests
PYTHONPATH=src python -m pytest tests/unit_tests
GROUNDTRUTH_LIVE=1 PYTHONPATH=src python -m pytest tests/integration_tests   # calls the real API

The unit tests run LangChain's standard ToolsUnitTests and ToolsIntegrationTests suites, plus behaviour tests, with the HTTP layer faked.

Other ways in

The same data is available as a Python client (groundtruth-company), a remote MCP server at https://companyfacts.dev/mcp, and plain REST. Docs: https://companyfacts.dev/llms.txt

MIT licensed.