minerva-sdk 0.0.12

Official Python SDK for the Minerva Data API — resolve, enrich, validate, usage.

Minerva SDK

The official Python SDK for the Minerva Data API — identity resolution, person enrichment, and validation, with one client, typed responses, and input validation baked in.

from minerva import Minerva

mc = Minerva()  # reads MINERVA_API_KEY from the environment

mc.status.health()          # quick liveness check (unauthenticated) -> {"api": HealthStatus(ok=True, ...)}

results = mc.api.enrich([{"record_id": "1", "linkedin_url": "https://www.linkedin.com/in/example"}])
df = results.to_df()        # straight to a DataFrame

Early access. Data API surface — resolve, enrich, LinkedIn lookup, email validation, country inference, and usage tallies — is wired and tested.

---

Installation

pip install minerva-sdk

Optional extras:

pip install "minerva-sdk[pandas]"   # results.to_df()
pip install "minerva-sdk[table]"    # results.to_table()
pip install "minerva-sdk[gsheet]"   # mc.io.*_from_sheet / .to_sheet
pip install "minerva-sdk[excel]"    # mc.io.*_from_excel / .to_excel
pip install "minerva-sdk[all]"      # everything

Requires Python 3.11+ (tested through 3.14).

---

Authentication

Minerva is the single entry point. The only credential you need is your API key:

Variable	Used for
MINERVA_API_KEY	every call the SDK makes

mc = Minerva()                          # api_key from MINERVA_API_KEY
mc = Minerva(api_key="mk_live_...")     # explicit

The SDK sends the API key as the x-api-key header on every request. The server-side authorizer decides what your key is entitled to.

---

Quickstart

from minerva import Minerva

mc = Minerva(api_key="mk_live_...")

# Resolve — match records to a Minerva PID
mc.api.resolve([{"record_id": "1", "first_name": "Jane", "last_name": "Doe",
                 "emails": ["[e-mail]"]}])

# Enrich — full profiles (up to 500 records per call)
resp = mc.api.enrich(
    [{"record_id": "1", "linkedin_url": "https://www.linkedin.com/in/example"}],
    match_condition_fields=["linkedin_url"],   # only count it a match if a LinkedIn URL is on file
)
for r in resp.results:
    print(r.record_id, r.is_match, r.minerva_pid, r.match_score)

# Tabular output
resp.to_df()            # pandas DataFrame   (needs [pandas])
resp.to_csv("out.csv")  # write a CSV
resp.to_dicts()         # list[dict]

---

Validate before you call — dry_run

Every input-bearing method takes dry_run=True. It validates your input locally and returns the exact request that would be sent — without touching the network. Invalid input raises MinervaValidationError immediately, with a precise field message.

from minerva import Minerva, MinervaValidationError

mc = Minerva()

req = mc.api.enrich(records, match_condition_fields=["linkedin_url"], dry_run=True)
# -> EnrichRequest (nothing sent). Inspect req.model_dump() to see the payload.

try:
    mc.api.enrich([], dry_run=True)     # 0 records — must be at least 1
except MinervaValidationError as e:
    print("caught before any API call:", e)

Great for checking a batch is well-formed (record limits, allowed match_condition_fields, record shape, …) before spending a call.

---

What you can do

Namespace	Highlights
mc.api	resolve, enrich, get_li_contact_info, validate_emails, infer_record_country, call
mc.usage	tallies() — your per-endpoint API usage
mc.status	health() — unauthenticated liveness probe for the API
mc.io	enrich_from_sheet · resolve_from_sheet · enrich_from_excel · resolve_from_excel · read_* / write_* — run the Data API directly off Google Sheets / Excel (extras: [gsheet], [excel])

Every response is a typed model with IDE autocomplete, and the list-shaped ones support .to_df() / .to_csv() / .to_dicts() / .to_table().

---

Liveness — mc.status.health()

Unauthenticated probe of the Minerva endpoints. Never raises — failure is surfaced as ok=False with the cause, so it's safe to call in a polling loop.

mc = Minerva()

# returns {endpoint_name: HealthStatus} — one entry today, more as endpoints come online
report = mc.status.health()

for name, h in report.items():
    if not h.ok:
        print(f"{name} is down: {h.error} (status_code={h.status_code})")
    else:
        print(f"{name} is up — {h.latency_ms:.0f} ms")

# probe a specific endpoint
mc.status.health(endpoints="api")          # -> {"api": HealthStatus(...)}
mc.status.health(endpoints=["api"])        # same, list form

Each HealthStatus carries ok, latency_ms, status_code, status (server-side verdict, e.g. "ok"), message (optional server detail), and error (SDK-side description of why ok=False). Works without an API key — the probe is unauthenticated.

---

Spreadsheets — mc.io

Run the Data API directly off a Google Sheet or Excel workbook, and write results back the same way. Each format is gated on an optional extra so the base wheel stays small.

pip install "minerva-sdk[gsheet]"   # Google Sheets
pip install "minerva-sdk[excel]"    # .xlsx

# The sheet id is the long string between `/d/` and `/edit` in the URL
SHEET_ID = "<paste-your-google-sheet-id-here>"
CREDS    = "/path/to/service-account.json"   # or a gspread.Client / dict / google Credentials

# Read sheet → enrich → write results to a different tab
resp = mc.io.enrich_from_sheet(
    SHEET_ID,
    credentials=CREDS,
    sheet_name="Customers",
    match_condition_fields=["linkedin_url"],
)

resp.to_sheet(
    SHEET_ID,
    credentials=CREDS,
    sheet_name="Enriched",
)

Excel works the same way:

resp = mc.io.enrich_from_excel("customers.xlsx", sheet_name="Sheet1")
resp.to_excel("enriched.xlsx")

Conventions:

• The first row of the sheet is the header. Column names map 1:1 to enrich fields (record_id, linkedin_url, first_name, emails, …). Use field_mapping={"customer_id": "record_id"} for renames.
• Rows above the 500-per-request limit auto-chunk; results are merged into one EnrichResponse / ResolveResponse.
• Google auth: pass a path to a service-account JSON, a dict, a built google.oauth2 Credentials, or a gspread.Client. Or set GOOGLE_APPLICATION_CREDENTIALS and skip the kwarg.
• Errors mirror the rest of the SDK: 401/403 → MinervaAuthError, 404 → MinervaAPIError(status_code=404), malformed sheet → MinervaValidationError.

---

Custom / tailored endpoints — mc.api.call

For client-specific routes (preview endpoints, partner integrations, paths Minerva built just for your org) on the Data API, use the generic mc.api.call:

result = mc.api.call("POST", "/v2/acme/lookup", json={"record_id": "abc"})

Same x-api-key auth, same error mapping, same rate-limit handling as the typed methods — the difference is the SDK doesn't know the response schema, so you get back the raw parsed JSON. The server enforces entitlement; callers without it see a 403 → MinervaAuthError.

---

Error handling

All errors derive from MinervaError:

from minerva import (
    MinervaValidationError,  # bad input — raised locally, before the call
    MinervaAuthError,        # 401/403 — bad key, not entitled
    MinervaRateLimitError,   # 429 — has .retry_after
    MinervaAPIError,         # other 4xx/5xx — has .status_code and .api_request_id
)

try:
    mc.api.enrich(records)
except MinervaRateLimitError as e:
    time.sleep(e.retry_after or 1)
except MinervaAPIError as e:
    print("request failed:", e.api_request_id)   # quote this to support

Responses are forward-compatible: new fields the API adds won't break an older client.

---

Python support

3.11, 3.12, 3.13, 3.14. Fully type-annotated (ships py.typed).

License

MIT © Minerva Data.