Metadata-Version: 2.4
Name: clarismd
Version: 0.1.0
Summary: Open-source AI gateway with PHI-aware governance — Python client
Project-URL: Homepage, https://clarismd.com
Project-URL: Documentation, https://docs.clarismd.com
Project-URL: Repository, https://github.com/amanjaiswal777/clarismd-python
Project-URL: Issues, https://github.com/amanjaiswal777/clarismd-python/issues
Project-URL: Changelog, https://github.com/amanjaiswal777/clarismd-python/blob/main/CHANGELOG.md
Author: ClarisMD contributors
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai-gateway,audit,clarismd,healthcare,llm,openai,phi
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: typing-extensions>=4.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="./assets/logo.svg" alt="ClarisMD" width="120" height="120"/>
</p>

<h1 align="center">clarismd</h1>

<p align="center">
  <a href="https://pypi.org/project/clarismd/"><img alt="PyPI" src="https://img.shields.io/pypi/v/clarismd.svg"/></a>
  <a href="https://pypi.org/project/clarismd/"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/clarismd.svg"/></a>
  <a href="https://github.com/amanjaiswal777/clarismd-python/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/amanjaiswal777/clarismd-python/actions/workflows/ci.yml/badge.svg"/></a>
  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/pypi/l/clarismd.svg"/></a>
  <a href="https://pypi.org/project/clarismd/"><img alt="PyPI Downloads" src="https://img.shields.io/pypi/dm/clarismd.svg"/></a>
</p>

Official Python SDK for the [ClarisMD](https://clarismd.com) governed-AI gateway
for healthcare. One-line drop-in replacement for the OpenAI SDK with PHI
detection, audit logging, and configurable policy enforcement built in.

> **Note.** ClarisMD is a governance gateway. It does not, by itself, make any
> call HIPAA compliant — compliance is a property of your full deployment,
> contracts (BAAs), and operational controls. See `NOTICE` for the full
> disclaimer.

---

## Install

From PyPI:

```bash
pip install clarismd
```

From the public GitHub repo (latest `main`, or pin to a tag/commit):

```bash
pip install git+https://github.com/amanjaiswal777/clarismd-python.git
pip install git+https://github.com/amanjaiswal777/clarismd-python.git@v0.1.0
pip install git+https://github.com/amanjaiswal777/clarismd-python.git@<commit-sha>
```

In a `requirements.txt`:

```
clarismd @ git+https://github.com/amanjaiswal777/clarismd-python.git@v0.1.0
```

For local development (editable install with dev extras):

```bash
git clone https://github.com/amanjaiswal777/clarismd-python.git
cd clarismd-python
pip install -e ".[dev]"
```

Python 3.9+ supported.

---

## Quickstart

```python
from clarismd import ClarisMD

client = ClarisMD()  # reads CLARISMD_API_KEY

resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Summarize hypertension treatment options."}],
)
print(resp.choices[0].message.content)
```

Set your API key once:

```bash
export CLARISMD_API_KEY=cmd-...
```

---

## Migrating from OpenAI

The surface mirrors `openai>=1.0`. In most cases, the diff is one line:

```diff
-from openai import OpenAI
-client = OpenAI()
+from clarismd import ClarisMD
+client = ClarisMD()
```

Everything else — `client.chat.completions.create`, `client.embeddings.create`,
streaming, async — works the same way.

---

## Self-host

Point the SDK at your own gateway with one environment variable:

```bash
export CLARISMD_BASE_URL=https://gateway.your-org.internal/v1
export CLARISMD_API_KEY=cmd-...
```

Or pass it explicitly:

```python
client = ClarisMD(base_url="https://gateway.your-org.internal/v1")
```

Verify the gateway is reachable (no API key required):

```python
status = client.health.check()
print(status.status, status.version)  # "ok" 0.4.2
```

---

## Streaming

```python
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain ACE inhibitors briefly."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content, end="", flush=True)
```

Streams expose `.close()` and the underlying `httpx.Response` via
`stream.response`, and can be used as context managers.

---

## Async

```python
import asyncio
from clarismd import AsyncClarisMD

async def main() -> None:
    async with AsyncClarisMD() as client:
        resp = await client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": "Hi"}],
        )
        print(resp.choices[0].message.content)

asyncio.run(main())
```

---

## PHI scan

Run text through the PHI detector without making a generation call:

```python
result = client.phi.scan("Patient John Doe, MRN 4471, called the clinic.")
if result.detected:
    for entity in result.entities:
        print(entity.type, "->", entity.text)
```

---

## Audit export

Pull a signed evidence bundle for a date range:

```python
from datetime import datetime, timezone

bundle = client.audit.export(
    format="pdf",
    start_date=datetime(2026, 5, 1, tzinfo=timezone.utc),
    end_date=datetime(2026, 5, 31, tzinfo=timezone.utc),
)
with open("audit-may.pdf", "wb") as f:
    f.write(bundle)
```

---

## Compliance score

```python
score = client.compliance.score(framework="hipaa")
print(f"Auto-verified: {score.auto_verified.satisfied}/{score.auto_verified.total}")
print(f"Manual:        {score.manual.acknowledged}/{score.manual.total}")
```

---

## Error handling

All errors derive from `ClarisMDError`. The closed-set typed errors let you
branch precisely:

```python
from clarismd import (
    ClarisMD,
    AuthenticationError,
    PHIPolicyViolationError,
    RateLimitError,
)

client = ClarisMD()

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "..."}],
    )
except PHIPolicyViolationError as exc:
    # Request was blocked by a configured PHI policy.
    print("PHI violation:", exc, "request_id:", exc.request_id)
except RateLimitError as exc:
    # Retry-After honored automatically; this fires only after the budget is spent.
    print("Backed off too long:", exc)
except AuthenticationError:
    # 401 — bad / missing / revoked key.
    raise
```

Every `APIError` carries `.status_code`, `.request_id`, `.code`, `.param`,
`.type`, and `.body` for structured handling and bug reports.

### ClarisMD-specific request options

Two extra kwargs are accepted on every method and translate into HTTP headers
the gateway understands:

| Kwarg                | Header                       | Effect |
|----------------------|------------------------------|--------|
| `clarismd_policy`    | `X-ClarisMD-Policy`          | Override the policy for this request |
| `clarismd_phi_action`| `X-ClarisMD-PHI-Action`      | One of `block`, `redact`, `tokenize`, `alert` |

```python
client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "..."}],
    clarismd_phi_action="redact",
)
```

---

## Examples

Runnable scripts live in [`examples/`](./examples):

- [`quickstart.py`](./examples/quickstart.py) — five-line basic call
- [`streaming.py`](./examples/streaming.py) — server-sent-events streaming
- [`async_chat.py`](./examples/async_chat.py) — `AsyncClarisMD` round-trip
- [`phi_scan.py`](./examples/phi_scan.py) — PHI entity detection
- [`audit_export.py`](./examples/audit_export.py) — pull a PDF evidence bundle
- [`compliance_score.py`](./examples/compliance_score.py) — auto vs. manual breakdown

---

## License

Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).

The ClarisMD backend is licensed AGPL-3.0; this SDK is intentionally permissive
so you can ship it inside any application without copyleft obligations.

## Contributing

Issues and PRs welcome — see [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the
dev setup and PR conventions, and [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md)
for community expectations.

## Security

Found a vulnerability? Please report it privately per
[`SECURITY.md`](./SECURITY.md) — do not open a public issue.
