Skip to main content

Python SDK

The stable Python SDK is webhook-first for async workflows and ready for production use today, with psychometrics as the additional stable sync workflow.

Status

The Python package is shipped and supported today. This section covers the current public Python path for install, report creation, matching, and verified webhook consumption.

Stable surface today​

  • package name: mappa-conduit
  • import surface: conduit
  • Python version: 3.12+
  • conduit.reports.create(...)
  • conduit.reports.get(...)
  • conduit.psychometrics.create(...)
  • conduit.psychometrics.get(...)
  • conduit.matching.create(...)
  • conduit.matching.get(...)
  • conduit.webhooks.verify_signature(...)
  • conduit.webhooks.parse_event(...)
  • advanced primitives under conduit.primitives.entities, conduit.primitives.media, and conduit.primitives.jobs
  1. Install mappa-conduit and create a server-side Conduit(api_key=...) client.
  2. Create report or matching jobs with snake_case request dictionaries.
  3. Pass a webhook URL for production completion.
  4. Verify the raw webhook body before parsing the event.
  5. Use conduit.psychometrics.create(...) when you want the direct sync trait payload instead of an async report.
  6. Use receipt.handle.wait() or receipt.handle.stream() only for local scripts, tests, or controlled backoffice flows.

Quick example​

from conduit import Conduit

conduit = Conduit(api_key="sk_...")

receipt = conduit.reports.create(
    source={"url": "https://storage.example.com/call.wav"},
    output={"template": "sales_playbook"},
    target={"strategy": "dominant"},
    webhook={"url": "https://your-app.com/webhooks/conduit"},
    idempotency_key="call-42",
)

print(receipt.job_id, receipt.status)

Psychometrics example​

result = conduit.psychometrics.create(
    source={"path": "recordings/demo-call.wav"},
    target={"strategy": "magic_hint", "hint": "the candidate"},
)

print(result.analysis_id, result.psychometrics["conscientiousness"])

Psychometrics stays narrow on purpose: accepted sources are file, url, and path, and accepted targets are dominant or magic_hint.

Documentation​

Notes​

  • Public request dictionaries use snake_case keys like media_id, entity_id, template_params, and time_range.
  • reports is the default integration path for one-speaker analysis.
  • matching is also stable for closed-context comparison flows.
  • Use the REST API directly if you need an endpoint that is not exposed by the shipped SDK surface yet.

Next steps​