Ask questions

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]. 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

Drex Max (drex-max) is the only model that reads images. 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, 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 another account's returns 422, and so does images with any model but drex-max. 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)

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.