# oig-leie

A small, dependency-free Python client for screening against the public
**OIG LEIE** (List of Excluded Individuals/Entities), the federal database of
people and organizations excluded from Medicare, Medicaid, and all other
federal healthcare programs.

## What the LEIE is

The LEIE is published monthly by the U.S. Department of Health and Human
Services, Office of Inspector General (OIG), as a downloadable CSV. Each row
describes one excluded individual or entity. The official download page is:

https://oig.hhs.gov/exclusions/exclusions_list.asp

## Why it matters

Screening against the LEIE is a mandatory part of healthcare credentialing and
provider enrollment. Federal healthcare programs do not pay for items or
services furnished, ordered, or prescribed by an excluded individual or entity,
and employing or contracting with an excluded party can expose an organization
to civil monetary penalties. Most compliance programs check the LEIE on hire
and on a recurring basis (commonly monthly) for staff, contractors, and
vendors.

## The human-verification caveat (read this first)

A name match, or even an NPI match, against the LEIE is **not** a confirmed
exclusion. OIG requires verifying a potential match using additional
identifiers such as a Social Security Number, date of birth, or other
identifying data before any adverse action is taken.

This library reflects that posture deliberately. Lookups return **possible
matches** that a human must verify. The library never returns a definitive
"excluded = true" verdict. Sources surface candidates. A human makes the
decision.

## Install

```
pip install oig-leie
```

Optional MCP server support:

```
pip install "oig-leie[mcp]"
```

The core library has no runtime dependencies.

## Usage

First, download the monthly LEIE CSV from the official page above and save it
locally (for example as `leie.csv`). Then load it and run lookups.

```python
from oig_leie import LeieClient

client = LeieClient.from_csv("leie.csv")

# Individual lookup by last name (first name optional, matched as a prefix).
possible = client.check_individual("Sampleton", "Roberta")
for record in possible:
    print(record.display_name, record.excltype, record.excldate)

# Business / entity lookup (case-insensitive, partial match).
client.check_business("home health")

# NPI lookup (only digits are compared, so formatting does not matter).
client.check_npi("1234567893")
```

Every returned item is a frozen `Exclusion` dataclass holding the raw CSV
fields (`lastname`, `firstname`, `midname`, `busname`, `general`, `specialty`,
`npi`, `upin`, `dob`, address fields, `excltype`, `excldate`, `reindate`,
`waiverdate`, and more). Remember: a returned record is a candidate to verify,
not a confirmed exclusion.

You can also load from an open file object or from a string:

```python
with open("leie.csv", encoding="utf-8-sig") as fh:
    client = LeieClient.from_fileobj(fh)

client = LeieClient.from_string(csv_text)
```

### Refreshing the local file (optional)

A helper is provided for callers who want to fetch the monthly CSV
programmatically. It performs a real network request, so it is never called by
the test suite or during normal use. Pass the official monthly CSV URL.

```python
from oig_leie import download

download("https://oig.hhs.gov/exclusions/downloadables/UPDATED.csv", "leie.csv")
```

## MCP server

With the `mcp` extra installed, the package ships an optional
[Model Context Protocol](https://modelcontextprotocol.io) server exposing a
single `check_exclusion` tool. Point it at a local LEIE CSV via the
`OIG_LEIE_CSV` environment variable.

```
OIG_LEIE_CSV=/path/to/leie.csv oig-leie-mcp
```

Example MCP client configuration:

```json
{
  "mcpServers": {
    "oig-leie": {
      "command": "oig-leie-mcp",
      "env": { "OIG_LEIE_CSV": "/path/to/leie.csv" }
    }
  }
}
```

The `check_exclusion` tool accepts `last_name`, `first_name`, and `npi`, and
returns candidate matches plus an explicit `requires_human_verification` flag
and disclaimer. It does not confirm exclusion.

## Development

```
python -m venv .venv
. .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest -v
```

The test suite uses a small synthetic fixture CSV with made-up names and makes
no network calls.

## License

MIT. Copyright (c) 2026 Giles-Evan Mboumi. See [LICENSE](LICENSE).

## Disclaimer

This project is not affiliated with or endorsed by the HHS Office of Inspector
General. It is a convenience client over publicly published data. Always follow
OIG guidance and your own compliance program when screening and verifying
matches.