ZeticMLangeDecisionModel
API reference for managed Decision inference on iOS.
This page describes the API planned for ZeticMLange iOS 1.13.0.
ZeticMLangeDecisionModel loads the Decision package selected for the device from the Melange registry. Build a request from structured state and named questions, then call evaluate(_:) to receive typed answers.
Import
import ZeticMLangeLoad a managed Decision model
The managed initializer resolves the model by its registry name and uses backend selection to choose a package for the current device. version: nil uses the model's default version.
public convenience init(
personalKey: String,
name: String,
version: Int? = nil,
modelMode: DecisionModelMode = .RUN_AUTO,
cacheHandlingPolicy: ModelCacheHandlingPolicy = .REMOVE_OVERLAPPING,
initOption: DecisionInitOption = .defaults,
onDownload: ((Float) -> Void)? = nil
) async throws| Parameter | Description |
|---|---|
personalKey | Personal key used to access the model. |
name | Model name in account_name/project_name format. |
version | Version to load. nil uses the model's default version. |
modelMode | Package selection preference: .RUN_AUTO, .RUN_SPEED, or .RUN_ACCURACY. |
cacheHandlingPolicy | Managed artifact cache policy. Defaults to .REMOVE_OVERLAPPING. |
initOption | Decision initialization options. The backend-selected package supplies the run configuration. |
onDownload | Optional download progress callback from 0.0 to 1.0. |
DecisionInitOption exposes the per-request context setting:
public struct DecisionInitOption {
public let nCtx: Int32
public init(nCtx: Int32 = 0) throws
public static let defaults: DecisionInitOption
}nCtx: 0 uses the selected package's context setting. An explicit value such as 2048 is a caller setting for that model load; the supported request length is reported by model.capabilities.maxSequenceLength.
Loading and evaluation perform model I/O and inference. Run them away from the main thread. The following example keeps the model and its request on a detached task:
let evaluation = Task.detached(priority: .userInitiated) {
let model = try await ZeticMLangeDecisionModel(
personalKey: PERSONAL_KEY,
name: "account_name/project_name",
modelMode: .RUN_AUTO,
initOption: try DecisionInitOption(nCtx: 2048)
)
defer { model.close() }
let request = ZeticMLangeDecisionRequest(
state: .object([
"message": .string("I was charged twice for my order.")
]),
questions: [
"is_refund_request": .noul(
ZeticMLangeNoulQuestion(instructions: "Is this a refund request?")
)
]
)
let result = try model.evaluate(request)
if case let .noul(probability)? = result.answers["is_refund_request"] {
print("Probability true: \(probability)")
}
}
try await evaluation.value2048 is the context value used in this example. It does not declare a fixed context limit for every model. Use the loaded model's capabilities.maxSequenceLength and keep each request within the supported sequence length.
Build a request
A request contains a JSON-like state, an ordered map of questions, and optionally one media item. Question keys become answer keys. Keep the order of questions and choice criteria intentional because that order is used when constructing the prompt. A dictionary literal preserves the order written; constructing ZeticMLangeDecisionOrderedMap from a Swift Dictionary sorts the keys.
let request = ZeticMLangeDecisionRequest(
state: .object([
"ticket": .object([
"subject": .string("Duplicate charge"),
"amount": .number(24.99)
])
]),
questions: [
"route": .choice(ZeticMLangeChoiceQuestion(
instructions: "Choose the best support queue.",
criteria: [
"billing": .string("Payment, invoice, or refund issues"),
"technical": .string("Product faults or setup issues")
]
)),
"urgency": .score(ZeticMLangeScoreQuestion(
instructions: "Rate urgency from low to high.",
criteria: [.string("low"), .string("normal"), .string("high")]
))
]
)
let result = try model.evaluate(request)ZeticMLangeDecisionValue supports strings, finite numbers, booleans, ordered objects, arrays, and null. Question types are:
| Type | Request value | Result |
|---|---|---|
| NOUL | ZeticMLangeNoulQuestion | .noul(noul:); noul is the probability of true. |
| Choice | ZeticMLangeChoiceQuestion with named criteria | .choice(choice:confidence:probabilities:). |
| Score | ZeticMLangeScoreQuestion with ordered criteria | .score(score:confidence:legend:probabilities:). |
For the llama.cpp D1 models, a choice or score confidence is the probability assigned to the answer, and score is the median criterion. Other engines report the expected criterion for score and a confidence from 0 (uniform) to 1 (certain). Do not compare these fields across engines as though they had identical semantics.
Optional image or audio input
Check model.capabilities before attaching media. Support depends on the package selected for the device. If the selected model does not support the requested modality, evaluate(_:) throws an error.
let image = try ZeticMLangeDecisionImage(
rgb: packedRGB,
width: imageWidth,
height: imageHeight
)
let imageRequest = ZeticMLangeDecisionRequest(
state: .object(["task": .string("Read the label")]),
questions: [
"label": .noul(ZeticMLangeNoulQuestion(instructions: "Is the label readable?"))
],
media: .image(image)
)
let audio = try ZeticMLangeDecisionAudio(samples: monoPCM16kHz, sampleRateHz: 16_000)
let audioRequest = ZeticMLangeDecisionRequest(
state: .object(["task": .string("Classify the recording")]),
questions: [
"contains_speech": .noul(ZeticMLangeNoulQuestion(instructions: "Does the audio contain speech?"))
],
media: .audio(audio)
)Image bytes must be packed row-major RGB UInt8 with exactly width * height * 3 values. Decision audio uses mono float samples at exactly 16 kHz. A request accepts one optional image or audio value; the API does not combine both media types in one request.
Read answers and usage
answers is keyed by the question names in the request. Match the enum case before reading an answer's associated values. usage can be nil when the selected engine does not report per-request accounting.
if case let .choice(value, confidence, probabilities)? = result.answers["route"] {
print("Selected route: \(value), confidence: \(confidence)")
print(probabilities)
}
if let usage = result.usage {
print("Input tokens: \(usage.inputTokens)")
print("Preprocess: \(usage.preprocessMs) ms")
print("Encoder: \(usage.encoderMs) ms")
print("Model: \(usage.trunkMs) ms")
}ZeticMLangeDecisionUsage reports input-token count, whether input was truncated, preprocessing time, encoder time, and model time. Timing fields are available only when the selected engine reports them.
Capabilities and lifecycle
model.capabilities.imageSupported
model.capabilities.audioSupported
model.capabilities.maxImages
model.capabilities.maxAudio
model.capabilities.maxSequenceLength
model.close()
model.isClosedCapability values describe the package opened on this device; they are not promises that every Decision model or backend supports the same media. close() releases the model and its managed cache lease. Call it when the model is no longer needed.
The optimized iOS D1-2B and D1-Omni-2B runtime lane documented for this release accepts text requests. Do not infer image or audio support from the model name; use the loaded model's capabilities for the selected package.