Python SDK

The same verified-output API, with a Python client that mirrors the TypeScript SDK (snake_case fields). Zero runtime dependencies — stdlib only. Python 3.8+.

pip install maxmodel

Quickstart

from maxmodel import MaxModel
 
mx = MaxModel(api_key="sk-...")  # your maxmodel.com gateway key
 
out = mx.verified.create(
    model="gpt-5.5-pro",
    messages=[{"role": "user", "content": "What is our refund policy?"}],
    sources=[{"id": "refunds.md", "text": "Full refunds within 30 days. No refunds after 30 days."}],
)
 
print(out.text)                 # grounded answer with inline [refunds.md] markers
for c in out.citations:
    print(f'✓ "{c.quote}" — {c.source} {c.range}')   # verbatim, traced to your source
for u in out.unsupported:
    print(f'⚠ dropped ({u.reason}): "{u.claim}"')     # hallucinations caught, not shipped

Client

MaxModel(api_key, *, base_url="https://api.maxmodel.com", timeout=60.0)

base_url — override for self-host / testing.
timeout — seconds, default 120. Raise for large eval batches; lower latency with a faster model. Reasoning models like gpt-5.5-pro can take 60–90s per call.

`mx.verified.create(...) -> VerifiedResult`

arg	type	default
`model`	`str`	—
`messages`	`list[dict]` (`{"role","content"}`)	—
`sources`	`list[dict]` (`{"id","text"}`)	—
`mode`	`"strict" \| "lenient"`	`"strict"`
`min_coverage`	`float`	`0.0` (off)
`retry`	`int`	`0`
`check_numbers`	`bool \| str`	`False` (`True`/`"source"` = anywhere; `"row"` = same table cell/line)
`allow_ungrounded`	`bool`	`False`
`temperature`	`float \| None`	`None`
`max_tokens`	`int \| None`	`None`

VerifiedResult is a dataclass: id, model, text, citations, unsupported, coverage, abstained, grounded, usage. Citation = claim, quote, source, range(tuple); Unsupported = claim, reason; Usage = prompt_tokens, completion_tokens, total_tokens, model_calls.

`mx.verified.eval(...) -> EvalResult`

Deterministic groundedness eval over many cases (no LLM judge) — see Eval.

r = mx.verified.eval(model="gpt-5.5-pro", cases=[
    {"messages": [{"role": "user", "content": "refund window?"}],
     "sources": [{"id": "r.md", "text": "Full refunds within 30 days."}]},
])
r.aggregate.coverage_mean   # 1.0
r.aggregate.unsupported_rate
r.model_calls               # a dataset run = many model calls

See verified.create for full field semantics and How verification works for the guarantee.

Errors

Typed and catchable — same taxonomy as the TS SDK:

from maxmodel import RateLimitError, NoSourcesError, MaxModelError
 
try:
    out = mx.verified.create(...)
except NoSourcesError:
    ...   # you forgot sources, or set allow_ungrounded=True
except RateLimitError:
    ...   # back off and retry
except MaxModelError as e:
    print(e.type, e.status)   # e.g. "invalid_key", 401

MaxModelError is the base; subclasses: AuthError (401), QuotaError (402), RateLimitError (429), NoSourcesError (400), ExtractionError (502), GatewayError (5xx).

OpenAI-compatible passthrough

r = mx.chat.completions.create(
    model="gpt-5.5-pro",
    messages=[{"role": "user", "content": "Hello"}],
)
print(r["choices"][0]["message"]["content"])

Privacy & data Integrations