Metadata-Version: 2.4
Name: maxmodel
Version: 0.1.0
Summary: The AI gateway with verified output. One API for every model, with verbatim citations and hallucinations stripped.
Project-URL: Homepage, https://docs.maxmodel.com
Project-URL: Documentation, https://docs.maxmodel.com
Author: MaxModel
License: MIT
License-File: LICENSE
Keywords: ai,citations,gateway,hallucination,llm,openai,rag,verified
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# maxmodel (Python)

The AI gateway with **verified output**. One API for every model, with a `verified` mode
that returns answers grounded in *your* sources: verbatim citations, hallucinations
stripped, checked by deterministic code (not an LLM judge).

```bash
pip install maxmodel
```

```python
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
```

## Why it's different

The grounding check is **deterministic code**: every cited quote must appear
character-for-character in a source you supplied, or the claim is dropped. No "LLM judging
an LLM".

## API

### `MaxModel(api_key, *, base_url=..., timeout=60.0)`
- `base_url` defaults to `https://api.maxmodel.com`; override for self-host/testing.

### `mx.verified.create(...) -> VerifiedResult`
| arg | type | default |
|---|---|---|
| `model` | `str` | — |
| `messages` | `list[dict]` | — |
| `sources` | `list[dict]` (`{"id","text"}`) | — |
| `mode` | `"strict" \| "lenient"` | `"strict"` |
| `allow_ungrounded` | `bool` | `False` |
| `temperature` | `float \| None` | `None` |
| `max_tokens` | `int \| None` | `None` |

`VerifiedResult` (dataclass): `id, model, text, citations, unsupported, grounded, usage`.

### `mx.chat.completions.create(**params) -> dict`
OpenAI-compatible passthrough.

## Errors

Typed and catchable: `MaxModelError` (base) with `AuthError` (401), `QuotaError` (402),
`RateLimitError` (429), `NoSourcesError` (400), `ExtractionError` (502), `GatewayError` (5xx).
Each carries `.type` and `.status`.

```python
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)
```

Zero runtime dependencies (stdlib only). Python 3.8+.
Docs: https://docs.maxmodel.com
