SPB Git

Repository Public

ScriptAssistant.swift 16.0 KB 258 lines swift

1// ORIX DJ2// File: Packages/ORIXDJCore/Sources/ORIXDJEngine/Anthropic/ScriptAssistant.swift3// Description: The Claude Studio pipeline: builds the request (language description + user-approved context), extracts4//              the proposed script from the answer, then compiles, budget-checks and simulates it locally. Nothing a5//              model writes reaches the engine without passing the same validation as a hand-written script.6//7// Author: Simon-Pierre Boucher8// Contact: contact@spboucher.ai9import Foundation10import ORIXDSP11import ORIXMIDI12import ORIXScript1314public enum AssistantTask: String, Sendable, CaseIterable, Identifiable, Codable {15    case generate, explain, fix, improve, effect, midi, plan16    public var id: String { rawValue }1718    public var title: String {19        switch self {20        case .generate: "Write an automation"21        case .explain: "Explain a script"22        case .fix: "Fix a script"23        case .improve: "Improve a script"24        case .effect: "Design an effect"25        case .midi: "Create a MIDI mapping"26        case .plan: "Plan a performance"27        }28    }29}3031/// What may be shared with Anthropic for one request. Each part is opt-in and shown to the user before sending.32public struct AssistantContext: Sendable, Equatable {33    public struct Deck: Sendable, Equatable {34        public var letter: String35        public var loaded: Bool36        public var playing: Bool37        public var bpm: Double38        public var key: String39        public var title: String40    }4142    public var includeDecks = true43    /// Track titles are private library data: off unless the user turns it on.44    public var includeTitles = false45    public var includeEffects = true46    public var includeScript = true47    public var includeDiagnostics = true48    public var decks: [Deck] = []49    public var masterBPM = 0.050    public var activeEffects: [String] = []51    public var script: String?52    public var diagnostics: [Diagnostic] = []53    public var simulationSummary: String?54    public var controllerDescription: String?5556    public init() {}5758    /// Captures the current state of the engine.59    public static func capture(_ engine: DJEngine) -> AssistantContext {60        var c = AssistantContext()61        for d in 0 ..< deckCount {62            let s = engine.deckStatus(d)63            c.decks.append(Deck(letter: deckLetters[d], loaded: s.track != nil, playing: s.playing, bpm: s.bpm, key: s.track?.key?.camelot ?? "", title: s.track?.title ?? ""))64        }65        c.masterBPM = engine.clock.bpm66        for rack in [nil] + (0 ..< deckCount).map(Optional.some) {67            for slot in engine.rackStatus(rack) where slot.enabled { c.activeEffects.append((rack.map { "deck.\(deckLetters[$0])." } ?? "") + "fx." + slot.kind.rawValue) }68        }69        return c70    }7172    /// The exact text added to the request. The interface shows this as the preview of what is shared.73    public func rendered() -> String {74        var lines: [String] = ["ORIX Script version: \(ORIXScriptLanguage.version)", "Decks available: A, B, C, D"]75        if includeDecks {76            lines.append("Master clock: \(masterBPM > 0 ? String(format: "%.1f BPM", masterBPM) : "unknown")")77            for d in decks {78                var s = "Deck \(d.letter): " + (d.loaded ? (d.playing ? "playing" : "loaded, paused") : "empty")79                if d.loaded {80                    s += d.bpm > 0 ? String(format: ", %.1f BPM", d.bpm) : ", tempo unknown"81                    if !d.key.isEmpty { s += ", key \(d.key)" }82                    if includeTitles, !d.title.isEmpty { s += ", \"\(d.title)\"" }83                }84                lines.append(s)85            }86        }87        if includeEffects { lines.append("Effects switched on: " + (activeEffects.isEmpty ? "none" : activeEffects.joined(separator: ", "))) }88        if let controllerDescription, !controllerDescription.isEmpty { lines.append("MIDI controller: \(controllerDescription)") }89        if includeScript, let script, !script.isEmpty { lines.append("Current script:\n```orixdj\n\(script)\n```") }90        if includeDiagnostics, !diagnostics.isEmpty { lines.append("Compiler messages:\n" + diagnostics.map { "line \($0.location.line), column \($0.location.column): \($0.message) [\($0.code)]" }.joined(separator: "\n")) }91        if includeDiagnostics, let simulationSummary, !simulationSummary.isEmpty { lines.append("Simulator output:\n\(simulationSummary)") }92        return lines.joined(separator: "\n")93    }94}9596public struct DiffLine: Sendable, Equatable, Identifiable {97    public enum Kind: Sendable { case same, added, removed }98    public var id: Int99    public var kind: Kind100    public var text: String101}102103/// A proposal from Claude after local validation.104public struct AssistantProposal: Sendable {105    public var answer: String106    /// The answer without the code block, for display next to the script.107    public var explanation: String108    public var script: String?109    public var compile: CompileResult?110    public var simulation: SimulationResult?111    public var requirements: AutomationRequirements?112    public var risks: [String] = []113    public var midiProfile: MIDIMappingProfile?114    public var midiIssues: [String] = []115116    public var isValid: Bool { compile?.succeeded == true && simulation?.error == nil }117}118119public enum ScriptAssistant {120    /// Stable system prompt: role, the generated language description, and the output contract.121    public static let systemPrompt: String = """122    You help DJs write automations for ORIX DJ, a professional DJ application for macOS. Automations are written in ORIX Script, a small language made for this application. Your scripts are compiled, type-checked and run in a simulator by the application before the user decides whether to use them, so correctness against the reference below matters more than anything else: a path or statement that is not in the reference is a compile error the user will see.123124    \(ReferenceGenerator.languageBrief)125126    EXAMPLE127    ```orixdj128    automation "Eight Bar Transition" quantize bar {129        deck.B.sync(true)130        deck.B.volume = -12dB131        deck.B.play()132        over 8 bars {133            deck.A.filter.highpass -> 12kHz134            deck.A.volume -> -60dB135            deck.B.volume -> 0dB136        }137        deck.A.pause()138        deck.A.filter.highpass = 20Hz139        deck.A.volume = 0dB140    }141    ```142143    HOW TO ANSWER144    When you write or change a script, give the complete script in one ```orixdj code block, then explain in a few short sentences what it does bar by bar, which decks and effects it needs, and anything the DJ should check before running it live (for example that a deck must already be playing, or that it leaves an effect switched on). Restore what you change when the automation is meant to be reusable: reset filters, EQ and faders you moved once the deck they belong to has stopped. When the request cannot be expressed in ORIX Script, say so plainly instead of inventing syntax. When asked only to explain, do not rewrite the script.145    """146147    static func instructions(for task: AssistantTask) -> String {148        switch task {149        case .generate: "Write an ORIX Script automation for this request."150        case .explain: "Explain what the current script does, bar by bar, and point out anything risky in a live set. Do not rewrite it."151        case .fix: "The current script does not work. Use the compiler messages and simulator output to correct it, changing as little as possible, and say what was wrong."152        case .improve: "Improve the current script for this goal, keeping its behaviour otherwise. Remove commands that do nothing and say what changed."153        case .effect: "Design this effect with the effects available in ORIX DJ: choose the units, their parameter values and the automation curves, as an ORIX Script automation that sets it up and performs it."154        case .midi: "Create a MIDI mapping for this controller. Answer with one ```json code block containing an object {\"name\": string, \"controllerNameHint\": string, \"mappings\": [{\"control\": {\"kind\": \"note\" | \"cc\" | \"pitchBend\", \"channel\": 0-15, \"number\": 0-127}, \"target\": string, \"mode\": \"absolute\" | \"relative\" | \"toggle\" | \"trigger\" | \"momentary\"}]}. Use only the targets listed in the context. Use absolute for faders and knobs, trigger for buttons that fire an action, toggle for switches. If you do not know the controller's MIDI numbers, say so and give a sensible generic layout the user can correct with MIDI learn."155        case .plan: "Suggest how to perform this with ORIX DJ: the order of tracks or sections, the transitions and effects to use, and which automations would help. Include an ORIX Script automation when one is useful."156        }157    }158159    public static func request(task: AssistantTask, prompt: String, context: AssistantContext, history: [AnthropicMessage] = []) -> AnthropicRequest {160        var body = instructions(for: task)161        if !prompt.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty { body += "\n\nRequest: \(prompt)" }162        var shared = context.rendered()163        if task == .midi { shared += "\nMappable targets:\n" + ControlTargets.all.map { "\($0.id) (\($0.kind.rawValue))" }.joined(separator: "\n") }164        body += "\n\nContext from the application:\n\(shared)"165        return AnthropicRequest(system: systemPrompt, messages: history + [AnthropicMessage(role: "user", content: body)])166    }167168    /// The first fenced block tagged with one of `languages` (or untagged when `allowUntagged`).169    static func codeBlock(in text: String, languages: [String], allowUntagged: Bool) -> (code: String, range: Range<String.Index>)? {170        var search = text.startIndex171        while let open = text.range(of: "```", range: search ..< text.endIndex) {172            let lineEnd = text[open.upperBound...].firstIndex(of: "\n") ?? text.endIndex173            let tag = text[open.upperBound ..< lineEnd].trimmingCharacters(in: .whitespaces).lowercased()174            guard lineEnd < text.endIndex, let close = text.range(of: "```", range: text.index(after: lineEnd) ..< text.endIndex) else { return nil }175            if languages.contains(tag) || (allowUntagged && tag.isEmpty) {176                return (String(text[text.index(after: lineEnd) ..< close.lowerBound]).trimmingCharacters(in: .newlines) + "\n", open.lowerBound ..< close.upperBound)177            }178            search = close.upperBound179        }180        return nil181    }182183    /// Validates an answer locally: parse, type and capability checks, resource limits, then a simulated run.184    public static func evaluate(answer: String, task: AssistantTask, simulation config: SimulationConfig = .init()) -> AssistantProposal {185        var proposal = AssistantProposal(answer: answer, explanation: answer)186        if task == .midi, let block = codeBlock(in: answer, languages: ["json"], allowUntagged: true) {187            proposal.explanation = answer.replacingCharacters(in: block.range, with: "").trimmingCharacters(in: .whitespacesAndNewlines)188            do {189                var profile = try MIDIMappingProfile(jsonData: Data(block.code.utf8))190                let unknown = profile.mappings.filter { ControlTargets.target($0.target) == nil }191                proposal.midiIssues += unknown.map { "Unknown target '\($0.target)' was removed." }192                profile.mappings.removeAll { ControlTargets.target($0.target) == nil }193                proposal.midiIssues += profile.validate().map { "\($0)" }194                proposal.midiProfile = profile195            } catch { proposal.midiIssues.append("The mapping could not be read: \(error.localizedDescription)") }196            return proposal197        }198        guard let block = codeBlock(in: answer, languages: ["orixdj", "orix", "orixscript"], allowUntagged: true), block.code.contains("automation") else { return proposal }199        proposal.script = block.code200        proposal.explanation = answer.replacingCharacters(in: block.range, with: "").trimmingCharacters(in: .whitespacesAndNewlines)201        let compiled = ScriptCompiler.compile(block.code)202        proposal.compile = compiled203        guard let program = compiled.program, let automation = program.automations.first else { return proposal }204        proposal.requirements = automation.requirements205        proposal.simulation = Simulator.run(program, config: config)206        proposal.risks = risks(source: block.code, automation: automation, simulation: proposal.simulation, warnings: compiled.warnings)207        return proposal208    }209210    static func risks(source: String, automation: CompiledAutomation, simulation: SimulationResult?, warnings: [Diagnostic]) -> [String] {211        var out: [String] = []212        let req = automation.requirements213        if req.usesEvents { out.append("It waits for events, so it keeps running until it stops itself or you stop it.") }214        if let beats = req.lengthBeats, beats > 256 { out.append("It runs for \(Int(beats / 4)) bars.") }215        if req.usesAbsoluteTime { out.append("It uses durations in seconds, which are converted with the tempo at the moment they run.") }216        if let sim = simulation {217            let actions = sim.actions.map(\.text)218            let paused = Set(actions.filter { $0.contains(".pause(") || $0.contains(".stop(") || $0.contains(".brake(") }.compactMap { $0.split(separator: ".").dropFirst().first.map(String.init) })219            if !paused.isEmpty { out.append("It stops deck \(paused.sorted().joined(separator: ", ")).") }220            let loads = actions.filter { $0.contains(".load(") || $0.contains(".loadNext(") || $0.contains(".eject(") }221            if !loads.isEmpty { out.append("It loads or ejects tracks.") }222            // Effects still on at the end of the simulated run.223            var on: Set<String> = []224            for a in sim.actions { let name = a.text.split(separator: "(").first.map(String.init) ?? ""225                if name.hasSuffix(".enable") { on.insert(String(name.dropLast(7))) } else if name.hasSuffix(".disable") { on.remove(String(name.dropLast(8))) } }226            if !on.isEmpty, !sim.timedOut { out.append("It leaves \(on.sorted().joined(separator: ", ")) switched on when it ends.") }227            if sim.timedOut { out.append("The simulation was still running after \(Int(sim.beats)) beats.") }228            if sim.stats.clampedValues > 0 { out.append("\(sim.stats.clampedValues) value(s) were outside their range in the simulation and were clamped.") }229            for w in sim.warnings.prefix(3) { out.append(w.text) }230            if let e = sim.error { out.append("The simulated run failed: \(e.message)") }231        }232        if source.contains("mixer.master.volume") { out.append("It changes the master volume.") }233        for w in warnings.prefix(3) { out.append("Line \(w.location.line): \(w.message)") }234        return out235    }236237    /// Line diff (longest common subsequence) between the script the user has and the proposed one.238    public static func diff(old: String, new: String) -> [DiffLine] {239        let a = old.components(separatedBy: "\n"), b = new.components(separatedBy: "\n")240        guard a.count * b.count < 4_000_000 else { return b.enumerated().map { DiffLine(id: $0.offset, kind: .added, text: $0.element) } }241        var table = [[Int]](repeating: [Int](repeating: 0, count: b.count + 1), count: a.count + 1)242        if !a.isEmpty, !b.isEmpty {243            for i in stride(from: a.count - 1, through: 0, by: -1) {244                for j in stride(from: b.count - 1, through: 0, by: -1) { table[i][j] = a[i] == b[j] ? table[i + 1][j + 1] + 1 : max(table[i + 1][j], table[i][j + 1]) }245            }246        }247        var out: [DiffLine] = []; var i = 0, j = 0248        while i < a.count, j < b.count {249            if a[i] == b[j] { out.append(DiffLine(id: out.count, kind: .same, text: a[i])); i += 1; j += 1 }250            else if table[i + 1][j] >= table[i][j + 1] { out.append(DiffLine(id: out.count, kind: .removed, text: a[i])); i += 1 }251            else { out.append(DiffLine(id: out.count, kind: .added, text: b[j])); j += 1 }252        }253        while i < a.count { out.append(DiffLine(id: out.count, kind: .removed, text: a[i])); i += 1 }254        while j < b.count { out.append(DiffLine(id: out.count, kind: .added, text: b[j])); j += 1 }255        return out256    }257}258
Files main
Menu

Theme