Recipe catalog / instrument-issue-kind

Classify an instrument problem report

What kind of problem does report describe with a musical instrument: tuning, buzz or rattle, no sound, intonation, mechanical, cosmetic, or unclear?

You take in repair requests or support messages from players and need to route each one to the right technician, help article, or intake form based on the kind of problem described.

Explore this recipe interactively · Source and implementation guide

Use instrument-issue-kind 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 { instrumentIssueKind } from 'jev-recipes/instrument-issue-kind';

const result = await instrumentIssueKind({
  "report": "My Telecaster has developed a metallic buzz on the low E and A strings whenever I fret anything between the 5th and 9th frets. Open strings are fine and it still tunes up normally. It only started after I swapped to a heavier string set last week.",
  "minConfidence": 0.8
});
console.log(result);

Input contract

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "report": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "report"
    ]
  },
  "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"
        ]
      },
      "verdict": {
        "type": "string",
        "enum": [
          "tuning",
          "buzz_or_rattle",
          "no_sound",
          "intonation",
          "mechanical",
          "cosmetic",
          "unclear"
        ]
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string",
          "enum": [
            "tuning",
            "buzz_or_rattle",
            "no_sound",
            "intonation",
            "mechanical",
            "cosmetic",
            "unclear"
          ]
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "required": [
          "tuning",
          "buzz_or_rattle",
          "no_sound",
          "intonation",
          "mechanical",
          "cosmetic",
          "unclear"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "verdict",
      "confidence",
      "probabilities"
    ],
    "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 instrument-issue-kind.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "verdict": "buzz_or_rattle",
  "confidence": 0.9,
  "probabilities": {
    "tuning": 0.02,
    "buzz_or_rattle": 0.9,
    "no_sound": 0.01,
    "intonation": 0.02,
    "mechanical": 0.03,
    "cosmetic": 0,
    "unclear": 0.02
  }
}

Evaluation evidence

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

Limitations

• Classifies the symptom as the player describes it, not the underlying cause. A buzz can come from frets, a nut, or loose hardware, and a tuning problem can come from strings, pegs, or a cracked neck; diagnosis is a separate step.
• A report that describes several problems is classified by the one it presses most. Split multi-problem reports in code when each needs its own ticket.
• Does not judge urgency, cost, or whether the instrument is under warranty.

Related recipes

• failure-kind: Use failure-kind when the categories are your own list rather than this fixed set of instrument problem types.
• issue-impact: Use issue-impact to grade how badly the problem affects the player, rather than what kind of problem it is.