Recipe catalog / modulation-moment

Check whether now is a moment to change key

Is now a musically suitable moment to modulate away from key, judged on the phrase position, cadence, and stability described in recentMaterial?

A generation loop wants to introduce a key change and needs to know whether the current point is a natural seam, such as the end of a phrase or a settled cadence, or whether a change now would cut a line off mid-thought.

Explore this recipe interactively · Source and implementation guide

Use modulation-moment in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { modulationMoment } from 'jev-recipes/modulation-moment';

const result = await modulationMoment({
  "recentMaterial": "Bar 3 of a four-bar phrase. The melody is climbing F4 G4 A4 toward the phrase peak on an upbeat, the harmony has just moved from ii to V, and there has been no cadence or rest since the phrase began.",
  "key": "C major",
  "minConfidence": 0.8
});
console.log(result);

Input contract

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "recentMaterial": {
        "type": "string"
      },
      "key": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "recentMaterial",
      "key"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "probability": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "verdict": {
        "type": "string",
        "enum": [
          "suitable",
          "unsuitable"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "probability",
      "confidence",
      "verdict"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo modulation-moment.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "probability": 0.06,
  "confidence": 0.94,
  "verdict": "unsuitable"
}

Evaluation evidence

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

• Judges suitability from the phrase position, cadence, and stability described in the text. It does not identify the current key, find pivot chords, or plan the new key; those belong in application code or a later step.
• A suitable moment is a seam, not an obligation; staying in key can be the better choice.
• Styles differ in how abruptly they modulate, so a moment unsuitable for a chorale can suit a film cue.

Related recipes

• topic-shift: Use topic-shift to detect whether a conversation message moves to a new topic, not whether a passage is ready to move to a new key.
• step-complete: Use step-complete when supplied evidence must establish a stated completion condition, rather than judging a musical seam from the passage itself.