Modaic Python SDK

The official, HTTP-only Python client for the public Modaic API. It includes matching synchronous and asynchronous clients and never invokes Git or reads or writes repository files.

Install

pip install modaic

Set an API key from https://modaic.dev/settings/keys:

export MODAIC_API_KEY="mdc_..."

Quickstart

from modaic import Modaic

with Modaic() as modaic:
    result = modaic.decisions.create(
        state={
            "ticket": "I was charged twice for order 4832. Please refund one charge."
        },
        model="typesafe/jev-latest",
        questions={
            "needs_refund": {
                "type": "noul",
                "instructions": "Should this customer receive a refund?",
                "criteria": {
                    "true": "A duplicate or invalid charge should be refunded.",
                    "false": "The charge is valid or more information is required.",
                },
            },
            "priority": {
                "type": "choice",
                "instructions": "Choose the support priority.",
                "criteria": {
                    "low": "No financial or time-sensitive impact.",
                    "normal": "Routine customer issue.",
                    "high": "Financial impact or an urgent blocker.",
                },
            },
        },
        idempotency_key="ticket-4832-v1",
    )

print(result.answers["priority"])

For a local server, pass the versioned API URL explicitly:

modaic = Modaic(api_key="mdc_...", base_url="http://localhost:3001/v1")

Async

The async client has the same resources and methods:

import asyncio
from modaic import AsyncModaic


async def main() -> None:
    async with AsyncModaic() as modaic:
        models = await modaic.models.list()
        print([model.name for model in models.models])


asyncio.run(main())

Model-bound resources

Models returned by models.create, models.get, and models.update can run decisions directly:

with Modaic() as modaic:
    model = modaic.models.get(workspace="acme", model="support-priority")
    result = model.decisions.create(
        state={"ticket": "Please refund my duplicate charge."},
    )
    examples = model.examples.list(page_size=10)
    batches = model.jobs.batch_decisions.list()
    alignments = model.jobs.alignments.list()

With AsyncModaic, await both calls. The bound method accepts every decision option except model and uses the same client; keep that client open while running decisions. Pass revision to pin a version. model_dump() and model_dump_json() contain only response data. The top-level modaic.decisions.create remains available.

model.examples exposes ingest, list, get, annotate, and list_decisions without a model ID argument. model.jobs.alignments and model.jobs.batch_decisions expose model-bound create and list. Use the top-level job resources to retrieve, wait for, or cancel a job by its ID.

Job progress

Pass progress=True to either job resource's wait() method for a tqdm display:

finished = modaic.batch_decisions.wait(job.id, progress=True)
finished = modaic.alignments.wait(alignment.id, progress=True)

With AsyncModaic, use await with the same option. Progress is off by default. Batch jobs show processed examples and failures; alignment shows its stage and metric-call budget usage, not an overall completion percentage. Updates use the existing polling interval. Timing out stops waiting without cancelling the job.

Resources

Resource	Methods
`decisions`	`create`
`models`	`list`, `create`, `get`, `update`, `delete`
`examples`	`ingest`, `list`, `get`, `annotate`, `list_decisions`
`batch_decisions`	`create`, `list`, `get`, `cancel`, `wait`
`alignments`	`create`, `list`, `get`, `logs`, `cancel`, `wait`

Responses are Pydantic models. Python attributes use snake_case even when the wire format uses camelCase.

Errors

Non-2xx responses raise ModaicAPIError, which exposes status_code, code, request_id, details, and the decoded response body. Network failures raise ModaicConnectionError; request and polling deadlines raise ModaicTimeoutError.

See the complete API documentation at https://docs.modaic.dev.

Release files for modaic 0.47.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for modaic 0.47.0
File	Interpreter	ABI	Platform	Reset
modaic-0.47.0-py3-none-any.whl 14.0 kB Sep 23, 2026	Python 3	none	any	Details

Release files / modaic-0.47.0-py3-none-any.whl

Download URL	modaic-0.47.0-py3-none-any.whl
Size	14.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`2f42793925a8c91ff1fd77e5a76216b938746cad9dc4800af51790a949e4242a`
BLAKE2b-256 checksum How to use checksums	`ee984cffec9b7f863e68814917f417790717dd796938869e3c0001f4e3f60efd`
Upload date	Sep 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/modaic-ai/modaic
Publishing commit: github.com/modaic-ai/modaic/tree/181b3e3e2495bbacd1c0e075120e0a55ce6bc62b

Workflow

Publishing configuration: github.com/modaic-ai/modaic/blob/181b3e3e2495bbacd1c0e075120e0a55ce6bc62b/.github/workflows/python-publish.yml
Publishing logs: github.com/modaic-ai/modaic/actions/runs/35890587030/attempts/1

Artifact

Subject: modaic-0.47.0-py3-none-any.whl
SHA-256 checksum: 2f42793925a8c91ff1fd77e5a76216b938746cad9dc4800af51790a949e4242a Verifying attestations