Recipe catalog / listener-request-kind

Classify a listener's request

What does a listener's message ask of the performance?

Chat messages steer a live or generated musical performance and you need to know which control each message reaches for before deciding what to change.

Explore this recipe interactively · Source and implementation guide

Use listener-request-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 { listenerRequestKind } from 'jev-recipes/listener-request-kind';

const result = await listenerRequestKind({
  "message": "can you slow it down a bit? feels kinda frantic rn",
  "context": "Live piano stream. The current passage is a fast run of sixteenth notes in C minor at roughly 150 bpm.",
  "minConfidence": 0.8
});
console.log(result);

Input contract

Field	Type	Needed
message	string	Required
context	string	Optional
minConfidence	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "message": {
        "type": "string"
      },
      "context": {
        "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"
        ]
      },
      "verdict": {
        "type": "string",
        "enum": [
          "mood",
          "tempo",
          "style",
          "specific_piece",
          "dynamics",
          "stop",
          "unclear"
        ]
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string",
          "enum": [
            "mood",
            "tempo",
            "style",
            "specific_piece",
            "dynamics",
            "stop",
            "unclear"
          ]
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "required": [
          "mood",
          "tempo",
          "style",
          "specific_piece",
          "dynamics",
          "stop",
          "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 listener-request-kind.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "verdict": "tempo",
  "confidence": 0.9,
  "probabilities": {
    "mood": 0.03,
    "tempo": 0.9,
    "style": 0.02,
    "specific_piece": 0.01,
    "dynamics": 0.02,
    "stop": 0.01,
    "unclear": 0.01
  }
}

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

Classifies what the message asks for, not whether the performer should comply or whether the request is feasible.
A message that asks for several things is classified by the request it presses most; split multi-part messages in code when each matters.
Chatter, reactions, and questions that ask nothing of the performance land on unclear rather than being guessed into a control.

Related recipes

turn-intent: Use turn-intent for the general communicative purpose of a message rather than which aspect of a performance it asks to change.
route: Use route when the destinations are caller-defined handlers rather than this fixed set of performance controls.