ModelSession | Drafts Script Reference
Drafts Script Reference
    Preparing search index...

    Class ModelSession

    Prompt the on-device ModelSession, part of the Foundation Models API introduced in iOS/macOS 27. Requires OS 27 and a device that supports (and has enabled) Apple Intelligence.

    The ModelSession object allows working with both on-device and Private Cloud Compute LLM Models, as well as Claude Sonnet and Opus models.

    For example actions and more details on selection of model modes, see User Guide

    NOTE: Each instance of ModelSession operates as a session, so repeated calls to respond will maintain the context of previous calls – and are cumulatively subject to the token limits.

    Prompting the On-Device LLM

    // create a prompt based on the content of the current draft
    let prompt = draft.processTemplate("[[draft]]")

    // create model instance and submit prompt
    let lm = new ModelSession()
    lm.mode = "onDevice" // or "pcc" for Private Cloud Compute

    let response = lm.respond(prompt)

    if (!response) { // handle failure
    	  alert(lm.lastError)
    	  context.fail()
    }
    else { // update draft to include response
    	  editor.setText(`${prompt}

    ===

    ${response}`)
    }

    Configuration

    instructions: string[]

    Array of text instructions to include in session to guide prompt evaluation.

    mode: modelSessionMode

    Model mode. Controls active model for the session. Default: onDevice

    reasoningLevel: string

    A reasoning level supported by the current model in use for the session. The on-device model does not support levels, pcc mode, for example, supports "light", "moderate", and "deep"

    temperature: number

    Value between 0.0 and 1.0 indicating the temperature to assign the session. Higher values allow the model to be more creative, but less predictable in generating responses.

    toolSets: toolSet[]

    Enable or disable tools sets to extend functionality of the model. Only enable tool sets you expect to use, as additional ones impact your token usage.

    Default: ["drafts", "editor"]

    • Add text instruction for the model to the instructions array.

      Parameters

      • instruction: string

      Returns null

    • Activate a tool set for the session.

      Parameters

      Returns null

    Constructor

    Modes

    isAvailable: boolean

    Check whether ModelSession, as configured, is available for use on the current device. Allows graceful fall back on devices that do not support Foundation Models, or are running older OS versions.

    • Check availability of ModelSession a model session mode on the current device. Allows graceful fall back on devices that do not support Foundation Models, or are running older OS versions.

      Parameters

      Returns boolean

    Other

    lastError?: string

    If a previous function returned an error, the error description will be available in this property

    transcript: string

    A JSON formatted output of the session's current transcript of prompts and responses. Can be useful in troubleshooting.

    • Get a response from the on-device language model.

      Parameters

      • prompt: string

        Text prompt to submit to the model.

      • Optionalschema: ModelSessionSchema

        Optional schema object to get responses in a structured format. If schema is not passed, responses will be in string format.

      Returns object

    Configuration
    Constructor
    Modes
    Other