@hraness/dawg 0.2.0 → 0.4.0

package/src/agent/chord-tools.ts

@@ -0,0 +1,357 @@
+/**
+ * Agent tools for chords: `suggest_progression` (read-only) and
+ * `write_chords` (score). Both run core/chords.ts, so the agent gets the
+ * same key-mode harmony, voice leading and performance play mode uses.
+ */
+
+import {
+  BASS_MODES,
+  CHORD_PATTERNS,
+  findChordPattern,
+  type BassMode,
+  generateProgression,
+  keyName,
+  parseKey,
+  PERFORM_MODES,
+  PROGRESSION_PRESETS,
+  PROGRESSION_STYLES,
+  renderProgression,
+  resolveChord,
+  SPREADS,
+  type Chord,
+  type Key,
+  type PerformMode,
+  type Spread,
+} from "../../core/chords.ts";
+import { midiToPitch } from "../../core/pitch.ts";
+import { SCORE_LIMITS, type ScoreOperation } from "../../core/score.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+
+/** Most notes one write_chords call may add (arpeggios multiply fast). */
+export const MAX_CHORD_NOTES = 512;
+const MAX_CHORDS = 32;
+
+class ChordToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+const STYLE_NAMES = [
+  ...PROGRESSION_STYLES,
+  ...PROGRESSION_PRESETS.map((preset) => preset.name),
+];
+
+const str = { type: "string" } as const;
+const int = { type: "integer" } as const;
+const num = { type: "number" } as const;
+const bool = { type: "boolean" } as const;
+const keySchema = {
+  type: "string",
+  description: '"C major", "a dorian"; default song key',
+} as const;
+const chordsSchema = {
+  type: "array",
+  items: str,
+  description: '"ii7", "bVII", "V/V" or "Cm7", "F/A"',
+} as const;
+const voicingSchema = {
+  inversion: { ...int, description: "-12..12" },
+  spread: { type: "string", enum: [...SPREADS] },
+} as const;
+const progressionSchema = {
+  key: keySchema,
+  chords: {
+    ...chordsSchema,
+    description: `${chordsSchema.description}; omit to generate`,
+  },
+  length: int,
+  style: str,
+  seed: int,
+  sevenths: bool,
+  ...voicingSchema,
+} as const;
+
+type Progression = Readonly<{ key: Key; chords: Chord[] }>;
+
+function progressionOf(
+  args: Record<string, unknown>,
+  context: ToolContext,
+): Progression {
+  const keyText =
+    args.key === undefined ? (context.score.key ?? "C major") : args.key;
+  const key = parseKey(typeof keyText === "string" ? keyText : undefined);
+  if (!key)
+    throw new ChordToolError(
+      `key must look like "C major", "a minor" or "F# dorian"`,
+    );
+  if (args.chords !== undefined) {
+    if (
+      !Array.isArray(args.chords) ||
+      args.chords.length === 0 ||
+      args.chords.length > MAX_CHORDS
+    )
+      throw new ChordToolError(`chords must list 1..${MAX_CHORDS} chords`);
+    const chords = args.chords.map((value, index) => {
+      const chord =
+        typeof value === "string" ? resolveChord(key, value) : undefined;
+      if (!chord)
+        throw new ChordToolError(
+          `chords[${index}]: not a roman numeral or chord symbol`,
+        );
+      return chord;
+    });
+    return { key, chords };
+  }
+  const length = integer(args, "length", 1, MAX_CHORDS) ?? 4;
+  const style = args.style;
+  if (
+    style !== undefined &&
+    (typeof style !== "string" || !STYLE_NAMES.includes(style))
+  )
+    throw new ChordToolError(`style must be one of ${STYLE_NAMES.join(", ")}`);
+  const sevenths = optionalBoolean(args, "sevenths");
+  return {
+    key,
+    chords: generateProgression({
+      key,
+      length,
+      ...(style !== undefined ? { style } : {}),
+      seed: integer(args, "seed", 0, 2 ** 31) ?? 1,
+      ...(sevenths !== undefined ? { sevenths } : {}),
+    }),
+  };
+}
+
+function voicingOf(args: Record<string, unknown>): {
+  inversion?: number;
+  spread?: Spread;
+} {
+  const inversion = integer(args, "inversion", -12, 12);
+  const spread = args.spread;
+  if (spread !== undefined && !(SPREADS as readonly unknown[]).includes(spread))
+    throw new ChordToolError(`spread must be one of ${SPREADS.join(", ")}`);
+  return {
+    ...(inversion !== undefined ? { inversion } : {}),
+    ...(spread !== undefined ? { spread: spread as Spread } : {}),
+  };
+}
+
+export const CHORD_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "suggest_progression",
+    description: `Read-only: voice-led diatonic chords (name, numeral, voicing, bass). style ${PROGRESSION_STYLES.join("|")} walks a seeded harmony graph; or a preset ${PROGRESSION_PRESETS.map((p) => p.name).join("|")}. length ≤${MAX_CHORDS}.`,
+    parameters: {
+      type: "object",
+      properties: progressionSchema,
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const { key, chords } = progressionOf(args, context);
+      const rendered = renderProgression({
+        key,
+        chords,
+        ...voicingOf(args),
+        bass: true,
+      });
+      const result = {
+        key: keyName(key),
+        chords: rendered.voiced.map((chord) => ({
+          name: chord.name,
+          roman: chord.roman,
+          voicing: chord.pitches.map((pitch) => midiToPitch(pitch)),
+          ...(chord.bass !== undefined
+            ? { bass: midiToPitch(chord.bass) }
+            : {}),
+        })),
+      };
+      const names = rendered.voiced.map((chord) => chord.name).join(" ");
+      return {
+        kind: "action",
+        summary: `${keyName(key)}: ${names}`.slice(0, 160),
+        run: async () => ({
+          content: JSON.stringify(result),
+          summary: `${keyName(key)}: ${names}`.slice(0, 160),
+        }),
+      };
+    },
+  },
+  {
+    name: "write_chords",
+    description: `Write voice-led chords to a track (one bar each by default), with optional bass here or on bassTrackId. perform pattern uses pattern ${CHORD_PATTERNS.map((p) => p.name).join("|")}. bassMode ${BASS_MODES.join("|")} (solo: bass only). ≤${MAX_CHORD_NOTES} notes.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: str,
+        key: keySchema,
+        chords: chordsSchema,
+        ...voicingSchema,
+        start: num,
+        beatsPerChord: num,
+        perform: { type: "string", enum: [...PERFORM_MODES] },
+        rate: { ...num, description: "arp step, beats" },
+        octaves: int,
+        strum: num,
+        velocity: num,
+        pattern: { type: "string", enum: CHORD_PATTERNS.map((p) => p.name) },
+        bass: bool,
+        bassMode: { type: "string", enum: [...BASS_MODES] },
+        bassTrackId: str,
+      },
+      required: ["chords"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = trackOf(args.trackId, context, "trackId");
+      if (args.chords === undefined)
+        throw new ChordToolError(
+          "write_chords needs chords (try suggest_progression)",
+        );
+      const bassTrackId =
+        args.bassTrackId === undefined
+          ? undefined
+          : trackOf(args.bassTrackId, context, "bassTrackId");
+      const { key, chords } = progressionOf(args, context);
+      const mode = args.perform;
+      if (
+        mode !== undefined &&
+        !(PERFORM_MODES as readonly unknown[]).includes(mode)
+      )
+        throw new ChordToolError(
+          `perform must be one of ${PERFORM_MODES.join(", ")}`,
+        );
+      const velocity = finite(args, "velocity", 0, 1);
+      const rate = finite(args, "rate", 0.0625, 4);
+      const strum = finite(args, "strum", 0, 1);
+      const octaves = integer(args, "octaves", 1, 4);
+      const pattern = args.pattern;
+      if (
+        pattern !== undefined &&
+        (typeof pattern !== "string" || !findChordPattern(pattern))
+      )
+        throw new ChordToolError(
+          `pattern must be one of ${CHORD_PATTERNS.map((p) => p.name).join(", ")}`,
+        );
+      const bassMode = args.bassMode;
+      if (
+        bassMode !== undefined &&
+        !(BASS_MODES as readonly unknown[]).includes(bassMode)
+      )
+        throw new ChordToolError(
+          `bassMode must be one of ${BASS_MODES.join(", ")}`,
+        );
+      const rendered = renderProgression({
+        key,
+        chords,
+        start: finite(args, "start", 0, Infinity) ?? 0,
+        beatsPerChord:
+          finite(args, "beatsPerChord", 1e-3, 64) ?? context.score.beatsPerBar,
+        ...voicingOf(args),
+        bass: args.bass === true || bassTrackId !== undefined,
+        ...(bassMode !== undefined ? { bassMode: bassMode as BassMode } : {}),
+        perform: {
+          mode: (mode as PerformMode | undefined) ?? "block",
+          ...(rate !== undefined ? { rate } : {}),
+          ...(strum !== undefined ? { strum } : {}),
+          ...(octaves !== undefined ? { octaves } : {}),
+          ...(velocity !== undefined ? { velocity } : {}),
+          seed: integer(args, "seed", 0, 2 ** 31) ?? 0,
+          ...(typeof pattern === "string" ? { pattern } : {}),
+        },
+      });
+      const total = rendered.notes.length + rendered.bass.length;
+      if (total > MAX_CHORD_NOTES)
+        throw new ChordToolError(
+          `${total} notes exceed ${MAX_CHORD_NOTES}; use fewer chords, a slower rate or fewer octaves`,
+        );
+      const tpb = context.score.ticksPerBeat;
+      const operations: ScoreOperation[] = [];
+      const add = (
+        notes: readonly {
+          pitch: number;
+          start: number;
+          length: number;
+          velocity: number;
+        }[],
+        target: string,
+      ) => {
+        for (const note of notes)
+          operations.push({
+            type: "addNote",
+            note: {
+              id: context.newNoteId(target, operations.length),
+              trackId: target,
+              startTick: Math.round(note.start * tpb),
+              durationTicks: Math.max(1, Math.round(note.length * tpb)),
+              pitch: note.pitch,
+              velocity: note.velocity,
+            },
+          });
+      };
+      add(rendered.notes, trackId);
+      add(rendered.bass, bassTrackId ?? trackId);
+      const names = rendered.voiced.map((chord) => chord.name).join(" ");
+      return {
+        kind: "score",
+        operations,
+        trackId,
+        summary: `${trackId} chords ${names}`.slice(0, 160),
+      };
+    },
+  },
+]);
+
+function trackOf(value: unknown, context: ToolContext, label: string): string {
+  const trackId = value ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
+    throw new ChordToolError(`${label} must be a short string`);
+  if (!context.score.tracks.some((track) => track.id === trackId))
+    throw new ChordToolError(
+      `unknown track ${trackId}; create it with create_track first`,
+    );
+  return trackId;
+}
+
+function finite(
+  args: Record<string, unknown>,
+  name: string,
+  min: number,
+  max: number,
+): number | undefined {
+  const value = args[name];
+  if (value === undefined) return undefined;
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value < min ||
+    value > max
+  )
+    throw new ChordToolError(
+      `${name} must be a number in ${min}..${max === Infinity ? "∞" : max}`,
+    );
+  return value;
+}
+
+function integer(
+  args: Record<string, unknown>,
+  name: string,
+  min: number,
+  max: number,
+): number | undefined {
+  const value = finite(args, name, min, max);
+  if (value !== undefined && !Number.isInteger(value))
+    throw new ChordToolError(`${name} must be an integer`);
+  return value;
+}
+
+function optionalBoolean(
+  args: Record<string, unknown>,
+  name: string,
+): boolean | undefined {
+  const value = args[name];
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean")
+    throw new ChordToolError(`${name} must be true or false`);
+  return value;
+}

package/src/agent/drum-tools.ts

@@ -0,0 +1,135 @@
+/**
+ * Agent tools for the drum pattern library and the synthesized kits:
+ * `list_drum_patterns`, `apply_drum_pattern`, `set_drum_kit`. Patterns land
+ * as rhythm rows (`set_rhythm` edits them afterwards), so a groove stays a
+ * few parameters per voice instead of dozens of notes.
+ */
+import { diffScores } from "../../core/diff.ts";
+import { SYNTH_KITS } from "../../core/kits.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import {
+  applyDrumPattern,
+  applySynthKit,
+  DRUM_PATTERNS,
+  patternLine,
+} from "../commands/drums.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+import { ToolArgumentError } from "./tools.ts";
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function trackIdOf(args: Record<string, unknown>, context: ToolContext) {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || !ID_PATTERN.test(trackId))
+    throw new ToolArgumentError(
+      "trackId must be 1-64 letters, digits, dot, dash, or underscore",
+    );
+  return trackId;
+}
+
+const trackId = {
+  type: "string",
+  maxLength: SCORE_LIMITS.maxIdLength,
+  description:
+    "Drum track id (created when missing). Defaults to the focused track.",
+} as const;
+
+export const DRUM_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "list_drum_patterns",
+    description:
+      "List the built-in drum patterns (name · tempo range · genre tags · voices). Filter by a word such as house, trap or 2-step.",
+    parameters: {
+      type: "object",
+      properties: { filter: { type: "string", maxLength: 40 } },
+      additionalProperties: false,
+    },
+    plan(args) {
+      const needle =
+        typeof args.filter === "string" ? args.filter.trim().toLowerCase() : "";
+      const lines = DRUM_PATTERNS.filter(
+        (entry) =>
+          !needle ||
+          entry.name.includes(needle) ||
+          entry.tags.some((tag) => tag.includes(needle)),
+      ).map(patternLine);
+      return {
+        kind: "action",
+        summary: needle ? `patterns ${needle}` : "list patterns",
+        run: async () => ({
+          content: JSON.stringify({
+            ok: true,
+            patterns: lines,
+            hint: "apply_drum_pattern puts one on a drum track; set_rhythm then edits its rows",
+          }),
+          summary: `${lines.length} patterns`,
+        }),
+      };
+    },
+  },
+  {
+    name: "apply_drum_pattern",
+    description:
+      "Replace a drum track's notes with a library pattern as Euclidean/grid rhythm rows (one per voice). Moves the tempo into the pattern's range unless tempo is keep.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", maxLength: 40 },
+        trackId,
+        tempo: { type: "string", enum: ["auto", "keep", "set"] },
+      },
+      required: ["name"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      if (typeof args.name !== "string" || !args.name.trim())
+        throw new ToolArgumentError("name must be a pattern name");
+      const id = trackIdOf(args, context);
+      const tempo =
+        args.tempo === "keep" || args.tempo === "set" ? args.tempo : "auto";
+      const result = applyDrumPattern(
+        context.score,
+        id,
+        args.name.trim().toLowerCase(),
+        tempo,
+      );
+      if (!result.ok || !result.next)
+        throw new ToolArgumentError(result.message);
+      return {
+        kind: "score",
+        operations: diffScores(context.score, result.next),
+        trackId: id,
+        summary: result.message,
+      };
+    },
+  },
+  {
+    name: "set_drum_kit",
+    description: `Choose the synthesized drum kit of a drum track: ${SYNTH_KITS.map((kit) => kit.name).join(", ")}, or default. Offline and instant; sample kits (909, 808, linn, …) go through use_sound.`,
+    parameters: {
+      type: "object",
+      properties: {
+        kit: {
+          type: "string",
+          enum: ["default", ...SYNTH_KITS.map((kit) => kit.name)],
+        },
+        trackId,
+      },
+      required: ["kit"],
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      if (typeof args.kit !== "string")
+        throw new ToolArgumentError("kit must be a synth kit name");
+      const id = trackIdOf(args, context);
+      const result = applySynthKit(context.score, id, args.kit);
+      if (!result.ok) throw new ToolArgumentError(result.message);
+      return {
+        kind: "score",
+        operations: result.next ? diffScores(context.score, result.next) : [],
+        trackId: id,
+        summary: result.message,
+      };
+    },
+  },
+]);