Advanced Features - Liquid Docs

This page consolidates the lower-level reference symbols used by Constrained Generation and Function Calling. Most apps don’t touch these directly — the high-level pages cover the usual flows. Reach here when you need to inspect schemas, build options programmatically, or wire a custom parser.

`GenerationOptions`

Per-request controls. Leave any field as null / nil to fall back to the manifest defaults.

Swift (iOS / macOS)
Kotlin (all platforms)

GenerationOptions is a Kotlin data class bridged into Swift. Kotlin parameter defaults don’t survive the ObjC bridge, so the canonical Swift idiom is the parameterless init plus chained .with(...) builders:

public class GenerationOptions {
  public var temperature: Float?
  public var topP: Float?
  public var minP: Float?
  public var repetitionPenalty: Float?
  public var topK: Int32?
  public var rngSeed: Int64?
  public var jsonSchemaConstraint: String?
  public var functionCallParser: LeapFunctionCallParser?
  public var injectSchemaIntoPrompt: Bool        // default true
  public var maxTokens: Int32?
  public var inlineThinkingTags: Bool            // default false
  public var enableThinking: Bool                // default false
  public var extras: String?

  public convenience init()
}

Builder-style chaining (v0.10.0+):

let opts = GenerationOptions()
    .with(temperature: 0.3)
    .with(minP: 0.15)
    .with(repetitionPenalty: 1.05)
    .with(jsonSchema: CityFact.jsonSchema())   // or any other schema string

For the legacy compat-class path (Leap.load(...) flows), GenerationOptionsCompat additionally exposes setResponseFormat(jsonSchema: String).

data class GenerationOptions(
    var temperature: Float? = null,
    var topP: Float? = null,
    var minP: Float? = null,
    var repetitionPenalty: Float? = null,
    var topK: Int? = null,
    var rngSeed: Long? = null,
    var jsonSchemaConstraint: String? = null,
    var functionCallParser: LeapFunctionCallParser? = LFMFunctionCallParser(),
    var injectSchemaIntoPrompt: Boolean = true,
    var maxTokens: Int? = null,
    var inlineThinkingTags: Boolean = false,
    var enableThinking: Boolean = false,
    var extras: String? = null,
) {
    inline fun <reified T : Any> setResponseFormatType()

    companion object {
        fun build(buildAction: GenerationOptions.() -> Unit): GenerationOptions
    }
}

Sampling fields — temperature, topP, minP, topK, and repetitionPenalty. Use the model bundle’s recommended values; arbitrary defaults from generic tutorials usually underperform.
rngSeed — deterministic sampling seed for tests and reproducible runs.
maxTokens — maximum completion tokens to generate. Prompt tokens do not count toward this cap.
jsonSchemaConstraint — JSON Schema string for constrained generation. Use the higher-level helpers — Swift options.with(jsonSchema: T.jsonSchema()) / Kotlin setResponseFormatType<T>() — instead of writing the schema by hand.
injectSchemaIntoPrompt — when true (default), the schema is also appended to the system message for semantic guidance. Set false to use only the structural constraint.
functionCallParser — LFMFunctionCallParser (default), HermesFunctionCallParser(), or null/nil to disable parsing and surface raw tool-call text in Chunks.
enableThinking / inlineThinkingTags — reasoning-mode controls for models that emit <think> content.
extras — backend-specific JSON payload.

Constrained generation utilities

Swift (iOS / macOS)
Kotlin (all platforms)

// Compile-time schema synthesis lives in the @Generatable macro.
// For ad-hoc inspection (ships in the LeapSDKMacros SPM product):
import LeapSDKMacros

let schemaString = JSONSchemaGenerator.getJSONSchema(for: CityFact.self)

JSONSchemaGenerator.getJSONSchema(for:) is non-throwing — it forwards to the jsonSchema() method that the @Generatable macro adds to the type, so the schema is produced at compile time. Useful when embedding the schema in the prompt itself, or when you want to debug the schema the model is being constrained against.See Constrained Generation for the full @Generatable / @Guide macro reference.

`JSONSchemaGenerator`

package ai.liquid.leap.structuredoutput

object JSONSchemaGenerator {
  @Throws(LeapGeneratableSchematizationException::class)
  fun <T : Any> getJSONSchema(serializer: KSerializer<T>, indentSpaces: Int? = null): String

  @Throws(LeapGeneratableSchematizationException::class)
  inline fun <reified T : Any> getJSONSchema(indentSpaces: Int? = null): String
}

serializer — the KSerializer<T> for a data class annotated with @Generatable and @Serializable. The reified-T overload calls serializer<T>() for you.
indentSpaces — non-null formats the output with the given indent (pretty-print).

