Metadata-Version: 2.5
Name: langchain-carejobs
Version: 0.1.0
Summary: LangChain tools for CareJobs.Now: open US healthcare jobs, posted pay and employers
Project-URL: Homepage, https://carejobs.now
Project-URL: Repository, https://github.com/yumaheymans/langchain-carejobs
Project-URL: Issues, https://github.com/yumaheymans/langchain-carejobs/issues
Project-URL: Changelog, https://github.com/yumaheymans/langchain-carejobs/blob/main/CHANGELOG.md
Author-email: "CareJobs.Now" <hello@carejobs.now>
License: MIT
License-File: LICENSE
Keywords: agent,healthcare,jobs,langchain,mcp,nursing,tools
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: <4.0.0,>=3.10.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: langchain-core<2.0.0,>=1.0.0
Description-Content-Type: text/markdown

# langchain-carejobs

[![PyPI - Version](https://img.shields.io/pypi/v/langchain-carejobs?label=%20)](https://pypi.org/project/langchain-carejobs/#history)
[![PyPI - License](https://img.shields.io/pypi/l/langchain-carejobs)](https://opensource.org/licenses/MIT)
[![PyPI - Downloads](https://img.shields.io/pepy/dt/langchain-carejobs)](https://pypistats.org/packages/langchain-carejobs)

This package contains the LangChain integration with [CareJobs.Now](https://carejobs.now), a free
US healthcare job board. It reads the open jobs of more than 2,000 hospitals, health systems,
clinic groups and care companies: nurses, CNAs, doctors, NPs and PAs, therapists, imaging and lab
techs, pharmacy, caregivers, front office and more.

The tools give a LangChain agent live access to those jobs, their posted pay, the employers and the
job-market numbers, through the public CareJobs.Now remote MCP endpoint. **No API key or account is
needed.** Every job in an answer links to its page on CareJobs.Now, where the person applies.

## Quick install

```bash
pip install langchain-carejobs
```

## Use the tools in an agent

```python
from langchain.agents import create_agent
from langchain_carejobs import CareJobsToolkit

tools = CareJobsToolkit().get_tools()

agent = create_agent(model="claude-sonnet-4-6", tools=tools)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Find night-shift ICU nursing jobs in Texas that pay at least "
                "$45 an hour, and tell me which employers post the most for nurses.",
            }
        ]
    }
)
print(result["messages"][-1].content)
```

## Available tools

| Class | Tool name | What it returns |
| --- | --- | --- |
| `CareJobsSearchJobs` | `search_healthcare_jobs` | Open jobs filtered by keyword, kind of job, employer, state, remote only, minimum hourly pay and sort order, with a link to each. |
| `CareJobsGetPay` | `get_healthcare_pay` | The median and typical hourly pay open jobs post, for every kind of job, one kind, one employer, or an employer and a kind. |
| `CareJobsGetJobMarket` | `get_healthcare_job_market` | How many healthcare jobs are open and new this week, by kind of job, state and employer. |
| `CareJobsGetJobsByState` | `get_healthcare_jobs_by_state` | Every state's open jobs, or one state's jobs by kind, pay, towns, employers and newest jobs. |
| `CareJobsListEmployers` | `list_healthcare_employers` | Employers, AI-training programs and job boards by name, kind of care, state or kind of job, with the slugs the other tools take. |
| `CareJobsGetEmployer` | `get_healthcare_employer` | One employer: where it hires, its open jobs by kind, posted pay, newest and best-paid jobs. |

The `kind` argument takes one of `nurses`, `nurse-practitioners`, `physicians`,
`nursing-assistants`, `caregivers`, `therapy-rehab`, `mental-health`, `pharmacy`, `imaging`, `lab`,
`surgical-techs`, `emts-paramedics`, `medical-assistants`, `dental`, `admin`, `allied-health` or
`ai-training`. The `state` argument takes a two-letter code (`TX`) or a name (`Texas`). Employers
are identified by a slug such as `kaiser-permanente` or by name.

`CareJobsToolkit().get_tools()` returns all six. Every tool also works on its own:

```python
from langchain_carejobs import CareJobsSearchJobs

tool = CareJobsSearchJobs()
print(tool.invoke({"kind": "nurses", "state": "TX", "query": "ICU", "limit": 5}))
```

Tools run natively async: use `await tool.ainvoke(...)`.

## Summary and structured data

Each tool returns the service's readable summary as the message content. The structured answer
that comes with it is the artifact of the `ToolMessage`:

```python
message = tool.invoke(
    {
        "args": {"state": "OH", "kind": "nursing-assistants"},
        "id": "1",
        "name": "get_healthcare_jobs_by_state",
        "type": "tool_call",
    }
)
print(message.content)  # the readable summary
print(message.artifact)  # the structured answer (a dict)
```

Here `tool` is a `CareJobsGetJobsByState()`.

## Errors

If CareJobs.Now cannot be reached or rejects a request (for example an unknown employer), the tool
returns the service's message to the model, which can correct the call. The tools set
`handle_tool_error=True` for this. Pass `handle_tool_error=False` to raise `CareJobsError` (a
`ToolException`) instead.

The first request after a quiet period can take up to about 25 seconds while the service wakes.
The default timeout is 30 seconds. To wait longer, pass a client:

```python
from langchain_carejobs import CareJobsAPIWrapper, CareJobsToolkit

toolkit = CareJobsToolkit(api_wrapper=CareJobsAPIWrapper(timeout=60))
```

## Notes on the data

- Pay is what employers post, measured from the hourly rates open jobs state, before shift
  differentials and bonuses.
- Results cover US jobs only.
- Send people to the link in each result to apply. The tools never apply to a job.

## Privacy

The tools send only the arguments of each call to `https://carejobs.now/api/mcp` and store
nothing. See the CareJobs.Now [privacy policy](https://carejobs.now/legal/privacy) and
[terms](https://carejobs.now/legal/terms).

## Development

```bash
uv sync --all-groups
make test                      # unit tests, network disabled
make integration_tests         # standard integration tests against the live API
make lint
```

## Links

- Service: https://carejobs.now
- Source: https://github.com/yumaheymans/langchain-carejobs
- Contact: hello@carejobs.now
- [LangChain](https://docs.langchain.com/oss/python/langchain/overview)
