Ask questions

Use client.models.list() with the same API key and base URL to check which models are available before selecting one.

client.system_one(state, questions, **options)

It returns a SystemOneResponse. A decision is billed per input token and only when it returns 200, so the SDK's retries never bill twice.

from nace_sdk import Choice, NaceClient, Noul, Score

with NaceClient() as client:
    result = client.system_one(
        state="I was charged twice for my March invoice.",
        questions={
            "wants_refund": Noul(instructions="Is the customer asking for a refund?"),
            "topic": Choice(instructions="Which topic is it?", criteria={"billing": None, "shipping": None, "other": None}),
            "urgency": Score(instructions="How urgent is it?", criteria=["low", "medium", "high"]),
        },
    )

print(result.nouls["wants_refund"].noul)
print(result.choices["topic"].choice, result.choices["topic"].confidence)
print(result.scores["urgency"].score, result.usage.input_tokens, result.request_id)

Question typesCopy Anchor Link

These names are type aliases, for annotating your own code:

questions = {
    "wants_refund": {"type": "noul", "instructions": "Is the customer asking for a refund?"},
    "is_spam": Noul(criteria={"true": "Unsolicited advertising", "false": "A real customer message"}),
}

The SDK checks the questions before it sends anything and raises NaceError for no questions or more than 512, a Noul with neither instructions nor a described outcome, a Choice whose criteria isn't a nonempty mapping, a Score with no criteria, and a dictionary without a nonempty type (or, for choice and score, without criteria). An unknown field on a question object raises pydantic.ValidationError. Unset instructions and criteria are left out of the request.

Read the responseCopy Anchor Link

SystemOneResponse:

request_id and raw_http_response aren't fields, so model_dump() leaves them out. Every response type has them, and a from_http_response(response) class method that builds one from an httpx.Response you fetched yourself, raising the same errors as a call.

Answer is the union of the three, told apart by type. Score probabilities are keyed by int, so read them as result.scores["urgency"].probabilities[2]. legend is always a tuple of labels, whichever shape the server sent: a legend keyed by level, which Drex sends when a request asks for X-Nace-Legend: object or comes from a TypeSafe client, is read as the same tuple. The SDK doesn't send that header. An answer of a type this SDK version doesn't know is dropped with a warning on the nace_sdk logger; it is still in raw_http_response. See Reading answers.

Parse into your own modelCopy Anchor Link

Subclass SystemOneResponse and declare an answer per question name. The SDK copies each declared answer from answers into its field (answers still has it too), and you keep request_id and raw_http_response:

from nace_sdk import Choice, ChoiceAnswer, NaceClient, Noul, NoulAnswer, SystemOneResponse


class Ticket(SystemOneResponse):
    wants_refund: NoulAnswer
    topic: ChoiceAnswer


with NaceClient() as client:
    ticket = client.system_one(
        state="I was charged twice for my March invoice.",
        questions={
            "wants_refund": Noul(instructions="Is the customer asking for a refund?"),
            "topic": Choice(criteria={"billing": None, "shipping": None}),
        },
        response_model=Ticket,
    )

print(ticket.wants_refund.noul, ticket.topic.choice, ticket.request_id)

Any other pydantic.BaseModel is validated against the raw JSON body and has no request_id or raw_http_response. A body that doesn't match raises NaceAPIResponseValidationError.

ImagesCopy Anchor Link

The served Drex Max models read images. Retired ids that resolve to Max v1.1 accept images too. Pass them in images and refer to them as "Image 1", "Image 2" and so on in the state or the instructions; media inside state or questions returns 422. Each entry, an ImageInput, is one of:

• an UploadedFile that client.documents.upload returned (upload without workspace_id), or the WorkspaceFileSource for one. It is sent as a workspace_file reference and doesn't count toward the 4 MiB request body, so use it for anything but small images;
• a standard base64 string, or a data URL such as data:image/jpeg;base64,...;
• the wire's own {"type": "workspace_file", "workspace_id": ..., "file_id": ...} dictionary.

ImageInput is str | UploadedFile | WorkspaceFileSource | Mapping[str, str]. Any other entry, a string that is neither base64 nor a data URL (such as a file path: pass image_input(path) instead), or a single string in place of the list, raises NaceError before sending. A file in one of your Workspaces or in another account's returns 422, and so does images with any model that does not support images. Images are PNG, JPEG or WebP, up to 8 per request, 16 MiB each and 32 MiB in all. Their tokens are in usage.image_tokens, already counted in input_tokens.

image_input(content), from nace_sdk:

It returns a str | dict[str, str] for images. Content that isn't a PNG, JPEG or WebP image, or is over 16 MiB, raises NaceError. An inline image counts toward the 4 MiB request body, base64 expansion included.

from nace_sdk import NaceClient, Noul, image_input

with NaceClient() as client:
    receipt = client.documents.upload("receipt.jpg")
    result = client.system_one(
        state="Image 1 is a scanned receipt. Image 2 is the shop's logo.",
        questions={"same_shop": Noul(instructions="Was the receipt in Image 1 issued by the shop whose logo is Image 2?")},
        model="drex-max",
        images=[receipt, image_input("logo.png")],
    )

print(result.nouls["same_shop"].noul, result.usage.image_tokens)

OpenAI-compatible decisionsCopy Anchor Link

client.decisions.create(*, input, questions, model=None, safety_identifier=None, prompt_cache_key=None, prompt_cache_options=None, retry=None, timeout=None, extra_headers=None, extra_body=None, response_model=None)

It returns a Decision. This is system_one in the wire shape of OpenAI's Decisions API, which POST /v1/decisions serves: answers come back in question order rather than by name, and nothing is checked before sending, so a bad question is the server's 422, with the field at fault in the error's param. The same models, funding, limits and billing apply.

from nace_sdk import NaceClient

with NaceClient() as client:
    decision = client.decisions.create(
        input="I was charged twice for my March invoice.",
        questions=[
            {"type": "predicate", "name": "wants_refund", "instructions": "Is the customer asking for a refund?"},
            {"type": "choice", "name": "refund", "instructions": "Refund?", "choices": [{"value": True}, {"value": False}, {"value": "partial"}]},
        ],
    )

wants_refund, refund = decision.answers
print(wants_refund.probability, refund.choice, decision.usage.input_tokens, decision.request_id)

The request types are TypedDicts, so the dictionaries an OpenAI client builds type-check as they are:

AsyncNaceClient.decisions is an AsyncDecisions with the same create, awaited.

List modelsCopy Anchor Link

client.models.list(**options) takes retry, timeout and extra_headers, and returns a ListModelsResponse. It works at any balance and is free, so it doubles as a key check.

with NaceClient() as client:
    print([model.name for model in client.models.list().models])

See Models.