Metadata-Version: 2.5
Name: langchain-groundtruth
Version: 0.1.0
Summary: LangChain tools for the Ground Truth company API: look up a company from its domain (registrar, DNS, tech stack, hiring) and read the contact details it publishes.
Project-URL: Homepage, https://companyfacts.dev
Project-URL: Documentation, https://companyfacts.dev/llms.txt
Project-URL: Pricing, https://companyfacts.dev/pricing
License: MIT
License-File: LICENSE
Keywords: ai-agents,company-data,company-enrichment,company-lookup,contact-info,domain-lookup,hiring-data,langchain,langchain-tools,tech-stack
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: groundtruth-company>=0.1.1
Requires-Dist: langchain-core>=1.0.0
Description-Content-Type: text/markdown

# 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

```python
from langchain_groundtruth import GroundTruthCompanyLookup

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

## The tools

| Class | Tool name | Input | Returns |
|---|---|---|---|
| `GroundTruthCompanyLookup` | `groundtruth_company_lookup` | `domain`; optional `name`, `country`, `ticker` | JSON: registrar and DNS record, email provider, tech stack, hiring (open roles, salary ranges where published, roles opened and closed in the last 30 days). With `name` and `country` the official register entry; with `ticker` revenue reported to the SEC. A part with nothing to report is listed under `missing` with the reason |
| `GroundTruthCompanyContacts` | `groundtruth_company_contacts` | `domain` | JSON: phone numbers, role inboxes such as `sales@`, contact page, postal address, read from the company's own website. For US companies also the other addresses it published at its own domain. Nothing is guessed from a name pattern |

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

## Agent example

```python
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

```bash
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.

| | |
|---|---|
| Free tier | 10 calls a day, no key |
| $10 once | 2,000 calls that never expire. [Buy](https://buy.stripe.com/dRm7sM04G4iManHeO51Jm00) |
| $49 a month | 20,000 calls a month. [Buy](https://buy.stripe.com/9B6aEYg3EbLe8fz35n1Jm01) |

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.

```python
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

| Argument | Default | |
|---|---|---|
| `api_key` | `GROUNDTRUTH_API_KEY` env var, else none | Stored as a secret, never shown in `repr` |
| `base_url` | `https://companyfacts.dev` | Point at another deployment |
| `timeout` | `60.0` | Seconds per call. A company lookup runs several checks in parallel |

## 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`](https://pypi.org/project/groundtruth-company/)), a remote MCP server at `https://companyfacts.dev/mcp`, and plain REST. Docs: https://companyfacts.dev/llms.txt

MIT licensed.
