Recipe catalog / instrument-report-facets

Label the facets of an instrument repair message

Which of these does message state about an instrument problem: the instrument and model, the symptom, when it started, recent changes, and the environment it is kept in?

You take in repair or support messages from players and want to know which standard intake details are already supplied so you can pre-fill a ticket or ask only for what is missing.

Explore this recipe interactively · Source and implementation guide

Use instrument-report-facets 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 { instrumentReportFacets } from 'jev-recipes/instrument-report-facets';

const result = await instrumentReportFacets({
  "message": "Hi, I have a Martin D-18 (2019) and the B string has started buzzing on the 2nd and 3rd frets. Open it is fine. This began about ten days ago, right after I changed to a set of light-gauge phosphor bronze strings and lowered the saddle a little myself. I have not changed anything else. Can someone take a look?",
  "minConfidence": 0.8
});
console.log(result);

Input contract

Field	Type	Needed
message	string	Required
minConfidence	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "message": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "message"
    ]
  },
  "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"
        ]
      },
      "detected": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": [
            "statesInstrument",
            "statesSymptom",
            "statesOnset",
            "statesRecentChanges",
            "statesEnvironment"
          ]
        }
      },
      "labels": {
        "type": "object",
        "properties": {
          "statesInstrument": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready",
                  "review"
                ]
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "present",
                  "absent"
                ]
              },
              "probability": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "status",
              "verdict",
              "probability",
              "confidence"
            ],
            "additionalProperties": false
          },
          "statesSymptom": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready",
                  "review"
                ]
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "present",
                  "absent"
                ]
              },
              "probability": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "status",
              "verdict",
              "probability",
              "confidence"
            ],
            "additionalProperties": false
          },
          "statesOnset": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready",
                  "review"
                ]
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "present",
                  "absent"
                ]
              },
              "probability": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "status",
              "verdict",
              "probability",
              "confidence"
            ],
            "additionalProperties": false
          },
          "statesRecentChanges": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready",
                  "review"
                ]
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "present",
                  "absent"
                ]
              },
              "probability": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "status",
              "verdict",
              "probability",
              "confidence"
            ],
            "additionalProperties": false
          },
          "statesEnvironment": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ready",
                  "review"
                ]
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "present",
                  "absent"
                ]
              },
              "probability": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              },
              "confidence": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            },
            "required": [
              "status",
              "verdict",
              "probability",
              "confidence"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "statesInstrument",
          "statesSymptom",
          "statesOnset",
          "statesRecentChanges",
          "statesEnvironment"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "detected",
      "labels"
    ],
    "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-report-facets.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "detected": [
    "statesInstrument",
    "statesSymptom",
    "statesOnset",
    "statesRecentChanges"
  ],
  "labels": {
    "statesInstrument": {
      "status": "ready",
      "verdict": "present",
      "probability": 0.97,
      "confidence": 0.97
    },
    "statesSymptom": {
      "status": "ready",
      "verdict": "present",
      "probability": 0.96,
      "confidence": 0.96
    },
    "statesOnset": {
      "status": "ready",
      "verdict": "present",
      "probability": 0.93,
      "confidence": 0.93
    },
    "statesRecentChanges": {
      "status": "ready",
      "verdict": "present",
      "probability": 0.95,
      "confidence": 0.95
    },
    "statesEnvironment": {
      "status": "ready",
      "verdict": "absent",
      "probability": 0.05,
      "confidence": 0.95
    }
  }
}

Evaluation evidence

Fixture only

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

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

Limitations

Labels are independent, so a message can state several facets or none.
Detects that a detail is stated, not that it is accurate. A model name can be wrong and a stated onset can be misremembered.
Does not diagnose the problem or judge its severity. Parse dates, humidity figures, and model identifiers in application code.

Related recipes

symptom-facets: Use symptom-facets for the analogous intake check on a patient's description of a medical symptom.
bug-report-completeness: Use bug-report-completeness for software bug reports, where the expected parts are reproduction steps, expected and actual behavior, and environment.