Repository Public
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