Guide: Classify with Response

The /v1/classify-respond endpoint combines classification with conversational output. It classifies user input and generates a natural language response acknowledging the classification.

When to Use

Use /v1/classify-respond when you need:

1. Classification results (to route or understand intent)
2. Natural language response (for chat-like interactions)

This is ideal for conversational interfaces where you want to acknowledge what the user said before taking action.

How It Works

The /v1/classify-respond endpoint:

1. Classifies the input (like /v1/classify)
2. Performs extraction if enabled (for multi-intent queries)
3. Generates a natural language response based on the classifications
4. Returns both the classifications and the response text

Example Request

{
  "data": "Turn on the kitchen lights and set bedroom temperature to 72",
  "classification_set": "area-router-v1"
}

Context

You can provide optional context (max 1,000 characters) to help the LLM make better classification decisions:

{
  "data": "It's running hot",
  "classification_set": "support-v1",
  "context": "Customer is reporting an issue with their laptop"
}

Example Response (with extraction)

{
  "response": "I'll turn on the kitchen lights and set bedroom temperature to 72 for you.",
  "classifications": [
    {
      "label": "kitchen",
      "confidence": 0.95
    },
    {
      "label": "bedroom",
      "confidence": 0.93
    }
  ],
  "metadata": {
    "requests_used": 4,
    "requests_remaining": 9996,
    "source": "compute",
    "extraction_performed": true,
    "sub_classifications_performed": 2
  }
}

Example Response (single intent)

{
  "response": "I understand you want to turn on the kitchen lights.",
  "classifications": [
    {
      "label": "kitchen",
      "confidence": 0.96
    }
  ],
  "metadata": {
    "requests_used": 2,
    "requests_remaining": 9998,
    "source": "compute"
  }
}

Personas

You can customize the response style using personas. Define personas in your App config:

{
  "personas": [
    {
      "name": "home-assistant",
      "description": "A friendly smart home assistant"
    },
    {
      "name": "concise-bot",
      "description": "Brief, direct responses"
    }
  ]
}

The first persona in your config is automatically used for classify/respond responses.

Cost

The /v1/classify-respond endpoint costs:

• 2 requests for single-intent classification
• 4 requests for multi-intent classification with extraction (when enabled)

This is double the cost of regular /v1/classify due to the additional response generation.

Extraction Support

When your classification set has enable_extraction: true, the /v1/classify-respond endpoint automatically:

1. Detects multi-intent queries
2. Extracts and classifies each sub-intent
3. Generates a response that acknowledges all intents

Example multi-intent query:

"Turn on kitchen lights and turn off bedroom lights"

Response:

"I'll turn on kitchen lights and turn off bedroom lights for you."

Caching

Like /v1/classify, the /v1/classify-respond endpoint benefits from semantic caching. Similar queries return cached results instantly, including the generated response.