Metadata-Version: 2.4
Name: medscope-api
Version: 0.1.0
Summary: Python client library for the MedScope API
Project-URL: Homepage, https://medscope.info
Project-URL: Documentation, https://medscope.info
Author: MedScope
License: Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# MedScope API for Python

Official Python client for the MedScope API.

Use this package if you want to send documents easily to MedScope from Python without building HTTP requests, headers, file uploads, or error handling yourself.

Python 3.10 or newer is required.

The client sends requests to:

```text
https://api.medscope.info
```

## Install

From PyPI:

```bash
pip install medscope-api
```

From this repository:

```bash
pip install ./code
```

If you are already inside the `code` directory:

```bash
pip install .
```

## Set Your API Key

You can pass the API key directly:

```python
from medscope import MedScope

client = MedScope(api_key="your_medscope_api_key")
```

For applications that make multiple requests, use the client as a context
manager so pooled network connections are closed deterministically:

```python
from medscope import MedScope

with MedScope(api_key="your_medscope_api_key") as client:
    result = client.extract("your_doctors_letter.pdf")
```

Or set it once as an environment variable:

```bash
export MEDSCOPE_API_KEY="your_medscope_api_key"
```

Then create the client without passing the key:

```python
from medscope import MedScope

client = MedScope()
```

## Test The API Server Connection

```python
from medscope import MedScope

client = MedScope()

print(client.health())
```

## Extract Data From A PDF

```python
from medscope import MedScope

client = MedScope(api_key="your_medscope_api_key")

result = client.extract(
    "your_doctors_letter.pdf",
)

print(result)
```

`extract(...)` accepts a file path (`str` or `PathLike`), PDF bytes, or an open binary file object.

## Options

You can enable optional API features with `flags`:

```python
from medscope import MedScope

client = MedScope(
    api_key="your_medscope_api_key",
    flags={
        "include_fhir": True,
        "include_raw_text": False,
    },
)

result = client.extract(
    "your_doctors_letter.pdf",
)
```

You can also pass flags for a single request:

```python
result = client.extract(
    "your_doctors_letter.pdf",
    flags={"include_fhir": True},
)
```

Request-level flags override client-level flags.

Unknown flags are allowed and sent as query parameters. This lets the API support new flags without requiring an immediate client update.

## Client Configuration

The default request timeout is 120 seconds. You can configure it globally or
for a single request:

```python
client = MedScope(api_key="your_medscope_api_key", timeout=180)
result = client.extract("your_doctors_letter.pdf", timeout=240)
```

For local development or staging, pass a different API URL:

```python
client = MedScope(
    api_key="your_medscope_api_key",
    base_url="https://staging-api.example.com",
)
```

## Exclude Data Blocks

Use `exclude` to remove specific entity blocks from the returned `structured_data` and `quality` sections:

```python
result = client.extract(
    "your_doctors_letter.pdf",
    exclude=["medication", "allergies"],
)
```

You can also pass a comma-separated string:

```python
result = client.extract(
    "your_doctors_letter.pdf",
    exclude="medication,allergies",
)
```

## Available Methods

```python
client.health()
client.extract("your_doctors_letter.pdf")
```

## Errors

The client raises `MedScopeAuthenticationError` if no API key is configured for a protected request.

The client raises `MedScopeAPIError` if the API returns an error response or an unexpected response.

`MedScopeAPIError.status_code` contains the HTTP status when one was received,
and `MedScopeAPIError.response` contains the parsed error response. These fields
may contain sensitive medical information and should not be logged without
appropriate redaction.

```python
from medscope import MedScope, MedScopeAPIError, MedScopeAuthenticationError

client = MedScope(api_key="your_medscope_api_key")

try:
    result = client.extract("your_doctors_letter.pdf")
except MedScopeAuthenticationError:
    print("Missing API key")
except MedScopeAPIError as error:
    print(error)
```

## Development

Use this only if you want to work on the client library itself:

```bash
pip install -e ".[dev]"
pytest
```