Throws LeapGeneratableSchematizationException if the class can’t be translated.

`GeneratableFactory`

import kotlinx.serialization.json.JsonObject

object GeneratableFactory {
  @Throws(LeapGeneratableDeserializationException::class)
  fun <T : Any> createFromJsonObject(jsonObject: JsonObject, serializer: KSerializer<T>): T

  @Throws(LeapGeneratableDeserializationException::class)
  inline fun <reified T : Any> createFromJsonObject(jsonObject: JsonObject): T
}

Note the camelCase Json in the method name and the kotlinx.serialization.json.JsonObject argument (not org.json.JSONObject). The reified-T overload is a convenience when the target type can be inferred from context.

Annotations

package ai.liquid.leap.structuredoutput

@Target(AnnotationTarget.CLASS)
annotation class Generatable(val description: String)

@Target(AnnotationTarget.PROPERTY)
annotation class Guide(val description: String)

Function-calling type reference

The full surface is documented in Function Calling; the type signatures here are the at-a-glance reference.

Swift (iOS / macOS)
Kotlin (all platforms)

public struct LeapFunction {
  public let name: String
  public let description: String
  public let parameters: [LeapFunctionParameter]
}

public struct LeapFunctionParameter {
  public let name: String
  public let type: LeapFunctionParameterType
  public let description: String
  public let optional: Bool
}

public indirect enum LeapFunctionParameterType: Codable, Equatable {
  case string(StringType)
  case number(NumberType)
  case integer(IntegerType)
  case boolean(BooleanType)
  case array(ArrayType)
  case object(ObjectType)
  case null(NullType)
}

public struct LeapFunctionCall {
  public let name: String
  public let arguments: [String: Any?]
}

Type wrappers (StringType, NumberType, etc.) carry per-type metadata like enumValues for restricting valid inputs and description for prompt-time hints (used when the type is nested inside an array or object).

data class LeapFunction(
    val name: String,
    val description: String,
    val parameters: List<LeapFunctionParameter>,
)

data class LeapFunctionParameter(
    val name: String,
    val type: LeapFunctionParameterType,
    val description: String,
    val optional: Boolean = false,
)

sealed class LeapFunctionParameterType(typeDescription: kotlin.String? = null) {
  var description: kotlin.String? = typeDescription
    private set

  // Nested class names carry a `Leap` prefix so they don't shadow `kotlin.String`,
  // `kotlin.Number`, etc. at use sites.
  class LeapStr(val enumValues: List<kotlin.String>? = null, description: kotlin.String? = null) : LeapFunctionParameterType(description)
  class LeapNum(val enumValues: List<kotlin.Number>? = null, description: kotlin.String? = null) : LeapFunctionParameterType(description)
  class LeapInt(val enumValues: List<Int>? = null, description: kotlin.String? = null) : LeapFunctionParameterType(description)
  class LeapBool(description: kotlin.String? = null) : LeapFunctionParameterType(description)
  class LeapNull : LeapFunctionParameterType()
  class LeapArr(val itemType: LeapFunctionParameterType, description: kotlin.String? = null) : LeapFunctionParameterType(description)
  class LeapObj(
    val properties: Map<kotlin.String, LeapFunctionParameterType>,
    val required: List<kotlin.String> = listOf(),
    description: kotlin.String? = null,
  ) : LeapFunctionParameterType(description)
}

data class LeapFunctionCall(
    val name: String,
    val arguments: Map<String, Any?>,
)

Parsers

Two parser implementations ship with the SDK on every platform:

LFMFunctionCallParser — default. Handles Liquid Foundation Model (LFM2) Pythonic-style control tokens (<|tool_call_start|> / <|tool_call_end|>).
HermesFunctionCallParser — Qwen3 and other models using the Hermes function-calling format.

Subclass LeapFunctionCallParser (Kotlin abstract class, bridged to Swift as a class with the same name) to add support for a new format.

Prompt token budgeting

getPromptTokensSize(messages:, addBosToken:) is declared directly on ModelRunner — no cast required. Useful when you need to estimate context usage before sending a long request.

Swift (iOS / macOS)
Kotlin (all platforms)

let count = try await runner.getPromptTokensSize(messages: history, addBosToken: true)
print("Prompt would consume \(count) tokens")

val count = runner.getPromptTokensSize(messages = history, addBosToken = true)
println("Prompt would consume $count tokens")

getPromptTokensSize is suspend — call it from a coroutine.

​GenerationOptions

​Constrained generation utilities

​JSONSchemaGenerator

​GeneratableFactory

​Annotations

​Function-calling type reference

​Parsers

​Prompt token budgeting