Melange
API ReferenceiOS

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 ZeticMLange

Load 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
ParameterDescription
personalKeyPersonal key used to access the model.
nameModel name in account_name/project_name format.
versionVersion to load. nil uses the model's default version.
modelModePackage selection preference: .RUN_AUTO, .RUN_SPEED, or .RUN_ACCURACY.
cacheHandlingPolicyManaged artifact cache policy. Defaults to .REMOVE_OVERLAPPING.
initOptionDecision initialization options. The backend-selected package supplies the run configuration.
onDownloadOptional 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.value

2048 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:

TypeRequest valueResult
NOULZeticMLangeNoulQuestion.noul(noul:); noul is the probability of true.
ChoiceZeticMLangeChoiceQuestion with named criteria.choice(choice:confidence:probabilities:).
ScoreZeticMLangeScoreQuestion 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.isClosed

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

On this page