Metadata-Version: 2.4
Name: midim-sdk
Version: 0.1.0
Summary: Official Python SDK for the MIDIM Verify API — MIDI provenance and rights verification
Author-email: "MIDIM.net" <developers@midim.net>
License-Expression: MIT
Project-URL: Homepage, https://midim.net/developer
Project-URL: Documentation, https://midim.net/api/docs
Project-URL: Repository, https://github.com/midim/midim-sdk
Project-URL: Bug Tracker, https://github.com/midim/midim-sdk/issues
Keywords: midi,provenance,rights,verification,sdk,api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Multimedia :: Sound/Audio
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# midim-sdk · Python

Official Python SDK for the [MIDIM Verify API](https://midim.net/developer) — MIDI provenance, rights verification, and POIM status in one call.

## Installation

```bash
pip install midim-sdk
```

Requires **Python 3.9+**. No external runtime dependencies — uses the standard library `urllib`.

## Quick start

```python
from midim_sdk import MidimClient

client = MidimClient(api_key="midim_...")

# Verify by file hash
result = client.verify(asset_hash="<sha256-hex-of-midi>")

if result.flagged:
    print("Rights concern detected")
else:
    print(f"Rights confidence: {result.rights_confidence}/100")
```

> Get your API key at **[midim.net/developer](https://midim.net/developer)**.

## API Reference

All methods return typed dataclass instances and raise `MidimApiError` on non-2xx responses.

### `MidimClient(api_key, base_url?)`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str` | — | **Required.** API key starting with `midim_` |
| `base_url` | `str` | `https://midim.net/api` | Override for self-hosted or staging |

---

### `verify(*, asset_hash?, poim_certificate_id?, midi_file?)` → `VerifyResponse`

`POST /api/verify`

Verify MIDI provenance, POIM status, rights, and marketplace eligibility in a single call. Provide **at least one** identifier.

| Parameter | Type | Description |
|---|---|---|
| `asset_hash` | `str?` | SHA-256 hex hash of the MIDI file |
| `poim_certificate_id` | `str?` | POIM certificate ID |
| `midi_file` | `str?` | Base64-encoded MIDI file |

**Returns `VerifyResponse`:**

| Field | Type | Description |
|---|---|---|
| `verification_id` | `str` | Unique ID for this verification |
| `verification_timestamp` | `str` | ISO 8601 timestamp |
| `known_asset` | `bool` | Whether the asset is in the MIDIM registry |
| `poim_registered` | `bool` | Whether a POIM certificate exists |
| `poim_level` | `int \| None` | POIM level 1–4 (None if not registered) |
| `rights_confidence` | `int \| None` | Rights confidence score 0–100 |
| `active_claims` | `int` | Number of active rights claims |
| `license_status` | `str \| None` | License status string |
| `marketplace_eligible` | `bool` | Whether the asset can be listed on a marketplace |
| `flagged` | `bool` | Whether the asset has unresolved rights concerns |
| `asset_id` | `int \| None` | Internal MIDIM asset ID |
| `midim_id` | `str \| None` | Public MIDIM asset identifier |

---

### `get_provenance(asset_id)` → `ProvenanceRecord`

`GET /api/provenance/{assetId}`

Full certificate chain and lineage for an asset.

| Field | Type | Description |
|---|---|---|
| `asset` | `dict?` | Asset metadata |
| `cert_chain` | `list[dict]` | Ordered list of POIM certificates |
| `lineage` | `dict?` | Fork / derivation history |

---

### `get_certificate(cert_id)` → `CertificateDetail`

`GET /api/certificate/{certId}`

Single POIM certificate with evidence and active claims.

| Field | Type | Description |
|---|---|---|
| `cert_id` | `str?` | Certificate ID |
| `asset_id` | `int?` | Asset ID |
| `poim_level` | `int?` | POIM level 1–4 |
| `status` | `str?` | `active` \| `revoked` \| `expired` |
| `rights` | `dict?` | Rights breakdown |
| `claims` | `list[dict]` | Active claims against the certificate |

---

### `get_claims(asset_id)` → `ClaimsList`

`GET /api/claims/{assetId}`

Active and resolved rights claims for an asset.

| Field | Type | Description |
|---|---|---|
| `asset_id` | `int?` | Asset ID |
| `active_claims` | `list[dict]` | Unresolved claims |
| `resolved_claims` | `list[dict]` | Resolved claims |

---

### `get_license(asset_id)` → `LicenseStatus`

`GET /api/license/{assetId}`

License status and composition/arrangement rights.

| Field | Type | Description |
|---|---|---|
| `asset_id` | `int?` | Asset ID |
| `license_status` | `str?` | Overall license status |
| `composition_status` | `str?` | Composition rights status |
| `arrangement_status` | `str?` | Arrangement rights status |
| `rights_confidence` | `int?` | Confidence score 0–100 |
| `source_work` | `str?` | Source work title if a derivative |
| `composer` | `str?` | Composer attribution |

---

### `get_marketplace_eligibility(asset_id)` → `MarketplaceEligibility`

`GET /api/marketplace-eligibility/{assetId}`

Check whether an asset can be listed on a marketplace.

| Field | Type | Description |
|---|---|---|
| `asset_id` | `int?` | Asset ID |
| `eligible` | `bool?` | Eligible for marketplace listing |
| `reasons` | `list[str]` | Blocking reasons if not eligible |
| `rights_confidence` | `int?` | Confidence score 0–100 |

---

### `get_dataset_compliance(dataset_id)` → `DatasetCompliance`

`GET /api/dataset-compliance/{datasetId}`

Aggregate compliance report for an AI training dataset or collection.

| Field | Type | Description |
|---|---|---|
| `dataset_id` | `str?` | Dataset identifier |
| `total_assets` | `int?` | Total assets in the dataset |
| `poim_registered` | `int?` | Number with POIM certificates |
| `poim_distribution` | `dict?` | Breakdown by POIM level |
| `license_summary` | `dict?` | License type distribution |
| `rights_coverage` | `dict?` | Rights coverage statistics |
| `generated_at` | `str?` | ISO 8601 report timestamp |

---

## Error handling

```python
from midim_sdk import MidimClient, MidimApiError

client = MidimClient(api_key="midim_...")

try:
    result = client.verify(asset_hash="abc123")
except MidimApiError as err:
    if err.status == 401:
        print("Invalid API key")
    elif err.status == 404:
        print("Asset not found")
    else:
        print(f"MIDIM API error {err.status}: {err.error}")
```

## Links

- **Developer Portal**: [midim.net/developer](https://midim.net/developer)
- **API Reference**: [midim.net/api/docs](https://midim.net/api/docs)
- **TypeScript SDK**: [`midim-sdk` on npm](https://www.npmjs.com/package/midim-sdk)
- **License**: MIT
