@swiftbrowser/swift 0.1.0 → 0.3.0

package/Sources/FoundationModels/FoundationModels.swift

@@ -0,0 +1,1098 @@
+// Foundation Models (iOS 26): Apple Intelligence's on-device language
+// model. The browser has no such model to run: Chrome's Prompt API
+// (`LanguageModel`) is offered to extensions and origin trials, not to pages
+// in general, and nothing else answers prompts on the device. So the system
+// model reports what an iPhone without Apple Intelligence reports:
+// `availability` is `.unavailable(.deviceNotEligible)`, `isAvailable` is
+// false, and a session's `respond` and `streamResponse` fail with
+// `GenerationError.assetsUnavailable`. Apps check availability before
+// offering their features (Ice Cubes' composer hides its assistant).
+//
+// The API is complete enough for such apps to compile and run unchanged:
+// sessions with instructions (builders included), prompts, generation
+// options, `Generable` with `@Generable` / `@Guide` (macros of the shim's
+// SwiftDataMacros plugin), `GeneratedContent` with its JSON form, generation
+// schemas and guides, tools, transcripts and response streams.
+
+import Foundation
+import FoundationBridge
+import SwiftUI
+
+// MARK: - The system model
+
+/// The on-device model of Apple Intelligence: unavailable in the browser.
+public final class SystemLanguageModel: Sendable {
+    /// What the model is tuned for.
+    public struct UseCase: Sendable, Hashable {
+        let name: String
+        /// Writing, summarizing, answering.
+        public static let general = UseCase(name: "general")
+        /// Tagging and extracting entities.
+        public static let contentTagging = UseCase(name: "contentTagging")
+    }
+
+    /// The safety filters applied to prompts and responses.
+    public struct Guardrails: Sendable, Hashable {
+        let name: String
+        public static let `default` = Guardrails(name: "default")
+        /// Fewer refusals when transforming the user's own text.
+        public static let permissiveContentTransformations = Guardrails(name: "permissiveContentTransformations")
+    }
+
+    /// Whether the model can be used.
+    public enum Availability: Sendable, Equatable {
+        public enum UnavailableReason: Sendable, Equatable, Hashable {
+            /// The device cannot run Apple Intelligence: the browser's answer.
+            case deviceNotEligible
+            /// Apple Intelligence is turned off.
+            case appleIntelligenceNotEnabled
+            /// The model is still downloading.
+            case modelNotReady
+        }
+        case available
+        case unavailable(UnavailableReason)
+    }
+
+    /// The general-purpose model.
+    public static let `default` = SystemLanguageModel()
+
+    public let useCase: UseCase
+    public let guardrails: Guardrails
+
+    public init(useCase: UseCase = .general, guardrails: Guardrails = .default) {
+        self.useCase = useCase
+        self.guardrails = guardrails
+    }
+
+    /// `.unavailable(.deviceNotEligible)`: there is no on-device model in the browser.
+    public var availability: Availability { .unavailable(.deviceNotEligible) }
+
+    /// False (see `availability`).
+    public var isAvailable: Bool { availability == .available }
+
+    /// No languages: there is no model.
+    public var supportedLanguages: Set<Locale.Language> { [] }
+
+    /// False for every locale: there is no model.
+    public func supportsLocale(_ locale: Locale = Locale.current) -> Bool { false }
+}
+
+// MARK: - Instructions and prompts
+
+/// A value that can be part of a session's instructions.
+public protocol InstructionsRepresentable {
+    var instructionsRepresentation: Instructions { get }
+}
+
+/// What a session's model is told to do, before any prompt.
+public struct Instructions: Sendable, Hashable, InstructionsRepresentable {
+    let text: String
+
+    public init(@InstructionsBuilder _ content: () throws -> Instructions) rethrows {
+        self = try content()
+    }
+
+    public init(_ representable: some InstructionsRepresentable) {
+        self = representable.instructionsRepresentation
+    }
+
+    init(text: String) { self.text = text }
+
+    public var instructionsRepresentation: Instructions { self }
+}
+
+extension String: InstructionsRepresentable {
+    public var instructionsRepresentation: Instructions { Instructions(text: self) }
+}
+
+extension Array: InstructionsRepresentable where Element: InstructionsRepresentable {
+    public var instructionsRepresentation: Instructions {
+        Instructions(text: map(\.instructionsRepresentation.text).joined(separator: "\n"))
+    }
+}
+
+/// Builds instructions from strings and other instructions, one per line.
+@resultBuilder
+public struct InstructionsBuilder {
+    public static func buildExpression(_ expression: some InstructionsRepresentable) -> Instructions {
+        expression.instructionsRepresentation
+    }
+    public static func buildBlock(_ components: Instructions...) -> Instructions {
+        Instructions(text: components.map(\.text).filter { !$0.isEmpty }.joined(separator: "\n"))
+    }
+    public static func buildArray(_ components: [Instructions]) -> Instructions {
+        Instructions(text: components.map(\.text).filter { !$0.isEmpty }.joined(separator: "\n"))
+    }
+    public static func buildEither(first component: Instructions) -> Instructions { component }
+    public static func buildEither(second component: Instructions) -> Instructions { component }
+    public static func buildOptional(_ component: Instructions?) -> Instructions { component ?? Instructions(text: "") }
+    public static func buildLimitedAvailability(_ component: Instructions) -> Instructions { component }
+}
+
+/// A value that can be part of a prompt.
+public protocol PromptRepresentable {
+    var promptRepresentation: Prompt { get }
+}
+
+/// What a session is asked.
+public struct Prompt: Sendable, Hashable, PromptRepresentable {
+    let text: String
+
+    public init(@PromptBuilder _ content: () throws -> Prompt) rethrows {
+        self = try content()
+    }
+
+    public init(_ representable: some PromptRepresentable) {
+        self = representable.promptRepresentation
+    }
+
+    init(text: String) { self.text = text }
+
+    public var promptRepresentation: Prompt { self }
+}
+
+extension String: PromptRepresentable {
+    public var promptRepresentation: Prompt { Prompt(text: self) }
+}
+
+extension Array: PromptRepresentable where Element: PromptRepresentable {
+    public var promptRepresentation: Prompt {
+        Prompt(text: map(\.promptRepresentation.text).joined(separator: "\n"))
+    }
+}
+
+/// Builds a prompt from strings and other prompts, one per line.
+@resultBuilder
+public struct PromptBuilder {
+    public static func buildExpression(_ expression: some PromptRepresentable) -> Prompt {
+        expression.promptRepresentation
+    }
+    public static func buildBlock(_ components: Prompt...) -> Prompt {
+        Prompt(text: components.map(\.text).filter { !$0.isEmpty }.joined(separator: "\n"))
+    }
+    public static func buildArray(_ components: [Prompt]) -> Prompt {
+        Prompt(text: components.map(\.text).filter { !$0.isEmpty }.joined(separator: "\n"))
+    }
+    public static func buildEither(first component: Prompt) -> Prompt { component }
+    public static func buildEither(second component: Prompt) -> Prompt { component }
+    public static func buildOptional(_ component: Prompt?) -> Prompt { component ?? Prompt(text: "") }
+    public static func buildLimitedAvailability(_ component: Prompt) -> Prompt { component }
+}
+
+// MARK: - Options
+
+/// How a response is sampled.
+public struct GenerationOptions: Sendable, Equatable {
+    /// Greedy or random sampling.
+    public struct SamplingMode: Sendable, Equatable {
+        enum Mode: Sendable, Equatable {
+            case greedy
+            case top(Int, seed: UInt64?)
+            case threshold(Double, seed: UInt64?)
+        }
+        let mode: Mode
+        /// Always the most likely token.
+        public static let greedy = SamplingMode(mode: .greedy)
+        /// Among the `top` most likely tokens.
+        public static func random(top k: Int, seed: UInt64? = nil) -> SamplingMode { SamplingMode(mode: .top(k, seed: seed)) }
+        /// Among the most likely tokens whose probabilities add up to `probabilityThreshold`.
+        public static func random(probabilityThreshold: Double, seed: UInt64? = nil) -> SamplingMode {
+            SamplingMode(mode: .threshold(probabilityThreshold, seed: seed))
+        }
+    }
+
+    public var sampling: SamplingMode?
+    public var temperature: Double?
+    public var maximumResponseTokens: Int?
+
+    public init(sampling: SamplingMode? = nil, temperature: Double? = nil, maximumResponseTokens: Int? = nil) {
+        self.sampling = sampling
+        self.temperature = temperature
+        self.maximumResponseTokens = maximumResponseTokens
+    }
+}
+
+// MARK: - Generated content
+
+/// Identifies one generation of a value.
+public struct GenerationID: Sendable, Hashable {
+    let uuid = UUID()
+    public init() {}
+}
+
+/// Structured output: null, a boolean, a number, a string, an array or a
+/// structure of named properties (in order). It reads and writes JSON.
+public struct GeneratedContent: Sendable, Equatable, CustomDebugStringConvertible {
+    public enum Kind: Sendable, Equatable {
+        case null
+        case bool(Bool)
+        case number(Double)
+        case string(String)
+        case array([GeneratedContent])
+        case structure(properties: [String: GeneratedContent], orderedKeys: [String])
+    }
+
+    public var kind: Kind
+    public var id: GenerationID?
+
+    /// Whether the content is complete: always, since nothing is streamed into it here.
+    public var isComplete: Bool { true }
+
+    public init(kind: Kind, id: GenerationID? = nil) {
+        self.kind = kind
+        self.id = id
+    }
+
+    public init(_ value: some ConvertibleToGeneratedContent) {
+        self = value.generatedContent
+    }
+
+    public init(_ value: some ConvertibleToGeneratedContent, id: GenerationID) {
+        self = value.generatedContent
+        self.id = id
+    }
+
+    /// A structure with the properties in their order.
+    public init(properties: KeyValuePairs<String, any ConvertibleToGeneratedContent>, id: GenerationID? = nil) {
+        var values: [String: GeneratedContent] = [:]
+        var keys: [String] = []
+        for (key, value) in properties {
+            if values[key] == nil { keys.append(key) }
+            values[key] = value.generatedContent
+        }
+        self.init(kind: .structure(properties: values, orderedKeys: keys), id: id)
+    }
+
+    /// An array of the elements.
+    public init<S: Sequence>(elements: S, id: GenerationID? = nil) where S.Element == any ConvertibleToGeneratedContent {
+        self.init(kind: .array(elements.map(\.generatedContent)), id: id)
+    }
+
+    /// Parses JSON (object keys keep their order).
+    public init(json: String) throws {
+        var parser = _JSONParser(text: Array(json.unicodeScalars))
+        guard let content = parser.parseDocument() else {
+            throw LanguageModelSession.GenerationError.decodingFailure(.init(debugDescription: "The text is not valid JSON."))
+        }
+        self = content
+    }
+
+    /// The content as JSON.
+    public var jsonString: String {
+        var out = ""
+        write(into: &out)
+        return out
+    }
+
+    public var debugDescription: String { jsonString }
+
+    /// The content as `type`.
+    public func value<Value: ConvertibleFromGeneratedContent>(_ type: Value.Type = Value.self) throws -> Value {
+        try Value(self)
+    }
+
+    /// The structure's property `property` as `type`; a missing property fails.
+    public func value<Value: ConvertibleFromGeneratedContent>(_ type: Value.Type = Value.self, forProperty property: String) throws -> Value {
+        guard case .structure(let properties, _) = kind, let content = properties[property] else {
+            throw LanguageModelSession.GenerationError.decodingFailure(.init(debugDescription: "No property '\(property)' in \(jsonString)."))
+        }
+        return try Value(content)
+    }
+
+    /// The structure's property `property` as `type`; nil when missing or null.
+    public func value<Value: ConvertibleFromGeneratedContent>(_ type: Value?.Type = Value?.self, forProperty property: String) throws -> Value? {
+        guard case .structure(let properties, _) = kind else {
+            throw LanguageModelSession.GenerationError.decodingFailure(.init(debugDescription: "\(jsonString) is not a structure."))
+        }
+        guard let content = properties[property], content.kind != .null else { return nil }
+        return try Value(content)
+    }
+
+    /// The error for content that is not of the expected kind.
+    public static func _mismatch(_ content: GeneratedContent, _ type: Any.Type) -> LanguageModelSession.GenerationError {
+        .decodingFailure(.init(debugDescription: "\(content.jsonString) is not a \(type)."))
+    }
+
+    private func write(into out: inout String) {
+        switch kind {
+        case .null: out += "null"
+        case .bool(let value): out += value ? "true" : "false"
+        case .number(let value):
+            if value.isFinite, value == value.rounded(), abs(value) < 1e15 { out += String(Int64(value)) }
+            else if value.isFinite { out += "\(value)" }
+            else { out += "null" }
+        case .string(let value): Self.writeString(value, into: &out)
+        case .array(let items):
+            out += "["
+            for (index, item) in items.enumerated() {
+                if index > 0 { out += ", " }
+                item.write(into: &out)
+            }
+            out += "]"
+        case .structure(let properties, let keys):
+            out += "{"
+            for (index, key) in keys.enumerated() {
+                if index > 0 { out += ", " }
+                Self.writeString(key, into: &out)
+                out += ": "
+                (properties[key] ?? GeneratedContent(kind: .null)).write(into: &out)
+            }
+            out += "}"
+        }
+    }
+
+    private static func writeString(_ value: String, into out: inout String) {
+        out += "\""
+        for scalar in value.unicodeScalars {
+            switch scalar {
+            case "\"": out += "\\\""
+            case "\\": out += "\\\\"
+            case "\n": out += "\\n"
+            case "\r": out += "\\r"
+            case "\t": out += "\\t"
+            default:
+                if scalar.value < 0x20 {
+                    let hex = String(scalar.value, radix: 16)
+                    out += "\\u" + String(repeating: "0", count: 4 - hex.count) + hex
+                } else {
+                    out.unicodeScalars.append(scalar)
+                }
+            }
+        }
+        out += "\""
+    }
+}
+
+/// A small JSON reader that keeps the order of object keys.
+struct _JSONParser {
+    let text: [Unicode.Scalar]
+    var index = 0
+
+    mutating func parseDocument() -> GeneratedContent? {
+        guard let value = parseValue() else { return nil }
+        skipSpace()
+        return index == text.count ? value : nil
+    }
+
+    mutating func skipSpace() {
+        while index < text.count, [" ", "\n", "\r", "\t"].contains(text[index]) { index += 1 }
+    }
+
+    mutating func parseValue() -> GeneratedContent? {
+        skipSpace()
+        guard index < text.count else { return nil }
+        switch text[index] {
+        case "{":
+            index += 1
+            var properties: [String: GeneratedContent] = [:]
+            var keys: [String] = []
+            skipSpace()
+            if index < text.count, text[index] == "}" { index += 1; return GeneratedContent(kind: .structure(properties: [:], orderedKeys: [])) }
+            while true {
+                skipSpace()
+                guard let key = parseString() else { return nil }
+                skipSpace()
+                guard index < text.count, text[index] == ":" else { return nil }
+                index += 1
+                guard let value = parseValue() else { return nil }
+                if properties[key] == nil { keys.append(key) }
+                properties[key] = value
+                skipSpace()
+                guard index < text.count else { return nil }
+                if text[index] == "," { index += 1; continue }
+                if text[index] == "}" { index += 1; break }
+                return nil
+            }
+            return GeneratedContent(kind: .structure(properties: properties, orderedKeys: keys))
+        case "[":
+            index += 1
+            var items: [GeneratedContent] = []
+            skipSpace()
+            if index < text.count, text[index] == "]" { index += 1; return GeneratedContent(kind: .array([])) }
+            while true {
+                guard let value = parseValue() else { return nil }
+                items.append(value)
+                skipSpace()
+                guard index < text.count else { return nil }
+                if text[index] == "," { index += 1; continue }
+                if text[index] == "]" { index += 1; break }
+                return nil
+            }
+            return GeneratedContent(kind: .array(items))
+        case "\"":
+            return parseString().map { GeneratedContent(kind: .string($0)) }
+        case "t": return literal("true", .bool(true))
+        case "f": return literal("false", .bool(false))
+        case "n": return literal("null", .null)
+        default:
+            let start = index
+            while index < text.count, "+-0123456789.eE".unicodeScalars.contains(text[index]) { index += 1 }
+            var number = ""
+            number.unicodeScalars.append(contentsOf: text[start..<index])
+            return Double(number).map { GeneratedContent(kind: .number($0)) }
+        }
+    }
+
+    mutating func literal(_ word: String, _ kind: GeneratedContent.Kind) -> GeneratedContent? {
+        let scalars = Array(word.unicodeScalars)
+        guard index + scalars.count <= text.count, Array(text[index..<index + scalars.count]) == scalars else { return nil }
+        index += scalars.count
+        return GeneratedContent(kind: kind)
+    }
+
+    mutating func parseString() -> String? {
+        guard index < text.count, text[index] == "\"" else { return nil }
+        index += 1
+        var out = String.UnicodeScalarView()
+        var pendingHigh: UInt32?
+        while index < text.count {
+            let scalar = text[index]
+            index += 1
+            if scalar == "\"" { return String(out) }
+            guard scalar == "\\" else { out.append(scalar); continue }
+            guard index < text.count else { return nil }
+            let escape = text[index]
+            index += 1
+            switch escape {
+            case "n": out.append("\n")
+            case "r": out.append("\r")
+            case "t": out.append("\t")
+            case "b": out.append("\u{8}")
+            case "f": out.append("\u{c}")
+            case "u":
+                guard index + 4 <= text.count else { return nil }
+                var hex = ""
+                hex.unicodeScalars.append(contentsOf: text[index..<index + 4])
+                index += 4
+                guard let code = UInt32(hex, radix: 16) else { return nil }
+                if (0xD800..<0xDC00).contains(code) { pendingHigh = code; continue }
+                if (0xDC00..<0xE000).contains(code), let high = pendingHigh {
+                    pendingHigh = nil
+                    if let combined = Unicode.Scalar(0x10000 + ((high - 0xD800) << 10) + (code - 0xDC00)) { out.append(combined) }
+                    continue
+                }
+                if let decoded = Unicode.Scalar(code) { out.append(decoded) }
+            default: out.append(escape)
+            }
+        }
+        return nil
+    }
+}
+
+// MARK: - Generable
+
+/// A type that can be made from generated content.
+public protocol ConvertibleFromGeneratedContent {
+    init(_ content: GeneratedContent) throws
+}
+
+/// A type that can be written as generated content.
+public protocol ConvertibleToGeneratedContent: InstructionsRepresentable, PromptRepresentable {
+    var generatedContent: GeneratedContent { get }
+}
+
+extension ConvertibleToGeneratedContent {
+    public var instructionsRepresentation: Instructions { Instructions(text: generatedContent.jsonString) }
+    public var promptRepresentation: Prompt { Prompt(text: generatedContent.jsonString) }
+}
+
+/// A type a model can generate: it has a schema the output must follow.
+/// `@Generable` makes a struct or an enum one.
+public protocol Generable: ConvertibleFromGeneratedContent, ConvertibleToGeneratedContent {
+    /// The type a response stream delivers while the value is incomplete
+    /// (the type itself here: nothing is streamed).
+    associatedtype PartiallyGenerated: ConvertibleFromGeneratedContent = Self
+    static var generationSchema: GenerationSchema { get }
+}
+
+extension Generable {
+    /// The value as its partially generated type.
+    public func asPartiallyGenerated() -> PartiallyGenerated {
+        (try? PartiallyGenerated(generatedContent))!
+    }
+}
+
+/// Makes a struct or an enum `Generable` (see Sources/SwiftDataMacros/GenerableMacro.swift).
+@attached(extension, conformances: Generable, names: named(init(_:)), named(generatedContent), named(generationSchema))
+public macro Generable(description: String? = nil) = #externalMacro(module: "SwiftDataMacros", type: "GenerableMacro")
+
+/// Describes and constrains a property of a `@Generable` type.
+@attached(peer)
+public macro Guide(description: String? = nil, _ guides: GenerationGuide<Any>...) = #externalMacro(module: "SwiftDataMacros", type: "GuideMacro")
+
+/// Constrains a string property of a `@Generable` type to a pattern.
+@attached(peer)
+public macro Guide<RegexOutput>(description: String? = nil, _ guide: Regex<RegexOutput>) = #externalMacro(module: "SwiftDataMacros", type: "GuideMacro")
+
+extension String: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .string) }
+    public init(_ content: GeneratedContent) throws {
+        guard case .string(let value) = content.kind else { throw GeneratedContent._mismatch(content, String.self) }
+        self = value
+    }
+    public var generatedContent: GeneratedContent { GeneratedContent(kind: .string(self)) }
+}
+
+extension Bool: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .boolean) }
+    public init(_ content: GeneratedContent) throws {
+        guard case .bool(let value) = content.kind else { throw GeneratedContent._mismatch(content, Bool.self) }
+        self = value
+    }
+    public var generatedContent: GeneratedContent { GeneratedContent(kind: .bool(self)) }
+}
+
+extension Int: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .integer) }
+    public init(_ content: GeneratedContent) throws {
+        guard case .number(let value) = content.kind, let int = Int(exactly: value) else { throw GeneratedContent._mismatch(content, Int.self) }
+        self = int
+    }
+    public var generatedContent: GeneratedContent { GeneratedContent(kind: .number(Double(self))) }
+}
+
+extension Double: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .number) }
+    public init(_ content: GeneratedContent) throws {
+        guard case .number(let value) = content.kind else { throw GeneratedContent._mismatch(content, Double.self) }
+        self = value
+    }
+    public var generatedContent: GeneratedContent { GeneratedContent(kind: .number(self)) }
+}
+
+extension Float: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .number) }
+    public init(_ content: GeneratedContent) throws {
+        guard case .number(let value) = content.kind else { throw GeneratedContent._mismatch(content, Float.self) }
+        self = Float(value)
+    }
+    public var generatedContent: GeneratedContent { GeneratedContent(kind: .number(Double(self))) }
+}
+
+extension Decimal: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .number) }
+    public init(_ content: GeneratedContent) throws {
+        guard case .number(let value) = content.kind else { throw GeneratedContent._mismatch(content, Decimal.self) }
+        self = Decimal(value)
+    }
+    public var generatedContent: GeneratedContent {
+        GeneratedContent(kind: .number(NSDecimalNumber(decimal: self).doubleValue))
+    }
+}
+
+extension Array: ConvertibleToGeneratedContent where Element: ConvertibleToGeneratedContent {
+    public var generatedContent: GeneratedContent { GeneratedContent(kind: .array(map(\.generatedContent))) }
+}
+
+extension Array: ConvertibleFromGeneratedContent where Element: ConvertibleFromGeneratedContent {
+    public init(_ content: GeneratedContent) throws {
+        guard case .array(let items) = content.kind else { throw GeneratedContent._mismatch(content, Array.self) }
+        self = try items.map { try Element($0) }
+    }
+}
+
+extension Array: Generable where Element: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .array(Element.generationSchema.node, [])) }
+}
+
+extension Optional: ConvertibleToGeneratedContent, InstructionsRepresentable, PromptRepresentable where Wrapped: ConvertibleToGeneratedContent {
+    public var generatedContent: GeneratedContent { self?.generatedContent ?? GeneratedContent(kind: .null) }
+}
+
+extension GeneratedContent: Generable {
+    public static var generationSchema: GenerationSchema { GenerationSchema(node: .any) }
+    public init(_ content: GeneratedContent) throws { self = content }
+    public var generatedContent: GeneratedContent { self }
+}
+
+// MARK: - Schemas and guides
+
+/// A constraint on a generated value: a count of elements, a range, choices.
+/// Its type is not checked against the property's here.
+public struct GenerationGuide<Value>: @unchecked Sendable {
+    typealias Constraint = _GuideConstraint
+    let constraints: [Constraint]
+
+    /// One of these strings.
+    public static func anyOf(_ values: [String]) -> GenerationGuide<Value> { .init(constraints: [.anyOf(values)]) }
+    /// Exactly this string.
+    public static func constant(_ value: String) -> GenerationGuide<Value> { .init(constraints: [.constant(value)]) }
+    /// Exactly `count` elements.
+    public static func count(_ count: Int) -> GenerationGuide<Value> { .init(constraints: [.count(count)]) }
+    /// Between the bounds' numbers of elements.
+    public static func count(_ range: ClosedRange<Int>) -> GenerationGuide<Value> {
+        .init(constraints: [.minimumCount(range.lowerBound), .maximumCount(range.upperBound)])
+    }
+    /// At least `count` elements.
+    public static func minimumCount(_ count: Int) -> GenerationGuide<Value> { .init(constraints: [.minimumCount(count)]) }
+    /// At most `count` elements.
+    public static func maximumCount(_ count: Int) -> GenerationGuide<Value> { .init(constraints: [.maximumCount(count)]) }
+    /// A number within the range.
+    public static func range(_ range: ClosedRange<Int>) -> GenerationGuide<Value> {
+        .init(constraints: [.minimum(Double(range.lowerBound)), .maximum(Double(range.upperBound))])
+    }
+    public static func range(_ range: ClosedRange<Double>) -> GenerationGuide<Value> {
+        .init(constraints: [.minimum(range.lowerBound), .maximum(range.upperBound)])
+    }
+    /// A number at least `value`.
+    public static func minimum(_ value: Int) -> GenerationGuide<Value> { .init(constraints: [.minimum(Double(value))]) }
+    public static func minimum(_ value: Double) -> GenerationGuide<Value> { .init(constraints: [.minimum(value)]) }
+    /// A number at most `value`.
+    public static func maximum(_ value: Int) -> GenerationGuide<Value> { .init(constraints: [.maximum(Double(value))]) }
+    public static func maximum(_ value: Double) -> GenerationGuide<Value> { .init(constraints: [.maximum(value)]) }
+    /// Applies `guide` to each element.
+    public static func element(_ guide: GenerationGuide<Value>) -> GenerationGuide<Value> {
+        .init(constraints: [.element(guide.constraints)])
+    }
+}
+
+/// One constraint of a guide, whatever its value type.
+enum _GuideConstraint: Sendable, Equatable {
+    case anyOf([String]), constant(String), pattern(String)
+    case count(Int), minimumCount(Int), maximumCount(Int)
+    case minimum(Double), maximum(Double)
+    case element([_GuideConstraint])
+}
+
+/// The shape a generated value must have: a JSON schema (`debugDescription`).
+public struct GenerationSchema: Sendable, CustomDebugStringConvertible {
+    indirect enum Node: Sendable {
+        case any, string, integer, number, boolean
+        case choices([String])
+        case array(Node, [_GuideConstraint])
+        case object(name: String, description: String?, properties: [Property])
+        case guided(Node, description: String?, [_GuideConstraint])
+    }
+
+    /// A property of a structure's schema.
+    public struct Property: Sendable {
+        let name: String
+        let description: String?
+        let node: Node
+        let isOptional: Bool
+        let constraints: [_GuideConstraint]
+
+        public init<Value: Generable>(name: String, description: String? = nil, type: Value.Type,
+                                      guides: [GenerationGuide<Value>] = []) {
+            self.name = name
+            self.description = description
+            node = Value.generationSchema.node
+            isOptional = false
+            constraints = guides.flatMap(\.constraints)
+        }
+
+        public init<Value: Generable>(name: String, description: String? = nil, type: Value?.Type,
+                                      guides: [GenerationGuide<Value>] = []) {
+            self.name = name
+            self.description = description
+            node = Value.generationSchema.node
+            isOptional = true
+            constraints = guides.flatMap(\.constraints)
+        }
+
+        /// `@Generable`'s form: the guides as `@Guide` wrote them.
+        public init<Value: Generable>(name: String, description: String? = nil, type: Value.Type,
+                                      _guides: [GenerationGuide<Any>]) {
+            self.name = name
+            self.description = description
+            node = Value.generationSchema.node
+            isOptional = false
+            constraints = _guides.flatMap(\.constraints)
+        }
+
+        public init<Value: Generable>(name: String, description: String? = nil, type: Value?.Type,
+                                      _guides: [GenerationGuide<Any>]) {
+            self.name = name
+            self.description = description
+            node = Value.generationSchema.node
+            isOptional = true
+            constraints = _guides.flatMap(\.constraints)
+        }
+    }
+
+    let node: Node
+
+    init(node: Node) { self.node = node }
+
+    /// A structure with these properties.
+    public init(type: any Generable.Type, description: String? = nil, properties: [Property]) {
+        node = .object(name: String(describing: type), description: description, properties: properties)
+    }
+
+    /// One of these strings (an enum's cases).
+    public init(type: any Generable.Type, description: String? = nil, anyOf choices: [String]) {
+        node = .guided(.choices(choices), description: description, [])
+    }
+
+    /// One of these types' values.
+    public init(type: any Generable.Type, description: String? = nil, anyOf types: [any Generable.Type]) {
+        node = .guided(.any, description: description, [])
+    }
+
+    public var debugDescription: String { Self.json(node).jsonString }
+
+    static func json(_ node: Node) -> GeneratedContent {
+        func object(_ pairs: [(String, GeneratedContent)]) -> GeneratedContent {
+            var properties: [String: GeneratedContent] = [:]
+            for (key, value) in pairs { properties[key] = value }
+            return GeneratedContent(kind: .structure(properties: properties, orderedKeys: pairs.map(\.0)))
+        }
+        func string(_ text: String) -> GeneratedContent { GeneratedContent(kind: .string(text)) }
+        func constrain(_ pairs: inout [(String, GeneratedContent)], _ constraints: [_GuideConstraint]) {
+            for constraint in constraints {
+                switch constraint {
+                case .anyOf(let values): pairs.append(("enum", GeneratedContent(kind: .array(values.map(string)))))
+                case .constant(let value): pairs.append(("const", string(value)))
+                case .pattern(let value): pairs.append(("pattern", string(value)))
+                case .count(let n):
+                    pairs.append(("minItems", GeneratedContent(kind: .number(Double(n)))))
+                    pairs.append(("maxItems", GeneratedContent(kind: .number(Double(n)))))
+                case .minimumCount(let n): pairs.append(("minItems", GeneratedContent(kind: .number(Double(n)))))
+                case .maximumCount(let n): pairs.append(("maxItems", GeneratedContent(kind: .number(Double(n)))))
+                case .minimum(let n): pairs.append(("minimum", GeneratedContent(kind: .number(n))))
+                case .maximum(let n): pairs.append(("maximum", GeneratedContent(kind: .number(n))))
+                case .element: break
+                }
+            }
+        }
+        switch node {
+        case .any: return object([])
+        case .string: return object([("type", string("string"))])
+        case .integer: return object([("type", string("integer"))])
+        case .number: return object([("type", string("number"))])
+        case .boolean: return object([("type", string("boolean"))])
+        case .choices(let values):
+            return object([("type", string("string")), ("enum", GeneratedContent(kind: .array(values.map(string))))])
+        case .array(let items, let constraints):
+            var pairs: [(String, GeneratedContent)] = [("type", string("array")), ("items", json(items))]
+            constrain(&pairs, constraints)
+            return object(pairs)
+        case .guided(let inner, let description, let constraints):
+            guard case .structure(let properties, let keys) = json(inner).kind else { return json(inner) }
+            var pairs = keys.map { ($0, properties[$0]!) }
+            if let description { pairs.append(("description", string(description))) }
+            constrain(&pairs, constraints)
+            return object(pairs)
+        case .object(let name, let description, let properties):
+            var pairs: [(String, GeneratedContent)] = [("type", string("object")), ("title", string(name))]
+            if let description { pairs.append(("description", string(description))) }
+            let fields = properties.map { property -> (String, GeneratedContent) in
+                var node = property.node
+                let elementConstraints = property.constraints.compactMap { constraint -> [_GuideConstraint]? in
+                    if case .element(let inner) = constraint { return inner }
+                    return nil
+                }.flatMap { $0 }
+                let own = property.constraints.filter { if case .element = $0 { return false } else { return true } }
+                if case .array(let items, let existing) = node {
+                    node = .array(elementConstraints.isEmpty ? items : .guided(items, description: nil, elementConstraints), existing + own)
+                    return (property.name, json(property.description.map { .guided(node, description: $0, []) } ?? node))
+                }
+                return (property.name, json(.guided(node, description: property.description, own)))
+            }
+            pairs.append(("properties", object(fields)))
+            pairs.append(("required", GeneratedContent(kind: .array(properties.filter { !$0.isOptional }.map { string($0.name) }))))
+            return object(pairs)
+        }
+    }
+}
+
+// MARK: - Tools
+
+/// A function the model may call while responding (never, here: there is no model).
+public protocol Tool<Arguments, Output>: Sendable {
+    associatedtype Arguments: ConvertibleFromGeneratedContent
+    associatedtype Output: PromptRepresentable
+    var name: String { get }
+    var description: String { get }
+    var parameters: GenerationSchema { get }
+    var includesSchemaInInstructions: Bool { get }
+    func call(arguments: Arguments) async throws -> Output
+}
+
+extension Tool {
+    public var name: String { String(describing: Self.self) }
+    public var includesSchemaInInstructions: Bool { true }
+}
+
+extension Tool where Arguments: Generable {
+    public var parameters: GenerationSchema { Arguments.generationSchema }
+}
+
+// MARK: - Transcripts
+
+/// A session's history: its instructions, prompts and responses.
+public struct Transcript: Sendable, Equatable, RandomAccessCollection {
+    public struct TextSegment: Sendable, Equatable, Identifiable {
+        public var id: String
+        public var content: String
+        public init(id: String = UUID().uuidString, content: String) {
+            self.id = id
+            self.content = content
+        }
+    }
+
+    public enum Segment: Sendable, Equatable, Identifiable {
+        case text(TextSegment)
+        public var id: String {
+            switch self { case .text(let segment): segment.id }
+        }
+    }
+
+    public struct Instructions: Sendable, Equatable, Identifiable {
+        public var id: String
+        public var segments: [Segment]
+        public init(id: String = UUID().uuidString, segments: [Segment]) {
+            self.id = id
+            self.segments = segments
+        }
+    }
+
+    public struct Prompt: Sendable, Equatable, Identifiable {
+        public var id: String
+        public var segments: [Segment]
+        public init(id: String = UUID().uuidString, segments: [Segment]) {
+            self.id = id
+            self.segments = segments
+        }
+    }
+
+    public struct Response: Sendable, Equatable, Identifiable {
+        public var id: String
+        public var segments: [Segment]
+        public init(id: String = UUID().uuidString, segments: [Segment]) {
+            self.id = id
+            self.segments = segments
+        }
+    }
+
+    public enum Entry: Sendable, Equatable, Identifiable {
+        case instructions(Instructions)
+        case prompt(Prompt)
+        case response(Response)
+
+        public var id: String {
+            switch self {
+            case .instructions(let entry): entry.id
+            case .prompt(let entry): entry.id
+            case .response(let entry): entry.id
+            }
+        }
+    }
+
+    var entries: [Entry]
+
+    public init() {
+        entries = []
+    }
+
+    public init(entries: some Sequence<Entry>) {
+        self.entries = Array(entries)
+    }
+
+    public var startIndex: Int { entries.startIndex }
+    public var endIndex: Int { entries.endIndex }
+    public subscript(position: Int) -> Entry { entries[position] }
+}
+
+// MARK: - Sessions
+
+/// A conversation with the model. Every request fails with
+/// `GenerationError.assetsUnavailable` in the browser (see the file comment).
+public final class LanguageModelSession: @unchecked Sendable {
+    /// Why a request failed.
+    public enum GenerationError: Error, LocalizedError, Sendable {
+        public struct Context: Sendable {
+            public let debugDescription: String
+            public init(debugDescription: String) { self.debugDescription = debugDescription }
+        }
+
+        /// A refusal and its explanation.
+        public struct Refusal: Sendable {
+            public init(transcriptEntries: [Transcript.Entry] = []) {}
+        }
+
+        case exceededContextWindowSize(Context)
+        /// The model is not on the device: the browser's answer to every request.
+        case assetsUnavailable(Context)
+        case guardrailViolation(Context)
+        case unsupportedGuide(Context)
+        case unsupportedLanguageOrLocale(Context)
+        case decodingFailure(Context)
+        case rateLimited(Context)
+        case concurrentRequests(Context)
+        case refusal(Refusal, Context)
+
+        public var errorDescription: String? {
+            switch self {
+            case .exceededContextWindowSize(let context), .assetsUnavailable(let context), .guardrailViolation(let context),
+                 .unsupportedGuide(let context), .unsupportedLanguageOrLocale(let context), .decodingFailure(let context),
+                 .rateLimited(let context), .concurrentRequests(let context), .refusal(_, let context):
+                context.debugDescription
+            }
+        }
+    }
+
+    /// An error a tool threw while the model called it.
+    public struct ToolCallError: Error, LocalizedError {
+        public var tool: any Tool
+        public var underlyingError: any Error
+        public init(tool: any Tool, underlyingError: any Error) {
+            self.tool = tool
+            self.underlyingError = underlyingError
+        }
+    }
+
+    /// A complete response.
+    public struct Response<Content> {
+        public let content: Content
+        public let rawContent: GeneratedContent
+        public let transcriptEntries: ArraySlice<Transcript.Entry>
+    }
+
+    /// The snapshots of a response as it is generated. Iterating it fails
+    /// with the request's error (here, always `assetsUnavailable`).
+    public struct ResponseStream<Content: Generable>: AsyncSequence, Sendable {
+        public struct Snapshot {
+            public var content: Content.PartiallyGenerated
+            public var rawContent: GeneratedContent
+
+            public init(content: Content.PartiallyGenerated, rawContent: GeneratedContent) {
+                self.content = content
+                self.rawContent = rawContent
+            }
+        }
+        public typealias Element = Snapshot
+
+        let failure: GenerationError
+
+        public struct AsyncIterator: AsyncIteratorProtocol {
+            let failure: GenerationError
+            var finished = false
+
+            public mutating func next() async throws -> Snapshot? {
+                guard !finished else { return nil }
+                finished = true
+                throw failure
+            }
+        }
+
+        public func makeAsyncIterator() -> AsyncIterator { AsyncIterator(failure: failure) }
+
+        /// The whole response, once generated.
+        public func collect() async throws -> Response<Content> { throw failure }
+    }
+
+    let model: SystemLanguageModel
+    public let tools: [any Tool]
+    /// Whether a request is in progress (never: requests fail at once).
+    public private(set) var isResponding = false
+    /// The instructions; nothing is added, since nothing is generated.
+    public private(set) var transcript: Transcript
+
+    public init(model: SystemLanguageModel = .default, tools: [any Tool] = [], instructions: Instructions? = nil) {
+        self.model = model
+        self.tools = tools
+        var entries: [Transcript.Entry] = []
+        if let instructions {
+            entries.append(.instructions(Transcript.Instructions(segments: [.text(Transcript.TextSegment(content: instructions.text))])))
+        }
+        transcript = Transcript(entries: entries)
+    }
+
+    public convenience init(model: SystemLanguageModel = .default, tools: [any Tool] = [], instructions: String) {
+        self.init(model: model, tools: tools, instructions: Instructions(text: instructions))
+    }
+
+    public convenience init(model: SystemLanguageModel = .default, tools: [any Tool] = [],
+                            @InstructionsBuilder instructions: () throws -> Instructions) rethrows {
+        self.init(model: model, tools: tools, instructions: try instructions())
+    }
+
+    public init(model: SystemLanguageModel = .default, tools: [any Tool] = [], transcript: Transcript) {
+        self.model = model
+        self.tools = tools
+        self.transcript = transcript
+    }
+
+    /// Loads the model ahead of a request: nothing to load.
+    public func prewarm(promptPrefix: Prompt? = nil) {}
+
+    private var failure: GenerationError {
+        .assetsUnavailable(.init(debugDescription: "The on-device language model is not available in the browser."))
+    }
+
+    // Text responses.
+
+    public func respond(to prompt: String, options: GenerationOptions = GenerationOptions()) async throws -> Response<String> {
+        throw failure
+    }
+
+    public func respond(to prompt: Prompt, options: GenerationOptions = GenerationOptions()) async throws -> Response<String> {
+        throw failure
+    }
+
+    public func respond(options: GenerationOptions = GenerationOptions(),
+                        @PromptBuilder prompt: () throws -> Prompt) async throws -> Response<String> {
+        _ = try prompt()
+        throw failure
+    }
+
+    // Generable responses.
+
+    public func respond<Content: Generable>(to prompt: String, generating type: Content.Type = Content.self,
+                                            includeSchemaInPrompt: Bool = true,
+                                            options: GenerationOptions = GenerationOptions()) async throws -> Response<Content> {
+        throw failure
+    }
+
+    public func respond<Content: Generable>(to prompt: Prompt, generating type: Content.Type = Content.self,
+                                            includeSchemaInPrompt: Bool = true,
+                                            options: GenerationOptions = GenerationOptions()) async throws -> Response<Content> {
+        throw failure
+    }
+
+    public func respond<Content: Generable>(generating type: Content.Type = Content.self, includeSchemaInPrompt: Bool = true,
+                                            options: GenerationOptions = GenerationOptions(),
+                                            @PromptBuilder prompt: () throws -> Prompt) async throws -> Response<Content> {
+        _ = try prompt()
+        throw failure
+    }
+
+    public func respond(to prompt: String, schema: GenerationSchema, includeSchemaInPrompt: Bool = true,
+                        options: GenerationOptions = GenerationOptions()) async throws -> Response<GeneratedContent> {
+        throw failure
+    }
+
+    // Streams.
+
+    public func streamResponse(to prompt: String, options: GenerationOptions = GenerationOptions()) -> ResponseStream<String> {
+        ResponseStream(failure: failure)
+    }
+
+    public func streamResponse(to prompt: Prompt, options: GenerationOptions = GenerationOptions()) -> ResponseStream<String> {
+        ResponseStream(failure: failure)
+    }
+
+    public func streamResponse(options: GenerationOptions = GenerationOptions(),
+                               @PromptBuilder prompt: () throws -> Prompt) rethrows -> ResponseStream<String> {
+        _ = try prompt()
+        return ResponseStream(failure: failure)
+    }
+
+    public func streamResponse<Content: Generable>(to prompt: String, generating type: Content.Type = Content.self,
+                                                   includeSchemaInPrompt: Bool = true,
+                                                   options: GenerationOptions = GenerationOptions()) -> ResponseStream<Content> {
+        ResponseStream(failure: failure)
+    }
+
+    public func streamResponse<Content: Generable>(to prompt: Prompt, generating type: Content.Type = Content.self,
+                                                   includeSchemaInPrompt: Bool = true,
+                                                   options: GenerationOptions = GenerationOptions()) -> ResponseStream<Content> {
+        ResponseStream(failure: failure)
+    }
+
+    public func streamResponse(to prompt: String, schema: GenerationSchema, includeSchemaInPrompt: Bool = true,
+                               options: GenerationOptions = GenerationOptions()) -> ResponseStream<GeneratedContent> {
+        ResponseStream(failure: failure)
+    }
+}